Bitarray postselect

[aeddins-ibm]

Summary

Add method BitArray.postselect(), per issue #12688 .

[edit July 22, 2024: deleting outdated, distracting details from this description. See linked issue and the method docstring for more information.]

[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:

• @Qiskit/terra-core
• @ajavadia
• @levbishop
• @t-imamichi

[coveralls]

Pull Request Test Coverage Report for Build 9719523525

Details

• 4 of 4 (100.0%) changed or added relevant lines in 1 file are covered.
• 16 unchanged lines in 2 files lost coverage.
• Overall coverage decreased (-0.008%) to 89.765%

---

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	4	92.88%
crates/qasm2/src/parse.rs	12	97.15%

Totals
Change from base Build 9718390567:	-0.008%
Covered Lines:	64075
Relevant Lines:	71381

---

💛 - Coveralls

[coveralls]

Pull Request Test Coverage Report for Build 9725434498

Details

• 4 of 4 (100.0%) changed or added relevant lines in 1 file are covered.
• 4 unchanged lines in 2 files lost coverage.
• Overall coverage increased (+0.009%) to 89.782%

---

Files with Coverage Reduction	New Missed Lines	%
qiskit/transpiler/passes/synthesis/unitary_synthesis.py	2	88.2%
crates/qasm2/src/lex.rs	2	93.38%

Totals
Change from base Build 9718390567:	0.009%
Covered Lines:	64087
Relevant Lines:	71381

---

💛 - Coveralls

[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:

• @Qiskit/terra-core
• @ajavadia
• @levbishop
• @t-imamichi

[ihincks]

Thanks for opening the PR!

This change will also need a reno.

[coveralls]

Pull Request Test Coverage Report for Build 9767937070

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

• 4 of 4 (100.0%) changed or added relevant lines in 1 file are covered.
• 630 unchanged lines in 20 files lost coverage.
• Overall coverage increased (+0.03%) to 89.807%

---

Files with Coverage Reduction	New Missed Lines	%
qiskit/circuit/library/standard_gates/rxx.py	1	97.56%
qiskit/transpiler/passes/routing/commuting_2q_gate_routing/pauli_2q_evolution_commutation.py	1	97.92%
qiskit/circuit/library/standard_gates/rzx.py	1	97.56%
qiskit/circuit/library/standard_gates/ryy.py	2	95.12%
crates/accelerate/src/synthesis/permutation/utils.rs	2	97.94%
qiskit/circuit/library/standard_gates/rzz.py	2	94.74%
qiskit/circuit/library/standard_gates/p.py	3	96.55%
crates/qasm2/src/lex.rs	4	93.13%
crates/qasm2/src/parse.rs	6	97.61%
qiskit/visualization/circuit/circuit_visualization.py	16	73.43%

Totals
Change from base Build 9718390567:	0.03%
Covered Lines:	64545
Relevant Lines:	71871

---

💛 - Coveralls

[coveralls]

Pull Request Test Coverage Report for Build 9768517825

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

• 4 of 4 (100.0%) changed or added relevant lines in 1 file are covered.
• 631 unchanged lines in 20 files lost coverage.
• Overall coverage increased (+0.03%) to 89.805%

---

Files with Coverage Reduction	New Missed Lines	%
qiskit/circuit/library/standard_gates/rxx.py	1	97.56%
qiskit/transpiler/passes/routing/commuting_2q_gate_routing/pauli_2q_evolution_commutation.py	1	97.92%
qiskit/circuit/library/standard_gates/rzx.py	1	97.56%
qiskit/circuit/library/standard_gates/ryy.py	2	95.12%
crates/accelerate/src/synthesis/permutation/utils.rs	2	97.94%
qiskit/circuit/library/standard_gates/rzz.py	2	94.74%
qiskit/circuit/library/standard_gates/p.py	3	96.55%
crates/qasm2/src/lex.rs	5	92.62%
crates/qasm2/src/parse.rs	6	97.61%
qiskit/visualization/circuit/circuit_visualization.py	16	73.43%

Totals
Change from base Build 9718390567:	0.03%
Covered Lines:	64544
Relevant Lines:	71871

---

💛 - Coveralls

[aeddins-ibm]

Before merging and committing to this function signature, should we consider if there are more general postselection conditions we could easily support?

For example, a plausible use case is someone wants all shots where, for all even k, cbits[k] != cbits[k+1].

--
Update: I think this is probably not necessary, at least not urgent. For N values of k, the above example case could be resolved by calling postselect 2N times, which isn't great but is much better than the exponential blowup that I was initially imagining. (I was incorrectly concerned one would have to call postselect 2^N times, once for each of the possible 2N-qubit bitstrings. But one only has to call postselect 2N times, with selection=[0, 1] and selection=[1,0] for each value of k.)

[t-imamichi]

If you have any use case of cbits[k] != cbits[k+1] in mind, we have a little time left to discuss the extension (before 1.2 release).
If it's not urgent, I agree to merge this PR. This PR is LGTM already.

[aeddins-ibm]

I think it's OK to merge as-is. The use-case I imagined above can at least be done in a linear number of calls to this function, which seems tolerable for now.

There are other hypothetical use cases that would require an exponential number of calls AFAICT. Like if we wanted only those shots where there are an odd number of 1's (odd parity) in a set of N bits, for large N. Then I think one would need to call postselect an exponential number of times to pick out each of the (2^N)/2 odd-parity bitstrings individually. This is not a fundamental limitation -- postselect could keep all shots where bitwise_xor.reduce of the selected bits gives 1. But I don't see a natural way to generalize the postselect interface, and likewise don't see an obvious place to stop generalizing the logic (if we add xor, do we also need to add xnor? And any? And...).

So I think it's better to leave postselect doing just the one thing it already does.

Someday, if we want to add support for e.g. selecting shots with a certain parity on many bits, we might instead add a separate method BitArray.parity(indices) that returns the parity of the specified bits for each shot, and then the user can use that to create a boolean mask to keep shots with the desired parity. (There may be overlap with code to compute expectation values). This would require modifying slice_shots to accept a boolean mask, which at a glance looks straightforward.

Frankly, we could also use this approach instead of having a postselect method at all, except that currently postselect should be faster than slice_bits due to the bit unpacking/repacking. I was not able to make slice_bits faster via numpy bitwise operations, but maybe a Rust version of slice_bits would be faster, at which point postselect could optionally be deprecated (or not) in favor of doing all types of postselection by creating a boolean mask along the shots axis.

Anyway, that's all to say I agree this PR is good to merge. Thanks for your patient reviewing!

[t-imamichi]

Thank you for your contributions. LGTM.

Post-selection with parity sounds an interesting use case. I agree to think of a separate method to realize it.

[aeddins-ibm]

In case it's any use as a future reference, here is one approach to compute parity of specified bits.

This snippet uses bitmask as defined in the postselect code. It first uses bitwise_xor to collapse together all bytes in the bits axis, then broadcasts the remaining 8 bits to a byte each to take their xor.

shot_mask = np.bitwise_xor.reduce(flattened._array & bitmask, axis=-1, dtype=np.uint8, keepdims=True)
shot_mask = np.logical_xor.reduce(shot_mask & (np.uint8(1) << np.arange(8, dtype=np.uint8)), axis=-1, dtype=bool)

[t-imamichi]

LGTM

[t-imamichi]

Could you review this again, @ihincks? I would like to merge it if there is no problem.

[t-imamichi]

Since there is no comment from @ihincks, I will merge this PR once CI gets recovered.

[ElePT]

Neko won't block the merge queue so I think we can already add the PR to the queue :)