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 unquoted <value><unit> scalars (e.g. 150μm) for lossless round-tripping.

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

extract_parameter_set(g::SchematicGraph) -> ParameterSet

Create a detached ParameterSet containing the supported final parameters of the components in g.

Each component is stored below components at its unique node ID. Dots in node IDs become nested namespace segments, and composite-component graphs are recursively nested below their parent component. Parameter values are taken from the constructed component instances, so defaults and applied overrides are both included. Scalar values are retained, as are one-dimensional AbstractArrays of supported values; ranges and views are materialized as plain Vectors. Named tuples and dictionaries form parameter namespaces. Other values are omitted, including component-valued parameters and Points, which are StaticVectors standing for single geometric values rather than arrays.

If g carries a source ParameterSet, its top-level namespaces other than components are deep-copied into the result. The source components namespace is replaced with the graph-derived component tree. The result has an empty source path and access log and shares no mutable parameter data with the graph or source set.

Extraction realizes lazy composite graphs. An ArgumentError is thrown if a component path collides with a parameter leaf.

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".