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

  • Fluxonium — circuit-level fluxonium in the phase basis.

  • ChargeBasisTransmon — circuit-level transmon in the integer charge basis.

Coupling Protocols (for drive dispatch)

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

Bases: DeviceModel

Transmon with its Hamiltonian authored in the integer-charge basis.

Parameters:

  • E_C (Scalar)

  • E_J (Scalar)

  • n_g (Scalar)

  • levels (int | None)

  • label (str | None)

  • num_basis (int)

  • basis (Literal['native', 'eigen'] | None)

  • collapse_model (Literal['fermi_golden', 'ladder'])

  • coupling_channel (Literal['charge'] | None)

  • collapse_rate_threshold (float)

  • noise (Any)

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 a finite integer-charge basis; accuracy is governed by num_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.

computational = True

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

requires_projection_levels: ClassVar[bool] = True
structural_setting_names = ('num_basis', 'basis', 'projection_levels', 'collapse_model', 'coupling_channel', 'collapse_rate_threshold')
E_C: Scalar = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='E_C', noise=False, kw_only=False, required=False)
E_J: Scalar = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='E_J', noise=False, kw_only=False, required=False)
n_g: Scalar = Parameter(default=0.0, positive=False, nonnegative=False, serialize=True, unit=None, symbol='n_g', noise=False, kw_only=False, 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:
Return type:

tuple[CollapseChannel, …]

local_space()[source]

Return the authored integer-charge space.

Return type:

ChargeSpace

local_hamiltonian(op, p)[source]

Return 4 E_C (n - n_g)^2 - E_J cos(phi).

Parameters:
Return type:

PhysicsExpr

property freq: Any

Return the isolated 0-to-1 transition in GHz.

eigenenergies()[source]

Return isolated energies shifted to zero at the ground state.

Return type:

Any

eigenvectors()[source]

Return the isolated energy-ordered eigenvectors in the charge basis.

Return type:

Any

charge_coupling_operator()[source]

Return the authored charge operator.

Return type:

Any

phase_coupling_operator()[source]

Return sin(phi) in the authored charge basis.

Return type:

Any

tunable_param_bounds(name, value)[source]

Return the physical charge period for n_g.

Parameters:
Return type:

tuple[float, float]

physics_notes()[source]

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

Return type:

list[str]

classmethod from_frequency(freq, anharmonicity, n_g=0.0, levels=None, label=None, *, num_basis=61, basis=None, **kwargs)[source]

Construct from the leading transmon-regime inversion.

Parameters:
Return type:

ChargeBasisTransmon

to_dict()[source]

Serialize common device state plus declared parameter values.

Return type:

dict[str, Any]

classmethod from_dict(data)[source]

Reconstruct the device from to_dict() output.

Parameters:

data (dict[str, Any])

Return type:

ChargeBasisTransmon

class quchip.devices.ChargeSpace(num_basis)[source]

Bases: LocalSpace

Finite integer-charge basis centered on zero charge.

Parameters:

num_basis (int)

num_basis: int
property dimension: int

Return the authored local-space dimension.

matrix(name)[source]

Return one named operator as a JAX-compatible dense array.

Parameters:

name (str)

Return type:

Any

class quchip.devices.CustomSpace(dimension, operators)[source]

Bases: LocalSpace

Named local operators supplied as matrices or zero-argument JAX callables.

Parameters:

  • dimension (int)

  • operators (Mapping[str, Any])

property dimension: int

Return the authored local-space dimension.

matrix(name)[source]

Return one named operator as a JAX-compatible dense array.

Parameters:

name (str)

Return type:

Any

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

Bases: Protocol

Device exposes the physical charge operator in its authored local basis.

ChargeDrive dispatches against this Protocol and emits drives using charge_coupling_operator().

charge_coupling_operator()[source]

Return the physical charge operator in the authored local basis.

Return type:

Any

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

Bases: FockDevice

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

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

dressed_fit_target_fields = (('freq', 'freq'), ('anharmonicity', 'anharmonicity'))

(dressed_observable, declared_field) pairs used when this device appears in the desired-chip form of fit_a_dress. Empty means that the model makes no automatic dressed-target claim; circuit-level models can remain fixed until the user supplies explicit constraints.

dressed_fit_param_names = ('freq', 'anharmonicity')

Bare parameters normally varied to reproduce dressed_fit_target_fields. This remains separate from tunable_param_names: a model may expose parameters for sweeps without claiming that inverse design can identify all of them from its default dressed observables.

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=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='\\omega', noise=False, kw_only=False, required=False)
anharmonicity: Scalar = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='\\alpha', noise=False, kw_only=False, required=False)
local_hamiltonian(op, p)[source]

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

Parameters:
Return type:

PhysicsExpr

physics_notes()[source]

Return declared Duffing-approximation validity notes.

Return type:

list[str]

class quchip.devices.FockDevice(*, levels=2, label=None, **params)[source]

Bases: DeviceModel

Device with explicit conventional oscillator coupling operators.

Subclasses still own their Hamiltonian and approximation. This base only declares the standard Fock-space operators used by charge, phase, and frequency-modulating drives.

Parameters:

  • levels (int)

  • label (str | None)

  • params (Any)

abstractmethod local_hamiltonian(op, p)[source]

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

Parameters:
Return type:

PhysicsExpr

charge_coupling_operator()[source]

Return the conventional charge quadrature i(a - a†).

Return type:

PhysicsExpr

phase_coupling_operator()[source]

Return the conventional phase quadrature a + a†.

Return type:

PhysicsExpr

flux_coupling_operator()[source]

Return the number operator used for frequency modulation.

Return type:

PhysicsExpr

tunable_param_names = ()

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.devices.FockSpace(levels)[source]

Bases: LocalSpace

Finite Fock ladder with the standard bosonic and qubit operators.

Parameters:

levels (int)

levels: int
property dimension: int

Return the authored local-space dimension.

matrix(name)[source]

Return one named operator as a JAX-compatible dense array.

Parameters:

name (str)

Return type:

Any

operator(name, backend)[source]

Lower one named local operator through backend.

Parameters:
Return type:

Any

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

Bases: Protocol

Device exposes the physical flux-line coupling operator.

For a fluxonium this is \(\hat\varphi\). Used by FluxDrive.

flux_coupling_operator()[source]

Return the physical flux-line coupling operator in the authored basis.

Return type:

Any

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

Bases: FockDevice

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) – Current operating point Φ/Φ₀ and calibration-anchor coordinate. 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()). Rebinding this value alone preserves the inferred SQUID calibration and updates freq. Rebinding it together with freq defines a new anchor. It is a JAX pytree leaf and can be differentiated or swept through the public chip API.

  • 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', 'flux_bias')

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

dressed_fit_target_fields = (('freq', 'freq'), ('anharmonicity', 'anharmonicity'))

(dressed_observable, declared_field) pairs used when this device appears in the desired-chip form of fit_a_dress. Empty means that the model makes no automatic dressed-target claim; circuit-level models can remain fixed until the user supplies explicit constraints.

dressed_fit_param_names = ('freq', 'anharmonicity')

Bare parameters normally varied to reproduce dressed_fit_target_fields. This remains separate from tunable_param_names: a model may expose parameters for sweeps without claiming that inverse design can identify all of them from its default dressed observables.

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=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='\\omega', noise=False, kw_only=False, required=False)
anharmonicity: Scalar = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='\\alpha', noise=False, kw_only=False, required=False)
flux_bias: Scalar = Parameter(default=0.0, positive=False, nonnegative=False, serialize=True, unit='Phi_0', symbol='\\Phi', noise=False, kw_only=False, required=False)
asymmetry: Scalar = Parameter(default=0.0, positive=False, nonnegative=False, serialize=True, unit=None, symbol='d', noise=False, kw_only=False, required=False)
validate()[source]

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

Return type:

None

set_parameter_values(values)[source]

Apply flux and calibration overrides without mapping-order effects.

Parameters:

values (Mapping[str, Any])

Return type:

None

tunable_param_bounds(name, value)[source]

Use one SQUID period as the default bound for explicit flux fitting.

Parameters:
Return type:

tuple[float, float]

local_hamiltonian(op, p)[source]

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

H = ω n + (α/2) n(n − I). Rebinding flux_bias first updates the stored freq through the anchored SQUID dispersion.

Parameters:
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=None, label=None, *, num_basis=400, phi_max=15.707963267948966, basis=None, collapse_model='fermi_golden', coupling_channel=None, collapse_rate_threshold=1e-08, **noise)[source]

Bases: DeviceModel

Fluxonium with its Hamiltonian authored in a finite phase-grid basis.

Parameters:

  • E_C (Scalar)

  • E_J (Scalar)

  • E_L (Scalar)

  • phi_ext (Scalar)

  • levels (int | None)

  • label (str | None)

  • num_basis (int)

  • phi_max (float)

  • basis (Literal['native', 'eigen'] | None)

  • collapse_model (Literal['fermi_golden', 'ladder'])

  • coupling_channel (Literal['charge', 'flux'] | None)

  • collapse_rate_threshold (float)

  • noise (Any)

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

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 = 'Finite phase-grid model with a second-order charge kinetic operator; accuracy is governed by num_basis and phi_max.'

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.

requires_projection_levels: ClassVar[bool] = True
structural_setting_names = ('num_basis', 'phi_max', 'basis', 'projection_levels', 'collapse_model', 'coupling_channel', 'collapse_rate_threshold')
E_C: Scalar = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='E_C', noise=False, kw_only=False, required=False)
E_J: Scalar = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='E_J', noise=False, kw_only=False, required=False)
E_L: Scalar = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='E_L', noise=False, kw_only=False, required=False)
phi_ext: Scalar = Parameter(default=0.0, positive=False, nonnegative=False, serialize=True, unit=None, symbol='\\varphi_{\\mathrm{ext}}', noise=False, kw_only=False, 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:
Return type:

tuple[CollapseChannel, …]

local_space()[source]

Return the authored finite phase-grid space.

Return type:

PhaseGridSpace

local_hamiltonian(op, p)[source]

Return the native fluxonium Hamiltonian in ordinary GHz.

Parameters:
Return type:

PhysicsExpr

property freq: Any

Return the isolated 0-to-1 transition in GHz.

eigenenergies()[source]

Return isolated energies shifted to zero at the ground state.

Return type:

Any

eigenvectors()[source]

Return the isolated energy-ordered phase-grid eigenvectors.

Return type:

Any

charge_coupling_operator()[source]

Return the authored charge operator.

Return type:

Any

phase_coupling_operator()[source]

Return the authored phase operator.

Return type:

Any

flux_coupling_operator()[source]

Return the authored flux-line phase operator.

Return type:

Any

physics_notes()[source]

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

Return type:

list[str]

to_dict()[source]

Serialize common device state plus declared parameter values.

Return type:

dict[str, Any]

classmethod from_dict(data)[source]

Reconstruct the device from to_dict() output.

Parameters:

data (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=unbound, kerr=unbound, *, levels=30, label=None, T1=None, T2=None, thermal_population=None)[source]

Bases: FockDevice

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

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 = '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=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='\\omega', noise=False, kw_only=False, required=False)
kerr: Scalar = Parameter(default=unbound, positive=False, nonnegative=True, serialize=True, unit='GHz', symbol='K', noise=False, kw_only=False, required=False)
local_hamiltonian(op, p)[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:
physics_notes()[source]

Return declared Kerr-cavity approximation notes.

Return type:

list[str]

class quchip.devices.LocalSpace[source]

Bases: ABC

Numerical realization of the operators used by one device model.

abstract property dimension: int

Return the authored local-space dimension.

abstractmethod matrix(name)[source]

Return one named operator as a JAX-compatible dense array.

Parameters:

name (str)

Return type:

Any

operator(name, backend)[source]

Lower one named local operator through backend.

Parameters:
Return type:

Any

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

Bases: Protocol

Device exposes the physical phase-space coupling operator.

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

phase_coupling_operator()[source]

Return the physical phase-space coupling operator in the authored basis.

Return type:

Any

class quchip.devices.PhaseGridSpace(points, extent)[source]

Bases: LocalSpace

Uniform endpoint-excluded phase grid with nonperiodic finite differences.

The centered-difference stencil does not wrap across the grid boundary; values beyond either endpoint are treated as zero.

Parameters:
points: int
extent: float
property dimension: int

Return the authored local-space dimension.

matrix(name)[source]

Return one named operator as a JAX-compatible dense array.

Parameters:

name (str)

Return type:

Any

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

Bases: FockDevice

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.

  • internal_quality_factor (float | None, optional) – Internal Q referenced to the ordinary frequency freq in GHz. When set, adds a photon-loss Lindblad channel sqrt(2*pi*freq/Q) a with angular decay rate kappa = 2*pi*freq/Q in rad/ns. Must be positive. Like every noise parameter, it may be set after construction or cleared with None; the next simulation 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, internal_quality_factor=10_000, levels=8)
>>> len(r.collapse_operators()) >= 1
True
tunable_param_names = ('freq',)

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

dressed_fit_target_fields = (('freq', 'freq'),)

(dressed_observable, declared_field) pairs used when this device appears in the desired-chip form of fit_a_dress. Empty means that the model makes no automatic dressed-target claim; circuit-level models can remain fixed until the user supplies explicit constraints.

dressed_fit_param_names = ('freq',)

Bare parameters normally varied to reproduce dressed_fit_target_fields. This remains separate from tunable_param_names: a model may expose parameters for sweeps without claiming that inverse design can identify all of them from its default dressed observables.

freq: Scalar = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='GHz', symbol='\\omega', noise=False, kw_only=False, required=False)
internal_quality_factor: Scalar = Parameter(default=None, positive=True, nonnegative=False, serialize=True, unit=None, symbol=None, noise=True, kw_only=True, required=False)
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, p)[source]

Return the harmonic oscillator Hamiltonian H = freq * n.

Parameters:
Return type:

PhysicsExpr

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:
Return type:

tuple[CollapseChannel, …]

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 internal_quality_factor and T1/thermal_population build independent lowering-operator collapse channels on this device (the internal_photon_loss channel, 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.

fluxonium

Fluxonium authored on a finite phase grid.

fock

Convenience base for devices authored in a truncated Fock space.

kerr_cavity

KerrCavity — Kerr-nonlinear resonator model.

protocols

Runtime-checkable Protocols for physical-operator drive dispatch.

resonator

Linear-resonator device model.

spaces

Backend-neutral local Hilbert spaces and their named operators.

transmon

Transmon device models.