## `collect` -- collect coefficients of a polynomial expression

#### Introduction

`collect(`p, x`)` rewrites the polynomial expression `p` as sum(a[i]*x^i, i=0..n), such that x is not a polynomial indeterminate of any coefficient a[i].

`collect(`p, [x1, x2, ...]`)` rewrites the polynomial expression `p` as

    sum(a[i1,i2,..] * x1^i1 * x2^i2 *
        ..),

such that none of the xi is a polynomial indeterminate of any coefficient a[i1, i2, ..].

If a third argument `f` is given, then each coefficient in the return values above is replaced by f(a[i]) or f(a[i1,i2,..]), respectively.

#### Call(s)

`collect(p, x <, f>)`
`collect(p, [x1, x2, ...] <, f>)`

#### Parameters

`p` | - | a polynomial expression
`x, x1, x2, ...` | - | the indeterminates of the polynomial: typically, identifiers or indexed identifiers
`f` | - | a function

#### Returns

a polynomial expression, or `FAIL` if `p` cannot be converted into a polynomial.

#### Further Documentation

Chapter ``Manipulating Expressions'' of the Tutorial.

#### Related Functions

`coeff`, `combine`, `expand`, `factor`, `indets`, `normal`, `poly`, `rectform`, `rewrite`, `simplify`

#### Details

- `collect` groups the terms in `p` with like powers of the given indeterminates together. `collect` returns a modified copy of `p`; the argument itself remains unchanged. See example 1.
- `collect` is merely a shortcut for the functional composition of `expr` and `poly`. It first uses `poly` to convert `p` into a polynomial in the given unknowns. This has the effect that the terms are collected. Then the result is again converted into a polynomial expression via `expr`. See the help page of `poly` for more information and examples.
- The indeterminates need not be identifiers or indexed identifiers. Any expression can be used as an indeterminate as long as it is neither rational nor constant. E.g., the expressions `sin(x)`, `f(x)`, or `y^(1/3)` are accepted as indeterminates, but the constant expressions `sin(1)` and `f(1)` are not allowed. More precisely, `x` is accepted as polynomial indeterminate if and only if the call `indets(x, PolyExpr)` returns `{x}` . See the help page of `indets` for more information, and also example 2.
- `collect` does not recursively collect the operands of non-polynomial subexpressions of `p`. See example 2.
- The terms in the result of `collect` are usually not ordered; use `poly` instead to achieve this.

  Note also that the ``constant'' terms corresponding to a[0] or a[0,0,..] are not always grouped together.

  See example 4.

- `collect` returns `FAIL` if `p` cannot be converted into a polynomial; the help of `poly` has more information when this is the case. See example 3.

#### Example 1

We define a polynomial expression `p` and collect terms with like powers of `x` and `y`:

    >> p := x*y + z*x*y + y*x^2 - z*y*x^2 + x + z*x;
       collect(p, [x, y])

                                                2      2
                       x + x y + x z + x y z + x  y - x  y z

                                                 2
                      x (z + 1) + x y (z + 1) + x  y (1 - z)

The expression `p` itself remains unchanged:

    >> p

                                                2      2
                       x + x y + x z + x y z + x  y - x  y z

Now we collect terms with like powers of `x`:

    >> collect(p, [x])

                                               2
                        x (y + z + y z + 1) + x  (y - y z)

If there is only one indeterminate, then the square brackets may be omitted:

    >> collect(p, x)

                                               2
                        x (y + z + y z + 1) + x  (y - y z)

By passing the third argument `factor`, we cause every coefficient to be factored:

    >> collect(p, x, factor)

                                              2
                         x (y + 1) (z + 1) - x  y (z - 1)

#### Example 2

`collect` has the same behavior as `poly` with respect to non-polynomial subexpressions. Such a subexpression remains unchanged, even if it contains one of the given indeterminates. In particular, `collect` is not applied recursively to the operands of a non-polynomial subexpression:

    >> collect(sin((x + 1)^2)*(x + 1) + 5*sin((x + 1)^2) + x, x)

                                   2                  2
                      6 sin((x + 1) ) + x (sin((x + 1) ) + 1)

However, a non-polynomial subexpression may be passed to `collect` as indeterminate, provided that it is accepted as indeterminate by `poly`:

    >> collect(sin((x + 1)^2)*(x + 1) + 5*sin((x + 1)^2) + x,
               sin((x + 1)^2))

                                                    2
                             x + (x + 6) sin((x + 1) )

An error occurs if one of the indeterminates is illegal:

    >> collect(1 + I*(x + I), I)

          Error: Illegal indeterminate [poly];
          during evaluation of 'collect'

In this example, you can use `rectform` to achieve the desired result:

    >> rectform(1 + I*(x + I))

                                 - Im(x) + I Re(x)

#### Example 3

`collect` returns `FAIL` if the input cannot be converted into a polynomial:

    >> collect(1/x, x)

                                       FAIL

#### Example 4

The terms in the result of `collect` are usually not ordered by increasing or decreasing degree:

    >> collect(1 + x^2 + x, [x])

                                         2
                                    x + x  + 1

Use `poly` to achieve this:

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

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

Also, constant terms are not necessarily grouped together:

    >> collect(sin(1) + (x + 1)^2, [x])

                                               2
                               2 x + sin(1) + x  + 1

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

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

#### Changes

- no changes

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