quchip.declarative.parameters

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

parameter() is the field-declaration surface concrete DeviceModel, CouplingModel, and EnvelopeShape subclasses use; this module resolves those declarations into synthesized constructors and runs their sign constraints, both at construction and on post-construction writes.

Functions

build_declared_signature(param_fields[, ...])	Build a synthesized __init__ signature from declared param fields.
parameter(*[, default, positive, ...])	Declare a traceable scalar or modulation parameter on a model class.
parameter_fields(cls)	Resolve declarative parameter fields for cls, walking the MRO.
resolve_declared_params(cls, params)	Resolve declared parameters into a {name: value} dict.
serializable_value(value)	Prefer a concrete scalar for serialization while preserving tracers.
validate_sign(name, spec, value)	Enforce a field's declared sign constraint on concrete scalars only.

Classes

Parameter([default, positive, nonnegative, ...])

Metadata for a declarative model parameter field.

class quchip.declarative.parameters.Parameter(default=<object object>, positive=False, nonnegative=False, serialize=True, unit=None)

Bases: object

Metadata for a declarative model parameter field.

The metadata is intentionally lightweight: it records validation and serialization intent while leaving the runtime value fully traceable. Sign constraints (positive / nonnegative) are enforced only on concrete scalars, so traced values flow through unchecked.

Parameters:

• default (Any)

• positive (bool)

• nonnegative (bool)

• serialize (bool)

• unit (str | None)

default: Any = <object object>

positive: bool = False

nonnegative: bool = False

serialize: bool = True

unit: str | None = None

property has_default: bool

Return whether this field has a declared default value.

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

Declare a traceable scalar or modulation 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. When omitted the field is required in the synthesized __init__.

• 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 (e.g. "GHz").

Return type:

Any

Examples

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

quchip.declarative.parameters.serializable_value(value)

Prefer a concrete scalar for serialization while preserving tracers.

Parameters:

value (Any)

Return type:

Any

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

Enforce a field’s declared sign constraint on concrete scalars only.

Shared by construction (resolve_declared_params()) and post-construction writes (DeviceModel._validate_param_write) so the two paths cannot drift. Traced values flow through unchecked; None means “unset” and always passes.

Parameters:

• name (str)

• spec (Parameter)

• value (Any)

Return type:

None

quchip.declarative.parameters.build_declared_signature(param_fields, trailing=(), *, owner=None)

Build a synthesized __init__ signature from declared param fields.

Declared parameters become positional-or-keyword arguments in declaration order, carrying their declared defaults. trailing appends extra (typically keyword-only) structural parameters — e.g. levels, label and the noise kwargs for a DeviceModel. owner names the class whose declarations are being synthesized, for the ordering error raised by _check_declaration_order().

Parameters:

• param_fields (dict[str, Parameter])

• trailing (tuple[Parameter, ...])

• owner (type | None)

Return type:

Signature

quchip.declarative.parameters.resolve_declared_params(cls, params)

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

Walks parameter_fields(cls): for each declared field, 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 per declared field. Raises TypeError if a required field is missing or if params still contains unrecognized keys after the loop.

Parameters:

• cls (type)

• params (dict[str, Any])

Return type:

dict[str, Any]

quchip.declarative.parameters.parameter_fields(cls)

Resolve declarative parameter fields for cls, walking the MRO.

A field is included iff 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 (e.g. freq: Scalar = 5.0) silently drops the field — by design, so subclasses can elide a parent’s parameter when they want a concrete override.

Parameters:

cls (type)

Return type:

dict[str, Parameter]