pygsti.baseobjs.polynomial.Polynomial

class Polynomial(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:

• coeffs (dict) – 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_vars (int) – 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.

coeffs

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.

Type:

dict

max_num_vars

The maximum number of independent variables this polynomial can hold.

Type:

int

vindices_per_int

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

Type:

int

Initializes a new Polynomial object.

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:

• coeffs (dict) – 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_vars (int, optional) – The maximum number of variables the representation is allowed to have (x_0 to x_(max_num_vars-1)). This sets the maximum allowed variable index within this polynomial.

Methods

__init__([coeffs, max_num_vars])	Initializes a new Polynomial object.
compact([complex_coeff_tape])	Generate a compact form of this polynomial designed for fast evaluation.
copy()	Returns a copy of this polynomial.
deriv(wrt_param)	Take the derivative of this Polynomial with respect to a single variable.
evaluate(variable_values)	Evaluate this polynomial for a given set of variable values.
from_rep(rep)	Creates a Polynomial from a "representation" (essentially a lite-version) of a Polynomial.
from_variable_and_coefficient_lists(...[, ...])	Construct a Polynomial from parallel lists of monomials and coefficients.
map_indices(mapfn)	Performs a bulk find & replace on this polynomial's variable indices.
map_indices_inplace(mapfn)	Performs an in-place find & replace on this polynomial's variable indices.
mapvec_indices(mapvec)	Performs a bulk find & replace on this polynomial's variable indices.
mapvec_indices_inplace(mapvec)	Performs an in-place bulk find & replace on this polynomial's variable indices.
mult(x)	Multiplies this polynomial by another polynomial x.
product(list_of_polys)	Take the product of multiple polynomials.
scalar_mult(x)	Multiplies this polynomial by a scalar x.
scale(x)	Scale this polynomial by x (multiply all coefficients by x).
sum(list_of_polys)	Take the sum of multiple polynomials.
to_rep()	Construct a representation of this polynomial.
to_string([var_labels])	Construct a string representation of this polynomial.

Attributes

coeffs	A dictionary of this polynoial's coefficients.
degree	The largest sum-of-exponents for any term (monomial) within this polynomial.
max_num_vars	The maximum number of independent variables this polynomial can hold.
vindices_per_int	The number of this polynoial's variable indices that can be compactly fit into a single int.

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_tape (bool, 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, ctape – These two 1D arrays specify an efficient means for evaluating this polynomial.

Return type:

numpy.ndarray

copy()

Returns a copy of this polynomial.

Return type:

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_param (int) – The variable index to differentiate with respect to. E.g. “4” means “differentiate w.r.t. x_4”.

Return type:

Polynomial

evaluate(variable_values)

Evaluate this polynomial for a given set of variable values.

Parameters:

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

Returns:

Depending on the types of the coefficients and variable_values.

Return type:

float or complex

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:

rep (PolynomialRep) – A polynomial representation.

Return type:

Polynomial

classmethod from_variable_and_coefficient_lists(variables, coefficients, max_num_vars=100)

Construct a Polynomial from parallel lists of monomials and coefficients.

Unlike the dict-based constructor, variables may list the same monomial more than once; repeated monomials have their coefficients summed.

Parameters:

• variables (sequence of tuple of int) – Monomial terms, each a tuple of variable indices (e.g. (0, 0, 1) for x0^2 x1). May contain repeats.

• coefficients (sequence of complex) – The coefficient multiplying each monomial in variables; must be the same length as variables.

• max_num_vars (int, optional) – The maximum number of variables the representation may have (x_0 to x_(max_num_vars-1)).

Return type:

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:

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

Return type:

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:

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

Return type:

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:

mapvec (numpy.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.

Return type:

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:

mapvec (numpy.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.

Return type:

Polynomial

mult(x)

Multiplies this polynomial by another polynomial x.

Parameters:

x (Polynomial) – The polynomial to multiply by.

Returns:

The polynomial representing self * x.

Return type:

Polynomial

static product(list_of_polys)

Take the product of multiple polynomials.

Parameters:

list_of_polys (list) – List of polynomials to take the product of.

Return type:

Polynomial

scalar_mult(x)

Multiplies this polynomial by a scalar x.

Parameters:

x (float or complex) – The value to multiply by.

Return type:

Polynomial

scale(x)

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

Parameters:

x (float or complex) – The value to scale by.

Return type:

None

static sum(list_of_polys)

Take the sum of multiple polynomials.

Parameters:

list_of_polys (list) – List of polynomials to take the product of.

Return type:

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

Return type:

PolynomialRep

to_string(var_labels=None)

Construct a string representation of this polynomial.

Parameters:

var_labels (None, dict, sequence, or Callable, optional) –

Controls how variable indices are converted to strings:

• None: use default labels like x0, x1, …

• dict: map variable index to label

• sequence: use the i-th element as the label for variable i

• Callable: a function taking an integer index and returning a label

Return type:

str

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.

Return type:

dict

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.

Return type:

int

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 independent variable.

Return type:

int

property vindices_per_int

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

Return type:

int