API documentation

HornerMultivarPolynomial

class multivar_horner.HornerMultivarPolynomial(coefficients, exponents, rectify_input: bool = False, compute_representation: bool = False, verbose: bool = False, keep_tree: bool = False, store_c_instr: bool = False, store_numpy_recipe: bool = False, *args, **kwargs)[source]

Bases: AbstractPolynomial

a representation of a multivariate polynomial using Horner factorisation

after computing the factorised representation of the polynomial, the instructions required for evaluation are being compiled and stored. The default format is C instructions. When there is no C compiler installed, the fallback option is encoding the required instructions in numpy arrays (here referred to as “recipes”), which can be processed by (numba) just in time compiled functions.

Parameters
  • coefficients – ndarray of floats with shape (N,1) representing the coefficients of the monomials NOTE: coefficients with value 0 and 1 are allowed and will not affect the internal representation, because coefficients must be replaceable

  • exponents – ndarray of unsigned integers with shape (N,m) representing the exponents of the monomials where m is the number of dimensions (self.dim), the ordering corresponds to the ordering of the coefficients, every exponent row has to be unique!

  • rectify_input – bool, default=False whether to convert coefficients and exponents into compatible numpy arrays with this set to True, coefficients and exponents can be given in standard python arrays

  • compute_representation – bool, default=False whether to compute a string representation of the polynomial

  • verbose – bool, default=False whether to print status statements

  • keep_tree – whether the factorisation tree object should be kept in memory after finishing factorisation

  • store_c_instr – whether a C file with all required evaluation instructions should be created under any circumstances. By default the class will use C based evaluation, but skip if no compiler (gcc/cc) is installed.

  • store_numpy_recipe – whether a pickle file with all required evaluation instructions in the custom numpy+numba format should be created under any circumstances. By default the class will use C based evaluation and only use this evaluation format as fallback.

num_monomials

the amount of coefficients/monomials N of the polynomial

dim

the dimensionality m of the polynomial NOTE: the polynomial needs not to actually depend on all m dimensions

unused_variables

the dimensions the polynomial does not depend on

num_ops

the amount of mathematical operations required to evaluate the polynomial in this representation

representation

a human readable string visualising the polynomial representation

total_degree

the usual notion of degree for a polynomial. = the maximum sum of exponents in any of its monomials = the maximum l_1-norm of the exponent vectors of all monomials in contrast to 1D polynomials, different concepts of degrees exist for polynomials in multiple dimensions. following the naming in [1] L. Trefethen, “Multivariate polynomial approximation in the hypercube”, Proceedings of the American Mathematical Society, vol. 145, no. 11, pp. 4837–4844, 2017.

euclidean_degree

the maximum l_2-norm of the exponent vectors of all monomials. NOTE: this is not in general an integer

maximal_degree

the largest exponent in any of its monomials = the maximum l_infinity-norm of the exponent vectors of all monomials

factorisation

a tuple of factorisation_tree and factor_container. s. below

factorisation_tree

the object oriented, recursive data structure representing the factorisation (only if keep_tree=True)

factor_container

the object containing all (unique) factors of the factorisation (only if keep_tree=True)

root_value_idx

the index in the value array where the value of this polynomial (= root of the factorisation_tree) will be stored

value_array_length

the amount of addresses (storage) required to evaluate the polynomial. for evaluating the polynomial in tree form intermediary results have to be stored in a value array. the value array begins with the coefficients of the polynomial. (without further optimisation) every factor requires its own address.

copy_recipe

ndarray encoding the operations required to evaluate all scalar factors with exponent 1

scalar_recipe

ndarray encoding the operations required to evaluate all remaining scalar factors

monomial_recipe

ndarray encoding the operations required to evaluate all monomial factors

tree_recipe

ndarray encoding the addresses required to evaluate the polynomial values of the factorisation_tree.

tree_ops

ndarray encoding the type of operation required to evaluate the polynomial values of the factorisation_tree. encoded as a boolean ndarray separate from tree_recipe, since only the two operations ADD & MUL need to be encoded.

Raises
  • TypeError – if coefficients or exponents are not given as ndarrays of the required dtype

  • ValueError – if coefficients or exponents do not have the required shape or do not fulfill the other requirements

__init__(coefficients, exponents, rectify_input: bool = False, compute_representation: bool = False, verbose: bool = False, keep_tree: bool = False, store_c_instr: bool = False, store_numpy_recipe: bool = False, *args, **kwargs)[source]
root_class: Type
keep_tree: bool
value_array_length: int
recipe: Tuple
ctype_x
ctype_coeff
property factorisation_tree: BasePolynomialNode
property factor_container: FactorContainer
compute_string_representation(coeff_fmt_str: str = '{:.2}', factor_fmt_str: str = 'x_{dim}^{exp}', *args, **kwargs) str[source]

computes a string representation of the polynomial and sets self.representation

Returns

a string representing this polynomial instance

eval(x: Union[ndarray, List[float]], rectify_input: bool = False) float[source]

computes the value of the polynomial at query point x

either uses C or numpy+Numba evaluation

Parameters
  • x – ndarray of floats with shape = [self.dim] representing the query point

  • rectify_input – whether to convert coefficients and exponents into compatible numpy arrays with this set to True, the query point x can be given in standard python arrays

Returns

the value of the polynomial at point x

Raises
  • TypeError – if x is not given as ndarray of dtype float

  • ValueError – if x does not have the shape [self.dim]

eval_complex(x: ndarray) complex128[source]

computes the value of the polynomial at a complex query point x

Parameters

x – the query point given as numpy complex type

Returns

the complex value of the polynomial at point x

Raises
  • TypeError – if x is not given as ndarray of dtype complex

  • ValueError – if x does not have the shape [self.dim]

property c_eval_fct
get_c_file_name(ending: str = '.c') str[source]
property c_file: Path
property c_file_compiled
property recipe_file: Path
get_c_instructions() str[source]
factorisation
root_value_idx
use_c_eval
change_coefficients(coefficients: Union[ndarray, List[float]], rectify_input: bool = False, compute_representation: bool = False, in_place: bool = False, *args, **kwargs) AbstractPolynomial
coefficients: ndarray
compute_representation: bool
dim: int
euclidean_degree: float
exponents: ndarray
export_pickle(path: str = 'multivar_polynomial.pickle')
get_gradient(*args, **kwargs) List[AbstractPolynomial]

Note

all arguments will be passed to the constructor of the derivative polynomials

Returns

the list of all partial derivatives

get_partial_derivative(i: int, *args, **kwargs) AbstractPolynomial

retrieves a partial derivative

Note

all given additional arguments will be passed to the constructor of the derivative polynomial

Parameters

i – dimension to derive with respect to. ATTENTION: dimension counting starts with 1 (i >= 1)

Returns

the partial derivative of this polynomial wrt. the i-th dimension

maximal_degree: int
num_monomials: int
num_ops: int
print(*args)
representation: str
total_degree: int
unused_variables
verbose: bool

MultivarPolynomial

class multivar_horner.MultivarPolynomial(coefficients: Union[ndarray, List[float]], exponents: Union[ndarray, List[List[int]]], rectify_input: bool = False, compute_representation: bool = False, verbose: bool = False, *args, **kwargs)[source]

Bases: AbstractPolynomial

a representation of a multivariate polynomial in ‘canonical form’ (without any factorisation)

Parameters
  • coefficients – ndarray of floats with shape (N,1) representing the coefficients of the monomials NOTE: coefficients with value 0 and 1 are allowed and will not affect the internal representation, because coefficients must be replaceable

  • exponents – ndarray of unsigned integers with shape (N,m) representing the exponents of the monomials where m is the number of dimensions (self.dim), the ordering corresponds to the ordering of the coefficients, every exponent row has to be unique!

  • rectify_input – bool, default=False whether to convert coefficients and exponents into compatible numpy arrays with this set to True, coefficients and exponents can be given in standard python arrays

  • compute_representation – bool, default=False whether to compute a string representation of the polynomial

  • verbose – bool, default=False whether to print status statements

num_monomials

the amount of coefficients/monomials N of the polynomial

dim

the dimensionality m of the polynomial NOTE: the polynomial needs not to actually depend on all m dimensions

unused_variables

the dimensions the polynomial does not depend on

num_ops

the amount of mathematical operations required to evaluate the polynomial in this representation

representation

a human readable string visualising the polynomial representation

Raises
  • TypeError – if coefficients or exponents are not given as ndarrays of the required dtype

  • ValueError – if coefficients or exponents do not have the required shape or do not fulfill the other requirements or rectify_input=True and there are negative exponents

__init__(coefficients: Union[ndarray, List[float]], exponents: Union[ndarray, List[List[int]]], rectify_input: bool = False, compute_representation: bool = False, verbose: bool = False, *args, **kwargs)[source]
num_ops: int
compute_string_representation(coeff_fmt_str: str = '{:.2}', factor_fmt_str: str = 'x_{dim}^{exp}', *args, **kwargs) str[source]

computes a string representation of the polynomial and sets self.representation

Returns

a string representing this polynomial instance

eval(x: Union[ndarray, List[float]], rectify_input: bool = False) float[source]

computes the value of the polynomial at query point x

makes use of fast Numba just in time compiled functions

Parameters
  • x – ndarray of floats with shape = [self.dim] representing the query point

  • rectify_input – bool, default=False whether to convert coefficients and exponents into compatible numpy arrays with this set to True, the query point x can be given in standard python arrays

Returns

the value of the polynomial at point x

Raises
  • TypeError – if x is not given as ndarray of dtype float

  • ValueError – if x does not have the shape [self.dim]

eval_complex(x: ndarray) complex128[source]

computes the value of the polynomial at a complex query point x

Parameters

x – the query point given as numpy complex type

Returns

the complex value of the polynomial at point x

Raises
  • TypeError – if x is not given as ndarray of dtype complex

  • ValueError – if x does not have the shape [self.dim]

compute_representation: bool
coefficients: ndarray
euclidean_degree: float
exponents: ndarray
num_monomials: int
dim: int
maximal_degree: int
total_degree: int
unused_variables
representation: str
verbose: bool
change_coefficients(coefficients: Union[ndarray, List[float]], rectify_input: bool = False, compute_representation: bool = False, in_place: bool = False, *args, **kwargs) AbstractPolynomial
export_pickle(path: str = 'multivar_polynomial.pickle')
get_gradient(*args, **kwargs) List[AbstractPolynomial]

Note

all arguments will be passed to the constructor of the derivative polynomials

Returns

the list of all partial derivatives

get_partial_derivative(i: int, *args, **kwargs) AbstractPolynomial

retrieves a partial derivative

Note

all given additional arguments will be passed to the constructor of the derivative polynomial

Parameters

i – dimension to derive with respect to. ATTENTION: dimension counting starts with 1 (i >= 1)

Returns

the partial derivative of this polynomial wrt. the i-th dimension

print(*args)

HornerMultivarPolynomialOpt

class multivar_horner.HornerMultivarPolynomialOpt(coefficients, exponents, rectify_input: bool = False, compute_representation: bool = False, verbose: bool = False, keep_tree: bool = False, store_c_instr: bool = False, store_numpy_recipe: bool = False, *args, **kwargs)[source]

Bases: HornerMultivarPolynomial

a Horner factorised polynomial with an optimal factorisation found by searching all possible factorisations

Optimality in this context refers to the minimal amount of operations needed for evaluation in comparison to other Horner factorisation (not other factorisatio/optimisation techniques).

NOTES:

  • this requires MUCH more computational resources than just trying one factorisation

    (the number of possible factorisations is growing exponentially with the size of the polynomial!).

  • for the small polynomial examples in the current tests, the found factorisations were not superior

root_class: Type
factorisation
root_value_idx
value_array_length: int
keep_tree: bool
use_c_eval
recipe: Tuple
ctype_x
ctype_coeff
__init__(coefficients, exponents, rectify_input: bool = False, compute_representation: bool = False, verbose: bool = False, keep_tree: bool = False, store_c_instr: bool = False, store_numpy_recipe: bool = False, *args, **kwargs)
property c_eval_fct
property c_file: Path
property c_file_compiled
change_coefficients(coefficients: Union[ndarray, List[float]], rectify_input: bool = False, compute_representation: bool = False, in_place: bool = False, *args, **kwargs) AbstractPolynomial
coefficients: ndarray
compute_representation: bool
compute_string_representation(coeff_fmt_str: str = '{:.2}', factor_fmt_str: str = 'x_{dim}^{exp}', *args, **kwargs) str

computes a string representation of the polynomial and sets self.representation

Returns

a string representing this polynomial instance

dim: int
euclidean_degree: float
eval(x: Union[ndarray, List[float]], rectify_input: bool = False) float

computes the value of the polynomial at query point x

either uses C or numpy+Numba evaluation

Parameters
  • x – ndarray of floats with shape = [self.dim] representing the query point

  • rectify_input – whether to convert coefficients and exponents into compatible numpy arrays with this set to True, the query point x can be given in standard python arrays

Returns

the value of the polynomial at point x

Raises
  • TypeError – if x is not given as ndarray of dtype float

  • ValueError – if x does not have the shape [self.dim]

eval_complex(x: ndarray) complex128

computes the value of the polynomial at a complex query point x

Parameters

x – the query point given as numpy complex type

Returns

the complex value of the polynomial at point x

Raises
  • TypeError – if x is not given as ndarray of dtype complex

  • ValueError – if x does not have the shape [self.dim]

exponents: ndarray
export_pickle(path: str = 'multivar_polynomial.pickle')
property factor_container: FactorContainer
property factorisation_tree: BasePolynomialNode
get_c_file_name(ending: str = '.c') str
get_c_instructions() str
get_gradient(*args, **kwargs) List[AbstractPolynomial]

Note

all arguments will be passed to the constructor of the derivative polynomials

Returns

the list of all partial derivatives

get_partial_derivative(i: int, *args, **kwargs) AbstractPolynomial

retrieves a partial derivative

Note

all given additional arguments will be passed to the constructor of the derivative polynomial

Parameters

i – dimension to derive with respect to. ATTENTION: dimension counting starts with 1 (i >= 1)

Returns

the partial derivative of this polynomial wrt. the i-th dimension

maximal_degree: int
num_monomials: int
num_ops: int
print(*args)
property recipe_file: Path
representation: str
total_degree: int
unused_variables
verbose: bool