quchip.declarative.models¶

Declarative base classes for device and coupling physics models.

DeviceModel and CouplingModel let a subclass declare its physics parameters as annotated class attributes with parameter(). The subclass implements only the Hamiltonian expression. Both classes synthesize their own __init__, JAX pytree registration (for DeviceModel), and post-construction sign validation from the declared fields.

Classes

`CouplingModel`(device_a, device_b, *[, label])	Declarative two-body coupling base.
`DeviceModel`(*[, levels, label])	Declarative base for physics device models.

class quchip.declarative.models.DeviceModel(*, levels=2, label=None, **params)[source]¶

Bases: BaseDevice

Declarative base for physics device models.

Subclasses declare their parameters as annotated class attributes with parameter() (for example freq: Scalar = parameter(positive=True)) and implement local_hamiltonian(). The declared parameters become positional-or-keyword __init__ arguments and JAX pytree leaves, so the full instance is traceable, differentiable, and sweepable end-to-end.

The hamiltonian() adapter compiles the declarative expression returned by local_hamiltonian() into an operator for the active default backend.

Examples

>>> from quchip.declarative import DeviceModel, parameter, Scalar
>>> class DuffingOscillator(DeviceModel):
...     freq: Scalar = parameter(positive=True, unit="GHz")
...     anharmonicity: Scalar = parameter(unit="GHz")
...     def local_hamiltonian(self, op, p):
...         return p.freq * op.n + 0.5 * p.anharmonicity * op.n @ (op.n - op.I)
>>> device = DuffingOscillator(freq=5.0, anharmonicity=-0.3, levels=4)
>>> device.freq
5.0

Parameters:

levels (int, keyword-only, default 2) – Native local-space dimension or truncation.
label (str or None, keyword-only, default None) – Stable device label. None selects an automatic label.
**params (Any) – Declared model parameters and optional noise fields.

levels: int¶

label: Any¶

T1: Any = Parameter(default=None, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=True, kw_only=True, required=False)¶

T2: Any = Parameter(default=None, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=True, kw_only=True, required=False)¶

thermal_occupation: Any = Parameter(default=None, positive=False, nonnegative=True, serialize=True, unit=None, symbol=None, noise=True, kw_only=True, required=False)¶

property thermal_population: Any¶: Deprecated alias for the bath’s mean thermal occupation.

approximation: ClassVar[str | None] = None¶: Declared approximation-regime statement surfaced by physics_notes() — the mechanism that keeps a model’s stated validity range attached to the class rather than buried in a docstring a caller may not read.

computational: ClassVar[bool] = False¶: Whether this device represents a computational qubit, as opposed to e.g. a bus resonator or a coupler element.

structural_setting_names: ClassVar[tuple[str, ...]] = ()¶

local_hamiltonian(op, p)[source]¶

Return this device’s local Hamiltonian as a declarative expression.

Parameters:

op (LocalOps) – Operator namespace for this device’s endpoint. It exposes a, adag, n, I and the Pauli handles as composable PhysicsExpr nodes.
p (ParameterNamespace) – Symbolic leaves for this model’s declared parameters.

Returns:

The local Hamiltonian expression, in ordinary-frequency units (GHz).

Return type:

PhysicsExpr

time_terms(op, p)[source]¶

Return local time-dependent Hamiltonian terms beyond the static model.

Parameters:

op (LocalOps) – Local operator namespace.
p (ParameterNamespace) – Symbolic declared parameters.

dissipation(op, p)[source]¶

Return device-local Lindblad channels.

Parameters:

op (LocalOps) – Local operator namespace.
p (ParameterNamespace) – Symbolic declared parameters.
T1 (The base channels implement)
T2
Subclasses (and thermal occupation.)
``super().dissipation(op (may append channels with) –
p)``.

unresolved_hamiltonian()[source]¶

Return the authored symbolic local Hamiltonian.

to_dict()[source]¶

Serialize common device state and declared parameter values.

classmethod from_dict(d)[source]¶

Reconstruct the device from to_dict() output.

Parameters:: d (mapping) – Serialized device record.

physics_notes()[source]¶

Return base device notes plus the declared approximation, if any.

class quchip.declarative.models.CouplingModel(device_a, device_b, *, label=None, **params)[source]¶

Bases: BaseCoupling

Declarative two-body coupling base.

Subclasses declare physics parameters with parameter() and implement interaction(), which returns a PhysicsExpr over the two endpoint operators. After the authored interaction is assembled, the engine applies the chip’s approximation strategy structurally. Optional overrides:

time_terms(): time-dependent Hamiltonian terms. Each term pairs a local operator with a public time coefficient.

coupling_strength defaults to the first declared parameter field (the common case of one g-like scalar). Subclasses with a different convention override the property.

Note

Coupling instances are not registered as JAX pytrees and cannot be passed as dynamic jax.jit / jax.vmap / jax.grad arguments. Coupling parameters remain differentiable when the coupling (and the devices or chip it couples) is constructed from traced arguments inside the transformed function.

Examples

>>> from quchip.declarative import CouplingModel, parameter, Scalar
>>> class ExchangeCoupling(CouplingModel):
...     g: Scalar = parameter(unit="GHz")
...     def interaction(self, a, b, p):
...         return p.g * (a.a * b.adag + a.adag * b.a)
>>> c = ExchangeCoupling("q0", "q1", g=0.01)
>>> c.coupling_strength
0.01

Parameters:

device_a (device or str) – Coupled devices or their labels.
device_b (device or str) – Coupled devices or their labels.
label (str or None, keyword-only, default None) – Stable coupling label.
**params (Any) – Declared coupling parameters and settings.

device_a: BaseDevice | str¶

device_b: BaseDevice | str¶

label: Any¶

property coupling_strength: Any¶: Primary scalar coupling strength. The default is the first parameter.

property coupling_strength_name: str¶: Display name of coupling_strength. The default is the first parameter field.

interaction(a, b, p)[source]¶

Return the full two-body interaction expression.

Parameters:

a (EndpointOps) – Operator namespaces for the two coupled endpoints. Same-endpoint operators compose with @. Cross-endpoint operators combine with * (tensor product).
b (EndpointOps) – Operator namespaces for the two coupled endpoints. Same-endpoint operators compose with @. Cross-endpoint operators combine with * (tensor product).
p (ParameterNamespace) – Symbolic declared coupling parameters.

Returns:

The interaction Hamiltonian expression, in ordinary-frequency units (GHz).

Return type:

PhysicsExpr

time_terms(a, b, p)[source]¶

Return time-dependent interaction terms.

Parameters:

a (EndpointOps) – Operator namespaces for the two coupled endpoints.
b (EndpointOps) – Operator namespaces for the two coupled endpoints.
p (ParameterNamespace) – Symbolic declared coupling parameters.

Returns:

Local operators and their scalar time coefficients. An empty tuple means a purely static coupling.

Return type:

tuple of TimeDependentTerm

parametric_interaction(a, b, p)[source]¶

Return the parametric interaction structure, or None when this coupling is not modulable.

Parameters:

a (EndpointOps) – Ordered endpoint operator namespaces.
b (EndpointOps) – Ordered endpoint operator namespaces.
p (ParameterNamespace) – Symbolic declared coupling parameters.

Notes

This hook is the coupling-side mirror of the device drive-dispatch protocols. A ParametricDrive accepts all couplings whose hook returns a PhysicsExpr.

dissipation(a, b, p)[source]¶

Return authored two-endpoint Lindblad channels.

Parameters:

a (EndpointOps) – Ordered endpoint operator namespaces.
b (EndpointOps) – Ordered endpoint operator namespaces.
p (ParameterNamespace) – Symbolic declared coupling parameters.

interaction_hamiltonian()[source]¶

Return the authored symbolic interaction Hamiltonian.

collapse_channels()[source]¶

Return normalized coupling collapse channels.

classmethod from_dict(d, device_a, device_b)[source]¶

Reconstruct a coupling from to_dict() output.

Parameters:

d (mapping) – Serialized coupling record.
device_a (device or str) – Endpoints that the containing chip supplies.
device_b (device or str) – Endpoints that the containing chip supplies.
implementation (Default)
envelope (__init__. Subclasses with bespoke serialization (e.g.)
this. (modulations) override)

to_dict()[source]¶

Serialize common coupling state and declared parameter values.