On the registry root, dispatch to the concrete subclass named by data["type"] (forwarding *args / **kwargs). On a concrete subclass, defer to _from_dict_payload(). Concrete subclasses that carry payload override this method directly.

Parameters:: data (dict[str, Any])
Return type:: CableLoss

class quchip.extensions.ChargePhaseDrive(target=None, *, label=None)[source]¶

Bases: DeviceDrive

Map delivered I and Q to charge and phase observables.

Parameters:

target (Any)
label (Any)

hamiltonian(target, signal)[source]¶

Map a delivered classical signal to target-local quantum physics.

Parameters:

target (Any)
signal (Any)

Return type:

Any

class quchip.extensions.CollectiveDecayCoupling(device_a, device_b, exchange_strength=unbound, *, decay_rate=unbound, label=None)[source]¶

Bases: CouplingModel

Exchange coupling with an equal-phase collective decay channel.

Parameters:

device_a (BaseDevice | str)
device_b (BaseDevice | str)
exchange_strength (Any)
decay_rate (Any)
label (Any)

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

decay_rate: Any = Parameter(default=unbound, positive=False, nonnegative=True, serialize=True, unit='1/ns', symbol='\\gamma_c', noise=True, kw_only=True, required=False)¶

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

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

Return authored two-endpoint Lindblad channels.

Parameters:

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

Return type:

tuple[CollapseChannel, …]

class quchip.extensions.CosineEnvelope(duration=unbound, amplitude=1.0)[source]¶

Bases: Envelope

Raised-cosine pulse with zero endpoints and peak amplitude at mid-pulse.

\[E(t) = \frac{A}{2}\left[1-\cos(2\pi t/\tau)\right]\]

Parameters:

duration (Any)
amplitude (Any)

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

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

value(t)[source]¶

Return complex I/Q shape at time relative to the pulse start.

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

class quchip.extensions.FrequencyModulatedMode(frequency=unbound, modulation_amplitude=unbound, modulation_frequency=unbound, modulation_phase=0.0, *, levels=10, label=None, T1=None, T2=None, thermal_population=None)[source]¶

Bases: FockDevice

Harmonic mode with a prescribed sinusoidal frequency variation.

approximation = 'Single harmonic mode in a fixed Fock basis with an externally prescribed sinusoidal frequency coefficient.'¶: 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.

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

modulation_amplitude: Scalar = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='\\delta\\omega', noise=False, kw_only=False, required=False)¶

modulation_frequency: Scalar = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='\\nu_m', noise=False, kw_only=False, required=False)¶

modulation_phase: Scalar = Parameter(default=0.0, positive=False, nonnegative=False, serialize=True, unit='rad', symbol='\\phi_m', noise=False, kw_only=False, required=False)¶

property freq: Any¶: Bare reference frequency in GHz.

local_hamiltonian(op, p)[source]¶

Declare this device’s local Hamiltonian in its Fock space.

Parameters:

op (LocalOps)
p (Any)

Return type:

PhysicsExpr

time_terms(op, p)[source]¶

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

Parameters:

op (LocalOps)
p (Any)

Return type:

tuple[TimeDependentTerm, …]

tunable_param_names = ('frequency', 'modulation_amplitude', 'modulation_frequency', 'modulation_phase')¶

Bare parameters this device exposes as differentiable / tunable scalars. fit_a_dress walks this tuple to discover what it is allowed to optimize on each device, decoupling the inverse-design surface from any specific device model. Three states, keyed on whether the value is explicitly declared:

No explicit declaration anywhere in the DeviceModel lineage — the default is derived: every declared parameter() field, in declaration order (see DeviceModel.__init_subclass__).
Explicit tuple on the class or an ancestor — exact curation, validated at class-definition time; authoritative and inherited until a subclass explicitly replaces it.
Explicit empty tuple — deliberately freezes the device (and its subclasses, until one replaces it) out of inverse design.

On a plain (non-DeviceModel) BaseDevice subclass there is no derivation; the default stays empty unless the subclass declares its own tuple — e.g. Fluxonium uses ("E_C", "E_J", "E_L", "phi_ext").

class quchip.extensions.LossyChargeDrive(target=None, *, line_loss_rate=unbound, label=None)[source]¶

Bases: ChargeDrive

Charge-control line with an effective target-relaxation rate.

Parameters:

target (Any)
line_loss_rate (Any)
label (Any)

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

dissipation(device, op, p)[source]¶

Return target-local Lindblad channels contributed by this line.

Parameters:

device (BaseDevice)
op (Any)
p (Any)

Return type:

tuple[CollapseChannel, …]

class quchip.extensions.LossyKerrCavity(freq=unbound, kerr=unbound, *, levels=30, label=None, T1=None, T2=None, thermal_population=None, two_photon_loss_rate=unbound)[source]¶

Bases: KerrCavity

Kerr cavity with an intrinsic two-photon-loss channel.

two_photon_loss_rate: Scalar = Parameter(default=unbound, positive=False, nonnegative=True, serialize=True, unit='1/ns', symbol='\\kappa_2', noise=True, kw_only=True, required=False)¶

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

class quchip.extensions.ModulatedCapacitive(device_a, device_b, static_strength=unbound, modulation_amplitude=unbound, modulation_frequency=unbound, modulation_phase=0.0, *, label=None)[source]¶

Bases: CouplingModel

Capacitive interaction with a prescribed sinusoidal strength variation.

Parameters:

device_a (BaseDevice | str)
device_b (BaseDevice | str)
static_strength (Any)
modulation_amplitude (Any)
modulation_frequency (Any)
modulation_phase (Any)
label (Any)

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

modulation_amplitude: Any = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='\\delta g', noise=False, kw_only=False, required=False)¶

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

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

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

class quchip.extensions.SpinHalf(freq=unbound, *, basis=None, levels=2, label=None, T1=None, T2=None, thermal_population=None)[source]¶

Bases: DeviceModel

Two-level spin with a user-defined local operator vocabulary.

computational = True¶: Whether this device represents a computational qubit, as opposed to e.g. a bus resonator or a coupler element.

approximation = 'Exact two-level spin Hamiltonian in a fixed custom basis.'¶: 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.

basis: Literal['native', 'eigen'] | None = Setting(default=None, serialize=True, kw_only=True)¶

freq: Scalar = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='\\omega', noise=False, kw_only=False, required=False)¶

local_space()[source]¶

Return this device’s authored local operator space.

Return type:: CustomSpace

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

charge_coupling_operator()[source]¶

Return type:: Any

tunable_param_names = ('freq',)¶

No explicit declaration anywhere in the DeviceModel lineage — the default is derived: every declared parameter() field, in declaration order (see DeviceModel.__init_subclass__).
Explicit tuple on the class or an ancestor — exact curation, validated at class-definition time; authoritative and inherited until a subclass explicitly replaces it.
Explicit empty tuple — deliberately freezes the device (and its subclasses, until one replaces it) out of inverse design.

Modules

`couplings`	Reference coupling models with time dependence and coupling-owned loss.
`devices`	Reference device models, including device-owned time dependence and loss.
`drives`	Reference drives with multi-observable coupling and drive-owned loss.
`envelopes`	Reference scheduled envelope authored through the declarative surface.
`signals`	Reference classical signal transform.
`spaces`	Reference device authored on a custom local operator space.