API reference

Documentation under construction

Polynomial ¶

Polynomial(exponents: ArrayLike, coefficients: ArrayLike)

A multivariate polynomial class.

Represents a multivariate polynomial in the form:

P(X) = ∑ c_i * x_1^e_i1 * x_2^e_i2 * ... * x_n^e_in

where c_i are the coefficients and e_ji are the exponents of each monomial.

PARAMETER	DESCRIPTION
`exponents`	A nested sequence or a NumPy 2D-array with shape (n_monomials, n_vars), where each row contains the exponents of one monomial. The order of variables is assumed to be increasing, i.e., [x_1, x_2, ..., x_n]. TYPE: `ArrayLike`
`coefficients`	A sequence or a NumPy 1D-array with shape (n_monomials,). Containing the corresponding scalar multipliers of each monomial. TYPE: `ArrayLike`

ATTRIBUTE	DESCRIPTION
`n_vars`	Number of variables in the polynomial. TYPE: `int`
`degree`	Total degree of the polynomial. TYPE: `int`
`exponents`	A NumPy 2D-array representing the exponents of the polynomial. TYPE: `ndarray`
`coefficients`	A NumPy 1D-array with the corresponding coefficients. TYPE: `ndarray`

RAISES	DESCRIPTION
`TypeError`	If the input exponents cannot be safely converted to a NumPy 2D-array of integers. If the input coefficients cannot be safely converted to a NumPy 1D-array of floats.
`ValueError`	If the number of exponents does not match the number of coefficients. If the input arrays dimensions are inconsistent. If the input exponents rows are not unique. If any input exponent entry is negative.

Notes

The current implementation allows coefficients to be complex numbers, but complex polynomials are not yet officially supported and may produce unexpected behavior.

Although attributes are publicly accessible, modifying them directly may lead to bugs and unexpected behavior.

Examples:

>>> from polyany import Polynomial

Create the polynomial: 5*x_1**2*x_2*x_3**4*x_5 + 3*x_1*x_2 + 4*x_4**4*x_5**3

>>> exponents = [[1, 1, 0, 0, 0],
...              [0, 0, 0, 4, 3],
...              [2, 1, 4, 0, 1]]
>>> coefficients = [3, 4, 5]
>>> Polynomial(exponents, coefficients)
3*x_1*x_2 + 4*x_4^4*x_5^3 + 5*x_1^2*x_2*x_3^4*x_5

add ¶

__add__(other: object) -> Polynomial

Addition with another polynomial or scalar

PARAMETER	DESCRIPTION
`other`	The value to be added. A scalar can be an int, float, or NumPy scalars. TYPE: `object`

RETURNS	DESCRIPTION
`Polynomial`	A new polynomial representing the sum.

call ¶

__call__(point: ArrayLike) -> float64

Evaluate the polynomial at a given point

PARAMETER	DESCRIPTION
`point`	A point with `n_vars` components. TYPE: `ArrayLike`

RETURNS	DESCRIPTION
`float64`	The result of evaluating the polynomial at `point`.

RAISES	DESCRIPTION
`TypeError`	If `point` cannot be safely converted to a NumPy 1D-array of floats.
`ValueError`	If `point` does not have exactly one dimension. If `point` does not have `n_vars` components.

Examples:

For univariate polynomials:

>>> poly = Polynomial.univariate([1, 2, 3])
>>> poly([0])
np.float64(1.0)
>>> poly([2])
np.float64(17.0)

For multivariate polynomials:

>>> exponents = [[0, 0],
...              [1, 0],
...              [0, 1],
...              [1, 1]]
>>> coefficients = [9, 7, 5, 3]
>>> poly = Polynomial(exponents, coefficients)
>>> poly([0, 0])
np.float64(9.0)
>>> poly([1, 2])
np.float64(32.0)

lshift ¶

__lshift__(other: int) -> Polynomial

Removes empty variables of the Polynomial.

A shorthand for Polynomial.shift(k) with k < 0 using the left shift operator (<<). For more details, see the Polynomial.shift() method.

PARAMETER	DESCRIPTION
`other`	The shift count. Must be a non-negative integer. TYPE: `int`

RETURNS	DESCRIPTION
`Polynomial`	A new polynomial with shifted variables.

RAISES	DESCRIPTION
`ValueError`	If the shift count (`other`) is negative.

neg ¶

__neg__() -> Polynomial

The negation of the polynomial.

All coefficients are multiplied by -1. The exponents remain unchanged.

RETURNS	DESCRIPTION
`Polynomial`	A new polynomial with negated coefficients.

rshift ¶

__rshift__(other: int) -> Polynomial

Adds extra variables to the Polynomial.

A shorthand for Polynomial.shift(k) with k > 0 using the right shift operator (>>). For more details, see the Polynomial.shift() method.

PARAMETER	DESCRIPTION
`other`	The shift count. Must be a non-negative integer. TYPE: `int`

RETURNS	DESCRIPTION
`Polynomial`	A new polynomial with shifted variables.

RAISES	DESCRIPTION
`ValueError`	If the shift count (`other`) is negative.

sub ¶

__sub__(other: Algebraic) -> Polynomial

Subtraction with another polynomial or scalar

PARAMETER	DESCRIPTION
`other`	The value to be subtracted. A scalar can be an int, float, or NumPy scalars. TYPE: `Algebraic`

RETURNS	DESCRIPTION
`Polynomial`	A new polynomial representing the difference.

prune ¶

prune() -> Polynomial

Prune the empty monomials of a polynomial.

Removes all monomials whose associated coefficients are exactly zero.

RETURNS	DESCRIPTION
`Polynomial`	A pruned polynomial, containing only monomials with non-zero coefficients.

Examples:

>>> poly = Polynomial.univariate([1, 0, 0, 1])
>>> poly.exponents
array([[0],
       [1],
       [2],
       [3]])

This polynomial has four terms, but only the first and last have a non-zero coefficient.

>>> pruned = poly.prune()
>>> pruned.exponents
array([[0],
       [3]])

The result keeps only the non-empty monomials, discarding all others.

quadratic_form `classmethod` ¶

quadratic_form(matrix: ArrayLike) -> Polynomial

Creates a quadratic form from its associated symmetric matrix

PARAMETER	DESCRIPTION
`matrix`	A nested sequence or a NumPy 2D array of shape (`n_vars`, `n_vars`) that representing the symmetric matrix associated with the quadratic form. TYPE: `ArrayLike`

RETURNS	DESCRIPTION
`Polynomial`	A second-degree homogeneous multivariate polynomial, i.e, a quadratic form.

RAISES	DESCRIPTION
`TypeError`	If `matrix` is not safe-convertible to a NumPy 2D array with float entries.
`ValueError`	If `matrix` does not have 2 dimensions. If `matrix` is not square.

WARNS	DESCRIPTION
`UserWarning`	If `matrix`is not symmetric.

Notes

If matrix is not symmetric, its symmetric part is used instead, computed as symmetric_part = (matrix + matrix.T) / 2.

Examples:

>>> matrix = [[5, 3, 2],
...           [3, 1, 0],
...           [2, 0, 7]]
>>> Polynomial.quadratic_form(matrix)
5*x_1^2 + 6*x_1*x_2 + x_2^2 + 4*x_1*x_3 + 7*x_3^2

shift ¶

shift(k: int = 1) -> Polynomial

Shifts the polynomial variables.

This method returns a new polynomial with its variables shifted. A positive shift adds extra variables (increasing all variable indices). A negative shift removes variables, but only if they are empty.

PARAMETER	DESCRIPTION
`k`	The shift count. If positive, adds `k` extra variables (increase the variable indices). If negative, remove the first `abs(k)` variables, but only if they are empty (all corresponding exponents are zero). TYPE: `int` DEFAULT: `1`

RETURNS	DESCRIPTION
`Polynomial`	A new polynomial with shifted variables.

RAISES	DESCRIPTION
`TypeError`	If `k` is not an int.
`ValueError`	If `k` is negative and the number of variables after shifting would be less than one. If any of the first `abs(k)` variables are not empty.

Notes

If k = 0 a copy of the polynomial is returned.

The Python shift operators can be used as a syntactic sugar for this method. poly >> 3 is equivalent to poly.shift(3), and poly << 2 is equivalent to poly.shift(-2).

This method is reversible as long as both directions are valid.

The statement poly.shift(k).shift(-k) will return a polynomial equal to the original object poly.
Likewise, if poly.shift(-k) is possible, then applying shift(k) after it will also return a copy of poly.

Examples:

Adding extra variables (shift right), increases the variable indices.

>>> poly = Polynomial.univariate([1, 2, 3])
>>> poly
1 + 2*x_1 + 3*x_1^2
>>> poly.shift(2)
1 + 2*x_3 + 3*x_3^2
>>> poly >> 2 # equivalent syntax
1 + 2*x_3 + 3*x_3^2

Removing empty variables (shift left), decreases the variable indices.

>>> poly = Polynomial([[0, 1], [0, 3], [0, 5]], [10, 20, 30])
>>> poly
10*x_2 + 20*x_2^3 + 30*x_2^5
>>> poly.shift(-1)
10*x_1 + 20*x_1^3 + 30*x_1^5
>>> poly << 1 # equivalent syntax
10*x_1 + 20*x_1^3 + 30*x_1^5

univariate `classmethod` ¶

univariate(coefficients: ArrayLike) -> Polynomial

Creates a univariate polynomial from a coefficients vector

This classmethod is a convenient shortcut to construct a univariate polynomial from a coefficients vector.

PARAMETER	DESCRIPTION
`coefficients`	The coefficients of the univariate polynomial, associated with increasing powers of the variable `x_1`. TYPE: `ArrayLike`

RETURNS	DESCRIPTION
`Polynomial`	A univariate polynomial.

RAISES	DESCRIPTION
`ValueError`	If `coefficients` does not have exactly one dimension.

Examples:

>>> Polynomial.univariate([1, 2, -3, -4, 5])
1 + 2*x_1 - 3*x_1^2 - 4*x_1^3 + 5*x_1^4

zeros `classmethod` ¶

zeros(n_vars: int) -> Polynomial

Create a zero polynomial.

Returns a polynomial with a single monomial (the constant 0) in n_vars variables.

PARAMETER	DESCRIPTION
`n_vars`	Number of variables in the polynomial. TYPE: `int`

RETURNS	DESCRIPTION
`Polynomial`	A zero polynomial.

RAISES	DESCRIPTION
`TypeError`	If `n_vars` is not an int.
`ValueError`	If `n_vars` is less than 1.

Notes

Primarily intended for internal use in specific cases.

Examples:

>>> poly = Polynomial.zeros(3)
>>> poly
0
>>> poly.exponents
array([[0, 0, 0]])
>>> poly.coefficients
array([0.])

types ¶

Algebraic `module-attribute` ¶

Algebraic: TypeAlias = Scalar | Polynomial

An algebraic element that can be a scalar or a Polynomial.

Scalar `module-attribute` ¶

Scalar: TypeAlias = int | float | integer | floating

A numeric scalar that can be a builtin numeric type or a NumPy scalar.

API reference

Polynomial ¶

__add__ ¶

__call__ ¶

__lshift__ ¶

__neg__ ¶

__rshift__ ¶

__sub__ ¶

prune ¶

quadratic_form classmethod ¶

shift ¶

univariate classmethod ¶

zeros classmethod ¶

types ¶

Algebraic module-attribute ¶

Scalar module-attribute ¶

add ¶

call ¶

lshift ¶

neg ¶

rshift ¶

sub ¶

quadratic_form `classmethod` ¶

univariate `classmethod` ¶

zeros `classmethod` ¶

Algebraic `module-attribute` ¶

Scalar `module-attribute` ¶