Pretty-printing for Statevec and DensityMatrix (closes #501)

[Vinny010]

Closes #501.

Adds human-friendly rendering of amplitudes and states:

• complex_to_str — renders common values exactly (1/4, √2/2, e^(iπ/3)) via a square-then-rationalize heuristic, reusing the existing angle_to_str for the exponential phase. Supports ASCII / Unicode / LaTeX.
• statevec_to_str + Statevec.draw — ket notation, honouring the to_dict encoding parameter (e.g. √2/2|00⟩ + √2/2|01⟩).
• density_matrix_to_str + DensityMatrix.draw — column-aligned grid (ASCII/Unicode) or LaTeX pmatrix.
• Tests covering the issue examples plus edge cases (zero, negative, pure imaginary, LaTeX, decimal fallback, symbolic), with numpy-style docstrings.

Passes ruff check, ruff format, mypy --strict, and pytest locally (167 tests in the affected suites).

Design points I'd value feedback on:

• draw() returns a str, consistent with the existing to_unicode / to_latex style.
• The complex formatter prefers exponential form over cartesian when both magnitude and phase are recognized.

Happy to adjust either.

Developed with LLM assistance, reviewed and tested by me.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.17%. Comparing base (fcdb8f4) to head (78a48e7).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #524      +/-   ##
==========================================
+ Coverage   88.85%   89.17%   +0.31%     
==========================================
  Files          49       49              
  Lines        7135     7341     +206     
==========================================
+ Hits         6340     6546     +206     
  Misses        795      795              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[thierry-martinez]

Thank you very much for your contribution!

Codecov has detected that some parts of your code are not tested.

As you may have noticed, PR #503 and PR #523 address the same issue (#501). We invite you to cross‑review each other's work: PR reviews are an inherent part of software development, just as important as writing code. Moreover, this review process will help you position your PR relative to the others, allowing us to determine which contribution best addresses the issue.

[Vinny010]

Thanks for the review, @thierry-martinez! Pushed eebb104 addressing both inline points:

• Configurable precision — added a precision keyword argument to complex_to_str, statevec_to_str, density_matrix_to_str, and the matching Statevec.draw / DensityMatrix.draw methods. It controls the number of significant digits used by the decimal fallback. The default (4) preserves the previous behaviour. New regression test covering several precisions.
• Rename — renamed _recognize_real to _recognize_sqrt. The helper recognizes a real number as signed_num * sqrt(inner) / den, and the rationals are covered as the special case inner == 1 — added a sentence to the docstring to make that explicit.

I'll have a look at #503 and #523 and follow up with comments there.

[Vinny010]

@thierry-martinez — small process note: looks like the workflow run on eebb104 is still awaiting approval (no check runs have fired since the response push). Whenever you have a moment to re-trigger it, happy to address anything else that comes up.

[thierry-martinez]

Thank you for your update, @Vinny010. I think we are on a good track to merge this PR. In this respect, please add a comment in the discussion of #501 so that I can assign the issue to you.

I have also made a few remarks (as a side note, I did not use the "Request changes" flag since we've chosen not to use it in the Graphix project, to avoid blocking the PR from being merged if other maintainers approve it). Note that we have a two‑approval rule for non‑trivial PRs: therefore, once I or another maintainer approves this PR, we'll need a second approval before merging.

[thierry-martinez]

Thank you for your changes. Just minor comments left. Please have a look at the test coverage: there are still some gaps.

[Vinny010]

Thanks @thierry-martinez — all four addressed in 58eb451.

• rtol parameter. Added wherever atol is exposed: complex_to_str, density_matrix_to_str and DensityMatrix.draw (it was indeed missing there), threaded down into the math.isclose recognition calls as rel_tol. Statevec.draw/statevec_to_str already had it; it now also reaches the per-amplitude recognition, not just the amplitude-dropping. Default is 0.0, so existing behaviour is unchanged.
• _decimal_to_str. Now takes atol as an argument instead of reading the module-level _DEFAULT_ATOL.
• LaTeX ket coverage. The \ket{...} notation is now exercised in the statevec draw tests (both the bare basis state and the coefficient-prefixed Bell case).
• Test consolidation. Merged the remaining complex_to_str value tests (radius/Cartesian/decimal-fallback/integer-times-surd) into the parametrized test_complex_to_str_values. I kept two things out of it deliberately: test_complex_to_str_precision_is_configurable (it varies the precision argument rather than testing a default-args value→string mapping) and the Statevec/DensityMatrix draw tests (different entry points). Happy to fold those in too if you'd rather have a single table.
• Coverage for rtol. Added test_complex_to_str_rtol_controls_recognition (a value just off 1/2 is a decimal at the default tolerance, but recognized as 1/2 with a looser rtol) and a DensityMatrix.draw(rtol=...) test.

[thierry-martinez]

I extracted the coverage results from Codecov. You can view them here: https://app.codecov.io/gh/TeamGraphix/graphix/pull/524?src=pr&el=tree

[thierry-martinez]

Suggested change

	rtol: float = 0.0,
	rtol: float = _DEFAULT_RTOL,

[Vinny010]

Thanks @thierry-martinez — follow-up addressed in 5b7c389.

Uniform magnitude. Statevec output now factors a magnitude shared by every amplitude: √2/2(|00⟩ + |11⟩) instead of √2/2|00⟩ + √2/2|11⟩, with the signs kept inside the parentheses (1/2(|00⟩ - |01⟩ + |10⟩ + |11⟩)). Compound (Cartesian) amplitudes and non-uniform magnitudes fall back to the term-by-term form. Updated the affected tests and the docstring / doctest examples.

Uncovered lines. Added tests reaching each flagged branch:

• tiny non-zero real → "0" (the zero branches of _squarefree_decomposition and _render_real),
• a purely imaginary decimal (0.234567j → 0.2346i, the _imaginary_to_str → None and _decimal_to_str imaginary branches),
• a recognized phase with an unrecognized radius (π·e^(iπ/4), the _exponential_to_str radius-None branch),
• the empty-statevector "0" (via a tolerance large enough to drop every amplitude).

For the _recognize_sqrt x == 0 guard I removed it rather than test it: the general path already returns (0, 1, 1) for x == 0, so it was dead code.

(I checked the new branches execute by tracing the outputs; pytest-cov isn't in my local env, so if your coverage run still flags anything I missed, point me at the line and I'll cover it.)

[Vinny010]

Note on the red CI here: the 7 failures are all in tests/test_visualization.py — the pytest-mpl image-comparison tests (test_og_draw, the test_*_flow_draw set, test_xzcorr_draw, test_draw_graph_reference), each failing with "Image files did not match". The other 3342 tests pass.

Those render graph/flow figures and don't touch anything in this diff, which only changes amplitude/statevector text formatting — nothing in visualization.py calls complex_to_str/statevec_to_str/density_matrix_to_str. The same --mpl suite passed on #526's CI run a day earlier (11 Jun), so this looks like matplotlib-version pixel drift in the reference images rather than a regression from this branch.

Happy to help if a baseline refresh is wanted — if you let me know the matplotlib version the CI pins to, I can regenerate the references against it; or if you'd rather keep baseline changes out of this PR, that's fine too and I'll leave it to you.

[thierry-martinez]

Yes, indeed, the CI broke because of a new Matplotlib release. It was fixed in #541, which has now been merged. Could you merge the current master into your branch?

[thierry-martinez]

I checked the new branches execute by tracing the outputs; pytest-cov isn't in my local env, so if your coverage run still flags anything I missed, point me at the line and I'll cover it.

As I mentioned in my previous comment, you can view the code‑coverage results here: https://app.codecov.io/gh/TeamGraphix/graphix/pull/524

[Vinny010]

Thanks for the codecov link — that pinned it to a single line. The patch coverage was 99.5%, with one miss: pretty_print.py:847, the result += f" - {term[1:]}" separator in the term-by-term statevec fallback.

It was a side effect of the new uniform-magnitude factoring: the negative-amplitude case I had a test for ([0.5, -0.5, 0.5, 0.5]) now goes through the factored path (1/2(|00⟩ - |01⟩ + ...)), so it no longer reaches the fallback loop, and the only remaining fallback test (the binomial) has no negative term. Fixed in 78a48e7 by giving test_statevec_draw_non_uniform_not_factored a negative second amplitude (√3/2|0⟩ - 1/2|1⟩), which flows through the fallback and exercises that branch. Patch coverage should be 100% now.

[pranav97nair]

Hi @Vinny010 , thanks for your work on this PR! This will be a nice addition to Graphix. I have a couple points to add.

Currently, the statevector draw function factors out the magnitude when it is shared by all component amplitudes. I would however like to see this factoring even in the case when there is a relative phase, as this does not change the magnitude of the affected component. A basic example:

plus = Statevec(data=BasicStates.PLUS)
assert plus.draw() == "√2/2(|0⟩ + |1⟩)" # Passes

plus_i = Statevec(data=BasicStates.PLUS_I)
assert plus_i.draw() == "√2/2(|0⟩ + i|1⟩)" # Fails

Could you update your factoring function to account for this case and enforce factoring when all magnitudes are equal up to a relative phase $e^{i\varphi}$ ?

Also, could you include a test checking the impact of the max_denominator parameter of the new draw() functions? As it stands, I believe none of the tests use anything other than the default value.

[Vinny010]

Thanks @pranav97nair — both addressed in 0faf587.

Relative-phase factoring. _factor_uniform_magnitude now works on the amplitudes rather than the coefficient strings: it factors a shared modulus r and keeps each per-component phase amplitude / r inside the parentheses. So your example now holds:

Statevec(data=BasicStates.PLUS).draw()    # √2/2(|0⟩ + |1⟩)
Statevec(data=BasicStates.PLUS_I).draw()  # √2/2(|0⟩ + i|1⟩)
Statevec(data=BasicStates.MINUS_I).draw() # √2/2(|0⟩ - i|1⟩)

It still falls back to term-by-term when the moduli genuinely differ, when the shared modulus is trivial (1), or when the amplitudes are non-numeric (symbolic), so nothing regresses there. Added tests for the phase cases (Unicode + LaTeX) and direct edge-case coverage of the helper.

max_denominator test. Added test_draw_max_denominator, which checks both draw functions: with max_denominator=1, DensityMatrix.draw renders 0.5 instead of 1/2 and Statevec.draw renders 0.7071 instead of √2/2 (the denominators can no longer be recognized).

Local run is green (ruff / mypy / 185 tests + doctests). Let me know if you'd like the relative phase rendered differently (e.g. an explicit e^{iφ} form for non-Pauli phases).