Visualisation

The qtest.viz module provides convenience matplotlib plots for measurement distributions — useful in notebooks and when triaging a failed assert_distribution_close(). It requires the optional viz extra:

pip install 'qtest-quantum[viz]'

matplotlib is imported lazily, so importing qtest does not require it.

Public API

plot_distribution

Bar-plot a single measurement distribution.

plot_distribution_comparison

Grouped bar-plot of measured vs expected distributions.

Example

from qtest.viz import plot_distribution_comparison

measured = {"00": 0.48, "01": 0.01, "10": 0.02, "11": 0.49}
expected = {"00": 0.5, "11": 0.5}
ax = plot_distribution_comparison(measured, expected, title="Bell state")
ax.figure.savefig("bell.png")

Reference

Visualisation helpers for quantum measurement distributions.

These are convenience plotting functions for use in notebooks, debugging sessions, and test-failure triage. They require matplotlib, installed via the optional viz extra:

pip install 'qtest[viz]'

matplotlib is imported lazily, so importing qtest.viz (or qtest) does not require it — only calling a plotting function does. Each function draws onto a provided Axes (or a freshly created one) and returns that Axes so callers can further customise or save the figure.

qtest.viz.plot_distribution(distribution, ax=None, *, title=None, color=None, sort_keys=True)[source]

Bar-plot a single measurement distribution.

Parameters:

  • distribution (Mapping[str, float]) – Mapping {bitstring: probability} (or counts).

  • ax (Any | None) – Existing matplotlib Axes to draw on. A new one is created if None.

  • title (str | None) – Optional axes title.

  • color (str | None) – Optional bar colour.

  • sort_keys (bool) – Sort bitstrings lexicographically (default) for a stable x-axis.

Return type:

matplotlib.axes.Axes

qtest.viz.plot_distribution_comparison(measured, expected, ax=None, *, title=None)[source]

Grouped bar-plot of measured vs expected distributions.

Outcomes present in either distribution are shown side by side, making it easy to eyeball where a circuit’s sampled output drifts from the target — handy when triaging an assert_distribution_close failure.

Return type:

matplotlib.axes.Axes

Parameters: