BitArray
class qiskit.primitives.BitArray(array, num_bits)
Bases: ShapedMixin
Stores an array of bit values.
This object contains a single, contiguous block of data that represents an array of bitstrings. The last axis is over packed bits, the second last axis is over shots, and the preceding axes correspond to the shape of the pub that was executed to sample these bits.
Parameters
- array (NDArray[np.uint8]) – The
uint8data array. - num_bits (int) – How many bit are in each outcome.
Raises
- TypeError – If the input is not a NumPy array with type
numpy.uint8. - ValueError – If the input array has fewer than two axes, or the size of the last axis is not the smallest number of bytes that can contain
num_bits.
Attributes
array
The raw NumPy array of data.
ndim
num_bits
The number of bits in the register that this array stores data for.
For example, a ClassicalRegister(5, "meas") would result in num_bits=5.
num_shots
The number of shots sampled from the register in each configuration.
More precisely, the length of the second last axis of array.
shape
size
Methods
bitcount
bitcount()
Compute the number of ones appearing in the binary representation of each shot.
Returns
A numpy.uint64-array with shape (*shape, num_shots).
Return type
concatenate
static concatenate(bit_arrays, axis=0)
Join a sequence of bit arrays along an existing axis.
Parameters
- bit_arrays (Sequence[BitArray]) – The bit arrays must have (1) the same number of bits, (2) the same number of shots, and (3) the same shape, except in the dimension corresponding to axis (the first, by default).
- axis (int) – The axis along which the arrays will be joined. Default is 0.
Returns
The concatenated bit array.
Raises
- ValueError – If the sequence of bit arrays is empty.
- ValueError – If any bit arrays has a different number of bits.
- ValueError – If any bit arrays has a different number of shots.
- ValueError – If any bit arrays has a different number of dimensions.
Return type
concatenate_bits
static concatenate_bits(bit_arrays)
Join a sequence of bit arrays along the bits axis.
This method is equivalent to per-shot bitstring concatenation.
Parameters
bit_arrays (Sequence[BitArray]) – Bit arrays that have (1) the same number of shots, and (2) the same shape.
Returns
The stacked bit array.
Raises
- ValueError – If the sequence of bit arrays is empty.
- ValueError – If any bit arrays has a different number of shots.
- ValueError – If any bit arrays has a different shape.
Return type
concatenate_shots
static concatenate_shots(bit_arrays)
Join a sequence of bit arrays along the shots axis.
Parameters
bit_arrays (Sequence[BitArray]) – The bit arrays must have (1) the same number of bits, and (2) the same shape.
Returns
The stacked bit array.
Raises
- ValueError – If the sequence of bit arrays is empty.
- ValueError – If any bit arrays has a different number of bits.
- ValueError – If any bit arrays has a different shape.
Return type
expectation_values
expectation_values(observables)
Compute the expectation values of the provided observables, broadcasted against this bit array.
This method returns the real part of the expectation value even if the operator has complex coefficients due to the specification of sampled_expectation_value().
Parameters
- observables (str |Pauli |SparsePauliOp |Mapping[str |Pauli, float] | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool |int |float |complex |bytes | _NestedSequence[bool |int |float |complex |str |bytes]) – The observable(s) to take the expectation value of.
- and (Must have a shape broadcastable with with this bit array) –
- array. (the same number of qubits as the number of bits of this bit) –
- diagonal (The observables must be) –
Returns
An array of expectation values whose shape is the broadcast shape of observables and this bit array.
Raises
- ValueError – If the provided observables does not have a shape broadcastable with this bit array.
- ValueError – If the provided observables does not have the same number of qubits as the number of bits of this bit array.
- ValueError – If the provided observables are not diagonal.
Return type
from_bool_array
static from_bool_array(array, order='big')
Construct a new bit array from an array of bools.
Parameters
- array (ndarray[Any, dtype[bool_]]) – The array to convert, with “bitstrings” along the last axis.
- order (Literal['big', 'little']) – One of
"big"or"little", indicating whetherarray[..., 0]correspond to the most significant bits or the least significant bits of each bitstring, respectively.
Returns
A new bit array.
Return type
from_counts
static from_counts(counts, num_bits=None)
Construct a new bit array from one or more Counts-like objects.
The counts can have keys that are (uniformly) integers, hexstrings, or bitstrings. Their values represent numbers of occurrences of that value.
Parameters
- counts (Mapping[str |int, int] | Iterable[Mapping[str |int, int]]) – One or more counts-like mappings with the same number of shots.
- num_bits (int | None) – The desired number of bits per shot. If unset, the biggest value found sets this value, with a minimum of one bit.
Returns
A new bit array with shape () for single input counts, or (N,) for an iterable of counts.
Raises
- ValueError – If different mappings have different numbers of shots.
- ValueError – If no counts dictionaries are supplied.
Return type
from_samples
static from_samples(samples, num_bits=None)
Construct a new bit array from an iterable of bitstrings, hexstrings, or integers.
All samples are assumed to be integers if the first one is. Strings are all assumed to be bitstrings whenever the first string doesn’t start with "0x".
Consider pairing this method with reshape() if your samples represent nested data.
Parameters
- samples (Iterable[str] | Iterable[int]) – A list of bitstrings, a list of integers, or a list of hexstrings.
- num_bits (int | None) – The desired number of bits per sample. If unset, the biggest sample provided is used to determine this value, with a minimum of one bit.
Returns
A new bit array.
Raises
ValueError – If no strings are given.
Return type
get_bitstrings
get_bitstrings(loc=None)
Return a list of bitstrings.
Parameters
loc (int |tuple[int, ...] | None) – Which entry of this array to return a dictionary for. If None, counts from all positions in this array are unioned together.
Returns
A list of bitstrings.
Return type
get_counts
get_counts(loc=None)
Return a counts dictionary with bitstring keys.
Parameters
loc (int |tuple[int, ...] | None) – Which entry of this array to return a dictionary for. If None, counts from all positions in this array are unioned together.
Returns
A dictionary mapping bitstrings to the number of occurrences of that bitstring.
Return type
get_int_counts
get_int_counts(loc=None)
Return a counts dictionary, where bitstrings are stored as ints.
Parameters
loc (int |tuple[int, ...] | None) – Which entry of this array to return a dictionary for. If None, counts from all positions in this array are unioned together.
Returns
A dictionary mapping ints to the number of occurrences of that int.
Return type
postselect
postselect(indices, selection)
Post-select this bit array based on sliced equality with a given bitstring.
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 BitArray cannot handle ragged numbers of shots across axes.
Parameters
- indices (Sequence[int] | int) – A list of the indices of the cbits on which to postselect. If this bit array was produced by a sampler, then an index
icorresponds to theClassicalRegisterlocationcreg[i](as inslice_bits()). Negative indices are allowed. - selection (Sequence[bool |int] | bool |int) – A list of binary values (will be cast to
bool) of length matchingindices, withindices[i]corresponding toselection[i]. Shots will be discarded unless all cbits specified byindiceshave the values given byselection.
Returns
A new bit array with shape=(), num_bits=data.num_bits, num_shots<=data.num_shots.
Raises
- IndexError – If
max(indices)is greater than or equal tonum_bits. - IndexError – If
min(indices)is less than negativenum_bits. - ValueError – If the lengths of
selectionandindicesdo not match.
Return type
reshape
reshape(*shape)
Return a new reshaped bit array.
The num_shots axis is either included or excluded from the reshaping procedure depending on which picture the new shape is compatible with. For example, for a bit array with shape (20, 5) and 64 shots, a reshape to (100,) would leave the number of shots intact, whereas a reshape to (200, 32) would change the number of shots to 32.
Parameters
*shape (int |Iterable[int | Iterable[ShapeInput]]) – The new desired shape.
Returns
A new bit array.
Raises
ValueError – If the size corresponding to your new shape is not equal to either size, or the product of size and num_shots.
Return type
slice_bits
slice_bits(indices)
Return a bit array sliced along the bit axis of some indices of interest.
The convention used by this method is that the index 0 corresponds to the least-significant bit in the array, or equivalently the right-most bitstring entry as returned by get_counts() or get_bitstrings(), etc.
If this bit array was produced by a sampler, then an index i corresponds to the ClassicalRegister location creg[i].
Parameters
indices (int | Sequence[int]) – The bit positions of interest to slice along.
Returns
A bit array sliced along the bit axis.
Raises
IndexError – If there are any invalid indices of the bit axis.
Return type
slice_shots
slice_shots(indices)
Return a bit array sliced along the shots axis of some indices of interest.
Parameters
indices (int | Sequence[int]) – The shots positions of interest to slice along.
Returns
A bit array sliced along the shots axis.
Raises
IndexError – If there are any invalid indices of the shots axis.
Return type
transpose
transpose(*axes)
Return a bit array with axes transposed.
Parameters
axes – None, tuple of ints or n ints. See ndarray.transpose for the details.
Returns
A bit array with axes permuted.
Return type
Raises
- ValueError – If
axesdon’t match this bit array. - ValueError – If
axesincludes any indices that are out of bounds.