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¶
- 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]
- property c_eval_fct¶
- property c_file: Path¶
- property c_file_compiled¶
- property recipe_file: Path¶
- 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]
- compute_representation: bool¶
- coefficients: np.ndarray¶
- euclidean_degree: float¶
- exponents: np.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¶
- 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]
- 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¶