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 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.

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


 -- 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 341550071728321 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 34155071728321 `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:

* Functions and Variables for Symmetries::


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

32.1 Functions and Variables for Symmetries
===========================================

32.1.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.1.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.1.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.1.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.1.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.1.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.1.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 `$todd_coxeter_state'.

     The multiplication tables for the variables are in
     `table:todd_coxeter_state[2]'.  Then `table[i]' gives the table for
     the ith variable.  `mulcoset(coset,i) := table[varnum][coset];'

     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
          (%i7) table:todd_coxeter_state[2]$
          (%i8) table[1];
          (%o8) {Array: (SIGNED-BYTE 30) #(0 2 1 3 7 6 5 4 8 11 17 9 12 14 #

          13 20 16 10 18 19 15 0 0 0 0 0 0 0 0 0 0 0 0

            0 0 0)}

     Note only the elements 1 thru 20 of this array `%o8' are
     meaningful.  `table[1][4] = 7' indicates coset4.var1 = coset7



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.

     The return value is a Lisp string.

     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.


 -- Constant: inf
     Real positive infinity.


 -- Constant: infinity
     Complex infinity, an infinite magnitude of arbitrary phase angle.
     See also `inf' and `minf'.


 -- 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.


 -- 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>.

     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 Maxima strings.
     Rules for other functions have names which are ordinary 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 strings, while names for other
     functions are ordinary 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) [trigrule0, trigrule1, trigrule2, trigrule3, trigrule4,
          htrigrule1, htrigrule2, htrigrule3, htrigrule4, foorule1,
          foorule2, foorule3, +rule1, *rule1, ^rule1]
          (%i8) foorule_name: first (%o1);
          (%o8)                       foorule1
          (%i9) plusrule_name: first (%o4);
          (%o9)                        +rule1
          (%i10) [?mstringp (foorule_name), symbolp (foorule_name)];
          (%o10)                    [false, true]
          (%i11) [?mstringp (plusrule_name), symbolp (plusrule_name)];
          (%o11)                    [true, true]
          (%i12) remrule (foo, foorule1);
          (%o12)                         foo
          (%i13) remrule ("^", "^rule1");
          (%o13)                          ^

     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: 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)$
          (%o3)                        90 = 90
          (%i4) cardinality(p) = stirling2 (6, 3);

     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)$
          (%o3)                          {3}
          (%i4) map (cardinality, p);

     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)$
          (%o3)                 {{0, 1, 2, 3, 4, 5}}
          (%i4) map (lambda ([x], apply (union, listify (x))), p);

 -- 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])


 -- 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<>



File: maxima.info,  Node: Functions and Variables for Function Definition,  Prev: Macros,  Up: Function Definition

39.4 Functions and Variables for Function Definition
====================================================

 -- Function: apply (<F>, [<x_1>, ..., <x_n>])
     Constructs and evaluates an expression `<F>(<arg_1>, ...,
     <arg_n>)'.

     `apply' does not attempt to distinguish array functions from
     ordinary functions; when <F> is the name of an array function,
     `apply' evaluates `<F>(...)' (that is, a function call with
     parentheses instead of square brackets).  `arrayapply' evaluates a
     function call with square brackets in this case.

     Examples:

     `apply' evaluates its arguments.  In this example, `min' is
     applied to the value of `L'.

          (%i1) L : [1, 5, -10.2, 4, 3];
          (%o1)                 [1, 5, - 10.2, 4, 3]
          (%i2) apply (min, L);
          (%o2)                        - 10.2

     `apply' evaluates arguments, even if the function <F> quotes them.

          (%i1) F (x) := x / 1729;
                                             x
          (%o1)                     F(x) := ----
                                            1729
          (%i2) fname : F;
          (%o2)                           F
          (%i3) dispfun (F);
                                             x
          (%t3)                     F(x) := ----
                                            1729

          (%o3)                         [%t3]
          (%i4) dispfun (fname);
          fname is not the name of a user function.
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i5) apply (dispfun, [fname]);
                                             x
          (%t5)                     F(x) := ----
                                            1729

          (%o5)                         [%t5]

     `apply' evaluates the function name <F>.  Single quote `'' defeats
     evaluation.  `demoivre' is the name of a global variable and also
     a function.

          (%i1) demoivre;
          (%o1)                         false
          (%i2) demoivre (exp (%i * x));
          (%o2)                  %i sin(x) + cos(x)
          (%i3) apply (demoivre, [exp (%i * x)]);
          demoivre evaluates to false
          Improper name or value in functional position.
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i4) apply ('demoivre, [exp (%i * x)]);
          (%o4)                  %i sin(x) + cos(x)


 -- Function: block ([<v_1>, ..., <v_m>], <expr_1>, ..., <expr_n>)
 -- Function: block (<expr_1>, ..., <expr_n>)
     `block' evaluates <expr_1>, ..., <expr_n> in sequence and returns
     the value of the last expression evaluated.  The sequence can be
     modified by the `go', `throw', and `return' functions.  The last
     expression is <expr_n> unless `return' or an expression containing
     `throw' is evaluated.  Some variables <v_1>, ..., <v_m> can be
     declared local to the block; these are distinguished from global
     variables of the same names.  If no variables are declared local
     then the list may be omitted.  Within the block, any variable
     other than <v_1>, ..., <v_m> is a global variable.

     `block' saves the current values of the variables <v_1>, ...,
     <v_m> (if any) upon entry to the block, then unbinds the variables
     so that they evaluate to themselves.  The local variables may be
     bound to arbitrary values within the block but when the block is
     exited the saved values are restored, and the values assigned
     within the block are lost.

     `block' may appear within another `block'.  Local variables are
     established each time a new `block' is evaluated.  Local variables
     appear to be global to any enclosed blocks.  If a variable is
     non-local in a block, its value is the value most recently
     assigned by an enclosing block, if any, otherwise, it is the value
     of the variable in the global environment.  This policy may
     coincide with the usual understanding of "dynamic scope".

     If it is desired to save and restore other local properties
     besides `value', for example `array' (except for complete arrays),
     `function', `dependencies', `atvalue', `matchdeclare', `atomgrad',
     `constant', and `nonscalar' then the function `local' should be
     used inside of the block with arguments being the names of the
     variables.

     The value of the block is the value of the last statement or the
     value of the argument to the function `return' which may be used
     to exit explicitly from the block. The function `go' may be used
     to transfer control to the statement of the block that is tagged
     with the argument to `go'.  To tag a statement, precede it by an
     atomic argument as another statement in the block.  For example:
     `block ([x], x:1, loop, x: x+1, ..., go(loop), ...)'.  The
     argument to `go' must be the name of a tag appearing within the
     block.  One cannot use `go' to transfer to a tag in a block other
     than the one containing the `go'.

     Blocks typically appear on the right side of a function definition
     but can be used in other places as well.


 -- Function: break (<expr_1>, ..., <expr_n>)
     Evaluates and prints <expr_1>, ..., <expr_n> and then causes a
     Maxima break at which point the user can examine and change his
     environment.  Upon typing `exit;' the computation resumes.


 -- Function: catch (<expr_1>, ..., <expr_n>)
     Evaluates <expr_1>, ..., <expr_n> one by one; if any leads to the
     evaluation of an expression of the form `throw (arg)', then the
     value of the `catch' is the value of `throw (arg)', and no further
     expressions are evaluated.  This "non-local return" thus goes
     through any depth of nesting to the nearest enclosing `catch'.  If
     there is no `catch' enclosing a `throw', an error message is
     printed.

     If the evaluation of the arguments does not lead to the evaluation
     of any `throw' then the value of `catch' is the value of <expr_n>.

          (%i1) lambda ([x], if x < 0 then throw(x) else f(x))$
          (%i2) g(l) := catch (map (''%, l))$
          (%i3) g ([1, 2, 3, 7]);
          (%o3)               [f(1), f(2), f(3), f(7)]
          (%i4) g ([1, 2, -3, 7]);
          (%o4)                          - 3

     The function `g' returns a list of `f' of each element of `l' if
     `l' consists only of non-negative numbers; otherwise, `g'
     "catches" the first negative element of `l' and "throws" it up.


 -- Function: compfile (<filename>, <f_1>, ..., <f_n>)
 -- Function: compfile (<filename>, functions)
 -- Function: compfile (<filename>, all)
     Translates Maxima functions into Lisp and writes the translated
     code into the file <filename>.

     `compfile(<filename>, <f_1>, ..., <f_n>)' translates the specified
     functions.  `compfile(<filename>, functions)' and
     `compfile(<filename>, all)' translate all user-defined functions.

     The Lisp translations are not evaluated, nor is the output file
     processed by the Lisp compiler.  `translate' creates and evaluates
     Lisp translations.  `compile_file' translates Maxima into Lisp,
     and then executes the Lisp compiler.

     See also `translate', `translate_file', and `compile_file'.


 -- Function: compile (<f_1>, ..., <f_n>)
 -- Function: compile (functions)
 -- Function: compile (all)
     Translates Maxima functions <f_1>, ..., <f_n> into Lisp, evaluates
     the Lisp translations, and calls the Lisp function `COMPILE' on
     each translated function.  `compile' returns a list of the names
     of the compiled functions.

     `compile (all)' or `compile (functions)' compiles all user-defined
     functions.

     `compile' quotes its arguments; the quote-quote operator `'''
     defeats quotation.


 -- Function: define (<f>(<x_1>, ..., <x_n>), <expr>)
 -- Function: define (<f>[<x_1>, ..., <x_n>], <expr>)
 -- Function: define (funmake (<f>, [<x_1>, ..., <x_n>]), <expr>)
 -- Function: define (arraymake (<f>, [<x_1>, ..., <x_n>]), <expr>)
 -- Function: define (ev (<expr_1>), <expr_2>)
     Defines a function named <f> with arguments <x_1>, ..., <x_n> and
     function body <expr>.  `define' always evaluates its second
     argument (unless explicitly quoted).  The function so defined may
     be an ordinary Maxima function (with arguments enclosed in
     parentheses) or an array function (with arguments enclosed in
     square brackets).

     When the last or only function argument <x_n> is a list of one
     element, the function defined by `define' accepts a variable
     number of arguments.  Actual arguments are assigned one-to-one to
     formal arguments <x_1>, ..., <x_(n - 1)>, and any further actual
     arguments, if present, are assigned to <x_n> as a list.

     When the first argument of `define' is an expression of the form
     `<f>(<x_1>, ..., <x_n>)' or `<f>[<x_1>, ..., <x_n>]', the function
     arguments are evaluated but <f> is not evaluated, even if there is
     already a function or variable by that name.

     When the first argument is an expression with operator `funmake',
     `arraymake', or `ev', the first argument is evaluated; this allows
     for the function name to be computed, as well as the body.

     All function definitions appear in the same namespace; defining a
     function `f' within another function `g' does not limit the scope
     of `f' to `g'.

     If some formal argument <x_k> is a quoted symbol (after
     evaluation), the function defined by `define' does not evaluate
     the corresponding actual argument.  Otherwise all actual arguments
     are evaluated.

     See also `:=' and `::='.

     Examples:

     `define' always evaluates its second argument (unless explicitly
     quoted).

          (%i1) expr : cos(y) - sin(x);
          (%o1)                    cos(y) - sin(x)
          (%i2) define (F1 (x, y), expr);
          (%o2)              F1(x, y) := cos(y) - sin(x)
          (%i3) F1 (a, b);
          (%o3)                    cos(b) - sin(a)
          (%i4) F2 (x, y) := expr;
          (%o4)                   F2(x, y) := expr
          (%i5) F2 (a, b);
          (%o5)                    cos(y) - sin(x)

     The function defined by `define' may be an ordinary Maxima
     function or an array function.

          (%i1) define (G1 (x, y), x.y - y.x);
          (%o1)               G1(x, y) := x . y - y . x
          (%i2) define (G2 [x, y], x.y - y.x);
          (%o2)                G2     := x . y - y . x
                                 x, y

     When the last or only function argument <x_n> is a list of one
     element, the function defined by `define' accepts a variable
     number of arguments.

          (%i1) define (H ([L]), '(apply ("+", L)));
          (%o1)                H([L]) := apply("+", L)
          (%i2) H (a, b, c);
          (%o2)                       c + b + a

     When the first argument is an expression with operator `funmake',
     `arraymake', or `ev', the first argument is evaluated.

          (%i1) [F : I, u : x];
          (%o1)                        [I, x]
          (%i2) funmake (F, [u]);
          (%o2)                         I(x)
          (%i3) define (funmake (F, [u]), cos(u) + 1);
          (%o3)                  I(x) := cos(x) + 1
          (%i4) define (arraymake (F, [u]), cos(u) + 1);
          (%o4)                   I  := cos(x) + 1
                                   x
          (%i5) define (foo (x, y), bar (y, x));
          (%o5)                foo(x, y) := bar(y, x)
          (%i6) define (ev (foo (x, y)), sin(x) - cos(y));
          (%o6)             bar(y, x) := sin(x) - cos(y)


 -- Function: define_variable (<name>, <default_value>, <mode>)
     Introduces a global variable into the Maxima environment.
     `define_variable' is useful in user-written packages, which are
     often translated or compiled.

     `define_variable' carries out the following steps:

       1. `mode_declare (<name>, <mode>)' declares the mode of <name>
          to the translator.  See `mode_declare' for a list of the
          possible modes.

       2. If the variable is unbound, <default_value> is assigned to
          <name>.

       3. `declare (<name>, special)' declares it special.

       4. Associates <name> with a test function to ensure that <name>
          is only assigned values of the declared mode.

     The `value_check' property can be assigned to any variable which
     has been defined via `define_variable' with a mode other than
     `any'.  The `value_check' property is a lambda expression or the
     name of a function of one variable, which is called when an
     attempt is made to assign a value to the variable.  The argument
     of the `value_check' function is the would-be assigned value.

     `define_variable' evaluates `default_value', and quotes `name' and
     `mode'.  `define_variable' returns the current value of `name',
     which is `default_value' if `name' was unbound before, and
     otherwise it is the previous value of `name'.

     Examples:

     `foo' is a Boolean variable, with the initial value `true'.
          (%i1) define_variable (foo, true, boolean);
          (%o1)                         true
          (%i2) foo;
          (%o2)                         true
          (%i3) foo: false;
          (%o3)                         false
          (%i4) foo: %pi;
          Error: foo was declared mode boolean, has value: %pi
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i5) foo;
          (%o5)                         false

     `bar' is an integer variable, which must be prime.
          (%i1) define_variable (bar, 2, integer);
          (%o1)                           2
          (%i2) qput (bar, prime_test, value_check);
          (%o2)                      prime_test
          (%i3) prime_test (y) := if not primep(y) then
                                     error (y, "is not prime.");
          (%o3) prime_test(y) := if not primep(y)

                                             then error(y, "is not prime.")
          (%i4) bar: 1439;
          (%o4)                         1439
          (%i5) bar: 1440;
          1440 is not prime.
          #0: prime_test(y=1440)
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i6) bar;
          (%o6)                         1439

     `baz_quux' is a variable which cannot be assigned a value.  The
     mode `any_check' is like `any', but `any_check' enables the
     `value_check' mechanism, and `any' does not.
          (%i1) define_variable (baz_quux, 'baz_quux, any_check);
          (%o1)                       baz_quux
          (%i2) F: lambda ([y], if y # 'baz_quux then
                           error ("Cannot assign to `baz_quux'."));
          (%o2) lambda([y], if y # 'baz_quux

                                  then error(Cannot assign to `baz_quux'.))
          (%i3) qput (baz_quux, ''F, value_check);
          (%o3) lambda([y], if y # 'baz_quux

                                  then error(Cannot assign to `baz_quux'.))
          (%i4) baz_quux: 'baz_quux;
          (%o4)                       baz_quux
          (%i5) baz_quux: sqrt(2);
          Cannot assign to `baz_quux'.
          #0: lambda([y],if y # 'baz_quux then
                           error("Cannot assign to `baz_quux'."))(y=sqrt(2))
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i6) baz_quux;
          (%o6)                       baz_quux


 -- Function: dispfun (<f_1>, ..., <f_n>)
 -- Function: dispfun (all)
     Displays the definition of the user-defined functions <f_1>, ...,
     <f_n>.  Each argument may be the name of a macro (defined with
     `::='), an ordinary function (defined with `:=' or `define'), an
     array function (defined with `:=' or `define', but enclosing
     arguments in square brackets `[ ]'), a subscripted function,
     (defined with `:=' or `define', but enclosing some arguments in
     square brackets and others in parentheses `( )') one of a family
     of subscripted functions selected by a particular subscript value,
     or a subscripted function defined with a constant subscript.

     `dispfun (all)' displays all user-defined functions as given by
     the `functions', `arrays', and `macros' lists, omitting
     subscripted functions defined with constant subscripts.

     `dispfun' creates an intermediate expression label (`%t1', `%t2',
     etc.)  for each displayed function, and assigns the function
     definition to the label.  In contrast, `fundef' returns the
     function definition.

     `dispfun' quotes its arguments; the quote-quote operator `'''
     defeats quotation.  `dispfun' returns the list of intermediate
     expression labels corresponding to the displayed functions.

     Examples:

          (%i1) m(x, y) ::= x^(-y);
                                               - y
          (%o1)                   m(x, y) ::= x
          (%i2) f(x, y) :=  x^(-y);
                                               - y
          (%o2)                    f(x, y) := x
          (%i3) g[x, y] :=  x^(-y);
                                              - y
          (%o3)                     g     := x
                                     x, y
          (%i4) h[x](y) :=  x^(-y);
                                              - y
          (%o4)                     h (y) := x
                                     x
          (%i5) i[8](y) :=  8^(-y);
                                              - y
          (%o5)                     i (y) := 8
                                     8
          (%i6) dispfun (m, f, g, h, h[5], h[10], i[8]);
                                               - y
          (%t6)                   m(x, y) ::= x

                                               - y
          (%t7)                    f(x, y) := x

                                              - y
          (%t8)                     g     := x
                                     x, y

                                              - y
          (%t9)                     h (y) := x
                                     x

                                              1
          (%t10)                     h (y) := --
                                      5        y
                                              5

                                               1
          (%t11)                    h  (y) := ---
                                     10         y
                                              10

                                              - y
          (%t12)                    i (y) := 8
                                     8

          (%o12)       [%t6, %t7, %t8, %t9, %t10, %t11, %t12]
          (%i12) ''%;
                               - y              - y            - y
          (%o12) [m(x, y) ::= x   , f(x, y) := x   , g     := x   ,
                                                      x, y
                            - y           1              1             - y
                  h (y) := x   , h (y) := --, h  (y) := ---, i (y) := 8   ]
                   x              5        y   10         y   8
                                          5             10


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

     `functions' is the list of ordinary Maxima functions in the
     current session.  An ordinary function is a function constructed by
     `define' or `:=' and called with parentheses `()'.  A function may
     be defined at the Maxima prompt or in a Maxima file loaded by
     `load' or `batch'.

     Array functions (called with square brackets, e.g., `F[x]') and
     subscripted functions (called with square brackets and
     parentheses, e.g., `F[x](y)') are listed by the global variable
     `arrays', and not by `functions'.

     Lisp functions are not kept on any list.

     Examples:

          (%i1) F_1 (x) := x - 100;
          (%o1)                   F_1(x) := x - 100
          (%i2) F_2 (x, y) := x / y;
                                                x
          (%o2)                    F_2(x, y) := -
                                                y
          (%i3) define (F_3 (x), sqrt (x));
          (%o3)                   F_3(x) := sqrt(x)
          (%i4) G_1 [x] := x - 100;
          (%o4)                    G_1  := x - 100
                                      x
          (%i5) G_2 [x, y] := x / y;
                                               x
          (%o5)                     G_2     := -
                                       x, y    y
          (%i6) define (G_3 [x], sqrt (x));
          (%o6)                    G_3  := sqrt(x)
                                      x
          (%i7) H_1 [x] (y) := x^y;
                                                y
          (%o7)                     H_1 (y) := x
                                       x
          (%i8) functions;
          (%o8)              [F_1(x), F_2(x, y), F_3(x)]
          (%i9) arrays;
          (%o9)                 [G_1, G_2, G_3, H_1]


 -- Function: fundef (<f>)
     Returns the definition of the function <f>.

     The argument may be the name of a macro (defined with `::='), an
     ordinary function (defined with `:=' or `define'), an array
     function (defined with `:=' or `define', but enclosing arguments
     in square brackets `[ ]'), a subscripted function, (defined with
     `:=' or `define', but enclosing some arguments in square brackets
     and others in parentheses `( )') one of a family of subscripted
     functions selected by a particular subscript value, or a
     subscripted function defined with a constant subscript.

     `fundef' quotes its argument; the quote-quote operator `'''
     defeats quotation.

     `fundef (<f>)' returns the definition of <f>.  In contrast,
     `dispfun (<f>)' creates an intermediate expression label and
     assigns the definition to the label.


 -- Function: funmake (<F>, [<arg_1>, ..., <arg_n>])
     Returns an expression `<F>(<arg_1>, ..., <arg_n>)'.  The return
     value is simplified, but not evaluated, so the function <F> is not
     called, even if it exists.

     `funmake' does not attempt to distinguish array functions from
     ordinary functions; when <F> is the name of an array function,
     `funmake' returns `<F>(...)' (that is, a function call with
     parentheses instead of square brackets).  `arraymake' returns a
     function call with square brackets in this case.

     `funmake' evaluates its arguments.

     Examples:

     `funmake' applied to an ordinary Maxima function.

          (%i1) F (x, y) := y^2 - x^2;
                                             2    2
          (%o1)                  F(x, y) := y  - x
          (%i2) funmake (F, [a + 1, b + 1]);
          (%o2)                    F(a + 1, b + 1)
          (%i3) ''%;
                                        2          2
          (%o3)                  (b + 1)  - (a + 1)

     `funmake' applied to a macro.

          (%i1) G (x) ::= (x - 1)/2;
                                            x - 1
          (%o1)                    G(x) ::= -----
                                              2
          (%i2) funmake (G, [u]);
          (%o2)                         G(u)
          (%i3) ''%;
                                        u - 1
          (%o3)                         -----
                                          2

     `funmake' applied to a subscripted function.

          (%i1) H [a] (x) := (x - 1)^a;
                                                  a
          (%o1)                   H (x) := (x - 1)
                                   a
          (%i2) funmake (H [n], [%e]);
                                                 n
          (%o2)               lambda([x], (x - 1) )(%e)
          (%i3) ''%;
                                              n
          (%o3)                       (%e - 1)
          (%i4) funmake ('(H [n]), [%e]);
          (%o4)                        H (%e)
                                        n
          (%i5) ''%;
                                              n
          (%o5)                       (%e - 1)

     `funmake' applied to a symbol which is not a defined function of
     any kind.

          (%i1) funmake (A, [u]);
          (%o1)                         A(u)
          (%i2) ''%;
          (%o2)                         A(u)

     `funmake' evaluates its arguments, but not the return value.

          (%i1) det(a,b,c) := b^2 -4*a*c;
                                              2
          (%o1)              det(a, b, c) := b  - 4 a c
          (%i2) (x : 8, y : 10, z : 12);
          (%o2)                          12
          (%i3) f : det;
          (%o3)                          det
          (%i4) funmake (f, [x, y, z]);
          (%o4)                    det(8, 10, 12)
          (%i5) ''%;
          (%o5)                         - 284

     Maxima simplifies `funmake''s return value.

          (%i1) funmake (sin, [%pi / 2]);
          (%o1)                           1


 -- Function: lambda ([<x_1>, ..., <x_m>], <expr_1>, ..., <expr_n>)
 -- Function: lambda ([[<L>]], <expr_1>, ..., <expr_n>)
 -- Function: lambda ([<x_1>, ..., <x_m>, [<L>]], <expr_1>, ...,
          <expr_n>)
     Defines and returns a lambda expression (that is, an anonymous
     function).  The function may have required arguments <x_1>, ...,
     <x_m> and/or optional arguments <L>, which appear within the
     function body as a list.  The return value of the function is
     <expr_n>.  A lambda expression can be assigned to a variable and
     evaluated like an ordinary function.  A lambda expression may
     appear in some contexts in which a function name is expected.

     When the function is evaluated, unbound local variables <x_1>,
     ..., <x_m> are created.  `lambda' may appear within `block' or
     another `lambda'; local variables are established each time
     another `block' or `lambda' is evaluated.  Local variables appear
     to be global to any enclosed `block' or `lambda'.  If a variable
     is not local, its value is the value most recently assigned in an
     enclosing `block' or `lambda', if any, otherwise, it is the value
     of the variable in the global environment.  This policy may
     coincide with the usual understanding of "dynamic scope".

     After local variables are established, <expr_1> through <expr_n>
     are evaluated in turn.  The special variable `%%', representing
     the value of the preceding expression, is recognized.  `throw' and
     `catch' may also appear in the list of expressions.

     `return' cannot appear in a lambda expression unless enclosed by
     `block', in which case `return' defines the return value of the
     block and not of the lambda expression, unless the block happens
     to be <expr_n>.  Likewise, `go' cannot appear in a lambda
     expression unless enclosed by `block'.

     `lambda' quotes its arguments; the quote-quote operator `'''
     defeats quotation.

     Examples:

        * A lambda expression can be assigned to a variable and
          evaluated like an ordinary function.

          (%i1) f: lambda ([x], x^2);
                                                2
          (%o1)                    lambda([x], x )
          (%i2) f(a);
                                          2
          (%o2)                          a

        * A lambda expression may appear in contexts in which a
          function evaluation is expected.

          (%i3) lambda ([x], x^2) (a);
                                          2
          (%o3)                          a
          (%i4) apply (lambda ([x], x^2), [a]);
                                          2
          (%o4)                          a
          (%i5) map (lambda ([x], x^2), [a, b, c, d, e]);
                                  2   2   2   2   2
          (%o5)                 [a , b , c , d , e ]

        * Argument variables are local variables.  Other variables
          appear to be global variables.  Global variables are
          evaluated at the time the lambda expression is evaluated,
          unless some special evaluation is forced by some means, such
          as `'''.

          (%i6) a: %pi$
          (%i7) b: %e$
          (%i8) g: lambda ([a], a*b);
          (%o8)                   lambda([a], a b)
          (%i9) b: %gamma$
          (%i10) g(1/2);
                                       %gamma
          (%o10)                       ------
                                         2
          (%i11) g2: lambda ([a], a*''b);
          (%o11)                lambda([a], a %gamma)
          (%i12) b: %e$
          (%i13) g2(1/2);
                                       %gamma
          (%o13)                       ------
                                         2

        * Lambda expressions may be nested.  Local variables within the
          outer lambda expression appear to be global to the inner
          expression unless masked by local variables of the same names.

          (%i14) h: lambda ([a, b], h2: lambda ([a], a*b), h2(1/2));
                                                             1
          (%o14)    lambda([a, b], h2 : lambda([a], a b), h2(-))
                                                             2
          (%i15) h(%pi, %gamma);
                                       %gamma
          (%o15)                       ------
                                         2

        * Since `lambda' quotes its arguments, lambda expression `i'
          below does not define a "multiply by `a'" function.  Such a
          function can be defined via `buildq', as in lambda expression
          `i2' below.

          (%i16) i: lambda ([a], lambda ([x], a*x));
          (%o16)            lambda([a], lambda([x], a x))
          (%i17) i(1/2);
          (%o17)                  lambda([x], a x)
          (%i18) i2: lambda([a], buildq([a: a], lambda([x], a*x)));
          (%o18)    lambda([a], buildq([a : a], lambda([x], a x)))
          (%i19) i2(1/2);
                                               x
          (%o19)                   lambda([x], -)
                                               2
          (%i20) i2(1/2)(%pi);
                                         %pi
          (%o20)                         ---
                                          2

        * A lambda expression may take a variable number of arguments,
          which are indicated by `[<L>]' as the sole or final argument.
          The arguments appear within the function body as a list.

          (%i1) f : lambda ([aa, bb, [cc]], aa * cc + bb);
          (%o1)          lambda([aa, bb, [cc]], aa cc + bb)
          (%i2) f (foo, %i, 17, 29, 256);
          (%o2)       [17 foo + %i, 29 foo + %i, 256 foo + %i]
          (%i3) g : lambda ([[aa]], apply ("+", aa));
          (%o3)             lambda([[aa]], apply(+, aa))
          (%i4) g (17, 29, x, y, z, %e);
          (%o4)                  z + y + x + %e + 46

 -- Function: local (<v_1>, ..., <v_n>)
     Declares the variables <v_1>, ..., <v_n> to be local with respect
     to all the properties in the statement in which this function is
     used.

     `local' quotes its arguments.  `local' returns `done'.

     `local' may only be used in `block', in the body of function
     definitions or `lambda' expressions, or in the `ev' function, and
     only one occurrence is permitted in each.

     `local' is independent of `context'.


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

     `macroexpansion' controls whether the expansion (that is, the
     return value) of a macro function is substituted for the macro
     function call.  A substitution may speed up subsequent expression
     evaluations, at the cost of storing the expansion.

    `false'
          The expansion of a macro function is not substituted for the
          macro function call.

    `expand'
          The first time a macro function call is evaluated, the
          expansion is stored.  The expansion is not recomputed on
          subsequent calls; any side effects (such as `print' or
          assignment to global variables) happen only when the macro
          function call is first evaluated.  Expansion in an expression
          does not affect other expressions which have the same macro
          function call.

    `displace'
          The first time a macro function call is evaluated, the
          expansion is substituted for the call, thus modifying the
          expression from which the macro function was called.  The
          expansion is not recomputed on subsequent calls; any side
          effects happen only when the macro function call is first
          evaluated.  Expansion in an expression does not affect other
          expressions which have the same macro function call.

     Examples

     When `macroexpansion' is `false', a macro function is called every
     time the calling expression is evaluated, and the calling
     expression is not modified.

          (%i1) f (x) := h (x) / g (x);
                                            h(x)
          (%o1)                     f(x) := ----
                                            g(x)
          (%i2) g (x) ::= block (print ("x + 99 is equal to", x),
                                 return (x + 99));
          (%o2) g(x) ::= block(print("x + 99 is equal to", x),
                                                            return(x + 99))
          (%i3) h (x) ::= block (print ("x - 99 is equal to", x),
                                 return (x - 99));
          (%o3) h(x) ::= block(print("x - 99 is equal to", x),
                                                            return(x - 99))
          (%i4) macroexpansion: false;
          (%o4)                         false
          (%i5) f (a * b);
          x - 99 is equal to x
          x + 99 is equal to x
                                      a b - 99
          (%o5)                       --------
                                      a b + 99
          (%i6) dispfun (f);
                                            h(x)
          (%t6)                     f(x) := ----
                                            g(x)

          (%o6)                         done
          (%i7) f (a * b);
          x - 99 is equal to x
          x + 99 is equal to x
                                      a b - 99
          (%o7)                       --------
                                      a b + 99

     When `macroexpansion' is `expand', a macro function is called once,
     and the calling expression is not modified.

          (%i1) f (x) := h (x) / g (x);
                                            h(x)
          (%o1)                     f(x) := ----
                                            g(x)
          (%i2) g (x) ::= block (print ("x + 99 is equal to", x),
                                 return (x + 99));
          (%o2) g(x) ::= block(print("x + 99 is equal to", x),
                                                            return(x + 99))
          (%i3) h (x) ::= block (print ("x - 99 is equal to", x),
                                 return (x - 99));
          (%o3) h(x) ::= block(print("x - 99 is equal to", x),
                                                            return(x - 99))
          (%i4) macroexpansion: expand;
          (%o4)                        expand
          (%i5) f (a * b);
          x - 99 is equal to x
          x + 99 is equal to x
                                      a b - 99
          (%o5)                       --------
                                      a b + 99
          (%i6) dispfun (f);
                                            h(x)
          (%t6)                     f(x) := ----
                                            g(x)

          (%o6)                         done
          (%i7) f (a * b);
                                      a b - 99
          (%o7)                       --------
                                      a b + 99

     When `macroexpansion' is `expand', a macro function is called once,
     and the calling expression is modified.

          (%i1) f (x) := h (x) / g (x);
                                            h(x)
          (%o1)                     f(x) := ----
                                            g(x)
          (%i2) g (x) ::= block (print ("x + 99 is equal to", x),
                                 return (x + 99));
          (%o2) g(x) ::= block(print("x + 99 is equal to", x),
                                                            return(x + 99))
          (%i3) h (x) ::= block (print ("x - 99 is equal to", x),
                                 return (x - 99));
          (%o3) h(x) ::= block(print("x - 99 is equal to", x),
                                                            return(x - 99))
          (%i4) macroexpansion: displace;
          (%o4)                       displace
          (%i5) f (a * b);
          x - 99 is equal to x
          x + 99 is equal to x
                                      a b - 99
          (%o5)                       --------
                                      a b + 99
          (%i6) dispfun (f);
                                           x - 99
          (%t6)                    f(x) := ------
                                           x + 99

          (%o6)                         done
          (%i7) f (a * b);
                                      a b - 99
          (%o7)                       --------
                                      a b + 99


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

     When `mode_checkp' is `true', `mode_declare' checks the modes of
     bound variables.


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

     When `mode_check_errorp' is `true', `mode_declare' calls error.


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

     When `mode_check_warnp' is `true', mode errors are described.


 -- Function: mode_declare (<y_1>, <mode_1>, ..., <y_n>, <mode_n>)
     `mode_declare' is used to declare the modes of variables and
     functions for subsequent translation or compilation of functions.
     `mode_declare' is typically placed at the beginning of a function
     definition, at the beginning of a Maxima script, or executed at
     the interactive prompt.

     The arguments of `mode_declare' are pairs consisting of a variable
     and a mode which is one of `boolean', `fixnum', `number',
     `rational', or `float'.  Each variable may also be a list of
     variables all of which are declared to have the same mode.

     If a variable is an array, and if every element of the array which
     is referenced has a value then `array (yi, complete, dim1, dim2,
     ...)' rather than
          array(yi, dim1, dim2, ...)
     should be used when first declaring the bounds of the array.  If
     all the elements of the array are of mode `fixnum' (`float'), use
     `fixnum' (`float') instead of `complete'.  Also if every element
     of the array is of the same mode, say `m', then

          mode_declare (completearray (yi), m))

     should be used for efficient translation.

     Numeric code using arrays might run faster by declaring the
     expected size of the array, as in:

          mode_declare (completearray (a [10, 10]), float)

     for a floating point number array which is 10 x 10.

     One may declare the mode of the result of a function by using
     `function (f_1, f_2, ...)' as an argument; here `f_1', `f_2', ...
     are the names of functions.  For example the expression,

          mode_declare ([function (f_1, f_2, ...)], fixnum)

     declares that the values returned by `f_1', `f_2', ... are
     single-word integers.

     `modedeclare' is a synonym for `mode_declare'.


 -- Function: mode_identity (<arg_1>, <arg_2>)
     A special form used with `mode_declare' and `macros' to declare,
     e.g., a list of lists of flonums, or other compound data object.
     The first argument to `mode_identity' is a primitive value mode
     name as given to `mode_declare' (i.e., one of `float', `fixnum',
     `number', `list', or `any'), and the second argument is an
     expression which is evaluated and returned as the value of
     `mode_identity'.  However, if the return value is not allowed by
     the mode declared in the first argument, an error or warning is
     signalled.  The important thing is that the mode of the expression
     as determined by the Maxima to Lisp translator, will be that given
     as the first argument, independent of anything that goes on in the
     second argument.  E.g., `x: 3.3; mode_identity (fixnum, x);'
     yields an error. `mode_identity (flonum, x)' returns 3.3 .  This
     has a number of uses, e.g., if you knew that `first (l)' returned a
     number then you might write `mode_identity (number, first (l))'.
     However, a more efficient way to do it would be to define a new
     primitive,

          firstnumb (x) ::= buildq ([x], mode_identity (number, x));

     and use `firstnumb' every time you take the first of a list of
     numbers.


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

     When `transcompile' is `true', `translate' and `translate_file'
     generate declarations to make the translated code more suitable
     for compilation.

     `compfile' sets `transcompile: true' for the duration.


 -- Function: translate (<f_1>, ..., <f_n>)
 -- Function: translate (functions)
 -- Function: translate (all)
     Translates the user-defined functions <f_1>, ..., <f_n> from the
     Maxima language into Lisp and evaluates the Lisp translations.
     Typically the translated functions run faster than the originals.

     `translate (all)' or `translate (functions)' translates all
     user-defined functions.

     Functions to be translated should include a call to `mode_declare'
     at the beginning when possible in order to produce more efficient
     code.  For example:

          f (x_1, x_2, ...) := block ([v_1, v_2, ...],
              mode_declare (v_1, mode_1, v_2, mode_2, ...), ...)

     where the <x_1>, <x_2>, ...  are the parameters to the function
     and the <v_1>, <v_2>, ... are the local variables.

     The names of translated functions are removed from the `functions'
     list if `savedef' is `false' (see below) and are added to the
     `props' lists.

     Functions should not be translated unless they are fully debugged.

     Expressions are assumed simplified; if they are not, correct but
     non-optimal code gets generated.  Thus, the user should not set
     the `simp' switch to `false' which inhibits simplification of the
     expressions to be translated.

     The switch `translate', if `true', causes automatic translation of
     a user's function to Lisp.

     Note that translated functions may not run identically to the way
     they did before translation as certain incompatabilities may exist
     between the Lisp and Maxima versions.  Principally, the `rat'
     function with more than one argument and the `ratvars' function
     should not be used if any variables are `mode_declare''d canonical
     rational expressions (CRE).  Also the `prederror: false' setting
     will not translate.

     `savedef' - if `true' will cause the Maxima version of a user
     function to remain when the function is `translate''d.  This
     permits the definition to be displayed by `dispfun' and allows the
     function to be edited.

     `transrun' - if `false' will cause the interpreted version of all
     functions to be run (provided they are still around) rather than
     the translated version.

     The result returned by `translate' is a list of the names of the
     functions translated.


 -- Function: translate_file (<maxima_filename>)
 -- Function: translate_file (<maxima_filename>, <lisp_filename>)
     Translates a file of Maxima code into a file of Lisp code.
     `translate_file' returns a list of three filenames: the name of
     the Maxima file, the name of the Lisp file, and the name of file
     containing additional information about the translation.
     `translate_file' evaluates its arguments.

     `translate_file ("foo.mac"); load("foo.LISP")' is the same as
     `batch ("foo.mac")' except for certain restrictions, the use of
     `''' and `%', for example.

     `translate_file (<maxima_filename>)' translates a Maxima file
     <maxima_filename> into a similarly-named Lisp file.  For example,
     `foo.mac' is translated into `foo.LISP'.  The Maxima filename may
     include a directory name or names, in which case the Lisp output
     file is written to the same directory from which the Maxima input
     comes.

     `translate_file (<maxima_filename>, <lisp_filename>)' translates a
     Maxima file <maxima_filename> into a Lisp file <lisp_filename>.
     `translate_file' ignores the filename extension, if any, of
     `lisp_filename'; the filename extension of the Lisp output file is
     always `LISP'.  The Lisp filename may include a directory name or
     names, in which case the Lisp output file is written to the
     specified directory.

     `translate_file' also writes a file of translator warning messages
     of various degrees of severity.  The filename extension of this
     file is `UNLISP'.  This file may contain valuable information,
     though possibly obscure, for tracking down bugs in translated code.
     The `UNLISP' file is always written to the same directory from
     which the Maxima input comes.

     `translate_file' emits Lisp code which causes some declarations
     and definitions to take effect as soon as the Lisp code is
     compiled.  See `compile_file' for more on this topic.

     See also `tr_array_as_ref', `tr_bound_function_applyp',
     `tr_exponent', `tr_file_tty_messagesp',
     `tr_float_can_branch_complex', `tr_function_call_default',
     `tr_numer', `tr_optimize_max_loop', `tr_semicompile',
     `tr_state_vars', `tr_warnings_get', `tr_warn_bad_function_calls',
     `tr_warn_fexpr', `tr_warn_meval', `tr_warn_mode',
     `tr_warn_undeclared', `tr_warn_undefined_variable', and `tr_windy'.


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

     When `transrun' is `false' will cause the interpreted version of
     all functions to be run (provided they are still around) rather
     than the translated version.


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

     If `translate_fast_arrays' is `false', array references in Lisp
     code emitted by `translate_file' are affected by `tr_array_as_ref'.
     When `tr_array_as_ref' is `true', array names are evaluated,
     otherwise array names appear as literal symbols in translated code.

     `tr_array_as_ref' has no effect if `translate_fast_arrays' is
     `true'.


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

     When `tr_bound_function_applyp' is `true', Maxima gives a warning
     if a bound variable (such as a function argument) is found being
     used as a function.  `tr_bound_function_applyp' does not affect
     the code generated in such cases.

     For example, an expression such as `g (f, x) := f (x+1)' will
     trigger the warning message.


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

     When `tr_file_tty_messagesp' is `true', messages generated by
     `translate_file' during translation of a file are displayed on the
     console and inserted into the UNLISP file.  When `false', messages
     about translation of the file are only inserted into the UNLISP
     file.


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

     Tells the Maxima-to-Lisp translator to assume that the functions
     `acos', `asin', `asec', and `acsc' can return complex results.

     The ostensible effect of `tr_float_can_branch_complex' is the
     following.  However, it appears that this flag has no effect on
     the translator output.

     When it is `true' then `acos(x)' is of mode `any' even if `x' is
     of mode `float' (as set by `mode_declare').  When `false' then
     `acos(x)' is of mode `float' if and only if `x' is of mode `float'.


 -- Option variable: tr_function_call_default
     Default value: `general'

     `false' means give up and call `meval', `expr' means assume Lisp
     fixed arg function.  `general', the default gives code good for
     `mexprs' and `mlexprs' but not `macros'.  `general' assures
     variable bindings are correct in compiled code.  In `general'
     mode, when translating F(X), if F is a bound variable, then it
     assumes that `apply (f, [x])' is meant, and translates a such, with
     apropriate warning. There is no need to turn this off.  With the
     default settings, no warning messages implies full compatibility of
     translated and compiled code with the Maxima interpreter.


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

     When `tr_numer' is `true', `numer' properties are used for atoms
     which have them, e.g. `%pi'.


 -- Option variable: tr_optimize_max_loop
     Default value: 100

     `tr_optimize_max_loop' is the maximum number of times the
     macro-expansion and optimization pass of the translator will loop
     in considering a form.  This is to catch macro expansion errors,
     and non-terminating optimization properties.


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

     When `tr_semicompile' is `true', `translate_file' and `compfile'
     output forms which will be macroexpanded but not compiled into
     machine code by the Lisp compiler.


 -- System variable: tr_state_vars
     Default value:
          [transcompile, tr_semicompile, tr_warn_undeclared, tr_warn_meval,
          tr_warn_fexpr, tr_warn_mode, tr_warn_undefined_variable,
          tr_function_call_default, tr_array_as_ref,tr_numer]

     The list of the switches that affect the form of the translated
     output.  This information is useful to system people when trying
     to debug the translator.  By comparing the translated product to
     what should have been produced for a given state, it is possible to
     track down bugs.


 -- Function: tr_warnings_get ()
     Prints a list of warnings which have been given by the translator
     during the current translation.


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

     - Gives a warning when when function calls are being made which
     may not be correct due to improper declarations that were made at
     translate time.


 -- Option variable: tr_warn_fexpr
     Default value: `compfile'

     - Gives a warning if any FEXPRs are encountered.  FEXPRs should
     not normally be output in translated code, all legitimate special
     program forms are translated.


 -- Option variable: tr_warn_meval
     Default value: `compfile'

     - Gives a warning if the function `meval' gets called.  If `meval'
     is called that indicates problems in the translation.


 -- Option variable: tr_warn_mode
     Default value: `all'

     - Gives a warning when variables are assigned values inappropriate
     for their mode.


 -- Option variable: tr_warn_undeclared
     Default value: `compile'

     - Determines when to send warnings about undeclared variables to
     the TTY.


 -- Option variable: tr_warn_undefined_variable
     Default value: `all'

     - Gives a warning when undefined global variables are seen.


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

     - Generate helpful comments and programming hints.


 -- Function: compile_file (<filename>)
 -- Function: compile_file (<filename>, <compiled_filename>)
 -- Function: compile_file (<filename>, <compiled_filename>,
          <lisp_filename>)
     Translates the Maxima file <filename> into Lisp, executes the Lisp
     compiler, and, if the translation and compilation succeed, loads
     the compiled code into Maxima.

     `compile_file' returns a list of the names of four files: the
     original Maxima file, the Lisp translation, notes on translation,
     and the compiled code.  If the compilation fails, the fourth item
     is `false'.

     Some declarations and definitions take effect as soon as the Lisp
     code is compiled (without loading the compiled code).  These
     include functions defined with the `:=' operator, macros define
     with the `::=' operator, `alias', `declare', `define_variable',
     `mode_declare', and `infix', `matchfix', `nofix', `postfix',
     `prefix', and `compfile'.

     Assignments and function calls are not evaluated until the
     compiled code is loaded.  In particular, within the Maxima file,
     assignments to the translation flags (`tr_numer', etc.) have no
     effect on the translation.

     <filename> may not contain `:lisp' statements.

     `compile_file' evaluates its arguments.


 -- Function: declare_translated (<f_1>, <f_2>, ...)
     When translating a file of Maxima code to Lisp, it is important
     for the translator to know which functions it sees in the file are
     to be called as translated or compiled functions, and which ones
     are just Maxima functions or undefined.  Putting this declaration
     at the top of the file, lets it know that although a symbol does
     which does not yet have a Lisp function value, will have one at
     call time. `(MFUNCTION-CALL fn arg1 arg2 ...)' is generated when
     the translator does not know `fn' is going to be a Lisp function.



File: maxima.info,  Node: Program Flow,  Next: Debugging,  Prev: Function Definition,  Up: Top

40 Program Flow
***************

* Menu:

* Introduction to Program Flow::
* Functions and Variables for Program Flow::


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

40.1 Introduction to Program Flow
=================================

Maxima provides a `do' loop for iteration, as well as more primitive
constructs such as `go'.


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

40.2 Functions and Variables for Program Flow
=============================================

 -- Function: backtrace ()
 -- Function: backtrace (<n>)
     Prints the call stack, that is, the list of functions which called
     the currently active function.

     `backtrace()' prints the entire call stack.

     `backtrace (<n>)' prints the <n> most recent functions, including
     the currently active function.

     `backtrace' can be called from a script, a function, or the
     interactive prompt (not only in a debugging context).

     Examples:

        * `backtrace()' prints the entire call stack.

               (%i1) h(x) := g(x/7)$
               (%i2) g(x) := f(x-11)$
               (%i3) f(x) := e(x^2)$
               (%i4) e(x) := (backtrace(), 2*x + 13)$
               (%i5) h(10);
               #0: e(x=4489/49)
               #1: f(x=-67/7)
               #2: g(x=10/7)
               #3: h(x=10)
                                             9615
               (%o5)                         ----
                                              49

        * `backtrace (<n>)' prints the <n> most recent functions,
          including the currently active function.

               (%i1) h(x) := (backtrace(1), g(x/7))$
               (%i2) g(x) := (backtrace(1), f(x-11))$
               (%i3) f(x) := (backtrace(1), e(x^2))$
               (%i4) e(x) := (backtrace(1), 2*x + 13)$
               (%i5) h(10);
               #0: h(x=10)
               #0: g(x=10/7)
               #0: f(x=-67/7)
               #0: e(x=4489/49)
                                             9615
               (%o5)                         ----
                                              49


 -- Special operator: do
     The `do' statement is used for performing iteration.  Due to its
     great generality the `do' statement will be described in two parts.
     First the usual form will be given which is analogous to that used
     in several other programming languages (Fortran, Algol, PL/I,
     etc.); then the other features will be mentioned.

     There are three variants of this form that differ only in their
     terminating conditions.  They are:

        * `for <variable>: <initial_value> step <increment>       thru
          <limit> do <body>'

        * `for <variable>: <initial_value> step <increment>       while
          <condition> do <body>'

        * `for <variable>: <initial_value> step <increment>
          unless <condition> do <body>'

     (Alternatively, the `step' may be given after the termination
     condition or limit.)

     <initial_value>, <increment>, <limit>, and <body> can be any
     expressions.  If the increment is 1 then "`step 1'" may be omitted.

     The execution of the `do' statement proceeds by first assigning
     the <initial_value> to the <variable> (henceforth called the
     control-variable). Then: (1) If the control-variable has exceeded
     the limit of a `thru' specification, or if the condition of the
     `unless' is `true', or if the condition of the `while' is `false'
     then the `do' terminates. (2) The <body> is evaluated.  (3) The
     increment is added to the control-variable.  The process from (1)
     to (3) is performed repeatedly until the termination condition is
     satisfied.  One may also give several termination conditions in
     which case the `do' terminates when any of them is satisfied.

     In general the `thru' test is satisfied when the control-variable
     is greater than the <limit> if the <increment> was non-negative,
     or when the control-variable is less than the <limit> if the
     <increment> was negative.  The <increment> and <limit> may be
     non-numeric expressions as long as this inequality can be
     determined.  However, unless the <increment> is syntactically
     negative (e.g. is a negative number) at the time the `do'
     statement is input, Maxima assumes it will be positive when the
     `do' is executed.  If it is not positive, then the `do' may not
     terminate properly.

     Note that the <limit>, <increment>, and termination condition are
     evaluated each time through the loop.  Thus if any of these involve
     much computation, and yield a result that does not change during
     all the executions of the <body>, then it is more efficient to set
     a variable to their value prior to the `do' and use this variable
     in the `do' form.

     The value normally returned by a `do' statement is the atom
     `done'.  However, the function `return' may be used inside the
     <body> to exit the `do' prematurely and give it any desired value.
     Note however that a `return' within a `do' that occurs in a
     `block' will exit only the `do' and not the `block'. Note also
     that the `go' function may not be used to exit from a `do' into a
     surrounding `block'.

     The control-variable is always local to the `do' and thus any
     variable may be used without affecting the value of a variable with
     the same name outside of the `do'.  The control-variable is unbound
     after the `do' terminates.

          (%i1) for a:-3 thru 26 step 7 do display(a)$
                                       a = - 3

                                        a = 4

                                       a = 11

                                       a = 18

                                       a = 25

          (%i1) s: 0$
          (%i2) for i: 1 while i <= 10 do s: s+i;
          (%o2)                         done
          (%i3) s;
          (%o3)                          55

     Note that the condition `while i <= 10' is equivalent to `unless i
     > 10' and also `thru 10'.

          (%i1) series: 1$
          (%i2) term: exp (sin (x))$
          (%i3) for p: 1 unless p > 7 do
                    (term: diff (term, x)/p,
                     series: series + subst (x=0, term)*x^p)$
          (%i4) series;
                            7    6     5    4    2
                           x    x     x    x    x
          (%o4)            -- - --- - -- - -- + -- + x + 1
                           90   240   15   8    2

     which gives 8 terms of the Taylor series for `e^sin(x)'.

          (%i1) poly: 0$
          (%i2) for i: 1 thru 5 do
                    for j: i step -1 thru 1 do
                        poly: poly + i*x^j$
          (%i3) poly;
                            5      4       3       2
          (%o3)          5 x  + 9 x  + 12 x  + 14 x  + 15 x
          (%i4) guess: -3.0$
          (%i5) for i: 1 thru 10 do
                    (guess: subst (guess, x, 0.5*(x + 10/x)),
                     if abs (guess^2 - 10) < 0.00005 then return (guess));
          (%o5)                  - 3.162280701754386

     This example computes the negative square root of 10 using the
     Newton- Raphson iteration a maximum of 10 times.  Had the
     convergence criterion not been met the value returned would have
     been `done'.

     Instead of always adding a quantity to the control-variable one
     may sometimes wish to change it in some other way for each
     iteration.  In this case one may use `next <expression>' instead
     of `step <increment>'.  This will cause the control-variable to be
     set to the result of evaluating <expression> each time through the
     loop.

          (%i6) for count: 2 next 3*count thru 20 do display (count)$
                                      count = 2

                                      count = 6

                                     count = 18

     As an alternative to `for <variable>: <value> ...do...' the syntax
     `for <variable> from <value> ...do...'  may be used.  This permits
     the `from <value>' to be placed after the `step' or `next' value
     or after the termination condition.  If `from <value>' is omitted
     then 1 is used as the initial value.

     Sometimes one may be interested in performing an iteration where
     the control-variable is never actually used.  It is thus
     permissible to give only the termination conditions omitting the
     initialization and updating information as in the following
     example to compute the square-root of 5 using a poor initial guess.

          (%i1) x: 1000$
          (%i2) thru 20 do x: 0.5*(x + 5.0/x)$
          (%i3) x;
          (%o3)                   2.23606797749979
          (%i4) sqrt(5), numer;
          (%o4)                   2.23606797749979

     If it is desired one may even omit the termination conditions
     entirely and just give `do <body>' which will continue to evaluate
     the <body> indefinitely.  In this case the function `return'
     should be used to terminate execution of the `do'.

          (%i1) newton (f, x):= ([y, df, dfx], df: diff (f ('x), 'x),
                    do (y: ev(df), x: x - f(x)/y,
                        if abs (f (x)) < 5e-6 then return (x)))$
          (%i2) sqr (x) := x^2 - 5.0$
          (%i3) newton (sqr, 1000);
          (%o3)                   2.236068027062195

     (Note that `return', when executed, causes the current value of
     `x' to be returned as the value of the `do'.  The `block' is
     exited and this value of the `do' is returned as the value of the
     `block' because the `do' is the last statement in the block.)

     One other form of the `do' is available in Maxima.  The syntax is:

          for <variable> in <list> <end_tests> do <body>

     The elements of <list> are any expressions which will successively
     be assigned to the `variable' on each iteration of the <body>.
     The optional termination tests <end_tests> can be used to
     terminate execution of the `do'; otherwise it will terminate when
     the <list> is exhausted or when a `return' is executed in the
     <body>.  (In fact, `list' may be any non-atomic expression, and
     successive parts are taken.)

          (%i1)  for f in [log, rho, atan] do ldisp(f(1))$
          (%t1)                                  0
          (%t2)                                rho(1)
                                               %pi
          (%t3)                                 ---
                                                4
          (%i4) ev(%t3,numer);
          (%o4)                             0.78539816


 -- Function: errcatch (<expr_1>, ..., <expr_n>)
     Evaluates <expr_1>, ..., <expr_n> one by one and returns
     `[<expr_n>]' (a list) if no error occurs.  If an error occurs in
     the evaluation of any argument, `errcatch' prevents the error from
     propagating and returns the empty list `[]' without evaluating any
     more arguments.

     `errcatch' is useful in `batch' files where one suspects an error
     might occur which would terminate the `batch' if the error weren't
     caught.


 -- Function: error (<expr_1>, ..., <expr_n>)
 -- System variable: error
     Evaluates and prints <expr_1>, ..., <expr_n>, and then causes an
     error return to top level Maxima or to the nearest enclosing
     `errcatch'.

     The variable `error' is set to a list describing the error.  The
     first element of `error' is a format string, which merges all the
     strings among the arguments <expr_1>, ..., <expr_n>, and the
     remaining elements are the values of any non-string arguments.

     `errormsg()' formats and prints `error'.  This is effectively
     reprinting the most recent error message.


 -- Function: errormsg ()
     Reprints the most recent error message.  The variable `error'
     holds the message, and `errormsg' formats and prints it.


 -- Special operator: for
     Used in iterations. See `do' for a description of Maxima's
     iteration facilities.


 -- Function: go (<tag>)
     is used within a `block' to transfer control to the statement of
     the block which is tagged with the argument to `go'.  To tag a
     statement, precede it by an atomic argument as another statement in
     the `block'.  For example:

          block ([x], x:1, loop, x+1, ..., go(loop), ...)

     The argument to `go' must be the name of a tag appearing in the
     same `block'.  One cannot use `go' to transfer to tag in a `block'
     other than the one containing the `go'.


 -- Special operator: if
     Represents conditional evaluation. Various forms of `if'
     expressions are recognized.

     `if <cond_1> then <expr_1> else <expr_0>' evaluates to <expr_1> if
     <cond_1> evaluates to `true', otherwise the expression evaluates
     to <expr_0>.

     `if <cond_1> then <expr_1> elseif <cond_2> then <expr_2> elseif
     ... else <expr_0>' evaluates to <expr_k> if <cond_k> is `true' and
     all preceding conditions are `false'.  If none of the conditions
     are `true', the expression evaluates to `expr_0'.

     A trailing `else false' is assumed if `else' is missing.  That is,
     `if <cond_1> then <expr_1>' is equivalent to `if <cond_1> then
     <expr_1> else false', and `if <cond_1> then <expr_1> elseif ...
     elseif <cond_n> then <expr_n>' is equivalent to `if <cond_1> then
     <expr_1> elseif ... elseif <cond_n> then <expr_n> else false'.

     The alternatives <expr_0>, ..., <expr_n> may be any Maxima
     expressions, including nested `if' expressions.  The alternatives
     are neither simplified nor evaluated unless the corresponding
     condition is `true'.

     The conditions <cond_1>, ..., <cond_n> are expressions which
     potentially or actually evaluate to `true' or `false'.  When a
     condition does not actually evaluate to `true' or `false', the
     behavior of `if' is governed by the global flag `prederror'.  When
     `prederror' is `true', it is an error if any evaluated condition
     does not evaluate to `true' or `false'.  Otherwise, conditions
     which do not evaluate to `true' or `false' are accepted, and the
     result is a conditional expression.

     Among other elements, conditions may comprise relational and
     logical operators as follows.

          Operation            Symbol      Type

          less than            <           relational infix
          less than            <=
            or equal to                    relational infix
          equality (syntactic) =           relational infix
          negation of =        #           relational infix
          equality (value)     equal       relational function
          negation of equal    notequal    relational function
          greater than         >=
            or equal to                    relational infix
          greater than         >           relational infix
          and                  and         logical infix
          or                   or          logical infix
          not                  not         logical prefix


 -- Function: map (<f>, <expr_1>, ..., <expr_n>)
     Returns an expression whose leading operator is the same as that
     of the expressions <expr_1>, ..., <expr_n> but whose subparts are
     the results of applying <f> to the corresponding subparts of the
     expressions.  <f> is either the name of a function of n arguments
     or is a `lambda' form of n arguments.

     `maperror' - if `false' will cause all of the mapping functions to
     (1) stop when they finish going down the shortest <expr_i> if not
     all of the <expr_i> are of the same length and (2) apply <f> to
     [<expr_1>, <expr_2>, ...]  if the <expr_i> are not all the same
     type of object. If `maperror' is `true' then an error message will
     be given in the above two instances.

     One of the uses of this function is to `map' a function (e.g.
     `partfrac') onto each term of a very large expression where it
     ordinarily wouldn't be possible to use the function on the entire
     expression due to an exhaustion of list storage space in the
     course of the computation.

          (%i1) map(f,x+a*y+b*z);
          (%o1)                        f(b z) + f(a y) + f(x)
          (%i2) map(lambda([u],partfrac(u,x)),x+1/(x^3+4*x^2+5*x+2));
                                     1       1        1
          (%o2)                     ----- - ----- + -------- + x
                                   x + 2   x + 1          2
                                                   (x + 1)
          (%i3) map(ratsimp, x/(x^2+x)+(y^2+y)/y);
                                                1
          (%o3)                            y + ----- + 1
                                              x + 1
          (%i4) map("=",[a,b],[-0.5,3]);
          (%o4)                          [a = - 0.5, b = 3]

 -- Function: mapatom (<expr>)
     Returns `true' if and only if <expr> is treated by the mapping
     routines as an atom.  "Mapatoms" are atoms, numbers (including
     rational numbers), and subscripted variables.


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

     When `maperror' is `false', causes all of the mapping functions,
     for example

          map (<f>, <expr_1>, <expr_2>, ...)

     to (1) stop when they finish going down the shortest <expr_i> if
     not all of the <expr_i> are of the same length and (2) apply <f>
     to [<expr_1>, <expr_2>, ...] if the <expr_i> are not all the same
     type of object.

     If `maperror' is `true' then an error message is displayed in the
     above two instances.


 -- Function: maplist (<f>, <expr_1>, ..., <expr_n>)
     Returns a list of the applications of <f> to the parts of the
     expressions <expr_1>, ..., <expr_n>.  <f> is the name of a
     function, or a lambda expression.

     `maplist' differs from `map (<f>, <expr_1>, ..., <expr_n>)' which
     returns an expression with the same main operator as <expr_i> has
     (except for simplifications and the case where `map' does an
     `apply').


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

     When `prederror' is `true', an error message is displayed whenever
     the predicate of an `if' statement or an `is' function fails to
     evaluate to either `true' or `false'.

     If `false', `unknown' is returned instead in this case.  The
     `prederror: false' mode is not supported in translated code;
     however, `maybe' is supported in translated code.

     See also `is' and `maybe'.


 -- Function: return (<value>)
     May be used to exit explicitly from a block, bringing its
     argument.  See `block' for more information.


 -- Function: scanmap (<f>, <expr>)
 -- Function: scanmap (<f>, <expr>, bottomup)
     Recursively applies <f> to <expr>, in a top down manner.  This is
     most useful when complete factorization is desired, for example:

          (%i1) exp:(a^2+2*a+1)*y + x^2$
          (%i2) scanmap(factor,exp);
                                              2      2
          (%o2)                         (a + 1)  y + x

     Note the way in which `scanmap' applies the given function
     `factor' to the constituent subexpressions of <expr>; if another
     form of <expr> is presented to `scanmap' then the result may be
     different. Thus, `%o2' is not recovered when `scanmap' is applied
     to the expanded form of `exp':

          (%i3) scanmap(factor,expand(exp));
                                     2                  2
          (%o3)                      a  y + 2 a y + y + x

     Here is another example of the way in which `scanmap' recursively
     applies a given function to all subexpressions, including
     exponents:

          (%i4) expr : u*v^(a*x+b) + c$
          (%i5) scanmap('f, expr);
                              f(f(f(a) f(x)) + f(b))
          (%o5) f(f(f(u) f(f(v)                      )) + f(c))

     `scanmap (<f>, <expr>, bottomup)' applies <f> to <expr> in a
     bottom-up manner.  E.g., for undefined `f',

          scanmap(f,a*x+b) ->
             f(a*x+b) -> f(f(a*x)+f(b)) -> f(f(f(a)*f(x))+f(b))
          scanmap(f,a*x+b,bottomup) -> f(a)*f(x)+f(b)
              -> f(f(a)*f(x))+f(b) ->
               f(f(f(a)*f(x))+f(b))

     In this case, you get the same answer both ways.


 -- Function: throw (<expr>)
     Evaluates <expr> and throws the value back to the most recent
     `catch'.  `throw' is used with `catch' as a nonlocal return
     mechanism.


 -- Special operator: while
     See `do'.


 -- Function: outermap (<f>, <a_1>, ..., <a_n>)
     Applies the function <f> to each one of the elements of the outer
     product <a_1> cross <a_2> ... cross <a_n>.

     <f> is the name of a function of n arguments or a lambda
     expression of n arguments.  Each argument <a_k> may be a list or
     nested list, or a matrix, or any other kind of expression.

     The `outermap' return value is a nested structure.  Let <x> be the
     return value.  Then <x> has the same structure as the first list,
     nested list, or matrix argument, `<x>[i_1]...[i_m]' has the same
     structure as the second list, nested list, or matrix argument,
     `<x>[i_1]...[i_m][j_1]...[j_n]' has the same structure as the
     third list, nested list, or matrix argument, and so on, where <m>,
     <n>, ... are the numbers of indices required to access the
     elements of each argument (one for a list, two for a matrix, one
     or more for a nested list).  Arguments which are not lists or
     matrices have no effect on the structure of the return value.

     Note that the effect of `outermap' is different from that of
     applying <f> to each one of the elements of the outer product
     returned by `cartesian_product'.  `outermap' preserves the
     structure of the arguments in the return value, while
     `cartesian_product' does not.

     `outermap' evaluates its arguments.

     See also `map', `maplist', and `apply'.

     Examples:

     Elementary examples of `outermap'.  To show the argument
     combinations more clearly, `F' is left undefined.

          (%i1) outermap(F, [a, b, c], [1, 2, 3]);
          (%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)],
                                               [F(c, 1), F(c, 2), F(c, 3)]]
          (%i2) outermap(F, matrix([a, b],[c, d]), matrix([1, 2],[3, 4]));
                   [ [ F(a, 1)  F(a, 2) ]  [ F(b, 1)  F(b, 2) ] ]
                   [ [                  ]  [                  ] ]
                   [ [ F(a, 3)  F(a, 4) ]  [ F(b, 3)  F(b, 4) ] ]
          (%o2)    [                                            ]
                   [ [ F(c, 1)  F(c, 2) ]  [ F(d, 1)  F(d, 2) ] ]
                   [ [                  ]  [                  ] ]
                   [ [ F(c, 3)  F(c, 4) ]  [ F(d, 3)  F(d, 4) ] ]
          (%i3) outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
                 [ F(a, x, 1)  F(a, x, 2) ]  [ F(b, x, 1)  F(b, x, 2) ]
          (%o3) [[                        ], [                        ]]
                 [ F(a, x, 3)  F(a, x, 4) ]  [ F(b, x, 3)  F(b, x, 4) ]
          (%i4) outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
                 [ [ F(a, 1, x) ]  [ F(a, 2, x) ] ]
          (%o4) [[ [            ]  [            ] ],
                 [ [ F(a, 1, y) ]  [ F(a, 2, y) ] ]
                                        [ [ F(b, 1, x) ]  [ F(b, 2, x) ] ]
                                        [ [            ]  [            ] ]]
                                        [ [ F(b, 1, y) ]  [ F(b, 2, y) ] ]
          (%i5) outermap ("+", [a, b, c], [1, 2, 3]);
          (%o5) [[a + 1, a + 2, a + 3], [b + 1, b + 2, b + 3],
                                                     [c + 1, c + 2, c + 3]]

     A closer examination of the `outermap' return value.  The first,
     second, and third arguments are a matrix, a list, and a matrix,
     respectively.  The return value is a matrix.  Each element of that
     matrix is a list, and each element of each list is a matrix.

          (%i1) arg_1 :  matrix ([a, b], [c, d]);
                                      [ a  b ]
          (%o1)                       [      ]
                                      [ c  d ]
          (%i2) arg_2 : [11, 22];
          (%o2)                       [11, 22]
          (%i3) arg_3 : matrix ([xx, yy]);
          (%o3)                      [ xx  yy ]
          (%i4) xx_0 : outermap(lambda([x, y, z], x / y + z), arg_1,
                                                             arg_2, arg_3);
                         [  [      a        a  ]  [      a        a  ]  ]
                         [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
                         [  [      11       11 ]  [      22       22 ]  ]
          (%o4)  Col 1 = [                                              ]
                         [  [      c        c  ]  [      c        c  ]  ]
                         [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
                         [  [      11       11 ]  [      22       22 ]  ]
                           [  [      b        b  ]  [      b        b  ]  ]
                           [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
                           [  [      11       11 ]  [      22       22 ]  ]
                   Col 2 = [                                              ]
                           [  [      d        d  ]  [      d        d  ]  ]
                           [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
                           [  [      11       11 ]  [      22       22 ]  ]
          (%i5) xx_1 : xx_0 [1][1];
                     [      a        a  ]  [      a        a  ]
          (%o5)     [[ xx + --  yy + -- ], [ xx + --  yy + -- ]]
                     [      11       11 ]  [      22       22 ]
          (%i6) xx_2 : xx_0 [1][1] [1];
                                [      a        a  ]
          (%o6)                 [ xx + --  yy + -- ]
                                [      11       11 ]
          (%i7) xx_3 : xx_0 [1][1] [1] [1][1];
                                            a
          (%o7)                        xx + --
                                            11
          (%i8) [op (arg_1), op (arg_2), op (arg_3)];
          (%o8)                  [matrix, [, matrix]
          (%i9) [op (xx_0), op (xx_1), op (xx_2)];
          (%o9)                  [matrix, [, matrix]

     `outermap' preserves the structure of the arguments in the return
     value, while `cartesian_product' does not.

          (%i1) outermap (F, [a, b, c], [1, 2, 3]);
          (%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)],
                                               [F(c, 1), F(c, 2), F(c, 3)]]
          (%i2) setify (flatten (%));
          (%o2) {F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3),
                                                 F(c, 1), F(c, 2), F(c, 3)}
          (%i3) map(lambda([L], apply(F, L)),
                               cartesian_product({a, b, c}, {1, 2, 3}));
          (%o3) {F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3),
                                                 F(c, 1), F(c, 2), F(c, 3)}
          (%i4) is (equal (%, %th (2)));
          (%o4)                         true



File: maxima.info,  Node: Debugging,  Next: augmented_lagrangian,  Prev: Program Flow,  Up: Top

41 Debugging
************

* Menu:

* Source Level Debugging::
* Keyword Commands::
* Functions and Variables for Debugging::


File: maxima.info,  Node: Source Level Debugging,  Next: Keyword Commands,  Up: Debugging

41.1 Source Level Debugging
===========================

Maxima has a built-in source level debugger.  The user can set a
breakpoint at a function, and then step line by line from there.  The
call stack may be examined, together with the variables bound at that
level.

   The command `:help' or `:h' shows the list of debugger commands.
(In general, commands may be abbreviated if the abbreviation is unique.
If not unique, the alternatives will be listed.)  Within the debugger,
the user can also use any ordinary Maxima functions to examine, define,
and manipulate variables and expressions.

   A breakpoint is set by the `:br' command at the Maxima prompt.
Within the debugger, the user can advance one line at a time using the
`:n' ("next") command.  The `:bt' ("backtrace") command shows a list of
stack frames.  The `:r' ("resume") command exits the debugger and
continues with execution.  These commands are demonstrated in the
example below.

     (%i1) load ("/tmp/foobar.mac");

     (%o1)                           /tmp/foobar.mac

     (%i2) :br foo
     Turning on debugging debugmode(true)
     Bkpt 0 for foo (in /tmp/foobar.mac line 1)

     (%i2) bar (2,3);
     Bkpt 0:(foobar.mac 1)
     /tmp/foobar.mac:1::

     (dbm:1) :bt                        <-- :bt typed here gives a backtrace
     #0: foo(y=5)(foobar.mac line 1)
     #1: bar(x=2,y=3)(foobar.mac line 9)

     (dbm:1) :n                         <-- Here type :n to advance line
     (foobar.mac 2)
     /tmp/foobar.mac:2::

     (dbm:1) :n                         <-- Here type :n to advance line
     (foobar.mac 3)
     /tmp/foobar.mac:3::

     (dbm:1) u;                         <-- Investigate value of u
     28

     (dbm:1) u: 33;                     <-- Change u to be 33
     33

     (dbm:1) :r                         <-- Type :r to resume the computation

     (%o2)                                1094

   The file `/tmp/foobar.mac' is the following:

     foo(y) := block ([u:y^2],
       u: u+3,
       u: u^2,
       u);

     bar(x,y) := (
       x: x+2,
       y: y+2,
       x: foo(y),
       x+y);

   USE OF THE DEBUGGER THROUGH EMACS

   If the user is running the code under GNU emacs in a shell window
(dbl shell), or is running the graphical interface version, Xmaxima,
then if he stops at a break point, he will see his current position in
the source file which will be displayed in the other half of the
window, either highlighted in red, or with a little arrow pointing at
the right line.  He can advance single lines at a time by typing M-n
(Alt-n).

   Under Emacs you should run in a `dbl' shell, which requires the
`dbl.el' file in the elisp directory.  Make sure you install the elisp
files or add the Maxima elisp directory to your path: e.g., add the
following to your `.emacs' file or the `site-init.el'

     (setq load-path (cons "/usr/share/maxima/5.9.1/emacs" load-path))
     (autoload 'dbl "dbl")

   then in emacs

     M-x dbl

   should start a shell window in which you can run programs, for
example Maxima, gcl, gdb etc.   This shell window also knows about
source level debugging, and display of source code in the other window.

   The user may set a break point at a certain line of the file by
typing `C-x space'.  This figures out which function the cursor is in,
and then it sees which line of that function the cursor is on.   If the
cursor is on, say, line 2 of `foo', then it will insert in the other
window the command, "`:br foo 2'", to break `foo' at its second line.
To have this enabled, the user must have maxima-mode.el turned on in
the window in which the file `foobar.mac' is visiting.  There are
additional commands available in that file window, such as evaluating
the function into the Maxima, by typing `Alt-Control-x'.