quchip.backend.containers

Backend-agnostic solver-result and IR-lowering containers.

These frozen/auto dataclasses are the payloads that cross the backend boundary. The engine or the backends produce them without committing to a solver’s native storage. A SolverResult holds native states but shows a backend-free shape. A PreparedHamiltonian / PreparedBatch opaquely carries any RHS the backend’s solver accepts.

References

  • Johansson, Nation, Nori — QuTiP 2, Comput. Phys. Commun. 183, 1760 (2012)

  • Guilmin et al. — dynamiqs: an open-source Python library for GPU-accelerated and differentiable simulation of quantum systems (2024)

Module Attributes

PreparedBatch

What Backend.prepare_batch() may return — the batching strategy is explicit in the type, and Backend.solve_batch() dispatches on it.

Classes

CoherenceResponseSolverResult(responses, ...)

Scattering and relative residuals from adjacent-sector response solves.

DeferredBatch(shared, batch_size[, ...])

Batched-solve payload whose RHS construction is deferred.

EagerBatch(rhs_list, batch_size[, metadata, ...])

Batched-solve payload with one native RHS per element.

EigensystemData(eigenvalues, eigenvector_matrix)

Hermitian eigensystem returned in a single diagonalization call.

LinearResponseSolverResult(responses, ...)

Backend payload for one batched passive-linear scattering solve.

PreparedHamiltonian(rhs[, metadata])

Backend-native Hamiltonian produced by Backend.prepare_hamiltonian().

PreparedStationary(backend, engine_result, ...)

Temporary native generator shared by one stationary operating point.

SolverResult(times[, states, expect, ...])

Backend-agnostic container for a single time-evolution solve.

SteadyStateSolverResult(state[, expect, ...])

Backend payload for one stationary Lindblad solve.

VmappedBatch(rhs, batch_size[, metadata, tlist])

Batched-solve payload with a single natively batched RHS.

Exceptions

BatchSolveError(index, detail[, parameters])

A numerical or configuration failure at one batch point, safe across workers.
exception quchip.backend.containers.BatchSolveError(index, detail, parameters=None)[source]

Bases: RuntimeError

A numerical or configuration failure at one batch point, safe across workers.

Parameters:

  • index (int) – Zero-based flat batch index that failed.

  • detail (str) – Underlying numerical or configuration failure.

  • parameters (dict or None, default None) – Parameter values at the failed point. None stores an empty mapping.

class quchip.backend.containers.SolverResult(times, states=None, expect=None, final_state=None, stats=<factory>, solver='', native=None)[source]

Bases: object

Backend-agnostic container for a single time-evolution solve.

Variables:

  • times (Any) – 1D array of save times (ns) matching the solver’s tlist.

  • states (list[Any] | None) – Saved states, one per save time, in the backend’s native state type (Qobj / QArray). None if store_states was off.

  • expect (list[list[float]] | dict[str | tuple[str, str], Any] | None) – Expectation-value traces as a list[list[float]] indexed by e_ops and then by time. When the engine supplied labelled observables, this is a dict keyed by strings or (drive_label, op) pairs.

  • final_state (Any | None) – Final state (states[-1] when states are stored). Useful for multi-segment protocols that do not keep full trajectories.

  • stats (dict[str, Any]) – Solver-specific diagnostics (integrator step count, batch index, etc.). No physics depends on them.

  • solver (str) – Dispatched native solver name.

  • native (Any) – Unchanged stochastic result, or None for a deterministic payload.

times: Any
states: list[Any] | None = None
expect: list[list[float]] | dict[str | tuple[str, str], Any] | None = None
final_state: Any | None = None
stats: dict[str, Any]
solver: str = ''
native: Any = None
class quchip.backend.containers.SteadyStateSolverResult(state, expect=None, stats=<factory>, residual=None, nullity=None, _condition_number=None)[source]

Bases: object

Backend payload for one stationary Lindblad solve.

Variables:

  • state (State) – Stationary density matrix in the native backend basis.

  • expect (list or None) – Expectations in the requested observable order. None when not evaluated.

  • stats (dict) – Backend diagnostics, including whether uniqueness was checked.

  • residual (scalar or None) – Norm of the stationary Liouvillian residual, or None if not calculated.

  • nullity (int or None) – Estimated Liouvillian null-space dimension, or None when unchecked.

state: Any
expect: list[Any] | None = None
stats: dict[str, Any]
residual: Any = None
nullity: Any = None
property condition_number: Any
class quchip.backend.containers.LinearResponseSolverResult(responses, mode_amplitudes, residuals, _condition_numbers, _mode_covariance)[source]

Bases: object

Backend payload for one batched passive-linear scattering solve.

Variables:

  • responses (array_like, shape (n_freq, n_ports, n_ports)) – Complex scattering matrix indexed by frequency, output, then input.

  • mode_amplitudes (array_like, shape (n_freq, n_modes, n_ports)) – Internal mode response to unit incident amplitude at each input port.

  • residuals (array_like, shape (n_freq,)) – Linear-system residual norms at each probe frequency.

responses: Any
mode_amplitudes: Any
residuals: Any
property mode_covariance: Any

Return centered normal covariance N_ij = <delta a_j† delta a_i>.

property condition_numbers: Any
class quchip.backend.containers.CoherenceResponseSolverResult(responses, residuals, _condition_numbers)[source]

Bases: object

Scattering and relative residuals from adjacent-sector response solves.

Variables:

  • responses (array_like) – Scattering with shape (frequencies, outputs, inputs).

  • residuals (array_like) – Maximum relative block residual for each frequency.

responses: Any
residuals: Any
class quchip.backend.containers.PreparedHamiltonian(rhs, metadata=<factory>)[source]

Bases: object

Backend-native Hamiltonian produced by Backend.prepare_hamiltonian().

rhs is the object the backend’s solver accepts directly: a Qobj / QobjEvo for QuTiP, and a dynamiqs TimeQArray or a sum of them for dynamiqs. metadata passes engine-level hints through opaquely, for example spectral_bound_ghz for integrator step heuristics.

Variables:

  • rhs (object) – Native Hamiltonian consumed by the solver, already in angular-frequency units.

  • metadata (dict) – Integration hints, including spectral/carrier bounds when available.

rhs: Any
metadata: dict[str, Any]
class quchip.backend.containers.PreparedStationary(backend, engine_result, liouvillian)[source]

Bases: object

Temporary native generator shared by one stationary operating point.

Variables:

  • backend (Backend) – Backend instance that owns this preparation.

  • engine_result (EngineResult) – Exact captured operating point associated with the generator.

  • liouvillian (object) – Native stationary generator, with rates in 1/ns.

backend: Any
engine_result: Any
liouvillian: Any
class quchip.backend.containers.EagerBatch(rhs_list, batch_size, metadata=<factory>, tlist=None)[source]

Bases: object

Batched-solve payload with one native RHS per element.

The default Backend.solve_batch() dispatches each element’s RHS through Backend.batched_sesolve() / Backend.batched_mesolve().

Variables:

  • rhs_list (list) – One native right-hand side per batch element.

  • batch_size (int) – Number of batch elements.

  • metadata (dict) – Shared lowering and integration hints.

  • tlist (array_like or None) – Common save-time grid in ns, or None when unspecified.

rhs_list: list[Any]
batch_size: int
metadata: dict[str, Any]
tlist: Any | None = None
class quchip.backend.containers.VmappedBatch(rhs, batch_size, metadata=<factory>, tlist=None)[source]

Bases: object

Batched-solve payload with a single natively batched RHS.

rhs covers every element at once. On this dynamiqs path, the per-element signals are stacked along a leading batch axis and the solver runs one vmapped call.

Variables:

  • rhs (object) – Native right-hand side, with the batch axis.

  • batch_size (int) – Number of batch elements.

  • metadata (dict) – Shared lowering and integration hints.

  • tlist (array_like or None) – Common save-time grid in ns, or None when unspecified.

rhs: Any
batch_size: int
metadata: dict[str, Any]
tlist: Any | None = None
class quchip.backend.containers.DeferredBatch(shared, batch_size, metadata=<factory>, tlist=None)[source]

Bases: object

Batched-solve payload whose RHS construction is deferred.

shared carries backend-private state. The producing backend must override Backend.solve_batch() to consume it. QuTiP assembles final QobjEvo objects inside its workers. Dynamiqs assembles a vmapped RHS inside its cached JIT.

Variables:

  • shared (object) – Backend-private lowering payload consumed by solve_batch.

  • batch_size (int) – Number of batch elements.

  • metadata (dict) – Shared lowering and integration hints.

  • tlist (array_like or None) – Common save-time grid in ns, or None when unspecified.

shared: Any
batch_size: int
metadata: dict[str, Any]
tlist: Any | None = None
quchip.backend.containers.PreparedBatch: TypeAlias = quchip.backend.containers.EagerBatch | quchip.backend.containers.VmappedBatch | quchip.backend.containers.DeferredBatch

What Backend.prepare_batch() may return — the batching strategy is explicit in the type, and Backend.solve_batch() dispatches on it.

class quchip.backend.containers.EigensystemData(eigenvalues, eigenvector_matrix, _states_builder=None, _states_cache=None)[source]

Bases: object

Hermitian eigensystem returned in a single diagonalization call.

eigenvalues is ascending. eigenvector_matrix stacks the eigenvectors as columns in the bare-product basis used for the diagonalization. The eigenstates property gives the per-column backend-native kets lazily.

Backends populate _states_builder, a callable that materializes the ket list on demand. Alternatively, backends prime _states_cache directly when the diagonalizer already produced the kets, for example QuTiP’s Qobj.eigenstates.

Variables:

  • eigenvalues (array_like, shape (D,)) – Ascending eigenvalues in the input operator’s units.

  • eigenvector_matrix (array_like, shape (D, D)) – Eigenvectors as columns in the input operator basis.

eigenvalues: Any
eigenvector_matrix: Any
property eigenstates: list[Any]

Return per-column backend-native eigenstate kets (built on first access).

Memoizes only when the materialized kets are tracer-free. Concrete states are cached.