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

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

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

Return type:

list[str]

to_dict()

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

Return type:

dict[str, Any]

classmethod from_dict(d)

Reconstruct an EigenbasisDevice from to_dict() output.

Parameters:

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

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	EigenbasisDevice — exact-lane device wrapping constant eigenbasis data.
scqubits	scqubits interoperability — from_scqubits / to_scqubits dispatch.