Pretty-print for `Statevec` and `DensityMatrix`

[matulni]

This issue is part of unitaryHACK 2026. You have to be registered to participate. Please read carefully the unitaryHack rules before submitting a PR for this issue.

A note about AI Slop: while we are open to collaboration with LLMs for unitaryHACK, fully AI-generated PRs are not acceptable. It is at the maintainers' discretion whether or not LLM-generated PRs are the right fit for the issues, and those that appear fully AI-generated may be immediately rejected. Please read carefully the AI policy if you are using LLMs for your work.

Context

Simulating a quantum circuit or an MBQC pattern leads to an output state that is represented either as a statevector (Statevec class) or a density matrix (DensityMatrix class). These classes embed a numpy array that the users may want to print to check the computation. The Statevec class provides a method to_dict() to represent the statevector as a dictionary where values close to zero has been filtered.

>>> c = Circuit(2)
>>> c.h(0)
>>> c.cz(0, 1)
>>> c.simulate_statevector().statevec.to_dict()
{'00': np.complex128(0.7071067811865474+0j), '01': np.complex128(0.7071067811865474+0j)}

We would like a method to pretty-print this statevector in a more user-friendly way: instead of the floating-point complex number 0.7071067811865474+0j, we would prefer to pretty-print it as $\frac {\sqrt 2} 2$.

Tasks

• Define a function in pretty_print.py to pretty-print a complex number. This function should take an output parameter of type OutputFormat. We would like common values to be rendered nicely: that includes fractions (0.25 should be printed as $\frac 1 4$), square roots (0.70710678 should be printed as $\frac {\sqrt 2} 2$) and exponentials (0.5 + 0.8660254j should be printed as $\mathrm e^{\mathrm i \frac \pi 3}$.
• Define a function in pretty_print.py to pretty-print a statevector using the previously defined function and Statevec.to_dict. Define a method draw in Statevec that calls this function. Use the ket-notation with an ENCODING parameter as for Statevec.to_dict.
• Define a function in pretty_print.py to pretty-print a density matrix. Define a method draw in DensityMatrix that calls this function.

Acceptance criteria

For the PR to be considered for review:

• It should pass the CI, including linting and type-checking.

• New functions should be tested and documented appropriately following numpy style.

• Unitary Hack AI use guidelines should be respected.

• Author should be ready to engage in a feedback loop.

For the PR to be accepted:

• All provided feedback should have been implemented.

[unsyncedot]

Hi! I'd like to work on this issue.
This is my first time contribution. So, I'll take a look at the implementation and submit a PR if everything goes well.

[thierry-martinez]

@unsyncedot, thank you for your willingness to contribute. However, #524 is already on a solid path toward being merged to address this issue, so I recommend that you don't spend too much time on it and instead look for another UnitaryHack bounty that isn't as close to being claimed by someone else.

[Vinny010]

Hi @thierry-martinez - thanks for the review! I'd be glad to take this one. I've implemented pretty-printing for Statevec and DensityMatrix in #524 and just pushed an update addressing your latest remarks (the \ket{} macro, i-leading imaginary parts such as i/2 and -i?2/2, preferring the Cartesian form over a radius-prefixed exponential, and merging the format-specific tests into a single Mapping[OutputFormat, str] parametrization). Please feel free to assign the issue to me.