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 ofMultiset
instances ordered in correspondence witharray_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
, andA11
can be instantiated withap = 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
andap.ndim
return the shape and number of dimensions of the output of the polynomial. Some array methods are also supported, such astranspose
andtrace
, and their output produces a newArrayPolynomial
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
andap2
, the callap1.matmul(ap2, monomial_filter=lambda x: len(x) <= 3)
is similar to
ap1 @ ap2
, but will result in anArrayPolynomial
in which all terms of degree larger than3
will not be included in the results.Construct a multivariable matrix polynomial.
- Parameters:
constant_term (
Union
[ndarray
,number
,int
,float
,complex
,Tracer
,Array
,Array
,spmatrix
,BCOO
,list
,None
]) – An array representing the constant term of the polynomial.array_coefficients (
Union
[ndarray
,number
,int
,float
,complex
,Tracer
,Array
,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 asarray_coefficients
indicating the monomial coefficient for each correspondingarray_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 aMultiset
and return abool
, and a term with label given bymultiset
will be included only ifmonomial_filter(multiset) == True
, and will not be computed ifmonomial_filter(multiset) == False
.- Parameters:
other (
Union
[ArrayPolynomial
,ndarray
,number
,int
,float
,complex
,Tracer
,Array
,Array
,spmatrix
,BCOO
,list
]) – Other to add to self.monomial_filter (
Optional
[Callable
]) – Function determining which terms to compute and keep.
- Return type:
- 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
,Array
,spmatrix
,BCOO
,list
]) – Array of variables.- Return type:
Union
[ndarray
,number
,int
,float
,complex
,Tracer
,Array
,Array
,spmatrix
,BCOO
,list
]- Returns:
Array of all monomial terms ordered according to
self.monomial_labels
.
- matmul(other, monomial_filter=None)[source]#
Matmul self @ other 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 aMultiset
and return abool
, and a term with label given bymultiset
will be included only ifmonomial_filter(multiset) == True
, and will not be computed ifmonomial_filter(multiset) == False
.- Parameters:
other (
Union
[ArrayPolynomial
,ndarray
,number
,int
,float
,complex
,Tracer
,Array
,Array
,spmatrix
,BCOO
,list
]) – Other to add to self.monomial_filter (
Optional
[Callable
]) – Function determining which terms to compute and keep.
- Return type:
- 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.
Optionally, a function
monomial_filter
can be provided to limit which monomials appear in the output. It must accept as input aMultiset
and return abool
, and a term with label given bymultiset
will be included only ifmonomial_filter(multiset) == True
, and will not be computed ifmonomial_filter(multiset) == False
.- Parameters:
other (
Union
[ArrayPolynomial
,ndarray
,number
,int
,float
,complex
,Tracer
,Array
,Array
,spmatrix
,BCOO
,list
]) – Other to add to self.monomial_filter (
Optional
[Callable
]) – Function determining which terms to compute and keep.
- Return type:
- Returns:
ArrayPolynomial achieved by matmul of self and other.
- Raises:
QiskitError – if other cannot be cast as an ArrayPolynomial.
- trace(offset=0, axis1=0, axis2=1, dtype=None)[source]#
Take the trace of the coefficients.
- Return type:
- transpose(axes=None)[source]#
Return the ArrayPolynomial when transposing all coefficients.
- Return type:
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.