BindingsArray

class qiskit.primitives.BindingsArray(data=None, shape=None)

Bases: ShapedMixin

Stores parameter binding value sets for a qiskit.QuantumCircuit.

A single parameter binding set provides numeric values to bind to a circuit with free qiskit.circuit.Parameters. 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 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.

import numpy as np
from qiskit.primitives import BindingsArray
 
# 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))}
)

Initialize a 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 shape.

Since 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.

Parameters

data (BindingsArrayLike | None) – A mapping from one or more parameters to arrays of values to bind them to, where the last axis is over parameters.
shape (ShapeInput | None) – 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 values can’t be cast to a float type.