quchip.chip.coupling_base

Coupling base class and registry.

Classes

BaseCoupling(device_a, device_b, *[, label])

Abstract base for a two-body coupling between :class:`BaseDevice`s.

class quchip.chip.coupling_base.BaseCoupling(device_a, device_b, *, label=None)

Bases: StateVersioned, Registrable, ABC

Abstract base for a two-body coupling between :class:`BaseDevice`s.

Subclasses own their local interaction Hamiltonian H_int on H_a ⊗ H_b. The engine embeds this local form into the full chip tensor space, and couplings never use the engine directly.

Subclasses register automatically through the shared Registrable mixin, without a manual registration step. Import the module that defines the subclass so that the registration runs.

Parameters:

• device_a (BaseDevice or str) – The two coupled devices. Label strings are late-bound: the coupling keeps the string, and Chip resolves it to the matching device instance at construction time. Until then, the coupling cannot build an interaction Hamiltonian.

• device_b (BaseDevice or str) – The two coupled devices. Label strings are late-bound: the coupling keeps the string, and Chip resolves it to the matching device instance at construction time. Until then, the coupling cannot build an interaction Hamiltonian.

• label (str, optional) – Human-readable label. If omitted, quchip derives it from _type_prefix (e.g. "cap_0" for Capacitive).

Notes

All coupling parameters (g, any tunable envelope, and others) must be JAX-traceable, so sweeps and gradient-based optimization work without forced concretization.

reduces_to_crosskerr: ClassVar[bool] = False

default_fit_observable: ClassVar[str] = 'coupling_strength'

Observable represented by this coupling’s declared scalar when the enclosing chip is passed to fit_a_dress as a dressed specification. Concrete coupling models override this when their inverse-design quantity is a dressed interaction observable.

copy(device_map)

Copy authored values and rebind endpoints.

Parameters:

device_map (dict[str, BaseDevice]) – Destination devices keyed by label.

parameter_values()

Return this coupling’s bindable values by local field name.

set_parameter_value(name, value)

Apply one local parameter value on an isolated coupling copy.

Parameters:

• name (str) – Local parameter name.

• value (Any) – Replacement value in the parameter’s declared units.

property device_a_label: str

Label of the first coupled device (works before and after binding).

property device_b_label: str

Label of the second coupled device (works before and after binding).

property is_resolved: bool

True if both device references are bound to BaseDevice instances.

abstract property coupling_strength: float

Scalar coupling strength in GHz.

property coupling_strength_name: str

Display name of the scalar coupling_strength parameter.

The default is "g", the conventional coupling-strength symbol and the attribute name on Coupling. CouplingModel overrides it with the name of its first declared parameter field. A subclass with a different primary-scalar convention overrides it directly.

set_coupling_strength(value)

Write the primary scalar named by coupling_strength_name.

Examples are g, g_0, and chi. Override this method if the writable attribute has a different name.

Parameters:

value (Any) – Coupling strength in GHz.

default_dressed_target()

Return this edge’s component-owned inverse-design constraint.

The method reads the value directly from the declared coupling scalar and does not evaluate a chip-level observable.

abstractmethod interaction_hamiltonian()

Return the full H_int on the local H_a ⊗ H_b subspace.

Couplings author one complete interaction, and the selected engine approximation determines which resolved bands are retained.

physics_notes()

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

dropped_terms()

Return advisory records for terms that this coupling’s own model removes.

The assembly reports RWA band drops generically. This hook is for other approximations that a coupling applies in interaction_hamiltonian(). By default, no terms are dropped.

collapse_channels()

Return the local Lindblad channels that this coupling adds.

to_dict()

Serialize structural fields into a JSON-safe dictionary.