Documentation

# `poly`, `Expr`, `IntMod`

Create a polynomial

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

## Syntax

```poly(`f`, <`[x1, x2, …]`>, <`ring`>)
poly(`p`, <`[x1, x2, …]`>, <`ring`>)
poly(`list`, `[x1, x2, …]`, <`ring`>)
poly(`coeffs`, `[x]`, <`ring`>)
```

## Description

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

The kernel domain `DOM_POLY` represents polynomials. The arithmetic for this data structure is more efficient than the arithmetic for polynomial expressions. Moreover, this domain allows you 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 `poly` function does not require an expanded form of the expression `f`. The function internally expands expressions.

If you do not specify indeterminates, MuPAD® searches for them internally. If MuPAD cannot identify indeterminates, it returns `FAIL`.

By default, the `poly` function uses the coefficient ring of arbitrary MuPAD expressions. In this case, you can use arbitrary MuPAD expressions as coefficients.

If the `poly` function cannot convert an expression to a polynomial, the function returns `FAIL`. See Example 10.

If `f` is a domain element, the system calls `f::dom::poly` for the conversion into a polynomial. If `f` contains domain elements, the system recursively calls `f::dom::poly` for domain elements inside `f`. See Example 11.

`poly(p, [x1, x2, ...], ring)` converts a polynomial `p` of the type `DOM_POLY` to a polynomial in the indeterminates `x1, x2, ...` over the specified coefficient ring. The indeterminates and the coefficient ring are part of the data structure `DOM_POLY`. Using this function call, you can change the indeterminates and the coefficient ring of a polynomial.

If you do not specify indeterminates, `poly` uses the indeterminates of the original polynomial `p`.

If you do not specify a coefficient ring, `poly` uses the ring of the original polynomial `p`.

See Example 8 and Example 9.

`poly(list, [x])` converts a list of coefficients [a0, a1, a2, …] to a univariate polynomial a0 + a1x + a2x2 + …. See Example 3.

For a univariate polynomial `p`, the call ```poly(list, [x])``` converts the result of the call `coeff(p, All)` back to a polynomial.

`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. See Example 4 and Example 7.

This call is the fastest method to create polynomials of the type `DOM_POLY` because the input already has the form that MuPAD uses internally.

The list must contain an element for each nonzero monomial of the polynomial. Therefore, you must use sparse input involving only nonzero terms. In particular, an empty list results in the zero polynomial.

Each element of the list must 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, the list corresponds to c1xe1 + c2xe2 + …. 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, the term list corresponds to c1x1e11x2e12 + c2x1e21x2e22 + ….

The order of the elements of the term list does not affect the resulting polynomial. If you provide multiple entries corresponding to the same term, `poly` adds the coefficients.

This call lets you restore polynomials from the term lists returned by `poly2list`.

The position of the indeterminates in the input list ```[x1, x2, ...]``` determines their order in the resulting polynomial. If you do not specify indeterminates, MuPAD searches the expression `f` for possible indeterminates and determines their order. See Example 2.

You can perform arithmetical operations on polynomials that have the same indeterminates and the same coefficient ring. Also, you can perform arithmetical operations on polynomials and arithmetical expressions. When you operate on a polynomial and an arithmetical expression, MuPAD internally converts that arithmetical expression to a polynomial and performs the calculation. See Example 1.

The `poly` function does not limit acceptable indeterminates to identifiers or indexed identifiers. You can use any expression (except for rational expressions) as an indeterminate. For example, `poly` accepts the expressions `sin(x)` and `f(x)` as indeterminates. See Example 5.

After creating a polynomial, the `poly` function does not evaluate the coefficients of the polynomial. If the coefficients contain free identifiers, `poly` does not replace these identifiers with their values. See Example 12.

If any domain of type `DOM_DOMAIN` provides arithmetical operations, you can use that domain as a coefficient ring. See the “Background” section for details.

If you specify a coefficient domain, MuPAD accepts only the elements of that domain as coefficients of the polynomial. On input, `poly` tries to convert a polynomial expression `f` to a polynomial over the coefficient ring. For some coefficient rings, you cannot use arithmetical expressions to represent a polynomial. The reason is that multiplication with the indeterminates can be an invalid operation in the ring. In such cases, you can define the polynomial by using a term list. See Example 7.

## Examples

### Example 1

The `poly` function creates a polynomial from a polynomial expression:

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

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

`p^2 - p*(p + 1)`
` `

You can multiply a polynomial by an arithmetical expression. MuPAD internally converts the expression to a polynomial of the appropriate type, and then multiplies polynomials. For example, multiply the polynomial `p` by the constant 5:

`p*5`
` `

Now, multiply the polynomial `p` by ```x - 1```:

`p*(x - 1)`
` `

If MuPAD cannot convert the expression to a polynomial of the appropriate type, the arithmetical operation between a polynomial and this expression fails:

`p*(1/x - 1)`
```Error: Invalid argument. [_mult] ```
`delete p:`

### Example 2

You can create a polynomial with parameters. In the following call, `y` is a parameter (not an indeterminate):

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

If you do not specify indeterminates, MuPAD tries to find indeterminates automatically. The following call converts a multivariate expression to a multivariate polynomial:

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

Now, specify the order of the indeterminates explicitly:

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

### Example 3

Use the `poly` function to convert the following list of coefficients to a univariate polynomial in `x`. The first entry of the list produces the term with the zero exponent. The last entry produces the term with the highest exponent:

`p := poly([1, 2, 3, 4, 5], [x])`
` `

To revert the ordering of the coefficients in a polynomial, use the `revert` function:

`revert(p)`
` `

### Example 4

Create the following polynomials by term lists:

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

If you provide multiple coefficients corresponding to the same exponent, `poly` adds those coefficients:

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

For multivariate polynomials, specify exponent vectors by lists:

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

### Example 5

You can use expressions as indeterminates:

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

### Example 6

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

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

For computations that involve polynomials over this ring, MuPAD uses modular arithmetic:

`p^3`
` `

However, MuPAD does not return coefficients as elements of a special domain. Instead, it returns coefficients as plain integers of the type `DOM_INT`:

`coeff(p)`
` `
`delete p:`

### Example 7

To create the following polynomial, combine the input syntax that uses term lists with a specified coefficient ring:

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

MuPAD interprets the input coefficients as elements of the coefficient domain. For example, conversions such as ```9 mod 7 = 2 mod 7``` occur on input. You also can use the domain `Dom::IntegerMod``(7)` to define an equivalent polynomial. If you use `IntMod``(7)`, MuPAD uses the symmetric modulo function `mods` and represents the coefficients by the numbers - 3, …, 3. If you use `Dom::IntegerMod``(7)`, MuPAD uses the positive modulo function `modp` and represents the coefficients by the numbers 0, …, 6:

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

The domain `Dom::IntegerMod``(7)` does not allow multiplication with identifiers:

`c := Dom::IntegerMod(7)(3)`
` `
`poly(c*x^2, [x], Dom::IntegerMod(7))`
` `

Instead, use the term list to specify the polynomial:

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

### Example 8

Change the indeterminates in a polynomial:

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

### Example 9

Change the coefficient ring of a polynomial:

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

### Example 10

Create a polynomial over the coefficient ring `Dom::Float`:

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

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

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

### Example 11

You can overload `poly` by its first operand. For example, create a domain `polyInX` that represents polynomials in `x`:

```domain polyInX new := () -> new(dom, poly(args(), [x])); print := p -> expr(extop(p, 1)); poly := p -> if args(0) = 1 then print(Unquoted, "polyInX::poly called with 1 argument"); extop(p, 1); else print(Unquoted, "polyInX::poly called with more than 1 argument"); poly(extop(p, 1), args(2..args(0))); end; end_domain: p := polyInX(3*x^2-2)```
` `

You can convert the elements of `polyInX` into polynomials of the type `DOM_POLY`. The `poly` function calls the `poly` method of the domain:

`poly(p)`
```polyInX::poly called with 1 argument ```
` `

By reacting to additional arguments, the overloading defined above also allows you to create polynomials over other coefficient rings:

`poly(p, [x], IntMod(2))`
```polyInX::poly called with more than 1 argument ```
` `

### Example 12

Create a polynomial with coefficients containing the identifier `y`. Although you assign the value 1 to `y`, MuPAD does not substitute the new value into the polynomial:

```f := poly(x^2 - y, [x]): y := 1: eval(f)```
` `

You can evaluate the coefficients explicitly. Use the `mapcoeffs` function to apply `eval` to the coefficients of the polynomial:

`f := mapcoeffs(f, eval)`
` `

## Parameters

 `f` `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` greater than 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 `coeffs` A list containing coefficients of a univariate polynomial `x` The indeterminate of a univariate polynomial

## Options

 `Expr` The default ring `Expr` represents arbitrary MuPAD expressions. Mathematically, this ring coincides with `Dom::ExpressionField``()`. However, MuPAD operates differently on the polynomials created over `Expr` and the polynomials created over `Dom::ExpressionField``()`. In particular, MuPAD performs arithmetic operations for polynomials over the ring `Expr` faster. `IntMod` The ring `IntMod``(n)` represents the residue class ring ℤn, using the symmetrical representation. Here, `n` is an integer greater than 1. Mathematically, this ring coincides with `Dom::IntegerMod``(n)`. However, MuPAD operates differently on the polynomials created over `IntMod``(n)` and the polynomials created over `Dom::IntegerMod``(n)`. In particular, MuPAD performs arithmetic operations for polynomials over the ring `IntMod` faster. Also, for polynomials over `IntMod`, `coeff` and similar functions return requested coefficients as integers of the type `DOM_INT`. See Example 6, Example 7, and Example 9.

## Return Values

Polynomial of the domain type `DOM_POLY`. If conversion to a polynomial is not possible, the return value is `FAIL`.

`f`

## Algorithms

To use a domain as a coefficient, the domain must contain the following:

• The entry `"zero"` that provides the neutral element with respect to addition.

• The entry `"one"` that provides the neutral element with respect to multiplication.

• The method `"_plus"` that adds domain elements.

• The method `"_negate"` that returns the inverse with respect to addition.

• The method `"_mult"` that multiplies domain elements.

• The method `"_power"` that computes integer powers of a domain element. Call this method with the domain element as the first argument and an integer as the second argument.

In addition, you must define the following methods. Functions (such as `gcd`, `diff`, `divide`, `norm` and so on) call these methods:

• The method `"gcd"` that returns the greatest common divisor of domain elements.

• The method `"diff"` that differentiates a domain element with respect to a variable.

• The method `"_divide"` that divides two domain elements. It must return `FAIL` if division is not possible.

• The method `"norm"` that computes the norm of a domain element and returns it as a number.

• The method `"convert"` that converts an expression to a domain element. The method must return `FAIL` if such conversion is not possible.

The system calls this method to convert the coefficients of polynomial expressions to coefficients of the specified domain. If this method does not exist, you can specify the coefficients only by using domain elements.

• The method `"expr"` that converts 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, `expr` inserts domain elements into the expression.

You can convert a polynomial over a certain coefficient domain into a polynomial over the same domain, but a different set of indeterminates. This conversion is much more efficient when the domain has the axiom `Ax::indetElements`. MuPAD implicitly assumes that this axiom holds for the domain `IntMod(n)`, but not for `Expr`.

Internally, MuPAD stores polynomials of the type `DOM_POLY` in a sparse representation and uses machine integers for the exponents. This method implies that in a 32-bit environment, the exponent of each variable in each monomial cannot exceed 231 - 1.

#### Mathematical Modeling with Symbolic Math Toolbox

Get examples and videos