quchip.interop

Third-party model interoperability: ModelMapping authoring surface and registry.

This package is the library-agnostic foundation for converting circuit-QED models to and from quchip devices. Concrete mappings for specific libraries (e.g. scqubits) live in sibling modules and import both sides; this module never does.

class quchip.interop.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

class quchip.interop.ModelMapping

Bases: object

Base class for a single third-party <-> quchip device conversion.

source

Registry key (see source_key()) of the third-party type this mapping imports from. None means the mapping supports export only.

Type:

str or None

target

The quchip device type this mapping exports to. Required whenever export_model() is overridden; None means import-only.

Type:

type or None

library

Name of the third-party library this mapping exports for. Defaults to source.split(".")[0] when source is set; export-only mappings must set it explicitly.

Type:

str or None

Subclassing registers the mapping automatically

\* setting ``source`` registers it for :func:`import_object` under that

key; a second subclass reusing the same source raises TypeError at class-definition time.

\* overriding :meth:`export_model` registers it for :func:`export_object`

under (library, target); overriding without setting target raises TypeError, overriding without a resolvable library (no source to default it from) raises TypeError, and a second subclass reusing the same (library, target) pair raises TypeError naming both classes.

The abstract base itself (``source is None`` and no ``export_model``

override) registers nothing.

source: ClassVar[str | None] = None

target: ClassVar[type | None] = None

library: ClassVar[str | None] = None

import_model(obj, **opts)

Convert third-party object obj into a quchip device.

Override to support import. The base implementation raises NotImplementedError.

Parameters:

• obj (Any)

• opts (Any)

Return type:

Any

export_model(device, **opts)

Convert quchip device into a third-party object.

Override to support export; overriding requires setting target. The base implementation raises NotImplementedError.

Parameters:

• device (Any)

• opts (Any)

Return type:

Any

quchip.interop.export_object(device, library, **opts)

Export quchip device to a third-party object of library.

Walks type(device).__mro__ and dispatches to the first ModelMapping registered under (library, that class).

Raises:

LookupError – No mapping is registered for (library, type(device)) or any base class. The message lists the device types library can export.

Parameters:

• device (Any)

• library (str)

• opts (Any)

Return type:

Any

quchip.interop.import_object(obj, **opts)

Import third-party obj into a quchip device via a registered mapping.

Walks type(obj).__mro__ and dispatches to the first ModelMapping registered under that class’s source_key().

Raises:

LookupError – No mapping is registered for type(obj) or any of its base classes. The message names the missing source key and shows the skeleton for authoring a new ModelMapping.

Parameters:

• obj (Any)

• opts (Any)

Return type:

Any

quchip.interop.source_key(tp)

Return the registry key for third-party type tp.

The key is the type’s top-level module name joined with its qualified name, e.g. "scqubits.Transmon". Only the top-level module is used so that a mapping registered against a package root matches classes re-exported from submodules.

Parameters:

tp (type)

Return type:

str

Modules

base	Library-agnostic registry and dispatch for third-party model mappings.
eigenbasis	A frozen energy-basis device for third-party models without a native quchip model.
scqubits	scqubits interoperability — from_scqubits / to_scqubits dispatch.