quchip.inverse_design.subsystems

Neighborhood extraction for large-chip observables.

When the full Hilbert space is too large to dress repeatedly inside a least-squares loop, fit_a_dress evaluates each target on the smallest sub-chip that still contains the relevant physics: the target device(s) plus every directly coupled neighbor (one-hop closure).

This is a pragmatic truncation, not a controlled approximation — the one-hop neighborhood captures all first-order dispersive effects for the target but ignores second-order contributions from non-neighbors. Use max_hilbert_dim in fit_a_dress() to control when the fit switches from "full" to "local".

Functions

build_local_subsystem(chip, labels)	Build a reduced Chip holding only the given device labels.
choose_evaluator(chip, max_hilbert_dim)	Pick "full" or "local" based on total Hilbert-space size.
device_labels_for_local_eval(chip, label)	Return the seed device(s) plus every directly coupled neighbor.

quchip.inverse_design.subsystems.choose_evaluator(chip, max_hilbert_dim)

Pick "full" or "local" based on total Hilbert-space size.

Returns "full" when the product of all device levels is at most max_hilbert_dim; otherwise "local".

Parameters:

• chip (Chip)

• max_hilbert_dim (int) – Total-Hilbert-space-size threshold.

Returns:

"full" or "local".

Return type:

str

quchip.inverse_design.subsystems.build_local_subsystem(chip, labels)

Build a reduced Chip holding only the given device labels.

Couplings are retained iff both endpoint labels are in labels; frame, RWA, and backend settings are inherited from the parent.

Parameters:

• chip (Chip)

• labels (tuple[str, ...]) – Device labels to keep.

Returns:

Reduced chip holding only the kept devices and their mutual couplings.

Return type:

Chip

quchip.inverse_design.subsystems.device_labels_for_local_eval(chip, label)

Return the seed device(s) plus every directly coupled neighbor.

label may be a single device/label or a tuple of device/labels; all entries are normalized through resolve_label(). The returned tuple is sorted for determinism.

Parameters:

• chip (Chip)

• label (Any) – A single device/label or a tuple of devices/labels.

Returns:

Sorted device labels: the seed(s) plus every directly coupled neighbor.

Return type:

tuple[str, …]

Examples

A q0 - q1 - q2 chain keeps the seed and its direct neighbors:

>>> from quchip import Chip, DuffingTransmon, Capacitive
>>> from quchip.inverse_design.subsystems import device_labels_for_local_eval
>>> qs = [DuffingTransmon(freq=5.0 + 0.1 * i, anharmonicity=-0.3, levels=3,
...                       label=f"q{i}") for i in range(3)]
>>> chip = Chip(devices=qs, couplings=[Capacitive(qs[0], qs[1], g=0.005),
...                                    Capacitive(qs[1], qs[2], g=0.005)])
>>> device_labels_for_local_eval(chip, "q0")
('q0', 'q1')
>>> device_labels_for_local_eval(chip, ("q0", "q1"))
('q0', 'q1', 'q2')