quchip.interop.eigenbasis

EigenbasisDevice — exact-lane device wrapping constant eigenbasis data.

A third-party circuit-QED model (e.g. an scqubits ZeroPi or Fluxonium) computes its own eigenenergies and coupling-operator matrix elements in its own native basis and diagonalization routine. EigenbasisDevice takes that already-diagonalized data — energies and, optionally, the charge and phase operator matrices expressed in the eigenbasis — and treats it as a CircuitDevice whose native basis happens to already be diagonal. _eigensys() then diagonalizes a diagonal matrix (a no-op beyond sorting and truncation), so every inherited mechanism — truncation, drive-operator projection, Fermi-golden-rule collapse channels, serialization — applies unchanged, with no native-basis machinery of its own to maintain.

The snapshot is exact at the parameter point it was computed at and frozen from then on: EigenbasisDevice stores plain numbers, not a recipe for recomputing them from underlying circuit parameters, so it is not differentiable with respect to whatever generated it. See EigenbasisDevice.physics_notes().

Example

>>> import numpy as np
>>> from quchip.interop.eigenbasis import EigenbasisDevice
>>> E = np.array([0.0, 5.1, 9.8])
>>> n = np.array([[0, 1.0, 0], [1.0, 0, 1.3], [0, 1.3, 0]], dtype=complex)
>>> q = EigenbasisDevice(E, charge_operator=n, source_type="scqubits.Fluxonium")
>>> float(q.freq)
5.1

Classes

EigenbasisDevice(energies, *[, ...])

Device wrapping constant eigenenergies and eigenbasis operator matrices.
class quchip.interop.eigenbasis.EigenbasisDevice(energies, *, charge_operator=None, phase_operator=None, levels=None, label=None, source_type=None, collapse_model='fermi_golden', coupling_channel=None, collapse_rate_threshold=1e-08, **noise_kwargs)[source]

Bases: CircuitDevice

Device wrapping constant eigenenergies and eigenbasis operator matrices.

Parameters:

  • energies (array_like) – 1-D array of eigenenergies, any offset (stored ground-shifted so \(E_0 = 0\)). Length sets the native-basis dimension.

  • charge_operator (array_like, optional) – Charge-like coupling operator \(\hat n\), expressed in the same eigenbasis as energies, shape (len(energies), len(energies)). Omit if the source model has no charge-like operator to hand over.

  • phase_operator (array_like, optional) – Phase-like coupling operator, expressed in the same eigenbasis as energies, same shape convention as charge_operator.

  • levels (int, optional) – Truncated eigenbasis size. Defaults to len(energies); must not exceed it.

  • label (str or None)

  • source_type (str or None) – Free-form identifier of the originating third-party model (e.g. "scqubits.ZeroPi"), surfaced in physics_notes() and preserved through serialization. Purely descriptive.

  • collapse_model (see) – CircuitDevice.

  • coupling_channel (see) – CircuitDevice.

  • collapse_rate_threshold (see) – CircuitDevice.

  • **noise_kwargs – Forwarded to BaseDevice.

Raises:

ValueError – If levels exceeds len(energies), or if charge_operator / phase_operator is supplied with the wrong shape.

Notes

Since the eigenbasis is the native basis here, _native_charge_operator and _native_phase_operator return the stored matrix directly (or raise if it was never supplied, at the point a drive first asks for it) rather than computing one from circuit parameters.

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

physics_notes()[source]

Return declared assumptions, including the frozen-import snapshot note.

Return type:

list[str]

to_dict()[source]

Extend CircuitDevice.to_dict() with the eigenbasis snapshot data.

Return type:

dict[str, Any]

classmethod from_dict(d)[source]

Reconstruct an EigenbasisDevice from to_dict() output.

Parameters:

d (dict[str, Any]) – Dict produced by to_dict().

Return type:

EigenbasisDevice