## `Dom::DistributedPolynomial` -- the domains of distributed polynomials

#### Introduction

`Dom::DistributedPolynomial``(Vars, R, ..)` creates the domain of polynomials in the variables of the list `Vars` over the commutative ring `R` in distributed representation.

#### Domain

`Dom::DistributedPolynomial( <Vars <, R <, Order>>>)`

#### Parameters

`Vars` | - | a list of indeterminates. Default is `[]` (the empty list, indicating ``arbitrary indeterminates'').
`R` | - | a commutative ring, i.e., a domain of category `Cat::CommutativeRing`. Default is `Dom::ExpressionField(normal)`.
`Order` | - | a monomial ordering, i.e., one of the predefined orderings `LexOrder`, `DegreeOrder` or `DegInvLexOrder` or any object of type `Dom::MonomOrdering`. Default is `LexOrder`.

#### Details

- `Dom::DistributedPolynomial``(Vars, R, Order)` creates a domain of polynomials in the variables of the list `Vars` over a domain of category `Cat::CommutativeRing` in sparse distributed representation with respect to the monomial ordering `Order`.
- If `Dom::DistributedPolynomial` is called without any argument, a polynomial domain in arbitrarily many indeterminates over the domain `Dom::ExpressionField``(normal)` with respect to the lexicographic monomial ordering is created.
- If `Dom::DistributedPolynomial` is called only with the variable list `Vars` as argument, the polynomial domain in the variable list `Vars` over the domain `Dom::ExpressionField``(normal)` with respect to the lexicographic monomial ordering is created.

- Only commutative coefficient rings of type `DOM_DOMAIN` are allowed which inherit from `Dom::BaseDomain`. If `R` is of type `DOM_DOMAIN` but does not inherit from `Dom::BaseDomain`, the domain `Dom::ExpressionField``(normal)` will be used instead.

- `Dom::DistributedPolynomial` accepts expressions as indeterminates, similar to the kernel domain `DOM_POLY`. Hence, for example, `[x,cos(x)]` is a valid variable list.
- If the variable list `Vars` is the empty list (`[]`), a polynomial domain in arbitrarily many indeterminates is created. In this case, when creating new elements from polynomials or polynomial expressions, the system function `indets` is first called to get the variables and then the polynomial is created with respect to these variables. Hence, in this case only identifiers can be valid indeterminates, because `indets` returns only identifiers.
- It is not allowed to create polynomial domains in arbitrarily many indeterminates over another polynomial domain of category `Cat::Polynomial`, but it is possible to create multivariate polynomial domains with a given list of variables over any polynomial domain.
- `Dom::DistributedPolynomial` represents polynomials over arbitrary commutative rings. It is intended as a basic domain for distributed polynomials from which it is easy to create new distributed polynomial domains.

  All usual algebraic and arithmetical polynomial operations are implemented, including Gröbner basis computation.

- It is highly recommend to use only coefficient rings with unique zero representation. Otherwise it can happen that, e.g., a polynomial division will not terminate or a wrong degree will be returned.

- Please note that for reasons of efficiency not all methods check their arguments, not even at the interactive level. In particular this is true for many access methods, converting methods and technical methods.

#### Creating Elements

``Dom::DistributedPolynomial`(Vars, R, Order)(p)`
``Dom::DistributedPolynomial`(Vars, R, Order)(lm)`
``Dom::DistributedPolynomial`(Vars, R, Order)(lm,v)`

#### Parameters

`p` | - | a polynomial or a polynomial expression.
`lm` | - | list of monomials, which are represented as lists containing the coefficients together with the exponents or exponent vectors.
`v` | - | list of indeterminates. This parameter is only valid for `Vars` = `[]`.

#### Categories

if `Vars` has a single variable, then
`Cat::UnivariatePolynomial(R)`
else
`Cat::Polynomial(R)`

#### Related Domains

`Dom::Polynomial`, `Dom::MultivariatePolynomial`, `Dom::UnivariatePolynomial`

#### Entries

characteristic

  The characteristic of this domain.

coeffRing

  The coefficient ring of this domain as defined by the parameter `R`.

key

  The name of the created domain.

one

  The neutral element w.r.t. `"_mult"`.

ordering

  The monomial order as defined by the parameter `Order`.

variables

  The list of variables as defined by the parameter `Vars`.

zero

  The neutral element w.r.t. `"_plus"`.

#### Method _divide: exact polynomial division

- `_divide(dom a, dom b)`
- `_divide(dom a, R b)`
- `_divide(dom a, DOM_INT b)`
- - Divides `a` by `b` and returns the divisor, if `a` is divisible by `b` otherwise `FAIL`.
  - It overloads the function `_divide` for polynomials, i.e., one may use it either in the form `a / b`, or in functional form `_divide(a, b)`.

  - This method only exists if `R` is an integral domain, i.e., a domain of category `Cat::IntegralDomain`.

#### Method _invert: inverse of an element

- `_invert(dom a)`
- - Returns the inverse of `a` if it exists, otherwise `FAIL`.

#### Method _mult: multiplies polynomials and coefficient ring elements

- `_mult( <a,b...>)`
- - Multiplies an arbitrary number of polynomials of this domain, elements of the coefficient ring `R` and elements of type `DOM_INT` and returns an element of this domain. If any element of a different domain occurs as an argument, the method from that domain is called and the result of that call is returned. If this call fails, `FAIL` is returned.
  - This method overloads the function `_mult` for polynomials, i.e., one may use it either in the form `a * b * ...` or in functional notation `_mult(a, b...)`.

#### Method _negate: negates a polynomial

- `_negate(dom a)`
- - Negates `a`, i.e., multiplies `a` by -1.
  - This method overloads the function `_negate` for polynomials, i.e., one may use it either in the form `-a` or in functional notation `_negate(a)`.

#### Method _plus: adds polynomials and coefficent ring elements

- `_plus( <a,b...>)`
- - Adds an arbitrary number of polynomials of this domain together with elements of the coefficient ring `R` and elements of type `DOM_INT` and returns an element of this domain. When any other element of a different domain occurs as argument, the method from that domain is called and an element of that domain is returned. If this call fails, `FAIL` is returned.
  - This method overloads the function `_plus` for polynomials, i.e., one may use it either in the form `a + b + ...` or in functional notation `_plus(a, b...)`.

#### Method _power: nth power of a polynomial

- `_power(dom a, NonNegativeInteger n)`
- - Returns the `n`-th power of `a`, i.e., multiplies `a` `n` times by itself.
  - This method overloads the function `_power` for polynomials, i.e., one may use it either in the form `a^n` or in functional notation `_power(a,n)`.

#### Method _subtract: subtracts a polynomial or a coefficient ring element

- `_subtract(a, b)`
- - Subtracts `a` by `b`, whereby both arguments can be either polynomials of this domain or elements of the coefficient ring `R` or elements of type `DOM_INT` and returns an element of this domain. If not possible, an error message will occur.
  - This method overloads the function `_subtract` for polynomials, i.e., one may use it either in the form `a - b` or in functional notation `_subtract(a, b)`.

#### Method content: content of a polynomial

- `content(dom a)`
- - computes the content of `a`, i.e., the gcd of all coefficients.

  - This method only exists if `R` is a domain of category `Cat::GcdDomain`.

#### Method D: differential operator for polynomials

- `D(dom a)`
- `D(list of positive integers l, dom a)`
- - This method overloads the function `polylib::Dpoly` for polynomials and is simply another name for the method `"Dpoly"`.

#### Method Dpoly: differential operator for polynomials

- `Dpoly(dom a)`
- `Dpoly(list of positive integers l, dom a)`
- - `Dpoly(a)` computes the derivative of `a`, if `a` has exactly one indeterminate.
  - `Dpoly(l,a)` computes the partial derivative of `a` with respect to `l`. For details see `polylib::Dpoly`.
  - This method overloads the function `polylib::Dpoly` for polynomials.

#### Method decompose: functional decomposition of a polynomial

- `decompose(dom a <, indeterminate var>)`
- - Returns a sequence of of polynomials of this domain `p1, ..., pn` such that `a` = `p1(...pn(var)...)`.
  - If `a` is a polynomial in only one variable, the second argument is not necessary.
  - This method overloads the function `polylib::decompose` for polynomials.

#### Method diff: differentiates a polynomial

- `diff(dom a, sequence of indeterminates varseq)`
- - Returns the partial derivative of `a` with respect to the sequence of indeterminates `varseq`.
  - If `varseq` is an empty sequence, `a` is returned unchanged.
  - If in `varseq` an expression occurs which is not a variable of `a`, the zero polynomial is returned.
  - This method overloads the function `diff` for polynomials.

#### Method dimension: dimension of affine variety

- `dimension(list of dom ais <, monomial ordering ord>)`
- `dimension(set of dom ais <, monomial ordering ord>)`
- - Computes the dimension of the affine variety generated by the polynomials of `ais` with respect to the monomial ordering `ord`, if explicitly given, otherwise `Order` will be used instead.
  - This method is merely an interface for the function `groebner::dimension`.

  - This method only exists if `R` is a field, i.e., a domain of category `Cat::Field` and `Vars` is not the empty list.

#### Method divide: divides polynomials

- `divide(dom a, dom b <, Quo, Rem or Exact opt>)`
- `divide(dom a, dom b, indeterminate var <, Quo, Rem or Exact opt>)`
- - Divides `a` by `b`, whereby both polynomials are univariate in a common variable or with respect to the given indeterminate `var`. Note that if `Vars` has a single variable the second call leads to an error. If no indeterminate is given the main variable of the first polynomial will be used.
  - If no option is given, the quotient `s` and the remainder `r` are computed such that `a` = `s*b + r` and the degree of `r` in the relevant indeterminate is smaller than that of `b`. The sequence consisting of `s, r` is returned, otherwise `FAIL`.
  - If the option `Quo` is given, only the quotient `s` is returned.
  - If the option `Rem` is given, only the remainder `r` is returned.
  - If the option `Exact` is given, only the quotient `s` is returned, in case the remainder is zero, otherwise `FAIL`.
  - `divide(a,b,Exact)` divides the multivariate polynomial `a` by `b`. If `a` cannot be divided by `b`, the method returns `FAIL`.
  - This method overloads the function `divide` for polynomials.

  - This method only exists if `R` is a field, i.e., a domain of category `Cat::Field` and either this domain is of category `Cat::UnivariatePolynomial(R)` or `R` has characteristic zero (`R::characteristic` = 0). If the first pair of conditions is true then the first call is valid otherwise the second one.

#### Method evalp: evaluates a polynomial

- `evalp(dom a, sequence of equations var = e)`
- - Evaluates the polynomial `a` by substituting the variables `var, ...` by `e, ...`. The values `e, ...` should be elements of the coefficient ring or expressions that could be used as coefficients. The variables are evaluated in the sequence given by the equations using Horner's rule. An element of this domain or an element of the coefficient ring respectively is returned.
  - This method overloads the function `evalp` for polynomials.

#### Method factor: factors a polynomial

- `factor(dom a)`
- - Computes a factorization of the polynomial `a` into irreducible factors such that `a` = `u*a1^e1 ...*an^en` where `u` is the content of `a` and `ai` (1 ≤i ≤n) are the irreducible factors of `a` and returns an element of domain type `Factored`. See `factor` for more details.
  - This method overloads the function `factor` for polynomials.

  - This method only exists if `R` is a domain of category `Cat::Field` or if `R` is the domain `Dom::Integer`.

#### Method func_call: applies expressions to a polynomial

- `func_call(dom a,` R e1, ..., `R` en, <Expr>)
- `func_call(dom a,` dom e1, ..., `dom` en, <Expr>)
- `func_call(dom a,` expression e1, ..., `expression` en, Expr)
- - This method may also be used either in the form `a(e1,..., en, <Expr>)` or in functional notation `func_call(a, e1,..., en, <Expr>)`.
  - `a(e1,..., en)` applies the sequence `e1,..., en` of either elements of this domain or elements of `R` with respect to `Vars` (where `n` is the number of variables) to the polynomial `a`. An element of this domain or an element of the coefficient ring respectively is returned.
  - `a(e1,..., en, Expr)` applies the sequence of expressions or of elements of this domain or of elements of `R` to the polynomial `a`. With this call `a` is first converted into an expression. Afterwards `e1,..., en` is substituted into this expression with respect to `Vars`. The return value may be any object.
  - The number of variables must be equal to the number of applied expressions.

  - This method only exists if `Vars` has at least one indeterminate.

#### Method gcd: greatest common divisor of polynomials

- `gcd(dom a, dom b...)`
- - Computes a greatest common divisor of the polynomials `a, b, ...`
  - This method overloads the function `gcd` for polynomials.

  - This method only exists if `R` is a domain of category `Cat::GcdDomain`.

#### Method gcdex: extended Euclidean algorithm for polynomials

- `gcdex(dom a, dom b)`
- - Applies the extended Euclidean algorithm to compute polynomials `s` and `t` such that `g` = `s*a+t*b`, where `g` is a greatest common divisor of `a` and `b` and `degree(s)` < `degree(b)` and `degree(t)` < `degree(a)`. The sequence of the three polynomials of this domain `g, s, t` is returned.
  - This method overloads the function `gcdex` for polynomials. Especially, it only works for coefficient rings described there.

  - This method only exists if `R` is a domain of category `Cat::GcdDomain`.

#### Method groebner: reduced Gröbner basis

- `groebner(list of dom ais <, monomial ordering ord> <, Reorder>)`
- `groebner(set of dom ais <, monomial ordering ord> <, Reorder>)`
- - Computes a reduced normalized Gröbner-basis for the ideal generated by the polynomials of `ais` with respect to the monomial ordering `ord` (w.r.t. `Order`, if `ord` is not explicitly given) and returns a list of polynomials of this domain.
  - If the option `Reorder` is given, the lexicographical order of variables may change to another one that is likely to decrease the running time.

    Note that this may also cause a change of the returned list, which may now have polynomials over the same coefficient ring `R` but with a possibly re-ordered variable list. Thus, it may contain elements not belonging to this domain.

  - This method is merely an interface for the function `groebner::gbasis`.

  - This method only exists if `R` is a field, i.e., a domain of category `Cat::Field`, and `Vars` is not the empty list.

#### Method int: definite and indefinite integration of a polynomial

- `int(dom a <, indeterminate x>)`
- `int(dom a <, x=x0..x1>)`
- - `int(a,x)` returns the indefinite integral int(a,x) as an element either of this domain (if `R` is of category `Cat::Field` or of category `Cat::Algebra(Dom::Rational)` or `Cat::Algebra(Dom::Fraction(Dom::Integer))`) or as an element of a polynomial domain over `Dom::Fraction(R)` or `FAIL`, if the antiderivative cannot be converted into one of the previously given domains. If `a` has only one variable, the second argument is not necessary.
  - `int(a,x=x0..x1)` returns the definite integral int(a,x=x0..x1) or `FAIL`, if the result is not an element of this domain or an element of a polynomial domain over `Dom::Fraction(R)`.
  - This method overloads the function `int` for polynomials.

#### Method intmult: multiplies a polynomial with an integer

- `intmult(dom a, integer z)`
- - Multiplies `a` by `z`.
  - This method is more efficient than using polynomial multiplication and is, e.g., necessary for the method `"Dpoly"`.

#### Method isone: test for one

- `isone(dom a)`
- - Tests if `a` is the multiplicative neutral element of this domain and returns `TRUE` if this is the case, otherwise `FALSE`.

  - The result can only be valid if the coefficients of `a` are in normal form (i.e., if zero has a unique representation in `R`). Thus, `R` should have at least `Ax::normalRep`.

#### Method iszero: test for zero

- `iszero(dom a)`
- - Tests if `a` is the additive neutral element of this domain and returns `TRUE` if this is the case, otherwise `FALSE`.

  - The result can only be valid, if the coefficients of `a` are in normal form (i.e., if zero has a unique representation in `R`). Thus, the coefficient ring `R` should have at least `Ax::normalRep`.

#### Method lcm: least common multiple of polynomials

- `lcm(dom a, dom b...)`
- - Computes the least common multiple of the polynomials `a, b, ...`
  - This method overloads the function `lcm` for polynomials.

  - This method only exists if `R` is a domain of category `Cat::GcdDomain`.

#### Method makeIntegral: makes the coefficients fraction free

- `makeIntegral(dom a)`
- - Multiplies `a` by the `lcm` of all coefficient denominators.

  - This method only exists if `R` is a domain of category `Cat::GcdDomain` and `R` has the method `"denom"`.

#### Method monic: normalizes a polynomial

- `monic(dom a)`
- - Normalizes `a`, i.e., the leading coefficient of the resulting polynomial is `R::one`. For this, `a` is divided by its leading coefficient.
  - The zero polynomial returns itself.

  - This method only exists if `R` is a field, i.e., a domain of category `Cat::Field`.

#### Method normalForm: complete reduction modulo an ideal

- `normalForm(dom a, list of dom ais <, monomial ordering ord>)`
- `normalForm(dom a, set of dom ais <, monomial ordering ord>)`
- - Reduces the polynomial `a` completely modulo all polynomials of `ais` (see `groebner::normalf`) with respect to the monomial ordering `ord` (i.e., w.r.t. `Order`, if `ord` is not explicitly given).
    A reduced form of `a` always exists, but need not be unique; if `ais` form a Gröbner basis, it is unique.
  - This method is merely an interface for the function `groebner::normalf`.

  - This method only exists if `R` is a field, i.e., a domain of category `Cat::Field`, and `Vars` is not the empty list.

#### Method numericSolve: numerical zeros of polynomials

- `numericSolve(dom a <, indeterminate var> <, options>)`
- `numericSolve(dom a <, list or set of indeterminates vars> <, options>)`
- `numericSolve(list or set of dom ais <, indeterminate var> <, options>)`
- `numericSolve(list or set of dom ais <, list or set of indeterminates vars> <, options>)`
- - `numericSolve(a, ..)` tries to find the zeros of `a` numerically. It is possible to control the behavior of `numericSolve` by passing a variable or a set or list of variables together with options. For details see the function `numeric::solve`).
  - `numericSolve(ais, ..)` tries to find the zeros of the polynomial system `ais` numerically, with the exact behavior depending on further arguments. For details see the function `numeric::solve`).
  - All coefficients must be convertible into the basic domain `DOM_EXPR`, since in a precomputation step all polynomials of this domain are converted into the basic polynomial domain `DOM_POLY` over `DOM_EXPR`.
  - For a detailed description of possible return values and options see function `numeric::solve`.
  - This method overloads the function `numeric::solve`.

#### Method pdioe: solves polynomial Diophantine equations

- `pdioe(dom a, dom b, dom c)`
- - Returns a sequence of two polynomials `u` and `v` that satisfy the equation `a*u + b*v` = `c` or `FAIL`, if this equation is not solvable.
  - This method overloads the function `solvelib::pdioe`.

  - This method only exists if `R` is a field, i.e., a domain of category `Cat::Field` and `Vars` consists of a single variable.

#### Method pdivide: pseudo-division of polynomials

- `pdivide(dom a, dom b <, Quo or Rem opt>)`
- - Computes the pseudo-division of `a` by `b` and returns the sequence consisting of an element `p` of `R` and two polynomials `q` and `r` of this domain satisfying `p*a` = `q*b+r`, where `p` = `lcoeff(b)^(degree(a)-degree(b)+1)`.
  - If the option `Quo` is given, only the pseudo-quotient `q` is returned.
  - If the option `Rem` is given, only the pseudo-remainder `r` is returned.
  - This method overloads the function `pdivide` for polynomials.

  - This method only exists if `Vars` consists of a single variable.

#### Method pquo: pseudo-quotient of polynomials

- `pquo(dom a, dom b)`
- - Computes the pseudo-quotient of `a` by `b`. For details see method `"pdivide"`.

  - This method only exists if `Vars` consists of a single variable.

#### Method prem: pseudo-remainder of polynomials

- `prem(dom a, dom b)`
- - Computes the pseudo-remainder of `a` by `b`. For details see method `"pdivide"`.

  - This method only exists if `Vars` consists of a single variable.

#### Method random: creates a random polynomial

- `random()`
- - Returns a random generated polynomial of this domain.
  - With every call the global variable `SEED` is changed by a call of `random()`. Thus it is hard to create the same random sequence twice, see `random`.
  - If the parameter `Vars` is the empty list, first a list of 1 to 4 variables is generated randomly and the random polynomial is generated in these indeterminates afterwards.
  - This method overloads the function `polylib::randpoly` for polynomials.

#### Method realSolve: isolates all real roots of a real univariate polynomial

- `realSolve(dom a <, positive real number eps>)`
- - `realSolve(a)` returns intervals isolating the real roots of the real univariate polynomial `a`.
  - `realSolve(a, eps)` returns refined intervals approximating the real roots of `a` to the relative precision given by `eps`.
  - For a detailed description see function `polylib::realroots`.
  - All coefficients must be convertible into either integers, rational numbers or (real) floating point numbers.
  - This method overloads the function `polylib::realroots` for polynomials.

  - This method only exists if `Vars` consists of a single variable.

#### Method resultant: resultant of two polynomials

- `resultant(dom a, dom b <, indeterminate var>)`
- - `resultant(a, b)` returns the resultant of `a` and `b` with respect to their main variable, i.e., the return value of the call `a::dom::mainvar(a)`.
  - `resultant(a, b, var)` returns the resultant of `a` and `b` with respect to the variable `var`.
  - The value returned is a polynomial of this domain or `FAIL`.
  - This method overloads the function `polylib::resultant` for polynomials.

  - This method only exists if `R` has the method `"_divide"`.

#### Method ringmult: multiplies a polynomial with a coefficient ring element

- `ringmult(dom a, R c)`
- - Multiplies `a` by the coefficient ring element `c`.

#### Method solve: zeros of polynomials

- `solve(dom a <, indeterminate var> <, options>)`
- `solve(dom a <, list or set of indeterminates vars> <, options>)`
- `solve(list or set of dom ais <, indeterminate var> <, options>)`
- `solve(list or set of dom ais <, list or set of indeterminates vars> <, options>)`
- - `solve(a, ..)` tries to find the zeros of `a`. It is possible to control the behavior of `solve` by passing a variable or a set or list of variables together with options.
  - `solve(ais, ..)` tries to find the zeros of the polynomial system `ais`. The exact behavior depends on further arguments.
  - For a detailed description of possible return values and options see function `solve`.
  - This method overloads the function `solve`.

#### Method SPolynomial: computes the S-polynomial of two polynomials

- `SPolynomial(dom a, dom b <, monomial ordering ord>)`
- - Computes the S-polynomial of `a` and `b` with respect to the monomial ordering `ord` (or w.r.t. `Order`, if `ord` is not explicitly given).
  - This method is merely an interface for the function `groebner::spoly`.

  - This method only exists if `R` is a field, i.e., a domain of category `Cat::Field`, and `Vars` is not the empty list.

#### Method sqrfree: square-free factorization of polynomials

- `sqrfree(dom a)`
- - Returns the square-free factorization of `a` as a list in the form `[u, a1, e1, ..., an, en]` which means that `a` = `u * a1^e1 * ... * an^en`.
  - The `ai` are primitive and pairwise different square-free divisors of `a` and represented as elements of this domain. `u` is a unit of the coefficient ring and represented as an element of this domain. The `ei` are integers.
  - This method overloads the function `polylib::sqrfree` for polynomials.

  - This method only exists if `R` is a field, i.e., a domain of category `Cat::Field`, or if `R` is `Dom::Integer`.

#### Method coeff: coefficients of a polynomial

- `coeff(dom a)`
- `coeff(dom a, indeterminate var, NonNegativeInteger n)`
- `coeff(dom a, NonNegativeInteger n)`
- - `coeff(a)` returns a sequence with all coefficients of `a` as elements of the coefficient ring `R`. The coefficients are ordered according to the monomial ordering `Order`.
  - `coeff(a,var,n)` returns the coefficient of the term `var^n`--as an element of this domain if it is of category `Cat::Polynomial(R)`, or as an element of the coefficient ring `R` if it is of `Cat::UnivariatePolynomial(R)`, where `a` is considered as a univariate polynomial in a valid variable `var`.
  - `coeff(a,n)` returns the coefficient of the term `var^n`--as an element of this domain if it is of category `Cat::Polynomial(R)`, or as an element of the coefficient ring `R` if it is of `Cat::UnivariatePolynomial(R)`, where `a` is considered as a univariate polynomial in `var` and `var` is the main variable of `a`, i.e., the variable returned by `dom::mainvar(a)`.
  - This method overloads the function `coeff` for polynomials.

#### Method degree: degree of a polynomial

- `degree(dom a)`
- `degree(dom a, indeterminate var)`
- - `degree(a)` returns the total degree of `a`.
  - `degree(a, var)` returns the degree of `a` with respect to `var`.
  - The degree of the zero polynomial is defined as zero.
  - This method overloads the function `degree` for polynomials.

#### Method degreevec: vector of exponents of the leading term of a polynomial

- `degreevec(dom a <, monomial ordering ord>)`
- - Returns the vector of exponents of the leading term of `a` with respect to the monomial ordering `ord` as a list. If `var1^e1 * ... * varm^em` is the leading term then the list `[e1, ..., em]` is returned. If `ord` is not explicitely given, the ordering `Order` will be used instead.
  - The degree vector of the zero polynomial is defined as a list of zeros.
  - This method overloads the function `degreevec` for polynomials.

#### Method euclideanDegree: Euclidean degree function

- `euclideanDegree(dom a)`
- - Returns the Euclidean degree of `a`, which is here simply defined as the degree of `a`.

  - This method only exists if `Vars` consists of a single variable.

#### Method ground: ground term of a polynomial

- `ground(dom a)`
- - Returns the term of `a` in which no variable of `a` occurs.
  - This method overloads the function `ground` for polynomials.

#### Method has: existence of an object in a polynomial

- `has(dom a, any obj)`
- - Tests if `a` contains the object `obj`. Only complete subexpressions and operators are found. If the second argument is a list or set then these elements are tested to see if at least one of it is a subexpression of `a`. See function `has` for more details.
  - This method overloads the function `has`.

#### Method indets: indeterminates of a polynomial

- `indets( <dom a>)`
- - Returns a set of all indeterminates of `a`.
  - In case `Vars` is not the empty list, `indets` can be called without argument.
  - Since this domain allows expressions as indeterminates, the returned set may contain expressions, too.
  - This method overloads the function `indets` for polynomials.

#### Method lcoeff: leading coefficient of a polynomial

- `lcoeff(dom a)`
- `lcoeff(dom a <, list of indeterminates vars> <, monomial ordering ord>)`
- - `lcoeff(a)` returns the leading coefficient of `a` with respect to the monomial ordering `Order` as an element of the coefficient ring `R`.
  - `lcoeff(a, ord)` returns the leading coefficient of `a` with respect to the monomial ordering `ord` as an element of the coefficient ring `R`.
  - `lcoeff(a, vars <, ord>)` returns the leading coefficient of `a` with respect to the variable list `vars` and the monomial ordering `ord` as an element of this domain if it is of category `Cat::Polynomial(R)`, or as an element of the coefficient ring `R` if it is of `Cat::UnivariatePolynomial(R)`.
    - If `ord` is not explicitly given, the lexicographical order `LexOrder` will be used instead.
    - It tries to convert `a` into a polynomial in the specified list of indeterminates `vars` over the coefficient ring `R` and returns `FAIL` if this conversions fails.
  - This method overloads the function `lcoeff` for polynomials.

#### Method ldegree: lowest degree of a polynomial

- `ldegree(dom a)`
- `ldegree(dom a, indeterminate x)`
- - `ldegree(a)` returns the lowest total degree of the terms of `a`.
  - `ldegree(a, x)` returns the lowest degree of the variable `x` in `a`.
  - This method overloads the function `ldegree` for polynomials.

#### Method lmonomial: leading monomial of a polynomial

- `lmonomial(dom a <, monomial ordering ord>)`
- `lmonomial(dom a <, list of indeterminates vars> <, monomial ordering ord> <, Rem>)`
- - `lmonomial(a <, ord>)` returns the leading monomial of `a` with respect to the monomial ordering `ord` as an element of this domain. If `ord` is not explicitly given, the ordering `Order` will be used instead.
  - `lmonomial(a, vars <, ord>)` returns the leading monomial of `a` with respect to the variable list `vars` and the monomial ordering `ord` as an element of this domain.
    - If `ord` is not explicitly given, the lexicographical order `LexOrder` will be used instead.
    - It tries to convert `a` into a polynomial in the specified list of indeterminates `vars` over the coefficient ring `R` and returns `FAIL` if this conversions fails.
  - `lmonomial(a <, vars> <, ord>, Rem)` returns the list consisting of the leading monomial and the reductum of `a` with respect to the variable list `vars` and the monomial ordering `ord` as a list of elements of this domain.
    - If `ord` is not explicitly given, the lexicographical order `LexOrder` will be used instead.
    - It tries to convert `a` into a polynomial in the specified list of indeterminates `vars` over the coefficient ring `R` and returns `FAIL` if this conversions fails.

  - In MuPAD a monomial denotes a coefficient together with a power product as, e.g., 3x2.

  - This method overloads the function `lmonomial` for polynomials.

#### Method lterm: leading term of a polynomial

- `lterm(dom a)`
- `lterm(dom a <, list of indeterminates vars> <, monomial ordering ord>)`
- - `lterm(a)` returns the leading term of `a` with respect to the monomial ordering `Order` as an element of this domain.
  - `lterm(a, ord)` returns the leading coefficient of `a` with respect to the monomial ordering `ord` as an element of this domain.
  - `lterm(a, vars <, ord>)` returns the leading term of `a` with respect to the variable list `vars` and the monomial ordering `ord` as an element of this domain.
    - If `ord` is not explicitly given, the lexicographical order `LexOrder` will be used instead.
    - It tries to convert `a` into a polynomial in the specified list of indeterminates `vars` over the coefficient ring `R` and returns `FAIL` if this conversions fails.

  - In MuPAD a term denotes a power product without a coefficient as, e.g., x2y3z.

  - This method overloads the function `lterm` for polynomials.

#### Method mainvar: main variable of a polynomial

- `mainvar( <dom a>)`
- - Returns the main indeterminate of `a`, i.e., the first element of `dom::orderedVariableList(a)`.
  - If `Vars` is not the empty list, `mainvar` can be called without argument.

#### Method mapcoeffs: applies a function to the coefficients of a polynomial

- `mapcoeffs(dom a, function f <, sequence of arguments e1... >)`
- - Applies the function `f` to the coefficients of `a` and returns `a` with the new coefficients.
    - `mapcoeffs(a, f)`: `f(ci)` is executed for each coefficient `ci` of `a`.
    - `mapcoeffs(a, f, e1, ..., en)`: `f(ci, e1, ..., en)` is executed for each coefficient `ci` of `a` with the additional arguments `e1, ..., en`.
  - This method overloads the function `mapcoeffs` for polynomials.

#### Method multcoeffs: multiplies the coefficients of a polynomial with a factor

- `multcoeffs(dom a, R c)`
- - Multiplies all the coefficients of `a` with the factor `c`.
  - This method overloads the function `multcoeffs` for polynomials.

#### Method nterms: number of terms of a polynomial

- `nterms(dom a)`
- - Returns the number of non-zero terms of `a`. The zero polynomial has no terms.
  - This method overloads the function `nterms` for polynomials.

#### Method nthcoeff: n-th coefficient of a polynomial

- `nthcoeff(dom a, integer n <,monomial ordering ord>)`
- - Returns the `n`-th (non-zero) coefficient of `a` with respect to the monomial ordering `ord`. If `ord` is not explicitly given, the ordering `Order` will be used instead.
  - If `n` is larger than the number of monomials of the polynomial then the function returns `FAIL`.
  - The zero polynomial has no monomials. `nthcoeff` returns `FAIL` when invoked on the zero polynomial.
  - This method overloads the function `nthcoeff` for polynomials.

#### Method nthmonomial: n-th monomial of a polynomial

- `nthmonomial(dom a, integer n <,monomial ordering ord>)`
- - Returns the `n`-th (non-zero) monomial of `a` with respect to the monomial ordering `ord`. If `ord` is not explicitly given, the ordering `Order` will be used instead.
  - If `n` is larger than the number of monomials of the polynomial then the function returns `FAIL`.
  - The zero polynomial has no monomials. `nthmonomial` returns `FAIL` for the zero polynomial.
  - This method overloads the function `nthmonomial` for polynomials.

#### Method nthterm: n-th term of a polynomial

- `nthterm(dom a, integer n <,monomial ordering ord>)`
- - Returns the `n`-th (non-zero) term of `a` with respect to the monomial ordering `ord`. If `ord` is not explicitly given, the ordering `Order` will be used instead.
  - If `n` is larger than the number of monomials of the polynomial then the function returns `FAIL`.
  - The zero polynomial has no monomials. `nthterm` returns `FAIL` when called with the zero polynomial.
  - This method overloads the function `nthterm` for polynomials.

#### Method orderedVariableList: ordered list of indeterminates of a polynomial

- `orderedVariableList( <dom a>)`
- - Returns the ordered list of variables as specified when creating the domain. If no variable was specified for this domain (i.e., `Vars = []`, a sorted list of all variables of `a` is returned.
  - In case `Vars` is not the empty list, `orderedVariableList` can be called without an argument.

#### Method pivotSize: size of a pivot element

- `pivotSize(dom a)`
- - Returns the ``size'' of `a` as a pivot element, which is simply the total degree of `a`.
  - This method is called if this domain is used as the component ring of a matrix domain to perform a Gaussian elimination.

#### Method reductum: reductum of a polynomial

- `reductum(dom a <,monomial ordering ord>)`
- - Returns the reductum of `a` (i.e., `a-lmonomial(a)`) with respect to the monomial ordering `ord`. If `ord` is not explicitly given, the ordering `Order` will be used instead.

#### Method tcoeff: lowest coefficient of a polynomial

- `tcoeff(dom a <,monomial ordering ord>)`
- - Returns the lowest coefficient of `a` with respect to the monomial ordering `ord`. If `ord` is not explicitly given, the ordering `Order` will be used instead.
  - This method overloads the function `tcoeff` for polynomials.

#### Method convert: conversion to a polynomial

- `convert(any p)`
- - Tries to convert a polynomial expression or a polynomial `p` to an element of this domain and returns either an element of this domain or `FAIL`.

#### Method expr: conversion to a basic type

- `expr(dom a)`
- - Converts the polynomial `a` of this domain into an element of a basic domain. Thus the coefficients may no longer belong to the coefficient ring `R`.
  - This method overloads the function `expr`.

#### Method poly: converts to a basic polynomial domain

- `poly(dom a)`
- - Converts the polynomial `a` of this domain into an element of the basic domain `DOM_POLY`.
  - This method overloads the function `poly`.

#### Method TeX: TeX formatting of a polynomial

- `TeX(dom a)`
- - Returns a TeX-formatted string for the polynomial `a`.

#### Method TeXCoeff: TeX formatting of a polynomial coefficient

- `TeXCoeff(R c)`
- - Returns a TeX-formatted string for the polynomial coefficient `c`.

#### Method TeXident: TeX formatting of a polynomial indeterminate

- `TeXident(indeterminate var)`
- - Returns a TeX-formatted string for the polynomial indeterminate `var`.

#### Method TeXTerm: TeX formatting of a polynomial term

- `TeXTerm(dom t)`
- - Returns a TeX-formatted string for the polynomial term `t`.

#### Method adaptIndets: converts polynomials to common indeterminates

- `adaptIndets( <dom a, dom b ...>)`
- - Computes a common sorted list of indeterminates of all arguments and returns the sequence of polynomials converted to polynomials of type `DOM_POLY` with respect to this list of indeterminates.

  - This method only exists if the parameter `Vars` is the empty list (`[]`).

#### Method isNeg: test on leading output token

- `isNeg(dom a)`
- - Tests the leading output token of `a` and returns `TRUE` if it is the minus token `-` and `FALSE` if that is not the case or MuPAD cannot determine that token (e.g., if a domain involved does not have this method).

#### Method mult: multiplies polynomials

- `mult(dom a, dom b...)`
- - Multiplies an arbitrary number of elements of this domain.

#### Method new: creates a new element

- `new(any p)`
- `new(list of lists lm)`
- `new(list of lists lm, list of indeterminates v)`
- - One may use this method either in the form `dom::new(p)` or in the form `dom(p)`.
  - `dom(p)` creates an element of this domain from a polynomial or a polynomial expression `p` and returns that element. If this is not possible, an error message is given.
  - If `Vars` is chosen as the empty list (`[]`) then in creating new elements from a polynomial or polynomial expression the function `indets` is first called to get the identifiers. Afterwards the element is created with this list of identifiers. For creating an element from a constant the dummy variable `_dummy` is introduced. The drawback of this approach is that two mathematically equal polynomials may have variable lists which differ by the dummy variable.
  - `dom(lm)` creates, if `Vars` ≠ `[]`, a polynomial from the list `lm` of the form `[[c1, [e11,... e1n]],... [cm,[em1,... emn]]]` where the `ci` are coefficients and the `eij` are the exponents with respect to `Vars`. For a univariate polynomial this list can be simplified to `[[c1,e1],... [cm,em]]`.
  - `dom(lm,v)` creates, if `Vars` = `[]`, a polynomial from the list `lm` of the form `[[c1, [e11,... e1n]],... [cm,[em1,... emn]]]` where the `ci` are coefficients and the `eij` are the exponents with respect to `v`. For a univariate polynomial this list can be simplified to `[[c1,e1],... [cm,em]]`. The list of indeterminates `v` must contain valid indeterminates.

#### Method plus: adds polynomials

- `plus(dom a, dom b...)`
- - Adds an arbitrary number of elements of this domain.

#### Method print: prints polynomials

- `print(dom a)`
- - Prints the polynomial `a`. The terms are printed with respect to the given monomial ordering `Order` in descending order.
  - This method overloads the function `print`.

#### Method printMonomial: prints a monomial in defined order

- `printMonomial(R c, list of NonNegativeIntegers d, list of indeterminates v)`
- - Returns an ordered expression `c*v[1]^d[1]*..`, where `d` is the degree vector with respect to variable list `v`.

#### Method printTerm: prints a term in defined order

- `printTerm(list of NonNegativeIntegers d)`
- `printTerm(list of NonNegativeIntegers d, list of indeterminates v)`
- - `printTerm(d)` returns an ordered sequence of the indeterminates together with their powers as given in `Vars` and the degree vector `d` respectively.

    Note that this call is only valid if `Vars` is not the empty list.

  - `printTerm(d,v)` returns an ordered sequence of the indeterminates together with their powers as given in the variable list `v` and the degree vector `d` respectively.

    Note that this call is only valid if `nops(v)=nops(d)`.

#### Method Rep: data representation of a polynomial

- `Rep(dom a)`
- - Returns the internal data representation of `a`.

#### Method sign: leading sign of a polynomial

- `sign(dom a)`
- - Determines the sign of `a`, which is 0 if `a` is zero, 1 if `a` is either a positive constant or a positive monomial, `sign(a)` if `nterms(a)` > 1 and -1 otherwise. This method is currently used within the `"printMonomial"` method for pretty printing elements of this domain and is more or less intended to be an internal procedure. It is planned to replace this method by the method `"isNeg"` in future versions.
  - Note: this method does not have the meaning of a mathematical sign function!

#### Example 1

The following call creates a polynomial domain in x, y and z.

    >> DP := Dom::DistributedPolynomial([x, y, z])

          Dom::DistributedPolynomial([x, y, z],

             Dom::ExpressionField(normal, iszero@normal), LexOrder)

Since neither the coefficient ring nor the monomial ordering was specified, this domain is created with the default values for these parameters.

It is rather easy to create elements of this domain, as e.g.

    >> a := DP(x + 2*y*z + 3)

                                   x + 2 y z + 3

    >> b := DP(z^4 - 2*y^2*x^2)

                                       2  2    4
                                  - 2 x  y  + z

In contrast to expressions all elements of this domain have a representation which is fixed by the chosen `Order`, the representation of the coefficient ring `R` and the way of representing monomials.

With these elements one can now perform usual arithmetic operations as, e.g., (scalar) multiplication, multiplication with integers and adding polynomials and ring elements:

    >> 4*b^2 + a/3 + 1/2

                   4  4       2  2  4                        8
               16 x  y  - 16 x  y  z  + 1/3 x + 2/3 y z + 4 z  + 3/2

There are a lot of methods for manipulating polynomials and to get access to all parts of a polynomial. For example one has access to the leading monomial of `a` as follows:

    >> lmonomial(a)

                                         x

The leading monomial of a polynomial depends on the monomial ordering, so with respect to the degree order one gets a different result:

    >> lmonomial(a, DegreeOrder)

                                       2 y z

To get `a` minus its leading monomial one may call:

    >> DP::reductum(a)

                                     2 y z + 3

Obviously the following identity holds:

    >> a - lmonomial(a) - DP::reductum(a)

                                         0

There are also methods for converting elements of this domain into other domains, like a basic polynomial domain or the domain of arbitrary expressions:

    >> poly(a), domtype(poly(a))

          poly(x + 2 y z + 3, [x, y, z], Dom::ExpressionField(normal,

             iszero@normal)), DOM_POLY

    >> expr(b), domtype(expr(b))

                               4      2  2
                              z  - 2 x  y , DOM_EXPR

#### Super-Domain

`Dom::BaseDomain`

#### Axioms

if `R` has `Ax::normalRep`, then
`Ax::normalRep`
if `R` has `Ax::canonicalRep`, then
`Ax::canonicalRep`

#### Changes

- used to be called `Dom::PolynomialExplicit`
- The former implementation of this domain does no longer exist and is replaced by the former (undocumented) domain constructor `Dom::PolynomialExplicit`.
- It is now allowed to call this domain with zero, one, two or three arguments. With the third argument one can now choose an appropriate monomial ordering.
- The method `"indets"` now returns a set of indeterminates.
- The methods `"Rep"`, `"SPolynomial"`, `"decompose"`, `"dimension"`, `"func_call"`, `"groebner"`, `"ground"`, `"int"`, `"makeIntegral"`, `"monic"`, `"numericSolve"`, `"orderedVariableList"`, `"ordering"`, `"realSolve"`, `"reductum"`, `"resultant"`, `"variables"` were added.
- The method `"Factor"` was removed.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000