quchip.declarative.parameters

Declared-parameter metadata, synthesized __init__ signatures, and validation.

Concrete DeviceModel, CouplingModel, and Envelope subclasses use parameter() to declare fields. This module resolves those declarations into synthesized constructors and enforces their sign constraints at construction and on later writes.

Functions

authored_component_values(component)	Declared numerical and structural values used for copying and cache keys.
build_declared_signature(param_fields[, ...])	Build a synthesized __init__ signature from declared param fields.
component_fingerprint(component, *[, traced])	Track authored buffer edits and ordinary versioned assignments.
constructor_field(*[, default, kw_only, runtime])	Describe a synthesized constructor argument to static type checkers.
copy_authored_fields(source, target)	Give a derived component independent writable authored values.
parameter(*[, default, positive, ...])	Declare a traceable numerical parameter on a model class.
parameter_fields(cls)	Resolve declarative parameter fields for cls through the MRO.
resolve_declared_params(cls, params, *[, fields])	Resolve declared parameters into a {name: value} dict.
resolve_declared_settings(cls, values)	Pop declared structural settings from values and apply defaults.
serializable_value(value)	Prefer a concrete scalar for serialization, but keep tracers.
setting(*[, default, serialize, kw_only])	Declare serialized structural configuration on a model class.
setting_fields(cls)	Resolve structural setting fields for cls through the MRO.
validate_declared_fields(cls)	Validate cross-cutting constraints on a class's declared fields.
validate_sign(name, spec, value)	Enforce declared sign constraints on concrete scalars.

Classes

DeclarativeMeta(name, bases, namespace, **kwargs)	Expose synthesized declarative constructors without runtime fields.
KeywordOnlyDeclarativeMeta(name, bases, ...)	Expose keyword-only synthesized constructors for control declarations.
Parameter([default, positive, nonnegative, ...])	Metadata for a declared parameter's validation and serialization.
Setting([default, serialize, kw_only])	Metadata for a serialized, non-traceable structural model choice.

class quchip.declarative.parameters.Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)

Bases: object

Metadata for a declared parameter’s validation and serialization.

Sign constraints apply to concrete scalars. Traced values pass unchecked.

Parameters:

• default (Any, default UNBOUND) – Constructor default. UNBOUND makes the field required.

• positive (bool, default False) – Reject concrete values outside the selected sign constraint.

• nonnegative (bool, default False) – Reject concrete values outside the selected sign constraint.

• serialize (bool, default True) – Include the field in serialized model data.

• unit (str or None) – Display metadata for units and mathematical notation.

• symbol (str or None) – Display metadata for units and mathematical notation.

• noise (bool) – Mark noise fields, force keyword-only construction, or require a value.

• kw_only (bool) – Mark noise fields, force keyword-only construction, or require a value.

• required (bool) – Mark noise fields, force keyword-only construction, or require a value.

default: Any = unbound

positive: bool = False

nonnegative: bool = False

serialize: bool = True

unit: str | None = None

symbol: str | None = None

noise: bool = False

kw_only: bool = False

required: bool = False

class quchip.declarative.parameters.Setting(default=unbound, serialize=True, kw_only=True)

Bases: object

Metadata for a serialized, non-traceable structural model choice.

Parameters:

• default (Any, default UNBOUND) – Structural default. UNBOUND makes the setting required.

• serialize (bool, default True) – Include the setting in serialized model data.

• kw_only (bool, default True) – Must stay true because settings are structural choices.

default: Any = unbound

serialize: bool = True

kw_only: bool = True

property required: bool

quchip.declarative.parameters.constructor_field(*, default=unbound, kw_only=False, runtime=unbound)

Describe a synthesized constructor argument to static type checkers.

quchip.declarative.parameters.parameter(*, default=<object object>, positive=False, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False)

Declare a traceable numerical parameter on a model class.

unit is display metadata for human-readable surfaces such as Chip.describe(). The package-wide units contract (GHz, ns, mK) still governs the value itself. None means dimensionless or unknown. Returns a Parameter field descriptor that parameter_fields() collects at class-definition time.

Parameters:

• default (Any, optional) – Declared default value. If omitted, the constructor argument is required. Use default=UNBOUND to defer its value until numerical materialization.

• positive (bool, optional) – Reject concrete values <= 0. Traced values pass unchecked.

• nonnegative (bool, optional) – Reject concrete values < 0. Traced values pass unchecked.

• serialize (bool, optional) – Include the field in to_dict() output.

• unit (str or None, optional) – Display-only unit label (for example "GHz").

• symbol (str or None, optional) – Mathematical symbol for displaying authored physics. If omitted, the display uses the field name.

• noise (bool, optional) – If set, Chip.set_noise() can configure this field while its current value is unset.

• kw_only (bool, optional) – Place the declared field after the * in synthesized constructors.

Examples

>>> from quchip.declarative import DeviceModel, parameter, Scalar
>>> class Oscillator(DeviceModel):
...     freq: Scalar = parameter(positive=True, unit="GHz")
...     def local_hamiltonian(self, op, p):
...         return p.freq * op.n
>>> Oscillator(freq=5.0, levels=3).freq
5.0

quchip.declarative.parameters.setting(*, default=unbound, serialize=True, kw_only=True)

Declare serialized structural configuration on a model class.

Parameters:

• default (Any, default UNBOUND) – Structural default. If omitted, the setting is required.

• serialize (bool, default True) – Include the setting in serialized data.

• kw_only (bool, default True) – Must stay true for structural settings.

class quchip.declarative.parameters.DeclarativeMeta(name, bases, namespace, **kwargs)

Bases: ABCMeta

Expose synthesized declarative constructors without runtime fields.

class quchip.declarative.parameters.KeywordOnlyDeclarativeMeta(name, bases, namespace, **kwargs)

Bases: DeclarativeMeta

Expose keyword-only synthesized constructors for control declarations.

quchip.declarative.parameters.serializable_value(value)

Prefer a concrete scalar for serialization, but keep tracers.

quchip.declarative.parameters.validate_sign(name, spec, value)

Enforce declared sign constraints on concrete scalars.

Tracers and None (unset) pass unchecked.

quchip.declarative.parameters.build_declared_signature(param_fields, trailing=())

Build a synthesized __init__ signature from declared param fields.

Declared parameters become optional positional-or-keyword arguments in declaration order. trailing appends structural keyword-only parameters such as levels and label.

quchip.declarative.parameters.resolve_declared_params(cls, params, *, fields=None)

Resolve declared parameters into a {name: value} dict.

Walks parameter_fields(cls). For each declared field, it pops the matching kwarg from params (or uses its default), runs the concrete-only positivity check, and collects the result. Returns a dict of validated parameter values, one entry for each declared field. Raises TypeError if a required field is missing or if params still contains unrecognized keys after the loop.

quchip.declarative.parameters.resolve_declared_settings(cls, values)

Pop declared structural settings from values and apply defaults.

quchip.declarative.parameters.parameter_fields(cls)

Resolve declarative parameter fields for cls through the MRO.

A field is included if and only if some class in the MRO annotates the name and the resolved class attribute (getattr(cls, name)) is a Parameter instance. A subclass that shadows an inherited Parameter with a concrete value (for example freq: Scalar = 5.0) silently drops the field. By design, this lets subclasses remove a parent’s parameter when they want a concrete override.

quchip.declarative.parameters.setting_fields(cls)

Resolve structural setting fields for cls through the MRO.

quchip.declarative.parameters.authored_component_values(component)

Declared numerical and structural values used for copying and cache keys.

quchip.declarative.parameters.copy_authored_fields(source, target)

Give a derived component independent writable authored values.

quchip.declarative.parameters.component_fingerprint(component, *, traced=False)

Track authored buffer edits and ordinary versioned assignments.

traced=True keys traced values by identity. See scoped_entry().

quchip.declarative.parameters.validate_declared_fields(cls)

Validate cross-cutting constraints on a class’s declared fields.