# 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`uint8`

data array.**num_bits**(*int*(opens in a new tab)) – How many bit are in each outcome.

**Raises**

**TypeError**(opens in a new tab) – If the input is not a NumPy array with type`numpy.uint8`

.**ValueError**(opens in a new tab) – 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**

*ndarray*(opens in a new tab)[*Any*(opens in a new tab), *dtype*(opens in a new tab)[*uint64*]]

### concatenate

*static *`concatenate(bit_arrays, axis=0)`

Join a sequence of bit arrays along an existing axis.

**Parameters**

**bit_arrays**(*Sequence*(opens in a new tab)*[**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*(opens in a new tab)) – The axis along which the arrays will be joined. Default is 0.

**Returns**

The concatenated bit array.

**Raises**

**ValueError**(opens in a new tab) – If the sequence of bit arrays is empty.**ValueError**(opens in a new tab) – If any bit arrays has a different number of bits.**ValueError**(opens in a new tab) – If any bit arrays has a different number of shots.**ValueError**(opens in a new tab) – 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*(opens in a new tab)*[**BitArray**]*) – Bit arrays that have (1) the same number of shots, and (2) the same shape.

**Returns**

The stacked bit array.

**Raises**

**ValueError**(opens in a new tab) – If the sequence of bit arrays is empty.**ValueError**(opens in a new tab) – If any bit arrays has a different number of shots.**ValueError**(opens in a new tab) – 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*(opens in a new tab)*[**BitArray**]*) – The bit arrays must have (1) the same number of bits, and (2) the same shape.

**Returns**

The stacked bit array.

**Raises**

**ValueError**(opens in a new tab) – If the sequence of bit arrays is empty.**ValueError**(opens in a new tab) – If any bit arrays has a different number of bits.**ValueError**(opens in a new tab) – 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*(opens in a new tab)*|**Pauli**|**SparsePauliOp**|**Mapping*(opens in a new tab)*[**str*(opens in a new tab)*|**Pauli**,**float*(opens in a new tab)*] | _SupportsArray[**dtype*(opens in a new tab)*[**Any*(opens in a new tab)*]] | _NestedSequence[_SupportsArray[**dtype*(opens in a new tab)*[**Any*(opens in a new tab)*]]] |**bool*(opens in a new tab)*|**int*(opens in a new tab)*|**float*(opens in a new tab)*|**complex*(opens in a new tab)*|**bytes*(opens in a new tab)*| _NestedSequence[**bool*(opens in a new tab)*|**int*(opens in a new tab)*|**float*(opens in a new tab)*|**complex*(opens in a new tab)*|**str*(opens in a new tab)*|**bytes*(opens in a new tab)*]*) – 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**(opens in a new tab) – If the provided observables does not have a shape broadcastable with this bit array.**ValueError**(opens in a new tab) – If the provided observables does not have the same number of qubits as the number of bits of this bit array.**ValueError**(opens in a new tab) – If the provided observables are not diagonal.

**Return type**

*ndarray*(opens in a new tab)[*Any*(opens in a new tab), *dtype*(opens in a new tab)[*float64*]]

### from_bool_array

*static *`from_bool_array(array, order='big')`

Construct a new bit array from an array of bools.

**Parameters**

**array**(*ndarray*(opens in a new tab)*[**Any*(opens in a new tab)*,**dtype*(opens in a new tab)*[bool_]]*) – The array to convert, with “bitstrings” along the last axis.**order**(*Literal*(opens in a new tab)*['big', 'little']*) – One of`"big"`

or`"little"`

, indicating whether`array[..., 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*(opens in a new tab)*|**int*(opens in a new tab)*,**int*(opens in a new tab)*] | Iterable[Mapping[**str*(opens in a new tab)*|**int*(opens in a new tab)*,**int*(opens in a new tab)*]]*) – One or more counts-like mappings with the same number of shots.**num_bits**(*int*(opens in a new tab)*| None*) – The desired number of bits per shot. If unset, the biggest value found sets this value.

**Returns**

A new bit array with shape `()`

for single input counts, or `(N,)`

for an iterable of $N$ counts.

**Raises**

**ValueError**(opens in a new tab) – If different mappings have different numbers of shots.**ValueError**(opens in a new tab) – 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*(opens in a new tab)*] | Iterable[**int*(opens in a new tab)*]*) – A list of bitstrings, a list of integers, or a list of hexstrings.**num_bits**(*int*(opens in a new tab)*| None*) – The desired number of bits per sample. If unset, the biggest sample provided is used to determine this value.

**Returns**

A new bit array.

**Raises**

**ValueError**(opens in a new tab) – If no strings are given.

**Return type**

### get_bitstrings

`get_bitstrings(loc=None)`

Return a list of bitstrings.

**Parameters**

**loc** (*int*(opens in a new tab) *|**tuple*(opens in a new tab)*[**int*(opens in a new tab)*, ...] | 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*(opens in a new tab) *|**tuple*(opens in a new tab)*[**int*(opens in a new tab)*, ...] | 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**

dict(opens in a new tab)[str(opens in a new tab), int(opens in a new tab)]

### get_int_counts

`get_int_counts(loc=None)`

Return a counts dictionary, where bitstrings are stored as `int`

s.

**Parameters**

**loc** (*int*(opens in a new tab) *|**tuple*(opens in a new tab)*[**int*(opens in a new tab)*, ...] | 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**

dict(opens in a new tab)[int(opens in a new tab), int(opens in a new tab)]

### 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*(opens in a new tab) *|**Iterable*(opens in a new tab)*[**int*(opens in a new tab) *| Iterable[ShapeInput]]*) – The new desired shape.

**Returns**

A new bit array.

**Raises**

**ValueError**(opens in a new tab) – 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*(opens in a new tab) *| Sequence[**int*(opens in a new tab)*]*) – The bit positions of interest to slice along.

**Returns**

A bit array sliced along the bit axis.

**Raises**

**ValueError**(opens in a new tab) – 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*(opens in a new tab) *| Sequence[**int*(opens in a new tab)*]*) – The shots positions of interest to slice along.

**Returns**

A bit array sliced along the shots axis.

**Raises**

**ValueError**(opens in a new tab) – 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(opens in a new tab) for the details.

**Returns**

A bit array with axes permuted.

**Return type**

**Raises**

**ValueError**(opens in a new tab) – If`axes`

don’t match this bit array.**ValueError**(opens in a new tab) – If`axes`

includes any indices that are out of bounds.