quchip.control.equipment

Control-equipment container: drive lines and signal chain.

Signal transforms are owned here, not by individual drives.

Classes

ControlEquipment(lines, *[, signal_chain])	Ordered drive lines plus a sequence of signal-chain transforms.
CrosstalkMatrix(labels, beta, theta, delay)	Dense crosstalk transform and matrix view in control-line order.

class quchip.control.equipment.CrosstalkMatrix(labels, beta, theta, delay)

Bases: SignalTransform

Dense crosstalk transform and matrix view in control-line order.

Parameters:

• labels (tuple[str, ...])

• beta (Any)

• theta (Any)

• delay (Any)

labels

Drive labels in wiring order (the order drives appear in ControlEquipment.lines). Row / column i corresponds to labels[i].

Type:

tuple[str, …]

beta

[n, n] amplitude matrix. beta[i, j] is the leakage amplitude from source labels[j] onto victim labels[i] (column = source, row = victim). Diagonals represent self-coupling and are conventionally 1.0.

Type:

Any

theta

[n, n] phase matrix (radians), same indexing as beta.

Type:

Any

delay

[n, n] delay matrix (ns), same indexing as beta.

Type:

Any

Notes

Every off-diagonal edge reads the same input signal map, so reciprocal entries form one linear mixing stage without recursively leaking one another’s output. Matrix entries flow directly into the signal-program IR (PolarScale/Shift), preserving end-to-end JAX traceability.

labels: tuple[str, ...]

beta: Any

theta: Any

delay: Any

apply(signals)

Apply all directed leakage edges to one shared input snapshot.

Parameters:

signals (dict[tuple[str, int], SignalNode])

Return type:

dict[tuple[str, int], SignalNode]

referenced_lines()

Return control-line labels referenced by this transform.

Return type:

tuple[str, …]

without_line(line)

Return this transform without line, or None when it must be dropped.

Parameters:

line (str)

Return type:

CrosstalkMatrix | None

edges()

Return the directed-edge view used by topology and visualization.

Return type:

list[Crosstalk]

to_dict()

Serialize into a JSON-safe dictionary.

Return type:

dict[str, Any]

classmethod from_dict(d)

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:

d (dict[str, Any])

Return type:

CrosstalkMatrix

class quchip.control.equipment.ControlEquipment(lines, *, signal_chain=None)

Bases: object

Ordered drive lines plus a sequence of signal-chain transforms.

Drives produce raw line signals; the equipment pipes them through signal_chain in order before the engine assembles Hamiltonian terms.

Parameters:

• lines (list[BaseDrive])

• signal_chain (list[SignalTransform] | None)

property lines: list[BaseDrive]

Ordered drive lines (defensive copy).

property signal_chain: list[SignalTransform]

Signal-chain transforms (defensive copy).

apply_signal_chain(signals)

Apply every signal-chain transform to signals, in order.

Each transform receives the previous transform’s output, so transforms compose sequentially: reordering signal_chain changes the result (e.g. a Delay applied before a Gain sees the undelayed signal).

Parameters:

signals (SignalMap) – {(drive_label, drive_index): SignalProgram} map of raw line signals. drive_index distinguishes multiple ops on the same drive line and is assigned by the engine when it enumerates the chip’s scheduled drive ops.

Returns:

Transformed signal map. May contain keys absent from signals: a Crosstalk transform, for example, adds an entry under the victim drive’s label for every source entry it leaks from.

Return type:

SignalMap

property crosstalks: list[Crosstalk]

Directed crosstalk edges represented by the signal chain.

crosstalk_matrix()

Return a dense matrix view of the Crosstalk transforms.

The matrix uses wiring order (self.lines) as the stable axis ordering. Column index = source drive, row index = victim drive. Diagonal entries are beta=1, theta=0, delay=0 by convention (self-coupling). Off-diagonal entries aggregate every Crosstalk transform present in the signal chain; lines with no corresponding transform contribute zeros.

Non-Crosstalk transforms (Gain, Delay) are ignored here; this is strictly a view of the crosstalk edges.

Returns:

labels (wiring order), beta, theta, delay as [n, n] arrays. Arrays use jax.numpy when any stored entry is a JAX tracer or array, otherwise numpy.

Return type:

CrosstalkMatrix

set_crosstalk_matrix(beta, theta=None, delay=None, *, labels=None)

Rehydrate the crosstalk edges from dense matrices.

Removes every crosstalk transform currently in the signal chain and replaces them with one CrosstalkMatrix. Other signal-chain transforms (Gain, Delay, and user-defined subclasses) are preserved in order.

Parameters:

• beta (Any) – [n, n] amplitude matrix. beta[i, j] is emitted as the leakage amplitude from source labels[j] onto victim labels[i]. Diagonal entries are ignored (self-coupling belongs to the drive itself, not to a crosstalk edge).

• theta (Any, optional) – [n, n] phase matrix (radians). Defaults to zeros.

• delay (Any, optional) – [n, n] delay matrix (ns). Defaults to zeros.

• labels (tuple[str, ...] | list[str] | None, optional) – Axis ordering. Defaults to wiring order (self.lines). Must match beta.shape[0].

Return type:

None

Notes

Traced JAX entries flow unchanged into CrosstalkMatrix and therefore into the signal-program IR. No concretization occurs.

copy(device_map, coupling_map=None)

Return a structural copy with drive lines rebound to device_map / coupling_map.

Edge lines (target_kind == "edge") rebind via coupling_map, keyed by coupling label; device lines rebind via device_map as before.

Parameters:

• device_map (dict[str, Any])

• coupling_map (dict[str, Any] | None)

Return type:

ControlEquipment

to_dict()

Serialize into a JSON-safe dictionary.

Return type:

dict[str, Any]

classmethod from_dict(d, dev_map, coupling_map=None)

Reconstruct from to_dict() output, rebinding drives via dev_map / coupling_map.

Each line’s target_label is resolved against dev_map first, then coupling_map — device and coupling labels are disjoint by Chip construction, so at most one map holds the label.

Parameters:

• d (dict[str, Any])

• dev_map (dict[str, Any])

• coupling_map (dict[str, Any] | None)

Return type:

ControlEquipment