quchip.devices.transmon

Transmon device models.

• DuffingTransmon — weakly anharmonic Duffing approximation (valid in the transmon regime \(E_J \gg E_C\); Koch et al. PRA 76, 042319 (2007)).

• FluxTunableTransmon — SQUID-dispersion flux-tunable transmon (symmetric or asymmetric), suitable for parametric/flux-driven operations and tunable couplers. Inherits from BaseDevice directly; constructor takes physical dressed parameters.

• ChargeBasisTransmon — exact charge-basis diagonalization; captures charge-dispersion with \(n_g\) outside the deep transmon regime.

class quchip.devices.transmon.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)

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)

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

local_space()

Return the authored integer-charge space.

Return type:

ChargeSpace

local_hamiltonian(op, p)

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

Parameters:

• op (LocalOps)

• p (Any)

Return type:

PhysicsExpr

property freq: Any

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

eigenenergies()

Return isolated energies shifted to zero at the ground state.

Return type:

Any

eigenvectors()

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

Return type:

Any

charge_coupling_operator()

Return the authored charge operator.

Return type:

Any

phase_coupling_operator()

Return sin(phi) in the authored charge basis.

Return type:

Any

tunable_param_bounds(name, value)

Return the physical charge period for n_g.

Parameters:

• name (str)

• value (float)

Return type:

tuple[float, float]

physics_notes()

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)

Construct from the leading transmon-regime inversion.

Parameters:

• freq (float)

• anharmonicity (float)

• n_g (float)

• levels (int | None)

• label (str | None)

• num_basis (int)

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

• kwargs (Any)

Return type:

ChargeBasisTransmon

to_dict()

Serialize common device state plus declared parameter values.

Return type:

dict[str, Any]

classmethod from_dict(data)

Reconstruct the device from to_dict() output.

Parameters:

data (dict[str, Any])

Return type:

ChargeBasisTransmon

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

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)

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

Parameters:

• op (LocalOps)

• p (Any)

Return type:

PhysicsExpr

physics_notes()

Return declared Duffing-approximation validity notes.

Return type:

list[str]

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

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

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

Return type:

None

set_parameter_values(values)

Apply flux and calibration overrides without mapping-order effects.

Parameters:

values (Mapping[str, Any])

Return type:

None

tunable_param_bounds(name, value)

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

Parameters:

• name (str)

• value (float)

Return type:

tuple[float, float]

local_hamiltonian(op, p)

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:

• op (LocalOps)

• p (Any)

Return type:

PhysicsExpr

frequency_at(flux)

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)

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

Return declared SQUID-transmon calibration-anchor assumptions.

Return type:

list[str]

Modules

charge_basis	Transmon authored in a finite integer-charge basis.
duffing	Duffing-approximation transmon qubit.
flux_tunable	Symmetric/asymmetric-SQUID flux-tunable transmon.