## `poly` -- create a polynomial

#### Introduction

`poly(`f`)` converts a polynomial expression `f` to a polynomial of the kernel domain `DOM_POLY`.

#### Call(s)

`poly(f <, [x1, x2...]> <, ring>)`
`poly(p <, [x1, x2...]> <, ring>)`
`poly(list, [x1, x2...] <, ring>)`

#### Parameters

`f` | - | a polynomial expression
`x1, x2...` | - | the indeterminates of the polynomial: typically, identifiers or indexed identifiers.
`ring` | - | the coefficient ring: either Expr, or IntMod`(n)` with some integer `n` > 1, or a domain of type `DOM_DOMAIN`. The default is the ring Expr of arbitrary MuPAD expressions.
`p` | - | a polynomial of type `DOM_POLY` generated by `poly`
`list` | - | a list containing coefficients and exponents

#### Returns

a polynomial of the domain type `DOM_POLY`. `FAIL` is returned if conversion to a polynomial is not possible.

#### Related Functions

`Dom::DistributedPolynomial`, `Dom::MultivariatePolynomial`, `Dom::Polynomial`, `Dom::UnivariatePolynomial`, `RootOf`, `coeff`, `collect`, `degree`, `degreevec`, `divide`, `evalp`, `expr`, `factor`, `gcd`, `ground`, `indets`, `lcoeff`, `ldegree`, `lmonomial`, `lterm`, `mapcoeffs`, `nterms`, `nthcoeff`, `nthmonomial`, `nthterm`, `poly2list`, `polylib`, `tcoeff`

#### Details

- MuPAD provides the kernel domain `DOM_POLY` to represent polynomials. The arithmetic for this data structure is more efficient than the arithmetic for polynomial expressions. Moreover, this domain allows to use special coefficient rings that cannot be represented by expressions. The function `poly` is the tool for generating polynomials of this type.
- `poly(`f, [x1, x2...], ring`)` converts the expression `f` to a polynomial in the indeterminates `x1, x2...` over the specified coefficient ring. The expression `f` need not be entered in expanded form, it is internally expanded by `poly`.

  If no indeterminates are given, they are searched for internally. An error occurs if no indeterminates are found.

  The ring `Expr` is used if no coefficient ring is specified. In this case, arbitrary MuPAD expressions are allowed as coefficients.

  `poly` returns `FAIL` if the expression cannot be converted to a polynomial. Cf. example 9.

- `poly(`p, [x1, x2...], ring`)` converts a polynomial `p` of type `DOM_POLY` to a polynomial in the indeterminates `x1, x2...` over the specified coefficient ring. Note that both the indeterminates as well as the coefficient ring are part of the data structure `DOM_POLY`. This call may be used to change these data in a given polynomial `p` of this type.

  If no indeterminates are specified, the indeterminates of `p` are used.

  If no coefficient ring is specified, the ring of `p` is used.

  Cf. examples 7 and 8.

- `poly(`list, [x1, x2...], ring`)` converts a list of coefficients and exponents to a polynomial in the indeterminates `x1, x2...` over the specified coefficient ring. Cf. examples 3 and 6. This call is the fastest way of creating a polynomial of type `DOM_POLY`.

  The list must contain an element for each non-zero monomial of the polynomial, i.e., it is possible to use sparse input involving only non-zero terms. In particular, an empty list results in the zero polynomial.

  Each element of the list must in turn be a list with two elements: the coefficient of the monomial and the exponent or exponent vector. For a univariate polynomial in the variable x, say, the list

      [[c1, e1], [c2, e2], ...]

  corresponds to c1*x^e1 + c2*x^e2 + .... For a multivariate polynomial, the exponent vectors are lists containing the exponents of all indeterminates of the polynomial. The order of the exponents must be the same as the order given by the list of indeterminates. For a multivariate polynomial in the variables x1, x2, .., say, the term list

      [[c1, [e11, e12, ...]], [c2,[e21, e22, ... emn]], ..]

  corresponds to c1*x1^e11*x2^e12*... + c2*x1^e21*x2^e22*... + ....

  The order of the elements of the term list does not affect the resulting polynomial. There may be multiple entries corresponding to the same term: the coefficients are added in such cases.

  With this call, term lists returned by `poly2list` can be reconverted to polynomials.

- The order of the indeterminates is given by their position in the input list `[x1, x2...]`. If not specified, they are searched for internally in the expression `f` and their order is determined by the system. Cf. example 2.
- The indeterminates need not be identifiers or indexed identifiers. Any expression can be used as an indeterminate as long as it is not rational. E.g., the expressions `sin(x)`, `f(x)`, or `y^(1/3)` are accepted as indeterminates. Cf. example 4.
- `poly` is a function of the system kernel.

#### Option: `ring`

- The default ring Expr represents arbitrary MuPAD expressions. Mathematically, this ring coincides with `Dom::ExpressionField``()`. Note, however, that polynomials distinguish Expr and `Dom::ExpressionField``()`. In particular, arithmetic over Expr is faster.
- The ring IntMod`(n)` represents the residue class ring Z/nZ, using the symmetrical representation. Here, `n` must be an integer greater than 1. Mathematically, this ring coincides with `Dom::IntegerMod``(n)`. Note, however, that polynomials distinguish IntMod`(n)` and `Dom::IntegerMod``(n)`. In particular, arithmetic over IntMod is faster, coefficients requested by `coeff` etc. are returned as integers of type `DOM_INT`. Cf. examples 5, 6, and 8.
- Any domain of type `DOM_DOMAIN` can be used as a coefficient ring if the domain provides arithmetical operations. See the ``Background'' section below for further details.

  If a coefficient domain is specified, only elements of the domain are accepted as coefficients. On input, `poly` tries to convert a polynomial expression `f` to a polynomial over the coefficient ring. For some coefficient rings, however, it is not possible to use arithmetical expressions to represent a polynomial, because multiplication with the indeterminates may not be a valid operation in the ring. In this case, the polynomial can be defined via a term list. Cf. example 6.

#### Example 1

A call of `poly` creates a polynomial from a polynomial expression:

    >> p := poly(2*x*(x + 3))

                                       2
                               poly(2 x  + 6 x, [x])

The operators `*`, `+`, `-` and `^` work on polynomials:

    >> p^2 - p + poly(x, [x])

                               4       3       2
                       poly(4 x  + 24 x  + 34 x  - 5 x, [x])

For multiplication with a constant, one must either convert the constant to a polynomial of the appropriate type, or one can use `multcoeffs`:

    >> poly(c, [x])*p = multcoeffs(p, c)

                       2                               2
           poly((2 c) x  + (6 c) x, [x]) = poly((2 c) x  + (6 c) x, [x])

    >> delete p:

#### Example 2

A polynomial may be created with parameters. In the following call, `y` is a parameter and not an indeterminate:

    >> poly((x*(y + 1))^2, [x])

                                          2  2
                              poly((y + 1)  x , [x])

If no indeterminates are specified, they are searched for automatically. In the following call, the previous expression is converted to a multivariate polynomial:

    >> poly((x*(y + 1))^2)

                               2  2        2    2
                         poly(y  x  + 2 y x  + x , [y, x])

The order of the indeterminates can be specified explicitly:

    >> poly((x*(y + 1))^2, [x, y])

                               2  2      2      2
                         poly(x  y  + 2 x  y + x , [x, y])

#### Example 3

The following polynomials are created by term lists:

    >> poly([[c2, 3], [c1, 7], [c3, 0]], [x])

                                    7       3
                           poly(c1 x  + c2 x  + c3, [x])

    >> poly([[c2, 3], [c1, 7], [c3, 0], [a, 3]], [x])

                                 7             3
                        poly(c1 x  + (a + c2) x  + c3, [x])

For multivariate polynomials, exponent vectors must be specified via lists:

    >> poly([[c1, [2, 2]], [c2, [2, 1]], [c3, [2, 0]]], [x, y])

                              2  2       2         2
                     poly(c1 x  y  + c2 x  y + c3 x , [x, y])

#### Example 4

Expressions such as `f(x)` may be used as indeterminates:

    >> poly(f(x)*(f(x) + x^2))

                               2            2
                         poly(x  f(x) + f(x) , [x, f(x)])

#### Example 5

The residue class ring IntMod`(7)` is a valid coefficient ring:

    >> p := poly(9*x^3 + 4*x - 7, [x], IntMod(7))

                                 3
                         poly(2 x  - 3 x, [x], IntMod(7))

Internally, modular arithmetic is used when computing with polynomials over this ring:

    >> p^3

                           9    7      5    3
                     poly(x  - x  - 2 x  + x , [x], IntMod(7))

Note, however, that coefficients are not returned as elements of a special domain, but as plain integers of type `DOM_INT`:

    >> coeff(p)

                                       2, -3

    >> delete p:

#### Example 6

The input syntax using term lists may be combined with a given coefficient ring:

    >> poly([[9, 3], [4, 1], [-2, 0]], [x], IntMod(7))

                               3
                       poly(2 x  - 3 x - 2, [x], IntMod(7))

Note that the input coefficients are interpreted as elements of the coefficient domain, i.e., conversions such as 9 mod 7 -> 2 occur on input. We can also use the domain `Dom::IntegerMod``(7)` to define an equivalent polynomial. However, in contrast to IntMod`(7)`, the coefficients a represented by the numbers 0,...,6 rather than -3,...,3:

    >> poly([[9, 3], [4, 1], [-2, 0]], [x], Dom::IntegerMod(7))

                           3
                   poly(2 x  + 4 x + 5, [x], Dom::IntegerMod(7))

Note that the following attempt to define a polynomial via an expression fails, because the domain `Dom::IntegerMod``(7)` does not permit multiplication with identifiers:

    >> c := Dom::IntegerMod(7)(3)

                                      3 mod 7

    >> poly(c*x^2, [x], Dom::IntegerMod(7))

                                       FAIL

In such a case, term lists allow to specify the polynomial:

    >> poly([[c, 2]], [x], Dom::IntegerMod(7))

                                2
                        poly(3 x , [x], Dom::IntegerMod(7))

    >> delete c:

#### Example 7

It is possible to change the indeterminates in a polynomial:

    >> p:= poly(((a + b)*x - a^2)*x, [x]): p, poly(p, [a, b])

                        2       2
          poly((a + b) x  + (- a ) x, [x]),

                        2    2      2
             poly((-x) a  + x  a + x  b, [a, b])

#### Example 8

It is possible to change the coefficient ring of a polynomial:

    >> p := poly(-4*x + 5*y - 5, [x, y], IntMod(7)):
       p, poly(p, IntMod(3))

          poly(3 x - 2 y + 2, [x, y], IntMod(7)),

             poly(y - 1, [x, y], IntMod(3))

#### Example 9

Here we create a polynomial over the coefficient ring `Dom::Float`:

    >> poly(3*x - y, Dom::Float)

                     poly(- 1.0 y + 3.0 x, [y, x], Dom::Float)

The identifier `y` cannot turn up in coefficients from this ring, because it cannot be converted to a floating point number:

    >> poly(3*x - y, [x], Dom::Float)

                                       FAIL

#### Background

- A domain must contain certain entries if it is to be used as a coefficient domain:
  - The entry `"zero"` must provide the neutral element with respect to addition.
  - The entry `"one"` must provide the neutral element with respect to multiplication.
  - The method `"_plus"` must add domain elements.
  - The method `"_negate"` must return the inverse with respect to addition.
  - The method `"_mult"` must multiply domain elements.
  - The method `"_power"` must compute integer powers of a domain element. It is called with the domain element as the first argument and an integer as the second argument.
- Further, the following methods should be defined. They are called by functions such as `gcd`, `diff`, `divide`, `norm` etc.:
  - The method `"gcd"` must return the greatest common divisor of domain elements.
  - The method `"diff"` must differentiate a domain element with respect to a variable.
  - The method `"_divide"` must divide two domain elements. It must return `FAIL` if division is not possible.
  - The method `"norm"` must compute the norm of a domain element and return it as a number.
  - The method `"convert"` must convert an expression to a domain element. It must return `FAIL` if this is not possible.

    This method is called to convert the coefficients of polynomial expressions to coefficients of the specified domain. If this method does not exist then only domain elements can be used to specify the coefficients.

  - The method `"expr"` must convert a domain element to an expression.

    The system function `expr` calls this method to convert a polynomial over the coefficient domain to a polynomial expression. If this method does not exist, domain elements are simply inserted into the expression.

#### Changes

- no changes

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