# `pygsti.baseobjs.polynomial`

Defines the Polynomial class

## Module Contents

### Classes

 `FASTPolynomial` A polynomial that behaves like a Python dict of coefficients.

### Functions

 `bulk_load_compact_polynomials`(vtape, ctape[, ...]) Create a list of Polynomial objects from a "tape" of their compact versions. `compact_polynomial_list`(list_of_polys) Create a single vtape,ctape pair from a list of normal Polynomals

### Attributes

pygsti.baseobjs.polynomial.PLATFORM_BITS
class pygsti.baseobjs.polynomial.FASTPolynomial(coeffs=None, max_num_vars=100)

Bases: `object`

A polynomial that behaves like a Python dict of coefficients.

Variables are represented by integer indices, e.g. “2” means “x_2”. Keys are tuples of variable indices and values are numerical coefficients (floating point or complex numbers). To specify a variable to some power, its index is repeated in the key-tuple.

E.g. x_0^2 + 3*x_1 + 4 is stored as {(0,0): 1.0, (1,): 3.0, (): 4.0}

#### Parameters

coeffsdict

A dictionary of coefficients. Keys are tuples of integers that specify the polynomial term the coefficient value multiplies (see above). If None, the zero polynomial (no terms) is created.

max_num_varsint

The maximum number of independent variables this polynomial can hold. Placing a limit on the number of variables allows more compact storage and efficient evaluation of the polynomial.

#### Attributes

coeffsdict

A dictionary whose keys are tuples of variable indices (e.g. x0^2*x1 would translate to (0,0,1)) and values are the coefficients.

max_num_varsint

The maximum number of independent variables this polynomial can hold.

vindices_per_intint

The number of variable indices that can be compactly fit into a single int when there are at most max_num_vars variables.

Initializes a new Polynomial object (a subclass of dict).

Internally (as a dict) a Polynomial represents variables by integer indices, e.g. “2” means “x_2”. Keys are tuples of variable indices and values are numerical coefficients (floating point or complex numbers). A variable to a power > 1 has its index repeated in the key-tuple.

E.g. x_0^2 + 3*x_1 + 4 is stored as {(0,0): 1.0, (1,): 3.0, (): 4.0}

#### Parameters

coeffsdict

A dictionary of coefficients. Keys are tuples of integers that specify the polynomial term the coefficient value multiplies (see above). If None, the zero polynomial (no terms) is created.

max_num_varsint, optional

The maximum number of variables the represenatation is allowed to have (x_0 to x_(max_num_vars-1)). This sets the maximum allowed variable index within this polynomial.

property coeffs

A dictionary of this polynoial’s coefficients.

Keys are tuples of integers that specify the polynomial term the coefficient value multiplies (see above). If None, the zero polynomial (no terms) is created.

##### Returns

dict

property max_num_vars

The maximum number of independent variables this polynomial can hold.

Powers of variables are not “independent”, e.g. the polynomial x0^2 + 2*x0 + 3 has a single indepdent variable.

##### Returns

int

property vindices_per_int

The number of this polynoial’s variable indices that can be compactly fit into a single int.

##### Returns

int

property degree

The largest sum-of-exponents for any term (monomial) within this polynomial.

E.g. for x_2^3 + x_1^2*x_0^2 has degree 4.

##### Returns

int

classmethod from_rep(rep)

Creates a Polynomial from a “representation” (essentially a lite-version) of a Polynomial.

Note: usually we only need to convert from full-featured Python objects to the lighter-weight “representation” objects. Polynomials are an exception, since as the results of probability computations they need to be converted back from “representation-form” to “full-form”.

##### Parameters
repPolynomialRep

A polynomial representation.

##### Returns

Polynomial

classmethod product(list_of_polys)

Take the product of multiple polynomials.

##### Parameters
list_of_polyslist

List of polynomials to take the product of.

##### Returns

Polynomial

deriv(wrt_param)

Take the derivative of this Polynomial with respect to a single variable.

The result is another Polynomial.

E.g. deriv(x_2^3 + 3*x_1, wrt_param=2) = 3x^2

##### Parameters
wrt_paramint

The variable index to differentiate with respect to. E.g. “4” means “differentiate w.r.t. x_4”.

##### Returns

Polynomial

evaluate(variable_values)

Evaluate this polynomial for a given set of variable values.

##### Parameters
variable_valuesarray-like

An object that can be indexed so that variable_values[i] gives the numerical value for i-th variable (x_i).

##### Returns
float or complex

Depending on the types of the coefficients and variable_values.

compact(complex_coeff_tape=True)

Generate a compact form of this polynomial designed for fast evaluation.

The resulting “tapes” can be evaluated using `opcalc.bulk_eval_compact_polynomials()`.

##### Parameters
complex_coeff_tapebool, optional

Whether the ctape returned array is forced to be of complex type. If False, the real part of all coefficients is taken (even if they’re complex).

##### Returns
vtape, ctapenumpy.ndarray

These two 1D arrays specify an efficient means for evaluating this polynomial.

copy()

Returns a copy of this polynomial.

##### Returns

Polynomial

map_indices(mapfn)

Performs a bulk find & replace on this polynomial’s variable indices.

This is useful when the variable indices have external significance (like being the indices of a gate’s parameters) and one want to convert to another set of indices (like a parent model’s parameters).

##### Parameters
mapfnfunction

A function that takes as input an “old” variable-index-tuple (a key of this Polynomial) and returns the updated “new” variable-index-tuple.

##### Returns

Polynomial

map_indices_inplace(mapfn)

Performs an in-place find & replace on this polynomial’s variable indices.

This is useful when the variable indices have external significance (like being the indices of a gate’s parameters) and one want to convert to another set of indices (like a parent model’s parameters).

##### Parameters
mapfnfunction

A function that takes as input an “old” variable-index-tuple (a key of this Polynomial) and returns the updated “new” variable-index-tuple.

##### Returns

None

mapvec_indices(mapvec)

Performs a bulk find & replace on this polynomial’s variable indices.

This function is similar to `map_indices()` but uses a vector to describe individual index updates instead of a function for increased performance.

##### Parameters
mapvecnumpy.ndarray

An array whose i-th element gives the updated “new” index for the i-th variable. Note that this vector maps individual variable indices old->new, whereas mapfn in `map_indices()` maps between tuples of indices.

##### Returns

Polynomial

mapvec_indices_inplace(mapvec)

Performs an in-place bulk find & replace on this polynomial’s variable indices.

This function is similar to `map_indices_inplace()` but uses a vector to describe individual index updates instead of a function for increased performance.

##### Parameters
mapvecnumpy.ndarray

An array whose i-th element gives the updated “new” index for the i-th variable. Note that this vector maps individual variable indices old->new, whereas mapfn in `map_indices_inplace()` maps between tuples of indices.

##### Returns

Polynomial

mult(x)

Multiplies this polynomial by another polynomial x.

##### Parameters
xPolynomial

The polynomial to multiply by.

##### Returns
Polynomial

The polynomial representing self * x.

scale(x)

Scale this polynomial by x (multiply all coefficients by x).

##### Parameters
xfloat or complex

The value to scale by.

##### Returns

None

scalar_mult(x)

Multiplies this polynomial by a scalar x.

##### Parameters
xfloat or complex

The value to multiply by.

##### Returns

Polynomial

to_rep()

Construct a representation of this polynomial.

“Representations” are lightweight versions of objects used to improve the efficiency of intensely computational tasks. Note that Polynomial representations must have the same max_order and max_num_vars in order to interact with each other (add, multiply, etc.).

##### Returns

PolynomialRep

pygsti.baseobjs.polynomial.Polynomial

Create a list of Polynomial objects from a “tape” of their compact versions.

#### Parameters

vtapenumpy.ndarray

A 1D array of variable indices that, together with ctape, specify an efficient means for evaluating a set of polynoials.

ctapenumpy.ndarray

A 1D array of coefficients that, together with vtape, specify an efficient means for evaluating a set of polynoials.

keep_compactbool, optional

If True the returned list has elements which are (vtape,ctape) tuples for each individual polynomial. If False, then the elements are `Polynomial` objects.

max_num_varsint, optional

The maximum number of variables the created polynomials are allowed to have.

#### Returns

list

A list of Polynomial objects.

pygsti.baseobjs.polynomial.compact_polynomial_list(list_of_polys)

Create a single vtape,ctape pair from a list of normal Polynomals

#### Parameters

list_of_polyslist

A list of `Polynomial` objects.

#### Returns

vtape: numpy.ndarray

A “tape” of the variable indices.

ctape: numpy.ndarray

A “tape” of the polynomial coefficients.