This is maxima.info, produced by makeinfo version 4.7 from maxima.texi.

   This is a Texinfo Maxima Manual

   Copyright 1994,2001 William F. Schelter

START-INFO-DIR-ENTRY
* Maxima: (maxima).     A computer algebra system.
END-INFO-DIR-ENTRY


File: maxima.info,  Node: Functions and Variables for atensor,  Prev: Introduction to atensor,  Up: atensor

29.2 Functions and Variables for atensor
========================================

 -- Function: init_atensor (<alg_type>, <opt_dims>)
 -- Function: init_atensor (<alg_type>)
     Initializes the `atensor' package with the specified algebra type.
     <alg_type> can be one of the following:

     `universal': The universal algebra has no commutation rules.

     `grassmann': The Grassman algebra is defined by the commutation
     relation `u.v+v.u=0'.

     `clifford': The Clifford algebra is defined by the commutation
     relation `u.v+v.u=-2*sf(u,v)' where `sf' is a symmetric
     scalar-valued function. For this algebra, <opt_dims> can be up to
     three nonnegative integers, representing the number of positive,
     degenerate, and negative dimensions of the algebra, respectively.
     If any <opt_dims> values are supplied, `atensor' will configure the
     values of `adim' and `aform' appropriately. Otherwise, `adim' will
     default to 0 and `aform' will not be defined.

     `symmetric': The symmetric algebra is defined by the commutation
     relation `u.v-v.u=0'.

     `symplectic': The symplectic algebra is defined by the commutation
     relation `u.v-v.u=2*af(u,v)' where `af' is an antisymmetric
     scalar-valued function. For the symplectic algebra, <opt_dims> can
     be up to two nonnegative integers, representing the nondegenerate
     and degenerate dimensions, respectively. If any <opt_dims> values
     are supplied, `atensor' will configure the values of `adim' and
     `aform' appropriately. Otherwise, `adim' will default to 0 and
     `aform' will not be defined.

     `lie_envelop': The algebra of the Lie envelope is defined by the
     commutation relation `u.v-v.u=2*av(u,v)' where `av' is an
     antisymmetric function.

     The `init_atensor' function also recognizes several predefined
     algebra types:

     `complex' implements the algebra of complex numbers as the
     Clifford algebra Cl(0,1). The call `init_atensor(complex)' is
     equivalent to `init_atensor(clifford,0,0,1)'.

     `quaternion' implements the algebra of quaternions. The call
     `init_atensor(quaternion)' is equivalent to
     `init_atensor(clifford,0,0,2)'.

     `pauli' implements the algebra of Pauli-spinors as the
     Clifford-algebra Cl(3,0). A call to `init_atensor(pauli)' is
     equivalent to `init_atensor(clifford,3)'.

     `dirac' implements the algebra of Dirac-spinors as the
     Clifford-algebra Cl(3,1). A call to `init_atensor(dirac)' is
     equivalent to `init_atensor(clifford,3,0,1)'.


 -- Function: atensimp (<expr>)
     Simplifies an algebraic tensor expression <expr> according to the
     rules configured by a call to `init_atensor'. Simplification
     includes recursive application of commutation relations and
     resolving calls to `sf', `af', and `av' where applicable. A
     safeguard is used to ensure that the function always terminates,
     even for complex expressions.


 -- Function: alg_type
     The algebra type. Valid values are `universal', `grassmann',
     `clifford', `symmetric', `symplectic' and `lie_envelop'.


 -- Variable: adim
     Default value: 0

     The dimensionality of the algebra. `atensor' uses the value of
     `adim' to determine if an indexed object is a valid base vector.
     See `abasep'.


 -- Variable: aform
     Default value: `ident(3)'

     Default values for the bilinear forms `sf', `af', and `av'. The
     default is the identity matrix `ident(3)'.


 -- Variable: asymbol
     Default value: `v'

     The symbol for base vectors.


 -- Function: sf (<u>, <v>)
     A symmetric scalar function that is used in commutation relations.
     The default implementation checks if both arguments are base
     vectors using `abasep' and if that is the case, substitutes the
     corresponding value from the matrix `aform'.


 -- Function: af (<u>, <v>)
     An antisymmetric scalar function that is used in commutation
     relations.  The default implementation checks if both arguments
     are base vectors using `abasep' and if that is the case,
     substitutes the corresponding value from the matrix `aform'.


 -- Function: av (<u>, <v>)
     An antisymmetric function that is used in commutation relations.
     The default implementation checks if both arguments are base
     vectors using `abasep' and if that is the case, substitutes the
     corresponding value from the matrix `aform'.

     For instance:

          (%i1) load(atensor);
          (%o1)       /share/tensor/atensor.mac
          (%i2) adim:3;
          (%o2)                                  3
          (%i3) aform:matrix([0,3,-2],[-3,0,1],[2,-1,0]);
                                         [  0    3   - 2 ]
                                         [               ]
          (%o3)                          [ - 3   0    1  ]
                                         [               ]
                                         [  2   - 1   0  ]
          (%i4) asymbol:x;
          (%o4)                                  x
          (%i5) av(x[1],x[2]);
          (%o5)                                 x
                                                 3


 -- Function: abasep (<v>)
     Checks if its argument is an `atensor' base vector. That is, if it
     is an indexed symbol, with the symbol being the same as the value
     of `asymbol', and the index having a numeric value between 1 and
     `adim'.



File: maxima.info,  Node: Series,  Next: Number Theory,  Prev: atensor,  Up: Top

30 Series
*********

* Menu:

* Introduction to Series::
* Functions and Variables for Series::


File: maxima.info,  Node: Introduction to Series,  Next: Functions and Variables for Series,  Prev: Series,  Up: Series

30.1 Introduction to Series
===========================

Maxima contains functions `taylor' and `powerseries' for finding the
series of differentiable functions.   It also has tools such as `nusum'
capable of finding the closed form of some series.   Operations such as
addition and multiplication work as usual on series. This section
presents the global variables which control the expansion.


File: maxima.info,  Node: Functions and Variables for Series,  Prev: Introduction to Series,  Up: Series

30.2 Functions and Variables for Series
=======================================

 -- Option variable: cauchysum
     Default value: `false'

     When multiplying together sums with `inf' as their upper limit, if
     `sumexpand' is `true' and `cauchysum' is `true' then the Cauchy
     product will be used rather than the usual product.  In the Cauchy
     product the index of the inner summation is a function of the
     index of the outer one rather than varying independently.

     Example:

          (%i1) sumexpand: false$
          (%i2) cauchysum: false$
          (%i3) s: sum (f(i), i, 0, inf) * sum (g(j), j, 0, inf);
                                inf         inf
                                ====        ====
                                \           \
          (%o3)                ( >    f(i))  >    g(j)
                                /           /
                                ====        ====
                                i = 0       j = 0
          (%i4) sumexpand: true$
          (%i5) cauchysum: true$
          (%i6) ''s;
                           inf     i1
                           ====   ====
                           \      \
          (%o6)             >      >     g(i1 - i2) f(i2)
                           /      /
                           ====   ====
                           i1 = 0 i2 = 0


 -- Function: deftaylor (<f_1>(<x_1>), <expr_1>, ..., <f_n>(<x_n>),
          <expr_n>)
     For each function <f_i> of one variable <x_i>, `deftaylor' defines
     <expr_i> as the Taylor series about zero.  <expr_i> is typically a
     polynomial in <x_i> or a summation; more general expressions are
     accepted by `deftaylor' without complaint.

     `powerseries (<f_i>(<x_i>), <x_i>, 0)' returns the series defined
     by `deftaylor'.

     `deftaylor' returns a list of the functions <f_1>, ..., <f_n>.
     `deftaylor' evaluates its arguments.

     Example:

          (%i1) deftaylor (f(x), x^2 + sum(x^i/(2^i*i!^2), i, 4, inf));
          (%o1)                          [f]
          (%i2) powerseries (f(x), x, 0);
                                inf
                                ====      i1
                                \        x         2
          (%o2)                  >     -------- + x
                                /       i1    2
                                ====   2   i1!
                                i1 = 4
          (%i3) taylor (exp (sqrt (f(x))), x, 0, 4);
                                2         3          4
                               x    3073 x    12817 x
          (%o3)/T/     1 + x + -- + ------- + -------- + . . .
                               2     18432     307200


 -- Option variable: maxtayorder
     Default value: `true'

     When `maxtayorder' is `true', then during algebraic manipulation
     of (truncated) Taylor series, `taylor' tries to retain as many
     terms as are known to be correct.


 -- Function: niceindices (<expr>)
     Renames the indices of sums and products in <expr>.  `niceindices'
     attempts to rename each index to the value of `niceindicespref[1]',
     unless that name appears in the summand or multiplicand, in which
     case `niceindices' tries the succeeding elements of
     `niceindicespref' in turn, until an unused variable is found.  If
     the entire list is exhausted, additional indices are constructed
     by appending integers to the value of `niceindicespref[1]', e.g.,
     `i0', `i1', `i2', ....

     `niceindices' returns an expression.  `niceindices' evaluates its
     argument.

     Example:

          (%i1) niceindicespref;
          (%o1)                  [i, j, k, l, m, n]
          (%i2) product (sum (f (foo + i*j*bar), foo, 1, inf), bar, 1, inf);
                           inf    inf
                          /===\   ====
                           ! !    \
          (%o2)            ! !     >      f(bar i j + foo)
                           ! !    /
                          bar = 1 ====
                                  foo = 1
          (%i3) niceindices (%);
                               inf  inf
                              /===\ ====
                               ! !  \
          (%o3)                ! !   >    f(i j l + k)
                               ! !  /
                              l = 1 ====
                                    k = 1


 -- Option variable: niceindicespref
     Default value: `[i, j, k, l, m, n]'

     `niceindicespref' is the list from which `niceindices' takes the
     names of indices for sums and products.

     The elements of `niceindicespref' are typically names of variables,
     although that is not enforced by `niceindices'.

     Example:

          (%i1) niceindicespref: [p, q, r, s, t, u]$
          (%i2) product (sum (f (foo + i*j*bar), foo, 1, inf), bar, 1, inf);
                           inf    inf
                          /===\   ====
                           ! !    \
          (%o2)            ! !     >      f(bar i j + foo)
                           ! !    /
                          bar = 1 ====
                                  foo = 1
          (%i3) niceindices (%);
                               inf  inf
                              /===\ ====
                               ! !  \
          (%o3)                ! !   >    f(i j q + p)
                               ! !  /
                              q = 1 ====
                                    p = 1


 -- Function: nusum (<expr>, <x>, <i_0>, <i_1>)
     Carries out indefinite hypergeometric summation of <expr> with
     respect to <x> using a decision procedure due to R.W. Gosper.
     <expr> and the result must be expressible as products of integer
     powers, factorials, binomials, and rational functions.

     The terms "definite" and "indefinite summation" are used
     analogously to "definite" and "indefinite integration".  To sum
     indefinitely means to give a symbolic result for the sum over
     intervals of variable length, not just e.g. 0 to inf.  Thus, since
     there is no formula for the general partial sum of the binomial
     series, `nusum' can't do it.

     `nusum' and `unsum' know a little about sums and differences of
     finite products.  See also `unsum'.

     Examples:

          (%i1) nusum (n*n!, n, 0, n);

          Dependent equations eliminated:  (1)
          (%o1)                     (n + 1)! - 1
          (%i2) nusum (n^4*4^n/binomial(2*n,n), n, 0, n);
                               4        3       2              n
                2 (n + 1) (63 n  + 112 n  + 18 n  - 22 n + 3) 4      2
          (%o2) ------------------------------------------------ - ------
                              693 binomial(2 n, n)                 3 11 7
          (%i3) unsum (%, n);
                                        4  n
                                       n  4
          (%o3)                   ----------------
                                  binomial(2 n, n)
          (%i4) unsum (prod (i^2, i, 1, n), n);
                              n - 1
                              /===\
                               ! !   2
          (%o4)              ( ! !  i ) (n - 1) (n + 1)
                               ! !
                              i = 1
          (%i5) nusum (%, n, 1, n);

          Dependent equations eliminated:  (2 3)
                                      n
                                    /===\
                                     ! !   2
          (%o5)                      ! !  i  - 1
                                     ! !
                                    i = 1


 -- Function: pade (<taylor_series>, <numer_deg_bound>,
          <denom_deg_bound>)
     Returns a list of all rational functions which have the given
     Taylor series expansion where the sum of the degrees of the
     numerator and the denominator is less than or equal to the
     truncation level of the power series, i.e.  are "best"
     approximants, and which additionally satisfy the specified degree
     bounds.

     <taylor_series> is a univariate Taylor series.  <numer_deg_bound>
     and <denom_deg_bound> are positive integers specifying degree
     bounds on the numerator and denominator.

     <taylor_series> can also be a Laurent series, and the degree
     bounds can be `inf' which causes all rational functions whose total
     degree is less than or equal to the length of the power series to
     be returned.  Total degree is defined as `<numer_deg_bound> +
     <denom_deg_bound>'.  Length of a power series is defined as
     `"truncation level" + 1 - min(0, "order of series")'.

          (%i1) taylor (1 + x + x^2 + x^3, x, 0, 3);
                                        2    3
          (%o1)/T/             1 + x + x  + x  + . . .
          (%i2) pade (%, 1, 1);
                                           1
          (%o2)                       [- -----]
                                         x - 1
          (%i3) t: taylor(-(83787*x^10 - 45552*x^9 - 187296*x^8
                             + 387072*x^7 + 86016*x^6 - 1507328*x^5
                             + 1966080*x^4 + 4194304*x^3 - 25165824*x^2
                             + 67108864*x - 134217728)
                 /134217728, x, 0, 10);
                              2    3       4       5       6        7
                       x   3 x    x    15 x    23 x    21 x    189 x
          (%o3)/T/ 1 - - + ---- - -- - ----- + ----- - ----- - ------
                       2    16    32   1024    2048    32768   65536

                                            8         9          10
                                      5853 x    2847 x    83787 x
                                    + ------- + ------- - --------- + . . .
                                      4194304   8388608   134217728
          (%i4) pade (t, 4, 4);
          (%o4)                          []

     There is no rational function of degree 4 numerator/denominator,
     with this power series expansion.  You must in general have degree
     of the numerator and degree of the denominator adding up to at
     least the degree of the power series, in order to have enough
     unknown coefficients to solve.

          (%i5) pade (t, 5, 5);
                               5                4                 3
          (%o5) [- (520256329 x  - 96719020632 x  - 489651410240 x

                            2
           - 1619100813312 x  - 2176885157888 x - 2386516803584)

                         5                 4                  3
          /(47041365435 x  + 381702613848 x  + 1360678489152 x

                            2
           + 2856700692480 x  + 3370143559680 x + 2386516803584)]


 -- Option variable: powerdisp
     Default value: `false'

     When `powerdisp' is `true', a sum is displayed with its terms in
     order of increasing power.  Thus a polynomial is displayed as a
     truncated power series, with the constant term first and the
     highest power last.

     By default, terms of a sum are displayed in order of decreasing
     power.


 -- Function: powerseries (<expr>, <x>, <a>)
     Returns the general form of the power series expansion for <expr>
     in the variable <x> about the point <a> (which may be `inf' for
     infinity).

     If `powerseries' is unable to expand <expr>, `taylor' may give the
     first several terms of the series.

     When `verbose' is `true', `powerseries' prints progress messages.

          (%i1) verbose: true$
          (%i2) powerseries (log(sin(x)/x), x, 0);
          can't expand
                                           log(sin(x))
          so we'll try again after applying the rule:
                                                  d
                                                / -- (sin(x))
                                                [ dx
                                  log(sin(x)) = i ----------- dx
                                                ]   sin(x)
                                                /
          in the first simplification we have returned:
                                       /
                                       [
                                       i cot(x) dx - log(x)
                                       ]
                                       /
                              inf
                              ====        i1  2 i1             2 i1
                              \      (- 1)   2     bern(2 i1) x
                               >     ------------------------------
                              /                i1 (2 i1)!
                              ====
                              i1 = 1
          (%o2)                -------------------------------------
                                                2


 -- Option variable: psexpand
     Default value: `false'

     When `psexpand' is `true', an extended rational function
     expression is displayed fully expanded.  The switch `ratexpand'
     has the same effect.

     When `psexpand' is `false', a multivariate expression is displayed
     just as in the rational function package.

     When `psexpand' is  `multi', then terms with the same total degree
     in the variables are grouped together.


 -- Function: revert (<expr>, <x>)
 -- Function: revert2 (<expr>, <x>, <n>)
     These functions return the reversion of <expr>, a Taylor series
     about zero in the variable <x>.  `revert' returns a polynomial of
     degree equal to the highest power in <expr>.  `revert2' returns a
     polynomial of degree <n>, which may be greater than, equal to, or
     less than the degree of <expr>.

     `load ("revert")' loads these functions.

     Examples:

          (%i1) load ("revert")$
          (%i2) t: taylor (exp(x) - 1, x, 0, 6);
                             2    3    4    5     6
                            x    x    x    x     x
          (%o2)/T/      x + -- + -- + -- + --- + --- + . . .
                            2    6    24   120   720
          (%i3) revert (t, x);
                         6       5       4       3       2
                     10 x  - 12 x  + 15 x  - 20 x  + 30 x  - 60 x
          (%o3)/R/ - --------------------------------------------
                                          60
          (%i4) ratexpand (%);
                               6    5    4    3    2
                              x    x    x    x    x
          (%o4)             - -- + -- - -- + -- - -- + x
                              6    5    4    3    2
          (%i5) taylor (log(x+1), x, 0, 6);
                              2    3    4    5    6
                             x    x    x    x    x
          (%o5)/T/       x - -- + -- - -- + -- - -- + . . .
                             2    3    4    5    6
          (%i6) ratsimp (revert (t, x) - taylor (log(x+1), x, 0, 6));
          (%o6)                           0
          (%i7) revert2 (t, x, 4);
                                    4    3    2
                                   x    x    x
          (%o7)                  - -- + -- - -- + x
                                   4    3    2


 -- Function: taylor (<expr>, <x>, <a>, <n>)
 -- Function: taylor (<expr>, [<x_1>, <x_2>, ...], <a>, <n>)
 -- Function: taylor (<expr>, [<x>, <a>, <n>, 'asymp])
 -- Function: taylor (<expr>, [<x_1>, <x_2>, ...], [<a_1>, <a_2>, ...],
          [<n_1>, <n_2>, ...])
 -- Function: taylor (<expr>, [<x_1>, <a_1>, <n_1>], [<x_2>, <a_2>,
          <n_2>], ...)
     `taylor (<expr>, <x>, <a>, <n>)' expands the expression <expr> in
     a truncated Taylor or Laurent series in the variable <x> around
     the point <a>, containing terms through `(<x> - <a>)^<n>'.

     If <expr> is of the form `<f>(<x>)/<g>(<x>)' and `<g>(<x>)' has no
     terms up to degree <n> then `taylor' attempts to expand `<g>(<x>)'
     up to degree `2 <n>'.  If there are still no nonzero terms,
     `taylor' doubles the degree of the expansion of `<g>(<x>)' so long
     as the degree of the expansion is less than or equal to `<n>
     2^taylordepth'.

     `taylor (<expr>, [<x_1>, <x_2>, ...], <a>, <n>)' returns a
     truncated power series of degree <n> in all variables <x_1>,
     <x_2>, ...  about the point `(<a>, <a>, ...)'.

     `taylor (<expr>, [<x_1>, <a_1>, <n_1>], [<x_2>, <a_2>, <n_2>],
     ...)'  returns a truncated power series in the variables <x_1>,
     <x_2>, ...  about the point `(<a_1>, <a_2>, ...)', truncated at
     <n_1>, <n_2>, ....

     `taylor (<expr>, [<x_1>, <x_2>, ...], [<a_1>, <a_2>, ...], [<n_1>,
     <n_2>, ...])' returns a truncated power series in the variables
     <x_1>, <x_2>, ...  about the point `(<a_1>, <a_2>, ...)',
     truncated at <n_1>, <n_2>, ....

     `taylor (<expr>, [<x>, <a>, <n>, 'asymp])' returns an expansion of
     <expr> in negative powers of `<x> - <a>'.  The highest order term
     is `(<x> - <a>)^<-n>'.

     When `maxtayorder' is `true', then during algebraic manipulation
     of (truncated) Taylor series, `taylor' tries to retain as many
     terms as are known to be correct.

     When `psexpand' is `true', an extended rational function
     expression is displayed fully expanded.  The switch `ratexpand'
     has the same effect.  When `psexpand' is `false', a multivariate
     expression is displayed just as in the rational function package.
     When `psexpand' is  `multi', then terms with the same total degree
     in the variables are grouped together.

     See also the `taylor_logexpand' switch for controlling expansion.

     Examples:

          (%i1) taylor (sqrt (sin(x) + a*x + 1), x, 0, 3);
                                     2             2
                       (a + 1) x   (a  + 2 a + 1) x
          (%o1)/T/ 1 + --------- - -----------------
                           2               8

                                             3      2             3
                                         (3 a  + 9 a  + 9 a - 1) x
                                       + -------------------------- + . . .
                                                     48
          (%i2) %^2;
                                              3
                                             x
          (%o2)/T/           1 + (a + 1) x - -- + . . .
                                             6
          (%i3) taylor (sqrt (x + 1), x, 0, 5);
                                 2    3      4      5
                            x   x    x    5 x    7 x
          (%o3)/T/      1 + - - -- + -- - ---- + ---- + . . .
                            2   8    16   128    256
          (%i4) %^2;
          (%o4)/T/                  1 + x + . . .
          (%i5) product ((1 + x^i)^2.5, i, 1, inf)/(1 + x^2);
                                   inf
                                  /===\
                                   ! !    i     2.5
                                   ! !  (x  + 1)
                                   ! !
                                  i = 1
          (%o5)                   -----------------
                                        2
                                       x  + 1
          (%i6) ev (taylor(%, x,  0, 3), keepfloat);
                                         2           3
          (%o6)/T/    1 + 2.5 x + 3.375 x  + 6.5625 x  + . . .
          (%i7) taylor (1/log (x + 1), x, 0, 3);
                                         2       3
                           1   1   x    x    19 x
          (%o7)/T/         - + - - -- + -- - ----- + . . .
                           x   2   12   24    720
          (%i8) taylor (cos(x) - sec(x), x, 0, 5);
                                          4
                                     2   x
          (%o8)/T/                - x  - -- + . . .
                                         6
          (%i9) taylor ((cos(x) - sec(x))^3, x, 0, 5);
          (%o9)/T/                    0 + . . .
          (%i10) taylor (1/(cos(x) - sec(x))^3, x, 0, 5);
                                                         2          4
                      1     1       11      347    6767 x    15377 x
          (%o10)/T/ - -- + ---- + ------ - ----- - ------- - --------
                       6      4        2   15120   604800    7983360
                      x    2 x    120 x

                                                                    + . . .
          (%i11) taylor (sqrt (1 - k^2*sin(x)^2), x, 0, 6);
                         2  2       4      2   4
                        k  x    (3 k  - 4 k ) x
          (%o11)/T/ 1 - ----- - ----------------
                          2            24

                                              6       4       2   6
                                         (45 k  - 60 k  + 16 k ) x
                                       - -------------------------- + . . .
                                                    720
          (%i12) taylor ((x + 1)^n, x, 0, 4);
                                2       2     3      2         3
                              (n  - n) x    (n  - 3 n  + 2 n) x
          (%o12)/T/ 1 + n x + ----------- + --------------------
                                   2                 6

                                         4      3       2         4
                                       (n  - 6 n  + 11 n  - 6 n) x
                                     + ---------------------------- + . . .
                                                    24
          (%i13) taylor (sin (y + x), x, 0, 3, y, 0, 3);
                         3                 2
                        y                 y
          (%o13)/T/ y - -- + . . . + (1 - -- + . . .) x
                        6                 2

                              3                       2
                         y   y            2      1   y            3
                    + (- - + -- + . . .) x  + (- - + -- + . . .) x  + . . .
                         2   12                  6   12
          (%i14) taylor (sin (y + x), [x, y], 0, 3);
                               3        2      2      3
                              x  + 3 y x  + 3 y  x + y
          (%o14)/T/   y + x - ------------------------- + . . .
                                          6
          (%i15) taylor (1/sin (y + x), x, 0, 3, y, 0, 3);
                    1   y              1    1               1            2
          (%o15)/T/ - + - + . . . + (- -- + - + . . .) x + (-- + . . .) x
                    y   6               2   6                3
                                       y                    y

                                                     1            3
                                                + (- -- + . . .) x  + . . .
                                                      4
                                                     y
          (%i16) taylor (1/sin (y + x), [x, y], 0, 3);
                                       3         2       2        3
                      1     x + y   7 x  + 21 y x  + 21 y  x + 7 y
          (%o16)/T/ ----- + ----- + ------------------------------- + . . .
                    x + y     6                   360


 -- Option variable: taylordepth
     Default value: 3

     If there are still no nonzero terms, `taylor' doubles the degree
     of the expansion of `<g>(<x>)' so long as the degree of the
     expansion is less than or equal to `<n> 2^taylordepth'.


 -- Function: taylorinfo (<expr>)
     Returns information about the Taylor series <expr>.  The return
     value is a list of lists.  Each list comprises the name of a
     variable, the point of expansion, and the degree of the expansion.

     `taylorinfo' returns `false' if <expr> is not a Taylor series.

     Example:

          (%i1) taylor ((1 - y^2)/(1 - x), x, 0, 3, [y, a, inf]);
                            2                       2
          (%o1)/T/ - (y - a)  - 2 a (y - a) + (1 - a )

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

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

                   2                        2   3
           + (1 - a  - 2 a (y - a) - (y - a) ) x  + . . .
          (%i2) taylorinfo(%);
          (%o2)               [[y, a, inf], [x, 0, 3]]


 -- Function: taylorp (<expr>)
     Returns `true' if <expr> is a Taylor series, and `false' otherwise.


 -- Option variable: taylor_logexpand
     Default value: `true'

     `taylor_logexpand' controls expansions of logarithms in `taylor'
     series.

     When `taylor_logexpand' is `true', all logarithms are expanded
     fully so that zero-recognition problems involving logarithmic
     identities do not disturb the expansion process.  However, this
     scheme is not always mathematically correct since it ignores
     branch information.

     When `taylor_logexpand' is set to `false', then the only expansion
     of logarithms that occur is that necessary to obtain a formal
     power series.


 -- Option variable: taylor_order_coefficients
     Default value: `true'

     `taylor_order_coefficients' controls the ordering of coefficients
     in a Taylor series.

     When `taylor_order_coefficients' is `true', coefficients of taylor
     series are ordered canonically.


 -- Function: taylor_simplifier (<expr>)
     Simplifies coefficients of the power series <expr>.  `taylor'
     calls this function.


 -- Option variable: taylor_truncate_polynomials
     Default value: `true'

     When `taylor_truncate_polynomials' is `true', polynomials are
     truncated based upon the input truncation levels.

     Otherwise, polynomials input to `taylor' are considered to have
     infinite precison.


 -- Function: taytorat (<expr>)
     Converts <expr> from `taylor' form to canonical rational
     expression (CRE) form.  The effect is the same as `rat (ratdisrep
     (<expr>))', but faster.


 -- Function: trunc (<expr>)
     Annotates the internal representation of the general expression
     <expr> so that it is displayed as if its sums were truncated
     Taylor series.  <expr> is not otherwise modified.

     Example:

          (%i1) expr: x^2 + x + 1;
                                      2
          (%o1)                      x  + x + 1
          (%i2) trunc (expr);
                                          2
          (%o2)                  1 + x + x  + . . .
          (%i3) is (expr = trunc (expr));
          (%o3)                         true


 -- Function: unsum (<f>, <n>)
     Returns the first backward difference `<f>(<n>) - <f>(<n> - 1)'.
     Thus `unsum' in a sense is the inverse of `sum'.

     See also `nusum'.

     Examples:

          (%i1) g(p) := p*4^n/binomial(2*n,n);
                                               n
                                            p 4
          (%o1)               g(p) := ----------------
                                      binomial(2 n, n)
          (%i2) g(n^4);
                                        4  n
                                       n  4
          (%o2)                   ----------------
                                  binomial(2 n, n)
          (%i3) nusum (%, n, 0, n);
                               4        3       2              n
                2 (n + 1) (63 n  + 112 n  + 18 n  - 22 n + 3) 4      2
          (%o3) ------------------------------------------------ - ------
                              693 binomial(2 n, n)                 3 11 7
          (%i4) unsum (%, n);
                                        4  n
                                       n  4
          (%o4)                   ----------------
                                  binomial(2 n, n)


 -- Option variable: verbose
     Default value: `false'

     When `verbose' is `true', `powerseries' prints progress messages.



File: maxima.info,  Node: Number Theory,  Next: Symmetries,  Prev: Series,  Up: Top

31 Number Theory
****************

* Menu:

* Functions and Variables for Number Theory::


File: maxima.info,  Node: Functions and Variables for Number Theory,  Prev: Number Theory,  Up: Number Theory

31.1 Functions and Variables for Number Theory
==============================================

 -- Function: bern (<n>)
     Returns the <n>'th Bernoulli number for integer <n>.  Bernoulli
     numbers equal to zero are suppressed if `zerobern' is `false'.

     See also `burn'.

          (%i1) zerobern: true$
          (%i2) map (bern, [0, 1, 2, 3, 4, 5, 6, 7, 8]);
                            1  1       1      1        1
          (%o2)       [1, - -, -, 0, - --, 0, --, 0, - --]
                            2  6       30     42       30
          (%i3) zerobern: false$
          (%i4) map (bern, [0, 1, 2, 3, 4, 5, 6, 7, 8]);
                      1  1    1   5     691   7    3617  43867
          (%o4) [1, - -, -, - --, --, - ----, -, - ----, -----]
                      2  6    30  66    2730  6    510    798


 -- Function: bernpoly (<x>, <n>)
     Returns the <n>'th Bernoulli polynomial in the variable <x>.


 -- Function: bfzeta (<s>, <n>)
     Returns the Riemann zeta function for the argument <s>.  The
     return value is a big float (bfloat); <n> is the number of digits
     in the return value.


 -- Function: bfhzeta (<s>, <h>, <n>)
     Returns the Hurwitz zeta function for the arguments <s> and <h>.
     The return value is a big float (bfloat); <n> is the number of
     digits in the return value.

     The Hurwitz zeta function is defined as

          sum ((k+h)^-s, k, 0, inf)

     `load ("bffac")' loads this function.


 -- Function: binomial (<x>, <y>)
     The binomial coefficient `<x>!/(<y>! (<x> - <y>)!)'.  If <x> and
     <y> are integers, then the numerical value of the binomial
     coefficient is computed.  If <y>, or <x - y>, is an integer, the
     binomial coefficient is expressed as a polynomial.

     Examples:

          (%i1) binomial (11, 7);
          (%o1)                          330
          (%i2) 11! / 7! / (11 - 7)!;
          (%o2)                          330
          (%i3) binomial (x, 7);
                  (x - 6) (x - 5) (x - 4) (x - 3) (x - 2) (x - 1) x
          (%o3)   -------------------------------------------------
                                        5040
          (%i4) binomial (x + 7, x);
                (x + 1) (x + 2) (x + 3) (x + 4) (x + 5) (x + 6) (x + 7)
          (%o4) -------------------------------------------------------
                                         5040
          (%i5) binomial (11, y);
          (%o5)                    binomial(11, y)


 -- Function: burn (<n>)
     Returns the <n>'th Bernoulli number for integer <n>.  `burn' may
     be more efficient than `bern' for large, isolated <n> (perhaps <n>
     greater than 105 or so), as `bern' computes all the Bernoulli
     numbers up to index <n> before returning.

     `burn' exploits the observation that (rational) Bernoulli numbers
     can be approximated by (transcendental) zetas with tolerable
     efficiency.

     `load ("bffac")' loads this function.


 -- Function: cf (<expr>)
     Converts <expr> into a continued fraction.  <expr> is an expression
     comprising continued fractions and square roots of integers.
     Operands in the expression may be combined with arithmetic
     operators.  Aside from continued fractions and square roots,
     factors in the expression must be integer or rational numbers.
     Maxima does not know about operations on continued fractions
     outside of `cf'.

     `cf' evaluates its arguments after binding `listarith' to `false'.
     `cf' returns a continued fraction, represented as a list.

     A continued fraction `a + 1/(b + 1/(c + ...))' is represented by
     the list `[a, b, c, ...]'.  The list elements `a', `b', `c', ...
     must evaluate to integers.  <expr> may also contain `sqrt (n)'
     where `n' is an integer.  In this case `cf' will give as many
     terms of the continued fraction as the value of the variable
     `cflength' times the period.

     A continued fraction can be evaluated to a number by evaluating
     the arithmetic representation returned by `cfdisrep'.  See also
     `cfexpand' for another way to evaluate a continued fraction.

     See also `cfdisrep', `cfexpand', and `cflength'.

     Examples:

        * <expr> is an expression comprising continued fractions and
          square roots of integers.

               (%i1) cf ([5, 3, 1]*[11, 9, 7] + [3, 7]/[4, 3, 2]);
               (%o1)               [59, 17, 2, 1, 1, 1, 27]
               (%i2) cf ((3/17)*[1, -2, 5]/sqrt(11) + (8/13));
               (%o2)        [0, 1, 1, 1, 3, 2, 1, 4, 1, 9, 1, 9, 2]

        * `cflength' controls how many periods of the continued fraction
          are computed for algebraic, irrational numbers.

               (%i1) cflength: 1$
               (%i2) cf ((1 + sqrt(5))/2);
               (%o2)                    [1, 1, 1, 1, 2]
               (%i3) cflength: 2$
               (%i4) cf ((1 + sqrt(5))/2);
               (%o4)               [1, 1, 1, 1, 1, 1, 1, 2]
               (%i5) cflength: 3$
               (%i6) cf ((1 + sqrt(5))/2);
               (%o6)           [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2]

        * A continued fraction can be evaluated by evaluating the
          arithmetic representation returned by `cfdisrep'.

               (%i1) cflength: 3$
               (%i2) cfdisrep (cf (sqrt (3)))$
               (%i3) ev (%, numer);
               (%o3)                   1.731707317073171

        * Maxima does not know about operations on continued fractions
          outside of `cf'.

               (%i1) cf ([1,1,1,1,1,2] * 3);
               (%o1)                     [4, 1, 5, 2]
               (%i2) cf ([1,1,1,1,1,2]) * 3;
               (%o2)                  [3, 3, 3, 3, 3, 6]



 -- Function: cfdisrep (<list>)
     Constructs and returns an ordinary arithmetic expression of the
     form `a + 1/(b + 1/(c + ...))' from the list representation of a
     continued fraction `[a, b, c, ...]'.

          (%i1) cf ([1, 2, -3] + [1, -2, 1]);
          (%o1)                     [1, 1, 1, 2]
          (%i2) cfdisrep (%);
                                            1
          (%o2)                     1 + ---------
                                              1
                                        1 + -----
                                                1
                                            1 + -
                                                2


 -- Function: cfexpand (<x>)
     Returns a matrix of the numerators and denominators of the last
     (column 1) and next-to-last (column 2) convergents of the
     continued fraction <x>.

          (%i1) cf (rat (ev (%pi, numer)));

          `rat' replaced 3.141592653589793 by 103993/33102 =3.141592653011902
          (%o1)                  [3, 7, 15, 1, 292]
          (%i2) cfexpand (%);
                                   [ 103993  355 ]
          (%o2)                    [             ]
                                   [ 33102   113 ]
          (%i3) %[1,1]/%[2,1], numer;
          (%o3)                   3.141592653011902


 -- Option variable: cflength
     Default value: 1

     `cflength' controls the number of terms of the continued fraction
     the function `cf' will give, as the value `cflength' times the
     period.  Thus the default is to give one period.

          (%i1) cflength: 1$
          (%i2) cf ((1 + sqrt(5))/2);
          (%o2)                    [1, 1, 1, 1, 2]
          (%i3) cflength: 2$
          (%i4) cf ((1 + sqrt(5))/2);
          (%o4)               [1, 1, 1, 1, 1, 1, 1, 2]
          (%i5) cflength: 3$
          (%i6) cf ((1 + sqrt(5))/2);
          (%o6)           [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2]


 -- Function: divsum (<n>, <k>)
 -- Function: divsum (<n>)
     `divsum (<n>, <k>)' returns the sum of the divisors of <n> raised
     to the <k>'th power.

     `divsum (<n>)' returns the sum of the divisors of <n>.

          (%i1) divsum (12);
          (%o1)                          28
          (%i2) 1 + 2 + 3 + 4 + 6 + 12;
          (%o2)                          28
          (%i3) divsum (12, 2);
          (%o3)                          210
          (%i4) 1^2 + 2^2 + 3^2 + 4^2 + 6^2 + 12^2;
          (%o4)                          210


 -- Function: euler (<n>)
     Returns the <n>'th Euler number for nonnegative integer <n>.

     For the Euler-Mascheroni constant, see `%gamma'.

          (%i1) map (euler, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
          (%o1)    [1, 0, - 1, 0, 5, 0, - 61, 0, 1385, 0, - 50521]


 -- Constant: %gamma
     The Euler-Mascheroni constant, 0.5772156649015329 ....


 -- Function: factorial (<x>)
     Represents the factorial function. Maxima treats `factorial (<x>)'
     the same as `<x>!'.  See `!'.


 -- Function: fib (<n>)
     Returns the <n>'th Fibonacci number.  `fib(0)' equal to 0 and
     `fib(1)' equal to 1, and `fib (-<n>)' equal to `(-1)^(<n> + 1) *
     fib(<n>)'.

     After calling `fib', `prevfib' is equal to `fib (<x> - 1)', the
     Fibonacci number preceding the last one computed.

          (%i1) map (fib, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
          (%o1)         [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]


 -- Function: fibtophi (<expr>)
     Expresses Fibonacci numbers in <expr> in terms of the constant
     `%phi', which is `(1 + sqrt(5))/2', approximately 1.61803399.

     Examples:

          (%i1) fibtophi (fib (n));
                                     n             n
                                 %phi  - (1 - %phi)
          (%o1)                  -------------------
                                     2 %phi - 1
          (%i2) fib (n-1) + fib (n) - fib (n+1);
          (%o2)          - fib(n + 1) + fib(n) + fib(n - 1)
          (%i3) fibtophi (%);
                      n + 1             n + 1       n             n
                  %phi      - (1 - %phi)        %phi  - (1 - %phi)
          (%o3) - --------------------------- + -------------------
                          2 %phi - 1                2 %phi - 1
                                                    n - 1             n - 1
                                                %phi      - (1 - %phi)
                                              + ---------------------------
                                                        2 %phi - 1
          (%i4) ratsimp (%);
          (%o4)                           0


 -- Function: ifactors (<n>)
     For a positive integer <n> returns the factorization of <n>. If
     `n=p1^e1..pk^nk' is the decomposition of <n> into prime factors,
     ifactors returns `[[p1, e1], ... , [pk, ek]]'.

     Factorization methods used are trial divisions by primes up to
     9973, Pollard's rho method and elliptic curve method.

          (%i1) ifactors(51575319651600);
          (%o1)     [[2, 4], [3, 2], [5, 2], [1583, 1], [9050207, 1]]
          (%i2) apply("*", map(lambda([u], u[1]^u[2]), %));
          (%o2)                        51575319651600


 -- Function: inrt (<x>, <n>)
     Returns the integer <n>'th root of the absolute value of <x>.

          (%i1) l: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]$
          (%i2) map (lambda ([a], inrt (10^a, 3)), l);
          (%o2) [2, 4, 10, 21, 46, 100, 215, 464, 1000, 2154, 4641, 10000]


 -- Function: inv_mod (<n>, <m>)
     Computes the inverse of <n> modulo <m>.  `inv_mod (n,m)' returns
     `false', if <n> is a zero divisor modulo <m>.

          (%i1) inv_mod(3, 41);
          (%o1)                           14
          (%i2) ratsimp(3^-1), modulus=41;
          (%o2)                           14
          (%i3) inv_mod(3, 42);
          (%o3)                          false


 -- Function: jacobi (<p>, <q>)
     Returns the Jacobi symbol of <p> and <q>.

          (%i1) l: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]$
          (%i2) map (lambda ([a], jacobi (a, 9)), l);
          (%o2)         [1, 1, 0, 1, 1, 0, 1, 1, 0, 1, 1, 0]


 -- Function: lcm (<expr_1>, ..., <expr_n>)
     Returns the least common multiple of its arguments.  The arguments
     may be general expressions as well as integers.

     `load ("functs")' loads this function.


 -- Function: minfactorial (<expr>)
     Examines <expr> for occurrences of two factorials which differ by
     an integer.  `minfactorial' then turns one into a polynomial times
     the other.

          (%i1) n!/(n+2)!;
                                         n!
          (%o1)                       --------
                                      (n + 2)!
          (%i2) minfactorial (%);
                                          1
          (%o2)                    ---------------
                                   (n + 1) (n + 2)


 -- Function: next_prime (<n>)
     Returns the smallest prime bigger than <n>.

          (%i1) next_prime(27);
          (%o1)                       29


 -- Function: partfrac (<expr>, <var>)
     Expands the expression <expr> in partial fractions with respect to
     the main variable <var>.  `partfrac' does a complete partial
     fraction decomposition.  The algorithm employed is based on the
     fact that the denominators of the partial fraction expansion (the
     factors of the original denominator) are relatively prime.  The
     numerators can be written as linear combinations of denominators,
     and the expansion falls out.

          (%i1) 1/(1+x)^2 - 2/(1+x) + 2/(2+x);
                                2       2        1
          (%o1)               ----- - ----- + --------
                              x + 2   x + 1          2
                                              (x + 1)
          (%i2) ratsimp (%);
                                           x
          (%o2)                 - -------------------
                                   3      2
                                  x  + 4 x  + 5 x + 2
          (%i3) partfrac (%, x);
                                2       2        1
          (%o3)               ----- - ----- + --------
                              x + 2   x + 1          2
                                              (x + 1)

 -- Function: power_mod (<a>, <n>, <m>)
     Uses a modular algorithm to compute `a^n mod m' where <a> and <n>
     are integers and <m> is a positive integer.  If <n> is negative,
     `inv_mod' is used to find the modular inverse.

          (%i1) power_mod(3, 15, 5);
          (%o1)                          2
          (%i2) mod(3^15,5);
          (%o2)                          2
          (%i3) power_mod(2, -1, 5);
          (%o3)                          3
          (%i4) inv_mod(2,5);
          (%o4)                          3


 -- Function: primep (<n>)
     Primality test. If `primep (<n>)' returns `false', <n> is a
     composite number and if it returns `true', <n> is a prime number
     with very high probability.

     For <n> less than 10^16 a deterministic version of Miller-Rabin's
     test is used. If `primep (<n>)' returns `true', then <n> is a
     prime number.

     For <n> bigger than 10^16 `primep' uses `primep_number_of_tests'
     Miller-Rabin's pseudo-primality tests and one Lucas
     pseudo-primality test. The probability that <n> will pass one
     Miller-Rabin test is less than 1/4. Using the default value 25 for
     `primep_number_of_tests', the probability of <n> beeing composite
     is much smaller that 10^-15.


 -- Option variable: primep_number_of_tests
     Default value: 25

     Number of Miller-Rabin's tests used in `primep'.


 -- Function: prev_prime (<n>)
     Returns the greatest prime smaller than <n>.

          (%i1) prev_prime(27);
          (%o1)                       23


 -- Function: qunit (<n>)
     Returns the principal unit of the real quadratic number field
     `sqrt (<n>)' where <n> is an integer, i.e., the element whose norm
     is unity.  This amounts to solving Pell's equation `a^2 - <n> b^2
     = 1'.

          (%i1) qunit (17);
          (%o1)                     sqrt(17) + 4
          (%i2) expand (% * (sqrt(17) - 4));
          (%o2)                           1


 -- Function: totient (<n>)
     Returns the number of integers less than or equal to <n> which are
     relatively prime to <n>.


 -- Option variable: zerobern
     Default value: `true'

     When `zerobern' is `false', `bern' excludes the Bernoulli numbers
     which are equal to zero.  See `bern'.


 -- Function: zeta (<n>)
     Returns the Riemann zeta function if <x> is a negative integer, 0,
     1, or a positive even number, and returns a noun form `zeta (<n>)'
     for all other arguments, including rational noninteger, floating
     point, and complex arguments.

     See also `bfzeta' and `zeta%pi'.

          (%i1) map (zeta, [-4, -3, -2, -1, 0, 1, 2, 3, 4, 5]);
                                               2              4
                     1        1     1       %pi            %pi
          (%o1) [0, ---, 0, - --, - -, inf, ----, zeta(3), ----, zeta(5)]
                    120       12    2        6              90


 -- Option variable: zeta%pi
     Default value: `true'

     When `zeta%pi' is `true', `zeta' returns an expression
     proportional to `%pi^n' for even integer `n'.  Otherwise, `zeta'
     returns a noun form `zeta (n)' for even integer `n'.

          (%i1) zeta%pi: true$
          (%i2) zeta (4);
                                           4
                                        %pi
          (%o2)                         ----
                                         90
          (%i3) zeta%pi: false$
          (%i4) zeta (4);
          (%o4)                        zeta(4)



File: maxima.info,  Node: Symmetries,  Next: Groups,  Prev: Number Theory,  Up: Top

32 Symmetries
*************

* Menu:

* Introduction to Symmetries::
* Functions and Variables for Symmetries::


File: maxima.info,  Node: Introduction to Symmetries,  Next: Functions and Variables for Symmetries,  Prev: Symmetries,  Up: Symmetries

32.1 Introduction to Symmetries
===============================

`sym' is a package for working with symmetric groups of polynomials.


File: maxima.info,  Node: Functions and Variables for Symmetries,  Prev: Introduction to Symmetries,  Up: Symmetries

32.2 Functions and Variables for Symmetries
===========================================

32.2.1 Changing bases
---------------------

 -- Function: comp2pui (<n>, <L>)
     implements passing from the complete symmetric functions given in
     the list <L> to the elementary symmetric functions from 0 to <n>.
     If the list <L> contains fewer than <n+1> elements, it will be
     completed with formal values of the type <h1>, <h2>, etc. If the
     first element of the list <L> exists, it specifies the size of the
     alphabet, otherwise the size is set to <n>.

          (%i1) comp2pui (3, [4, g]);
                                  2                    2
          (%o1)    [4, g, 2 h2 - g , 3 h3 - g h2 + g (g  - 2 h2)]


 -- Function: ele2pui (<m>, <L>)
     goes from the elementary symmetric functions to the complete
     functions.  Similar to `comp2ele' and `comp2pui'.

     Other functions for changing bases: `comp2ele'.


 -- Function: ele2comp (<m>, <L>)
     Goes from the elementary symmetric functions to the compete
     functions.  Similar to `comp2ele' and `comp2pui'.

     Other functions for changing bases: `comp2ele'.


 -- Function: elem (<ele>, <sym>, <lvar>)
     decomposes the symmetric polynomial <sym>, in the variables
     contained in the list <lvar>, in terms of the elementary symmetric
     functions given in the list <ele>.  If the first element of <ele>
     is given, it will be the size of the alphabet, otherwise the size
     will be the degree of the polynomial <sym>.  If values are missing
     in the list <ele>, formal values of the type <e1>, <e2>, etc. will
     be added.  The polynomial <sym> may be given in three different
     forms: contracted (`elem' should then be 1, its default value),
     partitioned (`elem' should be 3), or extended (i.e. the entire
     polynomial, and `elem' should then be 2).  The function `pui' is
     used in the same way.

     On an alphabet of size 3 with <e1>, the first elementary symmetric
     function, with value 7, the symmetric polynomial in 3 variables
     whose contracted form (which here depends on only two of its
     variables) is <x^4-2*x*y> decomposes as follows in elementary
     symmetric functions:

          (%i1) elem ([3, 7], x^4 - 2*x*y, [x, y]);
          (%o1) 7 (e3 - 7 e2 + 7 (49 - e2)) + 21 e3

                                                   + (- 2 (49 - e2) - 2) e2
          (%i2) ratsimp (%);
                                        2
          (%o2)             28 e3 + 2 e2  - 198 e2 + 2401

     Other functions for changing bases: `comp2ele'.


 -- Function: mon2schur (<L>)
     The list <L> represents the Schur function S_L: we have L = [i_1,
     i_2, ..., i_q], with i_1 <= i_2 <= ... <= i_q.  The Schur function
     S_[i_1, i_2, ..., i_q] is the minor of the infinite matrix
     h_[i-j], i <= 1, j <= 1, consisting of the q first rows and the
     columns 1 + i_1, 2 + i_2, ..., q + i_q.

     This Schur function can be written in terms of monomials by using
     `treinat' and `kostka'.  The form returned is a symmetric
     polynomial in a contracted representation in the variables
     x_1,x_2,\ldots.

          (%i1) mon2schur ([1, 1, 1]);
          (%o1)                       x1 x2 x3
          (%i2) mon2schur ([3]);
                                            2        3
          (%o2)                x1 x2 x3 + x1  x2 + x1
          (%i3) mon2schur ([1, 2]);
                                                2
          (%o3)                  2 x1 x2 x3 + x1  x2

     which means that for 3 variables this gives:

             2 x1 x2 x3 + x1^2 x2 + x2^2 x1 + x1^2 x3 + x3^2 x1
              + x2^2 x3 + x3^2 x2
     Other functions for changing bases: `comp2ele'.


 -- Function: multi_elem (<l_elem>, <multi_pc>, <l_var>)
     decomposes a multi-symmetric polynomial in the multi-contracted
     form <multi_pc> in the groups of variables contained in the list
     of lists <l_var> in terms of the elementary symmetric functions
     contained in <l_elem>.

          (%i1) multi_elem ([[2, e1, e2], [2, f1, f2]], a*x + a^2 + x^3,
                [[x, y], [a, b]]);
                                                            3
          (%o1)         - 2 f2 + f1 (f1 + e1) - 3 e1 e2 + e1
          (%i2) ratsimp (%);
                                   2                       3
          (%o2)         - 2 f2 + f1  + e1 f1 - 3 e1 e2 + e1

     Other functions for changing bases: `comp2ele'.


 -- Function: multi_pui
     is to the function `pui' what the function `multi_elem' is to the
     function `elem'.

          (%i1) multi_pui ([[2, p1, p2], [2, t1, t2]], a*x + a^2 + x^3,
                [[x, y], [a, b]]);
                                                      3
                                          3 p1 p2   p1
          (%o1)              t2 + p1 t1 + ------- - ---
                                             2       2


 -- Function: pui (<L>, <sym>, <lvar>)
     decomposes the symmetric polynomial <sym>, in the variables in the
     list <lvar>, in terms of the power functions in the list <L>.  If
     the first element of <L> is given, it will be the size of the
     alphabet, otherwise the size will be the degree of the polynomial
     <sym>.  If values are missing in the list <L>, formal values of
     the type <p1>, <p2> , etc. will be added. The polynomial <sym> may
     be given in three different forms: contracted (`elem' should then
     be 1, its default value), partitioned (`elem' should be 3), or
     extended (i.e. the entire polynomial, and `elem' should then be
     2). The function `pui' is used in the same way.

          (%i1) pui;
          (%o1)                           1
          (%i2) pui ([3, a, b], u*x*y*z, [x, y, z]);
                                 2
                             a (a  - b) u   (a b - p3) u
          (%o2)              ------------ - ------------
                                  6              3
          (%i3) ratsimp (%);
                                                 3
                                (2 p3 - 3 a b + a ) u
          (%o3)                 ---------------------
                                          6
     Other functions for changing bases: `comp2ele'.


 -- Function: pui2comp (<n>, <lpui>)
     renders the list of the first <n> complete functions (with the
     length first) in terms of the power functions given in the list
     <lpui>. If the list <lpui> is empty, the cardinal is <n>,
     otherwise it is its first element (as in `comp2ele' and
     `comp2pui').

          (%i1) pui2comp (2, []);
                                                 2
                                          p2 + p1
          (%o1)                   [2, p1, --------]
                                             2
          (%i2) pui2comp (3, [2, a1]);
                                                      2
                                           a1 (p2 + a1 )
                                   2  p3 + ------------- + a1 p2
                            p2 + a1              2
          (%o2)     [2, a1, --------, --------------------------]
                               2                  3
          (%i3) ratsimp (%);
                                      2                     3
                               p2 + a1   2 p3 + 3 a1 p2 + a1
          (%o3)        [2, a1, --------, --------------------]
                                  2               6
     Other functions for changing bases: `comp2ele'.


 -- Function: pui2ele (<n>, <lpui>)
     effects the passage from power functions to the elementary
     symmetric functions.  If the flag `pui2ele' is `girard', it will
     return the list of elementary symmetric functions from 1 to <n>,
     and if the flag is `close', it will return the <n>-th elementary
     symmetric function.

     Other functions for changing bases: `comp2ele'.


 -- Function: puireduc (<n>, <lpui>)
     <lpui> is a list whose first element is an integer <m>.
     `puireduc' gives the first <n> power functions in terms of the
     first <m>.

          (%i1) puireduc (3, [2]);
                                                   2
                                             p1 (p1  - p2)
          (%o1)          [2, p1, p2, p1 p2 - -------------]
                                                   2
          (%i2) ratsimp (%);
                                                     3
                                         3 p1 p2 - p1
          (%o2)              [2, p1, p2, -------------]
                                               2


 -- Function: schur2comp (<P>, <l_var>)
     <P> is a polynomial in the variables of the list <l_var>.  Each of
     these variables represents a complete symmetric function.  In
     <l_var> the <i>-th complete symmetric function is represented by
     the concatenation of the letter `h' and the integer <i>: `h<i>'.
     This function expresses <P> in terms of Schur functions.

          (%i1) schur2comp (h1*h2 - h3, [h1, h2, h3]);
          (%o1)                         s
                                         1, 2
          (%i2) schur2comp (a*h3, [h3]);
          (%o2)                         s  a
                                         3


32.2.2 Changing representations
-------------------------------

 -- Function: cont2part (<pc>, <lvar>)
     returns the partitioned polynomial associated to the contracted
     form <pc> whose variables are in <lvar>.

          (%i1) pc: 2*a^3*b*x^4*y + x^5;
                                     3    4      5
          (%o1)                   2 a  b x  y + x
          (%i2) cont2part (pc, [x, y]);
                                             3
          (%o2)              [[1, 5, 0], [2 a  b, 4, 1]]


 -- Function: contract (<psym>, <lvar>)
     returns a contracted form (i.e. a monomial orbit under the action
     of the symmetric group) of the polynomial <psym> in the variables
     contained in the list <lvar>.  The function `explose' performs the
     inverse operation.  The function `tcontract' tests the symmetry of
     the polynomial.

          (%i1) psym: explose (2*a^3*b*x^4*y, [x, y, z]);
                   3      4      3      4      3    4        3    4
          (%o1) 2 a  b y z  + 2 a  b x z  + 2 a  b y  z + 2 a  b x  z

                                                     3      4      3    4
                                                + 2 a  b x y  + 2 a  b x  y
          (%i2) contract (psym, [x, y, z]);
                                        3    4
          (%o2)                      2 a  b x  y


 -- Function: explose (<pc>, <lvar>)
     returns the symmetric polynomial associated with the contracted
     form <pc>. The list <lvar> contains the variables.

          (%i1) explose (a*x + 1, [x, y, z]);
          (%o1)                  a z + a y + a x + 1


 -- Function: part2cont (<ppart>, <lvar>)
     goes from the partitioned form to the contracted form of a
     symmetric polynomial.  The contracted form is rendered with the
     variables in <lvar>.

          (%i1) part2cont ([[2*a^3*b, 4, 1]], [x, y]);
                                        3    4
          (%o1)                      2 a  b x  y


 -- Function: partpol (<psym>, <lvar>)
     <psym> is a symmetric polynomial in the variables of the list
     <lvar>. This function retturns its partitioned representation.

          (%i1) partpol (-a*(x + y) + 3*x*y, [x, y]);
          (%o1)               [[3, 1, 1], [- a, 1, 0]]


 -- Function: tcontract (<pol>, <lvar>)
     tests if the polynomial <pol> is symmetric in the variables of the
     list <lvar>.  If so, it returns a contracted representation like
     the function `contract'.


 -- Function: tpartpol (<pol>, <lvar>)
     tests if the polynomial <pol> is symmetric in the variables of the
     list <lvar>.  If so, it returns its partitioned representation like
     the function `partpol'.


32.2.3 Groups and orbits
------------------------

 -- Function: direct ([<p_1>, ..., <p_n>], <y>, <f>, [<lvar_1>, ...,
          <lvar_n>])
     calculates the direct image (see M. Giusti, D. Lazard et A.
     Valibouze, ISSAC 1988, Rome) associated to the function <f>, in
     the lists of variables <lvar_1>, ..., <lvar_n>, and in the
     polynomials <p_1>, ..., <p_n> in a variable <y>.  The arity of the
     function <f> is important for the calulation.  Thus, if the
     expression for <f> does not depend on some variable, it is useless
     to include this variable, and not including it will also
     considerably reduce the amount of computation.

          (%i1) direct ([z^2  - e1* z + e2, z^2  - f1* z + f2],
                        z, b*v + a*u, [[u, v], [a, b]]);
                 2
          (%o1) y  - e1 f1 y

                                           2            2             2   2
                            - 4 e2 f2 - (e1  - 2 e2) (f1  - 2 f2) + e1  f1
                          + -----------------------------------------------
                                                   2
          (%i2) ratsimp (%);
                        2                2                   2
          (%o2)        y  - e1 f1 y + (e1  - 4 e2) f2 + e2 f1
          (%i3) ratsimp (direct ([z^3-e1*z^2+e2*z-e3,z^2  - f1* z + f2],
                        z, b*v + a*u, [[u, v], [a, b]]));
                 6            5         2                        2    2   4
          (%o3) y  - 2 e1 f1 y  + ((2 e1  - 6 e2) f2 + (2 e2 + e1 ) f1 ) y

                                    3                               3   3
           + ((9 e3 + 5 e1 e2 - 2 e1 ) f1 f2 + (- 2 e3 - 2 e1 e2) f1 ) y

                   2       2        4    2
           + ((9 e2  - 6 e1  e2 + e1 ) f2

                              2       2       2                   2    4
           + (- 9 e1 e3 - 6 e2  + 3 e1  e2) f1  f2 + (2 e1 e3 + e2 ) f1 )

            2          2                      2     3          2
           y  + (((9 e1  - 27 e2) e3 + 3 e1 e2  - e1  e2) f1 f2

                           2            2    3                5
           + ((15 e2 - 2 e1 ) e3 - e1 e2 ) f1  f2 - 2 e2 e3 f1 ) y

                     2                   3           3     2   2    3
           + (- 27 e3  + (18 e1 e2 - 4 e1 ) e3 - 4 e2  + e1  e2 ) f2

                   2      3                   3    2   2
           + (27 e3  + (e1  - 9 e1 e2) e3 + e2 ) f1  f2

                             2    4        2   6
           + (e1 e2 e3 - 9 e3 ) f1  f2 + e3  f1

     Finding the polynomial whose roots are the sums a+u where a is a
     root of z^2 - e_1 z + e_2 and u is a root of z^2 - f_1 z + f_2.

          (%i1) ratsimp (direct ([z^2 - e1* z + e2, z^2 - f1* z + f2],
                                    z, a + u, [[u], [a]]));
                 4                    3             2
          (%o1) y  + (- 2 f1 - 2 e1) y  + (2 f2 + f1  + 3 e1 f1 + 2 e2

               2   2                              2               2
           + e1 ) y  + ((- 2 f1 - 2 e1) f2 - e1 f1  + (- 2 e2 - e1 ) f1

                            2                     2            2
           - 2 e1 e2) y + f2  + (e1 f1 - 2 e2 + e1 ) f2 + e2 f1  + e1 e2 f1

               2
           + e2

     `direct' accepts two flags: `elementaires' and `puissances'
     (default) which allow decomposing the symmetric polynomials
     appearing in the calculation into elementary symmetric functions,
     or power functions, respectively.

     Functions of `sym' used in this function:

     `multi_orbit' (so `orbit'), `pui_direct', `multi_elem' (so
     `elem'), `multi_pui' (so `pui'), `pui2ele', `ele2pui' (if the flag
     `direct' is in `puissances').


 -- Function: multi_orbit (<P>, [<lvar_1>, <lvar_2>,..., <lvar_p>])
     <P> is a polynomial in the set of variables contained in the lists
     <lvar_1>, <lvar_2>, ..., <lvar_p>. This function returns the orbit
     of the polynomial <P> under the action of the product of the
     symmetric groups of the sets of variables represented in these <p>
     lists.

          (%i1) multi_orbit (a*x + b*y, [[x, y], [a, b]]);
          (%o1)                [b y + a x, a y + b x]
          (%i2) multi_orbit (x + y + 2*a, [[x, y], [a, b, c]]);
          (%o2)        [y + x + 2 c, y + x + 2 b, y + x + 2 a]
     Also see: `orbit' for the action of a single symmetric group.


 -- Function: multsym (<ppart_1>, <ppart_2>, <n>)
     returns the product of the two symmetric polynomials in <n>
     variables by working only modulo the action of the symmetric group
     of order <n>. The polynomials are in their partitioned form.

     Given the 2 symmetric polynomials in <x>, <y>:  `3*(x + y) +
     2*x*y' and `5*(x^2 + y^2)' whose partitioned forms are `[[3, 1],
     [2, 1, 1]]' and `[[5, 2]]', their product will be

          (%i1) multsym ([[3, 1], [2, 1, 1]], [[5, 2]], 2);
          (%o1)         [[10, 3, 1], [15, 3, 0], [15, 2, 1]]
     that is `10*(x^3*y + y^3*x) + 15*(x^2*y + y^2*x) + 15*(x^3 + y^3)'.

     Functions for changing the representations of a symmetric
     polynomial:

     `contract', `cont2part', `explose', `part2cont', `partpol',
     `tcontract', `tpartpol'.


 -- Function: orbit (<P>, <lvar>)
     computes the orbit of the polynomial <P> in the variables in the
     list <lvar> under the action of the symmetric group of the set of
     variables in the list <lvar>.

          (%i1) orbit (a*x + b*y, [x, y]);
          (%o1)                [a y + b x, b y + a x]
          (%i2) orbit (2*x + x^2, [x, y]);
                                  2         2
          (%o2)                 [y  + 2 y, x  + 2 x]
     See also `multi_orbit' for the action of a product of symmetric
     groups on a polynomial.


 -- Function: pui_direct (<orbite>, [<lvar_1>, ..., <lvar_n>], [<d_1>,
          <d_2>, ..., <d_n>])
     Let <f> be a polynomial in <n> blocks of variables <lvar_1>, ...,
     <lvar_n>.  Let <c_i> be the number of variables in <lvar_i>, and
     <SC> be the product of <n> symmetric groups of degree <c_1>, ...,
     <c_n>. This group acts naturally on <f>.  The list <orbite> is the
     orbit, denoted `<SC>(<f>)', of the function <f> under the action
     of <SC>. (This list may be obtained by the function
     `multi_orbit'.)  The <di> are integers s.t. c_1 \le d_1, c_2 \le
     d_2, \ldots, c_n \le d_n.

     Let <SD> be the product of the symmetric groups S_[d_1] x S_[d_2]
     x ... x S_[d_n].  The function `pui_direct' returns the first <n>
     power functions of `<SD>(<f>)' deduced from the power functions of
     `<SC>(<f>)', where <n> is the size of `<SD>(<f>)'.

     The result is in multi-contracted form w.r.t. <SD>, i.e. only one
     element is kept per orbit, under the action of <SD>.

          (%i1) l: [[x, y], [a, b]];
          (%o1)                   [[x, y], [a, b]]
          (%i2) pui_direct (multi_orbit (a*x + b*y, l), l, [2, 2]);
                                                 2  2
          (%o2)               [a x, 4 a b x y + a  x ]
          (%i3) pui_direct (multi_orbit (a*x + b*y, l), l, [3, 2]);
                                       2  2     2    2        3  3
          (%o3) [2 a x, 4 a b x y + 2 a  x , 3 a  b x  y + 2 a  x ,

              2  2  2  2      3    3        4  4
          12 a  b  x  y  + 4 a  b x  y + 2 a  x ,

              3  2  3  2      4    4        5  5
          10 a  b  x  y  + 5 a  b x  y + 2 a  x ,

              3  3  3  3       4  2  4  2      5    5        6  6
          40 a  b  x  y  + 15 a  b  x  y  + 6 a  b x  y + 2 a  x ]
          (%i4) pui_direct ([y + x + 2*c, y + x + 2*b, y + x + 2*a],
                [[x, y], [a, b, c]], [2, 3]);
                                       2              2
          (%o4) [3 x + 2 a, 6 x y + 3 x  + 4 a x + 4 a ,

                           2                   3        2       2        3
                        9 x  y + 12 a x y + 3 x  + 6 a x  + 12 a  x + 8 a ]


32.2.4 Partitions
-----------------

 -- Function: kostka (<part_1>, <part_2>)
     written by P. Esperet, calculates the Kostka number of the
     partition <part_1> and <part_2>.

          (%i1) kostka ([3, 3, 3], [2, 2, 2, 1, 1, 1]);
          (%o1)                           6


 -- Function: lgtreillis (<n>, <m>)
     returns the list of partitions of weight <n> and length <m>.

          (%i1) lgtreillis (4, 2);
          (%o1)                   [[3, 1], [2, 2]]
     Also see: `ltreillis', `treillis' and `treinat'.


 -- Function: ltreillis (<n>, <m>)
     returns the list of partitions of weight <n> and length less than
     or equal to <m>.

          (%i1) ltreillis (4, 2);
          (%o1)               [[4, 0], [3, 1], [2, 2]]
     Also see: `lgtreillis', `treillis' and `treinat'.


 -- Function: treillis (<n>)
     returns all partitions of weight <n>.

          (%i1) treillis (4);
          (%o1)    [[4], [3, 1], [2, 2], [2, 1, 1], [1, 1, 1, 1]]

     See also: `lgtreillis', `ltreillis' and `treinat'.


 -- Function: treinat (<part>)
     retruns the list of partitions inferior to the partition <part>
     w.r.t.  the natural order.

          (%i1) treinat ([5]);
          (%o1)                         [[5]]
          (%i2) treinat ([1, 1, 1, 1, 1]);
          (%o2) [[5], [4, 1], [3, 2], [3, 1, 1], [2, 2, 1], [2, 1, 1, 1],

                                                           [1, 1, 1, 1, 1]]
          (%i3) treinat ([3, 2]);
          (%o3)                 [[5], [4, 1], [3, 2]]

     See also: `lgtreillis', `ltreillis' and `treillis'.


32.2.5 Polynomials and their roots
----------------------------------

 -- Function: ele2polynome (<L>, <z>)
     returns the polynomial in <z> s.t. the elementary symmetric
     functions of its roots are in the list `<L> = [<n>, <e_1>, ...,
     <e_n>]', where <n> is the degree of the polynomial and <e_i> the
     <i>-th elementary symmetric function.

          (%i1) ele2polynome ([2, e1, e2], z);
                                    2
          (%o1)                    z  - e1 z + e2
          (%i2) polynome2ele (x^7 - 14*x^5 + 56*x^3  - 56*x + 22, x);
          (%o2)          [7, 0, - 14, 0, 56, 0, - 56, - 22]
          (%i3) ele2polynome ([7, 0, -14, 0, 56, 0, -56, -22], x);
                            7       5       3
          (%o3)            x  - 14 x  + 56 x  - 56 x + 22
     The inverse: `polynome2ele (<P>, <z>)'.

     Also see: `polynome2ele', `pui2polynome'.


 -- Function: polynome2ele (<P>, <x>)
     gives the list `<l> = [<n>, <e_1>, ..., <e_n>]' where <n> is the
     degree of the polynomial <P> in the variable <x> and <e_i> is the
     <i>-the elementary symmetric function of the roots of <P>.

          (%i1) polynome2ele (x^7 - 14*x^5 + 56*x^3 - 56*x + 22, x);
          (%o1)          [7, 0, - 14, 0, 56, 0, - 56, - 22]
          (%i2) ele2polynome ([7, 0, -14, 0, 56, 0, -56, -22], x);
                            7       5       3
          (%o2)            x  - 14 x  + 56 x  - 56 x + 22
     The inverse: `ele2polynome (<l>, <x>)'


 -- Function: prodrac (<L>, <k>)
     <L> is a list containing the elementary symmetric functions on a
     set <A>. `prodrac' returns the polynomial whose roots are the <k>
     by <k> products of the elements of <A>.

     Also see `somrac'.


 -- Function: pui2polynome (<x>, <lpui>)
     calculates the polynomial in <x> whose power functions of the roots
     are given in the list <lpui>.

          (%i1) pui;
          (%o1)                           1
          (%i2) kill(labels);
          (%o0)                         done
          (%i1) polynome2ele (x^3 - 4*x^2 + 5*x - 1, x);
          (%o1)                     [3, 4, 5, 1]
          (%i2) ele2pui (3, %);
          (%o2)                     [3, 4, 6, 7]
          (%i3) pui2polynome (x, %);
                                  3      2
          (%o3)                  x  - 4 x  + 5 x - 1
     See also: `polynome2ele', `ele2polynome'.


 -- Function: somrac (<L>, <k>)
     The list <L> contains elementary symmetric functions of a
     polynomial <P> . The function computes the polynomial whose roots
     are the <k> by <k> distinct sums of the roots of <P>.

     Also see `prodrac'.


32.2.6 Resolvents
-----------------

 -- Function: resolvante (<P>, <x>, <f>, [<x_1>,..., <x_d>])
     calculates the resolvent of the polynomial <P> in <x> of degree
     <n> >= <d> by the function <f> expressed in the variables <x_1>,
     ..., <x_d>.  For efficiency of computation it is important to not
     include in the list `[<x_1>, ..., <x_d>]' variables which do not
     appear in the transformation function <f>.

     To increase the efficiency of the computation one may set flags in
     `resolvante' so as to use appropriate algorithms:

     If the function <f> is unitary:
        * A polynomial in a single variable,

        *   linear,

        *   alternating,

        *   a sum,

        *   symmetric,

        *   a product,

        * the function of the Cayley resolvent (usable up to degree 5)

               (x1*x2 + x2*x3 + x3*x4 + x4*x5 + x5*x1 -
                    (x1*x3 + x3*x5 + x5*x2 + x2*x4 + x4*x1))^2

          general,
     the flag of `resolvante' may be, respectively:
        *   unitaire,

        *   lineaire,

        *   alternee,

        *   somme,

        *   produit,

        *   cayley,

        *   generale.

          (%i1) resolvante: unitaire$
          (%i2) resolvante (x^7 - 14*x^5 + 56*x^3 - 56*x + 22, x, x^3 - 1,
                [x]);

          " resolvante unitaire " [7, 0, 28, 0, 168, 0, 1120, - 154, 7840,
                                   - 2772, 56448, - 33880,

          413952, - 352352, 3076668, - 3363360, 23114112, - 30494464,

          175230832, - 267412992, 1338886528, - 2292126760]
            3       6      3       9      6      3
          [x  - 1, x  - 2 x  + 1, x  - 3 x  + 3 x  - 1,

           12      9      6      3       15      12       9       6      3
          x   - 4 x  + 6 x  - 4 x  + 1, x   - 5 x   + 10 x  - 10 x  + 5 x

                 18      15       12       9       6      3
           - 1, x   - 6 x   + 15 x   - 20 x  + 15 x  - 6 x  + 1,

           21      18       15       12       9       6      3
          x   - 7 x   + 21 x   - 35 x   + 35 x  - 21 x  + 7 x  - 1]
          [- 7, 1127, - 6139, 431767, - 5472047, 201692519, - 3603982011]
                 7      6        5         4          3           2
          (%o2) y  + 7 y  - 539 y  - 1841 y  + 51443 y  + 315133 y

                                                        + 376999 y + 125253
          (%i3) resolvante: lineaire$
          (%i4) resolvante (x^4 - 1, x, x1 + 2*x2 + 3*x3, [x1, x2, x3]);

          " resolvante lineaire "
                 24       20         16            12             8
          (%o4) y   + 80 y   + 7520 y   + 1107200 y   + 49475840 y

                                                              4
                                                 + 344489984 y  + 655360000
          (%i5) resolvante: general$
          (%i6) resolvante (x^4 - 1, x, x1 + 2*x2 + 3*x3, [x1, x2, x3]);

          " resolvante generale "
                 24       20         16            12             8
          (%o6) y   + 80 y   + 7520 y   + 1107200 y   + 49475840 y

                                                              4
                                                 + 344489984 y  + 655360000
          (%i7) resolvante (x^4 - 1, x, x1 + 2*x2 + 3*x3, [x1, x2, x3, x4]);

          " resolvante generale "
                 24       20         16            12             8
          (%o7) y   + 80 y   + 7520 y   + 1107200 y   + 49475840 y

                                                              4
                                                 + 344489984 y  + 655360000
          (%i8) direct ([x^4 - 1], x, x1 + 2*x2 + 3*x3, [[x1, x2, x3]]);
                 24       20         16            12             8
          (%o8) y   + 80 y   + 7520 y   + 1107200 y   + 49475840 y

                                                              4
                                                 + 344489984 y  + 655360000
          (%i9) resolvante :lineaire$
          (%i10) resolvante (x^4 - 1, x, x1 + x2 + x3, [x1, x2, x3]);

          " resolvante lineaire "
                                        4
          (%o10)                       y  - 1
          (%i11) resolvante: symetrique$
          (%i12) resolvante (x^4 - 1, x, x1 + x2 + x3, [x1, x2, x3]);

          " resolvante symetrique "
                                        4
          (%o12)                       y  - 1
          (%i13) resolvante (x^4 + x + 1, x, x1 - x2, [x1, x2]);

          " resolvante symetrique "
                                     6      2
          (%o13)                    y  - 4 y  - 1
          (%i14) resolvante: alternee$
          (%i15) resolvante (x^4 + x + 1, x, x1 - x2, [x1, x2]);

          " resolvante alternee "
                      12      8       6        4        2
          (%o15)     y   + 8 y  + 26 y  - 112 y  + 216 y  + 229
          (%i16) resolvante: produit$
          (%i17) resolvante (x^7 - 7*x + 3, x, x1*x2*x3, [x1, x2, x3]);

          " resolvante produit "
                  35      33         29        28         27        26
          (%o17) y   - 7 y   - 1029 y   + 135 y   + 7203 y   - 756 y

                   24           23          22            21           20
           + 1323 y   + 352947 y   - 46305 y   - 2463339 y   + 324135 y

                    19           18             17              15
           - 30618 y   - 453789 y   - 40246444 y   + 282225202 y

                       14              12             11            10
           - 44274492 y   + 155098503 y   + 12252303 y   + 2893401 y

                        9            8            7             6
           - 171532242 y  + 6751269 y  + 2657205 y  - 94517766 y

                      5             3
           - 3720087 y  + 26040609 y  + 14348907
          (%i18) resolvante: symetrique$
          (%i19) resolvante (x^7 - 7*x + 3, x, x1*x2*x3, [x1, x2, x3]);

          " resolvante symetrique "
                  35      33         29        28         27        26
          (%o19) y   - 7 y   - 1029 y   + 135 y   + 7203 y   - 756 y

                   24           23          22            21           20
           + 1323 y   + 352947 y   - 46305 y   - 2463339 y   + 324135 y

                    19           18             17              15
           - 30618 y   - 453789 y   - 40246444 y   + 282225202 y

                       14              12             11            10
           - 44274492 y   + 155098503 y   + 12252303 y   + 2893401 y

                        9            8            7             6
           - 171532242 y  + 6751269 y  + 2657205 y  - 94517766 y

                      5             3
           - 3720087 y  + 26040609 y  + 14348907
          (%i20) resolvante: cayley$
          (%i21) resolvante (x^5 - 4*x^2 + x + 1, x, a, []);

          " resolvante de Cayley "
                  6       5         4          3            2
          (%o21) x  - 40 x  + 4080 x  - 92928 x  + 3772160 x  + 37880832 x

                                                                 + 93392896

     For the Cayley resolvent, the 2 last arguments are neutral and the
     input polynomial must necessarily be of degree 5.

     See also:

     `resolvante_bipartite', `resolvante_produit_sym',
     `resolvante_unitaire', `resolvante_alternee1', `resolvante_klein',
     `resolvante_klein3', `resolvante_vierer', `resolvante_diedrale'.


 -- Function: resolvante_alternee1 (<P>, <x>)
     calculates the transformation `<P>(<x>)' of degree <n> by the
     function product(x_i - x_j, 1 <= i < j <= n - 1).

     See also:

     `resolvante_produit_sym', `resolvante_unitaire', `resolvante' ,
     `resolvante_klein', `resolvante_klein3', `resolvante_vierer',
     `resolvante_diedrale', `resolvante_bipartite'.


 -- Function: resolvante_bipartite (<P>, <x>)
     calculates the transformation of `<P>(<x>)' of even degree <n> by
     the function x_1 x_2 ... x_[n/2] + x_[n/2 + 1] ... x_n.

     See also:

     `resolvante_produit_sym', `resolvante_unitaire', `resolvante' ,
     `resolvante_klein', `resolvante_klein3', `resolvante_vierer',
     `resolvante_diedrale', `resolvante_alternee1'.

          (%i1) resolvante_bipartite (x^6 + 108, x);
                        10        8           6             4
          (%o1)        y   - 972 y  + 314928 y  - 34012224 y

     See also:

     `resolvante_produit_sym', `resolvante_unitaire', `resolvante',
     `resolvante_klein', `resolvante_klein3', `resolvante_vierer',
     `resolvante_diedrale', `resolvante_alternee1'.


 -- Function: resolvante_diedrale (<P>, <x>)
     calculates the transformation of `<P>(<x>)' by the function `<x_1>
     <x_2> + <x_3> <x_4>'.

          (%i1) resolvante_diedrale (x^5 - 3*x^4 + 1, x);
                 15       12       11       10        9         8         7
          (%o1) x   - 21 x   - 81 x   - 21 x   + 207 x  + 1134 x  + 2331 x

                  6         5          4          3          2
           - 945 x  - 4970 x  - 18333 x  - 29079 x  - 20745 x  - 25326 x

           - 697

     See also:

     `resolvante_produit_sym', `resolvante_unitaire',
     `resolvante_alternee1', `resolvante_klein', `resolvante_klein3',
     `resolvante_vierer', `resolvante'.


 -- Function: resolvante_klein (<P>, <x>)
     calculates the transformation of `<P>(<x>)' by the function `<x_1>
     <x_2> <x_4> + <x_4>'.

     See also:

     `resolvante_produit_sym', `resolvante_unitaire',
     `resolvante_alternee1', `resolvante', `resolvante_klein3',
     `resolvante_vierer', `resolvante_diedrale'.


 -- Function: resolvante_klein3 (<P>, <x>)
     calculates the transformation of `<P>(<x>)' by the function `<x_1>
     <x_2> <x_4> + <x_4>'.

     See also:

     `resolvante_produit_sym', `resolvante_unitaire',
     `resolvante_alternee1', `resolvante_klein', `resolvante',
     `resolvante_vierer', `resolvante_diedrale'.


 -- Function: resolvante_produit_sym (<P>, <x>)
     calculates the list of all product resolvents of the polynomial
     `<P>(<x>)'.

          (%i1) resolvante_produit_sym (x^5 + 3*x^4 + 2*x - 1, x);
                  5      4             10      8       7       6       5
          (%o1) [y  + 3 y  + 2 y - 1, y   - 2 y  - 21 y  - 31 y  - 14 y

              4       3      2       10      8       7    6       5       4
           - y  + 14 y  + 3 y  + 1, y   + 3 y  + 14 y  - y  - 14 y  - 31 y

                 3      2       5      4
           - 21 y  - 2 y  + 1, y  - 2 y  - 3 y - 1, y - 1]
          (%i2) resolvante: produit$
          (%i3) resolvante (x^5 + 3*x^4 + 2*x - 1, x, a*b*c, [a, b, c]);

          " resolvante produit "
                 10      8       7    6        5       4       3     2
          (%o3) y   + 3 y  + 14 y  - y  - 14 y  - 31 y  - 21 y  - 2 y  + 1

     See also:

     `resolvante', `resolvante_unitaire', `resolvante_alternee1',
     `resolvante_klein', `resolvante_klein3', `resolvante_vierer',
     `resolvante_diedrale'.


 -- Function: resolvante_unitaire (<P>, <Q>, <x>)
     computes the resolvent of the polynomial `<P>(<x>)' by the
     polynomial `<Q>(<x>)'.

     See also:

     `resolvante_produit_sym', `resolvante', `resolvante_alternee1',
     `resolvante_klein', `resolvante_klein3', `resolvante_vierer',
     `resolvante_diedrale'.


 -- Function: resolvante_vierer (<P>, <x>)
     computes the transformation of `<P>(<x>)' by the function `<x_1>
     <x_2> - <x_3> <x_4>'.

     See also:

     `resolvante_produit_sym', `resolvante_unitaire',
     `resolvante_alternee1', `resolvante_klein', `resolvante_klein3',
     `resolvante', `resolvante_diedrale'.


32.2.7 Miscellaneous
--------------------

 -- Function: multinomial (<r>, <part>)
     where <r> is the weight of the partition <part>.  This function
     returns the associate multinomial coefficient: if the parts of
     <part> are <i_1>, <i_2>, ..., <i_k>, the result is `<r>!/(<i_1>!
     <i_2>! ... <i_k>!)'.


 -- Function: permut (<L>)
     returns the list of permutations of the list <L>.



File: maxima.info,  Node: Groups,  Next: Runtime Environment,  Prev: Symmetries,  Up: Top

33 Groups
*********

* Menu:

* Functions and Variables for Groups::


File: maxima.info,  Node: Functions and Variables for Groups,  Prev: Groups,  Up: Groups

33.1 Functions and Variables for Groups
=======================================

 -- Function: todd_coxeter (<relations>, <subgroup>)
 -- Function: todd_coxeter (<relations>)
     Find the order of G/H where G is the Free Group modulo
     <relations>, and H is the subgroup of G generated by <subgroup>.
     <subgroup> is an optional argument, defaulting to [].  In doing
     this it produces a multiplication table for the right action of G
     on G/H, where the cosets are enumerated [H,Hg2,Hg3,...].  This can
     be seen internally in the variable `todd_coxeter_state'.

     Example:

          (%i1) symet(n):=create_list(
                  if (j - i) = 1 then (p(i,j))^^3 else
                      if (not i = j) then (p(i,j))^^2 else
                          p(i,i) , j, 1, n-1, i, 1, j);
                                                                 <3>
          (%o1) symet(n) := create_list(if j - i = 1 then p(i, j)

                                          <2>
           else (if not i = j then p(i, j)    else p(i, i)), j, 1, n - 1,

          i, 1, j)
          (%i2) p(i,j) := concat(x,i).concat(x,j);
          (%o2)        p(i, j) := concat(x, i) . concat(x, j)
          (%i3) symet(5);
                   <2>           <3>    <2>           <2>           <3>
          (%o3) [x1   , (x1 . x2)   , x2   , (x1 . x3)   , (x2 . x3)   ,

                      <2>           <2>           <2>           <3>    <2>
                    x3   , (x1 . x4)   , (x2 . x4)   , (x3 . x4)   , x4   ]
          (%i4) todd_coxeter(%o3);

          Rows tried 426
          (%o4)                          120
          (%i5) todd_coxeter(%o3,[x1]);

          Rows tried 213
          (%o5)                          60
          (%i6) todd_coxeter(%o3,[x1,x2]);

          Rows tried 71
          (%o6)                          20



File: maxima.info,  Node: Runtime Environment,  Next: Miscellaneous Options,  Prev: Groups,  Up: Top

34 Runtime Environment
**********************

* Menu:

* Introduction for Runtime Environment::
* Interrupts::
* Functions and Variables for Runtime Environment::


File: maxima.info,  Node: Introduction for Runtime Environment,  Next: Interrupts,  Prev: Runtime Environment,  Up: Runtime Environment

34.1 Introduction for Runtime Environment
=========================================

`maxima-init.mac' is a file which is loaded automatically when Maxima
starts.  You can use `maxima-init.mac' to customize your Maxima
environment.  `maxima-init.mac', if it exists, is typically placed in
the directory named by `maxima_userdir', although it can be in any
directory searched by the function `file_search'.

   Here is an example `maxima-init.mac' file:

     setup_autoload ("specfun.mac", ultraspherical, assoc_legendre_p);
     showtime:all;

   In this example, `setup_autoload' tells Maxima to load the specified
file (`specfun.mac') if any of the functions (`ultraspherical',
`assoc_legendre_p') are called but not yet defined.  Thus you needn't
remember to load the file before calling the functions.

   The statement `showtime: all' tells Maxima to set the `showtime'
variable.  The `maxima-init.mac' file can contain any other assignments
or other Maxima statements.


File: maxima.info,  Node: Interrupts,  Next: Functions and Variables for Runtime Environment,  Prev: Introduction for Runtime Environment,  Up: Runtime Environment

34.2 Interrupts
===============

The user can stop a time-consuming computation with the ^C (control-C)
character.  The default action is to stop the computation and print
another user prompt.  In this case, it is not possible to restart a
stopped computation.

   If the Lisp variable `*debugger-hook*' is set to `nil', by executing

     :lisp (setq *debugger-hook* nil)

then upon receiving ^C, Maxima will enter the Lisp debugger, and the
user may use the debugger to inspect the Lisp environment.  The stopped
computation can be restarted by entering `continue' in the Lisp
debugger.  The means of returning to Maxima from the Lisp debugger
(other than running the computation to completion) is different for
each version of Lisp.

   On Unix systems, the character ^Z (control-Z) causes Maxima to stop
altogether, and control is returned to the shell prompt.  The `fg'
command causes Maxima to resume from the point at which it was stopped.


File: maxima.info,  Node: Functions and Variables for Runtime Environment,  Prev: Interrupts,  Up: Runtime Environment

34.3 Functions and Variables for Runtime Environment
====================================================

 -- Declaration: feature
     Maxima understands two distinct types of features, system features
     and features which apply to mathematical expressions.  See also
     `status' for information about system features.  See also
     `features' and `featurep' for information about mathematical
     features.

     `feature' itself is not the name of a function or variable.


 -- Function: featurep (<a>, <f>)
     Attempts to determine whether the object <a> has the feature <f>
     on the basis of the facts in the current database.  If so, it
     returns `true', else `false'.

     Note that `featurep' returns `false' when neither <f> nor the
     negation of <f> can be established.

     `featurep' evaluates its argument.

     See also `declare' and `features'.

          (%i1) declare (j, even)$
          (%i2) featurep (j, integer);
          (%o2)                           true


 -- System variable: maxima_tempdir
     `maxima_tempdir' names the directory in which Maxima creates some
     temporary files.  In particular, temporary files for plotting are
     created in `maxima_tempdir'.

     The initial value of `maxima_tempdir' is the user's home directory,
     if Maxima can locate it; otherwise Maxima makes a guess about a
     suitable directory.

     `maxima_tempdir' may be assigned a string which names a directory.


 -- System variable: maxima_userdir
     `maxima_userdir' names a directory which Maxima searches to find
     Maxima and Lisp files.  (Maxima searches some other directories as
     well; `file_search_maxima' and `file_search_lisp' are the complete
     lists.)

     The initial value of `maxima_userdir' is a subdirectory of the
     user's home directory, if Maxima can locate it; otherwise Maxima
     makes a guess about a suitable directory.

     `maxima_userdir' may be assigned a string which names a directory.
     However, assigning to `maxima_userdir' does not automatically
     change `file_search_maxima' and `file_search_lisp'; those
     variables must be changed separately.


 -- Function: room ()
 -- Function: room (true)
 -- Function: room (false)
     Prints out a description of the state of storage and stack
     management in Maxima. `room' calls the Lisp function of the same
     name.

        * `room ()' prints out a moderate description.

        * `room (true)' prints out a verbose description.

        * `room (false)' prints out a terse description.


 -- Function: status (feature)
 -- Function: status (feature, <putative_feature>)
 -- Function: status (status)
     Returns information about the presence or absence of certain
     system-dependent features.

        * `status (feature)' returns a list of system features.  These
          include Lisp version, operating system type, etc.  The list
          may vary from one Lisp type to another.

        * `status (feature, <putative_feature>)' returns `true' if
          <putative_feature> is on the list of items returned by
          `status (feature)' and `false' otherwise.  `status' quotes
          the argument <putative_feature>.  The quote-quote operator
          `''' defeats quotation.  A feature whose name contains a
          special character, such as a hyphen, must be given as a
          string argument. For example, `status (feature, "ansi-cl")'.

        * `status (status)' returns a two-element list `[feature,
          status]'.  `feature' and `status' are the two arguments
          accepted by the `status' function; it is unclear if this list
          has additional significance.

     The variable `features' contains a list of features which apply to
     mathematical expressions. See `features' and `featurep' for more
     information.


 -- Function: time (%o1, %o2, %o3, ...)
     Returns a list of the times, in seconds, taken to compute the
     output lines `%o1', `%o2', `%o3', .... The time returned is
     Maxima's estimate of the internal computation time, not the
     elapsed time. `time' can only be applied to output line variables;
     for any other variables, `time' returns `unknown'.

     Set `showtime: true' to make Maxima print out the computation time
     and elapsed time with each output line.


 -- Function: timedate ()
     Returns a string representing the current time and date.  The
     string has the format `HH:MM:SS Day, mm/dd/yyyy (GMT-n)', where
     the fields are hours, minutes, seconds, day of week, month, day of
     month, year, and hours different from GMT.

     Example:

          (%i1) d: timedate ();
          (%o1) 08:05:09 Wed, 11/02/2005 (GMT-7)
          (%i2) print ("timedate reports current time", d)$
          timedate reports current time 08:05:09 Wed, 11/02/2005 (GMT-7)


 -- Function: absolute_real_time ()
     Returns the number of seconds since midnight, January 1, 1900 UTC.
     The return value is an integer.

     See also `elapsed_real_time' and `elapsed_run_time'.

     Example:

          (%i1) absolute_real_time ();
          (%o1)                      3385045277
          (%i2) 1900 + absolute_real_time () / (365.25 * 24 * 3600);
          (%o2)                   2007.265612087104


 -- Function: elapsed_real_time ()
     Returns the number of seconds (including fractions of a second)
     since Maxima was most recently started or restarted.  The return
     value is a floating-point number.

     See also `absolute_real_time' and `elapsed_run_time'.

     Example:

          (%i1) elapsed_real_time ();
          (%o1)                       2.559324
          (%i2) expand ((a + b)^500)$
          (%i3) elapsed_real_time ();
          (%o3)                       7.552087


 -- Function: elapsed_run_time ()
     Returns an estimate of the number of seconds (including fractions
     of a second) which Maxima has spent in computations since Maxima
     was most recently started or restarted.  The return value is a
     floating-point number.

     See also `absolute_real_time' and `elapsed_real_time'.

     Example:

          (%i1) elapsed_run_time ();
          (%o1)                         0.04
          (%i2) expand ((a + b)^500)$
          (%i3) elapsed_run_time ();
          (%o3)                         1.26



File: maxima.info,  Node: Miscellaneous Options,  Next: Rules and Patterns,  Prev: Runtime Environment,  Up: Top

35 Miscellaneous Options
************************

* Menu:

* Introduction to Miscellaneous Options::
* Share::
* Functions and Variables for Miscellaneous Options::


File: maxima.info,  Node: Introduction to Miscellaneous Options,  Next: Share,  Prev: Miscellaneous Options,  Up: Miscellaneous Options

35.1 Introduction to Miscellaneous Options
==========================================

In this section various options are discussed which have a global effect
on the operation of Maxima.   Also various lists such as the list of all
user defined functions, are discussed.


File: maxima.info,  Node: Share,  Next: Functions and Variables for Miscellaneous Options,  Prev: Introduction to Miscellaneous Options,  Up: Miscellaneous Options

35.2 Share
==========

The Maxima "share" directory contains programs and other files of
interest to Maxima users, but not part of the core implementation of
Maxima.  These programs are typically loaded via `load' or
`setup_autoload'.

   `:lisp *maxima-sharedir*' displays the location of the share
directory within the user's file system.

   `printfile ("share.usg")' prints an out-of-date list of share
packages.  Users may find it more informative to browse the share
directory using a file system browser.


File: maxima.info,  Node: Functions and Variables for Miscellaneous Options,  Prev: Share,  Up: Miscellaneous Options

35.3 Functions and Variables for Miscellaneous Options
======================================================

 -- System variable: aliases
     Default value: `[]'

     `aliases' is the list of atoms which have a user defined alias
     (set up by the `alias', `ordergreat', `orderless' functions or by
     declaring the atom a `noun' with `declare').


 -- Declaration: alphabetic
     `alphabetic' is a declaration type recognized by `declare'.  The
     expression `declare(<s>, alphabetic)' tells Maxima to recognize as
     alphabetic all of the characters in <s>, which must be a string.

     See also *Note Identifiers::.

     Example:

          (%i1) xx\~yy\`\@ : 1729;
          (%o1)                         1729
          (%i2) declare ("~`@", alphabetic);
          (%o2)                         done
          (%i3) xx~yy`@ + @yy`xx + `xx@@yy~;
          (%o3)               `xx@@yy~ + @yy`xx + 1729
          (%i4) listofvars (%);
          (%o4)                  [@yy`xx, `xx@@yy~]


 -- Function: apropos (<string>)
     Searches for Maxima names which have <string> appearing anywhere
     within them.  Thus, `apropos (exp)' returns a list of all the flags
     and functions which have `exp' as part of their names, such as
     `expand', `exp', and `exponentialize'.  Thus if you can only
     remember part of the name of something you can use this command to
     find the rest of the name.  Similarly, you could say `apropos
     (tr_)' to find a list of many of the switches relating to the
     translator, most of which begin with `tr_'.


 -- Function: args (<expr>)
     Returns the list of arguments of `expr', which may be any kind of
     expression other than an atom.  Only the arguments of the
     top-level operator are extracted; subexpressions of `expr' appear
     as elements or subexpressions of elements of the list of arguments.

     The order of the items in the list may depend on the global flag
     `inflag'.

     `args (<expr>)' is equivalent to `substpart ("[", <expr>, 0)'.
     See also `substpart', and `op'.


 -- Option variable: genindex
     Default value: `i'

     `genindex' is the alphabetic prefix used to generate the next
     variable of summation when necessary.


 -- Option variable: gensumnum
     Default value: 0

     `gensumnum' is the numeric suffix used to generate the next
     variable of summation.  If it is set to `false' then the index
     will consist only of `genindex' with no numeric suffix.


 -- System variable: infolists
     Default value: `[]'

     `infolists' is a list of the names of all of the information lists
     in Maxima. These are:

    `labels'
          All bound `%i', `%o', and `%t' labels.

    `values'
          All bound atoms which are user variables, not Maxima options
          or switches, created by `:' or `::' or functional binding.

    `functions'
          All user-defined functions, created by `:=' or `define'.

    `arrays'
          All declared and undeclared arrays, created by `:', `::', or
          `:='.

    `macros'
          All user-defined macro functions.

    `myoptions'
          All options ever reset by the user (whether or not they are
          later reset to their default values).

    `rules'
          All user-defined pattern matching and simplification rules,
          created by `tellsimp', `tellsimpafter', `defmatch', or
          `defrule'.

    `aliases'
          All atoms which have a user-defined alias, created by the
          `alias', `ordergreat', `orderless' functions or by declaring
          the atom as a `noun' with `declare'.

    `dependencies'
          All atoms which have functional dependencies, created by the
          `depends' or `gradef' functions.

    `gradefs'
          All functions which have user-defined derivatives, created by
          the `gradef' function.

    `props'
          All atoms which have any property other than those mentioned
          above, such as properties established by `atvalue' or
          `matchdeclare', etc., as well as properties established in
          the `declare' function.

    `let_rule_packages'
          All user-defined `let' rule packages plus the special package
          `default_let_rule_package'.  (`default_let_rule_package' is
          the name of the rule package used when one is not explicitly
          set by the user.)


 -- Function: integerp (<expr>)
     Returns `true' if <expr> is a literal numeric integer, otherwise
     `false'.

     `integerp' returns `false' if its argument is a symbol, even if
     the argument is declared integer.

     Examples:

          (%i1) integerp (0);
          (%o1)                         true
          (%i2) integerp (1);
          (%o2)                         true
          (%i3) integerp (-17);
          (%o3)                         true
          (%i4) integerp (0.0);
          (%o4)                         false
          (%i5) integerp (1.0);
          (%o5)                         false
          (%i6) integerp (%pi);
          (%o6)                         false
          (%i7) integerp (n);
          (%o7)                         false
          (%i8) declare (n, integer);
          (%o8)                         done
          (%i9) integerp (n);
          (%o9)                         false


 -- Option variable: m1pbranch
     Default value: `false'

     `m1pbranch' is the principal branch for `-1' to a power.
     Quantities such as `(-1)^(1/3)' (that is, an "odd" rational
     exponent) and `(-1)^(1/4)' (that is, an "even" rational exponent)
     are handled as follows:

                        domain:real

          (-1)^(1/3):      -1
          (-1)^(1/4):   (-1)^(1/4)

                       domain:complex
          m1pbranch:false          m1pbranch:true
          (-1)^(1/3)               1/2+%i*sqrt(3)/2
          (-1)^(1/4)              sqrt(2)/2+%i*sqrt(2)/2


 -- Function: numberp (<expr>)
     Returns `true' if <expr> is a literal integer, rational number,
     floating point number, or bigfloat, otherwise `false'.

     `numberp' returns `false' if its argument is a symbol, even if the
     argument is a symbolic number such as `%pi' or `%i', or declared
     to be `even', `odd', `integer', `rational', `irrational', `real',
     `imaginary', or `complex'.

     Examples:

          (%i1) numberp (42);
          (%o1)                         true
          (%i2) numberp (-13/19);
          (%o2)                         true
          (%i3) numberp (3.14159);
          (%o3)                         true
          (%i4) numberp (-1729b-4);
          (%o4)                         true
          (%i5) map (numberp, [%e, %pi, %i, %phi, inf, minf]);
          (%o5)      [false, false, false, false, false, false]
          (%i6) declare (a, even, b, odd, c, integer, d, rational,
               e, irrational, f, real, g, imaginary, h, complex);
          (%o6)                         done
          (%i7) map (numberp, [a, b, c, d, e, f, g, h]);
          (%o7) [false, false, false, false, false, false, false, false]


 -- Function: properties (<a>)
     Returns a list of the names of all the properties associated with
     the atom <a>.


 -- Special symbol: props
     `props' are atoms which have any property other than those
     explicitly mentioned in `infolists', such as specified by
     `atvalue', `matchdeclare', etc., as well as properties specified
     in the `declare' function.


 -- Function: propvars (<prop>)
     Returns a list of those atoms on the `props' list which have the
     property indicated by <prop>.  Thus `propvars (atvalue)' returns a
     list of atoms which have atvalues.


 -- Function: put (<atom>, <value>, <indicator>)
     Assigns <value> to the property (specified by <indicator>) of
     <atom>.  <indicator> may be the name of any property, not just a
     system-defined property.

     `put' evaluates its arguments.  `put' returns <value>.

     Examples:

          (%i1) put (foo, (a+b)^5, expr);
                                             5
          (%o1)                       (b + a)
          (%i2) put (foo, "Hello", str);
          (%o2)                         Hello
          (%i3) properties (foo);
          (%o3)            [[user properties, str, expr]]
          (%i4) get (foo, expr);
                                             5
          (%o4)                       (b + a)
          (%i5) get (foo, str);
          (%o5)                         Hello


 -- Function: qput (<atom>, <value>, <indicator>)
     Assigns <value> to the property (specified by <indicator>) of
     <atom>.  This is the same as `put', except that the arguments are
     quoted.

     Example:

          (%i1) foo: aa$
          (%i2) bar: bb$
          (%i3) baz: cc$
          (%i4) put (foo, bar, baz);
          (%o4)                          bb
          (%i5) properties (aa);
          (%o5)                [[user properties, cc]]
          (%i6) get (aa, cc);
          (%o6)                          bb
          (%i7) qput (foo, bar, baz);
          (%o7)                          bar
          (%i8) properties (foo);
          (%o8)            [value, [user properties, baz]]
          (%i9) get ('foo, 'baz);
          (%o9)                          bar


 -- Function: rem (<atom>, <indicator>)
     Removes the property indicated by <indicator> from <atom>.


 -- Function: remove (<a_1>, <p_1>, ..., <a_n>, <p_n>)
 -- Function: remove ([<a_1>, ..., <a_m>], [<p_1>, ..., <p_n>], ...)
 -- Function: remove ("<a>", operator)
 -- Function: remove (<a>, transfun)
 -- Function: remove (all, <p>)
     Removes properties associated with atoms.

     `remove (<a_1>, <p_1>, ..., <a_n>, <p_n>)' removes property `p_k'
     from atom `a_k'.

     `remove ([<a_1>, ..., <a_m>], [<p_1>, ..., <p_n>], ...)' removes
     properties `<p_1>, ..., <p_n>' from atoms <a_1>, ..., <a_m>.
     There may be more than one pair of lists.

     `remove (all, <p>)' removes the property <p> from all atoms which
     have it.

     The removed properties may be system-defined properties such as
     `function', `macro', or `mode_declare', or user-defined properties.

     A property may be `transfun' to remove the translated Lisp version
     of a function.  After executing this, the Maxima version of the
     function is executed rather than the translated version.

     `remove ("<a>", operator)' or, equivalently, `remove ("<a>", op)'
     removes from <a> the operator properties declared by `prefix',
     `infix', `nary', `postfix', `matchfix', or `nofix'.  Note that the
     name of the operator must be written as a quoted string.

     `remove' always returns `done' whether or not an atom has a
     specified property.  This behavior is unlike the more specific
     remove functions `remvalue', `remarray', `remfunction', and
     `remrule'.


 -- Function: remvalue (<name_1>, ..., <name_n>)
 -- Function: remvalue (all)
     Removes the values of user variables <name_1>, ..., <name_n>
     (which can be subscripted) from the system.

     `remvalue (all)' removes the values of all variables in `values',
     the list of all variables given names by the user (as opposed to
     those which are automatically assigned by Maxima).

     See also `values'.


 -- Function: rncombine (<expr>)
     Transforms <expr> by combining all terms of <expr> that have
     identical denominators or denominators that differ from each other
     by numerical factors only.  This is slightly different from the
     behavior of `combine', which collects terms that have identical
     denominators.

     Setting `pfeformat: true' and using `combine' yields results
     similar to those that can be obtained with `rncombine', but
     `rncombine' takes the additional step of cross-multiplying
     numerical denominator factors.  This results in neater forms, and
     the possibility of recognizing some cancellations.

     `load(rncomb)' loads this function.


 -- Function: scalarp (<expr>)
     Returns `true' if <expr> is a number, constant, or variable
     declared `scalar' with `declare', or composed entirely of numbers,
     constants, and such variables, but not containing matrices or
     lists.


 -- Function: setup_autoload (<filename>, <function_1>, ...,
          <function_n>)
     Specifies that if any of <function_1>, ..., <function_n> are
     referenced and not yet defined, <filename> is loaded via `load'.
     <filename> usually contains definitions for the functions
     specified, although that is not enforced.

     `setup_autoload' does not work for array functions.

     `setup_autoload' quotes its arguments.

     Example:

          (%i1) legendre_p (1, %pi);
          (%o1)                  legendre_p(1, %pi)
          (%i2) setup_autoload ("specfun.mac", legendre_p, ultraspherical);
          (%o2)                         done
          (%i3) ultraspherical (2, 1/2, %pi);
          Warning - you are redefining the Macsyma function ultraspherical
          Warning - you are redefining the Macsyma function legendre_p
                                      2
                           3 (%pi - 1)
          (%o3)            ------------ + 3 (%pi - 1) + 1
                                2
          (%i4) legendre_p (1, %pi);
          (%o4)                          %pi
          (%i5) legendre_q (1, %pi);
                                        %pi + 1
                                %pi log(-------)
                                        1 - %pi
          (%o5)                 ---------------- - 1
                                       2



File: maxima.info,  Node: Rules and Patterns,  Next: Lists,  Prev: Miscellaneous Options,  Up: Top

36 Rules and Patterns
*********************

* Menu:

* Introduction to Rules and Patterns::
* Functions and Variables for Rules and Patterns::


File: maxima.info,  Node: Introduction to Rules and Patterns,  Next: Functions and Variables for Rules and Patterns,  Prev: Rules and Patterns,  Up: Rules and Patterns

36.1 Introduction to Rules and Patterns
=======================================

This section describes user-defined pattern matching and simplification
rules.  There are two groups of functions which implement somewhat
different pattern matching schemes.  In one group are `tellsimp',
`tellsimpafter', `defmatch', `defrule', `apply1', `applyb1', and
`apply2'.  In the other group are `let' and `letsimp'.  Both schemes
define patterns in terms of pattern variables declared by
`matchdeclare'.

   Pattern-matching rules defined by `tellsimp' and `tellsimpafter' are
applied automatically by the Maxima simplifier.  Rules defined by
`defmatch', `defrule', and `let' are applied by an explicit function
call.

   There are additional mechanisms for rules applied to polynomials by
`tellrat', and for commutative and noncommutative algebra in `affine'
package.


File: maxima.info,  Node: Functions and Variables for Rules and Patterns,  Prev: Introduction to Rules and Patterns,  Up: Rules and Patterns

36.2 Functions and Variables for Rules and Patterns
===================================================

 -- Function: apply1 (<expr>, <rule_1>, ..., <rule_n>)
     Repeatedly applies <rule_1> to <expr> until it fails, then
     repeatedly applies the same rule to all subexpressions of <expr>,
     left to right, until <rule_1> has failed on all subexpressions.
     Call the result of transforming <expr> in this manner <expr_2>.
     Then <rule_2> is applied in the same fashion starting at the top
     of <expr_2>.  When <rule_n> fails on the final subexpression, the
     result is returned.

     `maxapplydepth' is the depth of the deepest subexpressions
     processed by `apply1' and `apply2'.

     See also `applyb1', `apply2', and `let'.


 -- Function: apply2 (<expr>, <rule_1>, ..., <rule_n>)
     If <rule_1> fails on a given subexpression, then <rule_2> is
     repeatedly applied, etc.  Only if all rules fail on a given
     subexpression is the whole set of rules repeatedly applied to the
     next subexpression.  If one of the rules succeeds, then the same
     subexpression is reprocessed, starting with the first rule.

     `maxapplydepth' is the depth of the deepest subexpressions
     processed by `apply1' and `apply2'.

     See also `apply1' and `let'.


 -- Function: applyb1 (<expr>, <rule_1>, ..., <rule_n>)
     Repeatedly applies <rule_1> to the deepest subexpression of <expr>
     until it fails, then repeatedly applies the same rule one level
     higher (i.e., larger subexpressions), until <rule_1> has failed on
     the top-level expression.  Then <rule_2> is applied in the same
     fashion to the result of <rule_1>.  After <rule_n> has been
     applied to the top-level expression, the result is returned.

     `applyb1' is similar to `apply1' but works from the bottom up
     instead of from the top down.

     `maxapplyheight' is the maximum height which `applyb1' reaches
     before giving up.

     See also `apply1', `apply2', and `let'.


 -- Option variable: current_let_rule_package
     Default value: `default_let_rule_package'

     `current_let_rule_package' is the name of the rule package that is
     used by functions in the `let' package (`letsimp', etc.) if no
     other rule package is specified.  This variable may be assigned
     the name of any rule package defined via the `let' command.

     If a call such as `letsimp (expr, rule_pkg_name)' is made, the
     rule package `rule_pkg_name' is used for that function call only,
     and the value of `current_let_rule_package' is not changed.


 -- Option variable: default_let_rule_package
     Default value: `default_let_rule_package'

     `default_let_rule_package' is the name of the rule package used
     when one is not explicitly set by the user with `let' or by
     changing the value of `current_let_rule_package'.


 -- Function: defmatch (<progname>, <pattern>, <x_1>, ..., <x_n>)
 -- Function: defmatch (<progname>, <pattern>)
     Defines a function `<progname>(<expr>, <x_1>, ..., <x_n>)' which
     tests <expr> to see if it matches <pattern>.

     <pattern> is an expression containing the pattern arguments <x_1>,
     ..., <x_n> (if any) and some pattern variables (if any).  The
     pattern arguments are given explicitly as arguments to `defmatch'
     while the pattern variables are declared by the `matchdeclare'
     function.  Any variable not declared as a pattern variable in
     `matchdeclare' or as a pattern argument in `defmatch' matches only
     itself.

     The first argument to the created function <progname> is an
     expression to be matched against the pattern and the other
     arguments are the actual arguments which correspond to the dummy
     variables <x_1>, ..., <x_n> in the pattern.

     If the match is successful, <progname> returns a list of equations
     whose left sides are the pattern arguments and pattern variables,
     and whose right sides are the subexpressions which the pattern
     arguments and variables matched.  The pattern variables, but not
     the pattern arguments, are assigned the subexpressions they match.
     If the match fails, <progname> returns `false'.

     A literal pattern (that is, a pattern which contains neither
     pattern arguments nor pattern variables) returns `true' if the
     match succeeds.

     See also `matchdeclare', `defrule', `tellsimp', and
     `tellsimpafter'.

     Examples:

     Define a function `linearp(expr, x)' which tests `expr' to see if
     it is of the form `a*x + b' such that `a' and `b' do not contain
     `x' and `a' is nonzero.  This match function matches expressions
     which are linear in any variable, because the pattern argument `x'
     is given to `defmatch'.

          (%i1) matchdeclare (a, lambda ([e], e#0 and freeof(x, e)), b,
                              freeof(x));
          (%o1)                         done
          (%i2) defmatch (linearp, a*x + b, x);
          (%o2)                        linearp
          (%i3) linearp (3*z + (y + 1)*z + y^2, z);
                                   2
          (%o3)              [b = y , a = y + 4, x = z]
          (%i4) a;
          (%o4)                         y + 4
          (%i5) b;
                                          2
          (%o5)                          y
          (%i6) x;
          (%o6)                           x

     Define a function `linearp(expr)' which tests `expr' to see if it
     is of the form `a*x + b' such that `a' and `b' do not contain `x'
     and `a' is nonzero.  This match function only matches expressions
     linear in `x', not any other variable, because no pattern argument
     is given to `defmatch'.

          (%i1) matchdeclare (a, lambda ([e], e#0 and freeof(x, e)), b,
                              freeof(x));
          (%o1)                         done
          (%i2) defmatch (linearp, a*x + b);
          (%o2)                        linearp
          (%i3) linearp (3*z + (y + 1)*z + y^2);
          (%o3)                         false
          (%i4) linearp (3*x + (y + 1)*x + y^2);
                                       2
          (%o4)                  [b = y , a = y + 4]

     Define a function `checklimits(expr)' which tests `expr' to see if
     it is a definite integral.

          (%i1) matchdeclare ([a, f], true);
          (%o1)                         done
          (%i2) constinterval (l, h) := constantp (h - l);
          (%o2)        constinterval(l, h) := constantp(h - l)
          (%i3) matchdeclare (b, constinterval (a));
          (%o3)                         done
          (%i4) matchdeclare (x, atom);
          (%o4)                         done
          (%i5) simp : false;
          (%o5)                         false
          (%i6) defmatch (checklimits, 'integrate (f, x, a, b));
          (%o6)                      checklimits
          (%i7) simp : true;
          (%o7)                         true
          (%i8) 'integrate (sin(t), t, %pi + x, 2*%pi + x);
                                 x + 2 %pi
                                /
                                [
          (%o8)                 I          sin(t) dt
                                ]
                                /
                                 x + %pi
          (%i9) checklimits (%);
          (%o9)    [b = x + 2 %pi, a = x + %pi, x = t, f = sin(t)]


 -- Function: defrule (<rulename>, <pattern>, <replacement>)
     Defines and names a replacement rule for the given pattern.  If
     the rule named <rulename> is applied to an expression (by
     `apply1', `applyb1', or `apply2'), every subexpression matching
     the pattern will be replaced by the replacement. All variables in
     the replacement which have been assigned values by the pattern
     match are assigned those values in the replacement which is then
     simplified.

     The rules themselves can be treated as functions which transform
     an expression by one operation of the pattern match and
     replacement.  If the match fails, the rule function returns
     `false'.


 -- Function: disprule (<rulename_1>, ..., <rulename_2>)
 -- Function: disprule (all)
     Display rules with the names <rulename_1>, ..., <rulename_n>, as
     returned by `defrule', `tellsimp', or `tellsimpafter', or a
     pattern defined by `defmatch'.  Each rule is displayed with an
     intermediate expression label (`%t').

     `disprule (all)' displays all rules.

     `disprule' quotes its arguments.  `disprule' returns the list of
     intermediate expression labels corresponding to the displayed
     rules.

     See also `letrules', which displays rules defined by `let'.

     Examples:

          (%i1) tellsimpafter (foo (x, y), bar (x) + baz (y));
          (%o1)                   [foorule1, false]
          (%i2) tellsimpafter (x + y, special_add (x, y));
          (%o2)                   [+rule1, simplus]
          (%i3) defmatch (quux, mumble (x));
          (%o3)                         quux
          (%i4) disprule (foorule1, "+rule1", quux);
          (%t4)        foorule1 : foo(x, y) -> baz(y) + bar(x)

          (%t5)          +rule1 : y + x -> special_add(x, y)

          (%t6)                quux : mumble(x) -> []

          (%o6)                    [%t4, %t5, %t6]
          (%i6) ''%;
          (%o6) [foorule1 : foo(x, y) -> baz(y) + bar(x),
               +rule1 : y + x -> special_add(x, y), quux : mumble(x) -> []]


 -- Function: let (<prod>, <repl>, <predname>, <arg_1>, ..., <arg_n>)
 -- Function: let ([<prod>, <repl>, <predname>, <arg_1>, ..., <arg_n>],
          <package_name>)
     Defines a substitution rule for `letsimp' such that <prod> is
     replaced by <repl>.  <prod> is a product of positive or negative
     powers of the following terms:

        * Atoms which `letsimp' will search for literally unless
          previous to calling `letsimp' the `matchdeclare' function is
          used to associate a predicate with the atom.  In this case
          `letsimp' will match the atom to any term of a product
          satisfying the predicate.

        * Kernels such as `sin(x)', `n!', `f(x,y)', etc.  As with atoms
          above `letsimp' will look for a literal match unless
          `matchdeclare' is used to associate a predicate with the
          argument of the kernel.

     A term to a positive power will only match a term having at least
     that power.  A term to a negative power on the other hand will
     only match a term with a power at least as negative.  In the case
     of negative powers in <prod> the switch `letrat' must be set to
     `true'.  See also `letrat'.

     If a predicate is included in the `let' function followed by a
     list of arguments, a tentative match (i.e. one that would be
     accepted if the predicate were omitted) is accepted only if
     `predname (arg_1', ..., arg_n')' evaluates to `true' where
     <arg_i'> is the value matched to <arg_i>.  The <arg_i> may be the
     name of any atom or the argument of any kernel appearing in <prod>.
     <repl> may be any rational expression. If any of the atoms or
     arguments from <prod> appear in <repl> the appropriate
     substitutions are made.  The global flag `letrat' controls the
     simplification of quotients by `letsimp'.  When `letrat' is
     `false', `letsimp' simplifies the numerator and denominator of
     <expr> separately, and does not simplify the quotient.
     Substitutions such as `n!/n' goes to `(n-1)!' then fail.  When
     `letrat' is `true', then the numerator, denominator, and the
     quotient are simplified in that order.

     These substitution functions allow you to work with several rule
     packages at once.  Each rule package can contain any number of
     `let' rules and is referenced by a user-defined name.  `let
     ([<prod>, <repl>, <predname>, <arg_1>, ..., <arg_n>],
     <package_name>)' adds the rule <predname> to the rule package
     <package_name>.  `letsimp (<expr>, <package_name>)' applies the
     rules in <package_name>.  `letsimp (<expr>, <package_name1>,
     <package_name2>, ...)' is equivalent to `letsimp (<expr>,
     <package_name1>)' followed by `letsimp (%, <package_name2>)', ....

     `current_let_rule_package' is the name of the rule package that is
     presently being used.  This variable may be assigned the name of
     any rule package defined via the `let' command.  Whenever any of
     the functions comprising the `let' package are called with no
     package name, the package named by `current_let_rule_package' is
     used.  If a call such as `letsimp (<expr>, <rule_pkg_name>)' is
     made, the rule package <rule_pkg_name> is used for that `letsimp'
     command only, and `current_let_rule_package' is not changed.  If
     not otherwise specified, `current_let_rule_package' defaults to
     `default_let_rule_package'.

          (%i1) matchdeclare ([a, a1, a2], true)$
          (%i2) oneless (x, y) := is (x = y-1)$
          (%i3) let (a1*a2!, a1!, oneless, a2, a1);
          (%o3)         a1 a2! --> a1! where oneless(a2, a1)
          (%i4) letrat: true$
          (%i5) let (a1!/a1, (a1-1)!);
                                  a1!
          (%o5)                   --- --> (a1 - 1)!
                                  a1
          (%i6) letsimp (n*m!*(n-1)!/m);
          (%o6)                      (m - 1)! n!
          (%i7) let (sin(a)^2, 1 - cos(a)^2);
                                  2               2
          (%o7)                sin (a) --> 1 - cos (a)
          (%i8) letsimp (sin(x)^4);
                                  4           2
          (%o8)                cos (x) - 2 cos (x) + 1


 -- Option variable: letrat
     Default value: `false'

     When `letrat' is `false', `letsimp' simplifies the numerator and
     denominator of a ratio separately, and does not simplify the
     quotient.

     When `letrat' is `true', the numerator, denominator, and their
     quotient are simplified in that order.

          (%i1) matchdeclare (n, true)$
          (%i2) let (n!/n, (n-1)!);
                                   n!
          (%o2)                    -- --> (n - 1)!
                                   n
          (%i3) letrat: false$
          (%i4) letsimp (a!/a);
                                         a!
          (%o4)                          --
                                         a
          (%i5) letrat: true$
          (%i6) letsimp (a!/a);
          (%o6)                       (a - 1)!


 -- Function: letrules ()
 -- Function: letrules (<package_name>)
     Displays the rules in a rule package.  `letrules ()' displays the
     rules in the current rule package.  `letrules (<package_name>)'
     displays the rules in <package_name>.

     The current rule package is named by `current_let_rule_package'.
     If not otherwise specified, `current_let_rule_package' defaults to
     `default_let_rule_package'.

     See also `disprule', which displays rules defined by `tellsimp'
     and `tellsimpafter'.


 -- Function: letsimp (<expr>)
 -- Function: letsimp (<expr>, <package_name>)
 -- Function: letsimp (<expr>, <package_name_1>, ..., <package_name_n>)
     Repeatedly applies the substitution rules defined by `let' until
     no further change is made to <expr>.

     `letsimp (<expr>)' uses the rules from `current_let_rule_package'.

     `letsimp (<expr>, <package_name>)' uses the rules from
     <package_name> without changing `current_let_rule_package'.

     `letsimp (<expr>, <package_name_1>, ..., <package_name_n>)' is
     equivalent to `letsimp (<expr>, <package_name_1>', followed by
     `letsimp (%, <package_name_2>)', and so on.


 -- Option variable: let_rule_packages
     Default value: `[default_let_rule_package]'

     `let_rule_packages' is a list of all user-defined let rule packages
     plus the default package `default_let_rule_package'.


 -- Function: matchdeclare (<a_1>, <pred_1>, ..., <a_n>, <pred_n>)
     Associates a predicate <pred_k> with a variable or list of
     variables <a_k> so that <a_k> matches expressions for which the
     predicate returns anything other than `false'.

     A predicate is the name of a function, or a lambda expression, or
     a function call or lambda call missing the last argument, or
     `true' or `all'.  Any expression matches `true' or `all'.  If the
     predicate is specified as a function call or lambda call, the
     expression to be tested is appended to the list of arguments; the
     arguments are evaluated at the time the match is evaluated.
     Otherwise, the predicate is specified as a function name or lambda
     expression, and the expression to be tested is the sole argument.
     A predicate function need not be defined when `matchdeclare' is
     called; the predicate is not evaluated until a match is attempted.

     A predicate may return a Boolean expression as well as `true' or
     `false'.  Boolean expressions are evaluated by `is' within the
     constructed rule function, so it is not necessary to call `is'
     within the predicate.

     If an expression satisfies a match predicate, the match variable
     is assigned the expression, except for match variables which are
     operands of addition `+' or multiplication `*'.  Only addition and
     multiplication are handled specially; other n-ary operators (both
     built-in and user-defined) are treated like ordinary functions.

     In the case of addition and multiplication, the match variable may
     be assigned a single expression which satisfies the match
     predicate, or a sum or product (respectively) of such expressions.
     Such multiple-term matching is greedy: predicates are evaluated in
     the order in which their associated variables appear in the match
     pattern, and a term which satisfies more than one predicate is
     taken by the first predicate which it satisfies.  Each predicate
     is tested against all operands of the sum or product before the
     next predicate is evaluated.  In addition, if 0 or 1
     (respectively) satisfies a match predicate, and there are no other
     terms which satisfy the predicate, 0 or 1 is assigned to the match
     variable associated with the predicate.

     The algorithm for processing addition and multiplication patterns
     makes some match results (for example, a pattern in which a "match
     anything" variable appears) dependent on the ordering of terms in
     the match pattern and in the expression to be matched.  However,
     if all match predicates are mutually exclusive, the match result
     is insensitive to ordering, as one match predicate cannot accept
     terms matched by another.

     Calling `matchdeclare' with a variable <a> as an argument changes
     the `matchdeclare' property for <a>, if one was already declared;
     only the most recent `matchdeclare' is in effect when a rule is
     defined, Later changes to the `matchdeclare' property (via
     `matchdeclare' or `remove') do not affect existing rules.

     `propvars (matchdeclare)' returns the list of all variables for
     which there is a `matchdeclare' property.  `printprops (<a>,
     matchdeclare)' returns the predicate for variable `a'.
     `printprops (all, matchdeclare)' returns the list of predicates
     for all `matchdeclare' variables.  `remove (<a>, matchdeclare)'
     removes the `matchdeclare' property from <a>.

     The functions `defmatch', `defrule', `tellsimp', `tellsimpafter',
     and `let' construct rules which test expressions against patterns.

     `matchdeclare' quotes its arguments.  `matchdeclare' always
     returns `done'.

     Examples:

     A predicate is the name of a function, or a lambda expression, or
     a function call or lambda call missing the last argument, or
     `true' or `all'.

          (%i1) matchdeclare (aa, integerp);
          (%o1)                         done
          (%i2) matchdeclare (bb, lambda ([x], x > 0));
          (%o2)                         done
          (%i3) matchdeclare (cc, freeof (%e, %pi, %i));
          (%o3)                         done
          (%i4) matchdeclare (dd, lambda ([x, y], gcd (x, y) = 1) (1728));
          (%o4)                         done
          (%i5) matchdeclare (ee, true);
          (%o5)                         done
          (%i6) matchdeclare (ff, all);
          (%o6)                         done

     If an expression satisfies a match predicate, the match variable
     is assigned the expression.

          (%i1) matchdeclare (aa, integerp, bb, atom);
          (%o1)                         done
          (%i2) defrule (r1, bb^aa, ["integer" = aa, "atom" = bb]);
                              aa
          (%o2)        r1 : bb   -> [integer = aa, atom = bb]
          (%i3) r1 (%pi^8);
          (%o3)               [integer = 8, atom = %pi]

     In the case of addition and multiplication, the match variable may
     be assigned a single expression which satisfies the match
     predicate, or a sum or product (respectively) of such expressions.

          (%i1) matchdeclare (aa, atom, bb, lambda ([x], not atom(x)));
          (%o1)                         done
          (%i2) defrule (r1, aa + bb, ["all atoms" = aa, "all nonatoms" =
                         bb]);
          bb + aa partitions `sum'
          (%o2)  r1 : bb + aa -> [all atoms = aa, all nonatoms = bb]
          (%i3) r1 (8 + a*b + sin(x));
          (%o3)     [all atoms = 8, all nonatoms = sin(x) + a b]
          (%i4) defrule (r2, aa * bb, ["all atoms" = aa, "all nonatoms" =
                         bb]);
          bb aa partitions `product'
          (%o4)   r2 : aa bb -> [all atoms = aa, all nonatoms = bb]
          (%i5) r2 (8 * (a + b) * sin(x));
          (%o5)    [all atoms = 8, all nonatoms = (b + a) sin(x)]

     When matching arguments of `+' and `*', if all match predicates
     are mutually exclusive, the match result is insensitive to
     ordering, as one match predicate cannot accept terms matched by
     another.

          (%i1) matchdeclare (aa, atom, bb, lambda ([x], not atom(x)));
          (%o1)                         done
          (%i2) defrule (r1, aa + bb, ["all atoms" = aa, "all nonatoms" =
                         bb]);
          bb + aa partitions `sum'
          (%o2)  r1 : bb + aa -> [all atoms = aa, all nonatoms = bb]
          (%i3) r1 (8 + a*b + %pi + sin(x) - c + 2^n);
                                                               n
          (%o3) [all atoms = %pi + 8, all nonatoms = sin(x) + 2  - c + a b]
          (%i4) defrule (r2, aa * bb, ["all atoms" = aa, "all nonatoms" =
                         bb]);
          bb aa partitions `product'
          (%o4)   r2 : aa bb -> [all atoms = aa, all nonatoms = bb]
          (%i5) r2 (8 * (a + b) * %pi * sin(x) / c * 2^n);
                                                            n
                                                   (b + a) 2  sin(x)
          (%o5) [all atoms = 8 %pi, all nonatoms = -----------------]
                                                           c

     The functions `propvars' and `printprops' return information about
     match variables.

          (%i1) matchdeclare ([aa, bb, cc], atom, [dd, ee], integerp);
          (%o1)                         done
          (%i2) matchdeclare (ff, floatnump, gg, lambda ([x], x > 100));
          (%o2)                         done
          (%i3) propvars (matchdeclare);
          (%o3)             [aa, bb, cc, dd, ee, ff, gg]
          (%i4) printprops (ee, matchdeclare);
          (%o4)                    [integerp(ee)]
          (%i5) printprops (gg, matchdeclare);
          (%o5)              [lambda([x], x > 100, gg)]
          (%i6) printprops (all, matchdeclare);
          (%o6) [lambda([x], x > 100, gg), floatnump(ff), integerp(ee),
                                integerp(dd), atom(cc), atom(bb), atom(aa)]


 -- Function: matchfix (<ldelimiter>, <rdelimiter>)
 -- Function: matchfix (<ldelimiter>, <rdelimiter>, <arg_pos>, <pos>)
     Declares a matchfix operator with left and right delimiters
     <ldelimiter> and <rdelimiter>.  The delimiters are specified as
     strings.

     A "matchfix" operator is a function of any number of arguments,
     such that the arguments occur between matching left and right
     delimiters.  The delimiters may be any strings, so long as the
     parser can distinguish the delimiters from the operands and other
     expressions and operators.  In practice this rules out unparseable
     delimiters such as `%', `,', `$' and `;', and may require
     isolating the delimiters with white space.  The right delimiter
     can be the same or different from the left delimiter.

     A left delimiter can be associated with only one right delimiter;
     two different matchfix operators cannot have the same left
     delimiter.

     An existing operator may be redeclared as a matchfix operator
     without changing its other properties.  In particular, built-in
     operators such as addition `+' can be declared matchfix, but
     operator functions cannot be defined for built-in operators.

     `matchfix (<ldelimiter>, <rdelimiter>, <arg_pos>, <pos>)' declares
     the argument part-of-speech <arg_pos> and result part-of-speech
     <pos>, and the delimiters <ldelimiter> and <rdelimiter>.

     "Part of speech", in reference to operator declarations, means
     expression type.  Three types are recognized: `expr', `clause',
     and `any', indicating an algebraic expression, a Boolean
     expression, or any kind of expression, respectively.  Maxima can
     detect some syntax errors by comparing the declared part of speech
     to an actual expression.

     The function to carry out a matchfix operation is an ordinary
     user-defined function.  The operator function is defined in the
     usual way with the function definition operator `:=' or `define'.
     The arguments may be written between the delimiters, or with the
     left delimiter as a quoted string and the arguments following in
     parentheses.  `dispfun (<ldelimiter>)' displays the function
     definition.

     The only built-in matchfix operator is the list constructor `[ ]'.
     Parentheses `( )' and double-quotes `" "' act like matchfix
     operators, but are not treated as such by the Maxima parser.

     `matchfix' evaluates its arguments.  `matchfix' returns its first
     argument, <ldelimiter>.

     Examples:

        * Delimiters may be almost any strings.

          (%i1) matchfix ("@@", "~");
          (%o1)                          @@
          (%i2) @@ a, b, c ~;
          (%o2)                      @@a, b, c~
          (%i3) matchfix (">>", "<<");
          (%o3)                          >>
          (%i4) >> a, b, c <<;
          (%o4)                      >>a, b, c<<
          (%i5) matchfix ("foo", "oof");
          (%o5)                          foo
          (%i6) foo a, b, c oof;
          (%o6)                     fooa, b, coof
          (%i7) >> w + foo x, y oof + z << / @@ p, q ~;
                               >>z + foox, yoof + w<<
          (%o7)                ----------------------
                                      @@p, q~

        * Matchfix operators are ordinary user-defined functions.

          (%i1) matchfix ("!-", "-!");
          (%o1)                         "!-"
          (%i2) !- x, y -! := x/y - y/x;
                                              x   y
          (%o2)                   !-x, y-! := - - -
                                              y   x
          (%i3) define (!-x, y-!, x/y - y/x);
                                              x   y
          (%o3)                   !-x, y-! := - - -
                                              y   x
          (%i4) define ("!-" (x, y), x/y - y/x);
                                              x   y
          (%o4)                   !-x, y-! := - - -
                                              y   x
          (%i5) dispfun ("!-");
                                              x   y
          (%t5)                   !-x, y-! := - - -
                                              y   x

          (%o5)                         done
          (%i6) !-3, 5-!;
                                          16
          (%o6)                         - --
                                          15
          (%i7) "!-" (3, 5);
                                          16
          (%o7)                         - --
                                          15


 -- Function: remlet (<prod>, <name>)
 -- Function: remlet ()
 -- Function: remlet (all)
 -- Function: remlet (all, <name>)
     Deletes the substitution rule, <prod> -> repl, most recently
     defined by the `let' function.  If name is supplied the rule is
     deleted from the rule package name.

     `remlet()' and `remlet(all)' delete all substitution rules from
     the current rule package.  If the name of a rule package is
     supplied, e.g. `remlet (all, <name>)', the rule package <name> is
     also deleted.

     If a substitution is to be changed using the same product,
     `remlet' need not be called, just redefine the substitution using
     the same product (literally) with the `let' function and the new
     replacement and/or predicate name.  Should `remlet (<prod>)' now be
     called the original substitution rule is revived.

     See also `remrule', which removes a rule defined by `tellsimp' or
     `tellsimpafter'.


 -- Function: remrule (<op>, <rulename>)
 -- Function: remrule (<op>, all)
     Removes rules defined by `tellsimp' or `tellsimpafter'.

     `remrule (<op>, <rulename>)' removes the rule with the name
     <rulename> from the operator <op>.  When <op> is a built-in or
     user-defined operator (as defined by `infix', `prefix', etc.),
     <op> and <rulename> must be enclosed in double quote marks.

     `remrule (<op>, all)' removes all rules for the operator <op>.

     See also `remlet', which removes a rule defined by `let'.

     Examples:

          (%i1) tellsimp (foo (aa, bb), bb - aa);
          (%o1)                   [foorule1, false]
          (%i2) tellsimpafter (aa + bb, special_add (aa, bb));
          (%o2)                   [+rule1, simplus]
          (%i3) infix ("@@");
          (%o3)                          @@
          (%i4) tellsimp (aa @@ bb, bb/aa);
          (%o4)                   [@@rule1, false]
          (%i5) tellsimpafter (quux (%pi, %e), %pi - %e);
          (%o5)                  [quuxrule1, false]
          (%i6) tellsimpafter (quux (%e, %pi), %pi + %e);
          (%o6)             [quuxrule2, quuxrule1, false]
          (%i7) [foo (aa, bb), aa + bb, aa @@ bb, quux (%pi, %e),
                 quux (%e, %pi)];
                                               bb
          (%o7) [bb - aa, special_add(aa, bb), --, %pi - %e, %pi + %e]
                                               aa
          (%i8) remrule (foo, foorule1);
          (%o8)                          foo
          (%i9) remrule ("+", "+rule1");
          (%o9)                           +
          (%i10) remrule ("@@", "@@rule1");
          (%o10)                         @@
          (%i11) remrule (quux, all);
          (%o11)                        quux
          (%i12) [foo (aa, bb), aa + bb, aa @@ bb, quux (%pi, %e),
                  quux (%e, %pi)];
          (%o12) [foo(aa, bb), bb + aa, aa @@ bb, quux(%pi, %e),
                                                   quux(%e, %pi)]


 -- Function: tellsimp (<pattern>, <replacement>)
     is similar to `tellsimpafter' but places new information before
     old so that it is applied before the built-in simplification rules.

     `tellsimp' is used when it is important to modify the expression
     before the simplifier works on it, for instance if the simplifier
     "knows" something about the expression, but what it returns is not
     to your liking.  If the simplifier "knows" something about the
     main operator of the expression, but is simply not doing enough for
     you, you probably want to use `tellsimpafter'.

     The pattern may not be a sum, product, single variable, or number.

     `rules' is the list of rules defined by `defrule', `defmatch',
     `tellsimp', and `tellsimpafter'.

     Examples:

          (%i1) matchdeclare (x, freeof (%i));
          (%o1)                         done
          (%i2) %iargs: false$
          (%i3) tellsimp (sin(%i*x), %i*sinh(x));
          (%o3)                 [sinrule1, simp-%sin]
          (%i4) trigexpand (sin (%i*y + x));
          (%o4)         sin(x) cos(%i y) + %i cos(x) sinh(y)
          (%i5) %iargs:true$
          (%i6) errcatch(0^0);
           0
          0  has been generated
          (%o6)                          []
          (%i7) ev (tellsimp (0^0, 1), simp: false);
          (%o7)                  [^rule1, simpexpt]
          (%i8) 0^0;
          (%o8)                           1
          (%i9) remrule ("^", %th(2)[1]);
          (%o9)                           ^
          (%i10) tellsimp (sin(x)^2, 1 - cos(x)^2);
          (%o10)                 [^rule2, simpexpt]
          (%i11) (1 + sin(x))^2;
                                                2
          (%o11)                    (sin(x) + 1)
          (%i12) expand (%);
                                             2
          (%o12)               2 sin(x) - cos (x) + 2
          (%i13) sin(x)^2;
                                            2
          (%o13)                     1 - cos (x)
          (%i14) kill (rules);
          (%o14)                        done
          (%i15) matchdeclare (a, true);
          (%o15)                        done
          (%i16) tellsimp (sin(a)^2, 1 - cos(a)^2);
          (%o16)                 [^rule3, simpexpt]
          (%i17) sin(y)^2;
                                            2
          (%o17)                     1 - cos (y)


 -- Function: tellsimpafter (<pattern>, <replacement>)
     Defines a simplification rule which the Maxima simplifier applies
     after built-in simplification rules.  <pattern> is an expression,
     comprising pattern variables (declared by `matchdeclare') and
     other atoms and operators, considered literals for the purpose of
     pattern matching.  <replacement> is substituted for an actual
     expression which matches <pattern>; pattern variables in
     <replacement> are assigned the values matched in the actual
     expression.

     <pattern> may be any nonatomic expression in which the main
     operator is not a pattern variable; the simplification rule is
     associated with the main operator.  The names of functions (with
     one exception, described below), lists, and arrays may appear in
     <pattern> as the main operator only as literals (not pattern
     variables); this rules out expressions such as `aa(x)' and `bb[y]'
     as patterns, if `aa' and `bb' are pattern variables.  Names of
     functions, lists, and arrays which are pattern variables may
     appear as operators other than the main operator in <pattern>.

     There is one exception to the above rule concerning names of
     functions.  The name of a subscripted function in an expression
     such as `aa[x](y)' may be a pattern variable, because the main
     operator is not `aa' but rather the Lisp atom `mqapply'.  This is
     a consequence of the representation of expressions involving
     subscripted functions.

     Simplification rules are applied after evaluation (if not
     suppressed through quotation or the flag `noeval').  Rules
     established by `tellsimpafter' are applied in the order they were
     defined, and after any built-in rules.  Rules are applied
     bottom-up, that is, applied first to subexpressions before
     application to the whole expression.  It may be necessary to
     repeatedly simplify a result (for example, via the quote-quote
     operator `''' or the flag `infeval') to ensure that all rules are
     applied.

     Pattern variables are treated as local variables in simplification
     rules.  Once a rule is defined, the value of a pattern variable
     does not affect the rule, and is not affected by the rule.  An
     assignment to a pattern variable which results from a successful
     rule match does not affect the current assignment (or lack of it)
     of the pattern variable.  However, as with all atoms in Maxima,
     the properties of pattern variables (as declared by `put' and
     related functions) are global.

     The rule constructed by `tellsimpafter' is named after the main
     operator of <pattern>.  Rules for built-in operators, and
     user-defined operators defined by `infix', `prefix', `postfix',
     `matchfix', and `nofix', have names which are Lisp identifiers.
     Rules for other functions have names which are Maxima identifiers.

     The treatment of noun and verb forms is slightly confused. If a
     rule is defined for a noun (or verb) form and a rule for the
     corresponding verb (or noun) form already exists, the
     newly-defined rule applies to both forms (noun and verb).  If a
     rule for the corresponding verb (or noun) form does not exist, the
     newly-defined rule applies only to the noun (or verb) form.

     The rule constructed by `tellsimpafter' is an ordinary Lisp
     function.  If the name of the rule is `$foorule1', the construct
     `:lisp (trace $foorule1)' traces the function, and `:lisp
     (symbol-function '$foorule1' displays its definition.

     `tellsimpafter' quotes its arguments.  `tellsimpafter' returns the
     list of rules for the main operator of <pattern>, including the
     newly established rule.

     See also `matchdeclare', `defmatch', `defrule', `tellsimp', `let',
     `kill', `remrule', and `clear_rules'.

     Examples:

     <pattern> may be any nonatomic expression in which the main
     operator is not a pattern variable.

          (%i1) matchdeclare (aa, atom, [ll, mm], listp, xx, true)$
          (%i2) tellsimpafter (sin (ll), map (sin, ll));
          (%o2)                 [sinrule1, simp-%sin]
          (%i3) sin ([1/6, 1/4, 1/3, 1/2, 1]*%pi);
                              1  sqrt(2)  sqrt(3)
          (%o3)              [-, -------, -------, 1, 0]
                              2     2        2
          (%i4) tellsimpafter (ll^mm, map ("^", ll, mm));
          (%o4)                  [^rule1, simpexpt]
          (%i5) [a, b, c]^[1, 2, 3];
                                          2   3
          (%o5)                      [a, b , c ]
          (%i6) tellsimpafter (foo (aa (xx)), aa (foo (xx)));
          (%o6)                   [foorule1, false]
          (%i7) foo (bar (u - v));
          (%o7)                    bar(foo(u - v))

     Rules are applied in the order they were defined.  If two rules
     can match an expression, the rule which was defined first is
     applied.

          (%i1) matchdeclare (aa, integerp);
          (%o1)                         done
          (%i2) tellsimpafter (foo (aa), bar_1 (aa));
          (%o2)                   [foorule1, false]
          (%i3) tellsimpafter (foo (aa), bar_2 (aa));
          (%o3)              [foorule2, foorule1, false]
          (%i4) foo (42);
          (%o4)                       bar_1(42)

     Pattern variables are treated as local variables in simplification
     rules.  (Compare to `defmatch', which treats pattern variables as
     global variables.)

          (%i1) matchdeclare (aa, integerp, bb, atom);
          (%o1)                         done
          (%i2) tellsimpafter (foo(aa, bb), bar('aa=aa, 'bb=bb));
          (%o2)                   [foorule1, false]
          (%i3) bb: 12345;
          (%o3)                         12345
          (%i4) foo (42, %e);
          (%o4)                 bar(aa = 42, bb = %e)
          (%i5) bb;
          (%o5)                         12345

     As with all atoms, properties of pattern variables are global even
     though values are local.  In this example, an assignment property
     is declared via `define_variable'.  This is a property of the atom
     `bb' throughout Maxima.

          (%i1) matchdeclare (aa, integerp, bb, atom);
          (%o1)                         done
          (%i2) tellsimpafter (foo(aa, bb), bar('aa=aa, 'bb=bb));
          (%o2)                   [foorule1, false]
          (%i3) foo (42, %e);
          (%o3)                 bar(aa = 42, bb = %e)
          (%i4) define_variable (bb, true, boolean);
          (%o4)                         true
          (%i5) foo (42, %e);
          Error: bb was declared mode boolean, has value: %e
           -- an error.  Quitting.  To debug this try debugmode(true);

     Rules are named after main operators.  Names of rules for built-in
     and user-defined operators are Lisp identifiers, while names for
     other functions are Maxima identifiers.

          (%i1) tellsimpafter (foo (%pi + %e), 3*%pi);
          (%o1)                   [foorule1, false]
          (%i2) tellsimpafter (foo (%pi * %e), 17*%e);
          (%o2)              [foorule2, foorule1, false]
          (%i3) tellsimpafter (foo (%i ^ %e), -42*%i);
          (%o3)         [foorule3, foorule2, foorule1, false]
          (%i4) tellsimpafter (foo (9) + foo (13), quux (22));
          (%o4)                   [+rule1, simplus]
          (%i5) tellsimpafter (foo (9) * foo (13), blurf (22));
          (%o5)                  [*rule1, simptimes]
          (%i6) tellsimpafter (foo (9) ^ foo (13), mumble (22));
          (%o6)                  [^rule1, simpexpt]
          (%i7) rules;
          (%o7) [foorule1, foorule2, foorule3, +rule1, *rule1, ^rule1]
          (%i8) foorule_name: first (%o1);
          (%o8)                       foorule1
          (%i9) plusrule_name: first (%o4);
          (%o9)                        +rule1
          (%i10) remrule (foo, foorule1);
          (%o10)                         foo
          (%i11) remrule ("^", ?\^rule1);
          (%o11)                          ^
          (%i12) rules;
          (%o12)        [foorule2, foorule3, +rule1, *rule1]

     A worked example: anticommutative multiplication.

          (%i1) gt (i, j) := integerp(j) and i < j;
          (%o1)           gt(i, j) := integerp(j) and i < j
          (%i2) matchdeclare (i, integerp, j, gt(i));
          (%o2)                         done
          (%i3) tellsimpafter (s[i]^^2, 1);
          (%o3)                 [^^rule1, simpncexpt]
          (%i4) tellsimpafter (s[i] . s[j], -s[j] . s[i]);
          (%o4)                   [.rule1, simpnct]
          (%i5) s[1] . (s[1] + s[2]);
          (%o5)                    s  . (s  + s )
                                    1     2    1
          (%i6) expand (%);
          (%o6)                      1 - s  . s
                                          2    1
          (%i7) factor (expand (sum (s[i], i, 0, 9)^^5));
          (%o7) 100 (s  + s  + s  + s  + s  + s  + s  + s  + s  + s )
                      9    8    7    6    5    4    3    2    1    0


 -- Function: clear_rules ()
     Executes `kill (rules)' and then resets the next rule number to 1
     for addition `+', multiplication `*', and exponentiation `^'.



File: maxima.info,  Node: Lists,  Next: Sets,  Prev: Rules and Patterns,  Up: Top

37 Lists
********

* Menu:

* Introduction to Lists::
* Functions and Variables for Lists::


File: maxima.info,  Node: Introduction to Lists,  Next: Functions and Variables for Lists,  Prev: Lists,  Up: Lists

37.1 Introduction to Lists
==========================

Lists are the basic building block for Maxima and Lisp.   All data types
other than arrays, hash tables, numbers are represented as Lisp lists,
These Lisp lists have the form

     ((MPLUS) $A 2)

to indicate an expression `a+2'.   At Maxima level one would see the
infix notation `a+2'.   Maxima also has lists which are printed as

     [1, 2, 7, x+y]

for a list with 4 elements.  Internally this corresponds to a Lisp list
of the form

     ((MLIST) 1  2  7  ((MPLUS)  $X $Y ))

The flag which denotes the type field of the Maxima expression is a list
itself, since after it has been through the simplifier the list would
become

     ((MLIST SIMP) 1 2 7 ((MPLUS SIMP) $X $Y))


File: maxima.info,  Node: Functions and Variables for Lists,  Prev: Introduction to Lists,  Up: Lists

37.2 Functions and Variables for Lists
======================================

 -- Function: append (<list_1>, ..., <list_n>)
     Returns a single list of the elements of <list_1> followed by the
     elements of <list_2>, ...  `append' also works on general
     expressions, e.g. `append (f(a,b), f(c,d,e));' yields
     `f(a,b,c,d,e)'.

     Do `example(append);' for an example.


 -- Function: assoc (<key>, <list>, <default>)
 -- Function: assoc (<key>, <list>)
     This function searches for the <key> in the left hand side of the
     input <list> of the form `[x,y,z,...]' where each of the <list>
     elements is an expression of a binary operand and 2 elements.  For
     example `x=1', `2^3', `[a,b]' etc.  The <key> is checked againts
     the first operand.  `assoc' returns the second operand if the
     `key' is found.  If the `key' is not found it either returns the
     <default> value.  <default> is optional and defaults to `false'.


 -- Function: atom (<expr>)
     Returns `true' if <expr> is atomic (i.e. a number, name or string)
     else `false'.  Thus `atom(5)' is `true' while `atom(a[1])' and
     `atom(sin(x))' are `false' (asuming `a[1]' and `x' are unbound).


 -- Function: cons (<expr>, <list>)
     Returns a new list constructed of the element <expr> as its first
     element, followed by the elements of <list>.  `cons' also works on
     other expressions, e.g. `cons(x, f(a,b,c));'  ->  `f(x,a,b,c)'.


 -- Function: copylist (<list>)
     Returns a copy of the list <list>.


 -- Function: create_list (<form>, <x_1>, <list_1>, ..., <x_n>,
          <list_n>)
     Create a list by evaluating <form> with <x_1> bound to each
     element of <list_1>, and for each such binding bind <x_2> to each
     element of <list_2>, ....  The number of elements in the result
     will be the product of the number of elements in each list.  Each
     variable <x_i> must actually be a symbol - it will not be
     evaluated.  The list arguments will be evaluated once at the
     beginning of the iteration.

          (%i1) create_list(x^i,i,[1,3,7]);
                           3   7
          (%o1)       [x, x , x ]

     With a double iteration:

          (%i1) create_list([i,j],i,[a,b],j,[e,f,h]);
          (%o1) [[a, e], [a, f], [a, h], [b, e], [b, f], [b, h]]

     Instead of <list_i> two args may be supplied each of which should
     evaluate to a number.  These will be the inclusive lower and upper
     bounds for the iteration.

          (%i1) create_list([i,j],i,[1,2,3],j,1,i);
          (%o1) [[1, 1], [2, 1], [2, 2], [3, 1], [3, 2], [3, 3]]

     Note that the limits or list for the `j' variable can depend on
     the current value of `i'.


 -- Function: delete (<expr_1>, <expr_2>)
 -- Function: delete (<expr_1>, <expr_2>, <n>)
     Removes all occurrences of <expr_1> from <expr_2>.  <expr_1> may
     be a term of <expr_2> (if it is a sum) or a factor of <expr_2> (if
     it is a product).

          (%i1) delete(sin(x), x+sin(x)+y);
          (%o1)                         y + x

     `delete(<expr_1>, <expr_2>, <n>)' removes the first <n>
     occurrences of <expr_1> from <expr_2>.  If there are fewer than <n>
     occurrences of <expr_1> in <expr_2> then all occurrences will be
     deleted.

          (%i1) delete(a, f(a,b,c,d,a));
          (%o1)                      f(b, c, d)
          (%i2) delete(a, f(a,b,a,c,d,a), 2);
          (%o2)                     f(b, c, d, a)


 -- Function: eighth (<expr>)
     Returns the 8'th item of expression or list <expr>.  See `first'
     for more details.


 -- Function: endcons (<expr>, <list>)
     Returns a new list consisting of the elements of `list' followed
     by <expr>.  `endcons' also works on general expressions, e.g.
     `endcons(x, f(a,b,c));'  ->  `f(a,b,c,x)'.


 -- Function: fifth (<expr>)
     Returns the 5'th item of expression or list <expr>.  See `first'
     for more details.


 -- Function: first (<expr>)
     Returns the first part of <expr> which may result in the first
     element of a list, the first row of a matrix, the first term of a
     sum, etc.  Note that `first' and its related functions, `rest' and
     `last', work on the form of <expr> which is displayed not the form
     which is typed on input.  If the variable `inflag' is set to
     `true' however, these functions will look at the internal form of
     <expr>.  Note that the simplifier re-orders expressions.  Thus
     `first(x+y)' will be `x' if `inflag' is `true' and `y' if `inflag'
     is `false' (`first(y+x)' gives the same results).  The functions
     `second' .. `tenth' yield the second through the tenth part of
     their input argument.


 -- Function: fourth (<expr>)
     Returns the 4'th item of expression or list <expr>.  See `first'
     for more details.


 -- Function: get (<a>, <i>)
     Retrieves the user property indicated by <i> associated with atom
     <a> or returns `false' if a doesn't have property <i>.

     `get' evaluates its arguments.

          (%i1) put (%e, 'transcendental, 'type);
          (%o1)                    transcendental
          (%i2) put (%pi, 'transcendental, 'type)$
          (%i3) put (%i, 'algebraic, 'type)$
          (%i4) typeof (expr) := block ([q],
                  if numberp (expr)
                  then return ('algebraic),
                  if not atom (expr)
                  then return (maplist ('typeof, expr)),
                  q: get (expr, 'type),
                  if q=false
                  then errcatch (error(expr,"is not numeric.")) else q)$
          (%i5) typeof (2*%e + x*%pi);
          x is not numeric.
          (%o5)  [[transcendental, []], [algebraic, transcendental]]
          (%i6) typeof (2*%e + %pi);
          (%o6)     [transcendental, [algebraic, transcendental]]


 -- Function: join (<l>, <m>)
     Creates a new list containing the elements of lists <l> and <m>,
     interspersed.  The result has elements `[<l>[1], <m>[1], <l>[2],
     <m>[2], ...]'.  The lists <l> and <m> may contain any type of
     elements.

     If the lists are different lengths, `join' ignores elements of the
     longer list.

     Maxima complains if <l> or <m> is not a list.

     Examples:

          (%i1) L1: [a, sin(b), c!, d - 1];
          (%o1)                [a, sin(b), c!, d - 1]
          (%i2) join (L1, [1, 2, 3, 4]);
          (%o2)          [a, 1, sin(b), 2, c!, 3, d - 1, 4]
          (%i3) join (L1, [aa, bb, cc, dd, ee, ff]);
          (%o3)        [a, aa, sin(b), bb, c!, cc, d - 1, dd]


 -- Function: last (<expr>)
     Returns the last part (term, row, element, etc.) of the <expr>.


 -- Function: length (<expr>)
     Returns (by default) the number of parts in the external
     (displayed) form of <expr>.  For lists this is the number of
     elements, for matrices it is the number of rows, and for sums it
     is the number of terms (see `dispform').

     The `length' command is affected by the `inflag' switch.  So, e.g.
     `length(a/(b*c));' gives 2 if `inflag' is `false' (Assuming
     `exptdispflag' is `true'), but 3 if `inflag' is `true' (the
     internal representation is essentially `a*b^-1*c^-1').


 -- Option variable: listarith
     default value: `true' - if `false' causes any arithmetic operations
     with lists to be suppressed; when `true', list-matrix operations
     are contagious causing lists to be converted to matrices yielding
     a result which is always a matrix.  However, list-list operations
     should return lists.


 -- Function: listp (<expr>)
     Returns `true' if <expr> is a list else `false'.


 -- Function: makelist (<expr>, <i>, <i_0>, <i_1>)
 -- Function: makelist (<expr>, <x>, <list>)
     Constructs and returns a list, each element of which is generated
     from <expr>.

     `makelist (<expr>, <i>, <i_0>, <i_1>)' returns a list, the `j''th
     element of which is equal to `ev (<expr>, <i>=j)' for `j' equal to
     <i_0> through <i_1>.

     `makelist (<expr>, <x>, <list>)' returns a list, the `j''th
     element of which is equal to `ev (<expr>, <x>=<list>[j])' for `j'
     equal to 1 through `length (<list>)'.

     Examples:

          (%i1) makelist(concat(x,i),i,1,6);
          (%o1)               [x1, x2, x3, x4, x5, x6]
          (%i2) makelist(x=y,y,[a,b,c]);
          (%o2)                 [x = a, x = b, x = c]


 -- Function: member (<expr_1>, <expr_2>)
     Returns `true' if `is(<expr_1> = <a>)' for some element <a> in
     `args(<expr_2>)', otherwise returns `false'.

     `expr_2' is typically a list, in which case `args(<expr_2>) =
     <expr_2>' and `is(<expr_1> = <a>)' for some element <a> in
     `expr_2' is the test.

     `member' does not inspect parts of the arguments of `expr_2', so
     it may return `false' even if `expr_1' is a part of some argument
     of `expr_2'.

     See also `elementp'.

     Examples:

          (%i1) member (8, [8, 8.0, 8b0]);
          (%o1)                         true
          (%i2) member (8, [8.0, 8b0]);
          (%o2)                         false
          (%i3) member (b, [a, b, c]);
          (%o3)                         true
          (%i4) member (b, [[a, b], [b, c]]);
          (%o4)                         false
          (%i5) member ([b, c], [[a, b], [b, c]]);
          (%o5)                         true
          (%i6) F (1, 1/2, 1/4, 1/8);
                                         1  1  1
          (%o6)                     F(1, -, -, -)
                                         2  4  8
          (%i7) member (1/8, %);
          (%o7)                         true
          (%i8) member ("ab", ["aa", "ab", sin(1), a + b]);
          (%o8)                         true


 -- Function: ninth (<expr>)
     Returns the 9'th item of expression or list <expr>.  See `first'
     for more details.


 -- Function: unique (<L>)
     Returns the unique elements of the list <L>.

     When all the elements of <L> are unique, `unique' returns a
     shallow copy of <L>, not <L> itself.

     If <L> is not a list, `unique' returns <L>.

     Example:

          (%i1) unique ([1, %pi, a + b, 2, 1, %e, %pi, a + b, [1]]);
          (%o1)              [1, 2, %e, %pi, [1], b + a]

 -- Function: rest (<expr>, <n>)
 -- Function: rest (<expr>)
     Returns <expr> with its first <n> elements removed if <n> is
     positive and its last `- <n>' elements removed if <n> is negative.
     If <n> is 1 it may be omitted.  <expr> may be a list, matrix, or
     other expression.


 -- Function: reverse (<list>)
     Reverses the order of the members of the <list> (not the members
     themselves).  `reverse' also works on general expressions, e.g.
     `reverse(a=b);' gives `b=a'.


 -- Function: second (<expr>)
     Returns the 2'nd item of expression or list <expr>.  See `first'
     for more details.


 -- Function: seventh (<expr>)
     Returns the 7'th item of expression or list <expr>.  See `first'
     for more details.


 -- Function: sixth (<expr>)
     Returns the 6'th item of expression or list <expr>.  See `first'
     for more details.


 -- Function: sublist_indices (<L>, <P>)
     Returns the indices of the elements `x' of the list <L> for which
     the predicate `maybe(<P>(x))' returns `true'; this excludes
     `unknown' as well as `false'.  <P> may be the name of a function
     or a lambda expression.  <L> must be a literal list.

     Examples:

          (%i1) sublist_indices ('[a, b, b, c, 1, 2, b, 3, b],
                                 lambda ([x], x='b));
          (%o1)                     [2, 3, 7, 9]
          (%i2) sublist_indices ('[a, b, b, c, 1, 2, b, 3, b], symbolp);
          (%o2)                  [1, 2, 3, 4, 7, 9]
          (%i3) sublist_indices ([1 > 0, 1 < 0, 2 < 1, 2 > 1, 2 > 0],
                                 identity);
          (%o3)                       [1, 4, 5]
          (%i4) assume (x < -1);
          (%o4)                       [x < - 1]
          (%i5) map (maybe, [x > 0, x < 0, x < -2]);
          (%o5)                [false, true, unknown]
          (%i6) sublist_indices ([x > 0, x < 0, x < -2], identity);
          (%o6)                          [2]


 -- Function: tenth (<expr>)
     Returns the 10'th item of expression or list <expr>.  See `first'
     for more details.


 -- Function: third (<expr>)
     Returns the 3'rd item of expression or list <expr>.  See `first'
     for more details.



File: maxima.info,  Node: Sets,  Next: Function Definition,  Prev: Lists,  Up: Top

38 Sets
*******

* Menu:

* Introduction to Sets::
* Functions and Variables for Sets::


File: maxima.info,  Node: Introduction to Sets,  Next: Functions and Variables for Sets,  Prev: Sets,  Up: Sets

38.1 Introduction to Sets
=========================

Maxima provides set functions, such as intersection and union, for
finite sets that are defined by explicit enumeration.  Maxima treats
lists and sets as distinct objects. This feature makes it possible to
work with sets that have members that are either lists or sets.

   In addition to functions for finite sets, Maxima provides some
functions related to combinatorics; these include the Stirling numbers
of the first and second kind, the Bell numbers, multinomial
coefficients, partitions of nonnegative integers, and a few others.
Maxima also defines a Kronecker delta function.

38.1.1 Usage
------------

To construct a set with members `a_1, ..., a_n', write `set(a_1, ...,
a_n)' or `{a_1, ..., a_n}'; to construct the empty set, write `set()'
or `{}'.  In input, `set(...)' and `{ ... }' are equivalent.  Sets are
always displayed with curly braces.

   If a member is listed more than once, simplification eliminates the
redundant member.

     (%i1) set();
     (%o1)                          {}
     (%i2) set(a, b, a);
     (%o2)                        {a, b}
     (%i3) set(a, set(b));
     (%o3)                       {a, {b}}
     (%i4) set(a, [b]);
     (%o4)                       {a, [b]}
     (%i5) {};
     (%o5)                          {}
     (%i6) {a, b, a};
     (%o6)                        {a, b}
     (%i7) {a, {b}};
     (%o7)                       {a, {b}}
     (%i8) {a, [b]};
     (%o8)                       {a, [b]}

   Two would-be elements <x> and <y> are redundant (i.e., considered
the same for the purpose of set construction) if and only if `is(<x> =
<y>)' yields `true'.  Note that `is(equal(<x>, <y>))' can yield `true'
while `is(<x> = <y>)' yields `false'; in that case the elements <x> and
<y> are considered distinct.

     (%i1) x: a/c + b/c;
                                   b   a
     (%o1)                         - + -
                                   c   c
     (%i2) y: a/c + b/c;
                                   b   a
     (%o2)                         - + -
                                   c   c
     (%i3) z: (a + b)/c;
                                   b + a
     (%o3)                         -----
                                     c
     (%i4) is (x = y);
     (%o4)                         true
     (%i5) is (y = z);
     (%o5)                         false
     (%i6) is (equal (y, z));
     (%o6)                         true
     (%i7) y - z;
                                b + a   b   a
     (%o7)                    - ----- + - + -
                                  c     c   c
     (%i8) ratsimp (%);
     (%o8)                           0
     (%i9) {x, y, z};
                               b + a  b   a
     (%o9)                    {-----, - + -}
                                 c    c   c

   To construct a set from the elements of a list, use `setify'.

     (%i1) setify ([b, a]);
     (%o1)                        {a, b}

   Set members `x' and `y' are equal provided `is(x = y)' evaluates to
`true'. Thus `rat(x)' and `x' are equal as set members; consequently,

     (%i1) {x, rat(x)};
     (%o1)                          {x}

   Further, since `is((x - 1)*(x + 1) = x^2 - 1)' evaluates to `false',
`(x - 1)*(x + 1)' and `x^2 - 1' are distinct set members; thus

     (%i1) {(x - 1)*(x + 1), x^2 - 1};
                                            2
     (%o1)               {(x - 1) (x + 1), x  - 1}

   To reduce this set to a singleton set, apply `rat' to each set
member:

     (%i1) {(x - 1)*(x + 1), x^2 - 1};
                                            2
     (%o1)               {(x - 1) (x + 1), x  - 1}
     (%i2) map (rat, %);
                                   2
     (%o2)/R/                    {x  - 1}

   To remove redundancies from other sets, you may need to use other
simplification functions. Here is an example that uses `trigsimp':

     (%i1) {1, cos(x)^2 + sin(x)^2};
                                 2         2
     (%o1)                {1, sin (x) + cos (x)}
     (%i2) map (trigsimp, %);
     (%o2)                          {1}

   A set is simplified when its members are non-redundant and sorted.
The current version of the set functions uses the Maxima function
`orderlessp' to order sets; however, future versions of the set
functions might use a different ordering function.

   Some operations on sets, such as substitution, automatically force a
re-simplification; for example,

     (%i1) s: {a, b, c}$
     (%i2) subst (c=a, s);
     (%o2)                        {a, b}
     (%i3) subst ([a=x, b=x, c=x], s);
     (%o3)                          {x}
     (%i4) map (lambda ([x], x^2), set (-1, 0, 1));
     (%o4)                        {0, 1}

   Maxima treats lists and sets as distinct objects; functions such as
`union' and `intersection' complain if any argument is not a set. If
you need to apply a set function to a list, use the `setify' function
to convert it to a set. Thus

     (%i1) union ([1, 2], {a, b});
     Function union expects a set, instead found [1,2]
      -- an error.  Quitting.  To debug this try debugmode(true);
     (%i2) union (setify ([1, 2]), {a, b});
     (%o2)                     {1, 2, a, b}

   To extract all set elements of a set `s' that satisfy a predicate
`f', use `subset(s, f)'. (A predicate is a boolean-valued function.)
For example, to find the equations in a given set that do not depend on
a variable `z', use

     (%i1) subset ({x + y + z, x - y + 4, x + y - 5},
                                         lambda ([e], freeof (z, e)));
     (%o1)               {- y + x + 4, y + x - 5}

   The section *Note Functions and Variables for Sets:: has a complete
list of the set functions in Maxima.

38.1.2 Set Member Iteration
---------------------------

There two ways to to iterate over set members. One way is the use
`map'; for example:

     (%i1) map (f, {a, b, c});
     (%o1)                  {f(a), f(b), f(c)}

   The other way is to use `for <x> in <s> do'

     (%i1) s: {a, b, c};
     (%o1)                       {a, b, c}
     (%i2) for si in s do print (concat (si, 1));
     a1
     b1
     c1
     (%o2)                         done

   The Maxima functions `first' and `rest' work correctly on sets.
Applied to a set, `first' returns the first displayed element of a set;
which element that is may be implementation-dependent. If `s' is a set,
then `rest(s)' is equivalent to `disjoin(first(s), s)'.  Currently,
there are other Maxima functions that work correctly on sets.  In
future versions of the set functions, `first' and `rest' may function
differently or not at all.

38.1.3 Bugs
-----------

The set functions use the Maxima function `orderlessp' to order set
members and the (Lisp-level) function `like' to test for set member
equality. Both of these functions have known bugs that may manifest if
you attempt to use sets with members that are lists or matrices that
contain expressions in canonical rational expression (CRE) form. An
example is

     (%i1) {[x], [rat (x)]};
     Maxima encountered a Lisp error:

       The value #:X1440 is not of type LIST.

     Automatically continuing.
     To reenable the Lisp debugger set *debugger-hook* to nil.

   This expression causes Maxima to halt with an error (the error
message depends on which version of Lisp your Maxima uses). Another
example is

     (%i1) setify ([[rat(a)], [rat(b)]]);
     Maxima encountered a Lisp error:

       The value #:A1440 is not of type LIST.

     Automatically continuing.
     To reenable the Lisp debugger set *debugger-hook* to nil.

   These bugs are caused by bugs in `orderlessp' and `like'; they are
not caused by bugs in the set functions. To illustrate, try the
expressions

     (%i1) orderlessp ([rat(a)], [rat(b)]);
     Maxima encountered a Lisp error:

       The value #:B1441 is not of type LIST.

     Automatically continuing.
     To reenable the Lisp debugger set *debugger-hook* to nil.
     (%i2) is ([rat(a)] = [rat(a)]);
     (%o2)                         false

   Until these bugs are fixed, do not construct sets with members that
are lists or matrices containing expressions in CRE form; a set with a
member in CRE form, however, shouldn't be a problem:

     (%i1) {x, rat (x)};
     (%o1)                          {x}

   Maxima's `orderlessp' has another bug that can cause problems with
set functions, namely that the ordering predicate `orderlessp' is not
transitive. The simplest known example that shows this is

     (%i1) q: x^2$
     (%i2) r: (x + 1)^2$
     (%i3) s: x*(x + 2)$
     (%i4) orderlessp (q, r);
     (%o4)                         true
     (%i5) orderlessp (r, s);
     (%o5)                         true
     (%i6) orderlessp (q, s);
     (%o6)                         false

   This bug can cause trouble with all set functions as well as with
Maxima functions in general. It is probable, but not certain, that this
bug can be avoided if all set members are either in CRE form or have
been simplified using `ratsimp'.

   Maxima's `orderless' and `ordergreat' mechanisms are incompatible
with the set functions. If you need to use either `orderless' or
`ordergreat', call those functions before constructing any sets, and do
not call `unorder'.

   If you find something that you think might be a set function bug,
please report it to the Maxima bug database. See `bug_report'.

38.1.4 Authors
--------------

Stavros Macrakis of Cambridge, Massachusetts and Barton Willis of the
University of Nebraska at Kearney (UNK) wrote the Maxima set functions
and their documentation.


File: maxima.info,  Node: Functions and Variables for Sets,  Prev: Introduction to Sets,  Up: Sets

38.2 Functions and Variables for Sets
=====================================

 -- Function: adjoin (<x>, <a>)
     Returns the union of the set <a> with `{<x>}'.

     `adjoin' complains if <a> is not a literal set.

     `adjoin(<x>, <a>)' and `union(set(<x>), <a>)' are equivalent;
     however, `adjoin' may be somewhat faster than `union'.

     See also `disjoin'.

     Examples:

          (%i1) adjoin (c, {a, b});
          (%o1)                       {a, b, c}
          (%i2) adjoin (a, {a, b});
          (%o2)                        {a, b}


 -- Function: belln (<n>)
     Represents the n-th Bell number.  `belln(n)' is the number of
     partitions of a set with <n> members.

     For nonnegative integers <n>, `belln(<n>)' simplifies to the n-th
     Bell number.  `belln' does not simplify for any other arguments.

     `belln' distributes over equations, lists, matrices, and sets.

     Examples:

     `belln' applied to nonnegative integers.

          (%i1) makelist (belln (i), i, 0, 6);
          (%o1)               [1, 1, 2, 5, 15, 52, 203]
          (%i2) is (cardinality (set_partitions ({})) = belln (0));
          (%o2)                         true
          (%i3) is (cardinality (set_partitions ({1, 2, 3, 4, 5, 6})) =
                                 belln (6));
          (%o3)                         true

     `belln' applied to arguments which are not nonnegative integers.

          (%i1) [belln (x), belln (sqrt(3)), belln (-9)];
          (%o1)        [belln(x), belln(sqrt(3)), belln(- 9)]


 -- Function: cardinality (<a>)
     Returns the number of distinct elements of the set <a>.

     `cardinality' ignores redundant elements even when simplification
     is disabled.

     Examples:

          (%i1) cardinality ({});
          (%o1)                           0
          (%i2) cardinality ({a, a, b, c});
          (%o2)                           3
          (%i3) simp : false;
          (%o3)                         false
          (%i4) cardinality ({a, a, b, c});
          (%o4)                           3


 -- Function: cartesian_product (<b_1>, ... , <b_n>)
     Returns a set of lists of the form `[<x_1>, ..., <x_n>]', where
     <x_1>, ..., <x_n> are elements of the sets <b_1>, ... , <b_n>,
     respectively.

     `cartesian_product' complains if any argument is not a literal set.

     Examples:

          (%i1) cartesian_product ({0, 1});
          (%o1)                      {[0], [1]}
          (%i2) cartesian_product ({0, 1}, {0, 1});
          (%o2)           {[0, 0], [0, 1], [1, 0], [1, 1]}
          (%i3) cartesian_product ({x}, {y}, {z});
          (%o3)                      {[x, y, z]}
          (%i4) cartesian_product ({x}, {-1, 0, 1});
          (%o4)              {[x, - 1], [x, 0], [x, 1]}


 -- Function: disjoin (<x>, <a>)
     Returns the set <a> without the member <x>.  If <x> is not a
     member of <a>, return <a> unchanged.

     `disjoin' complains if <a> is not a literal set.

     `disjoin(<x>, <a>)', `delete(<x>, <a>)', and `setdifference(<a>,
     set(<x>))' are all equivalent.  Of these, `disjoin' is generally
     faster than the others.

     Examples:

          (%i1) disjoin (a, {a, b, c, d});
          (%o1)                       {b, c, d}
          (%i2) disjoin (a + b, {5, z, a + b, %pi});
          (%o2)                      {5, %pi, z}
          (%i3) disjoin (a - b, {5, z, a + b, %pi});
          (%o3)                  {5, %pi, b + a, z}


 -- Function: disjointp (<a>, <b>)
     Returns `true' if and only if the sets <a> and <b> are disjoint.

     `disjointp' complains if either <a> or <b> is not a literal set.

     Examples:

          (%i1) disjointp ({a, b, c}, {1, 2, 3});
          (%o1)                         true
          (%i2) disjointp ({a, b, 3}, {1, 2, 3});
          (%o2)                         false


 -- Function: divisors (<n>)
     Represents the set of divisors of <n>.

     `divisors(<n>)' simplifies to a set of integers when <n> is a
     nonzero integer.  The set of divisors includes the members 1 and
     <n>.  The divisors of a negative integer are the divisors of its
     absolute value.

     `divisors' distributes over equations, lists, matrices, and sets.

     Examples:

     We can verify that 28 is a perfect number: the sum of its divisors
     (except for itself) is 28.

          (%i1) s: divisors(28);
          (%o1)                 {1, 2, 4, 7, 14, 28}
          (%i2) lreduce ("+", args(s)) - 28;
          (%o2)                          28

     `divisors' is a simplifying function.  Substituting 8 for `a' in
     `divisors(a)' yields the divisors without reevaluating
     `divisors(8)'.

          (%i1) divisors (a);
          (%o1)                      divisors(a)
          (%i2) subst (8, a, %);
          (%o2)                     {1, 2, 4, 8}

     `divisors' distributes over equations, lists, matrices, and sets.

          (%i1) divisors (a = b);
          (%o1)               divisors(a) = divisors(b)
          (%i2) divisors ([a, b, c]);
          (%o2)        [divisors(a), divisors(b), divisors(c)]
          (%i3) divisors (matrix ([a, b], [c, d]));
                            [ divisors(a)  divisors(b) ]
          (%o3)             [                          ]
                            [ divisors(c)  divisors(d) ]
          (%i4) divisors ({a, b, c});
          (%o4)        {divisors(a), divisors(b), divisors(c)}


 -- Function: elementp (<x>, <a>)
     Returns `true' if and only if <x> is a member of the set <a>.

     `elementp' complains if <a> is not a literal set.

     Examples:

          (%i1) elementp (sin(1), {sin(1), sin(2), sin(3)});
          (%o1)                         true
          (%i2) elementp (sin(1), {cos(1), cos(2), cos(3)});
          (%o2)                         false


 -- Function: emptyp (<a>)
     Return `true' if and only if <a> is the empty set or the empty
     list.

     Examples:

          (%i1) map (emptyp, [{}, []]);
          (%o1)                     [true, true]
          (%i2) map (emptyp, [a + b, {{}}, %pi]);
          (%o2)                 [false, false, false]


 -- Function: equiv_classes (<s>, <F>)
     Returns a set of the equivalence classes of the set <s> with
     respect to the equivalence relation <F>.

     <F> is a function of two variables defined on the Cartesian
     product of <s> with <s>.  The return value of <F> is either `true'
     or `false', or an expression <expr> such that `is(<expr>)' is
     either `true' or `false'.

     When <F> is not an equivalence relation, `equiv_classes' accepts
     it without complaint, but the result is generally incorrect in
     that case.

     Examples:

     The equivalence relation is a lambda expression which returns
     `true' or `false'.

          (%i1) equiv_classes ({1, 1.0, 2, 2.0, 3, 3.0},
                                  lambda ([x, y], is (equal (x, y))));
          (%o1)            {{1, 1.0}, {2, 2.0}, {3, 3.0}}

     The equivalence relation is the name of a relational function
     which `is' evaluates to `true' or `false'.

          (%i1) equiv_classes ({1, 1.0, 2, 2.0, 3, 3.0}, equal);
          (%o1)            {{1, 1.0}, {2, 2.0}, {3, 3.0}}

     The equivalence classes are numbers which differ by a multiple of
     3.

          (%i1) equiv_classes ({1, 2, 3, 4, 5, 6, 7},
                               lambda ([x, y], remainder (x - y, 3) = 0));
          (%o1)              {{1, 4, 7}, {2, 5}, {3, 6}}


 -- Function: every (<f>, <s>)
 -- Function: every (<f>, <L_1>, ..., <L_n>)
     Returns `true' if the predicate <f> is `true' for all given
     arguments.

     Given one set as the second argument, `every(<f>, <s>)' returns
     `true' if `is(<f>(<a_i>))' returns `true' for all <a_i> in <s>.
     `every' may or may not evaluate <f> for all <a_i> in <s>.  Since
     sets are unordered, `every' may evaluate `<f>(<a_i>)' in any order.

     Given one or more lists as arguments, `every(<f>, <L_1>, ...,
     <L_n>)' returns `true' if `is(<f>(<x_1>, ..., <x_n>))' returns
     `true' for all <x_1>, ..., <x_n> in <L_1>, ..., <L_n>,
     respectively.  `every' may or may not evaluate <f> for every
     combination <x_1>, ..., <x_n>.  `every' evaluates lists in the
     order of increasing index.

     Given an empty set `{}' or empty lists `[]' as arguments, `every'
     returns `false'.

     When the global flag `maperror' is `true', all lists <L_1>, ...,
     <L_n> must have equal lengths.  When `maperror' is `false', list
     arguments are effectively truncated to the length of the shortest
     list.

     Return values of the predicate <f> which evaluate (via `is') to
     something other than `true' or `false' are governed by the global
     flag `prederror'.  When `prederror' is `true', such values are
     treated as `false', and the return value from `every' is `false'.
     When `prederror' is `false', such values are treated as `unknown',
     and the return value from `every' is `unknown'.

     Examples:

     `every' applied to a single set.  The predicate is a function of
     one argument.

          (%i1) every (integerp, {1, 2, 3, 4, 5, 6});
          (%o1)                         true
          (%i2) every (atom, {1, 2, sin(3), 4, 5 + y, 6});
          (%o2)                         false

     `every' applied to two lists.  The predicate is a function of two
     arguments.

          (%i1) every ("=", [a, b, c], [a, b, c]);
          (%o1)                         true
          (%i2) every ("#", [a, b, c], [a, b, c]);
          (%o2)                         false

     Return values of the predicate <f> which evaluate to something
     other than `true' or `false' are governed by the global flag
     `prederror'.

          (%i1) prederror : false;
          (%o1)                         false
          (%i2) map (lambda ([a, b], is (a < b)), [x, y, z],
                             [x^2, y^2, z^2]);
          (%o2)              [unknown, unknown, unknown]
          (%i3) every ("<", [x, y, z], [x^2, y^2, z^2]);
          (%o3)                        unknown
          (%i4) prederror : true;
          (%o4)                         true
          (%i5) every ("<", [x, y, z], [x^2, y^2, z^2]);
          (%o5)                         false


 -- Function: extremal_subset (<s>, <f>, max)
 -- Function: extremal_subset (<s>, <f>, min)
     Returns the subset of <s> for which the function <f> takes on
     maximum or minimum values.

     `extremal_subset(<s>, <f>, max)' returns the subset of the set or
     list <s> for which the real-valued function <f> takes on its
     maximum value.

     `extremal_subset(<s>, <f>, min)' returns the subset of the set or
     list <s> for which the real-valued function <f> takes on its
     minimum value.

     Examples:

          (%i1) extremal_subset ({-2, -1, 0, 1, 2}, abs, max);
          (%o1)                       {- 2, 2}
          (%i2) extremal_subset ({sqrt(2), 1.57, %pi/2}, sin, min);
          (%o2)                       {sqrt(2)}


 -- Function: flatten (<expr>)
     Collects arguments of subexpressions which have the same operator
     as <expr> and constructs an expression from these collected
     arguments.

     Subexpressions in which the operator is different from the main
     operator of `expr' are copied without modification, even if they,
     in turn, contain some subexpressions in which the operator is the
     same as for `expr'.

     It may be possible for `flatten' to construct expressions in which
     the number of arguments differs from the declared arguments for an
     operator; this may provoke an error message from the simplifier or
     evaluator.  `flatten' does not try to detect such situations.

     Expressions with special representations, for example, canonical
     rational expressions (CRE), cannot be flattened; in such cases,
     `flatten' returns its argument unchanged.

     Examples:

     Applied to a list, `flatten' gathers all list elements that are
     lists.

          (%i1) flatten ([a, b, [c, [d, e], f], [[g, h]], i, j]);
          (%o1)            [a, b, c, d, e, f, g, h, i, j]

     Applied to a set, `flatten' gathers all members of set elements
     that are sets.

          (%i1) flatten ({a, {b}, {{c}}});
          (%o1)                       {a, b, c}
          (%i2) flatten ({a, {[a], {a}}});
          (%o2)                       {a, [a]}

     `flatten' is similar to the effect of declaring the main operator
     n-ary.  However, `flatten' has no effect on subexpressions which
     have an operator different from the main operator, while an n-ary
     declaration affects those.

          (%i1) expr: flatten (f (g (f (f (x)))));
          (%o1)                     f(g(f(f(x))))
          (%i2) declare (f, nary);
          (%o2)                         done
          (%i3) ev (expr);
          (%o3)                      f(g(f(x)))

     `flatten' treats subscripted functions the same as any other
     operator.

          (%i1) flatten (f[5] (f[5] (x, y), z));
          (%o1)                      f (x, y, z)
                                      5

     It may be possible for `flatten' to construct expressions in which
     the number of arguments differs from the declared arguments for an
     operator;

          (%i1) 'mod (5, 'mod (7, 4));
          (%o1)                   mod(5, mod(7, 4))
          (%i2) flatten (%);
          (%o2)                     mod(5, 7, 4)
          (%i3) ''%, nouns;
          Wrong number of arguments to mod
           -- an error.  Quitting.  To debug this try debugmode(true);


 -- Function: full_listify (<a>)
     Replaces every set operator in <a> by a list operator, and returns
     the result.  `full_listify' replaces set operators in nested
     subexpressions, even if the main operator is not `set'.

     `listify' replaces only the main operator.

     Examples:

          (%i1) full_listify ({a, b, {c, {d, e, f}, g}});
          (%o1)               [a, b, [c, [d, e, f], g]]
          (%i2) full_listify (F (G ({a, b, H({c, d, e})})));
          (%o2)              F(G([a, b, H([c, d, e])]))


 -- Function: fullsetify (<a>)
     When <a> is a list, replaces the list operator with a set operator,
     and applies `fullsetify' to each member which is a set.  When <a>
     is not a list, it is returned unchanged.

     `setify' replaces only the main operator.

     Examples:

     In line `(%o2)', the argument of `f' isn't converted to a set
     because the main operator of `f([b])' isn't a list.

          (%i1) fullsetify ([a, [a]]);
          (%o1)                       {a, {a}}
          (%i2) fullsetify ([a, f([b])]);
          (%o2)                      {a, f([b])}


 -- Function: identity (<x>)
     Returns <x> for any argument <x>.

     Examples:

     `identity' may be used as a predicate when the arguments are
     already Boolean values.

          (%i1) every (identity, [true, true]);
          (%o1)                         true

 -- Function: integer_partitions (<n>)
 -- Function: integer_partitions (<n>, <len>)
     Returns integer partitions of <n>, that is, lists of integers
     which sum to <n>.

     `integer_partitions(<n>)' returns the set of all partitions of the
     integer <n>.  Each partition is a list sorted from greatest to
     least.

     `integer_partitions(<n>, <len>)' returns all partitions that have
     length <len> or less; in this case, zeros are appended to each
     partition with fewer than <len> terms to make each partition have
     exactly <len> terms.  Each partition is a list sorted from
     greatest to least.

     A list [a_1, ..., a_m] is a partition of a nonnegative integer n
     when (1) each a_i is a nonzero integer, and (2) a_1 + ... + a_m =
     n. Thus 0 has no partitions.

     Examples:

          (%i1) integer_partitions (3);
          (%o1)               {[1, 1, 1], [2, 1], [3]}
          (%i2) s: integer_partitions (25)$
          (%i3) cardinality (s);
          (%o3)                         1958
          (%i4) map (lambda ([x], apply ("+", x)), s);
          (%o4)                         {25}
          (%i5) integer_partitions (5, 3);
          (%o5) {[2, 2, 1], [3, 1, 1], [3, 2, 0], [4, 1, 0], [5, 0, 0]}
          (%i6) integer_partitions (5, 2);
          (%o6)               {[3, 2], [4, 1], [5, 0]}

     To find all partitions that satisfy a condition, use the function
     `subset'; here is an example that finds all partitions of 10 that
     consist of prime numbers.

          (%i1) s: integer_partitions (10)$
          (%i2) cardinality (s);
          (%o2)                          42
          (%i3) xprimep(x) := integerp(x) and (x > 1) and primep(x)$
          (%i4) subset (s, lambda ([x], every (xprimep, x)));
          (%o4) {[2, 2, 2, 2, 2], [3, 3, 2, 2], [5, 3, 2], [5, 5], [7, 3]}


 -- Function: intersect (<a_1>, ..., <a_n>)
     `intersect' is the same as `intersection', which see.


 -- Function: intersection (<a_1>, ..., <a_n>)
     Returns a set containing the elements that are common to the sets
     <a_1> through <a_n>.

     `intersection' complains if any argument is not a literal set.

     Examples:

          (%i1) S_1 : {a, b, c, d};
          (%o1)                     {a, b, c, d}
          (%i2) S_2 : {d, e, f, g};
          (%o2)                     {d, e, f, g}
          (%i3) S_3 : {c, d, e, f};
          (%o3)                     {c, d, e, f}
          (%i4) S_4 : {u, v, w};
          (%o4)                       {u, v, w}
          (%i5) intersection (S_1, S_2);
          (%o5)                          {d}
          (%i6) intersection (S_2, S_3);
          (%o6)                       {d, e, f}
          (%i7) intersection (S_1, S_2, S_3);
          (%o7)                          {d}
          (%i8) intersection (S_1, S_2, S_3, S_4);
          (%o8)                          {}


 -- Function: kron_delta (<x>, <y>)
     Represents the Kronecker delta function.

     `kron_delta' simplifies to 1 when <x> and <y> are identical or
     demonstrably equivalent, and it simplifies to 0 when <x> and <y>
     are demonstrably not equivalent.  Otherwise, it is not certain
     whether <x> and <y> are equivalent, and `kron_delta' simplifies to
     a noun expression.  `kron_delta' implements a cautious policy with
     respect to floating point expressions: if the difference `<x> -
     <y>' is a floating point number, `kron_delta' simplifies to a noun
     expression when <x> is apparently equivalent to <y>.

     Specifically, `kron_delta(<x>, <y>)' simplifies to 1 when `is(x =
     y)' is `true'.  `kron_delta' also simplifies to 1 when
     `sign(abs(<x> - <y>))' is `zero' and `<x> - <y>' is not a floating
     point number (neither an ordinary float nor a bigfloat).
     `kron_delta' simplifies to 0 when `sign(abs(<x> - <y>))' is `pos'.

     Otherwise, `sign(abs(<x> - <y>))' is something other than `pos' or
     `zero', or it is `zero' and `<x> - <y>' is a floating point number.
     In these cases, `kron_delta' returns a noun expression.

     `kron_delta' is declared to be symmetric.  That is,
     `kron_delta(<x>, <y>)' is equal to `kron_delta(<y>, <x>)'.

     Examples:

     The arguments of `kron_delta' are identical.  `kron_delta'
     simplifies to 1.

          (%i1) kron_delta (a, a);
          (%o1)                           1
          (%i2) kron_delta (x^2 - y^2, x^2 - y^2);
          (%o2)                           1
          (%i3) float (kron_delta (1/10, 0.1));
          (%o3)                           1

     The arguments of `kron_delta' are equivalent, and their difference
     is not a floating point number.  `kron_delta' simplifies to 1.

          (%i1) assume (equal (x, y));
          (%o1)                     [equal(x, y)]
          (%i2) kron_delta (x, y);
          (%o2)                           1

     The arguments of `kron_delta' are not equivalent.  `kron_delta'
     simplifies to 0.

          (%i1) kron_delta (a + 1, a);
          (%o1)                           0
          (%i2) assume (a > b)$
          (%i3) kron_delta (a, b);
          (%o3)                           0
          (%i4) kron_delta (1/5, 0.7);
          (%o4)                           0

     The arguments of `kron_delta' might or might not be equivalent.
     `kron_delta' simplifies to a noun expression.

          (%i1) kron_delta (a, b);
          (%o1)                   kron_delta(a, b)
          (%i2) assume(x >= y)$
          (%i3) kron_delta (x, y);
          (%o3)                   kron_delta(x, y)

     The arguments of `kron_delta' are equivalent, but their difference
     is a floating point number.  `kron_delta' simplifies to a noun
     expression.

          (%i1) 1/4 - 0.25;
          (%o1)                          0.0
          (%i2) 1/10 - 0.1;
          (%o2)                          0.0
          (%i3) 0.25 - 0.25b0;
          Warning:  Float to bigfloat conversion of 0.25
          (%o3)                         0.0b0
          (%i4) kron_delta (1/4, 0.25);
                                            1
          (%o4)                  kron_delta(-, 0.25)
                                            4
          (%i5) kron_delta (1/10, 0.1);
                                            1
          (%o5)                  kron_delta(--, 0.1)
                                            10
          (%i6) kron_delta (0.25, 0.25b0);
          Warning:  Float to bigfloat conversion of 0.25
          (%o6)               kron_delta(0.25, 2.5b-1)

     `kron_delta' is symmetric.

          (%i1) kron_delta (x, y);
          (%o1)                   kron_delta(x, y)
          (%i2) kron_delta (y, x);
          (%o2)                   kron_delta(x, y)
          (%i3) kron_delta (x, y) - kron_delta (y, x);
          (%o3)                           0
          (%i4) is (equal (kron_delta (x, y), kron_delta (y, x)));
          (%o4)                         true
          (%i5) is (kron_delta (x, y) = kron_delta (y, x));
          (%o5)                         true


 -- Function: listify (<a>)
     Returns a list containing the members of <a> when <a> is a set.
     Otherwise, `listify' returns <a>.

     `full_listify' replaces all set operators in <a> by list operators.

     Examples:

          (%i1) listify ({a, b, c, d});
          (%o1)                     [a, b, c, d]
          (%i2) listify (F ({a, b, c, d}));
          (%o2)                    F({a, b, c, d})


 -- Function: lreduce (<F>, <s>)
 -- Function: lreduce (<F>, <s>, <s_0>)
     Extends the binary function <F> to an n-ary function by
     composition, where <s> is a list.

     `lreduce(<F>, <s>)' returns `F(... F(F(s_1, s_2), s_3), ... s_n)'.
     When the optional argument <s_0> is present, the result is
     equivalent to `lreduce(<F>, cons(<s_0>, <s>))'.

     The function <F> is first applied to the leftmost list elements,
     thus the name "lreduce".

     See also `rreduce', `xreduce', and `tree_reduce'.

     Examples:

     `lreduce' without the optional argument.

          (%i1) lreduce (f, [1, 2, 3]);
          (%o1)                     f(f(1, 2), 3)
          (%i2) lreduce (f, [1, 2, 3, 4]);
          (%o2)                  f(f(f(1, 2), 3), 4)

     `lreduce' with the optional argument.

          (%i1) lreduce (f, [1, 2, 3], 4);
          (%o1)                  f(f(f(4, 1), 2), 3)

     `lreduce' applied to built-in binary operators.  `/' is the
     division operator.

          (%i1) lreduce ("^", args ({a, b, c, d}));
                                         b c d
          (%o1)                       ((a ) )
          (%i2) lreduce ("/", args ({a, b, c, d}));
                                          a
          (%o2)                         -----
                                        b c d


 -- Function: makeset (<expr>, <x>, <s>)
     Returns a set with members generated from the expression <expr>,
     where <x> is a list of variables in <expr>, and <s> is a set or
     list of lists.  To generate each set member, <expr> is evaluated
     with the variables <x> bound in parallel to a member of <s>.

     Each member of <s> must have the same length as <x>.  The list of
     variables <x> must be a list of symbols, without subscripts.  Even
     if there is only one symbol, <x> must be a list of one element,
     and each member of <s> must be a list of one element.

     See also `makelist'.

     Examples:

          (%i1) makeset (i/j, [i, j], [[1, a], [2, b], [3, c], [4, d]]);
                                     1  2  3  4
          (%o1)                     {-, -, -, -}
                                     a  b  c  d
          (%i2) S : {x, y, z}$
          (%i3) S3 : cartesian_product (S, S, S);
          (%o3) {[x, x, x], [x, x, y], [x, x, z], [x, y, x], [x, y, y],
          [x, y, z], [x, z, x], [x, z, y], [x, z, z], [y, x, x],
          [y, x, y], [y, x, z], [y, y, x], [y, y, y], [y, y, z],
          [y, z, x], [y, z, y], [y, z, z], [z, x, x], [z, x, y],
          [z, x, z], [z, y, x], [z, y, y], [z, y, z], [z, z, x],
          [z, z, y], [z, z, z]}
          (%i4) makeset (i + j + k, [i, j, k], S3);
          (%o4) {3 x, 3 y, y + 2 x, 2 y + x, 3 z, z + 2 x, z + y + x,
                                                 z + 2 y, 2 z + x, 2 z + y}
          (%i5) makeset (sin(x), [x], {[1], [2], [3]});
          (%o5)               {sin(1), sin(2), sin(3)}


 -- Function: moebius (<n>)
     Represents the Moebius function.

     When <n> is product of k distinct primes, `moebius(<n>)'
     simplifies to (-1)^k; when <n> = 1, it simplifies to 1; and it
     simplifies to 0 for all other positive integers.

     `moebius' distributes over equations, lists, matrices, and sets.

     Examples:

          (%i1) moebius (1);
          (%o1)                           1
          (%i2) moebius (2 * 3 * 5);
          (%o2)                          - 1
          (%i3) moebius (11 * 17 * 29 * 31);
          (%o3)                           1
          (%i4) moebius (2^32);
          (%o4)                           0
          (%i5) moebius (n);
          (%o5)                      moebius(n)
          (%i6) moebius (n = 12);
          (%o6)                    moebius(n) = 0
          (%i7) moebius ([11, 11 * 13, 11 * 13 * 15]);
          (%o7)                      [- 1, 1, 1]
          (%i8) moebius (matrix ([11, 12], [13, 14]));
                                     [ - 1  0 ]
          (%o8)                      [        ]
                                     [ - 1  1 ]
          (%i9) moebius ({21, 22, 23, 24});
          (%o9)                      {- 1, 0, 1}


 -- Function: multinomial_coeff (<a_1>, ..., <a_n>)
 -- Function: multinomial_coeff ()
     Returns the multinomial coefficient.

     When each <a_k> is a nonnegative integer, the multinomial
     coefficient gives the number of ways of placing `<a_1> + ... +
     <a_n>' distinct objects into n boxes with <a_k> elements in the
     k'th box. In general, `multinomial_coeff (<a_1>, ..., <a_n>)'
     evaluates to `(<a_1> + ... + <a_n>)!/(<a_1>! ... <a_n>!)'.

     `multinomial_coeff()' (with no arguments) evaluates to 1.

     `minfactorial' may be able to simplify the value returned by
     `multinomial_coeff'.

     Examples:

          (%i1) multinomial_coeff (1, 2, x);
                                      (x + 3)!
          (%o1)                       --------
                                        2 x!
          (%i2) minfactorial (%);
                               (x + 1) (x + 2) (x + 3)
          (%o2)                -----------------------
                                          2
          (%i3) multinomial_coeff (-6, 2);
                                       (- 4)!
          (%o3)                       --------
                                      2 (- 6)!
          (%i4) minfactorial (%);
          (%o4)                          10


 -- Function: num_distinct_partitions (<n>)
 -- Function: num_distinct_partitions (<n>, list)
     Returns the number of distinct integer partitions of <n> when <n>
     is a nonnegative integer.  Otherwise, `num_distinct_partitions'
     returns a noun expression.

     `num_distinct_partitions(<n>, list)' returns a list of the number
     of distinct partitions of 1, 2, 3, ..., <n>.

     A distinct partition of <n> is a list of distinct positive
     integers k_1, ..., k_m such that <n> = k_1 + ... + k_m.

     Examples:

          (%i1) num_distinct_partitions (12);
          (%o1)                          15
          (%i2) num_distinct_partitions (12, list);
          (%o2)      [1, 1, 1, 2, 2, 3, 4, 5, 6, 8, 10, 12, 15]
          (%i3) num_distinct_partitions (n);
          (%o3)              num_distinct_partitions(n)


 -- Function: num_partitions (<n>)
 -- Function: num_partitions (<n>, list)
     Returns the number of integer partitions of <n> when <n> is a
     nonnegative integer.  Otherwise, `num_partitions' returns a noun
     expression.

     `num_partitions(<n>, list)' returns a list of the number of
     integer partitions of 1, 2, 3, ..., <n>.

     For a nonnegative integer <n>, `num_partitions(<n>)' is equal to
     `cardinality(integer_partitions(<n>))'; however, `num_partitions'
     does not actually construct the set of partitions, so it is much
     faster.

     Examples:

          (%i1) num_partitions (5) = cardinality (integer_partitions (5));
          (%o1)                         7 = 7
          (%i2) num_partitions (8, list);
          (%o2)            [1, 1, 2, 3, 5, 7, 11, 15, 22]
          (%i3) num_partitions (n);
          (%o3)                   num_partitions(n)


 -- Function: partition_set (<a>, <f>)
     Partitions the set <a> according to the predicate <f>.

     `partition_set' returns a list of two sets.  The first set
     comprises the elements of <a> for which <f> evaluates to `false',
     and the second comprises any other elements of <a>.
     `partition_set' does not apply `is' to the return value of <f>.

     `partition_set' complains if <a> is not a literal set.

     See also `subset'.

     Examples:

          (%i1) partition_set ({2, 7, 1, 8, 2, 8}, evenp);
          (%o1)                   [{1, 7}, {2, 8}]
          (%i2) partition_set ({x, rat(y), rat(y) + z, 1},
                               lambda ([x], ratp(x)));
          (%o2)/R/              [{1, x}, {y, y + z}]


 -- Function: permutations (<a>)
     Returns a set of all distinct permutations of the members of the
     list or set <a>. Each permutation is a list, not a set.

     When <a> is a list, duplicate members of <a> are included in the
     permutations.

     `permutations' complains if <a> is not a literal list or set.

     See also `random_permutation'.

     Examples:

          (%i1) permutations ([a, a]);
          (%o1)                       {[a, a]}
          (%i2) permutations ([a, a, b]);
          (%o2)           {[a, a, b], [a, b, a], [b, a, a]}


 -- Function: powerset (<a>)
 -- Function: powerset (<a>, <n>)
     Returns the set of all subsets of <a>, or a subset of that set.

     `powerset(<a>)' returns the set of all subsets of the set <a>.
     `powerset(<a>)' has `2^cardinality(<a>)' members.

     `powerset(<a>, <n>)' returns the set of all subsets of <a> that
     have cardinality <n>.

     `powerset' complains if <a> is not a literal set, or if <n> is not
     a nonnegative integer.

     Examples:

          (%i1) powerset ({a, b, c});
          (%o1) {{}, {a}, {a, b}, {a, b, c}, {a, c}, {b}, {b, c}, {c}}
          (%i2) powerset ({w, x, y, z}, 4);
          (%o2)                    {{w, x, y, z}}
          (%i3) powerset ({w, x, y, z}, 3);
          (%o3)     {{w, x, y}, {w, x, z}, {w, y, z}, {x, y, z}}
          (%i4) powerset ({w, x, y, z}, 2);
          (%o4)   {{w, x}, {w, y}, {w, z}, {x, y}, {x, z}, {y, z}}
          (%i5) powerset ({w, x, y, z}, 1);
          (%o5)                 {{w}, {x}, {y}, {z}}
          (%i6) powerset ({w, x, y, z}, 0);
          (%o6)                         {{}}


 -- Function: random_permutation (<a>)
     Returns a random permutation of the set or list <a>, as
     constructed by the Knuth shuffle algorithm.

     The return value is a new list, which is distinct from the
     argument even if all elements happen to be the same.  However, the
     elements of the argument are not copied.

     Examples:

          (%i1) random_permutation ([a, b, c, 1, 2, 3]);
          (%o1)                  [c, 1, 2, 3, a, b]
          (%i2) random_permutation ([a, b, c, 1, 2, 3]);
          (%o2)                  [b, 3, 1, c, a, 2]
          (%i3) random_permutation ({x + 1, y + 2, z + 3});
          (%o3)                 [y + 2, z + 3, x + 1]
          (%i4) random_permutation ({x + 1, y + 2, z + 3});
          (%o4)                 [x + 1, y + 2, z + 3]


 -- Function: rreduce (<F>, <s>)
 -- Function: rreduce (<F>, <s>, <s_{n + 1}>)
     Extends the binary function <F> to an n-ary function by
     composition, where <s> is a list.

     `rreduce(<F>, <s>)' returns `F(s_1, ... F(s_{n - 2}, F(s_{n - 1},
     s_n)))'.  When the optional argument <s_{n + 1}> is present, the
     result is equivalent to `rreduce(<F>, endcons(<s_{n + 1}>, <s>))'.

     The function <F> is first applied to the rightmost list elements,
     thus the name "rreduce".

     See also `lreduce', `tree_reduce', and `xreduce'.

     Examples:

     `rreduce' without the optional argument.

          (%i1) rreduce (f, [1, 2, 3]);
          (%o1)                     f(1, f(2, 3))
          (%i2) rreduce (f, [1, 2, 3, 4]);
          (%o2)                  f(1, f(2, f(3, 4)))

     `rreduce' with the optional argument.

          (%i1) rreduce (f, [1, 2, 3], 4);
          (%o1)                  f(1, f(2, f(3, 4)))

     `rreduce' applied to built-in binary operators.  `/' is the
     division operator.

          (%i1) rreduce ("^", args ({a, b, c, d}));
                                           d
                                          c
                                         b
          (%o1)                         a
          (%i2) rreduce ("/", args ({a, b, c, d}));
                                         a c
          (%o2)                          ---
                                         b d


 -- Function: setdifference (<a>, <b>)
     Returns a set containing the elements in the set <a> that are not
     in the set <b>.

     `setdifference' complains if either <a> or <b> is not a literal
     set.

     Examples:

          (%i1) S_1 : {a, b, c, x, y, z};
          (%o1)                  {a, b, c, x, y, z}
          (%i2) S_2 : {aa, bb, c, x, y, zz};
          (%o2)                 {aa, bb, c, x, y, zz}
          (%i3) setdifference (S_1, S_2);
          (%o3)                       {a, b, z}
          (%i4) setdifference (S_2, S_1);
          (%o4)                     {aa, bb, zz}
          (%i5) setdifference (S_1, S_1);
          (%o5)                          {}
          (%i6) setdifference (S_1, {});
          (%o6)                  {a, b, c, x, y, z}
          (%i7) setdifference ({}, S_1);
          (%o7)                          {}


 -- Function: setequalp (<a>, <b>)
     Returns `true' if sets <a> and <b> have the same number of elements
     and `is(<x> = <y>)' is `true' for `x' in the elements of <a> and
     `y' in the elements of <b>, considered in the order determined by
     `listify'.  Otherwise, `setequalp' returns `false'.

     Examples:

          (%i1) setequalp ({1, 2, 3}, {1, 2, 3});
          (%o1)                         true
          (%i2) setequalp ({a, b, c}, {1, 2, 3});
          (%o2)                         false
          (%i3) setequalp ({x^2 - y^2}, {(x + y) * (x - y)});
          (%o3)                         false


 -- Function: setify (<a>)
     Constructs a set from the elements of the list <a>. Duplicate
     elements of the list <a> are deleted and the elements are sorted
     according to the predicate `orderlessp'.

     `setify' complains if <a> is not a literal list.

     Examples:

          (%i1) setify ([1, 2, 3, a, b, c]);
          (%o1)                  {1, 2, 3, a, b, c}
          (%i2) setify ([a, b, c, a, b, c]);
          (%o2)                       {a, b, c}
          (%i3) setify ([7, 13, 11, 1, 3, 9, 5]);
          (%o3)                {1, 3, 5, 7, 9, 11, 13}


 -- Function: setp (<a>)
     Returns `true' if and only if <a> is a Maxima set.

     `setp' returns `true' for unsimplified sets (that is, sets with
     redundant members) as well as simplified sets.

     `setp' is equivalent to the Maxima function `setp(a) := not
     atom(a) and op(a) = 'set'.

     Examples:

          (%i1) simp : false;
          (%o1)                         false
          (%i2) {a, a, a};
          (%o2)                       {a, a, a}
          (%i3) setp (%);
          (%o3)                         true


 -- Function: set_partitions (<a>)
 -- Function: set_partitions (<a>, <n>)
     Returns the set of all partitions of <a>, or a subset of that set.

     `set_partitions(<a>, <n>)' returns a set of all decompositions of
     <a> into <n> nonempty disjoint subsets.

     `set_partitions(<a>)' returns the set of all partitions.

     `stirling2' returns the cardinality of the set of partitions of a
     set.

     A set of sets P is a partition of a set S when

       1. each member of P is a nonempty set,

       2. distinct members of P are disjoint,

       3. the union of the members of P equals S.

     Examples:

     The empty set is a partition of itself, the conditions 1 and 2
     being vacuously true.

          (%i1) set_partitions ({});
          (%o1)                         {{}}

     The cardinality of the set of partitions of a set can be found
     using `stirling2'.

          (%i1) s: {0, 1, 2, 3, 4, 5}$
          (%i2) p: set_partitions (s, 3)$
          (%i3) cardinality(p) = stirling2 (6, 3);
          (%o3)                        90 = 90

     Each member of `p' should have <n> = 3 members; let's check.

          (%i1) s: {0, 1, 2, 3, 4, 5}$
          (%i2) p: set_partitions (s, 3)$
          (%i3) map (cardinality, p);
          (%o3)                          {3}

     Finally, for each member of `p', the union of its members should
     equal `s'; again let's check.

          (%i1) s: {0, 1, 2, 3, 4, 5}$
          (%i2) p: set_partitions (s, 3)$
          (%i3) map (lambda ([x], apply (union, listify (x))), p);
          (%o3)                 {{0, 1, 2, 3, 4, 5}}


 -- Function: some (<f>, <a>)
 -- Function: some (<f>, <L_1>, ..., <L_n>)
     Returns `true' if the predicate <f> is `true' for one or more
     given arguments.

     Given one set as the second argument, `some(<f>, <s>)' returns
     `true' if `is(<f>(<a_i>))' returns `true' for one or more <a_i> in
     <s>.  `some' may or may not evaluate <f> for all <a_i> in <s>.
     Since sets are unordered, `some' may evaluate `<f>(<a_i>)' in any
     order.

     Given one or more lists as arguments, `some(<f>, <L_1>, ...,
     <L_n>)' returns `true' if `is(<f>(<x_1>, ..., <x_n>))' returns
     `true' for one or more <x_1>, ..., <x_n> in <L_1>, ..., <L_n>,
     respectively.  `some' may or may not evaluate <f> for some
     combinations <x_1>, ..., <x_n>.  `some' evaluates lists in the
     order of increasing index.

     Given an empty set `{}' or empty lists `[]' as arguments, `some'
     returns `false'.

     When the global flag `maperror' is `true', all lists <L_1>, ...,
     <L_n> must have equal lengths.  When `maperror' is `false', list
     arguments are effectively truncated to the length of the shortest
     list.

     Return values of the predicate <f> which evaluate (via `is') to
     something other than `true' or `false' are governed by the global
     flag `prederror'.  When `prederror' is `true', such values are
     treated as `false'.  When `prederror' is `false', such values are
     treated as `unknown'.

     Examples:

     `some' applied to a single set.  The predicate is a function of
     one argument.

          (%i1) some (integerp, {1, 2, 3, 4, 5, 6});
          (%o1)                         true
          (%i2) some (atom, {1, 2, sin(3), 4, 5 + y, 6});
          (%o2)                         true

     `some' applied to two lists.  The predicate is a function of two
     arguments.

          (%i1) some ("=", [a, b, c], [a, b, c]);
          (%o1)                         true
          (%i2) some ("#", [a, b, c], [a, b, c]);
          (%o2)                         false

     Return values of the predicate <f> which evaluate to something
     other than `true' or `false' are governed by the global flag
     `prederror'.

          (%i1) prederror : false;
          (%o1)                         false
          (%i2) map (lambda ([a, b], is (a < b)), [x, y, z],
                     [x^2, y^2, z^2]);
          (%o2)              [unknown, unknown, unknown]
          (%i3) some ("<", [x, y, z], [x^2, y^2, z^2]);
          (%o3)                        unknown
          (%i4) some ("<", [x, y, z], [x^2, y^2, z + 1]);
          (%o4)                         true
          (%i5) prederror : true;
          (%o5)                         true
          (%i6) some ("<", [x, y, z], [x^2, y^2, z^2]);
          (%o6)                         false
          (%i7) some ("<", [x, y, z], [x^2, y^2, z + 1]);
          (%o7)                         true


 -- Function: stirling1 (<n>, <m>)
     Represents the Stirling number of the first kind.

     When <n> and <m> are nonnegative integers, the magnitude of
     `stirling1 (<n>, <m>)' is the number of permutations of a set with
     <n> members that have <m> cycles.  For details, see Graham, Knuth
     and Patashnik Concrete Mathematics.  Maxima uses a recursion
     relation to define `stirling1 (<n>, <m>)' for <m> less than 0; it
     is undefined for <n> less than 0 and for non-integer arguments.

     `stirling1' is a simplifying function.  Maxima knows the following
     identities.

       1. stirling1(0, n) = kron_delta(0, n) (Ref. [1])

       2. stirling1(n, n) = 1 (Ref. [1])

       3. stirling1(n, n - 1) = binomial(n, 2) (Ref. [1])

       4. stirling1(n + 1, 0) = 0 (Ref. [1])

       5. stirling1(n + 1, 1) = n! (Ref. [1])

       6. stirling1(n + 1, 2) = 2^n  - 1 (Ref. [1])

     These identities are applied when the arguments are literal
     integers or symbols declared as integers, and the first argument
     is nonnegative.  `stirling1' does not simplify for non-integer
     arguments.

     References:

     [1] Donald Knuth, The Art of Computer Programming, third edition,
     Volume 1, Section 1.2.6, Equations 48, 49, and 50.

     Examples:

          (%i1) declare (n, integer)$
          (%i2) assume (n >= 0)$
          (%i3) stirling1 (n, n);
          (%o3)                           1

     `stirling1' does not simplify for non-integer arguments.

          (%i1) stirling1 (sqrt(2), sqrt(2));
          (%o1)              stirling1(sqrt(2), sqrt(2))

     Maxima applies identities to `stirling1'.

          (%i1) declare (n, integer)$
          (%i2) assume (n >= 0)$
          (%i3) stirling1 (n + 1, n);
                                      n (n + 1)
          (%o3)                       ---------
                                          2
          (%i4) stirling1 (n + 1, 1);
          (%o4)                          n!


 -- Function: stirling2 (<n>, <m>)
     Represents the Stirling number of the second kind.

     When <n> and <m> are nonnegative integers, `stirling2 (<n>, <m>)'
     is the number of ways a set with cardinality <n> can be
     partitioned into <m> disjoint subsets.  Maxima uses a recursion
     relation to define `stirling2 (<n>, <m>)' for <m> less than 0; it
     is undefined for <n> less than 0 and for non-integer arguments.

     `stirling2' is a simplifying function.  Maxima knows the following
     identities.

       1. stirling2(0, n) = kron_delta(0, n) (Ref. [1])

       2. stirling2(n, n) = 1 (Ref. [1])

       3. stirling2(n, n - 1) = binomial(n, 2) (Ref. [1])

       4. stirling2(n + 1, 1) = 1 (Ref. [1])

       5. stirling2(n + 1, 2) = 2^n  - 1 (Ref. [1])

       6. stirling2(n, 0) = kron_delta(n, 0) (Ref. [2])

       7. stirling2(n, m) = 0 when m > n (Ref. [2])

       8. stirling2(n, m) = sum((-1)^(m - k) binomial(m k) k^n,i,1,m) /
          m!  when m and n are integers, and n is nonnegative. (Ref.
          [3])

     These identities are applied when the arguments are literal
     integers or symbols declared as integers, and the first argument
     is nonnegative.  `stirling2' does not simplify for non-integer
     arguments.

     References:

     [1] Donald Knuth. The Art of Computer Programming, third edition,
     Volume 1, Section 1.2.6, Equations 48, 49, and 50.

     [2] Graham, Knuth, and Patashnik. Concrete Mathematics, Table 264.

     [3] Abramowitz and Stegun. Handbook of Mathematical Functions,
     Section 24.1.4.

     Examples:

          (%i1) declare (n, integer)$
          (%i2) assume (n >= 0)$
          (%i3) stirling2 (n, n);
          (%o3)                           1

     `stirling2' does not simplify for non-integer arguments.

          (%i1) stirling2 (%pi, %pi);
          (%o1)                  stirling2(%pi, %pi)

     Maxima applies identities to `stirling2'.

          (%i1) declare (n, integer)$
          (%i2) assume (n >= 0)$
          (%i3) stirling2 (n + 9, n + 8);
                                   (n + 8) (n + 9)
          (%o3)                    ---------------
                                          2
          (%i4) stirling2 (n + 1, 2);
                                        n
          (%o4)                        2  - 1


 -- Function: subset (<a>, <f>)
     Returns the subset of the set <a> that satisfies the predicate <f>.

     `subset' returns a set which comprises the elements of <a> for
     which <f> returns anything other than `false'.  `subset' does not
     apply `is' to the return value of <f>.

     `subset' complains if <a> is not a literal set.

     See also `partition_set'.

     Examples:

          (%i1) subset ({1, 2, x, x + y, z, x + y + z}, atom);
          (%o1)                     {1, 2, x, z}
          (%i2) subset ({1, 2, 7, 8, 9, 14}, evenp);
          (%o2)                      {2, 8, 14}


 -- Function: subsetp (<a>, <b>)
     Returns `true' if and only if the set <a> is a subset of <b>.

     `subsetp' complains if either <a> or <b> is not a literal set.

     Examples:

          (%i1) subsetp ({1, 2, 3}, {a, 1, b, 2, c, 3});
          (%o1)                         true
          (%i2) subsetp ({a, 1, b, 2, c, 3}, {1, 2, 3});
          (%o2)                         false


 -- Function: symmdifference (<a_1>, ..., <a_n>)
     Returns the symmetric difference, that is, the set of members that
     occur in exactly one set <a_k>.

     Given two arguments, `symmdifference ( <a>, <b>)' is the same as
     `union ( setdifference ( <a>, <b>), setdifference(<b>, <a>))'.

     `symmdifference' complains if any argument is not a literal set.

     Examples:

          (%i1) S_1 : {a, b, c};
          (%o1)                       {a, b, c}
          (%i2) S_2 : {1, b, c};
          (%o2)                       {1, b, c}
          (%i3) S_3 : {a, b, z};
          (%o3)                       {a, b, z}
          (%i4) symmdifference ();
          (%o4)                          {}
          (%i5) symmdifference (S_1);
          (%o5)                       {a, b, c}
          (%i6) symmdifference (S_1, S_2);
          (%o6)                        {1, a}
          (%i7) symmdifference (S_1, S_2, S_3);
          (%o7)                        {1, z}
          (%i8) symmdifference ({}, S_1, S_2, S_3);
          (%o8)                        {1, z}


 -- Function: tree_reduce (<F>, <s>)
 -- Function: tree_reduce (<F>, <s>, <s_0>)
     Extends the binary function <F> to an n-ary function by
     composition, where <s> is a set or list.

     `tree_reduce' is equivalent to the following: Apply <F> to
     successive pairs of elements to form a new list `[<F>(<s_1>,
     <s_2>), <F>(<s_3>, <s_4>), ...]', carrying the final element
     unchanged if there are an odd number of elements.  Then repeat
     until the list is reduced to a single element, which is the return
     value.

     When the optional argument <s_0> is present, the result is
     equivalent `tree_reduce(<F>, cons(<s_0>, <s>)'.

     For addition of floating point numbers, `tree_reduce' may return a
     sum that has a smaller rounding error than either `rreduce' or
     `lreduce'.

     The elements of <s> and the partial results may be arranged in a
     minimum-depth binary tree, thus the name "tree_reduce".

     Examples:

     `tree_reduce' applied to a list with an even number of elements.

          (%i1) tree_reduce (f, [a, b, c, d]);
          (%o1)                  f(f(a, b), f(c, d))

     `tree_reduce' applied to a list with an odd number of elements.

          (%i1) tree_reduce (f, [a, b, c, d, e]);
          (%o1)               f(f(f(a, b), f(c, d)), e)


 -- Function: union (<a_1>, ..., <a_n>)
     Returns the union of the sets <a_1> through <a_n>.

     `union()' (with no arguments) returns the empty set.

     `union' complains if any argument is not a literal set.

     Examples:

          (%i1) S_1 : {a, b, c + d, %e};
          (%o1)                   {%e, a, b, d + c}
          (%i2) S_2 : {%pi, %i, %e, c + d};
          (%o2)                 {%e, %i, %pi, d + c}
          (%i3) S_3 : {17, 29, 1729, %pi, %i};
          (%o3)                {17, 29, 1729, %i, %pi}
          (%i4) union ();
          (%o4)                          {}
          (%i5) union (S_1);
          (%o5)                   {%e, a, b, d + c}
          (%i6) union (S_1, S_2);
          (%o6)              {%e, %i, %pi, a, b, d + c}
          (%i7) union (S_1, S_2, S_3);
          (%o7)       {17, 29, 1729, %e, %i, %pi, a, b, d + c}
          (%i8) union ({}, S_1, S_2, S_3);
          (%o8)       {17, 29, 1729, %e, %i, %pi, a, b, d + c}


 -- Function: xreduce (<F>, <s>)
 -- Function: xreduce (<F>, <s>, <s_0>)
     Extends the function <F> to an n-ary function by composition, or,
     if <F> is already n-ary, applies <F> to <s>.  When <F> is not
     n-ary, `xreduce' is the same as `lreduce'.  The argument <s> is a
     list.

     Functions known to be n-ary include addition `+', multiplication
     `*', `and', `or', `max', `min', and `append'.  Functions may also
     be declared n-ary by `declare(<F>, nary)'.  For these functions,
     `xreduce' is expected to be faster than either `rreduce' or
     `lreduce'.

     When the optional argument <s_0> is present, the result is
     equivalent to `xreduce(<s>, cons(<s_0>, <s>))'.

     Floating point addition is not exactly associative; be that as it
     may, `xreduce' applies Maxima's n-ary addition when <s> contains
     floating point numbers.

     Examples:

     `xreduce' applied to a function known to be n-ary.  `F' is called
     once, with all arguments.

          (%i1) declare (F, nary);
          (%o1)                         done
          (%i2) F ([L]) := L;
          (%o2)                      F([L]) := L
          (%i3) xreduce (F, [a, b, c, d, e]);
          (%o3)         [[[[[("[", simp), a], b], c], d], e]

     `xreduce' applied to a function not known to be n-ary.  `G' is
     called several times, with two arguments each time.

          (%i1) G ([L]) := L;
          (%o1)                      G([L]) := L
          (%i2) xreduce (G, [a, b, c, d, e]);
          (%o2)         [[[[[("[", simp), a], b], c], d], e]
          (%i3) lreduce (G, [a, b, c, d, e]);
          (%o3)                 [[[[a, b], c], d], e]



File: maxima.info,  Node: Function Definition,  Next: Program Flow,  Prev: Sets,  Up: Top

39 Function Definition
**********************

* Menu:

* Introduction to Function Definition::
* Function::
* Macros::
* Functions and Variables for Function Definition::


File: maxima.info,  Node: Introduction to Function Definition,  Next: Function,  Prev: Function Definition,  Up: Function Definition

39.1 Introduction to Function Definition
========================================


File: maxima.info,  Node: Function,  Next: Macros,  Prev: Introduction to Function Definition,  Up: Function Definition

39.2 Function
=============

39.2.1 Ordinary functions
-------------------------

To define a function in Maxima you use the `:=' operator.  E.g.

     f(x) := sin(x)

defines a function `f'.  Anonmyous functions may also be created using
`lambda'.  For example

     lambda ([i, j], ...)

can be used instead of `f' where

     f(i,j) := block ([], ...);
     map (lambda ([i], i+1), l)

would return a list with 1 added to each term.

   You may also define a function with a variable number of arguments,
by having a final argument which is assigned to a list of the extra
arguments:

     (%i1) f ([u]) := u;
     (%o1)                      f([u]) := u
     (%i2) f (1, 2, 3, 4);
     (%o2)                     [1, 2, 3, 4]
     (%i3) f (a, b, [u]) := [a, b, u];
     (%o3)               f(a, b, [u]) := [a, b, u]
     (%i4) f (1, 2, 3, 4, 5, 6);
     (%o4)                 [1, 2, [3, 4, 5, 6]]

   The right hand side of a function is an expression.  Thus if you
want a sequence of expressions, you do

     f(x) := (expr1, expr2, ...., exprn);

   and the value of <exprn> is what is returned by the function.

   If you wish to make a `return' from some expression inside the
function then you must use `block' and `return'.

     block ([], expr1, ..., if (a > 10) then return(a), ..., exprn)

   is itself an expression, and so could take the place of the right
hand side of a function definition.  Here it may happen that the return
happens earlier than the last expression.

   The first `[]' in the block, may contain a list of variables and
variable assignments, such as `[a: 3, b, c: []]', which would cause the
three variables `a',`b',and `c' to not refer to their global values,
but rather have these special values for as long as the code executes
inside the `block', or inside functions called from inside the `block'.
This is called dynamic binding, since the variables last from the
start of the block to the time it exits.  Once you return from the
`block', or throw out of it, the old values (if any) of the variables
will be restored.   It is certainly a good idea to protect your
variables in this way.   Note that the assignments in the block
variables, are done in parallel.   This means, that if you had used `c:
a' in the above, the value of `c' would have been the value of `a' at
the time you just entered the block, but before `a' was bound.   Thus
doing something like

     block ([a: a], expr1, ... a: a+3, ..., exprn)

   will protect the external value of `a' from being altered, but would
let you access what that value was.   Thus the right hand side of the
assignments, is evaluated in the entering context, before any binding
occurs.  Using just `block ([x], ...' would cause the `x' to have itself
as value, just as if it would have if you entered a fresh Maxima
session.

   The actual arguments to a function are treated in exactly same way as
the variables in a block.  Thus in

     f(x) := (expr1, ..., exprn);

   and

     f(1);

   we would have a similar context for evaluation of the expressions as
if we had done

     block ([x: 1], expr1, ..., exprn)

   Inside functions, when the right hand side of a definition, may be
computed at runtime, it is useful to use `define' and possibly `buildq'.

39.2.2 Array functions
----------------------

An array function stores the function value the first time it is called
with a given argument, and returns the stored value, without
recomputing it, when that same argument is given.  Such a function is
often called a memoizing function.

   Array function names are appended to the global list `arrays' (not
the global list `functions').  `arrayinfo' returns the list of
arguments for which there are stored values, and `listarray' returns
the stored values.  `dispfun' and `fundef' return the array function
definition.

   `arraymake' constructs an array function call, analogous to
`funmake' for ordinary functions.  `arrayapply' applies an array
function to its arguments, analogous to `apply' for ordinary functions.
There is nothing exactly analogous to `map' for array functions,
although `map(lambda([<x>], <a>[<x>]), <L>)' or `makelist(<a>[<x>],
<x>, <L>)', where <L> is a list, are not too far off the mark.

   `remarray' removes an array function definition (including any
stored function values), analogous to `remfunction' for ordinary
functions.

   `kill(<a>[<x>])' removes the value of the array function <a> stored
for the argument <x>; the next time <a> is called with argument <x>,
the function value is recomputed.  However, there is no way to remove
all of the stored values at once, except for `kill(<a>)' or
`remarray(<a>)', which also remove the function definition.


File: maxima.info,  Node: Macros,  Next: Functions and Variables for Function Definition,  Prev: Function,  Up: Function Definition

39.3 Macros
===========

 -- Function: buildq (<L>, <expr>)
     Substitutes variables named by the list <L> into the expression
     <expr>, in parallel, without evaluating <expr>.  The resulting
     expression is simplified, but not evaluated, after `buildq'
     carries out the substitution.

     The elements of <L> are symbols or assignment expressions
     `<symbol>: <value>', evaluated in parallel.  That is, the binding
     of a variable on the right-hand side of an assignment is the
     binding of that variable in the context from which `buildq' was
     called, not the binding of that variable in the variable list <L>.
     If some variable in <L> is not given an explicit assignment, its
     binding in `buildq' is the same as in the context from which
     `buildq' was called.

     Then the variables named by <L> are substituted into <expr> in
     parallel.  That is, the substitution for every variable is
     determined before any substitution is made, so the substitution
     for one variable has no effect on any other.

     If any variable <x> appears as `splice (<x>)' in <expr>, then <x>
     must be bound to a list, and the list is spliced (interpolated)
     into <expr> instead of substituted.

     Any variables in <expr> not appearing in <L> are carried into the
     result verbatim, even if they have bindings in the context from
     which `buildq' was called.

     Examples

     `a' is explicitly bound to `x', while `b' has the same binding
     (namely 29) as in the calling context, and `c' is carried through
     verbatim.  The resulting expression is not evaluated until the
     explicit evaluation `''%'.

          (%i1) (a: 17, b: 29, c: 1729)$
          (%i2) buildq ([a: x, b], a + b + c);
          (%o2)                      x + c + 29
          (%i3) ''%;
          (%o3)                       x + 1758

     `e' is bound to a list, which appears as such in the arguments of
     `foo', and interpolated into the arguments of `bar'.

          (%i1) buildq ([e: [a, b, c]], foo (x, e, y));
          (%o1)                 foo(x, [a, b, c], y)
          (%i2) buildq ([e: [a, b, c]], bar (x, splice (e), y));
          (%o2)                  bar(x, a, b, c, y)

     The result is simplified after substitution.  If simplification
     were applied before substitution, these two results would be the
     same.
          (%i1) buildq ([e: [a, b, c]], splice (e) + splice (e));
          (%o1)                    2 c + 2 b + 2 a
          (%i2) buildq ([e: [a, b, c]], 2 * splice (e));
          (%o2)                        2 a b c

     The variables in <L> are bound in parallel; if bound sequentially,
     the first result would be `foo (b, b)'.  Substitutions are carried
     out in parallel; compare the second result with the result of
     `subst', which carries out substitutions sequentially.

          (%i1) buildq ([a: b, b: a], foo (a, b));
          (%o1)                       foo(b, a)
          (%i2) buildq ([u: v, v: w, w: x, x: y, y: z, z: u],
                        bar (u, v, w, x, y, z));
          (%o2)                 bar(v, w, x, y, z, u)
          (%i3) subst ([u=v, v=w, w=x, x=y, y=z, z=u],
                       bar (u, v, w, x, y, z));
          (%o3)                 bar(u, u, u, u, u, u)

     Construct a list of equations with some variables or expressions
     on the left-hand side and their values on the right-hand side.
     `macroexpand' shows the expression returned by `show_values'.

          (%i1) show_values ([L]) ::= buildq ([L], map ("=", 'L, L));
          (%o1)   show_values([L]) ::= buildq([L], map("=", 'L, L))
          (%i2) (a: 17, b: 29, c: 1729)$
          (%i3) show_values (a, b, c - a - b);
          (%o3)          [a = 17, b = 29, c - b - a = 1683]
          (%i4) macroexpand (show_values (a, b, c - a - b));
          (%o4)    map(=, '([a, b, c - b - a]), [a, b, c - b - a])

     Given a function of several arguments, create another function for
     which some of the arguments are fixed.

          (%i1) curry (f, [a]) :=
                  buildq ([f, a], lambda ([[x]], apply (f, append (a, x))))$
          (%i2) by3 : curry ("*", 3);
          (%o2)        lambda([[x]], apply(*, append([3], x)))
          (%i3) by3 (a + b);
          (%o3)                       3 (b + a)


 -- Function: macroexpand (<expr>)
     Returns the macro expansion of <expr> without evaluating it, when
     `expr' is a macro function call.  Otherwise, `macroexpand' returns
     <expr>.

     If the expansion of <expr> yields another macro function call,
     that macro function call is also expanded.

     `macroexpand' quotes its argument.  However, if the expansion of a
     macro function call has side effects, those side effects are
     executed.

     See also `::=', `macros', and `macroexpand1'.

     Examples

          (%i1) g (x) ::= x / 99;
                                              x
          (%o1)                      g(x) ::= --
                                              99
          (%i2) h (x) ::= buildq ([x], g (x - a));
          (%o2)            h(x) ::= buildq([x], g(x - a))
          (%i3) a: 1234;
          (%o3)                         1234
          (%i4) macroexpand (h (y));
                                        y - a
          (%o4)                         -----
                                         99
          (%i5) h (y);
                                      y - 1234
          (%o5)                       --------
                                         99


 -- Function: macroexpand1 (<expr>)
     Returns the macro expansion of <expr> without evaluating it, when
     `expr' is a macro function call.  Otherwise, `macroexpand1'
     returns <expr>.

     `macroexpand1' quotes its argument.  However, if the expansion of
     a macro function call has side effects, those side effects are
     executed.

     If the expansion of <expr> yields another macro function call,
     that macro function call is not expanded.

     See also `::=', `macros', and `macroexpand'.

     Examples

          (%i1) g (x) ::= x / 99;
                                              x
          (%o1)                      g(x) ::= --
                                              99
          (%i2) h (x) ::= buildq ([x], g (x - a));
          (%o2)            h(x) ::= buildq([x], g(x - a))
          (%i3) a: 1234;
          (%o3)                         1234
          (%i4) macroexpand1 (h (y));
          (%o4)                       g(y - a)
          (%i5) h (y);
                                      y - 1234
          (%o5)                       --------
                                         99


 -- Global variable: macros
     Default value: `[]'

     `macros' is the list of user-defined macro functions.  The macro
     function definition operator `::=' puts a new macro function onto
     this list, and `kill', `remove', and `remfunction' remove macro
     functions from the list.

     See also `infolists'.


 -- Function: splice (<a>)
     Splices (interpolates) the list named by the atom <a> into an
     expression, but only if `splice' appears within `buildq';
     otherwise, `splice' is treated as an undefined function.  If
     appearing within `buildq' as <a> alone (without `splice'), <a> is
     substituted (not interpolated) as a list into the result.  The
     argument of `splice' can only be an atom; it cannot be a literal
     list or an expression which yields a list.

     Typically `splice' supplies the arguments for a function or
     operator.  For a function `f', the expression `f (splice (<a>))'
     within `buildq' expands to `f (<a>[1], <a>[2], <a>[3], ...)'.  For
     an operator `o', the expression `"o" (splice (<a>)' within `buildq'
     expands to `"o" (<a>[1], <a>[2], <a>[3], ...)', where `o' may be
     any type of operator (typically one which takes multiple
     arguments).  Note that the operator must be enclosed in double
     quotes `"'.

     Examples

          (%i1) buildq ([x: [1, %pi, z - y]], foo (splice (x)) / length (x));
                                 foo(1, %pi, z - y)
          (%o1)                -----------------------
                               length([1, %pi, z - y])
          (%i2) buildq ([x: [1, %pi]], "/" (splice (x)));
                                          1
          (%o2)                          ---
                                         %pi
          (%i3) matchfix ("<>", "<>");
          (%o3)                          <>
          (%i4) buildq ([x: [1, %pi, z - y]], "<>" (splice (x)));
          (%o4)                   <>1, %pi, z - y<>


