quchip.devices.resonator

Linear-resonator device model.

Hamiltonian:

\[H = \omega \, \hat{n}\]

where \(\hat{n} = a^\dagger a\) is the Fock-basis number operator and \(\omega\) is the bare cavity frequency.

Approximation

Strictly harmonic / non-interacting: no Kerr, no cross-Kerr, no drive backaction other than what couplings/drives themselves introduce. It models the ideal cavity / transmission-line-resonator mode and applies to readout cavities, filter modes, photonic oscillators, and cavity-QED benchmarks, where anharmonicity is absent or modelled separately. For Kerr / anharmonic cavities, use a device that owns an explicit (K/2) n(n-1) term (see examples/kerr_cat_qubit.py).

Optional dissipation

If you pass internal_quality_factor = Q, the device adds a single unobserved photon-loss collapse operator sqrt(kappa) a with \(\kappa = 2\pi\,f/Q\) (energy-decay rate, 1/ns).

Quality-factor convention (physics, not a unit conversion). internal_quality_factor is defined against this class’s ordinary frequency freq (GHz), which gives the decay rate \(\kappa = 2\pi\,f/Q\) (energy decay, 1/ns). The \(2\pi\) here is intrinsic to the physical definition of Q, not an ordinary→angular units conversion at the engine boundary. Q/(2*pi) is the number of ordinary-frequency cycles per e-folding of energy, so energy decays as \(e^{-t/\tau} = e^{-\kappa t}\) with \(\kappa = \omega/Q = 2\pi f/Q\).

Noise hooks inherited from BaseDevice (T1, T2, thermal_occupation) produce the Lindblad channels described in that base class. For circuit-QED conventions see Krantz et al., Applied Physics Reviews 6, 021318 (2019), §V.

References

• Walls & Milburn, Quantum Optics, 2nd ed. (Springer, 2008), Ch. 7.

• Blais, Grimsmo, Girvin & Wallraff, Circuit quantum electrodynamics, Reviews of Modern Physics 93, 025005 (2021).

Example

>>> from quchip.chip import Chip
>>> from quchip.devices import Resonator
>>> r = Resonator(freq=7.2, levels=6, label="readout")
>>> chip = Chip(devices=[r])
>>> r.freq, r.levels
(7.2, 6)

Classes

Resonator([freq, levels, label, T1, T2, ...])

Linear microwave / photonic resonator (pure harmonic oscillator).

class quchip.devices.resonator.Resonator(freq=unbound, *, levels=10, label=None, T1=None, T2=None, thermal_occupation=None, internal_quality_factor=None)

Bases: FockDevice

Linear microwave / photonic resonator (pure harmonic oscillator).

Parameters:

• freq (float) – Bare cavity frequency ω in GHz. Must be positive. Can 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, it adds a photon-loss Lindblad channel sqrt(2*pi*freq/Q) a with energy-decay rate kappa = 2*pi*freq/Q in 1/ns. Must be positive. Like every noise parameter, it can be set after construction or cleared with None, and the next simulation uses the current value.

• levels (int, default 10) – Fock-space truncation. Choose it well above the maximum expected photon occupation.

• label (str | None, default None) – If omitted, the label is resonator_{idx} with the shared labeling counter.

• T1 (float or None, default None) – Energy-relaxation time in ns. None disables T1 relaxation.

• T2 (float or None, default None) – Total 0-1 coherence time in ns. If both are set, T2 <= 2*T1.

• thermal_occupation (float or None, default None) – Dimensionless mean bath occupation. None disables absorption.

References

Blais et al., Rev. Mod. Phys. 93, 025005 (2021), https://doi.org/10.1103/RevModPhys.93.025005.

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

Parameters eligible for inverse design. DeviceModel derives these from declared fields unless the class or an ancestor supplies a tuple. Explicit tuples remain authoritative when inherited; an empty tuple excludes the device from inverse design. Plain BaseDevice subclasses default to an empty tuple without derivation.

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)

Return the harmonic oscillator Hamiltonian H = freq * n.

Parameters:

• op (LocalOps) – Fock operator namespace.

• p (ParameterNamespace) – Symbolic freq value.

dissipation(op, p)

Return device-local Lindblad channels.

Parameters:

• op (LocalOps) – Local operator namespace.

• p (ParameterNamespace) – Symbolic declared parameters.

• T1 (The base channels implement)

• T2

• Subclasses (and thermal occupation.)

• ``super().dissipation(op (may append channels with) –

• p)``.

physics_notes()

Return declared harmonic-oscillator and dissipation assumptions.

intrinsic_decay_rate()

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

Both internal_quality_factor and T1/thermal_occupation build independent lowering-operator collapse channels on this device. The first is the internal_photon_loss channel, a pure loss channel that thermal_occupation does not affect. The second is the inherited thermal-emission channel. See intrinsic_decay_rate() for its (n̄+1)/T1 / n̄+1 formulas. This hook reports their summed rate, not either rate alone. A caller that reads one scalar decay rate, e.g. an adiabatic-elimination Purcell fold, then does not under-count decay when both are set. None only when neither is set.