qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/primitives/containers/bindings_array.py

@@ -0,0 +1,391 @@
+# 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.
+
+"""
+Bindings array class
+"""
+from __future__ import annotations
+
+from typing import Mapping, Union, Tuple
+from collections.abc import Iterable, Mapping as _Mapping
+from itertools import chain, islice
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from qiskit.circuit import Parameter, QuantumCircuit
+
+from .shape import ShapedMixin, ShapeInput, shape_tuple
+
+# Public API classes
+__all__ = ["ParameterLike", "BindingsArrayLike"]
+
+
+ParameterLike = Union[Parameter, str]
+"""A parameter or parameter name."""
+
+BindingsArrayLike = Mapping[Union[ParameterLike, Tuple[ParameterLike, ...]], ArrayLike]
+"""A mapping of numeric bindings for circuit parameters.
+
+This allows array values for single or multi-dimensional sweeps over parameter values.
+
+The mapping keys can be single or tuple of Parameter or parameter name strings.
+The values can be a float for a single parameter an N-dimensional array like where
+the array's last dimension indexes the circuit parameters, with its leading dimensions
+representing the array shape of its parameter bindings.
+
+Examples:
+- 0-d array (single binding): ``{"a": 4, ("b", "c"): [5, 6]}``
+- Single array (last index for parameters): ``{ParameterVector("a", 100): np.ones((10, 10, 100)))``
+- Multiple arrays (last index for parameters, flexible dimensions):
+  ``{("c", "a"): np.ones((10, 10, 2)), "b": np.zeros((10, 10))}``
+"""
+
+
+class BindingsArray(ShapedMixin):
+    r"""Stores parameter binding value sets for a :class:`qiskit.QuantumCircuit`.
+
+    A single parameter binding set provides numeric values to bind to a circuit with free
+    :class:`qiskit.circuit.Parameter`\s. An instance of this class stores an array-valued collection
+    of such sets. The simplest example is a 0-d array consisting of a single parameter binding set,
+    whereas an n-d array of parameter binding sets represents an n-d sweep over values.
+
+    The storage format is a dictionary of arrays attached to parameters,
+    ``{params_0: values_0,...}``. A convention is used where the last dimension of each array
+    indexes (a subset of) circuit parameters. For example, if the last dimension of ``values_0`` is
+    25, then it represents an array of possible binding values for the 25 distinct parameters
+    ``params_0``, where its leading shape is the array :attr:`~.shape` of its binding array. This
+    allows flexibility about whether values for different parameters are stored in one big array, or
+    across several smaller arrays.
+
+    .. plot::
+       :include-source:
+       :nofigs:
+
+        # 0-d array (i.e. only one binding)
+        BindingsArray({"a": 4, ("b", "c"): [5, 6]})
+
+        # single array, last index is parameters
+        parameters = tuple(f"a{idx}" for idx in range(100))
+        BindingsArray({parameters: np.ones((10, 10, 100))})
+
+        # multiple arrays, where each last index is parameters. notice that it's smart enough to
+        # figure out that a missing last dimension corresponds to a single parameter.
+        BindingsArray(
+            {("c", "a"): np.zeros((10, 10, 2)), "b": np.ones((10, 10))}
+        )
+    """
+
+    def __init__(
+        self,
+        data: BindingsArrayLike | None = None,
+        shape: ShapeInput | None = None,
+    ):
+        r"""
+        Initialize a :class:`~.BindingsArray`.
+
+        The ``shape`` argument does not need to be provided whenever it can unambiguously
+        be inferred from the provided arrays. Ambiguity arises whenever the key of an entry of
+        ``data`` contains only one parameter and the corresponding array's shape ends in a one.
+        In this case, it can't be decided whether that one is an index over parameters, or whether
+        it should be incorporated in :attr:`~shape`.
+
+        Since :class:`~.Parameter` objects are only allowed to represent float values, this
+        class casts all given values to float. If an incompatible dtype is given, such as complex
+        numbers, a ``TypeError`` will be raised.
+
+        Args:
+            data: A mapping from one or more parameters to arrays of values to bind
+                them to, where the last axis is over parameters.
+            shape: The leading shape of every array in these bindings.
+
+        Raises:
+            ValueError: If all inputs are ``None``.
+            ValueError: If the shape cannot be automatically inferred from the arrays, or if there
+                is some inconsistency in the shape of the given arrays.
+            TypeError: If some of the vaules can't be cast to a float type.
+        """
+        super().__init__()
+
+        if data is None:
+            self._data = {}
+        else:
+            self._data = {
+                (
+                    _format_key((key,)) if isinstance(key, (Parameter, str)) else _format_key(key)
+                ): np.asarray(val, dtype=float)
+                for key, val in data.items()
+            }
+
+        self._shape = _infer_shape(self._data) if shape is None else shape_tuple(shape)
+        self._num_parameters = None
+
+        self.validate()
+
+    def __getitem__(self, args) -> BindingsArray:
+        # because the parameters live on the last axis, we don't need to do anything special to
+        # accommodate them because there will always be an implicit slice(None, None, None)
+        # on all unspecified trailing dimensions
+        # separately, we choose to not disallow args which touch the last dimension, even though it
+        # would not be a particularly friendly way to chop parameters
+        data = {params: val[args] for params, val in self._data.items()}
+        try:
+            shape = next(iter(data.values())).shape[:-1]
+        except StopIteration:
+            shape = ()
+        return BindingsArray(data, shape)
+
+    def __repr__(self):
+        descriptions = [f"shape={self.shape}", f"num_parameters={self.num_parameters}"]
+        if self.num_parameters:
+            names = list(islice(map(repr, chain.from_iterable(map(_format_key, self._data))), 5))
+            if len(names) < self.num_parameters:
+                names.append("...")
+            descriptions.append(f"parameters=[{', '.join(names)}]")
+        return f"{type(self).__name__}(<{', '.join(descriptions)}>)"
+
+    @property
+    def data(self) -> dict[tuple[str, ...], np.ndarray]:
+        """The keyword values of this array."""
+        return self._data
+
+    @property
+    def num_parameters(self) -> int:
+        """The total number of parameters."""
+        if self._num_parameters is None:
+            self._num_parameters = sum(val.shape[-1] for val in self._data.values())
+        return self._num_parameters
+
+    def as_array(self, parameters: Iterable[ParameterLike] | None = None) -> np.ndarray:
+        """Return the contents of this bindings array as a single NumPy array.
+
+        The parameters are indexed along the last dimension of the returned array.
+
+        Parameters:
+            parameters: Optional parameters that determine the order of the output.
+
+        Returns:
+            This bindings array as a single NumPy array.
+
+        Raises:
+            ValueError: If ``parameters`` are provided, but do not match those found in ``data``.
+        """
+        position = 0
+        ret = np.empty(shape_tuple(self.shape, self.num_parameters))
+
+        if parameters is None:
+            # preserve the order of both the dict and the parameters in the keys
+            for arr in self.data.values():
+                size = arr.shape[-1]
+                ret[..., position : position + size] = arr
+                position += size
+        else:
+            # use the order of the provided parameters
+            parameters = list(parameters)
+            if len(parameters) != self.num_parameters:
+                raise ValueError(
+                    f"Expected {self.num_parameters} parameters but {len(parameters)} received."
+                )
+
+            # If we make it through the following loop without a KeyError, we will know that the
+            # data parameters are a subset of the given parameters. However, the above check
+            # ensures there are at least as many of them as parameters. Thus we will know that
+            # set(parameters) == set(chain(*data.values())).
+            idx_lookup = {_param_name(parameter): idx for idx, parameter in enumerate(parameters)}
+            for arr_params, arr in self.data.items():
+                try:
+                    idxs = [idx_lookup[_param_name(param)] + position for param in arr_params]
+                except KeyError as ex:
+                    missing = next(p for p in map(_param_name, arr_params) if p not in idx_lookup)
+                    raise ValueError(f"Could not find placement for parameter '{missing}'.") from ex
+                ret[..., idxs] = arr
+
+        return ret
+
+    def bind(self, circuit: QuantumCircuit, loc: tuple[int, ...]) -> QuantumCircuit:
+        """Return a new circuit bound to the values at the provided index.
+
+        Args:
+            circuit: The circuit to bind.
+            loc: A tuple of indices, on for each dimension of this array.
+
+        Returns:
+            The bound circuit.
+
+        Raises:
+            ValueError: If the index doesn't have the right number of values.
+        """
+        if len(loc) != self.ndim:
+            raise ValueError(f"Expected {loc} to index all dimensions of {self.shape}.")
+
+        parameters = {
+            param: val
+            for params, vals in self._data.items()
+            for param, val in zip(params, vals[loc])
+        }
+        return circuit.assign_parameters(parameters)
+
+    def bind_all(self, circuit: QuantumCircuit) -> np.ndarray:
+        """Return an object array of bound circuits with the same shape.
+
+        Args:
+            circuit: The circuit to bind.
+
+        Returns:
+            An object array of the same shape containing all bound circuits.
+        """
+        arr = np.empty(self.shape, dtype=object)
+        for idx in np.ndindex(self.shape):
+            arr[idx] = self.bind(circuit, idx)
+        return arr
+
+    def ravel(self) -> BindingsArray:
+        """Return a new :class:`~BindingsArray` with one dimension.
+
+        The returned bindings array has a :attr:`shape` given by ``(size, )``, where the size is the
+        :attr:`~size` of this bindings array.
+
+        Returns:
+            A new bindings array.
+        """
+        return self.reshape(self.size)
+
+    def reshape(self, *shape: int | Iterable[int]) -> BindingsArray:
+        """Return a new :class:`~BindingsArray` with a different shape.
+
+        This results in a new view of the same arrays.
+
+        Args:
+            shape: The shape of the returned bindings array.
+
+        Returns:
+            A new bindings array.
+
+        Raises:
+            ValueError: If the provided shape has a different product than the current size.
+        """
+        shape = shape_tuple(shape)
+        if any(dim < 0 for dim in shape):
+            # to reliably catch the ValueError, we need to manually deal with negative values
+            positive_size = np.prod([dim for dim in shape if dim >= 0], dtype=int)
+            missing_dim = self.size // positive_size
+            shape = tuple(dim if dim >= 0 else missing_dim for dim in shape)
+
+        if np.prod(shape, dtype=int) != self.size:
+            raise ValueError("Reshaping cannot change the total number of elements.")
+
+        data = {ps: val.reshape(shape + val.shape[-1:]) for ps, val in self._data.items()}
+        return BindingsArray(data, shape=shape)
+
+    @classmethod
+    def coerce(cls, bindings_array: BindingsArrayLike) -> BindingsArray:
+        """Coerce an input that is :class:`~BindingsArrayLike` into a new :class:`~BindingsArray`.
+
+        Args:
+            bindings_array: An object to be bindings array.
+
+        Returns:
+            A new bindings array.
+        """
+        if bindings_array is None:
+            bindings_array = cls()
+        elif isinstance(bindings_array, _Mapping):
+            bindings_array = cls(data=bindings_array)
+        elif isinstance(bindings_array, BindingsArray):
+            return bindings_array
+        else:
+            raise TypeError(f"Unsupported type {type(bindings_array)} is given.")
+        return bindings_array
+
+    def validate(self):
+        """Validate the consistency in bindings_array."""
+        for parameters, val in self._data.items():
+            val = self._data[parameters] = _standardize_shape(val, self._shape)
+            if len(parameters) != val.shape[-1]:
+                raise ValueError(
+                    f"Length of {parameters} inconsistent with last dimension of {val}"
+                )
+
+
+def _standardize_shape(val: np.ndarray, shape: tuple[int, ...]) -> np.ndarray:
+    """Return ``val`` or ``val[..., None]``.
+
+    Args:
+        val: The array whose shape to standardize.
+        shape: The shape to standardize to.
+
+    Returns:
+        An array with one more dimension than ``len(shape)``, and whose leading dimensions match
+        ``shape``.
+
+    Raises:
+        ValueError: If the leading shape of ``val`` does not match the ``shape``.
+    """
+    if val.shape == shape:
+        val = val[..., None]
+    elif val.ndim - 1 != len(shape) or val.shape[:-1] != shape:
+        raise ValueError(f"Array with shape {val.shape} inconsistent with {shape}")
+    return val
+
+
+def _infer_shape(data: dict[tuple[Parameter, ...], np.ndarray]) -> tuple[int, ...]:
+    """Return a shape tuple that consistently defines the leading dimensions of all arrays.
+
+    Args:
+        data: A mapping from tuples to arrays, where the length of each tuple should match the
+            last dimension of the corresponding array.
+
+    Returns:
+        A shape tuple that matches the leading dimension of every array.
+
+    Raises:
+        ValueError: If this cannot be done unambiguously.
+    """
+    only_possible_shapes = None
+
+    def examine_array(*possible_shapes):
+        nonlocal only_possible_shapes
+        if only_possible_shapes is None:
+            only_possible_shapes = set(possible_shapes)
+        else:
+            only_possible_shapes.intersection_update(possible_shapes)
+
+    for parameters, val in data.items():
+        if len(parameters) != 1:
+            # the last dimension _has_ to be over parameters
+            examine_array(val.shape[:-1])
+        elif val.shape and val.shape[-1] == 1:
+            # this case is a convention, and separated from the previous case for clarity:
+            # if the last axis is 1-d, make an assumption that it is for our 1 parameter
+            examine_array(val.shape[:-1])
+        else:
+            # otherwise, the user has left off the last axis and we'll be nice to them
+            examine_array(val.shape)
+
+    if only_possible_shapes is None:
+        return ()
+    if len(only_possible_shapes) == 1:
+        return next(iter(only_possible_shapes))
+    elif len(only_possible_shapes) == 0:
+        raise ValueError("Could not find any consistent shape.")
+    raise ValueError(
+        "Could not unambiguously determine the intended shape, all shapes in "
+        f"{only_possible_shapes} are consistent with the input; specify shape manually."
+    )
+
+
+def _format_key(key: tuple[Parameter | str, ...]):
+    return tuple(map(_param_name, key))
+
+
+def _param_name(param: Parameter | str) -> str:
+    return param.name if isinstance(param, Parameter) else param