quchip.declarative¶

Declarative physics model API.

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

Bases: BaseCoupling

Declarative two-body coupling base.

Subclasses declare physics parameters via parameter() and implement interaction() (returning a PhysicsExpr over the two endpoint operators). The chip’s approximation strategy is applied structurally by the engine after the authored interaction is assembled. Optional overrides:

time_terms() — time-dependent Hamiltonian terms, each pairing a local operator with a public time coefficient.

coupling_strength defaults to the first declared parameter field (suited for the common case of one g-like scalar). Override the property in subclasses with a different convention.

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 (BaseDevice | str)
device_b (BaseDevice | str)
label (Any)
params (Any)

device_a: BaseDevice | str¶

device_b: BaseDevice | str¶

label: Any¶

property coupling_strength: Any¶: Primary scalar coupling strength, defaulting to the first parameter.

property coupling_strength_name: str¶: Display name of coupling_strength, defaulting to 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 (Any)

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

Returns:

Local operators and their scalar time coefficients. The empty tuple denotes 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.

The coupling-side mirror of the device drive-dispatch protocols: a ParametricDrive accepts any coupling whose hook returns a PhysicsExpr.

Parameters:

a (Any)
b (Any)
p (Any)

Return type:

Any

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

Return authored two-endpoint Lindblad channels.

Parameters:

a (Any)
b (Any)
p (Any)

Return type:

tuple[CollapseChannel, …]

interaction_hamiltonian()[source]¶

Return the authored symbolic interaction Hamiltonian.

Return type:: Any

collapse_channels()[source]¶

Return normalized coupling collapse channels.

Return type:: tuple[CollapseChannel, …]

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

Reconstruct a coupling from to_dict() output.

Default implementation: forward declared parameters straight into __init__. Subclasses with bespoke serialization (e.g. envelope modulations) override this.

Parameters:

d (dict[str, Any])
device_a (Any)
device_b (Any)

Return type:

CouplingModel

to_dict()[source]¶

Serialize common coupling state plus declared parameter values.

Return type:: dict[str, Any]

class quchip.declarative.CollapseChannel(operator, rate, name)[source]¶

Bases: object

One unscaled Lindblad operator and its rate in inverse nanoseconds.

Parameters:

operator (Any)
rate (Any)
name (str)

operator: Any¶

rate: Any¶

name: str¶

class quchip.declarative.CosineCoefficient(amplitude=unbound, frequency=unbound, phase=0.0)[source]¶

Bases: TimeCoefficient

Cosine coefficient with amplitude in GHz and frequency in GHz.

Parameters:

amplitude (Any)
frequency (Any)
phase (Any)

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

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

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

value(t)[source]¶

Evaluate the coefficient at time t in ns.

Parameters:: t (Any)
Return type:: Any

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

Bases: BaseDevice

Declarative base for physics device models.

Subclasses declare their parameters as annotated class attributes using parameter() (e.g. 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 / 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)
label (str | None)
params (Any)

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_population: Any = Parameter(default=None, positive=False, nonnegative=True, serialize=True, unit=None, symbol=None, noise=True, kw_only=True, required=False)¶

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, ...]] = ()¶

validate()[source]¶

Cross-field validation hook, run at the end of construction.

Default is a no-op. Subclasses override to enforce constraints that span multiple declared parameters (e.g. 2 * edge <= duration). Checks must be gated on concrete scalars via quchip.utils.jax_utils.maybe_concrete_scalar() so traced parameters never force concretization.

Return type:: None

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, exposing a, adag, n, I and the Pauli handles as composable PhysicsExpr nodes.
p (ParameterNamespace) – Symbolic leaves for the parameters declared on this model.

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 (Any)
p (Any)

Return type:

tuple[TimeDependentTerm, …]

dissipation(op, p)[source]¶

Return device-local Lindblad channels.

The base channels implement T1, T2, and thermal occupation. Subclasses may append channels with super().dissipation(op, p).

Parameters:

op (Any)
p (Any)

Return type:

tuple[CollapseChannel, …]

unresolved_hamiltonian()[source]¶

Return the authored symbolic local Hamiltonian.

Return type:: Any

to_dict()[source]¶

Serialize common device state plus declared parameter values.

Return type:: dict[str, Any]

classmethod from_dict(d)[source]¶

Reconstruct the device from to_dict() output.

Parameters:: d (dict[str, Any])
Return type:: DeviceModel

physics_notes()[source]¶

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

Return type:: list[str]

quchip.declarative.EndpointOps¶: alias of LocalOps

class quchip.declarative.LocalOps(label, space, device=None)[source]¶

Bases: object

Declarative operator namespace for one local Hilbert space endpoint.

Passed as op to DeviceModel.local_hamiltonian() and as the two endpoints a, b to CouplingModel.interaction(). Each property returns a PhysicsExpr that composes with +, -, @ (same endpoint), * (scalar or tensor product).

Examples

>>> from quchip.declarative import LocalOps
>>> from quchip.devices.spaces import FockSpace
>>> op = LocalOps(label="q", space=FockSpace(3))
>>> H = 5.0 * op.n + 0.5 * (op.adag @ op.adag @ op.a @ op.a)
>>> H.kind
'add'

Parameters:

label (str)
space (LocalSpace)
device (Any)

label: str¶

space: LocalSpace¶

device: Any = None¶

property a: PhysicsExpr¶: Lowering operator for this endpoint.

property adag: PhysicsExpr¶: Raising operator for this endpoint.

property n: PhysicsExpr¶: Number operator for this endpoint.

property level: PhysicsExpr¶: Energy-level index operator in the authored local basis.

property n2: PhysicsExpr¶: Squared charge operator in a compatible authored local space.

property phi: PhysicsExpr¶: Phase operator in a compatible authored local space.

property cos_phi: PhysicsExpr¶: Cosine of phase in a compatible authored local space.

property sin_phi: PhysicsExpr¶: Sine of phase in a compatible authored local space.

property I: PhysicsExpr¶: Identity operator for this endpoint.

property x: PhysicsExpr¶: Unnormalized quadrature x = a + a† (no 1/sqrt(2) factor).

property charge: PhysicsExpr¶: Physical charge-like drive operator for this local representation.

property sigma_x: PhysicsExpr¶: |0><1| + |1><0| on the computational |0>, |1> subspace of the truncated space.

property sigma_y: PhysicsExpr¶: -i|0><1| + i|1><0| on the computational |0>, |1> subspace.

property sigma_z: PhysicsExpr¶: |0><0| - |1><1| on the computational |0>, |1> subspace.

property sigma_plus: PhysicsExpr¶: Raising operator |1><0| on the computational subspace.

property sigma_minus: PhysicsExpr¶: Lowering operator |0><1| on the computational subspace.

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

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.PhysicsExpr(kind, args=(), labels=(), _bindings=<factory>)[source]¶

Bases: object

Authored scalar and operator algebra, independent of numerical values.

Parameters:

kind (str)
args (tuple[Any, ...])
labels (tuple[str, ...])
_bindings (Mapping[str, Any])

kind: str¶

args: tuple[Any, ...] = ()¶

labels: tuple[str, ...] = ()¶

classmethod parameter(*, scope, name, symbol=None, unit=None)[source]¶

Create a symbolic declared-parameter leaf.

Parameters:

scope (str)
name (str)
symbol (str | None)
unit (str | None)

Return type:

PhysicsExpr

classmethod literal(value)[source]¶

Create a literal scalar leaf.

Parameters:: value (Any)
Return type:: PhysicsExpr

classmethod from_matrix(value, *, labels, dims, name=None)[source]¶

Create a named backend-neutral matrix contribution.

Parameters:

value (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str | None)

Return type:

PhysicsExpr

classmethod from_function(function, *arguments, labels, dims, name=None)[source]¶

Create an opaque matrix-valued contribution from a pure function.

The function runs only during numerical materialization. Display keeps its declared name and arguments, such as X(a, b), without exposing the implementation as symbolic algebra.

Parameters:

function (Any)
arguments (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str | None)

Return type:

PhysicsExpr

classmethod from_state(value, *, labels, dims, name)[source]¶

Create a named authored ket contribution.

Parameters:

value (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str)

Return type:

PhysicsExpr

classmethod from_state_function(function, *arguments, labels, dims, name)[source]¶

Create an opaque callable ket contribution.

Parameters:

function (Any)
arguments (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str)

Return type:

PhysicsExpr

classmethod from_signal(signal, *, name='f')[source]¶

Create a scalar time-function leaf backed by an engine signal.

Parameters:

signal (Any)
name (str)

Return type:

PhysicsExpr

embed(labels, dims)[source]¶

Embed this local contribution into an ordered composite Hilbert space.

Parameters:

labels (tuple[str, ...])
dims (tuple[int, ...])

Return type:

PhysicsExpr

with_bindings(bindings)[source]¶

Attach default values used only by direct numerical inspection.

Parameters:: bindings (Mapping[str, Any])
Return type:: PhysicsExpr

parameter_paths()[source]¶

Return referenced dotted parameter paths in authored order.

Return type:: tuple[str, …]

numeric_values()[source]¶

Return bound and matrix payloads for tracer-safe cache decisions.

Return type:: tuple[Any, …]

property shape: tuple[int, int]¶: Matrix shape implied by this operator expression’s static support.

latex()[source]¶

Render the authored expression with familiar mathematical notation.

Return type:: str

matrix(bindings=None, *, t=None, backend=None)[source]¶

Materialize this expression and return its dense numerical array.

Parameters:

bindings (Mapping[str, Any] | None)
t (Any | None)
backend (Any)

Return type:

Any

class quchip.declarative.TimeDependentTerm(operator, coefficient)[source]¶

Bases: object

An authored local operator and its time coefficient.

Parameters:

operator (Any)
coefficient (TimeCoefficient)

operator: Any¶

coefficient: TimeCoefficient¶

quchip.declarative.Scalar¶: alias of Any

class quchip.declarative.Setting(default=unbound, serialize=True, kw_only=True)[source]¶

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¶

class quchip.declarative.TimeCoefficient[source]¶

Bases: Registrable, ABC

Scalar coefficient of a component’s time-dependent Hamiltonian term.

Time is measured in ns. Implementations use quchip.qnp so values remain JAX-traceable without receiving an array namespace argument.

abstractmethod value(t)[source]¶

Evaluate the coefficient at time t in ns.

Parameters:: t (Any)
Return type:: Any

to_dict()[source]¶

Serialize the concrete coefficient and its numerical fields.

Return type:: dict[str, Any]

quchip.declarative.as_operator_expr(value, *, labels, dims, name, arguments=(), owner=None, scope=None, allowed=None)[source]¶

Normalize symbolic, matrix, or opaque callable operator authorship.

Parameters:

value (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str)
arguments (tuple[Any, ...])
owner (Any | None)
scope (str | None)
allowed (Mapping[str, Any] | None)

Return type:

PhysicsExpr

quchip.declarative.as_scalar_expr(value, *, name, arguments=(), owner=None, scope=None, allowed=None)[source]¶

Normalize symbolic, numeric, or opaque callable scalar authorship.

Parameters:

value (Any)
name (str)
arguments (tuple[Any, ...])
owner (Any | None)
scope (str | None)
allowed (Mapping[str, Any] | None)

Return type:

PhysicsExpr

quchip.declarative.as_state_expr(value, *, labels, dims, name, arguments=(), owner=None, scope=None, allowed=None)[source]¶

Normalize an authored ket array or opaque callable without evaluating it.

Parameters:

value (Any)
labels (tuple[str, ...])
dims (tuple[int, ...])
name (str)
arguments (tuple[Any, ...])
owner (Any | None)
scope (str | None)
allowed (Mapping[str, Any] | None)

Return type:

PhysicsExpr

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

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.setting(*, default=unbound, serialize=True, kw_only=True)[source]¶

Declare serialized structural configuration on a model class.

Parameters:

default (Any)
serialize (bool)
kw_only (bool)

Return type:

Any

Modules

`dissipation`	Authored Lindblad dissipation values.
`dynamics`	Public records for component-owned time-dependent Hamiltonian terms.
`expr`	One backend-neutral expression tree for authored scalar and operator physics.
`models`	Declarative base classes for device and coupling physics models.
`ops`	Declarative operator-handle namespaces for the physics DSL.
`parameters`	Declared-parameter metadata, synthesized `__init__` signatures, and validation.
`qnp`	Trace-safe numeric namespace for declarative model authors.