ArrayPolynomial¶

class ArrayPolynomial(constant_term=None, array_coefficients=None, monomial_labels=None, array_library=None)[source]¶

Bases: object

A polynomial with array-valued coefficients.

This class represents a multi-variable function of the form:

\[f(c_1, \dots, c_r) = A_\emptyset + \sum_{I \in S} c_I A_I,\]

where in the above:

\(S\) is a finite set of multisets indicating non-zero monomial terms,

For a given multiset of non-negative integers \(I=(i_1, \dots, i_k)\), \(c_I = c_{i_1} \times \dots \times c_{i_k}\), and

The \(A_I\) are arrays of the same shape, indexed by the first dimension.

See the multiset and power series notation section of the perturbation review for an explanation of the multiset notation.

An ArrayPolynomial is instantiated with the arguments:

constant_term specifying the array \(A_\emptyset\).

array_coefficients specifying a list of the arrays \(A_I\), or as a single array whose first index lists the \(A_I\),

monomial_labels specifying the set \(S\) as a list of Multiset instances ordered in correspondence with array_coefficients.

For example, the ArrayPolynomial corresponding to the mathematical polynomial

\[f(c_0, c_1) = A_\emptyset + c_{(0)} A_{(0)} + c_{(0, 1)}A_{(0, 1)} + c_{(1, 1)}A_{(1, 1)}\]

for arrays \(A_\emptyset, A_{(0)}, A_{(0, 1)}, A_{(1, 1)}\) stored in variables A_c, A0, A01, and A11 can be instantiated with

ap = ArrayPolynomial(
    constant_term = A_c
    array_coefficients=[A0, A01, A11],
    monomial_labels=[Multiset({0: 1}), Multiset({0: 1, 1: 1}), Multiset({1: 2})]
)

Once instantiated, the polynomial can be evaluated on an array of variable values, e.g.

c = np.array([c0, c1])
ap(c) # polynomial evaluated on variables

ArrayPolynomial supports some array properties, e.g. ap.shape and ap.ndim return the shape and number of dimensions of the output of the polynomial. Some array methods are also supported, such as transpose and trace, and their output produces a new ArrayPolynomial which evaluates to the array one would obtain by first evaluating the original, then calling the array method. E.g.

ap2 = ap1.transpose()
ap2(c) == ap1(c).transpose()

Finally, ArrayPolynomial supports algebraic operations, e.g.

ap3 = ap1 @ ap2
ap3(c) == ap1(c) @ ap2(c)

It also has specialized algebraic methods that perform algebraic operations while “ignoring” terms. E.g., for two instances ap1 and ap2, the call

ap1.matmul(ap2, monomial_filter=lambda x: len(x) <= 3)

is similar to ap1 @ ap2, but will result in an ArrayPolynomial in which all terms of degree larger than 3 will not be included in the results.

Construct a multivariable matrix polynomial.

Parameters:

constant_term (Union[ndarray, number, int, float, complex, Tracer, Array, spmatrix, BCOO, list, None]) – An array representing the constant term of the polynomial.
array_coefficients (Union[ndarray, number, int, float, complex, Tracer, Array, spmatrix, BCOO, list, None]) – A 3d array representing a list of array coefficients.
monomial_labels (Optional[List[Multiset]]) – A list of multisets with non-negative integer entries of the same length as array_coefficients indicating the monomial coefficient for each corresponding array_coefficients.
array_library (Optional[str]) – Array library for stored array terms.

Raises:

QiskitError – If insufficient information is supplied to define an ArrayPolynomial, or if monomial labels contain anything other than non-negative integers.

Methods

add(other, monomial_filter=None)[source]¶

Add two polynomials with bounds on which terms to keep.

Optionally, a function monomial_filter can be provided to limit which monomials appear in the output. It must accept as input a Multiset and return a bool, and a term with label given by multiset will be included only if monomial_filter(multiset) == True, and will not be computed if monomial_filter(multiset) == False.

Parameters:

other (Union[ArrayPolynomial, ndarray, number, int, float, complex, Tracer, Array, spmatrix, BCOO, list]) – Other to add to self.
monomial_filter (Optional[Callable]) – Function determining which terms to compute and keep.

Return type:

ArrayPolynomial

Returns:

ArrayPolynomial achieved by adding both self and other.

Raises:

QiskitError – if other cannot be cast as an ArrayPolynomial.

compute_monomials(c)[source]¶

Vectorized computation of all scalar monomial terms in the polynomial as specified by self.monomial_labels.

Parameters:: c (Union[ndarray, number, int, float, complex, Tracer, Array, spmatrix, BCOO, list]) – Array of variables.
Return type:: Union[ndarray, number, int, float, complex, Tracer, Array, spmatrix, BCOO, list]
Returns:: Array of all monomial terms ordered according to self.monomial_labels.

conj()[source]¶

Return an ArrayPolynomial that is the conjugate of self.

Return type:: ArrayPolynomial

matmul(other, monomial_filter=None)[source]¶

Matmul self @ other with bounds on which terms to keep.

Parameters:

other (Union[ArrayPolynomial, ndarray, number, int, float, complex, Tracer, Array, spmatrix, BCOO, list]) – Other to add to self.
monomial_filter (Optional[Callable]) – Function determining which terms to compute and keep.

Return type:

ArrayPolynomial

Returns:

ArrayPolynomial achieved by matmul of self and other.

Raises:

QiskitError – if other cannot be cast as an ArrayPolynomial.

mul(other, monomial_filter=None)[source]¶

Entrywise multiplication of two ArrayPolynomials with bounds on which terms to keep.

Parameters:

other (Union[ArrayPolynomial, ndarray, number, int, float, complex, Tracer, Array, spmatrix, BCOO, list]) – Other to add to self.
monomial_filter (Optional[Callable]) – Function determining which terms to compute and keep.

Return type:

ArrayPolynomial

Returns:

ArrayPolynomial achieved by matmul of self and other.

Raises:

QiskitError – if other cannot be cast as an ArrayPolynomial.

sum(axis=None, dtype=None)[source]¶: Perform a sum on the coefficients.

trace(offset=0, axis1=0, axis2=1, dtype=None)[source]¶

Take the trace of the coefficients.

Return type:: ArrayPolynomial

transpose(axes=None)[source]¶

Return the ArrayPolynomial when transposing all coefficients.

Return type:: ArrayPolynomial

Attributes

array_coefficients¶: The array coefficients for non-constant terms.

constant_term¶: The constant term.

monomial_labels¶: The monomial labels corresponding to non-constant terms.

ndim¶: Number of dimensions of the coefficients of the polynomial.

real¶: Return the real part of self.

shape¶: Shape of the arrays in the polynomial.