Add post-selection method to BitArray #12688
Description
What should we add?
We should add a method that helps to filter shots by post-selection. The user should be able to make requests such as "I would like all of the shots where bits 15 and 18 are in the state 01".
There is a complication to do with the shaped nature of BitArray: each index of the shape might result in a different number of post selections. For example, if the original BitArray has 100 shots, the example above might result in 57 post-selections on the first index, 17 on the second, and so forth. To get around this, I propose that the post-selection method always flattens the data. Alternate proposals welcome. For example, if a data BitArray has shape (2,3,4) and num_shots=20, then the post-selection specification would first flatten into a BitArray of shape () and num_shots=2023*4, and apply the post selection there.
Proposed signature:
def postselect(self, selection: BitArray, idxs: Iterable[int]) -> BitArray:
"""Post-select this bit array based on sliced equality with a given bitstring.
.. note::
If this bit array contains any shape axes, it is first flattened into a long list of shots before
applying post-selection. This is done because :class:`~BitArray` cannot handle ragged
numbers of shots across axes.
Args:
selection: A bit array containing only one bitstring, specifying what to post-select on.
idxs: A list of length matching ``selection``, specifying which bits of ``data`` it corresponds to.
Returns:
A new bit array with ``shape=(), num_bits=data.num_bits, num_shots<=data.num_shots``.
Raises:
ValueError: If ``selection`` has more bits than :attr:`num_bits``.
ValueError: If the lengths of ``selection`` and ``idxs`` do not match.
ValueError: If selection contains more than one bitstring.
"""