quchip.results.results

Backend-agnostic wrapper around solver output.

The engine wraps each backend’s solver output here, so callers use the same state, expectation, partial-trace, population, and batch interfaces.

Numerical population and overlap accessors return NumPy arrays for QuTiP and JAX arrays for Dynamiqs, even for eager calls. Host conversion is explicit.

Functions

capture_label_targets(problem, captured)	Capture the label-target record of a solve, once for each chip and approximation of a batch.
wrap_solver_result(solver_result, problem, ...)	Wrap a raw backend SolverResult into a user-facing SimulationResult.
wrap_solver_results_from_batch(...)	Wrap backend results with each batch point's resolved solve context.

Classes

ObservableTrace(values, raw)	One named expectation-value trace, with pre- and post-processing values.
OutputFieldTrace(exposure, times, amplitude, ...)	Complete transient field reported at one external reference plane.
SimulationBatchResult(results, *[, shape, axes])	Ordered, immutable batch of SimulationResult with stacked helpers.
SimulationResult(solver_result, backend, dims, *)	Backend-agnostic container for the output of one solve.

class quchip.results.results.ObservableTrace(values, raw)

Bases: object

One named expectation-value trace, with pre- and post-processing values.

Variables:

• values (Any) – Post-processed expectation values over time (e.g. demodulated, phase-corrected, band-summed). User code usually reads these.

• raw (Any) – The same quantity before post-processing. Use it to debug frame conventions, band decomposition, and demodulation.

values: Any

raw: Any

class quchip.results.results.OutputFieldTrace(exposure, times, amplitude, photon_flux, raw_amplitude, raw_photon_flux)

Bases: object

Complete transient field reported at one external reference plane.

amplitude is the complex mean field <b_out>. photon_flux is the normally ordered <b_out dagger b_out> in photons/ns. raw_* keep the same moments at the Markov boundary, before propagation through the outbound reference run. Complex amplitudes use the physics e^{-iωt} convention. Conjugate raw_amplitude to give a boundary template to iq_readout().

Variables:

• exposure (str) – External network-port label.

• times (array_like) – Saved times in ns.

• raw_amplitude (amplitude,) – Propagated and Markov-boundary complex means in 1/sqrt(ns).

• raw_photon_flux (photon_flux,) – Propagated and Markov-boundary normally ordered fluxes in photons/ns.

exposure: str

times: Any

amplitude: Any

photon_flux: Any

raw_amplitude: Any

raw_photon_flux: Any

quadrature(phase=0.0)

Return Re[exp(-i phase) <b_out>] without another solve.

Parameters:

phase (scalar, default=0.0) – Quadrature angle in radians.

property final_amplitude: Any

Return the final complex output amplitude.

property final_photon_flux: Any

Return the final normally ordered photon flux.

class quchip.results.results.SimulationResult(solver_result, backend, dims, *, device_info=None, observable_traces=None, output_traces=None, channels=(), bases=None, dissipation=True, readout_wiring=None, excitation_space=None, frame=None, label_targets=None)

Bases: object

Backend-agnostic container for the output of one solve.

Stored states follow the requested storage policy. times uses ns, and dims follows chip order. Dict-form e_ops become ObservableTrace entries in observable_traces.

Parameters:

• solver_result (SolverResult) – Backend output to wrap.

• backend (Backend) – Backend that owns the native states and arrays.

• dims (sequence of int) – Hilbert dimensions in chip order.

• device_info (optional) – Captured device, observable, output, channel, and basis metadata.

• observable_traces (optional) – Captured device, observable, output, channel, and basis metadata.

• output_traces (optional) – Captured device, observable, output, channel, and basis metadata.

• channels (optional) – Captured device, observable, output, channel, and basis metadata.

• bases (optional) – Captured device, observable, output, channel, and basis metadata.

• dissipation (bool, default=True) – Whether collapse channels were included.

• excitation_space (optional) – Captured exact excitation coordinate map, or None for product coordinates.

• readout_wiring (optional) – Captured downstream readout wiring.

• frame (ResolvedFrame or None, optional) – Integration frame of the saved states.

• label_targets (LabelTargets or None, optional) – Snapshot of the solve’s chip that prepares label targets.

Variables:

frame (ResolvedFrame or None) – Integration frame of the saved states: the frame frequency of each device and the frame mode.

property observable_traces: dict[Any, ObservableTrace | list[ObservableTrace]] | None

Return the dict of named ObservableTrace entries, or None.

The value is None when e_ops was not a dict.

expect(key, index=None)

Return an expectation trace over self.times.

Parameters:

• key (object or str) – Captured observable key.

• index (int or None, optional) – Entry of a list-valued observable.

observable_at(t, values, *, method='exact')

Select saved observable values at scalar or array times.

Values have time on their last axis, and the result has their leading axes followed by the query shape. nearest selects the earlier sample on a tie. interpolate is linear, including for complex values. Out-of-interval queries raise an error. No solve or state interpolation occurs.

Parameters:

• t (scalar or array_like) – Query times in ns.

• values (array_like) – Saved values with time on the final axis.

• method ({"exact", "nearest", "interpolate"}, default="exact") – Time-selection rule.

expect_final(key, index=None)

Return the final expectation value for an observable.

Parameters:

• key (object or str) – Captured observable key.

• index (int or None, optional) – Entry of a list-valued observable.

expect_values(key, index=None)

Return an expectation trace over self.times.

Parameters:

• key (object or str) – Captured observable key.

• index (int or None, optional) – Entry of a list-valued observable.

property outputs: dict[Any, OutputFieldTrace]

Return complete output-field traces keyed by network port label.

output(exposure)

Return one field trace by network port or label.

Parameters:

exposure (port object or str) – External output reference plane.

property collapse_channels: tuple[str, ...]

Return the resolved SLH channel keys accepted by jump_rate().

Hidden channels use keys such as "hidden.q.thermal_emission" and "hidden.r.internal_photon_loss". Channels exposed at external ports use their network labels.

jump_rate(key)

Return the cached jump rate <L†L>(t) for one resolved channel.

The rate, in 1/ns, is evaluated after the solve from stored states. key can be a resolved key from collapse_channels, a network port, or a "<device>.<channel>" label that identifies one channel. Address a port composed into a network through its external network port.

At an external network port, this rate equals raw_photon_flux only with vacuum input. Dephasing and thermal-absorption channels can also have nonzero jump rates, so this quantity alone is not an excitation-loss rate.

Parameters:

key (channel object or str) – Resolved channel key, external port, or unambiguous local label.

collapse_flux(key)

Deprecated alias for jump_rate().

Parameters:

key (channel object or str) – Resolved channel key.

collapse_integral(key)

Return the cumulative expected jump count for one channel.

The cumulative trapezoid integral of jump_rate() on the result grid. Its last entry is the expected number of jumps over the whole solve.

Parameters:

key (channel object or str) – Resolved channel key.

property states: Any

Return the kept native state history, or tell how to save it.

compact_state(t=None)

Return a reusable saved state without product-space expansion.

Parameters:

t (scalar or None, optional) – Saved time in ns. None selects the final state.

Returns:

Captured excitation state accepted as initial_state by a later solve.

Return type:

CompactState

overlap(target, *, frame='integration')

Return the overlap with target at every stored time.

For ket trajectories, the method returns |<target|psi(t)>|**2. For density matrices, it returns <target|rho(t)|target>. The result stays in the backend’s array module, so it is differentiable. One batched op covers the leading time axis, with no per-point loop.

A ket target is a fixed vector of the integration frame, so a target such as |+⟩ is written in that frame, and chip.bare_state(...) gives a bare product. With frame="lab", the target is a fixed lab-frame vector, such as a dressed state from chip.state(). A label target, such as {"q0": 0, "q1": 1}, is the dressed eigenstate |d_k⟩ of label k, which turns with its label: U(t)†|d_k⟩ exp(−i 2π t Σᵢ fᵢ kᵢ), where U(t)† maps the lab frame into the integration frame and fᵢ are the frame frequencies. An idle dressed state then reads 1 in every frame. A snapshot of the solve’s chip supplies |d_k⟩, with the solve’s approximation and excitation cutoff.

Parameters:

• target (state_like, mapping, or str) – Target ket in the captured full Hilbert space, a compatible CompactState, or a label of local energy levels, which names its dressed state.

• frame ({"integration", "lab"}, default="integration") – Frame in which a ket target is fixed.

amplitude_array(target, *, frame='integration')

Return the phase-sensitive complex projection <target|psi(t)> for kets.

Density-matrix trajectories raise TypeError, because a mixed state has no single phase-sensitive amplitude. For a mixed state, use overlap(). The method uses one batched op, with no per-point loop. Targets and frame are as in overlap(). With frame="lab", the phase is the lab-frame phase. A label target gives a phase that turns at Σᵢ fᵢ kᵢ − E_k, the detuning of the label’s frame energy from its dressed energy E_k.

Parameters:

• target (state_like, mapping, or str) – Target ket in the captured full Hilbert space, a compatible CompactState, or a label of local energy levels, which names its dressed state.

• frame ({"integration", "lab"}, default="integration") – Frame in which a ket target is fixed.

state(t=None, *, dm=False, frame='integration')

Return a kept state, optionally promoted to a density matrix.

Parameters:

• t (float or None, optional) – Saved time in ns. None selects the final state.

• dm (bool, default=False) – Promote a ket to a density matrix.

• frame ({"integration", "lab"}, default="integration") – Frame of the returned state.

state_at(t, *, method='exact', frame='integration')

Return a saved native state in captured product coordinates.

Saved states are in the integration frame of frame. With frame="lab", the method maps the state into the lab frame at its saved time.

Parameters:

• t (scalar) – Saved time in ns.

• method ({"exact", "nearest"}, default="exact") – Time-selection rule. The lookup never interpolates states.

• frame ({"integration", "lab"}, default="integration") – Frame of the returned state.

dm_at(t, *, method='exact', frame='integration')

Return a density matrix at a kept time, and promote kets on demand.

Parameters:

• t (float) – Query time in ns.

• method ({"exact", "nearest"}, default="exact") – Time-selection rule.

• frame ({"integration", "lab"}, default="integration") – Frame of the returned state.

property final_state: Any

Return the last kept state in captured product coordinates.

iq_readout(output, *, means, frequency, receiver, noise_frequencies=None)

Propagate conditional coherent boundary fields through captured output wiring.

means gives one noiseless complex field per outcome, in 1/sqrt(ns), at the selected Markov boundary channel. A mapping gives fields at several boundary channels. Unspecified fields are vacuum. The output line adds its resolved gain, filter loss noise, and amplifier noise. The given means, returned IQ, and receiver transfers follow the VNA engineering convention. Conjugate output(...).raw_amplitude before you use its stationary value as a boundary template. This stationary coherent-state readout model excludes quantum-device correlations and occupied boundary inputs. Use calibrated IQReadout distributions when those effects are included in a detector calibration.

Parameters:

• output (port object or str) – External output reference plane.

• means (array_like or mapping) – Engineering-convention Markov-boundary means in 1/sqrt(ns).

• frequency (scalar) – Carrier frequency in GHz.

• receiver (IQReceiver) – Boxcar receiver and optional digital transfer.

• noise_frequencies (array_like or None, optional) – Two-sided offsets in GHz. None uses the standard grid.

measure(*devices, t=None, basis='energy')

Measure kept states in local energy bases, without further evolution.

Pass multiple devices for joint outcomes, t for an exact saved time, or basis=’solver’. Custom local unitary columns are expressed in the captured energy basis of the stored integration frame. Give one matrix for one device, or a device mapping. No phase-frame conversion is applied. Samples at different times represent independently terminated experiments.

Parameters:

• *devices (device object or str) – Measured devices. An empty selection measures all devices.

• t (scalar, array_like, or None, optional) – Saved time or times in ns. None selects the final state.

• basis ({"energy", "solver"}, array_like, or mapping, default="energy") – Captured local measurement basis.

reduced_state(t, device, *, frame='integration')

Partial-trace a saved state down to one device.

Parameters:

• t (float) – Saved time in ns.

• device (device object or str) – Device to keep.

• frame ({"integration", "lab"}, default="integration") – Frame of the returned state.

property populations: dict[tuple[int, ...], Any]

Return per-basis-state populations |<n1, n2, ...|psi(t)>|**2 over time.

Keys index the solver’s product basis, which is not necessarily the local energy basis. Each value is a native real array over self.times. Use population() for isolated energy-level occupations.

This method requires states="all". For density-matrix trajectories, it reads the DM diagonal at each timestep.

population(device, level=0)

Return occupation of a captured isolated energy level in native arrays.

Parameters:

• device (device object or str) – Captured device.

• level (int, default=0) – Zero-based isolated energy level.

plot_populations(*, trace_out=None, computational=False, ax=None, **kwargs)

Plot per-basis-state populations over time.

Parameters:

• trace_out (device object, str, sequence, or None, optional) – Devices to trace out.

• computational (bool, default=False) – Restrict labels to computational levels.

• ax (matplotlib.axes.Axes or None, optional) – Destination axes.

• **kwargs (Any) – Forwarded to quchip.viz.plot_populations().

plot_state(index, *, trace_out=None, computational=False, mode='population', ax=None, **kwargs)

Plot one stored state as populations or a density matrix.

Parameters:

• index (int) – Saved-state index.

• trace_out (device object, str, sequence, or None, optional) – Devices to trace out.

• computational (bool, default=False) – Restrict labels to computational levels.

• mode ({"population", "density_matrix"}, default="population") – Plot representation.

• ax (matplotlib.axes.Axes or None, optional) – Destination axes.

• **kwargs (Any) – Forwarded to quchip.viz.plot_state().

plot_expectation(*, keys=None, ax=None, **kwargs)

Plot expectation-value traces over time.

Parameters:

• keys (list or None, optional) – Observable keys. None plots every captured trace.

• ax (matplotlib.axes.Axes or None, optional) – Destination axes.

• **kwargs (Any) – Forwarded to quchip.viz.plot_expectation().

plot_wigner(index=-1, *, trace_out=None, ax=None, **kwargs)

Plot the Wigner function of one stored state.

Parameters:

• index (int, default=-1) – Saved-state index.

• trace_out (device object, str, sequence, or None, optional) – Devices to trace out before plotting.

• ax (matplotlib.axes.Axes or None, optional) – Destination axes.

• **kwargs (Any) – Forwarded to quchip.viz.plot_wigner().

check_truncation(*, threshold=0.001)

Deprecated method form of quchip.check_truncation().

quchip 0.6 removes this method. Call quchip.check_truncation(result).

Parameters:

threshold (float, default=1e-3) – Maximum accepted boundary population.

class quchip.results.results.SimulationBatchResult(results, *, shape=None, axes=None)

Bases: BatchResult[SimulationResult]

Ordered, immutable batch of SimulationResult with stacked helpers.

Returned by solve_many() and by any sweep that solves many problems in one call. The batch keeps the iteration order, so each per-element result maps one-to-one onto the input that produced it.

The final_* helpers stack along a new leading batch axis in the backend’s array module. The grid-aware expect() / population() accept reduce='last' for a final-value slice, so a loss function that sums over the batch stays JAX-traceable end-to-end.

Variables:

• results (tuple of SimulationResult) – Per-point results in sweep order.

• shape (tuple of int) – Sweep-grid shape.

• axes (tuple) – Named sweep-axis metadata.

measure(*devices, t=None, basis='energy')

Measure kept states in local energy bases, without further evolution.

Pass multiple devices for joint outcomes, t for an exact saved time, or basis=’solver’. Custom local unitary columns are expressed in the captured energy basis of the stored integration frame. Give one matrix for one device, or a device mapping. No phase-frame conversion is applied. Samples at different times represent independently terminated experiments.

Parameters:

• *devices (device object or str) – Measured devices. An empty selection measures all devices.

• t (scalar, array_like, or None, optional) – Saved time or times in ns. None selects final states.

• basis ({"energy", "solver"}, array_like, or mapping, default="energy") – Captured local measurement basis.

property times: Any

Return shared native coordinates, or tell why time grids are incompatible.

expect(key, index=None, *, reduce=None)

Return expectation traces on the natural sweep grid.

Parameters:

• key (object or str) – Captured observable key.

• index (int or None, optional) – Entry of a list-valued observable.

• reduce ({None, "last", "max", "mean"}, optional) – Reduction along the time axis.

output(exposure)

Return one complete field trace on the natural sweep grid.

Parameters:

exposure (port object or str) – External output reference plane.

population(device, level=0, *, reduce=None)

Return population traces on the natural sweep grid.

Parameters:

• device (device object or str) – Captured device.

• level (int, default=0) – Zero-based isolated energy level.

• reduce ({None, "last", "max", "mean"}, optional) – Reduction along the time axis.

jump_rate(key, *, reduce=None)

Return the jump-rate traces of one channel on the natural sweep grid.

reduce accepts None, "last", "max", or "mean" and acts on the time axis.

Parameters:

• key (channel object or str) – Resolved channel key.

• reduce ({None, "last", "max", "mean"}, optional) – Reduction along the time axis.

collapse_flux(key, *, reduce=None)

Deprecated alias for jump_rate().

Parameters:

• key (channel object or str) – Resolved channel key.

• reduce ({None, "last", "max", "mean"}, optional) – Reduction along the time axis.

collapse_integral(key, *, reduce=None)

Return the cumulative jump counts of one channel on the natural sweep grid.

reduce accepts None, "last", "max", or "mean" and acts on the time axis. reduce="last" returns the expected number of jumps in each solve.

Parameters:

• key (channel object or str) – Resolved channel key.

• reduce ({None, "last", "max", "mean"}, optional) – Reduction along the time axis.

final_overlap_magnitudes(targets, *, frame='integration')

Return final target-state populations without histories.

Targets and frame are as in SimulationResult.overlap().

Parameters:

• targets (sequence of state_like, mapping, or str) – One target ket or label per batch result.

• frame ({"integration", "lab"}, default="integration") – Frame in which a ket target is fixed.

final_amplitudes(targets, *, frame='integration')

Return final complex ket amplitudes without histories.

Targets and frame are as in SimulationResult.amplitude_array().

Parameters:

• targets (sequence of state_like, mapping, or str) – One target ket or label per batch result.

• frame ({"integration", "lab"}, default="integration") – Frame in which a ket target is fixed.

quchip.results.results.wrap_solver_result(solver_result, problem, backend, *, label_targets=None)

Wrap a raw backend SolverResult into a user-facing SimulationResult.

The engine-side SolveProblem carries the metadata needed to rebuild dict-form observables (build_observable_traces()) and to label devices for partial-trace helpers.

Parameters:

• solver_result (SolverResult) – Raw backend solve output.

• problem (SolveProblem) – Frozen request carrying result metadata.

• backend (Backend) – Backend that owns the native states and arrays.

• label_targets (LabelTargets or None, optional) – Record captured when the solve finished. None captures it now.

quchip.results.results.wrap_solver_results_from_batch(solver_results, batch, backend)

Wrap backend results with each batch point’s resolved solve context.

quchip.results.results.capture_label_targets(problem, captured)

Capture the label-target record of a solve, once for each chip and approximation of a batch.

Parameters:

• problem (SolveProblem) – Finished solve request.

• captured (dict) – (chip, approximation, record) entries already captured for this batch, by chip identity. The function adds new ones.