quchip.interop.base

Library-agnostic registry and dispatch for third-party model mappings.

A ModelMapping subclass authors a one-directional or bidirectional conversion between a third-party circuit-QED object and a quchip device. Subclasses register at class-definition time, keyed by the third-party type they import from, the (library, quchip type) pair they export to, or both. Concrete mappings (e.g. for scqubits) live in sibling modules that import both sides.

Functions

export_object(device, library, **opts)

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

import_object(obj, **opts)

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

registered_mappings()

Return a copy of the import registry, keyed by source key.

source_key(tp)

Return the registry key for third-party type tp.

Classes

ModelMapping()

Base class for a single third-party <-> quchip device conversion.
quchip.interop.base.source_key(tp)[source]

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 a mapping registered against a package root matches classes re-exported from submodules.

Parameters:

tp (type) – Third-party class to identify.

Returns:

Top-level module and qualified class name separated by a dot.

Return type:

str

class quchip.interop.base.ModelMapping[source]

Bases: object

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

Variables:

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

  • target (type or None) – quchip device type this mapping exports to. Required when export_model() is overridden. None means import-only.

  • library (str or None) – 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.

  • automatically (Subclassing registers the mapping)

:ivar * setting source registers it for import_object() under that: key. A second subclass that reuses the same source raises

TypeError at class-definition time.

:ivar * overriding export_model() registers it for export_object(): under (library, target). An override without target, or without a

resolvable library (no source to default it from), raises TypeError. A second subclass that reuses the same (library, target) pair raises TypeError naming both classes.

Variables:

  • export_model (The abstract base itself (source is None and no)

  • nothing. (override) registers)

source: ClassVar[str | None] = None
target: ClassVar[type | None] = None
library: ClassVar[str | None] = None
import_model(obj, **opts)[source]

Convert third-party object obj into a quchip device.

Override to support import. The base implementation raises NotImplementedError.

Parameters:

  • obj (object) – Third-party instance to convert.

  • **opts (Any) – Mapping-specific keyword options. Subclasses must document supported keys.

Returns:

Converted quchip model, as defined by the subclass.

Return type:

object

export_model(device, **opts)[source]

Convert quchip device into a third-party object.

Override to support export, and also set target. The base implementation raises NotImplementedError.

Parameters:

  • device (object) – quchip device to convert.

  • **opts (Any) – Mapping-specific keyword options. Subclasses must document supported keys.

Returns:

Converted third-party model, as defined by the subclass.

Return type:

object

quchip.interop.base.import_object(obj, **opts)[source]

Import third-party obj into a quchip device through 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 a skeleton for authoring a new ModelMapping.

Parameters:

  • obj (object) – Third-party object whose type selects the registered mapping.

  • **opts (Any) – Keywords forwarded unchanged to the mapping’s conversion method, which documents supported keys and defaults.

Returns:

Converted quchip model.

Return type:

object

quchip.interop.base.export_object(device, library, **opts)[source]

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 (BaseDevice) – Device whose type selects the registered mapping.

  • library (str) – Registered target library, such as "scqubits".

  • **opts (Any) – Keywords forwarded unchanged to the mapping’s conversion method, which documents supported keys and defaults.

Returns:

Converted third-party object.

Return type:

object

quchip.interop.base.registered_mappings()[source]

Return a copy of the import registry, keyed by source key.

Changing the returned dict does not affect the registration state.