quchip.engine.routes

Choose how stationary and static calculations solve, and record the reason.

A stationary calculation solves on one of three kinds of space. A passive linear chip, or a conserving chip under an infinitesimal probe, keeps its mode or one-excitation equations. A conserving chip under a finite drive keeps the product labels with total excitation N <= K. Every other calculation uses the backend’s stationary Liouvillian on the product space, or on the retained labels of an excitation cutoff. Static queries diagonalize the blocks of a conserving chip or of an excitation cutoff, and otherwise the full static model.

Functions

array_name(backend)	Return the name of a backend's array library.
automatic_cutoff(maximum, solve, change, *, ...)	Raise K from FIRST_CUTOFF until N <= K + 1 changes the results by at most the tolerance.
cutoff_reason(cutoff, check)	Return the sentence that explains an automatic cutoff K.
largest_change(lower, upper)	Return the largest change |a - b| / (max(|a|, |b|) + floor / tolerance) over pairs of values.
liouvillian_route(backend, engine_result, reason)	Return the record of a solve with the backend's stationary Liouvillian.
plan_sectors(chip, workflow, *, labels[, ...])	Return the sector model of a stationary workflow, or None for the backend's Liouvillian, and why.
require_workflow(chip, name)	Return a workflow's capabilities, and raise when the chip's excitation cutoff is outside them.
sector_diagnostics(model, cutoff, solve, ...)	Return the diagnostics entries of a solve on the sectors N <= cutoff.
sector_route(model, cutoff, reason, *[, solved])	Return the record of a solve on the sectors N <= cutoff.
static_route(chip, structure)	Return how static dressed queries diagonalize a chip.
warn_cutoff(method, cutoff, size, check, ...)	Warn which truncation an automatic route kept and what its check found.
weak_probe_reason(chip, labels)	Return why neither the harmonic nor the vacuum response gives a chip's small-signal matrix.

Classes

CutoffCheck(status, compared_with, change, ...)	Comparison of an automatic cutoff K with K + 1 over a whole grid.
SolveRoute(name, reason, dimension, arrays)	The numerical route of one stationary or static calculation and the reason for it.
Workflow(name, cutoff, sectors)	What one public workflow supports.

class quchip.engine.routes.SolveRoute(name, reason, dimension, arrays, _peak_bytes=None)

Bases: object

The numerical route of one stationary or static calculation and the reason for it.

Variables:

• name (str) – "linear_response" for passive-linear mode equations, "vacuum_response" for the vacuum and one-excitation states under a weak probe, "conditional_response" for a frozen dressed reference, "sector_stationary" for the excitation sectors N <= K, and "stationary_resolvent" for the backend’s stationary Liouvillian on the product space or on the retained labels of an excitation cutoff. Static queries use "sector_eigensystem" or "full_eigensystem".

• reason (str) – Why the planner chose the route.

• dimension (int) – Number of modes or states that the route solves on.

• arrays (str) – Array library of the solve, "numpy" or "jax".

• peak_bytes (int or None) – Estimated peak memory of the solve, calculated on request. None means that the route has no estimate.

name: str

reason: str

dimension: int

arrays: str

property peak_bytes: int | None

Estimated peak memory of the solve in bytes, or None.

class quchip.engine.routes.Workflow(name, cutoff, sectors)

Bases: object

What one public workflow supports.

Variables:

• name (str) – Public name of the workflow in messages.

• cutoff (bool) – Whether the workflow runs under an ExcitationCutoff.

• sectors (bool) – Whether the planner can solve the workflow on excitation sectors. The sector route needs concrete values, because it solves on host NumPy arrays; traced values use the backend’s Liouvillian.

name: str

cutoff: bool

sectors: bool

quchip.engine.routes.require_workflow(chip, name)

Return a workflow’s capabilities, and raise when the chip’s excitation cutoff is outside them.

Parameters:

• chip (Chip) – Chip whose excitation cutoff is checked.

• name (str) – Key of the workflow in WORKFLOWS.

quchip.engine.routes.array_name(backend)

Return the name of a backend’s array library.

quchip.engine.routes.plan_sectors(chip, workflow, *, labels, inputs=(), modes=(), frequencies=(), options=None, concrete=True)

Return the sector model of a stationary workflow, or None for the backend’s Liouvillian, and why.

A chip with an excitation cutoff, or a chip with more than AUTOMATIC_SECTOR_STATES product states, solves on sectors when its static model conserves the total excitation N and its channels and inputs keep that structure. Solver options select the backend’s Liouvillian.

Parameters:

• chip (Chip) – Chip at one parameter point.

• workflow (Workflow) – Calling workflow.

• labels (tuple of str) – Output ports that the workflow reads.

• inputs (tuple of str) – Ports with coherent inputs.

• modes (tuple of str) – Fock modes whose observables the workflow reads.

• frequencies (sequence) – Carrier frequency of each coherent input in GHz.

• options (dict or None) – Stationary solver options.

• concrete (bool) – Whether the frequencies and amplitudes of the inputs are concrete.

quchip.engine.routes.weak_probe_reason(chip, labels)

Return why neither the harmonic nor the vacuum response gives a chip’s small-signal matrix.

quchip.engine.routes.cutoff_reason(cutoff, check)

Return the sentence that explains an automatic cutoff K.

quchip.engine.routes.sector_route(model, cutoff, reason, *, solved=True)

Return the record of a solve on the sectors N <= cutoff.

solved=False records a result that needed no stationary solve, which has no memory estimate.

quchip.engine.routes.sector_diagnostics(model, cutoff, solve, reason, choice, check)

Return the diagnostics entries of a solve on the sectors N <= cutoff.

Parameters:

• model (SectorProbeModel) – Sector model of the solve.

• cutoff (int) – Kept cutoff K.

• solve (SectorSolve) – The stationary solve on N <= K.

• reason (str) – Why the planner chose the sector route.

• choice ({"explicit", "automatic"}) – Whether K comes from the chip’s excitation cutoff or from the comparison with K + 1.

• check (CutoffCheck or None) – The comparison of an automatic K.

quchip.engine.routes.liouvillian_route(backend, engine_result, reason)

Return the record of a solve with the backend’s stationary Liouvillian.

quchip.engine.routes.static_route(chip, structure)

Return how static dressed queries diagonalize a chip.

Parameters:

• chip (Chip) – Chip whose static model is queried.

• structure (ExcitationStructure) – Excitation structure of that static model.

class quchip.engine.routes.CutoffCheck(status, compared_with, change, states)

Bases: object

Comparison of an automatic cutoff K with K + 1 over a whole grid.

Variables:

• status ({"passed", "not run"}) – "not run" means that N <= K + 1 did not fit in memory.

• compared_with (int) – The larger cutoff K + 1.

• change (float or None) – Largest relative change, or None when the comparison did not run.

• states (int) – Number of labels with N <= K + 1.

status: str

compared_with: int

change: float | None

states: int

record()

Return the check as diagnostics entries.

quchip.engine.routes.automatic_cutoff(maximum, solve, change, *, fits, states, complete=None)

Raise K from FIRST_CUTOFF until N <= K + 1 changes the results by at most the tolerance.

This is a convergence check, not an error bound.

Parameters:

• maximum (int) – Largest total of the chip, where the sectors hold every label.

• solve (callable) – solve(K, lower) returns the results on N <= K, starting from the results lower at a smaller cutoff, or from None.

• change (callable) – change(lower, upper) returns the largest relative change.

• fits (callable) – fits(K) says whether a solve on N <= K fits in memory.

• states (callable) – states(K) returns the number of labels with N <= K.

• complete (callable, optional) – complete(K, results) completes results that a comparison solved in part, when K becomes the kept cutoff.

Returns:

The kept cutoff, its results, and the check, which is None when the kept cutoff holds every label.

Return type:

tuple

quchip.engine.routes.largest_change(lower, upper)

Return the largest change |a - b| / (max(|a|, |b|) + floor / tolerance) over pairs of values.

quchip.engine.routes.warn_cutoff(method, cutoff, size, check, quantities, *, note='', stacklevel=2)

Warn which truncation an automatic route kept and what its check found.