Add a new argument to plot_state_qsphere (update to #5607)

[pragyakatyayan]

UPDATE #2:

This is an attempt to resolve conflicts from PR #5607 (dated: 12 Jan 2021). It was under active review but the master branch got updates in the code with new releases. The PR suffered from some conflicts and failed in some tests. So, I have updated the code in this PR. My first attempt at this PR was in PR (#5177) on 3 October 2020.

Motivation

I ran into this situation where only some states were visible while visualizing the qsphere few months back and asked help here. It was then that @aasfaw motivated me to do something like this. Many thanks to him. See the conversation here.

Summary

The previous show_state_labels argument is meant to show labels for only weighted states. When used with show_state_phases=True the weighted states displayed their phase values. The states with 0 weights were not given the labels.

The new 'optional' argument show_all_state_labels which is added with this PR shows all possible state labels when set to True. This Boolean variable which is false by default, aims at letting the end-user distinguish visually on the q-sphere between the states having zero weights and those having non-zero weights. The argument is kept optional to ensure that it is set to true only if the user wants to display all possible state labels for any particular circuit, the default view would show labels (and phases) for non-zero states only.
The new argument works well with show_state_phases=True and shows phase values for all possible state labels.
The test cases given below are performed for two circuits-one with 2 qubits and other with 3 qubits. Both the circuits were deliberately made to produce weights for half of the possible states, to notice the working of new argument for states with zero-weights. Snapshots show the default view and the new argument's output.

Details and comments

Case 1: Tested for two-qubit circuit (clutter possibility is low)

Default:

New Argument: show_all_state_labels=True

with show_state_phases=True

Default:

New Argument: show_all_state_labels=True, show_state_phases=True

---

Case 2: Tested for three-qubit circuit (clutter possibility is medium-high)

Default:

New Argument:

with show_state_phases=True

Default:

New Argument:

---

CAUTION: Users must note that this new argument might give you a cluttered output in case of qubits>3. That is why the argument's default setting is False. This argument must be set to True if and only if user wants to see the positioning of all possible states on the qsphere.

[coveralls]

Pull Request Test Coverage Report for Build 4981117588

• 0 of 14 (0.0%) changed or added relevant lines in 1 file are covered.
• 16 unchanged lines in 5 files lost coverage.
• Overall coverage increased (+0.008%) to 85.914%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
qiskit/visualization/state_visualization.py	0	14	0.0%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/expr.rs	1	93.76%
qiskit/extensions/quantum_initializer/squ.py	2	80.0%
crates/qasm2/src/lex.rs	3	91.14%
crates/accelerate/src/sabre_swap/layer.rs	4	97.32%
crates/qasm2/src/parse.rs	6	97.58%

Totals
Change from base Build 4961195397:	0.008%
Covered Lines:	71186
Relevant Lines:	82857

---

💛 - Coveralls

[coveralls]

Pull Request Test Coverage Report for Build 6384990269

• 0 of 14 (0.0%) changed or added relevant lines in 1 file are covered.
• 4 unchanged lines in 1 file lost coverage.
• Overall coverage decreased (-0.01%) to 87.003%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
qiskit/visualization/state_visualization.py	0	14	0.0%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	4	90.91%

Totals
Change from base Build 6384909590:	-0.01%
Covered Lines:	74104
Relevant Lines:	85174

---

💛 - Coveralls

[kevinsung]

Looks like you need to format your code using black.

[kevinsung]

Instead of duplicating the logic for show_state_labels, you can just modify the condition in line 988

if not np.isclose(prob, 0) and show_state_labels:

to

if show_all_state_labels or (not np.isclose(prob, 0) and show_state_labels):