dbac.plotting¶

Every figure in the paper and the notebooks is drawn by a function in this package. All functions are re-exported at the top level, so from dbac.plotting import plot_gci_results works for every function on this page. Functions that create a figure accept save_path= to save it.

See Plotting for examples of the most common plots.

`style.use_paper_style`([use_tex, font_size, ...])	Apply the rcParams used for the figures in the DBAC paper.
`style.figure_size`([journal, column, aspect])	Return (width, height) in inches for a figure sized to fit journal.
`cooling.plot_single_energy_curve`(...[, ...])	Plot a single DB-QITE energy-vs-theta curve against the un-cooled baseline, optionally overlaid with experimental data points.
`cooling.plot_energy_vs_theta`(theta_angles, ...)	Plot the data-qubit energy after DB-QITE against the initialization angle theta, for one or more circuits/configurations.
`cooling.plot_fidelity_fidelity`(...[, ...])	"Fidelity-fidelity" plot: final-state fidelity with the ground state against initial-state fidelity, for one or more DB-QITE/HBAC configurations.
`cooling.plot_energy_grid`(theta_angles, ...)	Lay out several plot_single_energy_curve-style panels on a grid, e.g. one panel per number of quantum instructions n used in DB-QITE.
`cooling.plot_ideal_dme_summary`(...[, ...])	Three-panel summary figure for the ideal-DME DBAC recursion: (a) the fidelity-fidelity plot across recursion depths k, (b) how the max-excitation fidelity improves with k, and (c) the optimized step size s against the number of Trotter steps M.
`cooling.plot_optimal_s_vs_M`(optimal_s_kM, *)	Plot the optimized DB-QITE step size s against the number of DME Trotter steps M, one curve per recursion depth k.
`cooling.plot_max_excitation_vs_k`(max_ext_list, *)	Plot "how far from the ground state the initial state can still be while reaching the target fidelity" (1 - max-excitation fidelity) against the DB-QITE recursion depth k.
`cooling.plot_hbac_fidelity_fidelity`(...[, ...])	Fidelity-fidelity plot comparing HBAC on pure vs. depolarized ("mixed") input states, for different numbers of cooling rounds.
`circuits.draw_dbac_circuit`(name, **kwargs)	Draw circuit "A", "B" or "C" of the paper's Fig.
`circuits.draw_circuit`(spec, *[, ax, ...])	Draw one circuit described by spec (an entry of DBAC_CIRCUITS).
`gci.plot_gci_results`(*results, target_energy)	Plot energy or fidelity vs evolution duration for one or more GCI runs.
`bloch.plot_bloch_trajectory`(states, texts, *)	Plot a sequence of states (e.g. the DB-QITE recursion states returned by GCI.execute_gci) on the Bloch sphere, one latitude circle per state, and optionally a dashed latitude circle marking a target fidelity with `\|0>`.
`bloch.plot_bloch_sphere`([font_size])	Plots the Bloch sphere with the surface, latitude and longitude lines, and the `\|0>` and `\|1>` labels at the poles.
`bloch.plot_bloch_vector`(state, ax[, color, ...])	Plots the Bloch vector as a red arrow on the Bloch sphere along with a latitude circle, and optionally adds a text label to the latitude circle.
`bloch.density_matrix_to_bloch`(state)	Convert a 2x2 density matrix to Bloch vector coordinates (u, v, w).
`bloch.add_3d_outline`(ax, x, y, z[, color, ...])	Adds a silhouette outline to a 3D surface by detecting edge points.
`ptm.plot_ptm`(ptm, labels, *[, ax, title, ...])	Plot the real part of a Pauli-transfer matrix (PTM) as a heatmap.
`ptm.plot_ptm_sweep`(ptms, titles, labels, *)	Plot several PTMs side by side (e.g. a sweep over a rotation angle), sharing a single colorbar.
`ptm.plot_process_matrix`(m, basis_name[, ax, ...])	Plots a process matrix using color-coded phases and magnitudes.
`dme.plot_dme_channel_norms`(norms, *[, ...])	Plot the trace-norm distance between an exact (matrix-exponential) DME step and one or more approximate implementations, as a function of the number of Trotter steps M.

Style¶

Paper-ready fonts, line widths and figure sizes.

use_paper_style(use_tex=True, font_size=10, figsize=None)[source]¶: Apply the rcParams used for the figures in the DBAC paper.

figure_size(journal='PRD', column='onecol', aspect=1.5714285714285714)[source]¶: Return (width, height) in inches for a figure sized to fit journal.

JOURNAL_WIDTHS¶: Column widths in inches, JOURNAL_WIDTHS[journal][column].

Cooling curves¶

Energy or fidelity after DBAC (or HBAC) against the initial state: the paper’s main plots.

plot_single_energy_curve(theta_angles, initial_energy, label, curve, color, marker, *, experimental=None, xticks=None, xtick_labels=None, annotate_poles=True, figsize=None, save_path=None, show=False)[source]¶

Plot a single DB-QITE energy-vs-theta curve against the un-cooled baseline, optionally overlaid with experimental data points.

Parameters:

theta_angles (sequence[float]) – Initialization angle (radians) per sample.
initial_energy (sequence[float]) – Energy of the un-cooled initial state.
label (str) – Name of the curve. Currently unused: the legend always reads “Analytical”.
curve (sequence[float]) – Analytical final-energy curve.
color – Styling for the analytical curve / experimental markers.
marker – Styling for the analytical curve / experimental markers.
experimental (tuple[sequence, sequence], optional) – (theta, energy) experimental data points to overlay as open markers.
xticks (sequence, optional) – Custom tick marks.
xtick_labels (sequence, optional) – Custom tick marks.
annotate_poles (bool) – Annotate the |1><1| and |0><0| corners.
save_path (str, optional) – If given, saves the figure.
show (bool) – If True, calls plt.show() (useful in a notebook).

Returns:

matplotlib.axes.Axes

plot_energy_vs_theta(theta_angles, initial_energy, results, *, colors=None, markers=None, target_energy=None, xlabel='$\\theta,$ Angle of initialisation', ylabel='Data qubit energy', xticks=None, xtick_labels=None, annotate_poles=True, ax=None, save_path=None)[source]¶

Plot the data-qubit energy after DB-QITE against the initialization angle theta, for one or more circuits/configurations.

Parameters:

theta_angles (sequence[float]) – Initialization angle (radians) per sample.
initial_energy (sequence[float]) – Energy of the un-cooled initial state.
results (dict[str, sequence[float]]) – label -> final energy curve.
colors (sequence, optional) – Styling cycled over results.
markers (sequence, optional) – Styling cycled over results.
target_energy (float, optional) – Draws a dashed horizontal reference line.
xticks (sequence, optional) – Custom tick marks (e.g. in units of pi).
xtick_labels (sequence, optional) – Custom tick marks (e.g. in units of pi).
annotate_poles (bool) – Annotate the |1><1| and |0><0| corners.
ax (matplotlib.axes.Axes, optional) – Axis to draw on; creates one if None.
save_path (str, optional) – If given, saves the figure.

Returns:

matplotlib.axes.Axes

plot_fidelity_fidelity(fidelities_initial, initial_curve, results, *, colors=None, markers=None, target_fidelity=None, mark_max_excitation=False, xlabel='Fidelity of initial state\nwith ground state', ylabel='Fidelity of final state\nwith ground state', annotate_poles=True, markersize=6, figsize=(5.5, 4), ax=None, save_path=None)[source]¶

“Fidelity-fidelity” plot: final-state fidelity with the ground state against initial-state fidelity, for one or more DB-QITE/HBAC configurations. This is the main result plot of the DBAC paper (Fig. 4).

Parameters:

fidelities_initial (sequence[float]) – Fidelity of each initial state with |0>.
initial_curve (sequence[float]) – Baseline “no cooling” fidelity to plot as a dotted reference line (equal to fidelities_initial for a noiseless initial state).
results (dict[str, sequence[float]]) – label -> final-state fidelities, one curve per circuit/configuration, in the order to be styled.
colors (sequence, optional) – Styling cycled over results.
markers (sequence, optional) – Styling cycled over results.
target_fidelity (float, optional) – Draws a dashed horizontal reference line.
mark_max_excitation (bool) – If True (requires target_fidelity), draws for each curve a vertical dashed line at the largest fidelities_initial for which the final fidelity still reaches target_fidelity, and returns those positions.
annotate_poles (bool) – Annotate the |1><1| and |0><0| corners.
ax (matplotlib.axes.Axes, optional) – Axis to draw on; creates one if None.
save_path (str, optional) – If given, saves the figure.

Returns:

matplotlib.axes.Axes, or (Axes, list[float | None]) if mark_max_excitation.

plot_energy_grid(theta_angles, initial_energy, plot_dict, plot_map, *, colors=None, markers=None, target_energy=None, nrows=2, ncols=2, figsize=None, titles=None, save_path=None)[source]¶

Lay out several plot_single_energy_curve-style panels on a grid, e.g. one panel per number of quantum instructions n used in DB-QITE.

Parameters:

theta_angles (sequence[float]) – Initialization angle (radians) per sample.
initial_energy (sequence[float]) – Energy of the un-cooled initial state.
plot_dict (dict[str, sequence[float]]) – label -> final energy curve.
plot_map (dict[int, str]) – Maps a flattened subplot index to a label in plot_dict; indices not present are left blank.
colors (sequence, optional) – Styling cycled over plot_map.
markers (sequence, optional) – Styling cycled over plot_map.
target_energy (float, optional) – Draws a dashed horizontal reference line.
nrows (int) – Grid shape.
ncols (int) – Grid shape.
titles (dict[int, str], optional) – Title per subplot index.
save_path (str, optional) – If given, saves the figure.

Returns:

(fig, axes)

plot_ideal_dme_summary(fidelities_initial, initial_curve, dict_fid, optimal_s_kM, *, target_fidelity, colors=None, markers=None, save_path=None)[source]¶

Three-panel summary figure for the ideal-DME DBAC recursion: (a) the fidelity-fidelity plot across recursion depths k, (b) how the max-excitation fidelity improves with k, and (c) the optimized step size s against the number of Trotter steps M. This reproduces the DBAC paper’s “ideal DME” rainbow-colored figure.

Parameters:

fidelities_initial (sequence[float]) – Fidelity of each initial state with |0>.
initial_curve (sequence[float]) – Baseline “no cooling” fidelity curve.
dict_fid (dict[str, sequence[float]]) – label (e.g. ‘k=1’, ‘k=2’, …) -> final-state fidelity curve.
optimal_s_kM (np.ndarray) – Shape (k_max, M_max) optimal step sizes.
target_fidelity (float) – Target fidelity used to mark max-excitation points.
colors (sequence, optional) – Styling cycled over dict_fid.
markers (sequence, optional) – Styling cycled over dict_fid.
save_path (str, optional) – If given, saves the figure.

Returns:

matplotlib.figure.Figure

plot_optimal_s_vs_M(optimal_s_kM, *, colors=None, markers=None, markersize=6, ax=None)[source]¶

Plot the optimized DB-QITE step size s against the number of DME Trotter steps M, one curve per recursion depth k.

Parameters:

optimal_s_kM (np.ndarray) – Shape (k_max, M_max) array of optimal s values, as produced by transposing optimal_s_Mk.
colors (sequence, optional) – Styling cycled over k.
markers (sequence, optional) – Styling cycled over k.
ax (matplotlib.axes.Axes, optional) – Axis to draw on; creates one if None.

Returns:

matplotlib.axes.Axes

plot_max_excitation_vs_k(max_ext_list, *, target_fidelity=0.9, colors=None, markers=None, markersize=6, ax=None)[source]¶

Plot “how far from the ground state the initial state can still be while reaching the target fidelity” (1 - max-excitation fidelity) against the DB-QITE recursion depth k.

Parameters:

max_ext_list (sequence[float]) – Max-excitation fidelity per k (output of plot_fidelity_fidelity(…, mark_max_excitation=True)).
target_fidelity (float) – The target fidelity max_ext_list was computed for, shown in the y-axis label.
colors (sequence, optional) – Styling cycled over k.
markers (sequence, optional) – Styling cycled over k.
ax (matplotlib.axes.Axes, optional) – Axis to draw on; creates one if None.

Returns:

matplotlib.axes.Axes

plot_hbac_fidelity_fidelity(fidelities_initial, baselines, results, *, markevery=4, title=None, save_path=None)[source]¶

Fidelity-fidelity plot comparing HBAC on pure vs. depolarized (“mixed”) input states, for different numbers of cooling rounds.

Parameters:

fidelities_initial (sequence[float]) – Fidelity of each initial (pure) state with |0>.
baselines (dict[str, sequence[float]]) – label -> dotted reference curve (e.g. ‘Initial pure state’, ‘Initial mixed state’).
results (dict[str, sequence[float]]) – label -> HBAC output fidelity curve.
markevery (int) – Marker spacing for the result curves.
title (str, optional) – Plot title.
save_path (str, optional) – If given, saves the figure.

Returns:

matplotlib.axes.Axes

DEFAULT_COLORS¶: Default palette, cycled over the curves of a plot.

DEFAULT_MARKERS¶: Default markers, cycled over the curves of a plot.

Circuits¶

Drawings of the hardware circuits, without a qiskit or LaTeX dependency.

draw_dbac_circuit(name, **kwargs)[source]¶: Draw circuit “A”, “B” or “C” of the paper’s Fig. 4. See draw_circuit.

draw_circuit(spec, *, ax=None, data_label=True, fontsize=9)[source]¶

Draw one circuit described by spec (an entry of DBAC_CIRCUITS).

Parameters:

spec (dict) – Circuit description, see the module docstring.
ax (matplotlib.axes.Axes, optional) – Axis to draw on; creates a figure if None.
data_label (bool) – Mark the data qubit at the right-hand end of its wire.
fontsize (float) – Font size of the gate labels.

Returns:

matplotlib.axes.Axes

DBAC_CIRCUITS¶: The circuits A, B and C of the paper’s Fig. 4. Each has n qubits, the (0-based) data qubit whose energy is read out, the barriers (columns after which a dashed line separates the DBAC steps), and ops: gates as (column, qubits, label), where a gate on two qubits is drawn as one tall box.

Recursion output¶

plot_gci_results(*results, target_energy, mode='Default', save_path=None)[source]¶

Plot energy or fidelity vs evolution duration for one or more GCI runs.

Parameters:

*results – Output tuples from GCI.execute_gci().
target_energy (float) – The energy of the target (ground) state, used to draw a horizontal reference line in ‘Default’ mode.
mode (str) – ‘Default’ for energy vs duration, ‘Fidelity’ for fidelity vs duration.
save_path (str, optional) – If given, saves the figure to this path.

Bloch sphere¶

plot_bloch_trajectory(states, texts, *, colors=None, marker=None, marker_color=None, target_fidelity=None, save_path=None)[source]¶

Plot a sequence of states (e.g. the DB-QITE recursion states returned by GCI.execute_gci) on the Bloch sphere, one latitude circle per state, and optionally a dashed latitude circle marking a target fidelity with |0>.

Parameters:

states (sequence) – Density matrices or state vectors, one per step.
texts (sequence[str]) – Label for each state’s latitude circle.
colors (sequence[str], optional) – Color per state. Defaults to [‘C0’, ‘#2c0084’, ‘#7a0085’, ‘#006f7a’].
marker (str, optional) – Marker for the first (initial) state.
marker_color (str, optional) – Marker color for the first state.
target_fidelity (float, optional) – If given, draws a dashed latitude circle at this fidelity with |0>.
save_path (str, optional) – If given, saves the figure to this path.

Returns:

The 3D axes with the trajectory drawn.

Return type:

matplotlib.axes._axes.Axes

plot_bloch_sphere(font_size=20)[source]¶

Plots the Bloch sphere with the surface, latitude and longitude lines, and the |0> and |1> labels at the poles.

Parameters: ax (matplotlib.axes._axes.Axes): The axes on which to plot the Bloch sphere. font_size (int): Font size for labels.

plot_bloch_vector(state, ax, color='r', num_points=100, text=None, marker=None, marker_color='k')[source]¶

Plots the Bloch vector as a red arrow on the Bloch sphere along with a latitude circle, and optionally adds a text label to the latitude circle.

Parameters: state (ndarray): The density matrix or state vector (2x2) for the system. ax (matplotlib.axes._axes.Axes): The axes on which to plot the vector. color (str): The color of the Bloch vector and latitude circle. num_points (int): Number of points to plot for the latitude circle. text (str or None): Text to place on the latitude circle (default is None).

density_matrix_to_bloch(state)[source]¶

Convert a 2x2 density matrix to Bloch vector coordinates (u, v, w).

Parameters: density_matrix (ndarray): A 2x2 density matrix.

Returns: tuple: The Bloch vector components (u, v, w).

add_3d_outline(ax, x, y, z, color='black', linewidth=2)[source]¶

Adds a silhouette outline to a 3D surface by detecting edge points.

Parameters: ax : Matplotlib 3D axis x, y, z : 2D arrays defining the surface color : str, outline color linewidth : int, thickness of the outline

Returns: ax : Updated 3D axis with the outline

Process matrices¶

Pauli-transfer matrices from process tomography, as heatmaps.

plot_ptm(ptm, labels, *, ax=None, title=None, cmap='RdBu_r', vmin=-1, vmax=1)[source]¶

Plot the real part of a Pauli-transfer matrix (PTM) as a heatmap.

Parameters:

ptm (np.ndarray) – The (real or complex) Pauli-transfer matrix.
labels (list[str]) – Tick labels for both axes (e.g. pauli_labels_2q).
ax (matplotlib.axes.Axes, optional) – Axis to plot on. Creates one if None.
title (str, optional) – Title of the plot.
cmap (str) – Colormap for the heatmap.
vmin (float) – Color scale limits.
vmax (float) – Color scale limits.

Returns:

The figure, axis, and the imshow artist (useful for attaching a shared colorbar when plotting several PTMs side by side).

Return type:

(fig, ax, image)

plot_ptm_sweep(ptms, titles, labels, *, figsize=(18, 6), colorbar_label='Real PTM', save_path=None)[source]¶

Plot several PTMs side by side (e.g. a sweep over a rotation angle), sharing a single colorbar.

Parameters:

ptms (sequence[np.ndarray]) – One Pauli-transfer matrix per panel.
titles (sequence[str]) – Title for each panel.
labels (list[str]) – Shared tick labels (e.g. pauli_labels_2q).
figsize (tuple) – Size of the overall figure.
colorbar_label (str) – Label of the shared colorbar.
save_path (str, optional) – If given, saves the figure to this path.

Returns:

The figure and the array of axes.

Return type:

(fig, axes)

plot_process_matrix(m: ndarray, basis_name: list[str], ax=None, title=None, base: int = 2)[source]¶

Plots a process matrix using color-coded phases and magnitudes.

Parameters:

m (np.ndarray) – The process matrix to plot.
basis_name (list[str]) – List of Pauli basis labels.
ax (matplotlib.axes.Axes, optional) – Axis to plot on. Creates one if None.
title (str, optional) – Title of the plot.
base (int) – Base for computing qubit number from matrix size.

pauli_labels¶: Tick labels for the single-qubit Pauli basis.

pauli_labels_2q¶: Tick labels for the two-qubit Pauli basis, in Kronecker order.

DME accuracy¶

plot_dme_channel_norms(norms, *, markers=None, colors=None, show_final_value=False, xlabel='M', ylabel='$|| e^{-it\\rho}\\sigma e^{it\\rho} - \\hat{E}_t^{(\\rho)}(\\sigma) ||$', legend=True, grid=True, save_path=None)[source]¶

Plot the trace-norm distance between an exact (matrix-exponential) DME step and one or more approximate implementations, as a function of the number of Trotter steps M.

Parameters:

norms (dict[str, sequence[float]]) – label -> norm values vs. M.
markers (sequence, optional) – Styling cycled over norms.
colors (sequence, optional) – Styling cycled over norms.
show_final_value (bool) – If True, appends the final norm value to each curve’s legend entry.
xlabel (str) – Axis labels.
ylabel (str) – Axis labels.
legend (bool) – Whether to draw a legend.
grid (bool) – Whether to draw a grid.
save_path (str, optional) – If given, saves the figure.

Returns:

matplotlib.axes.Axes