:py:mod:`pygsti.baseobjs.polynomial` ==================================== .. py:module:: pygsti.baseobjs.polynomial .. autoapi-nested-parse:: Defines the Polynomial class Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.baseobjs.polynomial.Polynomial Functions ~~~~~~~~~ .. autoapisummary:: pygsti.baseobjs.polynomial.bulk_load_compact_polynomials pygsti.baseobjs.polynomial.compact_polynomial_list Attributes ~~~~~~~~~~ .. autoapisummary:: pygsti.baseobjs.polynomial.PLATFORM_BITS pygsti.baseobjs.polynomial.FASTPolynomial .. py:data:: PLATFORM_BITS :value: '0' .. py:class:: Polynomial(coeffs=None, max_num_vars=100) Bases: :py:obj:`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. Attributes ---------- coeffs : dict 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_vars : int The maximum number of independent variables this polynomial can hold. vindices_per_int : int 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 ---------- 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 represenatation is allowed to have (x_0 to x_(`max_num_vars-1`)). This sets the maximum allowed variable index within this polynomial. .. py: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 .. py: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 .. py:property:: vindices_per_int The number of this polynoial's variable indices that can be compactly fit into a single int. Returns ------- int .. py: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 .. py:method:: from_rep(rep) :classmethod: 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. Returns ------- Polynomial .. py:method:: product(list_of_polys) :classmethod: Take the product of multiple polynomials. Parameters ---------- list_of_polys : list List of polynomials to take the product of. Returns ------- Polynomial .. py:method:: 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". Returns ------- Polynomial .. py:method:: 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 ------- float or complex Depending on the types of the coefficients and `variable_values`. .. py:method:: compact(complex_coeff_tape=True) Generate a compact form of this polynomial designed for fast evaluation. The resulting "tapes" can be evaluated using :func:`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 : numpy.ndarray These two 1D arrays specify an efficient means for evaluating this polynomial. .. py:method:: copy() Returns a copy of this polynomial. Returns ------- Polynomial .. py:method:: 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. Returns ------- Polynomial .. py:method:: 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. Returns ------- None .. py:method:: mapvec_indices(mapvec) Performs a bulk find & replace on this polynomial's variable indices. This function is similar to :meth:`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 :meth:`map_indices` maps between *tuples* of indices. Returns ------- Polynomial .. py:method:: mapvec_indices_inplace(mapvec) Performs an in-place bulk find & replace on this polynomial's variable indices. This function is similar to :meth:`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 :meth:`map_indices_inplace` maps between *tuples* of indices. Returns ------- Polynomial .. py:method:: mult(x) Multiplies this polynomial by another polynomial `x`. Parameters ---------- x : Polynomial The polynomial to multiply by. Returns ------- Polynomial The polynomial representing self * x. .. py:method:: scale(x) Scale this polynomial by `x` (multiply all coefficients by `x`). Parameters ---------- x : float or complex The value to scale by. Returns ------- None .. py:method:: scalar_mult(x) Multiplies this polynomial by a scalar `x`. Parameters ---------- x : float or complex The value to multiply by. Returns ------- Polynomial .. py:method:: 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 .. py:data:: FASTPolynomial .. py:function:: bulk_load_compact_polynomials(vtape, ctape, keep_compact=False, max_num_vars=100) Create a list of Polynomial objects from a "tape" of their compact versions. Parameters ---------- vtape : numpy.ndarray A 1D array of variable indices that, together with `ctape`, specify an efficient means for evaluating a set of polynoials. ctape : numpy.ndarray A 1D array of coefficients that, together with `vtape`, specify an efficient means for evaluating a set of polynoials. keep_compact : bool, optional If True the returned list has elements which are (vtape,ctape) tuples for each individual polynomial. If False, then the elements are :class:`Polynomial` objects. max_num_vars : int, optional The maximum number of variables the created polynomials are allowed to have. Returns ------- list A list of Polynomial objects. .. py:function:: compact_polynomial_list(list_of_polys) Create a single vtape,ctape pair from a list of normal Polynomals Parameters ---------- list_of_polys : list A list of :class:`Polynomial` objects. Returns ------- vtape: numpy.ndarray A "tape" of the variable indices. ctape: numpy.ndarray A "tape" of the polynomial coefficients.