quchip.inverse_design.types

Classes

FitADressResult(chip, loss, history, ...[, ...])

Result of a fit_a_dress() optimization run.

FitParameterReport(name, initial, final, ...)

Starting point, bounds, result, and provenance for one bare parameter.

ObservableReport(kind, label, target, ...[, ...])

Per-target record from a fit_a_dress run.
class quchip.inverse_design.types.ObservableReport(kind, label, target, initial, final, evaluator, source='legacy')[source]

Bases: object

Per-target record from a fit_a_dress run.

Parameters:
kind

Canonical desired-chip kind ("freq", "anharmonicity", "cross_kerr", "exchange_rate", or "coupling_strength"), or its deprecated compatibility counterpart.

Type:

str

label

Target locator — a device label for single-device observables, a (label_a, label_b) tuple for pair observables, or a coupling label for coupling-keyed observables.

Type:

Any

target

The value the optimizer tried to match (GHz).

Type:

float

initial

Observable value at the seed chip, before optimization (GHz).

Type:

float

final

Observable value at the fitted chip, after optimization (GHz).

Type:

float

evaluator

"full" if this target was evaluated on the whole chip or "local" if it was evaluated on a one-hop subsystem (see max_hilbert_dim in fit_a_dress()).

Type:

str

source

"component default" or "explicit" for the desired-chip contract; "legacy" for the deprecated compatibility path.

Type:

str

kind: str
label: Any
target: float
initial: float
final: float
evaluator: str
source: str = 'legacy'
property residual: float

Final signed error, final - target (GHz).

property relative_residual: float

Final residual on the fitter’s normalized objective scale.

class quchip.inverse_design.types.FitParameterReport(name, initial, final, lower_bound, upper_bound, seed_source, sign_choice=None)[source]

Bases: object

Starting point, bounds, result, and provenance for one bare parameter.

Parameters:
name: str
initial: float
final: float
lower_bound: float
upper_bound: float
seed_source: str
sign_choice: str | None = None
property delta: float

Signed optimizer displacement, final - initial (GHz).

class quchip.inverse_design.types.FitADressResult(chip, loss, history, initial_targets, final_targets, initial_params, final_params, solver_info, parameter_reports=())[source]

Bases: object

Result of a fit_a_dress() optimization run.

Parameters:
chip

Fitted chip: a clone of the desired specification (or compatibility seed) with updated device and coupling parameters. The input chip is never mutated. Exposing .chip makes this satisfy ChipTransform structurally, with no inheritance required.

Type:

Chip

loss

Final objective (sum of squared, scale-normalized residuals).

Type:

float

history

One-dimensional numpy array containing the normalized objective at every distinct parameter vector passed to the residual function. The first entry is the seed and the last is loss. With a numerical Jacobian, the intermediate entries include finite-difference probes as well as accepted solver iterates; use numpy.minimum.accumulate(history) for a monotone best-so-far convergence curve.

Type:

Any

initial_targets

One ObservableReport per target, evaluated on the optimizer’s initial candidate.

Type:

tuple[ObservableReport, …]

final_targets

One ObservableReport per target, evaluated on the fitted chip.

Type:

tuple[ObservableReport, …]

initial_params

{parameter_name: seed_value} — the starting point passed to the optimizer.

Type:

dict[str, float]

final_params

{parameter_name: fitted_value} — the optimizer output. Parameter names follow "<device>.freq", "<device>.anharmonicity", and "<coupling>.<coupling_strength_name>" — "<coupling>.g" for Capacitive, "<coupling>.g_0" for TunableCapacitive, "<coupling>.chi" for CrossKerr.

Type:

dict[str, float]

parameter_reports

One FitParameterReport per varied bare parameter, including its bounds, starting-point source, and any coupling-sign choice.

Type:

tuple[FitParameterReport, …]

solver_info

scipy solver metadata (method, status, message, nfev, jacobian), plus the identifiability receipt recorded for every fit_a_dress() call: n_free_parameters (length of final_params), n_target_residuals (length of final_targets), and underdetermined_by_count (True when the former exceeds the latter — a necessary, not sufficient, identifiability condition), final scaled-Jacobian rank, condition number, singular values, and any weak parameter directions. Rank uses normalized residuals in the solver’s scaled parameter coordinates. history_axis names the sampling axis used by history, and n_recorded_evaluations gives its length. jacobian is "jax" when a JAX-native backend supplies the exact residual Jacobian and "finite-difference" otherwise.

Type:

dict[str, Any]

chip: Chip
loss: float
history: Any
initial_targets: tuple[ObservableReport, ...]
final_targets: tuple[ObservableReport, ...]
initial_params: dict[str, float]
final_params: dict[str, float]
solver_info: dict[str, Any]
parameter_reports: tuple[FitParameterReport, ...] = ()
summary()[source]

Return a compact target, parameter, and identifiability receipt.

Return type:

str

rebind(seed: BaseDevice | str, /) → BaseDevice[source]
rebind(seed: BaseDevice | str, /, *more: BaseDevice | str) → tuple[BaseDevice, ...]

Look up the fitted clones matching one or more seed devices.

Use fit.rebind(qb, tc, cr) to retrieve the fitted clones corresponding to the seed devices.

Parameters:

*seeds (BaseDevice or str) – One or more devices (or their labels) from the seed chip passed to fit_a_dress(). At least one is required.

Returns:

The matching device(s) on chip (the fitted clone), in input order. A single positional seed returns that device directly; two or more return a tuple.

Return type:

BaseDevice or tuple[BaseDevice, …]

Raises:

ValueError – No seeds were given.