quchip.devices¶

Device models — truncated-Hilbert-space quantum systems owned by a chip.

A device declares its local Hamiltonian; couplings and drives contribute their own local Hamiltonians. See quchip.devices.base for the full device protocol.

Public models¶

Resonator — linear harmonic mode, H = omega * n_hat.
DuffingTransmon — Duffing-anharmonic transmon qubit, H = omega * n + (alpha/2) * n * (n - I).
FluxTunableTransmon — SQUID-dispersion flux-tunable transmon; freq/anharmonicity are the calibrated local transition parameters at the stored flux_bias.
KerrCavity — Kerr-nonlinear resonator, H = omega * n_hat - K * n_hat * (n_hat - I).
CircuitDevice — abstract base for circuit-level devices built by diagonalizing a native-basis Hamiltonian.
Fluxonium — circuit-level fluxonium in the phase basis.
ChargeBasisTransmon — circuit-level transmon in the integer charge basis.

Coupling Protocols (for drive dispatch)¶

ChargeCoupled, PhaseCoupled, FluxCoupled, FrequencyControlled

class quchip.devices.ChargeBasisTransmon(E_C, E_J, n_g=0.0, levels=3, label=None, *, num_basis=61, collapse_model='fermi_golden', coupling_channel=None, collapse_rate_threshold=1e-08, **noise_kwargs)[source]¶

Bases: CircuitDevice

Transmon in the integer charge basis — exact diagonalization.

Parameters:

E_C (float) – Charging energy in GHz. Must be positive. May be a JAX tracer.
E_J (float) – Josephson energy in GHz. Must be positive. May be a JAX tracer.
n_g (float, default 0.0) – Offset charge (units of \(2e\)). May be a JAX tracer.
levels (int, default 3) – Truncated eigenbasis size.
label (str or None) – Auto-generated as charge_basis_transmon_{n} if omitted.
num_basis (int, default 61) – Charge-basis cutoff — must be odd, corresponding to \(n \in [-n_\mathrm{cut}, +n_\mathrm{cut}]\) with \(n_\mathrm{cut} = (\text{num\_basis} - 1)/2\).
collapse_model ("fermi_golden" or "ladder", default "fermi_golden") – See CircuitDevice.
collapse_rate_threshold (float, default 1e-8) – See CircuitDevice.
**noise_kwargs – Forwarded to BaseDevice (T1, T2, thermal_population).
coupling_channel (Literal['charge', 'flux'] | None)

Notes

The T1 collapse-operator normalization assumes T1 is set by charge-operator-coupled relaxation (Breuer & Petruccione §3.4). For phonon / quasiparticle / flux-dominated T1, override collapse_operators() or pass collapse_model='ladder'.

tunable_param_names = ('E_C', 'E_J', 'n_g')¶

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").

approximation = 'Exact diagonalization in the truncated integer charge basis; accuracy governed by num_basis.'¶: Declared approximation-regime statement surfaced by physics_notes(), mirroring approximation — this class does not inherit from DeviceModel, so the attribute and its surfacing are declared here directly.

tunable_param_bounds(name, value)[source]¶

n_g lives in [-0.5, 0.5] (one charge period); other params delegate.

Parameters:

name (str)
value (float)

Return type:

tuple[float, float]

physics_notes()[source]¶

Return declared integer-charge-basis assumptions.

Return type:: list[str]

classmethod from_frequency(freq, anharmonicity, n_g=0.0, levels=3, label=None, *, num_basis=61, collapse_model='fermi_golden', coupling_channel=None, collapse_rate_threshold=1e-08, **noise_kwargs)[source]¶

Construct from (freq, anharmonicity) using the Koch-regime inversion.

Uses \(E_C = -\alpha\) and \(E_J = (\omega + E_C)^2 / (8 E_C)\). Residual between the Duffing approximation and the exact diagonalized spectrum is typically <1% for \(E_J/E_C > 50\), growing below that. A concrete-scalar warning fires at \(E_J/E_C < 20\).

Parameters:

freq (float)
anharmonicity (float)
n_g (float)
levels (int)
label (str | None)
num_basis (int)
collapse_model (Literal['fermi_golden', 'ladder'])
coupling_channel (Literal['charge', 'flux'] | None)
collapse_rate_threshold (float)
noise_kwargs (float | None)

Return type:

ChargeBasisTransmon

property computational: bool¶: Charge-basis transmon is a computational qubit.

to_dict()[source]¶

Extend CircuitDevice.to_dict() with the charge-basis circuit parameters.

Return type:: dict[str, Any]

classmethod from_dict(d)[source]¶

Reconstruct from to_dict() output.

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:: d (dict[str, Any])
Return type:: ChargeBasisTransmon

class quchip.devices.ChargeCoupled(*args, **kwargs)[source]¶

Bases: Protocol

Device exposes the physical charge operator in its truncated eigenbasis.

ChargeDrive dispatches against this Protocol and emits drives using charge_coupling_operator() rather than the structural 1j*(a - a†) from BaseDevice.lowering_operator().

charge_coupling_operator()[source]¶

Return the physical charge operator in the truncated eigenbasis.

Return type:: Any

class quchip.devices.CircuitDevice(levels, label=None, *, collapse_model='fermi_golden', coupling_channel=None, collapse_rate_threshold=1e-08, **noise_kwargs)[source]¶

Bases: BaseDevice

Abstract base for devices built by diagonalizing a native-basis circuit.

Conforms to the ChargeCoupled and PhaseCoupled Protocols by default; subclasses may additionally conform to FluxCoupled by defining flux_coupling_operator().

Subclasses must implement:

_build_native_hamiltonian()
_native_charge_operator()
_native_phase_operator()

Parameters:

levels (int)
label (str | None)
collapse_model (Literal['fermi_golden', 'ladder'])
coupling_channel (Literal['charge', 'flux'] | None)
collapse_rate_threshold (float)
noise_kwargs (float | None)

approximation: str | None = None¶: Declared approximation-regime statement surfaced by physics_notes(), mirroring approximation — this class does not inherit from DeviceModel, so the attribute and its surfacing are declared here directly.

hamiltonian()[source]¶

Diagonal diag(0, E_01, E_02, …) in the truncated eigenbasis.

Returned as a backend-native diagonal operator — the engine relies on chip.hamiltonian() producing the same sparse layout as number_operator() so layout-aware backends (e.g. dynamiqs sparse-DIA) do not silently densify when assembling H₀.

Return type:: Any

eigenenergies()[source]¶

Return the truncated eigenvalue array, shape (levels,), with \(E_0 = 0\).

Return type:: Any

eigenvectors()[source]¶

Return the truncated eigenvector matrix V, shape (num_basis, levels).

Return type:: Any

project_operator(native_op)[source]¶

Transform a native-basis operator O into the truncated eigenbasis.

Returns \(V^\dagger O V\).

Parameters:: native_op (Any)
Return type:: Any

property freq: Any¶: Bare 0→1 transition frequency \(E_1 - E_0\) (GHz).

charge_coupling_operator()[source]¶

Return the physical charge operator \(V^\dagger \hat n V\) in the eigenbasis.

Returned as a dense, trace-safe array-like (see quchip.devices.protocols); backend composition entry points coerce it to native form on use.

Return type:: Any

phase_coupling_operator()[source]¶

Return the physical phase-coupling operator in the eigenbasis.

Returns \(V^\dagger \hat\varphi V\) on a phase-basis device (fluxonium); returns \(V^\dagger \sin\hat\varphi V\) on an integer-charge-basis device (charge-basis transmon), since \(\hat\varphi\) is not single-valued there.

Return type:: Any

physics_notes()[source]¶

Return declared diagonalization and collapse-model assumptions.

Return type:: list[str]

to_dict()[source]¶

Extend BaseDevice.to_dict() with circuit-level collapse params.

Return type:: dict[str, Any]

class quchip.devices.DuffingTransmon(freq, anharmonicity, *, levels=3, label=None, T1=None, T2=None, thermal_population=None)[source]¶

Bases: DeviceModel

Transmon modelled as a weakly anharmonic Duffing oscillator.

Parameters:

freq (float) – Bare 0 -> 1 transition frequency ω in GHz. Must be positive. May be a JAX tracer for sweeps / gradients.
anharmonicity (float) – Anharmonicity α in GHz. Typically negative for superconducting transmons (e.g. -0.25 GHz). May be a JAX tracer.
levels (int, default 3) – Fock-space truncation. Three levels suffice for leakage-aware single-qubit modelling; increase for higher-level physics (e.g. iSWAP-family gates via the |02>-|11> crossing).
label (str | None, default None) – If omitted, auto-generated as duffing_{idx} via the shared labeling counter.
**noise_kwargs – Forwarded to BaseDevice — T1, T2, thermal_population.

Example

>>> from quchip.devices import DuffingTransmon
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, T1=30_000.0, T2=20_000.0)
>>> len(q.collapse_operators()) >= 1
True

tunable_param_names = ('freq', 'anharmonicity')¶

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.

approximation = 'Duffing expansion: cosine Josephson potential truncated at 4th order.'¶: 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 = True¶: Whether this device represents a computational qubit, as opposed to e.g. a bus resonator or a coupler element.

freq: Scalar = Parameter(default=<object object>, positive=True, nonnegative=False, serialize=True, unit='GHz')¶

anharmonicity: Scalar = Parameter(default=<object object>, positive=False, nonnegative=False, serialize=True, unit='GHz')¶

local_hamiltonian(op)[source]¶

Return the local Duffing Hamiltonian H = omega n + (alpha/2) n (n - I).

Parameters:: op (LocalOps)
Return type:: PhysicsExpr

physics_notes()[source]¶

Return declared Duffing-approximation validity notes.

Return type:: list[str]

class quchip.devices.FluxCoupled(*args, **kwargs)[source]¶

Bases: Protocol

Device exposes the physical flux-line coupling operator.

For a fluxonium this is \(V^\dagger \hat\varphi V\); for a flux-tunable transmon (future follow-up) it will be a flux-modulated term. Used by FluxDrive.

flux_coupling_operator()[source]¶

Return the physical flux-line coupling operator in the eigenbasis.

Return type:: Any

class quchip.devices.FluxTunableTransmon(freq, anharmonicity, flux_bias=0.0, asymmetry=0.0, *, levels=3, label=None, T1=None, T2=None, thermal_population=None)[source]¶

Bases: DeviceModel

SQUID-dispersion flux-tunable transmon.

The constructor takes the calibrated local physical parameters; SQUID metadata is derived on read and is not part of the public interface.

Parameters:

freq (float) – Calibrated local 0 -> 1 transition frequency ω in GHz, at the stored flux_bias. Must be positive. May be a JAX tracer.
anharmonicity (float) – Calibrated local anharmonicity α in GHz, at the stored flux_bias. Must be negative (α ≈ −E_C). May be a JAX tracer.
flux_bias (float, default 0.0) – Calibration-anchor operating point Φ/Φ₀. Any real value; the SQUID inversion is undefined only at the symmetric-SQUID degenerate point (asymmetry == 0 and flux_bias a half-integer — see validate()). The local Hamiltonian does not reference this value directly — freq and anharmonicity already carry it. A pytree leaf, so it is differentiable / sweepable like every other device parameter.
asymmetry (float, default 0.0) – SQUID junction asymmetry d = (E_{J1}−E_{J2})/(E_{J1}+E_{J2}). Must be in [0, 1).
levels (int, default 3) – Fock-space truncation.
label (str | None, default None) – Auto-generated as fluxtunable_{idx} when omitted.
**noise_kwargs – Forwarded to BaseDevice — T1, T2, thermal_population.

tunable_param_names = ('freq', 'anharmonicity')¶

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.

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

approximation = 'Duffing-approximated SQUID transmon; adiabatic flux (calibration-anchor, no Landau-Zener).'¶: 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.

freq: Scalar = Parameter(default=<object object>, positive=True, nonnegative=False, serialize=True, unit='GHz')¶

anharmonicity: Scalar = Parameter(default=<object object>, positive=False, nonnegative=False, serialize=True, unit='GHz')¶

flux_bias: Scalar = Parameter(default=0.0, positive=False, nonnegative=False, serialize=True, unit='Phi_0')¶

asymmetry: Scalar = Parameter(default=0.0, positive=False, nonnegative=False, serialize=True, unit=None)¶

validate()[source]¶

Range checks on concrete scalars only; traced values pass unchecked.

Return type:: None

local_hamiltonian(op)[source]¶

Return the Duffing Hamiltonian built from the calibrated freq and anharmonicity.

H = ω n + (α/2) n(n − I). Does not reference flux_bias.

Parameters:: op (LocalOps)
Return type:: PhysicsExpr

frequency_at(flux)[source]¶

SQUID dispersion ω(Φ/Φ₀) in GHz, using derived E_C and E_J_max.

Parameters:: flux (float) – Reduced flux Φ/Φ₀. JAX-traceable.
Return type:: Any

flux_for_frequency(target_freq)[source]¶

Inverse SQUID dispersion on the monotonic lobe Φ/Φ₀ ∈ [0, 0.5).

Derivation:: ω(Φ) = sqrt(8 E_C E_J_max sqrt(cos²(πΦ) + d²sin²(πΦ))) − E_C → let S = (ω + E_C)² / (8 E_C E_J_max) → cos²(πΦ)(1 − d²) + d² = S² → cos²(πΦ) = (S² − d²) / (1 − d²)

Raises:: ValueError – If target_freq is concrete and lands outside the frequency range frequency_at() reaches over Φ/Φ₀ ∈ [0, 0.5) at the current calibration anchor. A traced target_freq (or a traced anchor) skips this check; the returned flux clips to the lobe endpoint, so out-of-domain behavior is undefined for traced inputs.
Parameters:: target_freq (Any)
Return type:: Any

physics_notes()[source]¶

Return declared SQUID-transmon calibration-anchor assumptions.

Return type:: list[str]

class quchip.devices.Fluxonium(E_C, E_J, E_L, phi_ext=0.0, levels=10, label=None, *, num_basis=400, phi_max=None, collapse_model='fermi_golden', coupling_channel=None, collapse_rate_threshold=1e-08, **noise_kwargs)[source]¶

Bases: CircuitDevice

Fluxonium qubit on a non-periodic plane-wave phase basis.

Parameters:

E_C (float) – Charging energy in GHz. Positive. JAX-traceable.
E_J (float) – Josephson energy in GHz. Positive. JAX-traceable.
E_L (float) – Inductive energy in GHz. Positive. JAX-traceable.
phi_ext (float, default 0.0) – External flux in units of \(\Phi_0\) (0.5 = half-flux sweet spot). JAX-traceable.
levels (int, default 10) – Truncated eigenbasis size.
label (str or None)
num_basis (int, default 400) – Phase-basis grid points.
phi_max (float, default 5 * pi) – Phase grid half-range; grid is [-phi_max, +phi_max).
collapse_model (see) – CircuitDevice. coupling_channel is required when collapse_model='fermi_golden' (the default) with T1 set — pick 'flux' at or near the flux sweet spot (phi_ext = 0.5), where relaxation is flux-noise-dominated, and 'charge' for charge-operator-limited T1 regimes.
coupling_channel (see) – CircuitDevice. coupling_channel is required when collapse_model='fermi_golden' (the default) with T1 set — pick 'flux' at or near the flux sweet spot (phi_ext = 0.5), where relaxation is flux-noise-dominated, and 'charge' for charge-operator-limited T1 regimes.
collapse_rate_threshold (see) – CircuitDevice. coupling_channel is required when collapse_model='fermi_golden' (the default) with T1 set — pick 'flux' at or near the flux sweet spot (phi_ext = 0.5), where relaxation is flux-noise-dominated, and 'charge' for charge-operator-limited T1 regimes.
**noise_kwargs – Forwarded to BaseDevice.

Notes

The T1 collapse-operator model depends on coupling_channel: 'charge' uses \(\hat n\) matrix elements (Breuer-Petruccione §3.4, Smith 2020 §III.B); 'flux' uses \(\hat\varphi\) matrix elements (proportional to \(\partial H/\partial\varphi_\mathrm{ext}\) since only the \(\hat\varphi\) term is operator-valued there). Inherited pure dephasing uses level-index scaling — physically incomplete for fluxonium away from sweet spot, where flux-noise-weighted dephasing is the physical channel. Sweet-spot accurate dephasing is a follow-up PR.

tunable_param_names = ('E_C', 'E_J', 'E_L', 'phi_ext')¶

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.

approximation = 'Exact diagonalization on a finite phase grid; 2nd-order central finite differences for the kinetic term; accuracy governed by num_basis.'¶: Declared approximation-regime statement surfaced by physics_notes(), mirroring approximation — this class does not inherit from DeviceModel, so the attribute and its surfacing are declared here directly.

flux_coupling_operator()[source]¶

Return the flux-line coupling operator \(V^\dagger \hat\varphi V\).

Return type:: Any

physics_notes()[source]¶

Return declared phase-basis discretization assumptions.

Return type:: list[str]

property computational: bool¶: Fluxonium is a computational qubit.

to_dict()[source]¶

Extend CircuitDevice.to_dict() with the fluxonium circuit parameters.

Return type:: dict[str, Any]

classmethod from_dict(d)[source]¶

Reconstruct from to_dict() output.

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

class quchip.devices.FrequencyControlled(*args, **kwargs)[source]¶

Bases: Protocol

Device exposes a frequency-vs-flux relation, i.e. it is frequency-tunable.

reduce_device() uses isinstance(mode, FrequencyControlled) to decide whether an eliminated mode’s mediated-exchange fold should stay tunable — emitting a TunableCapacitive — rather than a fixed Capacitive. FluxTunableTransmon satisfies this Protocol structurally, with no explicit subclassing.

frequency_at(flux)[source]¶

Return the device’s transition frequency at the given flux bias.

Parameters:: flux (Any)
Return type:: Any

class quchip.devices.KerrCavity(freq, kerr, *, levels=30, label=None, T1=None, T2=None, thermal_population=None)[source]¶

Bases: DeviceModel

Kerr-nonlinear resonator supporting cat-qubit stabilisation.

Hamiltonian:

\[H = \omega \, \hat{n} - K \, \hat{n}(\hat{n} - I)\]

The nonlinearity \(K\) shifts the photon-number eigenenergies, making the cavity anharmonic. Combined with a two-photon parametric drive at \(2\omega\), the steady state becomes a cat state with amplitude \(\alpha = \sqrt{\varepsilon_2 / K}\).

Parameters:

freq (float) – Cavity frequency \(\omega\) in GHz. Must be positive. May be a JAX tracer for sweeps / gradients.
kerr (float) – Kerr nonlinearity \(K\) in GHz. Non-negative; positive value shifts even-photon levels downward. Typically 1–100 MHz in superconducting circuits.
levels (int) – Fock-space truncation dimension. Choose at least 4 * (eps2 / K) + 10 to avoid truncation artefacts. Default 30.
label (str | None) – Human-readable label. None → auto-generated kerr_cavity_0, kerr_cavity_1, …
**noise_kwargs – Forwarded to BaseDevice: T1, T2, thermal_population, etc.

Notes

This Hamiltonian is diagonal in the Fock basis and does not itself define a computational subspace. Combined with a two-photon parametric drive, the steady state can be engineered into a cat-code manifold spanned by the even cat state \(|C^+_\alpha\rangle\) and the odd cat state \(|C^-_\alpha\rangle\). Bit-flip errors within that manifold are exponentially suppressed, \(\sim e^{-2|\alpha|^2}\), in the stabilized regime. This class’s inherited Pauli surface (computational is False) addresses the bare Fock |0>, |1> subspace; see physics_notes() for the caveat.

References

Examples

>>> from quchip.devices.kerr_cavity import KerrCavity
>>> cav = KerrCavity(freq=5.0, kerr=1.0, levels=10, label="cav")
>>> cav.freq, cav.kerr, cav.levels
(5.0, 1.0, 10)

tunable_param_names = ('freq', 'kerr')¶

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.

approximation = 'Kerr-nonlinear cavity effective single-mode model; SNAIL/STS-SQUID adiabatically eliminated.'¶: 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 = False¶: Whether this device represents a computational qubit, as opposed to e.g. a bus resonator or a coupler element.

freq: Scalar = Parameter(default=<object object>, positive=True, nonnegative=False, serialize=True, unit='GHz')¶

kerr: Scalar = Parameter(default=<object object>, positive=False, nonnegative=True, serialize=True, unit='GHz')¶

local_hamiltonian(op)[source]¶

Return \(H = \omega \hat{n} - K \hat{n}(\hat{n} - I)\).

The Kerr term \(\hat{n}(\hat{n}-I) = \hat{n}^2 - \hat{n}\) gives eigenvalue contributions \(-K n(n-1)\) for the \(n\)-photon Fock state.

Returns:: Declarative expression for the Hermitian operator H = omega*n - K*n*(n-1) (GHz), diagonal in the Fock basis.
Return type:: PhysicsExpr
Parameters:: op (LocalOps)

physics_notes()[source]¶

Return declared Kerr-cavity approximation notes.

Return type:: list[str]

class quchip.devices.PhaseCoupled(*args, **kwargs)[source]¶

Bases: Protocol

Device exposes the physical phase-space coupling operator.

Returns \(V^\dagger \sin\hat\varphi V\) on a charge-basis transmon (where \(\hat\varphi\) is not single-valued in the integer charge basis) or \(V^\dagger \hat\varphi V\) on a fluxonium (where \(\hat\varphi\) is well-defined). Used by PhaseDrive.

phase_coupling_operator()[source]¶

Return the physical phase-space coupling operator in the eigenbasis.

Return type:: Any

class quchip.devices.Resonator(freq, quality_factor=None, *, levels=10, label=None, T1=None, T2=None, thermal_population=None)[source]¶

Bases: DeviceModel

Linear microwave / photonic resonator — pure harmonic oscillator.

Parameters:

freq (float) – Bare cavity frequency ω in GHz. Must be positive. May be a JAX tracer for sweeps / gradients.
quality_factor (float | None, optional) – Loaded Q, defined against the ordinary frequency freq (GHz). When set, adds a photon-loss Lindblad channel sqrt(2*pi*freq/Q) a — i.e. decay rate kappa = 2*pi*freq/Q (angular, rad/ns). The 2*pi here is part of the physical definition of Q (energy e-folds per ordinary cycle divided by Q), not a units-boundary conversion. Must be positive. Like every noise parameter it may be set — or cleared with None — after construction; the next simulate reflects the current value.
levels (int, default 10) – Fock-space truncation. Choose comfortably above the maximum expected photon occupation.
label (str | None, default None) – If omitted, auto-generated as resonator_{idx} via the shared labeling counter.
**noise_kwargs – Forwarded verbatim to BaseDevice — T1, T2, thermal_population.

Example

>>> from quchip.devices import Resonator
>>> r = Resonator(freq=7.2, quality_factor=10_000, levels=8)
>>> len(r.collapse_operators()) >= 1
True

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.

freq: Scalar = Parameter(default=<object object>, positive=True, nonnegative=False, serialize=True, unit='GHz')¶

quality_factor: Scalar = Parameter(default=None, positive=True, nonnegative=False, serialize=True, unit=None)¶

approximation = 'Linear harmonic oscillator with no Kerr or cross-Kerr self-interaction.'¶: 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.

local_hamiltonian(op)[source]¶

Return the harmonic oscillator Hamiltonian H = freq * n.

Parameters:: op (LocalOps)
Return type:: PhysicsExpr

physics_notes()[source]¶

Return declared harmonic-oscillator and dissipation assumptions.

Return type:: list[str]

intrinsic_decay_rate()[source]¶

Combined lowering-channel rate: κ = 2π·freq/Q photon loss plus the thermal-emission rate.

Both quality_factor and T1/thermal_population build independent lowering-operator collapse channels on this device (the photon_loss NoiseChannel, a pure loss channel unaffected by thermal_population, and the inherited thermal-emission channel — see intrinsic_decay_rate() for its (n̄+1)/T1 / n̄+1 formulas); this hook reports their summed rate rather than either alone, so a caller reading one scalar decay rate (e.g. an adiabatic-elimination Purcell fold) does not under-count decay when both are set. None only when neither is set.

Return type:: Any | None

Modules

`base`	Base device model for quchip.
`circuit`	CircuitDevice — shared base for diagonalize/truncate/project device models.
`fluxonium`	Fluxonium — phase-basis fluxonium qubit model.
`kerr_cavity`	KerrCavity — Kerr-nonlinear resonator model.
`protocols`	Runtime-checkable Protocols for physical-operator drive dispatch.
`resonator`	Linear-resonator device model.
`transmon`	Transmon device models.