quchip.chip.coupling_base

Coupling base class and registry.

Split out of quchip.chip.couplings so the declarative API in quchip.declarative.models can subclass BaseCoupling without re-entering the import chain through Capacitive (Capacitive now itself depends on CouplingModel). The concrete coupling classes — Capacitive, TunableCapacitive, Coupling — still live in quchip.chip.couplings.

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 acting on H_a ⊗ H_b. The engine embeds this local form into the full chip tensor space; couplings never touch the engine directly.

Subclasses auto-register via the shared Registrable mixin — no manual registration step is needed. Ensure the module defining the subclass is imported so the registration runs.

Parameters:

• device_a (BaseDevice or str) – The two coupled devices, given as device objects or their label strings. Label-string references are late-bound: the coupling remembers the string, and Chip resolves it to the matching device instance at construction time. Before that resolution the coupling cannot produce an interaction Hamiltonian.

• device_b (BaseDevice or str) – The two coupled devices, given as device objects or their label strings. Label-string references are late-bound: the coupling remembers the string, and Chip resolves it to the matching device instance at construction time. Before that resolution the coupling cannot produce an interaction Hamiltonian.

• label (str, optional) – Human-readable label. Auto-generated from _type_prefix when omitted (e.g. "cap_0" for Capacitive).

Notes

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

folds_exchange: ClassVar[bool] = False

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)

Shallow copy rebound to the device instances in device_map.

Parameters:

device_map (dict[str, BaseDevice])

Return type:

BaseCoupling

parameter_values()

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

Return type:

dict[str, Any]

set_parameter_value(name, value)

Apply one local parameter value on an isolated coupling copy.

Parameters:

• name (str)

• value (Any)

Return type:

None

property device_a_label: str

Label of the first coupled device (works pre- and post-binding).

property device_b_label: str

Label of the second coupled device (works pre- and post-binding).

property is_resolved: bool

Whether 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.

Default "g" (the conventional coupling-strength symbol, and the actual attribute name on Coupling). CouplingModel overrides this to the name of its first declared parameter field; a subclass with a different primary-scalar convention overrides it directly.

set_coupling_strength(value)

Write value into the scalar named by coupling_strength_name.

The mutation counterpart of coupling_strength: callers that need to move a coupling’s primary scalar (optimizers, sweeps) go through this seam instead of assuming an attribute name (g holds only for Capacitive / Coupling; TunableCapacitive uses g_0, CrossKerr uses chi). Default implementation covers the common case where the writable attribute name matches coupling_strength_name exactly; a subclass whose writable attribute differs from its display name overrides this.

Parameters:

value (Any)

Return type:

None

default_dressed_target()

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

The value is read directly from the declared coupling scalar. No chip-level observable is evaluated here.

Return type:

tuple[str, Any]

abstractmethod interaction_hamiltonian()

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

Couplings author one complete interaction. The selected engine approximation decides which resolved bands are retained.

Return type:

Any

physics_notes()

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

Return type:

list[str]

dropped_terms()

Return advisory records for terms this coupling’s model itself elides.

RWA band drops are reported generically during assembly; this hook is for other approximations a coupling applies inside interaction_hamiltonian(). Default: nothing is dropped.

Return type:

list[‘DroppedTerm’]

collapse_channels()

Local Lindblad channels contributed by this coupling.

Return type:

tuple[CollapseChannel, …]

to_dict()

Serialize structural fields into a JSON-safe dictionary.

Return type:

dict[str, Any]