qiskit 1.0.2__cp38-abi3-win32.whl → 1.1.0__cp38-abi3-win32.whl

qiskit/primitives/backend_sampler_v2.py

@@ -0,0 +1,287 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2024.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Sampler V2 implementation for an arbitrary Backend object."""
+
+from __future__ import annotations
+
+import warnings
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Iterable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from qiskit.circuit import QuantumCircuit
+from qiskit.primitives.backend_estimator import _run_circuits
+from qiskit.primitives.base import BaseSamplerV2
+from qiskit.primitives.containers import (
+    BitArray,
+    DataBin,
+    PrimitiveResult,
+    SamplerPubLike,
+    SamplerPubResult,
+)
+from qiskit.primitives.containers.bit_array import _min_num_bytes
+from qiskit.primitives.containers.sampler_pub import SamplerPub
+from qiskit.primitives.primitive_job import PrimitiveJob
+from qiskit.providers.backend import BackendV1, BackendV2
+from qiskit.result import Result
+
+
+@dataclass
+class Options:
+    """Options for :class:`~.BackendSamplerV2`"""
+
+    default_shots: int = 1024
+    """The default shots to use if none are specified in :meth:`~.run`.
+    Default: 1024.
+    """
+
+    seed_simulator: int | None = None
+    """The seed to use in the simulator. If None, a random seed will be used.
+    Default: None.
+    """
+
+
+@dataclass
+class _MeasureInfo:
+    creg_name: str
+    num_bits: int
+    num_bytes: int
+    start: int
+
+
+class BackendSamplerV2(BaseSamplerV2):
+    """Evaluates bitstrings for provided quantum circuits
+
+    The :class:`~.BackendSamplerV2` class is a generic implementation of the
+    :class:`~.BaseSamplerV2` interface that is used to wrap a :class:`~.BackendV2`
+    (or :class:`~.BackendV1`) object in the class :class:`~.BaseSamplerV2` API. It
+    facilitates using backends that do not provide a native
+    :class:`~.BaseSamplerV2` implementation in places that work with
+    :class:`~.BaseSamplerV2`. However,
+    if you're using a provider that has a native implementation of
+    :class:`~.BaseSamplerV2`, it is a better choice to leverage that native
+    implementation as it will likely include additional optimizations and be
+    a more efficient implementation. The generic nature of this class
+    precludes doing any provider- or backend-specific optimizations.
+
+    This class does not perform any measurement or gate mitigation.
+
+    Each tuple of ``(circuit, <optional> parameter values, <optional> shots)``, called a sampler
+    primitive unified bloc (PUB), produces its own array-valued result. The :meth:`~run` method can
+    be given many pubs at once.
+
+    The options for :class:`~.BackendSamplerV2` consist of the following items.
+
+    * ``default_shots``: The default shots to use if none are specified in :meth:`~run`.
+      Default: 1024.
+
+    * ``seed_simulator``: The seed to use in the simulator. If None, a random seed will be used.
+      Default: None.
+
+    .. note::
+
+        This class requires a backend that supports ``memory`` option.
+
+    """
+
+    def __init__(
+        self,
+        *,
+        backend: BackendV1 | BackendV2,
+        options: dict | None = None,
+    ):
+        """
+        Args:
+            backend: The backend to run the primitive on.
+            options: The options to control the default shots (``default_shots``) and
+                the random seed for the simulator (``seed_simulator``).
+        """
+        self._backend = backend
+        self._options = Options(**options) if options else Options()
+
+    @property
+    def backend(self) -> BackendV1 | BackendV2:
+        """Returns the backend which this sampler object based on."""
+        return self._backend
+
+    @property
+    def options(self) -> Options:
+        """Return the options"""
+        return self._options
+
+    def run(
+        self, pubs: Iterable[SamplerPubLike], *, shots: int | None = None
+    ) -> PrimitiveJob[PrimitiveResult[SamplerPubResult]]:
+        if shots is None:
+            shots = self._options.default_shots
+        coerced_pubs = [SamplerPub.coerce(pub, shots) for pub in pubs]
+        self._validate_pubs(coerced_pubs)
+        job = PrimitiveJob(self._run, coerced_pubs)
+        job._submit()
+        return job
+
+    def _validate_pubs(self, pubs: list[SamplerPub]):
+        for i, pub in enumerate(pubs):
+            if len(pub.circuit.cregs) == 0:
+                warnings.warn(
+                    f"The {i}-th pub's circuit has no output classical registers and so the result "
+                    "will be empty. Did you mean to add measurement instructions?",
+                    UserWarning,
+                )
+
+    def _run(self, pubs: list[SamplerPub]) -> PrimitiveResult[SamplerPubResult]:
+        pub_dict = defaultdict(list)
+        # consolidate pubs with the same number of shots
+        for i, pub in enumerate(pubs):
+            pub_dict[pub.shots].append(i)
+
+        results = [None] * len(pubs)
+        for shots, lst in pub_dict.items():
+            # run pubs with the same number of shots at once
+            pub_results = self._run_pubs([pubs[i] for i in lst], shots)
+            # reconstruct the result of pubs
+            for i, pub_result in zip(lst, pub_results):
+                results[i] = pub_result
+        return PrimitiveResult(results)
+
+    def _run_pubs(self, pubs: list[SamplerPub], shots: int) -> list[SamplerPubResult]:
+        """Compute results for pubs that all require the same value of ``shots``."""
+        # prepare circuits
+        bound_circuits = [pub.parameter_values.bind_all(pub.circuit) for pub in pubs]
+        flatten_circuits = []
+        for circuits in bound_circuits:
+            flatten_circuits.extend(np.ravel(circuits).tolist())
+
+        # run circuits
+        results, _ = _run_circuits(
+            flatten_circuits,
+            self._backend,
+            memory=True,
+            shots=shots,
+            seed_simulator=self._options.seed_simulator,
+        )
+        result_memory = _prepare_memory(results)
+
+        # pack memory to an ndarray of uint8
+        results = []
+        start = 0
+        for pub, bound in zip(pubs, bound_circuits):
+            meas_info, max_num_bytes = _analyze_circuit(pub.circuit)
+            end = start + bound.size
+            results.append(
+                self._postprocess_pub(
+                    result_memory[start:end], shots, bound.shape, meas_info, max_num_bytes
+                )
+            )
+            start = end
+
+        return results
+
+    def _postprocess_pub(
+        self,
+        result_memory: list[list[str]],
+        shots: int,
+        shape: tuple[int, ...],
+        meas_info: list[_MeasureInfo],
+        max_num_bytes: int,
+    ) -> SamplerPubResult:
+        """Converts the memory data into an array of bit arrays with the shape of the pub."""
+        arrays = {
+            item.creg_name: np.zeros(shape + (shots, item.num_bytes), dtype=np.uint8)
+            for item in meas_info
+        }
+        memory_array = _memory_array(result_memory, max_num_bytes)
+
+        for samples, index in zip(memory_array, np.ndindex(*shape)):
+            for item in meas_info:
+                ary = _samples_to_packed_array(samples, item.num_bits, item.start)
+                arrays[item.creg_name][index] = ary
+
+        meas = {
+            item.creg_name: BitArray(arrays[item.creg_name], item.num_bits) for item in meas_info
+        }
+        return SamplerPubResult(DataBin(**meas, shape=shape), metadata={})
+
+
+def _analyze_circuit(circuit: QuantumCircuit) -> tuple[list[_MeasureInfo], int]:
+    """Analyzes the information for each creg in a circuit."""
+    meas_info = []
+    max_num_bits = 0
+    for creg in circuit.cregs:
+        name = creg.name
+        num_bits = creg.size
+        if num_bits != 0:
+            start = circuit.find_bit(creg[0]).index
+        else:
+            start = 0
+        meas_info.append(
+            _MeasureInfo(
+                creg_name=name,
+                num_bits=num_bits,
+                num_bytes=_min_num_bytes(num_bits),
+                start=start,
+            )
+        )
+        max_num_bits = max(max_num_bits, start + num_bits)
+    return meas_info, _min_num_bytes(max_num_bits)
+
+
+def _prepare_memory(results: list[Result]) -> list[list[str]]:
+    """Joins splitted results if exceeding max_experiments"""
+    lst = []
+    for res in results:
+        for exp in res.results:
+            if hasattr(exp.data, "memory") and exp.data.memory:
+                lst.append(exp.data.memory)
+            else:
+                # no measure in a circuit
+                lst.append(["0x0"] * exp.shots)
+    return lst
+
+
+def _memory_array(results: list[list[str]], num_bytes: int) -> NDArray[np.uint8]:
+    """Converts the memory data into an array in an unpacked way."""
+    lst = []
+    for memory in results:
+        if num_bytes > 0:
+            data = b"".join(int(i, 16).to_bytes(num_bytes, "big") for i in memory)
+            data = np.frombuffer(data, dtype=np.uint8).reshape(-1, num_bytes)
+        else:
+            # no measure in a circuit
+            data = np.zeros((len(memory), num_bytes), dtype=np.uint8)
+        lst.append(data)
+    ary = np.asarray(lst)
+    return np.unpackbits(ary, axis=-1, bitorder="big")
+
+
+def _samples_to_packed_array(
+    samples: NDArray[np.uint8], num_bits: int, start: int
+) -> NDArray[np.uint8]:
+    """Converts an unpacked array of the memory data into a packed array."""
+    # samples of `Backend.run(memory=True)` will be the order of
+    # clbit_last, ..., clbit_1, clbit_0
+    # place samples in the order of clbit_start+num_bits-1, ..., clbit_start+1, clbit_start
+    if start == 0:
+        ary = samples[:, -start - num_bits :]
+    else:
+        ary = samples[:, -start - num_bits : -start]
+    # pad 0 in the left to align the number to be mod 8
+    # since np.packbits(bitorder='big') pads 0 to the right.
+    pad_size = -num_bits % 8
+    ary = np.pad(ary, ((0, 0), (pad_size, 0)), constant_values=0)
+    # pack bits in big endian order
+    ary = np.packbits(ary, axis=-1, bitorder="big")
+    return ary

qiskit/primitives/base/base_estimator.py

@@ -18,8 +18,6 @@ from abc import abstractmethod, ABC
 from collections.abc import Iterable, Sequence
 from copy import copy
 from typing import Generic, TypeVar
-import numpy as np
-from numpy.typing import NDArray
 
 from qiskit.circuit import QuantumCircuit
 from qiskit.providers import JobV1 as Job
@@ -27,7 +25,6 @@ from qiskit.quantum_info.operators import SparsePauliOp
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 
 from ..containers import (
-    make_data_bin,
     DataBin,
     EstimatorPubLike,
     PrimitiveResult,
@@ -205,12 +202,10 @@ class BaseEstimatorV2(ABC):
     """
 
     @staticmethod
-    def _make_data_bin(pub: EstimatorPub) -> DataBin:
-        # provide a standard way to construct estimator databins to ensure that names match
-        # across implementations
-        return make_data_bin(
-            (("evs", NDArray[np.float64]), ("stds", NDArray[np.float64])), pub.shape
-        )
+    def _make_data_bin(_: EstimatorPub) -> type[DataBin]:
+        # this method is present for backwards compat. new primitive implementatinos
+        # should avoid it.
+        return DataBin
 
     @abstractmethod
     def run(

qiskit/primitives/base/base_sampler.py

@@ -23,8 +23,8 @@ from qiskit.circuit import QuantumCircuit
 from qiskit.providers import JobV1 as Job
 
 from ..containers.primitive_result import PrimitiveResult
-from ..containers.pub_result import PubResult
 from ..containers.sampler_pub import SamplerPubLike
+from ..containers.sampler_pub_result import SamplerPubResult
 from . import validation
 from .base_primitive import BasePrimitive
 from .base_primitive_job import BasePrimitiveJob
@@ -165,7 +165,7 @@ class BaseSamplerV2(ABC):
     @abstractmethod
     def run(
         self, pubs: Iterable[SamplerPubLike], *, shots: int | None = None
-    ) -> BasePrimitiveJob[PrimitiveResult[PubResult]]:
+    ) -> BasePrimitiveJob[PrimitiveResult[SamplerPubResult]]:
         """Run and collect samples from each pub.
 
         Args:

qiskit/primitives/containers/__init__.py

@@ -15,11 +15,13 @@ Data containers for primitives.
 """
 
 
+from .bindings_array import BindingsArrayLike
 from .bit_array import BitArray
-from .data_bin import make_data_bin, DataBin
+from .data_bin import DataBin, make_data_bin
+from .estimator_pub import EstimatorPubLike
+from .observables_array import ObservableLike, ObservablesArrayLike
 from .primitive_result import PrimitiveResult
 from .pub_result import PubResult
-from .estimator_pub import EstimatorPubLike
 from .sampler_pub import SamplerPubLike
-from .bindings_array import BindingsArrayLike
-from .observables_array import ObservableLike, ObservablesArrayLike
+from .sampler_pub_result import SamplerPubResult
+from .shape import Shaped

qiskit/primitives/containers/bit_array.py

@@ -19,13 +19,15 @@ from __future__ import annotations
 from collections import defaultdict
 from functools import partial
 from itertools import chain, repeat
-from typing import Callable, Iterable, Literal, Mapping
+from typing import Callable, Iterable, Literal, Mapping, Sequence
 
 import numpy as np
 from numpy.typing import NDArray
 
-from qiskit.result import Counts
+from qiskit.exceptions import QiskitError
+from qiskit.result import Counts, sampled_expectation_value
 
+from .observables_array import ObservablesArray, ObservablesArrayLike
 from .shape import ShapedMixin, ShapeInput, shape_tuple
 
 # this lookup table tells you how many bits are 1 in each uint8 value
@@ -37,6 +39,23 @@ def _min_num_bytes(num_bits: int) -> int:
     return num_bits // 8 + (num_bits % 8 > 0)
 
 
+def _unpack(bit_array: BitArray) -> NDArray[np.uint8]:
+    arr = np.unpackbits(bit_array.array, axis=-1, bitorder="big")
+    arr = arr[..., -1 : -bit_array.num_bits - 1 : -1]
+    return arr
+
+
+def _pack(arr: NDArray[np.uint8]) -> tuple[NDArray[np.uint8], int]:
+    arr = arr[..., ::-1]
+    num_bits = arr.shape[-1]
+    pad_size = -num_bits % 8
+    if pad_size > 0:
+        pad_width = [(0, 0)] * (arr.ndim - 1) + [(pad_size, 0)]
+        arr = np.pad(arr, pad_width, constant_values=0)
+    arr = np.packbits(arr, axis=-1, bitorder="big")
+    return arr, num_bits
+
+
 class BitArray(ShapedMixin):
     """Stores an array of bit values.
 
@@ -110,6 +129,14 @@ class BitArray(ShapedMixin):
         desc = f"<shape={self.shape}, num_shots={self.num_shots}, num_bits={self.num_bits}>"
         return f"BitArray({desc})"
 
+    def __getitem__(self, indices):
+        """Slices the array along an existing axis of the array."""
+        if isinstance(indices, tuple) and len(indices) >= self.ndim + 2:
+            raise ValueError(
+                "BitArrays cannot be sliced along the bits axis, see slice_bits() instead."
+            )
+        return BitArray(self._array[indices], self.num_bits)
+
     @property
     def array(self) -> NDArray[np.uint8]:
         """The raw NumPy array of data."""
@@ -347,3 +374,267 @@ class BitArray(ShapedMixin):
         else:
             raise ValueError("Cannot change the size of the array.")
         return BitArray(self._array.reshape(shape), self.num_bits)
+
+    def transpose(self, *axes) -> "BitArray":
+        """Return a bit array with axes transposed.
+
+        Args:
+            axes: None, tuple of ints or n ints. See `ndarray.transpose
+                <https://numpy.org/doc/stable/reference/generated/
+                numpy.ndarray.transpose.html#numpy.ndarray.transpose>`_
+                for the details.
+
+        Returns:
+            BitArray: A bit array with axes permuted.
+
+        Raises:
+            ValueError: If ``axes`` don't match this bit array.
+            ValueError: If ``axes`` includes any indices that are out of bounds.
+        """
+        if len(axes) == 0:
+            axes = tuple(reversed(range(self.ndim)))
+        if len(axes) == 1 and isinstance(axes[0], Sequence):
+            axes = axes[0]
+        if len(axes) != self.ndim:
+            raise ValueError("axes don't match bit array")
+        for i in axes:
+            if i >= self.ndim or self.ndim + i < 0:
+                raise ValueError(
+                    f"axis {i} is out of bounds for bit array of dimension {self.ndim}."
+                )
+        axes = tuple(i if i >= 0 else self.ndim + i for i in axes) + (-2, -1)
+        return BitArray(self._array.transpose(axes), self.num_bits)
+
+    def slice_bits(self, indices: int | Sequence[int]) -> "BitArray":
+        """Return a bit array sliced along the bit axis of some indices of interest.
+
+        .. note::
+
+            The convention used by this method is that the index ``0`` corresponds to
+            the least-significant bit in the :attr:`~array`, or equivalently
+            the right-most bitstring entry as returned by
+            :meth:`~get_counts` or :meth:`~get_bitstrings`, etc.
+
+            If this bit array was produced by a sampler, then an index ``i`` corresponds to the
+            :class:`~.ClassicalRegister` location ``creg[i]``.
+
+        Args:
+            indices: The bit positions of interest to slice along.
+
+        Returns:
+            A bit array sliced along the bit axis.
+
+        Raises:
+            ValueError: If there are any invalid indices of the bit axis.
+        """
+        if isinstance(indices, int):
+            indices = (indices,)
+        for index in indices:
+            if index < 0 or index >= self.num_bits:
+                raise ValueError(
+                    f"index {index} is out of bounds for the number of bits {self.num_bits}."
+                )
+        # This implementation introduces a temporary 8x memory overhead due to bit
+        # unpacking. This could be fixed using bitwise functions, at the expense of a
+        # more complicated implementation.
+        arr = _unpack(self)
+        arr = arr[..., indices]
+        arr, num_bits = _pack(arr)
+        return BitArray(arr, num_bits)
+
+    def slice_shots(self, indices: int | Sequence[int]) -> "BitArray":
+        """Return a bit array sliced along the shots axis of some indices of interest.
+
+        Args:
+            indices: The shots positions of interest to slice along.
+
+        Returns:
+            A bit array sliced along the shots axis.
+
+        Raises:
+            ValueError: If there are any invalid indices of the shots axis.
+        """
+        if isinstance(indices, int):
+            indices = (indices,)
+        for index in indices:
+            if index < 0 or index >= self.num_shots:
+                raise ValueError(
+                    f"index {index} is out of bounds for the number of shots {self.num_shots}."
+                )
+        arr = self._array
+        arr = arr[..., indices, :]
+        return BitArray(arr, self.num_bits)
+
+    def expectation_values(self, observables: ObservablesArrayLike) -> NDArray[np.float64]:
+        """Compute the expectation values of the provided observables, broadcasted against
+        this bit array.
+
+        .. note::
+
+            This method returns the real part of the expectation value even if
+            the operator has complex coefficients due to the specification of
+            :func:`~.sampled_expectation_value`.
+
+        Args:
+            observables: The observable(s) to take the expectation value of.
+            Must have a shape broadcastable with with this bit array and
+            the same number of qubits as the number of bits of this bit array.
+            The observables must be diagonal (I, Z, 0 or 1) too.
+
+        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.
+        """
+        observables = ObservablesArray.coerce(observables)
+        arr_indices = np.fromiter(np.ndindex(self.shape), dtype=object).reshape(self.shape)
+        bc_indices, bc_obs = np.broadcast_arrays(arr_indices, observables)
+        counts = {}
+        arr = np.zeros_like(bc_indices, dtype=float)
+        for index in np.ndindex(bc_indices.shape):
+            loc = bc_indices[index]
+            for pauli, coeff in bc_obs[index].items():
+                if loc not in counts:
+                    counts[loc] = self.get_counts(loc)
+                try:
+                    expval = sampled_expectation_value(counts[loc], pauli)
+                except QiskitError as ex:
+                    raise ValueError(ex.message) from ex
+                arr[index] += expval * coeff
+        return arr
+
+    @staticmethod
+    def concatenate(bit_arrays: Sequence[BitArray], axis: int = 0) -> BitArray:
+        """Join a sequence of bit arrays along an existing axis.
+
+        Args:
+            bit_arrays: 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: 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.
+        """
+        if len(bit_arrays) == 0:
+            raise ValueError("Need at least one bit array to concatenate")
+        num_bits = bit_arrays[0].num_bits
+        num_shots = bit_arrays[0].num_shots
+        ndim = bit_arrays[0].ndim
+        if ndim == 0:
+            raise ValueError("Zero-dimensional bit arrays cannot be concatenated")
+        for i, ba in enumerate(bit_arrays):
+            if ba.num_bits != num_bits:
+                raise ValueError(
+                    "All bit arrays must have same number of bits, "
+                    f"but the bit array at index 0 has {num_bits} bits "
+                    f"and the bit array at index {i} has {ba.num_bits} bits."
+                )
+            if ba.num_shots != num_shots:
+                raise ValueError(
+                    "All bit arrays must have same number of shots, "
+                    f"but the bit array at index 0 has {num_shots} shots "
+                    f"and the bit array at index {i} has {ba.num_shots} shots."
+                )
+            if ba.ndim != ndim:
+                raise ValueError(
+                    "All bit arrays must have same number of dimensions, "
+                    f"but the bit array at index 0 has {ndim} dimension(s) "
+                    f"and the bit array at index {i} has {ba.ndim} dimension(s)."
+                )
+        if axis < 0 or axis >= ndim:
+            raise ValueError(f"axis {axis} is out of bounds for bit array of dimension {ndim}.")
+        data = np.concatenate([ba.array for ba in bit_arrays], axis=axis)
+        return BitArray(data, num_bits)
+
+    @staticmethod
+    def concatenate_shots(bit_arrays: Sequence[BitArray]) -> BitArray:
+        """Join a sequence of bit arrays along the shots axis.
+
+        Args:
+            bit_arrays: 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.
+        """
+        if len(bit_arrays) == 0:
+            raise ValueError("Need at least one bit array to stack")
+        num_bits = bit_arrays[0].num_bits
+        shape = bit_arrays[0].shape
+        for i, ba in enumerate(bit_arrays):
+            if ba.num_bits != num_bits:
+                raise ValueError(
+                    "All bit arrays must have same number of bits, "
+                    f"but the bit array at index 0 has {num_bits} bits "
+                    f"and the bit array at index {i} has {ba.num_bits} bits."
+                )
+            if ba.shape != shape:
+                raise ValueError(
+                    "All bit arrays must have same shape, "
+                    f"but the bit array at index 0 has shape {shape} "
+                    f"and the bit array at index {i} has shape {ba.shape}."
+                )
+        data = np.concatenate([ba.array for ba in bit_arrays], axis=-2)
+        return BitArray(data, num_bits)
+
+    @staticmethod
+    def concatenate_bits(bit_arrays: Sequence[BitArray]) -> BitArray:
+        """Join a sequence of bit arrays along the bits axis.
+
+        .. note::
+            This method is equivalent to per-shot bitstring concatenation.
+
+        Args:
+            bit_arrays: 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.
+        """
+        if len(bit_arrays) == 0:
+            raise ValueError("Need at least one bit array to stack")
+        num_shots = bit_arrays[0].num_shots
+        shape = bit_arrays[0].shape
+        for i, ba in enumerate(bit_arrays):
+            if ba.num_shots != num_shots:
+                raise ValueError(
+                    "All bit arrays must have same number of shots, "
+                    f"but the bit array at index 0 has {num_shots} shots "
+                    f"and the bit array at index {i} has {ba.num_shots} shots."
+                )
+            if ba.shape != shape:
+                raise ValueError(
+                    "All bit arrays must have same shape, "
+                    f"but the bit array at index 0 has shape {shape} "
+                    f"and the bit array at index {i} has shape {ba.shape}."
+                )
+        # This implementation introduces a temporary 8x memory overhead due to bit
+        # unpacking. This could be fixed using bitwise functions, at the expense of a
+        # more complicated implementation.
+        data = np.concatenate([_unpack(ba) for ba in bit_arrays], axis=-1)
+        data, num_bits = _pack(data)
+        return BitArray(data, num_bits)