## `mapcoeffs` -- apply a function to the coefficients of a polynomial

#### Introduction

`mapcoeffs(`p, F, a1, a2...`)` applies the function `F` to the polynomial `p` by replacing each coefficient `c` in `p` by `F(c, a1, a2...)`.

#### Call(s)

`mapcoeffs(p, F <, a1, a2...>)`
`mapcoeffs(f, <vars, > F <, a1, a2...>)`

#### Parameters

`p` | - | a polynomial of type `DOM_POLY`
`F` | - | a procedure
`a1, a2...` | - | additional parameters for the function `F`
`f` | - | a polynomial expression
`vars` | - | a list of indeterminates of the polynomial: typically, identifiers or indexed identifiers

#### Returns

a polynomial of type `DOM_POLY`, or a polynomial expression, or `FAIL`.

### Overloadable:

`p`, `f`

#### Related Functions

`coeff`, `degree`, `degreevec`, `lcoeff`, `ldegree`, `lterm`, `map`, `nterms`, `nthcoeff`, `nthmonomial`, `nthterm`, `poly`, `tcoeff`

#### Details

- For a polynomial `p` of type `DOM_POLY` generated by `poly`, the function `F` must accept arguments from the coefficient ring of `p` and must produce corresponding results.
- A polynomial expression `f` is first converted to a polynomial with the variables given by `vars`. If no variables are given, they are searched for in `f`. See `poly` about details of the conversion. `FAIL` is returned if `f` cannot be converted to a polynomial. After applying the function `F`, the result is converted to an expression.
- `mapcoeffs` evaluates its arguments. Note, however, that polynomials of type `DOM_POLY` do not evaluate their coefficients for efficiency reasons. Cf. example 4.
- `mapcoeffs` is a function of the system kernel.

#### Example 1

The function `sin` is mapped to the coefficients of a polynomial expression in the indeterminates `x` and `y`:

    >> mapcoeffs(3*x^3 + x^2*y^2 + 2, sin)

                                   3           2  2
                         sin(2) + x  sin(3) + x  y  sin(1)

The following call makes `mapcoeffs` regard this expression as a polynomial in `x`. Consequently, `y` is regarded as a parameter that becomes part of the coefficients:

    >> mapcoeffs(3*x^3 + x^2*y^2 + 2, [x], sin)

                                    3           2      2
                          sin(2) + x  sin(3) + x  sin(y )

The system function `_plus` adds its arguments. In the following call, it is used to add 2 to all coefficients by providing this shift as an additional argument:

    >> mapcoeffs(c1*x^3 + c2*x^2*y^2 + c3, [x, y], _plus, 2)

                             3             2  2
                       c3 + x  (c1 + 2) + x  y  (c2 + 2) + 2

#### Example 2

The function `sin` is mapped to the coefficients of a polynomial in the indeterminates `x` and `y`:

    >> mapcoeffs(poly(3*x^3 + x^2*y^2 + 2, [x, y]), sin)

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

In the following call, the polynomial has the indeterminate `x`. Consequently, `y` is regarded as a parameter that becomes part of the coefficients:

    >> mapcoeffs(poly(3*x^3 + x^2*y^2 + 2, [x]), sin)

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

A user-defined function is mapped to a polynomial:

    >> F := (c, a1, a2) -> exp(c + a1 + a2):
       mapcoeffs(poly(x^3 + c*x, [x]), F, a1, a2)

                                       3
                poly(exp(a1 + a2 + 1) x  + exp(c + a1 + a2) x, [x])

    >> delete F:

#### Example 3

We consider a polynomial over the integers modulo 7:

    >> p := poly(x^3 + 2*x*y, [x, y], Dom::IntegerMod(7)):

A function to be applied to the coefficients must produce values in the coefficient ring of the polynomial:

    >> mapcoeffs(p, c -> c^2)

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

The following call maps a function which converts its argument to an integer modulo 3. Such a return value is not a valid coefficient of `p`:

    >> mapcoeffs(p, c -> Dom::IntegerMod(3)(expr(c)))

                                       FAIL

    >> delete p:

#### Example 4

Note that polynomials of type `DOM_POLY` do not evaluate their arguments:

    >> delete a, x: p := poly(a*x, [x]): a := PI: p

                                  poly(a x, [x])

Evaluation can be enforced by the function `eval`:

    >> mapcoeffs(p, eval)

                                  poly(PI x, [x])

We map the sine function to the coefficients of `p`. The polynomial does not evaluate its coefficient `sin(a)` to `0`:

    >> mapcoeffs(p, sin)

                                poly(sin(a) x, [x])

The composition of `sin` and `eval` is mapped to the coefficients of the polynomial:

    >> mapcoeffs(p, eval@sin)

                                   poly(0, [x])

    >> delete p, a:

#### Changes

- no changes

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