quchip.devices.circuit

CircuitDevice — shared base for diagonalize/truncate/project device models.

Concrete subclasses (fluxonium, charge-basis transmon) implement three methods that live entirely in the native basis (phase grid or integer charge basis):

• _build_native_hamiltonian() — total Hamiltonian in native basis.

• _native_charge_operator() — charge operator \(\hat n\) in native basis.

• _native_phase_operator() — phase-space coupling operator (\(\hat\varphi\) or \(\sin\hat\varphi\) depending on basis) in native basis.

The base class handles:

• JAX-traceable diagonalization (_truncated_eigh(), an eigh whose reverse pass involves only kept-level gaps, so degenerate discarded levels cannot NaN circuit-parameter gradients) cached on the BaseDevice.state_version counter (tracer-safe via quchip.utils.jax_utils.contains_tracer()).

• Truncation to levels lowest eigenstates; spectrum shifted so \(E_0 = 0\).

• project_operator() transforming a native-basis matrix O to \(V^\dagger O V\) in the truncated eigenbasis.

• Physical-coupling accessors (charge_coupling_operator(), phase_coupling_operator()) consumed by drives that dispatch via quchip.devices.protocols.

• Fermi-golden-rule Lindblad channels in collapse_operators().

Init-order contract (subclass discipline)

Subclass __init__ must set all native-Hamiltonian parameters (E_C, E_J, E_L, phi_ext, num_basis, …) before returning, and must not call _eigensys from within __init__. Violating this would cache against a partially-constructed Hamiltonian. The base class enforces this by instantiating lazily: no accessor is called during __init__. Mutation tracking — which gates _validate_param_write() — switches on automatically once the outermost __init__ returns (StateVersioned); subclasses do not call _finish_init by hand.

See docs/superpowers/specs/2026-04-21-circuit-level-devices-design.md.

Classes

CircuitDevice(levels[, label, ...])

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

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

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

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

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

Return type:

Any

eigenvectors()

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

Return type:

Any

project_operator(native_op)

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

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

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

Return declared diagonalization and collapse-model assumptions.

Return type:

list[str]

to_dict()

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

Return type:

dict[str, Any]