# Types

## Variables

`MultivariatePolynomials.AbstractVariable`

— Type`AbstractVariable <: AbstractMonomialLike`

Abstract type for a variable.

`MultivariatePolynomials.variable`

— Function`variable(p::AbstractPolynomialLike)`

Converts `p`

to a variable. Throws `InexactError`

if it is not possible.

**Examples**

Calling `variable(x^2 + x - x^2)`

should return the variable `x`

and calling `variable(1.0y)`

should return the variable `y`

however calling `variable(2x)`

or `variable(x + y)`

should throw `InexactError`

.

**Note**

This operation is not type stable for the TypedPolynomials implementation if `nvariables(p) > 1`

but is type stable for DynamicPolynomials.

`MultivariatePolynomials.name`

— Function`name(v::AbstractVariable)::AbstractString`

Returns the name of a variable.

`MultivariatePolynomials.name_base_indices`

— Function`name_base_indices(v::AbstractVariable)`

Returns the name of the variable (as a `String`

or `Symbol`

) and its indices as a `Vector{Int}`

or tuple of `Int`

s.

`MultivariatePolynomials.variable_union_type`

— Function`variable_union_type(p::AbstractPolynomialLike)`

Return the supertype for variables of `p`

. If `p`

is a variable, it should not be the type of `p`

but the supertype of all variables that could be created.

**Examples**

For `TypedPolynomials`

, a variable of name `x`

has type `Variable{:x}`

so `variable_union_type`

should return `Variable`

. For `DynamicPolynomials`

, all variables have the same type `PolyVar{C}`

where `C`

is `true`

for commutative variables and `false`

for non-commutative ones so `variable_union_type`

should return `PolyVar{C}`

.

`MultivariatePolynomials.similarvariable`

— Function`similarvariable(p::AbstractPolynomialLike, variable::Type{Val{V}})`

Creates a new variable `V`

based upon the the given source polynomial.

`similarvariable(p::AbstractPolynomialLike, v::Symbol)`

Creates a new variable based upon the given source polynomial and the given symbol `v`

. Note that this can lead to type instabilities.

**Examples**

Calling `similarvariable(typedpoly, Val{:x})`

on a polynomial created with `TypedPolynomials`

results in `TypedPolynomials.Variable{:x}`

.

`MultivariatePolynomials.@similarvariable`

— Macro`@similarvariable(p::AbstractPolynomialLike, variable)`

Calls `similarvariable(p, Val{variable})`

and binds the result to a variable with the same name.

**Examples**

Calling `@similarvariable typedpoly x`

on a polynomial created with `TypedPolynomials`

binds `TypedPolynomials.Variable{:x}`

to the variable `x`

.

## Monomials

`MultivariatePolynomials.AbstractMonomialLike`

— Type`AbstractMonomialLike`

Abstract type for a value that can act like a monomial. For instance, an `AbstractVariable`

is an `AbstractMonomialLike`

since it can act as a monomial of one variable with degree `1`

.

`MultivariatePolynomials.AbstractMonomial`

— Type`AbstractMonomial <: AbstractMonomialLike`

Abstract type for a monomial, i.e. a product of variables elevated to a nonnegative integer power.

`MultivariatePolynomials.monomialtype`

— Function`monomialtype(p::AbstractPolynomialLike)`

Return the type of the monomials of `p`

.

`termtype(::Type{PT}) where PT<:AbstractPolynomialLike`

Returns the type of the monomials of a polynomial of type `PT`

.

`MultivariatePolynomials.variables`

— Function`variables(p::AbstractPolynomialLike)`

Returns the tuple of the variables of `p`

in decreasing order. It could contain variables of zero degree, see the example section.

**Examples**

Calling `variables(x^2*y)`

should return `(x, y)`

and calling `variables(x)`

should return `(x,)`

. Note that the variables of `m`

does not necessarily have nonzero degree. For instance, `variables([x^2*y, y*z][1])`

is usually `(x, y, z)`

since the two monomials have been promoted to a common type.

`MultivariatePolynomials.effective_variables`

— Function`effective_variables(p::AbstractPolynomialLike)`

Return a vector of `eltype`

`variable_union_type(p)`

(see `variable_union_type`

), containing all the variables that has nonzero degree in at least one term. That is, return all the variables `v`

such that `maxdegree(p, v)`

is not zero. The returned vector is sorted in decreasing order.

`MultivariatePolynomials.nvariables`

— Function`nvariables(p::AbstractPolynomialLike)`

Returns the number of variables in `p`

, i.e. `length(variables(p))`

. It could be more than the number of variables with nonzero degree (see the Examples section of `variables`

).

**Examples**

Calling `nvariables(x^2*y)`

should return at least 2 and calling `nvariables(x)`

should return at least 1.

`MultivariatePolynomials.exponents`

— Function`exponents(t::AbstractTermLike)`

Returns the exponent of the variables in the monomial of the term `t`

.

**Examples**

Calling `exponents(x^2*y)`

should return `(2, 1)`

.

`MultivariatePolynomials.degree`

— Function`degree(t::AbstractTermLike)`

Returns the *total degree* of the monomial of the term `t`

, i.e. `sum(exponents(t))`

.

`degree(t::AbstractTermLike, v::AbstractVariable)`

Returns the exponent of the variable `v`

in the monomial of the term `t`

.

**Examples**

Calling `degree(x^2*y)`

should return 3 which is $2 + 1$. Calling `degree(x^2*y, x)`

should return 2 and calling `degree(x^2*y, y)`

should return 1.

`MultivariatePolynomials.isconstant`

— Function`isconstant(t::AbstractTermLike)`

Returns whether the monomial of `t`

is constant.

`MultivariatePolynomials.powers`

— Function`powers(t::AbstractTermLike)`

Returns an iterator over the powers of the monomial of `t`

.

**Examples**

Calling `powers(3x^4*y) should return`

((x, 4), (y, 1))`.

`MultivariatePolynomials.constantmonomial`

— Function`constantmonomial(p::AbstractPolynomialLike)`

Returns a constant monomial of the monomial type of `p`

with the same variables as `p`

.

`constantmonomial(::Type{PT}) where {PT<:AbstractPolynomialLike}`

Returns a constant monomial of the monomial type of a polynomial of type `PT`

.

`MultivariatePolynomials.mapexponents`

— Function`mapexponents(f, m1::AbstractMonomialLike, m2::AbstractMonomialLike)`

If $m_1 = \prod x^{\alpha_i}$ and $m_2 = \prod x^{\beta_i}$ then it returns the monomial $m = \prod x^{f(\alpha_i, \beta_i)}$.

**Examples**

The multiplication `m1 * m2`

is equivalent to `mapexponents(+, m1, m2)`

, the unsafe division `_div(m1, m2)`

is equivalent to `mapexponents(-, m1, m2)`

, `gcd(m1, m2)`

is equivalent to `mapexponents(min, m1, m2)`

, `lcm(m1, m2)`

is equivalent to `mapexponents(max, m1, m2)`

.

## Terms

`MultivariatePolynomials.AbstractTermLike`

— Type`AbstractTermLike{T}`

Abstract type for a value that can act like a term. For instance, an `AbstractMonomial`

is an `AbstractTermLike{Int}`

since it can act as a term with coefficient `1`

.

`MultivariatePolynomials.AbstractTerm`

— Type`AbstractTerm{T} <: AbstractTermLike{T}`

Abstract type for a term of coefficient type `T`

, i.e. the product between a value of type `T`

and a monomial.

`MultivariatePolynomials.term`

— Function`term(coef, mono::AbstractMonomialLike)`

Returns a term with coefficient `coef`

and monomial `mono`

. There are two key difference between this and `coef * mono`

:

`term(coef, mono)`

does not copy`coef`

and`mono`

so modifying this term with MutableArithmetics may modifying the input of this function. To avoid this, call`term(MA.copy_if_mutable(coef), MA.copy_if_mutable(mono))`

where`MA = MutableArithmetics`

.Suppose that

`coef = (x + 1)`

and`mono = x^2`

,`coef * mono`

gives the polynomial with integer coefficients`x^3 + x^2`

which`term(x + 1, x^2)`

gives a term with polynomial coefficient`x + 1`

.term(p::AbstractPolynomialLike)

Converts the polynomial `p`

to a term. When applied on a polynomial, it throws an `InexactError`

if it has more than one term. When applied to a term, it is the identity and does not copy it. When applied to a monomial, it create a term of type `AbstractTerm{Int}`

.

`MultivariatePolynomials.termtype`

— Function`termtype(p::AbstractPolynomialLike)`

Returns the type of the terms of `p`

.

`termtype(::Type{PT}) where PT<:AbstractPolynomialLike`

Returns the type of the terms of a polynomial of type `PT`

.

`termtype(p::AbstractPolynomialLike, ::Type{T}) where T`

Returns the type of the terms of `p`

but with coefficient type `T`

.

`termtype(::Type{PT}, ::Type{T}) where {PT<:AbstractPolynomialLike, T}`

Returns the type of the terms of a polynomial of type `PT`

but with coefficient type `T`

.

`MultivariatePolynomials.coefficient`

— Function`coefficient(t::AbstractTermLike)`

Returns the coefficient of the term `t`

.

`coefficient(p::AbstractPolynomialLike, m::AbstractMonomialLike)`

Returns the coefficient of the monomial `m`

in `p`

.

**Examples**

Calling `coefficient`

on $4x^2y$ should return $4$. Calling `coefficient(2x + 4y^2 + 3, y^2)`

should return $4$. Calling `coefficient(2x + 4y^2 + 3, x^2)`

should return $0$.

`MultivariatePolynomials.coefficienttype`

— Function`coefficient(p::AbstractPolynomialLike)`

Returns the coefficient type of `p`

.

`coefficient(::Type{PT}) where PT`

Returns the coefficient type of a polynomial of type `PT`

.

**Examples**

Calling `coefficienttype`

on $(4//5)x^2y$ should return `Rational{Int}`

, calling `coefficienttype`

on $1.0x^2y + 2.0x$ should return `Float64`

and calling `coefficienttype`

on $xy$ should return `Int`

.

`MultivariatePolynomials.monomial`

— Function`monomial(t::AbstractTermLike)`

Returns the monomial of the term `t`

.

**Examples**

Calling `monomial`

on $4x^2y$ should return $x^2y$.

`MultivariatePolynomials.constantterm`

— Function`constantterm(α, p::AbstractPolynomialLike)`

Creates a constant term with coefficient α and the same variables as p.

`constantterm(α, ::Type{PT} where {PT<:AbstractPolynomialLike}`

Creates a constant term of the term type of a polynomial of type `PT`

.

`MultivariatePolynomials.zeroterm`

— Function`zeroterm(p::AbstractPolynomialLike{T}) where T`

Equivalent to `constantterm(zero(T), p)`

.

`zeroterm(α, ::Type{PT} where {T, PT<:AbstractPolynomialLike{T}}`

Equivalent to `constantterm(zero(T), PT)`

.

## Polynomials

`MultivariatePolynomials.AbstractPolynomialLike`

— Type`AbstractPolynomialLike{T}`

Abstract type for a value that can act like a polynomial. For instance, an `AbstractTerm{T}`

is an `AbstractPolynomialLike{T}`

since it can act as a polynomial of only one term.

`MultivariatePolynomials.AbstractPolynomial`

— Type`AbstractPolynomial{T} <: AbstractPolynomialLike{T}`

Abstract type for a polynomial of coefficient type `T`

, i.e. a sum of `AbstractTerm{T}`

s.

`MultivariatePolynomials.polynomial`

— Function`polynomial(p::AbstractPolynomialLike)`

Converts `p`

to a value with polynomial type.

`polynomial(p::AbstractPolynomialLike, ::Type{T}) where T`

Converts `p`

to a value with polynomial type with coefficient type `T`

.

`polynomial(a::AbstractVector, mv::AbstractVector{<:AbstractMonomialLike})`

Creates a polynomial equal to `dot(a, mv)`

.

`polynomial(terms::AbstractVector{<:AbstractTerm}, s::ListState=MessyState())`

Creates a polynomial equal to `sum(terms)`

where `terms`

are guaranteed to be in state `s`

.

`polynomial(f::Function, mv::AbstractVector{<:AbstractMonomialLike})`

Creates a polynomial equal to `sum(f(i) * mv[i] for i in 1:length(mv))`

.

**Examples**

Calling `polynomial([2, 4, 1], [x, x^2*y, x*y])`

should return $4x^2y + xy + 2x$.

`MultivariatePolynomials.polynomialtype`

— Function`polynomialtype(p::AbstractPolynomialLike)`

Returns the type that `p`

would have if it was converted into a polynomial.

`polynomialtype(::Type{PT}) where PT<:AbstractPolynomialLike`

Returns the same as `polynomialtype(::PT)`

.

`polynomialtype(p::AbstractPolynomialLike, ::Type{T}) where T`

Returns the type that `p`

would have if it was converted into a polynomial of coefficient type `T`

.

`polynomialtype(::Type{PT}, ::Type{T}) where {PT<:AbstractPolynomialLike, T}`

Returns the same as `polynomialtype(::PT, ::Type{T})`

.

`MultivariatePolynomials.terms`

— Function`terms(p::AbstractPolynomialLike)`

Returns an iterator over the nonzero terms of the polynomial `p`

sorted in the decreasing monomial order.

**Examples**

Calling `terms`

on $4x^2y + xy + 2x$ should return an iterator of $[4x^2y, xy, 2x]$.

`MultivariatePolynomials.nterms`

— Function`nterms(p::AbstractPolynomialLike)`

Returns the number of nonzero terms in `p`

, i.e. `length(terms(p))`

.

**Examples**

Calling `nterms`

on $4x^2y + xy + 2x$ should return 3.

`MultivariatePolynomials.coefficients`

— Function`coefficients(p::AbstractPolynomialLike)`

Returns an iterator over the coefficients of `p`

of the nonzero terms of the polynomial sorted in the decreasing monomial order.

`coefficients(p::AbstractPolynomialLike, X::AbstractVector)`

Returns an iterator over the coefficients of the monomials of `X`

in `p`

where `X`

is a monomial vector not necessarily sorted but with no duplicate entry.

**Examples**

Calling `coefficients`

on $4x^2y + xy + 2x$ should return an iterator of $[4, 1, 2]$. Calling `coefficients(4x^2*y + x*y + 2x + 3, [x, 1, x*y, y])`

should return an iterator of $[2, 3, 1, 0]$.

`MultivariatePolynomials.coefficient`

— Method`coefficient(p::AbstractPolynomialLike, m::AbstractMonomialLike, vars)::AbstractPolynomialLike`

Returns the coefficient of the monomial `m`

of the polynomial `p`

considered as a polynomial in variables `vars`

.

**Example**

Calling `coefficient((a+b)x^2+2x+y*x^2, x^2, [x,y])`

should return `a+b`

. Calling `coefficient((a+b)x^2+2x+y*x^2, x^2, [x])`

should return `a+b+y`

.

`MultivariatePolynomials.monomials`

— Function`monomials(p::AbstractPolynomialLike)`

Returns an iterator over the monomials of `p`

of the nonzero terms of the polynomial sorted in the decreasing order.

`monomials(vars::Tuple, degs::AbstractVector{Int}, filter::Function = m -> true)`

Builds the vector of all the monovec `m`

with variables `vars`

such that the degree `degree(m)`

is in `degs`

and `filter(m)`

is `true`

.

**Examples**

Calling `monomials`

on $4x^2y + xy + 2x$ should return an iterator of $[x^2y, xy, x]$.

Calling `monomials((x, y), [1, 3], m -> degree(m, y) != 1)`

should return `[x^3, x*y^2, y^3, x]`

where `x^2*y`

and `y`

have been excluded by the filter.

`MultivariatePolynomials.ordering`

— Function`ordering(p::AbstractPolynomialLike)`

Returns the ordering of polynomial `p`

.

`MultivariatePolynomials.mindegree`

— Function`mindegree(p::Union{AbstractPolynomialLike, AbstractVector{<:AbstractTermLike}})`

Returns the minimal total degree of the monomials of `p`

, i.e. `minimum(degree, terms(p))`

.

`mindegree(p::Union{AbstractPolynomialLike, AbstractVector{<:AbstractTermLike}}, v::AbstractVariable)`

Returns the minimal degree of the monomials of `p`

in the variable `v`

, i.e. `minimum(degree.(terms(p), v))`

.

**Examples**

Calling `mindegree`

on on $4x^2y + xy + 2x$ should return 1, `mindegree(4x^2y + xy + 2x, x)`

should return 1 and `mindegree(4x^2y + xy + 2x, y)`

should return 0.

`MultivariatePolynomials.maxdegree`

— Function`maxdegree(p::Union{AbstractPolynomialLike, AbstractVector{<:AbstractTermLike}})`

Returns the maximal total degree of the monomials of `p`

, i.e. `maximum(degree, terms(p))`

.

`maxdegree(p::Union{AbstractPolynomialLike, AbstractVector{<:AbstractTermLike}}, v::AbstractVariable)`

Returns the maximal degree of the monomials of `p`

in the variable `v`

, i.e. `maximum(degree.(terms(p), v))`

.

**Examples**

Calling `maxdegree`

on on $4x^2y + xy + 2x$ should return 3, `maxdegree(4x^2y + xy + 2x, x)`

should return 2 and `maxdegree(4x^2y + xy + 2x, y)`

should return 1.

`MultivariatePolynomials.extdegree`

— Function`extdegree(p::Union{AbstractPolynomialLike, AbstractVector{<:AbstractTermLike}})`

Returns the extremal total degrees of the monomials of `p`

, i.e. `(mindegree(p), maxdegree(p))`

.

`extdegree(p::Union{AbstractPolynomialLike, AbstractVector{<:AbstractTermLike}}, v::AbstractVariable)`

Returns the extremal degrees of the monomials of `p`

in the variable `v`

, i.e. `(mindegree(p, v), maxdegree(p, v))`

.

**Examples**

Calling `extdegree`

on on $4x^2y + xy + 2x$ should return `(1, 3)`

, `extdegree(4x^2y + xy + 2x, x)`

should return `(1, 2)`

and `maxdegree(4x^2y + xy + 2x, y)`

should return `(0, 1)`

.

`MultivariatePolynomials.leadingterm`

— Function`leadingterm(p::AbstractPolynomialLike)`

Returns the coefficient of the leading term, i.e. `first(terms(p))`

.

**Examples**

Calling `leadingterm`

on $4x^2y + xy + 2x$ should return $4x^2y$.

`MultivariatePolynomials.leadingcoefficient`

— Function`leadingcoefficient(p::AbstractPolynomialLike)`

Returns the coefficient of the leading term of `p`

, i.e. `coefficient(leadingterm(p))`

.

**Examples**

Calling `leadingcoefficient`

on $4x^2y + xy + 2x$ should return $4$ and calling it on $0$ should return $0$.

`MultivariatePolynomials.leadingmonomial`

— Function`leadingmonomial(p::AbstractPolynomialLike)`

Returns the monomial of the leading term of `p`

, i.e. `monomial(leadingterm(p))`

or `first(monomials(p))`

.

**Examples**

Calling `leadingmonomial`

on $4x^2y + xy + 2x$ should return $x^2y$.

`MultivariatePolynomials.removeleadingterm`

— Function`removeleadingterm(p::AbstractPolynomialLike)`

Returns a polynomial with the leading term removed in the polynomial `p`

.

**Examples**

Calling `removeleadingterm`

on $4x^2y + xy + 2x$ should return $xy + 2x$.

`MultivariatePolynomials.removemonomials`

— FunctionReturns a polynomial with the terms having their monomial in the monomial vector `mv`

removed in the polynomial `p`

.

**Examples**

Calling `removemonomials(4x^2*y + x*y + 2x, [x*y])`

should return $4x^2*y + 2x$.

`MultivariatePolynomials.monic`

— Function`monic(p::AbstractPolynomialLike)`

Returns `p / leadingcoefficient(p)`

where the leading coefficient of the returned polynomials is made sure to be exactly one to avoid rounding error.

`MultivariatePolynomials.mapcoefficients`

— Function`mapcoefficients(f::Function, p::AbstractPolynomialLike, nonzero = false)`

Returns a polynomial with the same monomials as `p`

but each coefficient `α`

is replaced by `f(α)`

. The function may return zero in which case the term is dropped. If the function is known to never returns zero for a nonzero input, `nonzero`

can be set to `true`

to get a small speedup.

See also `mapcoefficients!`

and `mapcoefficients_to!`

.

**Examples**

Calling `mapcoefficients(α -> mod(3α, 6), 2x*y + 3x + 1)`

should return `3x + 3`

.

`MultivariatePolynomials.mapcoefficients!`

— Function`mapcoefficients!(f::Function, p::AbstractPolynomialLike, nonzero = false)`

Mutate `p`

by replacing each coefficient `α`

by `f(α)`

. The function may return zero in which case the term is dropped. If the function is known to never returns zero for a nonzero input, `nonzero`

can be set to `true`

to get a small speedup. The function returns `p`

, which is identically equal to the second argument.

See also `mapcoefficients`

and `mapcoefficients_to!`

.

**Examples**

Let `p = 2x*y + 3x + 1`

, after `mapcoefficients!(α -> mod(3α, 6), p)`

, `p`

is equal to `3x + 3`

.

`MultivariatePolynomials.mapcoefficients_to!`

— Function`mapcoefficients_to!(output::AbstractPolynomialLike, f::Function, p::AbstractPolynomialLike, nonzero = false)`

Mutate `output`

by replacing each coefficient `α`

of `p`

by `f(α)`

. The function may return zero in which case the term is dropped. If the function is known to never returns zero for a nonzero input, `nonzero`

can be set to `true`

to get a small speedup. The function returns `output`

, which is identically equal to the first argument.

See also `mapcoefficients!`

and `mapcoefficients`

.

## Rational Polynomial Function

A rational polynomial function can be constructed with the `/`

operator. Common operations such as `+`

, `-`

, `*`

, `-`

have been implemented between rational functions. The numerator and denominator polynomials can be retrieved by the `numerator`

and `denominator`

functions.

## Monomial Vectors

`MultivariatePolynomials.monovec`

— Function`monovec(X::AbstractVector{MT}) where {MT<:AbstractMonomialLike}`

Returns the vector of monomials `X`

in decreasing order and without any duplicates.

**Examples**

Calling `monovec`

on $[xy, x, xy, x^2y, x]$ should return $[x^2y, xy, x]$.

`monovec(a, X::AbstractVector{MT}) where {MT<:AbstractMonomialLike}`

Returns `b, Y`

where `Y`

is the vector of monomials of `X`

in decreasing order and without any duplicates and `b`

is the vector of corresponding coefficients in `a`

, where coefficients of duplicate entries are summed together.

**Examples**

Calling `monovec`

on $[2, 1, 4, 3, -1], [xy, x, xy, x^2y, x]$ should return $[3, 6, 0], [x^2y, xy, x]$.

`MultivariatePolynomials.monovectype`

— Function`monovectype(X::AbstractVector{MT}) where {MT<:AbstractMonomialLike}`

Returns the return type of `monovec`

.

`MultivariatePolynomials.emptymonovec`

— Function`emptymonovec(p::AbstractPolynomialLike)`

Returns an empty collection of the type of `monomials(p)`

.

`MultivariatePolynomials.sortmonovec`

— Function`sortmonovec(X::AbstractVector{MT}) where {MT<:AbstractMonomialLike}`

Returns `σ`

, the orders in which one must take the monomials in `X`

to make them sorted and without any duplicate and the sorted vector of monomials, i.e. it returns `(σ, X[σ])`

.

**Examples**

Calling `sortmonovec`

on $[xy, x, xy, x^2y, x]$ should return $([4, 1, 2], [x^2y, xy, x])$.

`MultivariatePolynomials.mergemonovec`

— Function`mergemonovec{MT<:AbstractMonomialLike, MVT<:AbstractVector{MT}}(X::AbstractVector{MVT}}`

Returns the vector of monomials in the entries of `X`

in decreasing order and without any duplicates, i.e. `monovec(vcat(X...))`

**Examples**

Calling `mergemonovec`

on $[[xy, x, xy], [x^2y, x]]$ should return $[x^2y, xy, x]$.