ParameterSet API Reference

ParameterSet

Mutable parameter source, typically loaded from a YAML file.

The internal dict uses a namespace convention: String keys are namespace segments (navigate deeper into the hierarchy), non-Dict values are leaf parameters.

Supports dot access for both reading and writing:

ps.components.qubit.cap_width        # read
ps.components.qubit.cap_width = 350  # write

Every ParameterSet contains two required top-level namespaces:

• global - parameters shared across the design
• components - per-component parameter trees

Fields

• path::String: source file path (empty string if constructed from a Dict)
• data::Dict{String, Any}: nested parameter dictionary
• accessed::Set{String}: tracks which parameter paths were consumed (for auditing)
• prefix::String: dot-separated namespace prefix for scoped views (empty at root)

Construction

• ParameterSet() / ParameterSet(data::Dict{String,Any}): empty or from a nested Dict.
• ParameterSet(path::String) / ParameterSet(io::IO): load from a YAML file or stream. String values that parse as Unitful.Quantity (e.g. "150μm") are converted in place. Requires YAML.jl to be loaded (using YAML).

MissingNamespace

Returned when accessing a non-existent key on a ParameterSet.

Supports chained dot-writes (auto-vivifying intermediate namespaces) but shows a ParameterKeyError when used as a value. Check with x isa MissingNamespace.

ParameterKeyError <: Exception

Thrown when reading a non-existent key from a ParameterSet.

resolve(ps::ParameterSet, address::String)

Navigate a dot-separated address within the ParameterSet.

Returns the value at the address - either a scoped ParameterSet (if the value is a Dict) or a leaf value.

Examples

ps = ParameterSet(
    Dict{String, Any}(
        "global" => Dict{String, Any}(),
        "components" =>
            Dict{String, Any}("qubit" => Dict{String, Any}("cap_width" => 300))
    )
)
resolve(ps, "components.qubit.cap_width")  # => 300
resolve(ps, "components.qubit")            # => ParameterSet scoped to qubit

leaf_params(ps::ParameterSet)
leaf_params(d::Dict)

Extract non-Dict entries as a NamedTuple (the "leaf" parameters at this level). Dict entries (namespace segments) are excluded.

Examples

ps = ParameterSet(
    Dict{String, Any}(
        "global" => Dict{String, Any}(),
        "components" => Dict{String, Any}("cap_width" => 300, "cap_gap" => 20)
    )
)
leaf_params(ps.components)  # => (cap_width = 300, cap_gap = 20)

save_parameter_set(path::String, ps::ParameterSet)
save_parameter_set(io::IO, ps::ParameterSet)

Save a ParameterSet to a YAML file at path or write YAML to an IO stream.

Unitful.Quantity values are serialized as "<value><unit>" (e.g. "150μm") for lossless round-tripping.

Requires YAML.jl to be loaded (using YAML).

create_component(::Type{T}, ps::ParameterSet, address::String) where {T <: AbstractComponent}

Create an instance of type T using parameters from a ParameterSet at the given address.

The address is resolved to a scoped ParameterSet, and the call is delegated to create_component(T, sub::ParameterSet). That overload splats the leaves at sub as keyword arguments into the keyword-only create_component(T; kwargs...), which merges them recursively with default_parameters(T). Nested namespaces below address are not merged - scope at the level whose leaves match T's parameters.

Consumed leaves (those matching parameter_names(T)) are recorded in ps.accessed as qualified paths rooted at the original PS.

create_component(::Type{T}, sub::ParameterSet) where {T <: AbstractComponent}

Create an instance of type T from a scoped ParameterSet, typically obtained by chained-dot access like ps.components.transmon.junction.

Leaf parameters (non-Dict values) at sub are extracted via leaf_params and passed as keyword arguments. Consumed leaves are recorded in the shared accessed set as qualified paths (e.g. "components.transmon.junction.w_jj"), matching the behavior of the address-string form.

sub must be a scoped view (non-empty prefix); passing a root ParameterSet raises an ArgumentError because bare leaf names at the root have no meaningful qualified path and the use case is ambiguous - use the address-string form.

Example

junction = create_component(ExampleSimpleJunction, ps.components.transmon.junction)

set_parameters(c::AbstractComponent, ps::ParameterSet, address::String; kwargs...)

Apply ParameterSet leaves at address on top of the template instance c, optionally followed by composite-level keyword overrides.

Starting from c's parameters as the base, each leaf under resolve(ps, address) overrides the corresponding field. Nested namespaces below address are ignored — scope at the level whose leaves match c's parameters. Any kwargs are then applied on top of the ParameterSet overlay, so precedence is: template defaults < ParameterSet overlay < kwargs.

Throws ParameterKeyError if address doesn't resolve to anything (no such namespace), or if a kwarg value is a MissingNamespace (failed PS lookup). Throws ArgumentError if address resolves to a leaf scalar rather than a namespace, if any leaf under address is not a parameter of typeof(c) (surfaces typos at aliasing time rather than as a MethodError inside the constructor), or if a kwarg value is itself a ParameterSet (a subtree is never a valid component-field value and almost always indicates a missing leaf access).

Every PS leaf under address is recorded in ps.accessed as a fully qualified path — including leaves whose value happens to equal the template's default and leaves that are subsequently shadowed by a trailing kwarg. The audit semantics is "the loader read this PS leaf during build", not "this value reached the final component". A trailing kwarg that overrides a PS leaf does not unmark it.

This is the "templates-aliasing" entry point: a composite declares subcomponent defaults in a templates field, then _build_subcomponents overlays ParameterSet values on top of each template via this overload, optionally with trailing composite-level kwargs to enforce composite invariants.

function _build_subcomponents(tr::MyTransmon)
    ps = parameter_set(tr._graph)
    island = set_parameters(
        tr.templates.island,
        ps,
        "components.$(name(tr)).island";
        junction_gap=tr.junction_gap
    )
    return (island,)
end

set_parameters(c::AbstractComponent, sub::ParameterSet)

Apply leaves from a scoped ParameterSet on top of c.

sub must be a scoped view (non-empty prefix, typically reached via chained-dot access like ps.components.transmon.island). For a root ParameterSet use the address-string form instead.

Throws ArgumentError if any leaf in sub is not a parameter of typeof(c), surfacing typos in the ParameterSet source early.

Every leaf in sub is pushed into ps.accessed with its qualified path, even when the leaf's value happens to equal the field's existing value on c. The recorded fact is "the loader read this PS leaf", not "the value differed from the template default".