Add helper to plot counts from results

[alessandro-santini]

Add helper for plotting measurement counts and distributions

Summary

This PR adds plot_bitstrings helper for visualizing measurement results as either a count histogram

Features

• Plot measurement outcomes ordered by decreasing frequency.
• Optionally normalize counts into probabilities normalize=True.
• Optionally display only the top N results.
• Support plotting on an already existing Matplotlib axis.
• Allow some customization of the plot title and axis labels
• Allow customization of default bar color.
• Support highlighting a set of bistrings with a different color

Example

from qoolqit.visualization import plot_bitstrings
import matplotlib.pyplot as plt
import numpy as np

np.random.seed(42)

qubits = 4
counts_1 = {}
counts_2 = {}
for i in range(2**qubits):
    counts_1[np.binary_repr(i, width=qubits)] = np.random.randint(0, 10)
    counts_2[np.binary_repr(i, width=qubits)] = np.random.randint(0, 10)
bitstring_max, _ = max(counts_1.items(), key=lambda item: item[1])

fig, ax = plt.subplots(nrows=1, ncols=3, figsize=(12, 4))
plot_bitstrings(counts_1, top=10, ax=ax[0],normalize=True, highlight={bitstring_max:  "#00C887"}, label="barplot")
ax[0].set_title("Distribution 1 (normalized)")
ax[0].set_xlabel("top 10 bitstrings")
ax[0].legend()

plot_bitstrings(counts_1, ax=ax[1], top=6, color="C2", highlight={bitstring_max:"C1"})
ax[1].set_title("Histogram 1 (top 6)")

plot_bitstrings(counts_2, ax=ax[2], highlight={"0010": "tab:orange", "1000": "tab:cyan", "0101": "tab:red"}, top=6)
ax[2].set_title("Histogram 2")
ax[2].legend()

fig.tight_layout()

Output:

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-10 15:12 UTC

[sgrava]

few minors! We are nearly there

[sgrava]

Nice!