quchip.viz.results

Plots of simulation results: populations, snapshots, expectations, Wigner.

These helpers turn a backend-agnostic SimulationResult into Matplotlib figures, independent of the solver backend.

References

  • Nielsen & Chuang, Quantum Computation and Quantum Information, Cambridge University Press (2010) — density matrices, populations.

  • Wigner, “On the Quantum Correction for Thermodynamic Equilibrium”, Phys. Rev. 40, 749 (1932) — original Wigner-function definition.

  • Cahill & Glauber, “Density Operators and Quasiprobability Distributions”, Phys. Rev. 177, 1882 (1969) — Laguerre-polynomial expansion used by _wigner_from_density_matrix().

  • Leonhardt, Essential Quantum Optics, Cambridge University Press (2010) — modern continuous-variable treatment of the Wigner function.

Functions

plot_expectation(result, *[, keys, ax, ...])

Plot dict-form expectation values over time.

plot_populations(result, *[, trace_out, ...])

Plot basis-state populations over time.

plot_sparameters(result[, pairs, select, ...])

Plot entries from a small-signal scattering result.

plot_state(result, index, *[, trace_out, ...])

Plot a single stored state at time-index index.

plot_wigner(result[, index, trace_out, ...])

Plot the Wigner quasi-probability distribution of a stored state.
quchip.viz.results.plot_populations(result, *, trace_out=None, computational=False, ax=None, linewidth=2.5, legend=True, colors=None, threshold=0.01)[source]

Plot basis-state populations over time.

The x-axis is time (ns) and the y-axis is the population p_n(t) = Tr(|n><n| rho(t)). One line is drawn for each represented-basis ket |n> = |n_1 n_2 ...> of the retained subsystems. States whose peak population stays below threshold are hidden. Set threshold to 0 to show all states.

Parameters:

  • result (SimulationResult) – Output of quchip.engine.simulate().

  • trace_out (device, label, or list thereof, optional) – Subsystems to partial-trace over before computing populations. Accepts device objects or their string labels. The solver call must use states="all".

  • computational (bool) – When True, restrict computational subsystems to their {|0>, |1>} subspace.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on. When None, a new figure is created.

  • linewidth (float) – Line width for all population traces.

  • legend (bool) – Draw a legend of the visible states.

  • colors (dict, optional) – Per-state colour overrides, keyed by the internal basis-state tuples. States not in the dict use a tab20 cycle.

  • threshold (float) – Populations whose maximum over time is below this value are omitted.

Returns:

The figure that holds the population-trace axes (ax.figure when ax was given).

Return type:

Figure

Raises:

  • RuntimeError – trace_out is given but no states were stored (pass states="all" to the solver).

  • ValueError – trace_out would remove all subsystems.

quchip.viz.results.plot_state(result, index, *, trace_out=None, computational=False, mode='population', ax=None, cmap='RdBu_r', color=None)[source]

Plot a single stored state at time-index index.

Two modes are supported:

  • "population": a bar chart of diagonal elements p_n.

  • "dm": side-by-side heatmaps of Re(rho) and Im(rho) with the divergent colormap cmap. Both heatmaps share one symmetric normalization (vmin=-m, vmax=+m for m = max(|Re(rho)|, |Im(rho)|)), so their colours compare directly. Equal saturation in the two panels means equal magnitude.

If computational and non-computational subsystems are both present, pass trace_out to focus on a target register. Alternatively, set computational = True to restrict computational devices to the {|0>, |1>} subspace (see Nielsen & Chuang, Ch. 2).

Parameters:

  • result (SimulationResult) – Output of quchip.engine.simulate(), with states="all".

  • index (int) – Stored-time index to plot. Python-style negative indexes are supported (-1 is the last stored time). The index must satisfy -N <= index < N for N = len(result.times).

  • trace_out (device, label, or list thereof, optional) – Subsystems to partial-trace over before plotting.

  • computational (bool) – When True, restrict computational subsystems to their {|0>, |1>} subspace.

  • mode ({"population", "dm"}) – The representation to draw.

  • ax (matplotlib.axes.Axes, optional) – For mode="population": a single axes (or None for a new figure). For mode="dm": an iterable of exactly two axes (real_ax, imag_ax) (or None for a new 1x2 figure).

  • cmap (str) – Divergent colormap for mode="dm" heatmaps.

  • color (str, optional) – Bar colour override for mode="population". The default is a tab10 cycle per state.

Returns:

The figure that holds the plotted axes (ax.figure when ax was given).

Return type:

Figure

Raises:

  • IndexError – index is outside [-N, N) for N = len(result.times).

  • ValueError – mode is not "population" or "dm", or trace_out would remove all subsystems.

  • RuntimeError – No states were stored (pass states="all" to the solver).

quchip.viz.results.plot_expectation(result, *, keys=None, ax=None, linewidth=2.5, legend=True, real=True)[source]

Plot dict-form expectation values over time.

The x-axis is time (ns). The y-axis is observable_traces [key].values, the post-processed recorded trace for each observable O registered in the solver’s e_ops dict, which is not always Tr(O rho(t)).

.values depends on how you requested the observable and can already include demodulation, phase correction, or band summation (see ObservableTrace). Its .raw field holds the unprocessed quantity. When real is True (the default), only Re of the trace is drawn. When real is False, the real part (solid) and the imaginary part (dashed, lower alpha) are drawn in the same colour per key.

Parameters:

  • result (SimulationResult) – Output of quchip.engine.simulate(), with e_ops passed as a dict.

  • keys (list, optional) – Each entry is a bare key ("cav") or a (key, index) tuple that selects one element of a list-valued observable. Entries are matched against the registered observable_traces keys first (see _collect_expectation_traces()). resolve_label resolves string keys and device/drive keys, so the two forms are interchangeable. The default is all registered traces.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on. When None, a new figure is created.

  • linewidth (float) – Line width for all traces.

  • legend (bool) – Draw a legend of the plotted keys.

  • real (bool) – When True, draw only the real part of each trace. When False, draw the real (solid) and imaginary (dashed) parts.

Returns:

The figure that holds the expectation-trace axes (ax.figure when ax was given).

Return type:

Figure

Raises:

  • TypeError – e_ops was not passed as a dict (observable_traces is None).

  • KeyError – An entry in keys does not resolve to a registered trace or a valid (key, index) selector.

quchip.viz.results.plot_wigner(result, index=-1, *, trace_out=None, xvec=None, yvec=None, ax=None, cmap='RdBu_r', colorbar=True)[source]

Plot the Wigner quasi-probability distribution of a stored state.

The axes are the phase-space quadratures x (position-like) and p (momentum-like). The colourmap is divergent and symmetric about zero, so negative regions, the hallmark of non-classical states, are easy to see.

Without xvec, the plot window is sized from the reduced state’s mean photon number <n> = Tr(rho n_hat) and extends to at least +/-3. The mean photon number is computed directly from diag(rho).

Exactly one subsystem must remain after trace_out. A Wigner function is a single-mode phase-space picture, and its basis indices are read directly as photon numbers n = 0, 1, 2, .... The function checks this condition.

One more precondition cannot be seen from the result metadata, so the function does not check it: the retained subsystem’s represented basis must be a photon-number ladder. This holds for a bosonic mode such as Resonator, but not for a device whose represented basis is not Fock, for example a charge-basis or flux-basis qubit. If you pass such a device, the function silently makes a Wigner-shaped plot without physical meaning.

Parameters:

  • result (SimulationResult) – Output of quchip.engine.simulate(), with states="all".

  • index (int) – Stored-time index to plot. Python-style negative indexes are supported (-1, the default, is the last stored time). The index must satisfy -N <= index < N for N = len(result.times).

  • trace_out (device, label, or list thereof, optional) – Subsystems to partial-trace over before plotting. Required when more than one subsystem is stored (see Raises).

  • xvec (ndarray, optional) – Phase-space grids for the x/p quadratures. The default is an automatically sized, equally spaced grid (see above). If only xvec is given, yvec defaults to xvec.

  • yvec (ndarray, optional) – Phase-space grids for the x/p quadratures. The default is an automatically sized, equally spaced grid (see above). If only xvec is given, yvec defaults to xvec.

  • ax (matplotlib.axes.Axes, optional) – Existing axes to draw on. When None, a new figure is created.

  • cmap (str) – Divergent colormap, symmetric about zero.

  • colorbar (bool) – Attach a colorbar.

Returns:

The figure that holds the Wigner-function axes (ax.figure when ax was given).

Return type:

Figure

Raises:

  • IndexError – index is outside [-N, N) for N = len(result.times).

  • ValueError – More or fewer than one subsystem remains after trace_out. The message lists the retained device labels and a trace_out value that isolates a single one of them.

  • RuntimeError – No states were stored (pass states="all" to the solver).

References

  • Wigner, Phys. Rev. 40, 749 (1932).

  • Cahill & Glauber, Phys. Rev. 177, 1882 (1969).

  • Leonhardt, Essential Quantum Optics (2010), Ch. 3.

quchip.viz.results.plot_sparameters(result, pairs=None, *, select=None, kind='db_phase', axes=None)[source]

Plot entries from a small-signal scattering result.

Parameters:

  • result (SParameterResult) – Result that VNA.sweep() returns. The function rejects other result types.

  • pairs (list of (output, input), optional) – Matrix entries to draw. If omitted with exactly two planes, all four entries are drawn. Otherwise, the first input column is drawn, up to six entries.

  • select (dict of str to int, optional) – Indices on sweep axes other than frequency. Omitted axes use index 0, and the plot title shows those defaults. Frequency stays the x axis, and you cannot select it.

  • kind ({"db_phase", "magnitude", "iq"}) – "db_phase" stacks 20 log10|S| in dB above unwrapped phase in degrees. "magnitude" draws |S|. "iq" draws Im S against Re S.

  • axes (matplotlib.axes.Axes or iterable of matplotlib.axes.Axes, optional) – Existing axes to draw on: two for "db_phase" and one for the other kinds. When None, create the necessary axes.

Returns:

The figure that contains the plots.

Return type:

Figure

Raises:

  • TypeError – result is not an SParameterResult.

  • ValueError – kind is not "db_phase", "magnitude", or "iq", select names "frequency", or no sweep axis remains for the x axis.

  • KeyError – select contains an unknown sweep-axis name.