quchip.inverse_design.observables¶

Target compilation for quchip.fit_a_dress().

The desired-chip path reads component-declared numbers without dressing the input chip. The deprecated compatibility path remains separate so its seed-and-target semantics are not silently reinterpreted during migration.

Functions

`build_dressed_target_specs`(chip[, constraints])	Compile a desired chip's declared numbers into dressed constraints.
`build_target_specs`(chip, coupling_targets[, ...])	Merge device defaults, coupling targets, and explicit observables.
`infer_coupling_mode`(coupling[, override])	Infer whether a coupling's strength is targeted as `"g"`, `"chi"`, or `"zz"`.

Classes

TargetSpec(kind, label, target[, source])

A single optimization target.

class quchip.inverse_design.observables.TargetSpec(kind, label, target, source='legacy')[source]¶

Bases: object

A single optimization target.

Parameters:

kind (str)
label (Any)
target (float)
source (str)

kind¶

Observable kind — one of "freq", "anharmonicity", "chi", "zz", "exchange", "g".

Type:: str

label¶

Device label, (label_a, label_b) tuple, or coupling label that locates this target on the chip.

Type:: Any

target¶

Desired value in GHz.

Type:: float

source¶

Where the target came from: "component default", "explicit", or "legacy" for the deprecated compatibility contract.

Type:: str

kind: str¶

label: Any¶

target: float¶

source: str = 'legacy'¶

quchip.inverse_design.observables.build_dressed_target_specs(chip, constraints=None)[source]¶

Compile a desired chip’s declared numbers into dressed constraints.

Unlike build_target_specs(), this desired-chip path never calls a dressed-analysis method on chip. Devices and couplings provide their component-owned defaults; explicit constraints extend those defaults, replace the same (kind, locator) entry, or remove it with None.

Parameters:

chip – Numerical desired-chip specification.
constraints (dict | None) – Optional {component_or_pair: {observable: value_or_none}} mapping. Pair locators need not correspond to a direct coupling edge.

Return type:

tuple[TargetSpec, …]

quchip.inverse_design.observables.infer_coupling_mode(coupling, override=None)[source]¶

Infer whether a coupling’s strength is targeted as "g", "chi", or "zz".

When both devices are computational, the user almost always cares about the static zz; a qubit-resonator pair is instead best anchored by the dispersive chi; everything else is fit through the bare coupling strength. An explicit override short circuits the heuristic — including to "chi" on a pair that would not otherwise infer it; build_target_specs() validates that a "chi" target always has exactly one computational endpoint, whichever path selected it.

Parameters:

coupling – The coupling whose mode is being inferred.
override (str | None) – Explicit mode ("g", "chi", or "zz"), or None to use the computational-endpoint heuristic.

Returns:

"g", "chi", or "zz".

Return type:

str

quchip.inverse_design.observables.build_target_specs(chip, coupling_targets, observable_targets=None)[source]¶

Merge device defaults, coupling targets, and explicit observables.

The returned ordering is:

For every device, the dressed 0→1 transition frequency (chip.freq(device)) is anchored. Computational devices also anchor on the dressed anharmonicity (chip.dressed_anharmonicity(device)). Anchoring the dressed observable rather than the bare device attribute makes the defaults model-agnostic — Duffing, charge-basis transmon, and fluxonium all expose a dressed 0→1 spacing, even when the bare parametrization is wholly different (no freq or anharmonicity attribute).
One coupling target per entry in coupling_targets, with mode resolved via infer_coupling_mode() (override if a string mode is supplied, heuristic otherwise).
Every explicit entry from observable_targets.

An explicit (kind, label) in observable_targets suppresses the same-(kind, label) default from steps 1 and 2, so the user never ends up with duplicate anchors for the same quantity.

Returns:

Merged specs in the order documented above.

Return type:

tuple[TargetSpec, …]

Raises:

ValueError – A coupling target mode is not one of "chi", "zz", "g"; or any "chi" target in the merged result — from an auto device-implied default, a coupling_targets entry, or an explicit observable_targets entry — does not resolve to a coupling with exactly one computational endpoint (see _validate_chi_target()).

Parameters:

coupling_targets (dict)
observable_targets (dict | None)