quchip.interop.eigenbasis

A frozen energy-basis device for third-party models without a native quchip model.

Classes

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

Device backed by frozen energies and optional energy-basis operators.

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)

Bases: BaseDevice

Device backed by frozen energies and optional energy-basis operators.

This is the narrow import path for a third-party model that quchip cannot reconstruct from symbolic circuit parameters. Its authored local space is already the source model’s energy basis, so normal engine materialization applies without a device-owned diagonalization or projection path.

Parameters:

• energies (Any)

• charge_operator (Any | None)

• phase_operator (Any | None)

• levels (int | None)

• label (str | None)

• source_type (str | None)

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

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

• collapse_rate_threshold (float)

• noise (Any)

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

dissipation(op, p)

Return the common T1, T2, and thermal device channels.

Parameters:

• op (Any)

• p (Any)

Return type:

tuple[CollapseChannel, …]

unresolved_hamiltonian()

Return the frozen source spectrum as the authored Hamiltonian.

Return type:

PhysicsExpr

property freq: Any

Return the stored zero-to-one transition in GHz.

eigenenergies()

Return the stored ground-shifted energy table.

Return type:

Any

eigenvectors()

Return the identity map because the authored basis is energy ordered.

Return type:

Any

charge_coupling_operator()

Return the supplied charge-like operator in the authored basis.

Return type:

Any

phase_coupling_operator()

Return the supplied phase-like operator in the authored basis.

Return type:

Any

physics_notes()

Return human-readable declarations of this device’s approximations.

Each entry names a non-obvious assumption, approximation, or truncation that a user of this device should be aware of — e.g. “Hilbert truncation: 3 levels”, a model regime (Duffing), or a noise-channel selection (charge- vs flux-coupled T1).

The baseline entry is _truncation_note(), since every BaseDevice has some form of Hilbert-space truncation. A pure-dephasing note is added when T2 is set, since the number-operator dephasing model carries non-obvious assumptions. Subclasses super().physics_notes() and append their own model-specific notes; no registry / engine-side dispatch is needed.

Return type:

list[str]

to_dict()

JSON-safe serialization; subclasses extend with their own parameters.

Return type:

dict[str, Any]

classmethod from_dict(data)

Reconstruct from to_dict() output.

On the registry root, dispatch to the concrete subclass named by data["type"] (forwarding *args / **kwargs). On a concrete subclass, defer to _from_dict_payload(). Concrete subclasses that carry payload override this method directly.

Parameters:

data (dict[str, Any])

Return type:

EigenbasisDevice