quchip.inverse_design.types

Classes

FitADressResult(chip, loss, history, ...[, ...])	Result of a fit_a_dress() optimization run.
FitParameterReport(name, initial, final, ...)	Record one fitted 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='explicit')

Bases: object

Per-target record from a fit_a_dress run.

Variables:

• kind (str) – Canonical desired-chip kind ("freq", "anharmonicity", "cross_kerr", "exchange_rate", or "coupling_strength").

• label (Any) – 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.

• target (float) – Value the optimizer tried to match (GHz).

• initial (float) – Observable value at the seed chip, before optimization (GHz).

• final (float) – Observable value at the fitted chip, after optimization (GHz).

• evaluator (str) – "full" for evaluation on the whole chip or "local" for evaluation on a one-hop subsystem (see evaluator in fit_a_dress()).

• source (str) – "component default" or "explicit".

kind: str

label: Any

target: float

initial: float

final: float

evaluator: str

source: str = 'explicit'

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)

Bases: object

Record one fitted bare parameter.

Variables:

• name (str) – Path in chip.parameters.

• final (initial,) – Seed and fitted values in the parameter’s native units.

• upper_bound (lower_bound,) – Bounds used by the optimizer, in the same units.

• seed_source (str) – Origin of the starting value, as recorded by the fitter.

• sign_choice (str or None) – Coupling-sign decision, or None when no decision was necessary.

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, in the parameter’s native units.

class quchip.inverse_design.types.FitADressResult(chip, loss, history, initial_targets, final_targets, initial_params, final_params, solver_info, parameter_reports=(), history_params=(), history_residuals=None)

Bases: object

Result of a fit_a_dress() optimization run.

Variables:

• chip (Chip) – Fitted chip: a clone of the desired specification with updated device and coupling parameters. The fit never mutates the input chip. Because the result exposes .chip, it satisfies ChipTransform structurally, without inheritance.

• loss (float) – Final objective (sum of squared, scale-normalized residuals).

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

• history_params (tuple[dict[str, float], ...]) – One {parameter_name: value} dict per history entry, named like final_params. The first entry equals initial_params and the last entry equals final_params.

• history_residuals (Any) – Array of shape (len(history), len(final_targets)). Each row holds the observed minus the target value of each target (GHz) at that history entry, in final_targets order. The sum of the squared residuals, each divided by max(abs(target), 1e-9), is the matching history entry.

• initial_targets (tuple[ObservableReport, ...]) – One ObservableReport per target, evaluated on the optimizer’s initial candidate.

• final_targets (tuple[ObservableReport, ...]) – One ObservableReport per target, evaluated on the fitted chip.

• initial_params (dict[str, float]) – {parameter_name: seed_value}, the optimizer’s starting point.

• final_params (dict[str, float]) – {parameter_name: fitted_value}, the optimizer output. Parameter names follow "<device>.freq", "<device>.anharmonicity", and "<coupling>.<coupling_strength_name>". The coupling names are "<coupling>.g" for Capacitive, "<coupling>.g_0" for TunableCapacitive, "<coupling>.chi" for CrossKerr.

• parameter_reports (tuple[FitParameterReport, ...]) – One FitParameterReport per varied bare parameter, with its bounds, the source of its starting point, and any coupling-sign choice.

• solver_info (dict[str, Any]) –

  scipy solver metadata (method, status, message, nfev, jacobian). It also holds the identifiability receipt that each fit_a_dress() call records. The receipt contains n_free_parameters (length of final_params) and n_target_residuals (length of final_targets). Its underdetermined_by_count is True when the former exceeds the latter, a necessary but not sufficient identifiability condition. The receipt also contains the final scaled-Jacobian rank, the condition number, the 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.

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, ...] = ()

history_params: tuple[dict[str, float], ...] = ()

history_residuals: Any = None

property converged: bool | None

Convergence flag of the optimizer, or None when the status is not available.

property message: str | None

The optimizer’s termination reason, when recorded.

summary()

Return a compact target, parameter, and identifiability receipt.

rebind(seed: BaseDevice | str, /) → BaseDevice

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

Find the fitted clones that match one or more seed devices.

For example, call fit.rebind(qb, tc, cr).

Parameters:

*seeds (BaseDevice or str) – One or more devices (or their labels) from the seed chip passed to fit_a_dress(). You must give at least one.

Returns:

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

Return type:

BaseDevice or tuple[BaseDevice, …]

Raises:

ValueError – No seeds were given.