Fix plot_state_qsphere phase anchor bias due to solver noise

[dmeliksetian]

Summary

This PR fixes a visualization artifact in plot_state_qsphere where symmetric entangled states (e.g., Bell states) were being arbitrarily rotated due to floating-point noise.

The Issue:
The function uses scipy.linalg.eigh internally to decompose the input state. For symmetric states (e.g., |00> - |11>), the solver introduces microscopic noise ($\approx 10^{-16}$) that often makes the last element slightly larger than the first.
The previous logic (loc = np.absolute(state).argmax()) strictly trusted this noise, causing the visualization to select the "wrong" basis state as the global phase anchor (Phase 0).

The Fix:
Added a rounding step (np.round(..., decimals=13)) before calculating argmax. This filters out solver noise and ensures that effectively equal amplitudes are treated as a tie, allowing argmax to default to the canonical first index.

Details and comments

• Location: qiskit/visualization/state_visualization.py (Line ~951)
• Verification: Verified locally with a standard Bell state $|\Psi^-\rangle$.
  • Before: Anchor often defaulted to $|11\rangle$ (rendering $-|00\rangle + |11\rangle$).
  • After: Anchor correctly defaults to $|00\rangle$ (rendering $|00\rangle - |11\rangle$).
• AI Disclosure: AI tool used: Google Gemini (Assisted in isolating the scipy solver noise and drafting the fix).

Fixes #15493

[qiskit-bot]

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

One or more of the following people are relevant to this code:

• @enavarro51
• @Qiskit/terra-core

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ dmeliksetian
❌ dsmeliks
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[mergify]

⚠️ The sha of the head commit of this PR conflicts with #15473. Mergify cannot evaluate rules on this PR. ⚠️

[Cryoris]

In the cases with similar eigenvalues, doesn't the order returned by scipy.linalg.eigh also vary? If it does, then rounding afterwards doesn't guarantee a fixed order 🤔

[dmeliksetian]

we are looking at the magnitude of the elements of a vector, the vector elements are naturally ordered and argmax() returns the index of the first element when there are more than one element equal to the maximum value. So when the magnitudes are equal it will return the lowest position. In terms of adjusting the global phase, this is exactly what we want, if everything else is equal.

[Cryoris]

Ah right, these are not the eigenvalues but the vector itself. All good then!

[coveralls]

Pull Request Test Coverage Report for Build 20754331594

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 1 of 1 (100.0%) changed or added relevant line in 1 file are covered.
• 33 unchanged lines in 5 files lost coverage.
• Overall coverage increased (+0.009%) to 88.319%

---

Files with Coverage Reduction	New Missed Lines	%
crates/circuit/src/parameter/parameter_expression.rs	1	82.3%
qiskit/circuit/library/pauli_product_measurement.py	2	95.35%
crates/qasm2/src/lex.rs	4	91.52%
crates/circuit/src/parameter/symbol_expr.rs	8	72.98%
qiskit/circuit/library/n_local/evolved_operator_ansatz.py	18	89.3%

Totals
Change from base Build 20366546417:	0.009%
Covered Lines:	96732
Relevant Lines:	109526

---

💛 - Coveralls

[Cryoris]

It would be great to add a test for this, given that there's currently only a single qsphere test which is displaying the $|1\rangle$ state, not a bell state. This would be similar to

qiskit/test/visual/mpl/graph/test_graph_matplotlib_drawer.py

Line 138 in 841159e

def test_plot_state_qsphere(self):

just using a bell state instead. Generating the reference image can be a bit tricky though, due to slight mismatches in plot package versions. You could still try generating the reference locally, or otherwise download the generated image from the CI run. Let me know if you need help with this.

[dmeliksetian]

It would be great to add a test for this, given that there's currently only a single qsphere test which is displaying the | 1 ⟩ state, not a bell state. This would be similar to

qiskit/test/visual/mpl/graph/test_graph_matplotlib_drawer.py

Line 138 in 841159e

def test_plot_state_qsphere(self):

just using a bell state instead. Generating the reference image can be a bit tricky though, due to slight mismatches in plot package versions. You could still try generating the reference locally, or otherwise download the generated image from the CI run. Let me know if you need help with this.

Done, I locally tested test_plot_entangled_state_qsphere and it passed the test