quchip.declarative.parameters

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

parameter() is the field-declaration surface concrete DeviceModel, CouplingModel, and Envelope 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.
constructor_field(*[, default, kw_only, runtime])	Describe a synthesized constructor argument to static type checkers.
parameter(*[, default, positive, ...])	Declare a traceable numerical parameter on a model class.
parameter_fields(cls)	Resolve declarative parameter fields for cls, walking 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 while preserving tracers.
setting(*[, default, serialize, kw_only])	Declare serialized structural configuration on a model class.
setting_fields(cls)	Resolve structural setting fields for cls, walking the MRO.
validate_declared_fields(cls)	Validate cross-cutting constraints on a class's declared fields.
validate_sign(name, spec, value)	Enforce a field's declared sign constraint on concrete scalars only.

Classes

DeclarativeMeta(name, bases, namespace, **kwargs)	Expose synthesized declarative constructors without runtime fields.
DriveDeclarativeMeta(name, bases, namespace, ...)	Expose drive parameters as keyword-only synthesized arguments.
Parameter([default, positive, nonnegative, ...])	Metadata for a declarative model parameter field.
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 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)

• symbol (str | None)

• noise (bool)

• kw_only (bool)

• required (bool)

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)

• serialize (bool)

• kw_only (bool)

default: Any = unbound

serialize: bool = True

kw_only: bool = True

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

Describe a synthesized constructor argument to static type checkers.

Parameters:

• default (Any)

• kw_only (bool)

• runtime (Any)

Return type:

Any

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. When omitted the parameter remains unbound 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 (e.g. "GHz").

• symbol (str or None, optional) – Mathematical symbol used when displaying authored physics. The field name is used when omitted.

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

• kw_only (bool)

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, 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)

• serialize (bool)

• kw_only (bool)

Return type:

Any

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

Bases: ABCMeta

Expose synthesized declarative constructors without runtime fields.

Parameters:

• name (str)

• bases (tuple[type, ...])

• namespace (dict[str, Any])

• kwargs (Any)

Return type:

type

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

Bases: DeclarativeMeta

Expose drive parameters as keyword-only synthesized arguments.

Parameters:

• name (str)

• bases (tuple[type, ...])

• namespace (dict[str, Any])

• kwargs (Any)

Return type:

type

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=())

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.

Parameters:

• param_fields (dict[str, Parameter])

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

Return type:

Signature

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, 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])

• fields (dict[str, Parameter] | None)

Return type:

dict[str, Any]

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

Pop declared structural settings from values and apply defaults.

Parameters:

• cls (type)

• values (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]

quchip.declarative.parameters.setting_fields(cls)

Resolve structural setting fields for cls, walking the MRO.

Parameters:

cls (type)

Return type:

dict[str, Setting]

quchip.declarative.parameters.validate_declared_fields(cls)

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

Parameters:

cls (type)

Return type:

None