Action polynomial rings
An action polynomial ring over the commutative ring $R$ is a polynomial ring
\[S = R[\, (u_i)_J \mid i \in \lbrace 1, \ldots, m \rbrace, J \in \mathbb{Z}_{\geq 0}^n ]\]
in the countably infinitely many jet variables $(u_i)_J$, equipped with $n$ commuting $R$-linear action maps $\sigma_1, \ldots, \sigma_n$, where $m$ and $n$ are positive integers. The symbols $u_1, \ldots, u_m$ are called elementary symbols, the multiindices $J \in \mathbb{Z}_{\geq 0}^n$ are called jets.
The $j$-th action map has the property that, when applied to a jet variable, it increments the $j$-th entry of its jet by one. Depending on the setting it also has further properties, e.g. it is multiplicative for difference polynomial rings and it is a derivation for differential polynomial rings.
In Oscar we provide the action polynomial interface via the abstract types ActionPolyRing{T} <: Ring and ActionPolyRingElem{T} <: RingElem. The type parameter T is the element type of the coefficient ring. All concrete subtypes use the functionality of universal polynomials from the AbstractAlgebra package for polynomial arithmetic, as well as maintaining variables and adding new ones on demand. Any action polynomial ring maintains a sorted list of currently tracked jet variables, that can be accessed and extended by a number of methods, see, e.g., Element Constructors. The jet variables are sorted with respect to a user-defined ranking.
The set of valid jet variables of an action polynomial ring depend only on the integers $m$ and $n$ and are thus known at the time of construction. For reasons of efficiency, we keep the list of tracked jet variables as short as possible and track jet variables only, if necessary. The list of currently tracked jet variables is obtained, using gens.
Currently, there are two concrete subtypes available, namely DifferencePolyRing{T} and DifferentialPolyRing{T} with element types DifferencePolyRingElem{T} and DifferentialPolyRingElem{T}. See difference polynomial rings and differential polynomial rings for their unique functionality.
Specifying jet variables
Recall that a jet variable is of the form $(u_i)_J$ with $i \in \lbrace 1, \ldots, m \rbrace$ and $J \in \mathbb{Z}_{\geq 0}^n$. There are four ways in which jet variables can be specified as an input for methods, which can be found below. The first two do not require the jet variable in question to be tracked, the last two do.
- By a tuple consisting of the index
iand the jetJ. - By passing the tuple as separate arguments, starting with the index.
- By passing the index of the jet variable in the list of the currently tracked jet variables.
- By immediately passing the jet variable as an element of an action polynomial ring.
For many methods, e.g. degree or derivative we provide all the above versions, but only record one in this documentation for readability. Usually, we choose the second version from the above list.
Element Constructors
(A::ActionPolyRing)() returns the zero polynomial of the action polynomial ring A. (A::ActionPolyRing)(a::T) where {T<:RingElement} returns a as an element of A, if possible. This can be used for creating constant polynomials.
The next three methods take input arguments specifying a jet variable or a vector of jet variables. After calling one of them, the provided action polynomial ring A will track all jet variables specified.
gen — Methodgen(A::ActionPolyRing, i::Int, jet::Vector{Int})Return the jet variable of the action polynomial ring A specified by i and jet. If this jet variable was untracked, it is tracked afterwards. The jet variable may also be specified by a tuple, see Specifying jet variables. Additionally, the jet variable may also be specified by an integer but the corresponding method gen(A::ActionPolyRing, i::Int) slightly differs in its functionality, as it cannot create new jet variables.
Examples
julia> dpr = differential_polynomial_ring(ZZ, [:a, :b, :c], 4)[1]; gen(dpr, 1, [3,1,0,0])
a[3,1,0,0]
julia> gen(dpr, (1, [3,2,0,0]))
a[3,2,0,0]
julia> gens(dpr)
5-element Vector{DifferentialPolyRingElem{ZZRingElem}}:
a[3,2,0,0]
a[3,1,0,0]
a[0,0,0,0]
b[0,0,0,0]
c[0,0,0,0]This function is part of the experimental code in Oscar. Please read here for more details.
getindex — Methodgetindex(A::ActionPolyRing, i::Int, jet::Vector{Int})Alias for gen(A, i, jet).
This function is part of the experimental code in Oscar. Please read here for more details.
gens — Methodgens(A::ActionPolyRing, jet_idxs::Vector{Tuple{Int, Vector{Int}}})Return the jet variables of the action polynomial ring A specified by the entries of jet_idxs as a vector and track all new jet variables.
Examples
julia> dpr = differential_polynomial_ring(ZZ, [:a, :b, :c], 4)[1]; gens(dpr, [(1, [3,1,0,0]), (1, [3,2,0,0])])
2-element Vector{DifferentialPolyRingElem{ZZRingElem}}:
a[3,1,0,0]
a[3,2,0,0]
julia> gens(dpr)
5-element Vector{DifferentialPolyRingElem{ZZRingElem}}:
a[3,2,0,0]
a[3,1,0,0]
a[0,0,0,0]
b[0,0,0,0]
c[0,0,0,0]This function is part of the experimental code in Oscar. Please read here for more details.
Polynomials can be created by applying the usual arithmetic operations, such as +, -, *, and ^, to jet variables.
Generators and variables
gen — Methodgen(A::ActionPolyRing, i::Int)Among the currently tracked jet variables of A, return the i-th largest one.
Examples
julia> dpr = difference_polynomial_ring(ZZ, [:a, :b, :c], 4)[1]; gen(dpr, 2)
b[0,0,0,0]
julia> set_ranking!(dpr; partition = [[0,1,1],[1,0,0]]); gen(dpr, 2)
c[0,0,0,0]This function is part of the experimental code in Oscar. Please read here for more details.
gens — Methodgens(A::ActionPolyRing)Return the currently tracked jet variables of the action polynomial ring A as a vector. The jet variables are sorted with respect to the ranking of A, leading with the largest jet variable.
Examples
julia> dpr = difference_polynomial_ring(ZZ, [:a, :b, :c], 4)[1]; gens(dpr)
3-element Vector{DifferencePolyRingElem{ZZRingElem}}:
a[0,0,0,0]
b[0,0,0,0]
c[0,0,0,0]
julia> set_ranking!(dpr; partition = [[0,1,1],[1,0,0]]); gens(dpr)
3-element Vector{DifferencePolyRingElem{ZZRingElem}}:
b[0,0,0,0]
c[0,0,0,0]
a[0,0,0,0]
julia> gens(dpr, [(1, [1,1,1,1]), (2, [1,1,1,1])]);
julia> gens(dpr)
5-element Vector{DifferencePolyRingElem{ZZRingElem}}:
b[1,1,1,1]
b[0,0,0,0]
c[0,0,0,0]
a[1,1,1,1]
a[0,0,0,0]This function is part of the experimental code in Oscar. Please read here for more details.
is_gen — Methodis_gen(p::ActionPolyRingElem)Return true if p is a jet variable in an action polynomial ring.
This function is part of the experimental code in Oscar. Please read here for more details.
var_index — Methodvar_index(p::ActionPolyRingElem)Return the integer i such that p is the i-th largest currently tracked jet variable. If p is not a jet variable an exception is raised.
This function is part of the experimental code in Oscar. Please read here for more details.
vars — Methodvars(p::ActionPolyRingElem)Return the jet variables actually occuring in p as a vector. The jet variables are sorted with respect to the ranking of the action polynomial ring containing p, leading with the largest jet variable.
This function is part of the experimental code in Oscar. Please read here for more details.
leader — Methodleader(p::ActionPolyRingElem)Return the leader of the polynomial p, that is the largest jet variable with respect to the ranking of parent(p). If p is constant, an error is raised.
This function is part of the experimental code in Oscar. Please read here for more details.
We also provide the usual ngens and nvars methods that respectively return the number of currently tracked jet variables.
Basic methods for action polynomial rings
zero — Methodzero(A::ActionPolyRing)Return the zero element of the action polynomial ring A.
This function is part of the experimental code in Oscar. Please read here for more details.
one — Methodone(A::ActionPolyRing)Return the multiplicitive identity of the action polynomial ring A.
This function is part of the experimental code in Oscar. Please read here for more details.
n_elementary_symbols — Methodn_elementary_symbols(A::ActionPolyRing) -> IntReturn the number of elementary symbols of the action polynomial ring A.
This function is part of the experimental code in Oscar. Please read here for more details.
elementary_symbols — Methodelementary_symbols(A::ActionPolyRing) -> Vector{Symbol}Return the elementary symbols of the action polynomial ring A as a vector.
This function is part of the experimental code in Oscar. Please read here for more details.
n_action_maps — Methodn_action_maps(A::ActionPolyRing) -> IntReturn the number of elementary symbols of the action polynomial ring A.
This function is part of the experimental code in Oscar. Please read here for more details.
Iterators
The following iterators are available for elements of action polynomial rings. The entries across the different iterators are guaranteed to match. Moreover, the order of the entries of the iterators depends only on the ranking of the action polynomial ring, leading with the most significant entry.
coefficients — Methodcoefficients(p::ActionPolyRingElem)Return an iterator for the coefficients of p with respect to the ranking of the parent of p.
Examples
julia> dpr, (a,b,c) = difference_polynomial_ring(ZZ, [:a, :b, :c], 4; partition = [[0,1,1],[1,0,0]]); f = -2*a*b + a*c + 3*b^2;
julia> cf = coefficients(f)
Coefficients iterator of 3*b[0,0,0,0]^2 - 2*b[0,0,0,0]*a[0,0,0,0] + c[0,0,0,0]*a[0,0,0,0]
julia> collect(cf)
3-element Vector{ZZRingElem}:
3
-2
1This function is part of the experimental code in Oscar. Please read here for more details.
exponents — Methodexponents(p::ActionPolyRingElem)Return an iterator for the exponents of p with respect to the ranking of the parent of p.
Examples
julia> dpr, (a,b,c) = difference_polynomial_ring(ZZ, [:a, :b, :c], 4; partition = [[0,1,1],[1,0,0]]); f = -2*a*b + a*c + 3*b^2;
julia> ef = exponents(f)
Exponents iterator of 3*b[0,0,0,0]^2 - 2*b[0,0,0,0]*a[0,0,0,0] + c[0,0,0,0]*a[0,0,0,0]
julia> collect(ef)
3-element Vector{Vector{Int64}}:
[2, 0, 0]
[1, 0, 1]
[0, 1, 1]This function is part of the experimental code in Oscar. Please read here for more details.
monomials — Methodmonomials(p::ActionPolyRingElem)Return an iterator for the monomials of p with respect to the ranking of the parent of p.
Examples
julia> dpr, (a,b,c) = difference_polynomial_ring(ZZ, [:a, :b, :c], 4; partition = [[0,1,1],[1,0,0]]); f = -2*a*b + a*c + 3*b^2;
julia> mf = monomials(f)
Monomials iterator of 3*b[0,0,0,0]^2 - 2*b[0,0,0,0]*a[0,0,0,0] + c[0,0,0,0]*a[0,0,0,0]
julia> collect(mf)
3-element Vector{DifferencePolyRingElem{ZZRingElem}}:
b[0,0,0,0]^2
b[0,0,0,0]*a[0,0,0,0]
c[0,0,0,0]*a[0,0,0,0]This function is part of the experimental code in Oscar. Please read here for more details.
terms — Methodterms(p::ActionPolyRingElem)Return an iterator for the terms of p with respect to the ranking of the parent of p.
Examples
julia> dpr, (a,b,c) = difference_polynomial_ring(ZZ, [:a, :b, :c], 4; partition = [[0,1,1],[1,0,0]]); f = -2*a*b + a*c + 3*b^2;
julia> tf = terms(f)
Terms iterator of 3*b[0,0,0,0]^2 - 2*b[0,0,0,0]*a[0,0,0,0] + c[0,0,0,0]*a[0,0,0,0]
julia> collect(tf)
3-element Vector{DifferencePolyRingElem{ZZRingElem}}:
3*b[0,0,0,0]^2
-2*b[0,0,0,0]*a[0,0,0,0]
c[0,0,0,0]*a[0,0,0,0]This function is part of the experimental code in Oscar. Please read here for more details.
Iterator based methods
The following methods are based on the iterators for elements of action polynomial rings.
Basic access to entries of the iterators:
coeff — Methodcoeff(p::ActionPolyRingElem, i::Int)Return coefficient of the i-th term of p.
This function is part of the experimental code in Oscar. Please read here for more details.
exponent_vector — Methodexponent_vector(p::ActionPolyRingElem, i::Int)Return the exponent vector of the i-th term of p.
This function is part of the experimental code in Oscar. Please read here for more details.
monomial — Methodmonomial(p::ActionPolyRingElem, i::Int)Return the i-th monomial of p.
This function is part of the experimental code in Oscar. Please read here for more details.
term — Methodterm(p::ActionPolyRingElem, i::Int)Return the i-th term of p.
This function is part of the experimental code in Oscar. Please read here for more details.
Access to the first and last entries:
leading_coefficient — Methodleading_coefficient(p::ActionPolyRingElem{T}) -> TReturn the leading coefficient of the polynomial p, i.e. the coefficient of the first (with respect to the ranking of the action polynomial ring containing it) nonzero term.
This function is part of the experimental code in Oscar. Please read here for more details.
leading_monomial — Methodleading_monomial(p::ActionPolyRingElem)Return the leading monomial of the polynomial p with respect to the ranking of the action polynomial ring containing it.
This function is part of the experimental code in Oscar. Please read here for more details.
leading_term — Methodleading_term(p::ActionPolyRingElem)Return the leading term of the polynomial p with respect to the ranking of the action polynomial ring containing it.
This function is part of the experimental code in Oscar. Please read here for more details.
trailing_coefficient — Methodtrailing_coefficient(p::MPolyRingElem)Return the trailing coefficient of the polynomial $p$, i.e. the coefficient of the last nonzero term.
trailing_coefficient(p::ActionPolyRingElem{T}) -> TReturn the trailing coefficient of the polynomial p, i.e. the coefficient of the last (with respect to the ranking of the action polynomial ring containing it) nonzero term, or zero if the polynomial is zero.
This function is part of the experimental code in Oscar. Please read here for more details.
trailing_monomial — Methodtrailing_monomial(p::ActionPolyRingElem)Return the trailing monomial of the polynomial p with respect to the ranking of the action polynomial ring containing it.
This function is part of the experimental code in Oscar. Please read here for more details.
trailing_term — Methodtrailing_term(p::ActionPolyRingElem)Return the leading term of the polynomial p with respect to the ranking of the action polynomial ring containing it.
This function is part of the experimental code in Oscar. Please read here for more details.
Other useful methods:
is_monomial — Methodis_monomial(p::ActionPolyRingElem)Return true if p is a monomial and false otherwise.
This function is part of the experimental code in Oscar. Please read here for more details.
is_term — Methodis_term(p::ActionPolyRingElem)Return true if p is a term, i.e. a non-zero multiple of a monomial, and false otherwise.
This function is part of the experimental code in Oscar. Please read here for more details.
initial — Methodinitial(p::ActionPolyRingElem)Return the initial of the polynomial p, i.e. the leading coefficient of p regarded as a univariate polynomial in its leader.
This function is part of the experimental code in Oscar. Please read here for more details.
length — Methodlength(p::ActionPolyRingElem) -> IntReturn the length of p, i.e. the number of terms of p.
This function is part of the experimental code in Oscar. Please read here for more details.
tail — Methodtail(p::ActionPolyRingElem)Return the tail of p, i.e. p, i.e. return p without its leading term with respect to the ranking of the action polynomial ring containing it.
This function is part of the experimental code in Oscar. Please read here for more details.
Miscellaneous
In this subsection, we enumerate methods that might be useful but primarily exists, because they already do for other polynomial types.
Constant polynomials
is_constant — Methodis_constant(p::ActionPolyRingElem)Return true if p is a degree zero polynomial or the zero polynomial, i.e. a constant polynomial.
This function is part of the experimental code in Oscar. Please read here for more details.
constant_coefficient — Methodconstant_coefficient(p::ActionPolyRingElem{T}) -> TReturn the constant coefficient of p. Does not throw an error for the zero polynomial like trailing_coefficient.
This function is part of the experimental code in Oscar. Please read here for more details.
Degree
degree — Methoddegree(p::ActionPolyRingElem, i::Int, jet::Vector{Int}) -> IntReturn the degree of the polynomial p in the jet variable specified by i and jet. If this jet variable is valid but still untracked, return $0$. This method allows all versions described in Specifying jet variables.
This function is part of the experimental code in Oscar. Please read here for more details.
degrees — Methoddegrees(p::ActionPolyRingElem)Return an array of the degrees of the polynomial p in terms of each jet variable. The jet variables are sorted with respect to the ranking of the action polynomial ring containing p, leading with the largest variable.
This function is part of the experimental code in Oscar. Please read here for more details.
total_degree — Methodtotal_degree(p::ActionPolyRingElem) -> IntReturn the total degree of p.
This function is part of the experimental code in Oscar. Please read here for more details.
Derivative
derivative — Methodderivative(p::ActionPolyRing, i::Int, jet::Vector{Int})Return the derivative of p with respect to the jet variable specified by i and jet. This method allows all versions described in Specifying jet variables.
This function is part of the experimental code in Oscar. Please read here for more details.
Univariate polynomials
is_univariate — Methodis_univariate(p::ActionPolyRing)Return false, since an action polynomial ring cannot be univariate.
This function is part of the experimental code in Oscar. Please read here for more details.
is_univariate — Methodis_univariate(p::ActionPolyRingElem)Return true if p is a polynomial in a single jet variable and false otherwise.
This function is part of the experimental code in Oscar. Please read here for more details.
to_univariate — Methodto_univariate(R::PolyRing{T}, p::ActionPolyRingElem{T}) where {T <: RingElement}Assuming the polynomial p is actually a univariate polynomial, convert the polynomial to a univariate polynomial in the given univariate polynomial ring R. An exception is raised if the polynomial p involves more than one jet variable.
This function is part of the experimental code in Oscar. Please read here for more details.
to_univariate — Methodto_univariate(p::ActionPolyRingElem)Assuming the polynomial p is actually a univariate polynomial in the jet variable x, convert the polynomial to a univariate polynomial in a univariate polynomial ring over the same base ring in the variable x. If p is constant, it is considered to be a polynomial in the largest tracked jet variable of its parent. An exception is raised if the polynomial p involves more than one jet variable.
This function is part of the experimental code in Oscar. Please read here for more details.