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

     The declaration `local(<v_1>, ..., <v_m>)' within `block' saves
     the properties associated with the symbols <v_1>, ..., <v_m>,
     removes any properties before evaluating other expressions, and
     restores any saved properties on exit from the block.  Some
     declarations are implemented as properties of a symbol, including
     `:=', `array', `dependencies', `atvalue', `matchdeclare',
     `atomgrad', `constant', `nonscalar', `assume', and some others.
     The effect of `local' is to make such declarations effective only
     within the block; otherwise declarations within a block are
     actually global declarations.

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

     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 automatically
     limit the scope of `f' to `g'.  However, `local(f)' makes the
     definition of function `f' effective only within the block or
     other compound expression in which `local' appears.

     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>)
     Saves the properties associated with the symbols <v_1>, ..., <v_n>,
     removes any properties before evaluating other expressions, and
     restores any saved properties on exit from the block or other
     compound expression in which `local' appears.

     Some declarations are implemented as properties of a symbol,
     including `:=', `array', `dependencies', `atvalue', `matchdeclare',
     `atomgrad', `constant', `nonscalar', `assume', and some others.
     The effect of `local' is to make such declarations effective only
     within the block or other compound expression in which `local'
     appears; otherwise such declarations are global declarations.

     `local' can only appear in `block' or in the body of a function
     definition or `lambda' expression, and only one occurrence is
     permitted in each.

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

     Example:

     A local function definition.

          (%i1) foo (x) := 1 - x;
          (%o1)                    foo(x) := 1 - x
          (%i2) foo (100);
          (%o2)                         - 99
          (%i3) block (local (foo), foo (x) := 2 * x, foo (100));
          (%o3)                          200
          (%i4) foo (100);
          (%o4)                         - 99


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


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

     When `mapprint' is `true', various information messages from
     `map', `mapl', and `fullmap' are produced in certain situations.
     These include situations where `map' would use `apply', or `map'
     is truncating on the shortest list.

     If `mapprint' is `false', these messages are suppressed.


 -- 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: `false'

     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
 -- Special operator: unless
     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'.


File: maxima.info,  Node: Keyword Commands,  Next: Functions and Variables for Debugging,  Prev: Source Level Debugging,  Up: Debugging

41.2 Keyword Commands
=====================

Keyword commands are special keywords which are not interpreted as
Maxima expressions.  A keyword command can be entered at the Maxima
prompt or the debugger prompt, although not at the break prompt.
Keyword commands start with a colon, '`:''.  For example, to evaluate a
Lisp form you may type `:lisp' followed by the form to be evaluated.

     (%i1) :lisp (+ 2 3)
     5

   The number of arguments taken depends on the particular command.
Also, you need not type the whole command, just enough to be unique
among the break keywords.   Thus `:br' would suffice for `:break'.

   The keyword commands are listed below.

`:break F n'
     Set a breakpoint in function `F' at line offset `n' from the
     beginning of the function.  If `F' is given as a string, then it
     is assumed to be a file, and `n' is the offset from the beginning
     of the file.  The offset is optional. If not given, it is assumed
     to be zero (first line of the function or file).

`:bt'
     Print a backtrace of the stack frames

`:continue'
     Continue the computation

`:delete'
     Delete the specified breakpoints, or all if none are specified

`:disable'
     Disable the specified breakpoints, or all if none are specified

`:enable'
     Enable the specified breakpoints, or all if none are specified

`:frame n'
     Print stack frame `n', or the current frame if none is specified

`:help'
     Print help on a debugger command, or all commands if none is
     specified

`:info'
     Print information about item

`:lisp some-form'
     Evaluate `some-form' as a Lisp form

`:lisp-quiet some-form'
     Evaluate Lisp form `some-form' without any output

`:next'
     Like `:step', except `:next' steps over function calls

`:quit'
     Quit the current debugger level without completing the computation

`:resume'
     Continue the computation

`:step'
     Continue the computation until it reaches a new source line

`:top'
     Return to the Maxima prompt (from any debugger level) without
     completing the computation


File: maxima.info,  Node: Functions and Variables for Debugging,  Prev: Keyword Commands,  Up: Debugging

41.3 Functions and Variables for Debugging
==========================================

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

     When `refcheck' is `true', Maxima prints a message each time a
     bound variable is used for the first time in a computation.


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

     If `setcheck' is set to a list of variables (which can be
     subscripted), Maxima prints a message whenever the variables, or
     subscripted occurrences of them, are bound with the ordinary
     assignment operator `:', the `::' assignment operator, or function
     argument binding, but not the function assignment `:=' nor the
     macro assignment `::=' operators.  The message comprises the name
     of the variable and the value it is bound to.

     `setcheck' may be set to `all' or `true' thereby including all
     variables.

     Each new assignment of `setcheck' establishes a new list of
     variables to check, and any variables previously assigned to
     `setcheck' are forgotten.

     The names assigned to `setcheck' must be quoted if they would
     otherwise evaluate to something other than themselves.  For
     example, if `x', `y', and `z' are already bound, then enter

          setcheck: ['x, 'y, 'z]$

     to put them on the list of variables to check.

     No printout is generated when a variable on the `setcheck' list is
     assigned to itself, e.g., `X: 'X'.


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

     When `setcheckbreak' is `true', Maxima will present a break prompt
     whenever a variable on the `setcheck' list is assigned a new value.
     The break occurs before the assignment is carried out.  At this
     point, `setval' holds the value to which the variable is about to
     be assigned.  Hence, one may assign a different value by assigning
     to `setval'.

     See also `setcheck' and `setval'.


 -- System variable: setval
     Holds the value to which a variable is about to be set when a
     `setcheckbreak' occurs.  Hence, one may assign a different value
     by assigning to `setval'.

     See also `setcheck' and `setcheckbreak'.


 -- Function: timer (<f_1>, ..., <f_n>)
 -- Function: timer (all)
 -- Function: timer ()
     Given functions <f_1>, ..., <f_n>, `timer' puts each one on the
     list of functions for which timing statistics are collected.
     `timer(f)$ timer(g)$' puts `f' and then `g' onto the list; the
     list accumulates from one call to the next.

     `timer(all)' puts all user-defined functions (as named by the
     global variable `functions') on the list of timed functions.

     With no arguments, `timer' returns the list of timed functions.

     Maxima records how much time is spent executing each function on
     the list of timed functions.  `timer_info' returns the timing
     statistics, including the average time elapsed per function call,
     the number of calls, and the total time elapsed.  `untimer'
     removes functions from the list of timed functions.

     `timer' quotes its arguments.  `f(x) := x^2$ g:f$ timer(g)$' does
     not put `f' on the timer list.

     If `trace(f)' is in effect, then `timer(f)' has no effect; `trace'
     and `timer' cannot both be in effect at the same time.

     See also `timer_devalue'.


 -- Function: untimer (<f_1>, ..., <f_n>)
 -- Function: untimer ()
     Given functions <f_1>, ..., <f_n>, `untimer' removes each function
     from the timer list.

     With no arguments, `untimer' removes all functions currently on
     the timer list.

     After `untimer (f)' is executed, `timer_info (f)' still returns
     previously collected timing statistics, although `timer_info()'
     (with no arguments) does not return information about any function
     not currently on the timer list.  `timer (f)' resets all timing
     statistics to zero and puts `f' on the timer list again.


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

     When `timer_devalue' is `true', Maxima subtracts from each timed
     function the time spent in other timed functions. Otherwise, the
     time reported for each function includes the time spent in other
     functions.  Note that time spent in untimed functions is not
     subtracted from the total time.

     See also `timer' and `timer_info'.


 -- Function: timer_info (<f_1>, ..., <f_n>)
 -- Function: timer_info ()
     Given functions <f_1>, ..., <f_n>, `timer_info' returns a matrix
     containing timing information for each function.  With no
     arguments, `timer_info' returns timing information for all
     functions currently on the timer list.

     The matrix returned by `timer_info' contains the function name,
     time per function call, number of function calls, total time, and
     `gctime', which meant "garbage collection time" in the original
     Macsyma but is now always zero.

     The data from which `timer_info' constructs its return value can
     also be obtained by the `get' function:

          get(f, 'calls);  get(f, 'runtime);  get(f, 'gctime);

     See also `timer'.


 -- Function: trace (<f_1>, ..., <f_n>)
 -- Function: trace (all)
 -- Function: trace ()
     Given functions <f_1>, ..., <f_n>, `trace' instructs Maxima to
     print out debugging information whenever those functions are
     called.  `trace(f)$ trace(g)$' puts `f' and then `g' onto the list
     of functions to be traced; the list accumulates from one call to
     the next.

     `trace(all)' puts all user-defined functions (as named by the
     global variable `functions') on the list of functions to be traced.

     With no arguments, `trace' returns a list of all the functions
     currently being traced.

     The `untrace' function disables tracing.  See also `trace_options'.

     `trace' quotes its arguments. Thus, `f(x) := x^2$ g:f$ trace(g)$'
     does not put `f' on the trace list.

     When a function is redefined, it is removed from the timer list.
     Thus after `timer(f)$ f(x) := x^2$', function `f' is no longer on
     the timer list.

     If `timer (f)' is in effect, then `trace (f)' has no effect;
     `trace' and `timer' can't both be in effect for the same function.


 -- Function: trace_options (<f>, <option_1>, ..., <option_n>)
 -- Function: trace_options (<f>)
     Sets the trace options for function <f>.  Any previous options are
     superseded.  `trace_options (<f>, ...)' has no effect unless
     `trace (<f>)' is also called (either before or after
     `trace_options').

     `trace_options (<f>)' resets all options to their default values.

     The option keywords are:

        * `noprint' Do not print a message at function entry and exit.

        * `break' Put a breakpoint before the function is entered, and
          after the function is exited. See `break'.

        * `lisp_print' Display arguments and return values as Lisp
          objects.

        * `info' Print `-> true' at function entry and exit.

        * `errorcatch' Catch errors, giving the option to signal an
          error, retry the function call, or specify a return value.

     Trace options are specified in two forms. The presence of the
     option keyword alone puts the option into effect unconditionally.
     (Note that option <foo> is not put into effect by specifying
     `<foo>: true' or a similar form; note also that keywords need not
     be quoted.) Specifying the option keyword with a predicate
     function makes the option conditional on the predicate.

     The argument list to the predicate function is always `[level,
     direction, function, item]' where `level' is the recursion level
     for the function,  `direction' is either `enter' or `exit',
     `function' is the name of the function, and `item' is the argument
     list (on entering) or the return value (on exiting).

     Here is an example of unconditional trace options:

          (%i1) ff(n) := if equal(n, 0) then 1 else n * ff(n - 1)$

          (%i2) trace (ff)$

          (%i3) trace_options (ff, lisp_print, break)$

          (%i4) ff(3);

     Here is the same function, with the `break' option conditional on
     a predicate:

          (%i5) trace_options (ff, break(pp))$

          (%i6) pp (level, direction, function, item) := block (print (item),
              return (function = 'ff and level = 3 and direction = exit))$

          (%i7) ff(6);


 -- Function: untrace (<f_1>, ..., <f_n>)
 -- Function: untrace ()
     Given functions <f_1>, ..., <f_n>, `untrace' disables tracing
     enabled by the `trace' function.  With no arguments, `untrace'
     disables tracing for all functions.

     `untrace' returns a list of the functions for which it disabled
     tracing.



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

42 augmented_lagrangian
***********************

* Menu:

* Functions and Variables for augmented_lagrangian::


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

42.1 Functions and Variables for augmented_lagrangian
=====================================================

 -- Function: augmented_lagrangian_method (<FOM>, <xx>, <C>, <yy>)
 -- Function: augmented_lagrangian_method (<FOM>, <xx>, <C>, <yy>,
          optional_args)
     Returns an approximate minimum of the expression <FOM> with
     respect to the variables <xx>, holding the constraints <C> equal
     to zero.  <yy> is a list of initial guesses for <xx>.  The method
     employed is the augmented Lagrangian method (see Refs [1] and [2]).

     `optional_args' represents additional arguments, specified as
     `<symbol> = <value>'.  The optional arguments recognized are:

    `niter'
          Number of iterations of the augmented Lagrangian algorithm

    `lbfgs_tolerance'
          Tolerance supplied to LBFGS

    `iprint'
          IPRINT parameter (a list of two integers which controls
          verbosity) supplied to LBFGS

    `%lambda'
          Initial value of `%lambda' to be used for calculating the
          augmented Lagrangian

     This implementation minimizes the augmented Lagrangian by applying
     the limited-memory BFGS (LBFGS) algorithm, which is a quasi-Newton
     algorithm.

     `load(augmented_lagrangian)' loads this function.

     See also `lbfgs'.

     References:

     [1]
     `http://www-fp.mcs.anl.gov/otc/Guide/OptWeb/continuous/constrained/nonlinearcon/auglag.html'

     [2] `http://www.cs.ubc.ca/spider/ascher/542/chap10.pdf'

     Example:

          (%i1) load (lbfgs);
          (%o1)     /maxima/share/lbfgs/lbfgs.mac
          (%i2) load (augmented_lagrangian);
          (%o2)
             /maxima/share/contrib/augmented_lagrangian.mac
          (%i3) FOM: x^2 + 2*y^2;
                                         2    2
          (%o3)                       2 y  + x
          (%i4) xx: [x, y];
          (%o4)                        [x, y]
          (%i5) C: [x + y - 1];
          (%o5)                      [y + x - 1]
          (%i6) yy: [1, 1];
          (%o6)                        [1, 1]
          (%i7) augmented_lagrangian_method(FOM, xx, C, yy, iprint=[-1,0]);
          (%o7) [[x = 0.66665984108002, y = 0.33334027245545],
                                           %lambda = [- 1.333337940892525]]



File: maxima.info,  Node: bode,  Next: contrib_ode,  Prev: augmented_lagrangian,  Up: Top

43 bode
*******

* Menu:

* Functions and Variables for bode::


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

43.1 Functions and Variables for bode
=====================================

 -- Function: bode_gain (<H>, <range>, ...<plot_opts>...)
     Function to draw Bode gain plots.

     Examples (1 through 7 from
          `http://www.swarthmore.edu/NatSci/echeeve1/Ref/Bode/BodeHow.html',
     8 from Ron Crummett):
          (%i1) load("bode")$

          (%i2) H1 (s) := 100 * (1 + s) / ((s + 10) * (s + 100))$

          (%i3) bode_gain (H1 (s), [w, 1/1000, 1000])$

          (%i4) H2 (s) := 1 / (1 + s/omega0)$

          (%i5) bode_gain (H2 (s), [w, 1/1000, 1000]), omega0 = 10$

          (%i6) H3 (s) := 1 / (1 + s/omega0)^2$

          (%i7) bode_gain (H3 (s), [w, 1/1000, 1000]), omega0 = 10$

          (%i8) H4 (s) := 1 + s/omega0$

          (%i9) bode_gain (H4 (s), [w, 1/1000, 1000]), omega0 = 10$

          (%i10) H5 (s) := 1/s$

          (%i11) bode_gain (H5 (s), [w, 1/1000, 1000])$

          (%i12) H6 (s) := 1/((s/omega0)^2 + 2 * zeta * (s/omega0) + 1)$

          (%i13) bode_gain (H6 (s), [w, 1/1000, 1000]),
                            omega0 = 10, zeta = 1/10$

          (%i14) H7 (s) := (s/omega0)^2 + 2 * zeta * (s/omega0) + 1$

          (%i15) bode_gain (H7 (s), [w, 1/1000, 1000]),
                            omega0 = 10, zeta = 1/10$

          (%i16) H8 (s) := 0.5 / (0.0001 * s^3 + 0.002 * s^2 + 0.01 * s)$

          (%i17) bode_gain (H8 (s), [w, 1/1000, 1000])$

     To use this function write first `load("bode")'. See also
     `bode_phase'


 -- Function: bode_phase (<H>, <range>, ...<plot_opts>...)
     Function to draw Bode phase plots.

     Examples (1 through 7 from
          `http://www.swarthmore.edu/NatSci/echeeve1/Ref/Bode/BodeHow.html',
     8 from Ron Crummett):
          (%i1) load("bode")$

          (%i2) H1 (s) := 100 * (1 + s) / ((s + 10) * (s + 100))$

          (%i3) bode_phase (H1 (s), [w, 1/1000, 1000])$

          (%i4) H2 (s) := 1 / (1 + s/omega0)$

          (%i5) bode_phase (H2 (s), [w, 1/1000, 1000]), omega0 = 10$

          (%i6) H3 (s) := 1 / (1 + s/omega0)^2$

          (%i7) bode_phase (H3 (s), [w, 1/1000, 1000]), omega0 = 10$

          (%i8) H4 (s) := 1 + s/omega0$

          (%i9) bode_phase (H4 (s), [w, 1/1000, 1000]), omega0 = 10$

          (%i10) H5 (s) := 1/s$

          (%i11) bode_phase (H5 (s), [w, 1/1000, 1000])$

          (%i12) H6 (s) := 1/((s/omega0)^2 + 2 * zeta * (s/omega0) + 1)$

          (%i13) bode_phase (H6 (s), [w, 1/1000, 1000]),
                             omega0 = 10, zeta = 1/10$

          (%i14) H7 (s) := (s/omega0)^2 + 2 * zeta * (s/omega0) + 1$

          (%i15) bode_phase (H7 (s), [w, 1/1000, 1000]),
                             omega0 = 10, zeta = 1/10$

          (%i16) H8 (s) := 0.5 / (0.0001 * s^3 + 0.002 * s^2 + 0.01 * s)$

          (%i17) bode_phase (H8 (s), [w, 1/1000, 1000])$

          (%i18) block ([bode_phase_unwrap : false],
                        bode_phase (H8 (s), [w, 1/1000, 1000]));

          (%i19) block ([bode_phase_unwrap : true],
                        bode_phase (H8 (s), [w, 1/1000, 1000]));

     To use this function write first `load("bode")'. See also
     `bode_gain'



File: maxima.info,  Node: contrib_ode,  Next: descriptive,  Prev: bode,  Up: Top

44 contrib_ode
**************

* Menu:

* Introduction to contrib_ode::
* Functions and Variables for contrib_ode::
* Possible improvements to contrib_ode::
* Test cases for contrib_ode::
* References for contrib_ode::


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

44.1 Introduction to contrib_ode
================================

Maxima's ordinary differential equation (ODE) solver `ode2' solves
elementary linear ODEs of first and second order.  The function
`contrib_ode' extends `ode2' with additional methods for linear and
non-linear first order ODEs and linear homogeneous second order ODEs.
The code is still under development and the calling sequence may change
in future releases.  Once the code has stabilized it may be moved from
the contrib directory and integrated into Maxima.

   This package must be loaded with the command `load('contrib_ode)'
before use.

   The calling convention for `contrib_ode' is identical to `ode2'.  It
takes three arguments: an ODE (only the left hand side need be given if
the right hand side is 0), the dependent variable, and the independent
variable.  When successful, it returns a list of solutions.

   The form of the solution differs from `ode2'.  As non-linear
equations can have multiple solutions, `contrib_ode' returns a list of
solutions.  Each  solution can have a number of forms:
   * an explicit solution for the dependent variable,

   * an implicit solution for the dependent variable,

   * a parametric solution in terms of variable `%t', or

   * a tranformation into another ODE in variable `%u'.


   `%c' is used to represent the constant of integration for first
order equations.  `%k1' and `%k2' are the constants for second order
equations.  If `contrib_ode' cannot obtain a solution for whatever
reason, it returns `false', after perhaps printing out an error message.

   It is necessary to return a list of solutions, as even first order
non-linear ODEs can have multiple solutions.  For example:

     (%i1) load('contrib_ode)$

     (%i2) eqn:x*'diff(y,x)^2-(1+x*y)*'diff(y,x)+y=0;

                         dy 2             dy
     (%o2)            x (--)  - (x y + 1) -- + y = 0
                         dx               dx
     (%i3) contrib_ode(eqn,y,x);

                                                  x
     (%o3)             [y = log(x) + %c, y = %c %e ]
     (%i4) method;

     (%o4)                        factor

   Nonlinear ODEs can have singular solutions without constants of
integration, as in the second solution of the following example:

     (%i1) load('contrib_ode)$

     (%i2) eqn:'diff(y,x)^2+x*'diff(y,x)-y=0;

                            dy 2     dy
     (%o2)                 (--)  + x -- - y = 0
                            dx       dx
     (%i3) contrib_ode(eqn,y,x);

                                                2
                                      2        x
     (%o3)              [y = %c x + %c , y = - --]
                                               4
     (%i4) method;

     (%o4)                       clairault

   The following ODE has two parametric solutions in terms of the dummy
variable `%t'.  In this case the parametric solutions can be manipulated
to give explicit solutions.

     (%i1) load('contrib_ode)$

     (%i2) eqn:'diff(y,x)=(x+y)^2;

                               dy          2
     (%o2)                     -- = (y + x)
                               dx
     (%i3) contrib_ode(eqn,y,x);

     (%o3) [[x = %c - atan(sqrt(%t)), y = - x - sqrt(%t)],
                          [x = atan(sqrt(%t)) + %c, y = sqrt(%t) - x]]
     (%i4) method;

     (%o4)                       lagrange

   The following example (Kamke 1.112) demonstrates an implicit
solution.

     (%i1) load('contrib_ode)$

     (%i2) assume(x>0,y>0);

     (%o2)                    [x > 0, y > 0]
     (%i3) eqn:x*'diff(y,x)-x*sqrt(y^2+x^2)-y;

                          dy           2    2
     (%o3)              x -- - x sqrt(y  + x ) - y
                          dx
     (%i4) contrib_ode(eqn,y,x);

                                       y
     (%o4)                  [x - asinh(-) = %c]
                                       x
     (%i5) method;

     (%o5)                          lie

   The following Riccati equation is transformed into a linear second
order ODE in the variable `%u'.  Maxima is unable to solve the new ODE,
so it is returned unevaluated.
     (%i1) load('contrib_ode)$

     (%i2) eqn:x^2*'diff(y,x)=a+b*x^n+c*x^2*y^2;

                         2 dy      2  2      n
     (%o2)              x  -- = c x  y  + b x  + a
                           dx
     (%i3) contrib_ode(eqn,y,x);

                    d%u
                    ---                            2
                    dx        2     n - 2   a     d %u
     (%o3)  [[y = - ----, %u c  (b x      + --) + ---- c = 0]]
                    %u c                     2      2
                                            x     dx
     (%i4) method;

     (%o4)                        riccati

   For first order ODEs `contrib_ode' calls `ode2'.  It then tries the
following methods: factorization, Clairault, Lagrange, Riccati, Abel
and Lie symmetry methods.  The Lie method is not attempted on Abel
equations if the Abel method fails, but it is tried if the Riccati
method returns an unsolved second order ODE.

   For second order ODEs `contrib_ode' calls `ode2' then `odelin'.

   Extensive debugging traces and messages are displayed if the command
`put('contrib_ode,true,'verbose)' is executed.


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

44.2 Functions and Variables for contrib_ode
============================================

 -- Function: contrib_ode (<eqn>, <y>, <x>)
     Returns a list of solutions of the ODE <eqn> with independent
     variable <x> and dependent variable <y>.


 -- Function: odelin (<eqn>, <y>, <x>)
     `odelin' solves linear homogeneous ODEs of first and second order
     with independent variable <x> and dependent variable <y>.  It
     returns a fundamental solution set of the ODE.

     For second order ODEs, `odelin' uses a method, due to Bronstein
     and Lafaille, that searches for solutions in terms of given
     special functions.

          (%i1) load('contrib_ode);

          (%i2) odelin(x*(x+1)*'diff(y,x,2)+(x+5)*'diff(y,x,1)+(-4)*y,y,x);
          ...trying factor method
          ...solving 7 equations in 4 variables
          ...trying the Bessel solver
          ...solving 1 equations in 2 variables
          ...trying the F01 solver
          ...solving 1 equations in 3 variables
          ...trying the spherodial wave solver
          ...solving 1 equations in 4 variables
          ...trying the square root Bessel solver
          ...solving 1 equations in 2 variables
          ...trying the 2F1 solver
          ...solving 9 equations in 5 variables
                 gauss_a(- 6, - 2, - 3, - x)  gauss_b(- 6, - 2, - 3, - x)
          (%o2) {---------------------------, ---------------------------}
                              4                            4
                             x                            x


 -- Function: ode_check (<eqn>, <soln>)
     Returns the value of ODE <eqn> after substituting a possible
     solution <soln>.  The value is equivalent to zero if <soln> is a
     solution of <eqn>.

          (%i1) load('contrib_ode)$

          (%i2) eqn:'diff(y,x,2)+(a*x+b)*y;

                                   2
                                  d y
          (%o2)                   --- + (a x + b) y
                                    2
                                  dx
          (%i3) ans:[y = bessel_y(1/3,2*(a*x+b)^(3/2)/(3*a))*%k2*sqrt(a*x+b)
                   +bessel_j(1/3,2*(a*x+b)^(3/2)/(3*a))*%k1*sqrt(a*x+b)];

                                            3/2
                              1  2 (a x + b)
          (%o3) [y = bessel_y(-, --------------) %k2 sqrt(a x + b)
                              3       3 a
                                                    3/2
                                      1  2 (a x + b)
                           + bessel_j(-, --------------) %k1 sqrt(a x + b)]
                                      3       3 a
          (%i4) ode_check(eqn,ans[1]);

          (%o4)                           0


 -- System variable: method
     The variable `method' is set to the successful solution method.


 -- Variable: %c
     `%c' is the integration constant for first order ODEs.


 -- Variable: %k1
     `%k1' is the first integration constant for second order ODEs.


 -- Variable: %k2
     `%k2' is the second integration constant for second order ODEs.


 -- Function: gauss_a (<a>, <b>, <c>, <x>)
     `gauss_a(a,b,c,x)' and `gauss_b(a,b,c,x)' are 2F1 geometric
     functions.  They represent any two independent solutions of the
     hypergeometric differential equation `x(1-x) diff(y,x,2) +
     [c-(a+b+1)x diff(y,x) - aby = 0' (A&S 15.5.1).

     The only use of these functions is in solutions of ODEs returned by
     `odelin' and `contrib_ode'.  The definition and use of these
     functions may change in future releases of Maxima.

     See also `gauss_b', `dgauss_a' and `gauss_b'.


 -- Function: gauss_b (<a>, <b>, <c>, <x>)
     See `gauss_a'.


 -- Function: dgauss_a (<a>, <b>, <c>, <x>)
     The derivative with respect to <x> of `gauss_a(<a>, <b>, <c>,
     <x>)'.


 -- Function: dgauss_b (<a>, <b>, <c>, <x>)
     The derivative with respect to <x> of `gauss_b(<a>, <b>, <c>,
     <x>)'.


 -- Function: kummer_m (<a>, <b>, <x>)
     Kummer's M function, as defined in Abramowitz and Stegun, Handbook
     of Mathematical Functions, Section 13.1.2.

     The only use of this function is in solutions of ODEs returned by
     `odelin' and `contrib_ode'.  The definition and use of this
     function may change in future releases of Maxima.

     See also `kummer_u', `dkummer_m' and `dkummer_u'.


 -- Function: kummer_u (<a>, <b>, <x>)
     Kummer's U function, as defined in Abramowitz and Stegun, Handbook
     of Mathematical Functions, Section 13.1.3.

     See `kummer_m'.


 -- Function: dkummer_m (<a>, <b>, <x>)
     The derivative with respect to <x> of `kummer_m(<a>, <b>, <x>)'.


 -- Function: dkummer_u (<a>, <b>, <x>)
     The derivative with respect to <x> of `kummer_u(<a>, <b>, <x>)'.



File: maxima.info,  Node: Possible improvements to contrib_ode,  Next: Test cases for contrib_ode,  Prev: Functions and Variables for contrib_ode,  Up: contrib_ode

44.3 Possible improvements to contrib_ode
=========================================

These routines are work in progress.  I still need to:

   * Extend the FACTOR method `ode1_factor' to work for multiple roots.

   * Extend the FACTOR method `ode1_factor' to attempt to solve higher
     order factors.  At present it only attemps to solve linear
     factors.

   * Fix the LAGRANGE routine `ode1_lagrange' to prefer real roots over
      complex roots.

   * Add additional methods for Riccati equations.

   * Improve the detection of Abel equations of second kind.  The
     exisiting   pattern matching is weak.

   * Work on the Lie symmetry group routine `ode1_lie'.  There are
     quite a   few problems with it: some parts are unimplemented; some
     test cases   seem to run forever; other test cases crash; yet
     others return very   complex "solutions".  I wonder if it really
     ready for release yet.

   * Add more test cases.



File: maxima.info,  Node: Test cases for contrib_ode,  Next: References for contrib_ode,  Prev: Possible improvements to contrib_ode,  Up: contrib_ode

44.4 Test cases for contrib_ode
===============================

The routines have been tested on a approximately one thousand  test
cases from Murphy, Kamke, Zwillinger and elsewhere.  These are included
in the tests subdirectory.

   * The Clairault routine `ode1_clairault' finds all known solutions,
     including singular solutions, of the Clairault equations in
     Murphy and   Kamke.

   * The other routines often return a single solution when multiple
     solutions exist.

   * Some of the "solutions" from `ode1_lie' are overly complex and
     impossible to check.

   * There are some crashes.



File: maxima.info,  Node: References for contrib_ode,  Prev: Test cases for contrib_ode,  Up: contrib_ode

44.5 References for contrib_ode
===============================

  1. E. Kamke, Differentialgleichungen Losungsmethoden und Losungen,
     Vol 1,     Geest & Portig, Leipzig, 1961

  2. G. M. Murphy, Ordinary Differential Equations and Their Solutions,
        Van Nostrand, New York, 1960

  3. D. Zwillinger, Handbook of Differential Equations, 3rd edition,
     Academic Press, 1998

  4. F. Schwarz, Symmetry Analysis of Abel's Equation, Studies in
     Applied Mathematics, 100:269-294 (1998)

  5. F. Schwarz, Algorithmic Solution of Abel's Equation,     Computing
     61, 39-49 (1998)

  6. E. S. Cheb-Terrab, A. D. Roche, Symmetries and First Order     ODE
     Patterns, Computer Physics Communications 113 (1998), p 239.
     (`http://lie.uwaterloo.ca/papers/ode_vii.pdf')

  7. E. S. Cheb-Terrab, T. Koloknikov,  First Order ODEs,
     Symmetries and Linear Transformations, European Journal of
     Applied Mathematics, Vol. 14, No. 2, pp. 231-246 (2003).
     (`http://arxiv.org/abs/math-ph/0007023',
     `http://lie.uwaterloo.ca/papers/ode_iv.pdf')

  8. G. W. Bluman, S. C. Anco, Symmetry and Integration Methods for
     Differential Equations, Springer, (2002)

  9. M. Bronstein, S. Lafaille, Solutions of linear ordinary
     differential equations in terms of special functions, Proceedings
     of ISSAC 2002, Lille, ACM Press, 23-28.
     (`http://www-sop.inria.fr/cafe/Manuel.Bronstein/publications/issac2002.pdf')



File: maxima.info,  Node: descriptive,  Next: diag,  Prev: contrib_ode,  Up: Top

45 descriptive
**************

* Menu:

* Introduction to descriptive::
* Functions and Variables for data manipulation::
* Functions and Variables for descriptive statistics::
* Functions and Variables for specific multivariate descriptive statistics::
* Functions and Variables for statistical graphs::


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

45.1 Introduction to descriptive
================================

Package `descriptive' contains a set of functions for making
descriptive statistical computations and graphing.  Together with the
source code there are three data sets in your Maxima tree:
`pidigits.data', `wind.data' and `biomed.data'.

   Any statistics manual can be used as a reference to the functions in
package `descriptive'.

   For comments, bugs or suggestions, please contact me at <'mario AT
edu DOT xunta DOT es'>.

   Here is a simple example on how the descriptive functions in
`descriptive' do they work, depending on the nature of their arguments,
lists or matrices,

     (%i1) load (descriptive)$
     (%i2) /* univariate sample */   mean ([a, b, c]);
                                 c + b + a
     (%o2)                       ---------
                                     3
     (%i3) matrix ([a, b], [c, d], [e, f]);
                                 [ a  b ]
                                 [      ]
     (%o3)                       [ c  d ]
                                 [      ]
                                 [ e  f ]
     (%i4) /* multivariate sample */ mean (%);
                           e + c + a  f + d + b
     (%o4)                [---------, ---------]
                               3          3

   Note that in multivariate samples the mean is calculated for each
column.

   In case of several samples with possible different sizes, the Maxima
function `map' can be used to get the desired results for each sample,

     (%i1) load (descriptive)$
     (%i2) map (mean, [[a, b, c], [d, e]]);
                             c + b + a  e + d
     (%o2)                  [---------, -----]
                                 3        2

   In this case, two samples of sizes 3 and 2 were stored into a list.

   Univariate samples must be stored in lists like

     (%i1) s1 : [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5];
     (%o1)           [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5]

   and multivariate samples in matrices as in

     (%i1) s2 : matrix ([13.17, 9.29], [14.71, 16.88], [18.50, 16.88],
                  [10.58, 6.63], [13.33, 13.25], [13.21,  8.12]);
                             [ 13.17  9.29  ]
                             [              ]
                             [ 14.71  16.88 ]
                             [              ]
                             [ 18.5   16.88 ]
     (%o1)                   [              ]
                             [ 10.58  6.63  ]
                             [              ]
                             [ 13.33  13.25 ]
                             [              ]
                             [ 13.21  8.12  ]

   In this case, the number of columns equals the random variable
dimension and the number of rows is the sample size.

   Data can be introduced by hand, but big samples are usually stored
in plain text files. For example, file `pidigits.data' contains the
first 100 digits of number `%pi':
           3
           1
           4
           1
           5
           9
           2
           6
           5
           3 ...

   In order to load these digits in Maxima,

     (%i1) s1 : read_list (file_search ("pidigits.data"))$
     (%i2) length (s1);
     (%o2)                          100

   On the other hand, file `wind.data' contains daily average wind
speeds at 5 meteorological stations in the Republic of Ireland (This is
part of a data set taken at 12 meteorological stations. The original
file is freely downloadable from the StatLib Data Repository and its
analysis is discused in Haslett, J., Raftery, A. E. (1989) <Space-time
Modelling with Long-memory Dependence: Assessing Ireland's Wind Power
Resource, with Discussion>. Applied Statistics 38, 1-50). This loads
the data:

     (%i1) s2 : read_matrix (file_search ("wind.data"))$
     (%i2) length (s2);
     (%o2)                          100
     (%i3) s2 [%]; /* last record */
     (%o3)            [3.58, 6.0, 4.58, 7.62, 11.25]

   Some samples contain non numeric data. As an example, file
`biomed.data' (which is part of another bigger one downloaded from the
StatLib Data Repository) contains four blood measures taken from two
groups of patients, `A' and `B', of different ages,

     (%i1) s3 : read_matrix (file_search ("biomed.data"))$
     (%i2) length (s3);
     (%o2)                          100
     (%i3) s3 [1]; /* first record */
     (%o3)            [A, 30, 167.0, 89.0, 25.6, 364]

   The first individual belongs to group `A', is 30 years old and
his/her blood measures were 167.0, 89.0, 25.6 and 364.

   One must take care when working with categorical data. In the next
example, symbol `a' is asigned a value in some previous moment and then
a sample with categorical value `a' is taken,

     (%i1) a : 1$
     (%i2) matrix ([a, 3], [b, 5]);
                                 [ 1  3 ]
     (%o2)                       [      ]
                                 [ b  5 ]


File: maxima.info,  Node: Functions and Variables for data manipulation,  Next: Functions and Variables for descriptive statistics,  Prev: Introduction to descriptive,  Up: descriptive

45.2 Functions and Variables for data manipulation
==================================================

 -- Function: continuous_freq (<list>)
 -- Function: continuous_freq (<list>, <m>)
     The argument of `continuous_freq' must be a list of numbers, which
     will be then grouped in intervals and counted how many of them
     belong to each group. Optionally, function `continuous_freq'
     admits a second argument indicating the number of classes, 10 is
     default,

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) continuous_freq (s1, 5);
          (%o3) [[0, 1.8, 3.6, 5.4, 7.2, 9.0], [16, 24, 18, 17, 25]]

     The first list contains the interval limits and the second the
     corresponding counts: there are 16 digits inside the interval `[0,
     1.8]', that is 0's and 1's, 24 digits in `(1.8, 3.6]', that is 2's
     and 3's, and so on.


 -- Function: discrete_freq (<list>)
     Counts absolute frequencies in discrete samples, both numeric and
     categorical. Its unique argument is a list,

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) discrete_freq (s1);
          (%o3) [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
                                       [8, 8, 12, 12, 10, 8, 9, 8, 12, 13]]

     The first list gives the sample values and the second their
     absolute frequencies. Commands `? col' and `? transpose' should
     help you to understand the last input.


 -- Function: subsample (<data_matrix>, <predicate_function>)
 -- Function: subsample (<data_matrix>, <predicate_function>,
          <col_num1>, <col_num2>, ...)
     This is a sort of variant of the Maxima `submatrix' function.  The
     first argument is the data matrix, the second is a predicate
     function and optional additional arguments are the numbers of the
     columns to be taken.  Its behaviour is better understood with
     examples.

     These are multivariate records in which the wind speed in the
     first meteorological station were greater than 18.  See that in
     the lambda expression the <i>-th component is refered to as `v[i]'.
          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) subsample (s2, lambda([v], v[1] > 18));
                        [ 19.38  15.37  15.12  23.09  25.25 ]
                        [                                   ]
                        [ 18.29  18.66  19.08  26.08  27.63 ]
          (%o3)         [                                   ]
                        [ 20.25  21.46  19.95  27.71  23.38 ]
                        [                                   ]
                        [ 18.79  18.96  14.46  26.38  21.84 ]

     In the following example, we request only the first, second and
     fifth components of those records with wind speeds greater or
     equal than 16 in station number 1 and less than 25 knots in
     station number 4. The sample contains only data from stations 1, 2
     and 5. In this case, the predicate function is defined as an
     ordinary Maxima function.
          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) g(x):= x[1] >= 16 and x[4] < 25$
          (%i4) subsample (s2, g, 1, 2, 5);
                               [ 19.38  15.37  25.25 ]
                               [                     ]
                               [ 17.33  14.67  19.58 ]
          (%o4)                [                     ]
                               [ 16.92  13.21  21.21 ]
                               [                     ]
                               [ 17.25  18.46  23.87 ]

     Here is an example with the categorical variables of `biomed.data'.
     We want the records corresponding to those patients in group `B'
     who are older than 38 years.
          (%i1) load (descriptive)$
          (%i2) s3 : read_matrix (file_search ("biomed.data"))$
          (%i3) h(u):= u[1] = B and u[2] > 38 $
          (%i4) subsample (s3, h);
                          [ B  39  28.0  102.3  17.1  146 ]
                          [                               ]
                          [ B  39  21.0  92.4   10.3  197 ]
                          [                               ]
                          [ B  39  23.0  111.5  10.0  133 ]
                          [                               ]
                          [ B  39  26.0  92.6   12.3  196 ]
          (%o4)           [                               ]
                          [ B  39  25.0  98.7   10.0  174 ]
                          [                               ]
                          [ B  39  21.0  93.2   5.9   181 ]
                          [                               ]
                          [ B  39  18.0  95.0   11.3  66  ]
                          [                               ]
                          [ B  39  39.0  88.5   7.6   168 ]

     Probably, the statistical analysis will involve only the blood
     measures,
          (%i1) load (descriptive)$
          (%i2) s3 : read_matrix (file_search ("biomed.data"))$
          (%i3) subsample (s3, lambda([v], v[1] = B and v[2] > 38),
                           3, 4, 5, 6);
                             [ 28.0  102.3  17.1  146 ]
                             [                        ]
                             [ 21.0  92.4   10.3  197 ]
                             [                        ]
                             [ 23.0  111.5  10.0  133 ]
                             [                        ]
                             [ 26.0  92.6   12.3  196 ]
          (%o3)              [                        ]
                             [ 25.0  98.7   10.0  174 ]
                             [                        ]
                             [ 21.0  93.2   5.9   181 ]
                             [                        ]
                             [ 18.0  95.0   11.3  66  ]
                             [                        ]
                             [ 39.0  88.5   7.6   168 ]

     This is the multivariate mean of `s3',
          (%i1) load (descriptive)$
          (%i2) s3 : read_matrix (file_search ("biomed.data"))$
          (%i3) mean (s3);
                 65 B + 35 A  317          6 NA + 8145.0
          (%o3) [-----------, ---, 87.178, -------------, 18.123,
                     100      10                100
                                                              3 NA + 19587
                                                              ------------]
                                                                  100

     Here, the first component is meaningless, since `A' and `B' are
     categorical, the second component is the mean age of individuals
     in rational form, and the fourth and last values exhibit some
     strange behaviour. This is because symbol `NA' is used here to
     indicate <non available> data, and the two means are nonsense. A
     possible solution would be to take out from the matrix those rows
     with `NA' symbols, although this deserves some loss of information.
          (%i1) load (descriptive)$
          (%i2) s3 : read_matrix (file_search ("biomed.data"))$
          (%i3) g(v):= v[4] # NA and v[6] # NA $
          (%i4) mean(subsample(s3, g, 3,4,5,6));
          (%o4) [79.4923076923077, 86.2032967032967, 16.93186813186813,
                                                                      2514
                                                                      ----]
                                                                       13



File: maxima.info,  Node: Functions and Variables for descriptive statistics,  Next: Functions and Variables for specific multivariate descriptive statistics,  Prev: Functions and Variables for data manipulation,  Up: descriptive

45.3 Functions and Variables for descriptive statistics
=======================================================

 -- Function: mean (<list>)
 -- Function: mean (<matrix>)
     This is the sample mean, defined as
                                 n
                               ====
                       _   1   \
                       x = -    >    x
                           n   /      i
                               ====
                               i = 1

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) mean (s1);
                                         471
          (%o3)                          ---
                                         100
          (%i4) %, numer;
          (%o4)                         4.71
          (%i5) s2 : read_matrix (file_search ("wind.data"))$
          (%i6) mean (s2);
          (%o6)     [9.9485, 10.1607, 10.8685, 15.7166, 14.8441]


 -- Function: var (<list>)
 -- Function: var (<matrix>)
     This is the sample variance, defined as
                               n
                             ====
                     2   1   \          _ 2
                    s  = -    >    (x - x)
                         n   /       i
                             ====
                             i = 1

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) var (s1), numer;
          (%o3)                   8.425899999999999

     See also function `var1'.


 -- Function: var1 (<list>)
 -- Function: var1 (<matrix>)
     This is the sample variance, defined as
                               n
                             ====
                         1   \          _ 2
                        ---   >    (x - x)
                        n-1  /       i
                             ====
                             i = 1

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) var1 (s1), numer;
          (%o3)                    8.5110101010101
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) var1 (s2);
          (%o5) [17.39586540404041, 15.13912778787879, 15.63204924242424,
                                      32.50152569696971, 24.66977392929294]

     See also function `var'.


 -- Function: std (<list>)
 -- Function: std (<matrix>)
     This is the the square root of function `var', the variance with
     denominator n.

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) std (s1), numer;
          (%o3)                   2.902740084816414
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) std (s2);
          (%o5) [4.149928523480858, 3.871399812729241, 3.933920277534866,
                                      5.672434260526957, 4.941970881136392]

     See also functions `var' and `std1'.


 -- Function: std1 (<list>)
 -- Function: std1 (<matrix>)
     This is the the square root of function `var1', the variance with
     denominator n-1.

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) std1 (s1), numer;
          (%o3)                   2.917363553109228
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) std1 (s2);
          (%o5) [4.17083509672109, 3.89090320978032, 3.953738641137555,
                                      5.701010936401517, 4.966867617451963]

     See also functions `var1' and `std'.


 -- Function: noncentral_moment (<list>, <k>)
 -- Function: noncentral_moment (<matrix>, <k>)
     The non central moment of order k, defined as
                                 n
                               ====
                           1   \      k
                           -    >    x
                           n   /      i
                               ====
                               i = 1

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) noncentral_moment (s1, 1), numer; /* the mean */
          (%o3)                         4.71
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) noncentral_moment (s2, 5);
          (%o5) [319793.8724761506, 320532.1923892463, 391249.5621381556,
                                      2502278.205988911, 1691881.797742255]

     See also function `central_moment'.


 -- Function: central_moment (<list>, <k>)
 -- Function: central_moment (<matrix>, <k>)
     The central moment of order k, defined as
                              n
                            ====
                        1   \          _ k
                        -    >    (x - x)
                        n   /       i
                            ====
                            i = 1

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) central_moment (s1, 2), numer; /* the variance */
          (%o3)                   8.425899999999999
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) central_moment (s2, 3);
          (%o5) [11.29584771375004, 16.97988248298583, 5.626661952750102,
                                       37.5986572057918, 25.85981904394192]

     See also functions `central_moment' and `mean'.


 -- Function: cv (<list>)
 -- Function: cv (<matrix>)
     The variation coefficient is the quotient between the sample
     standard deviation (`std') and the `mean',

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) cv (s1), numer;
          (%o3)                   .6193977819764815
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) cv (s2);
          (%o5) [.4192426091090204, .3829365309260502, 0.363779605385983,
                                      .3627381836021478, .3346021393989506]

     See also functions `std' and `mean'.


 -- Function: mini (<list>)
 -- Function: mini (<matrix>)
     This is the minimum value of the sample <list>,

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) mini (s1);
          (%o3)                           0
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) mini (s2);
          (%o5)             [0.58, 0.5, 2.67, 5.25, 5.17]

     See also function `maxi'.


 -- Function: maxi (<list>)
 -- Function: maxi (<matrix>)
     This is the maximum value of the sample <list>,

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) maxi (s1);
          (%o3)                           9
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) maxi (s2);
          (%o5)          [20.25, 21.46, 20.04, 29.63, 27.63]

     See also function `mini'.


 -- Function: range (<list>)
 -- Function: range (<matrix>)
     The range is the difference between the extreme values.

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) range (s1);
          (%o3)                           9
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) range (s2);
          (%o5)          [19.67, 20.96, 17.37, 24.38, 22.46]


 -- Function: quantile (<list>, <p>)
 -- Function: quantile (<matrix>, <p>)
     This is the <p>-quantile, with <p> a number in [0, 1], of the
     sample <list>.  Although there are several definitions for the
     sample quantile (Hyndman, R. J., Fan, Y. (1996) <Sample quantiles
     in statistical packages>. American Statistician, 50, 361-365), the
     one based on linear interpolation is implemented in package
     `descriptive'.

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) /* 1st and 3rd quartiles */
                   [quantile (s1, 1/4), quantile (s1, 3/4)], numer;
          (%o3)                      [2.0, 7.25]
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) quantile (s2, 1/4);
          (%o5)    [7.2575, 7.477500000000001, 7.82, 11.28, 11.48]


 -- Function: median (<list>)
 -- Function: median (<matrix>)
     Once the sample is ordered, if the sample size is odd the median
     is the central value, otherwise it is the mean of the two central
     values.

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) median (s1);
                                          9
          (%o3)                           -
                                          2
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) median (s2);
          (%o5)         [10.06, 9.855, 10.73, 15.48, 14.105]

     The median is the 1/2-quantile.

     See also function `quantile'.


 -- Function: qrange (<list>)
 -- Function: qrange (<matrix>)
     The interquartilic range is the difference between the third and
     first quartiles, `quantile(<list>,3/4) - quantile(<list>,1/4)',

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) qrange (s1);
                                         21
          (%o3)                          --
                                         4
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) qrange (s2);
          (%o5) [5.385, 5.572499999999998, 6.0225, 8.729999999999999,
                                                         6.650000000000002]

     See also function `quantile'.


 -- Function: mean_deviation (<list>)
 -- Function: mean_deviation (<matrix>)
     The mean deviation, defined as
                               n
                             ====
                         1   \          _
                         -    >    |x - x|
                         n   /       i
                             ====
                             i = 1

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) mean_deviation (s1);
                                         51
          (%o3)                          --
                                         20
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) mean_deviation (s2);
          (%o5) [3.287959999999999, 3.075342, 3.23907, 4.715664000000001,
                                                         4.028546000000002]

     See also function `mean'.


 -- Function: median_deviation (<list>)
 -- Function: median_deviation (<matrix>)
     The median deviation, defined as
                           n
                         ====
                     1   \
                     -    >    |x - med|
                     n   /       i
                         ====
                         i = 1
     where `med' is the median of <list>.

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) median_deviation (s1);
                                          5
          (%o3)                           -
                                          2
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) median_deviation (s2);
          (%o5)           [2.75, 2.755, 3.08, 4.315, 3.31]

     See also function `mean'.


 -- Function: harmonic_mean (<list>)
 -- Function: harmonic_mean (<matrix>)
     The harmonic mean, defined as
                            n
                         --------
                          n
                         ====
                         \     1
                          >    --
                         /     x
                         ====   i
                         i = 1

     Example:

          (%i1) load (descriptive)$
          (%i2) y : [5, 7, 2, 5, 9, 5, 6, 4, 9, 2, 4, 2, 5]$
          (%i3) harmonic_mean (y), numer;
          (%o3)                   3.901858027632205
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) harmonic_mean (s2);
          (%o5) [6.948015590052786, 7.391967752360356, 9.055658197151745,
                                      13.44199028193692, 13.01439145898509]

     See also functions `mean' and `geometric_mean'.


 -- Function: geometric_mean (<list>)
 -- Function: geometric_mean (<matrix>)
     The geometric mean, defined as
                           /  n      \ 1/n
                           | /===\   |
                           |  ! !    |
                           |  ! !  x |
                           |  ! !   i|
                           | i = 1   |
                           \         /

     Example:

          (%i1) load (descriptive)$
          (%i2) y : [5, 7, 2, 5, 9, 5, 6, 4, 9, 2, 4, 2, 5]$
          (%i3) geometric_mean (y), numer;
          (%o3)                   4.454845412337012
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) geometric_mean (s2);
          (%o5) [8.82476274347979, 9.22652604739361, 10.0442675714889,
                                      14.61274126349021, 13.96184163444275]

     See also functions `mean' and `harmonic_mean'.


 -- Function: kurtosis (<list>)
 -- Function: kurtosis (<matrix>)
     The kurtosis coefficient, defined as
                              n
                            ====
                      1     \          _ 4
                     ----    >    (x - x)  - 3
                        4   /       i
                     n s    ====
                            i = 1

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) kurtosis (s1), numer;
          (%o3)                  - 1.273247946514421
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) kurtosis (s2);
          (%o5) [- .2715445622195385, 0.119998784429451,
             - .4275233490482866, - .6405361979019522, - .4952382132352935]

     See also functions `mean', `var' and `skewness'.


 -- Function: skewness (<list>)
 -- Function: skewness (<matrix>)
     The skewness coefficient, defined as
                              n
                            ====
                      1     \          _ 3
                     ----    >    (x - x)
                        3   /       i
                     n s    ====
                            i = 1

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) skewness (s1), numer;
          (%o3)                  .009196180476450306
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) skewness (s2);
          (%o5) [.1580509020000979, .2926379232061854, .09242174416107717,
                                      .2059984348148687, .2142520248890832]

     See also functions `mean', `var' and `kurtosis'.


 -- Function: pearson_skewness (<list>)
 -- Function: pearson_skewness (<matrix>)
     Pearson's skewness coefficient, defined as
                          _
                       3 (x - med)
                       -----------
                            s
     where <med> is the median of <list>.

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) pearson_skewness (s1), numer;
          (%o3)                   .2159484029093895
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) pearson_skewness (s2);
          (%o5) [- .08019976629211892, .2357036272952649,
                   .1050904062491204, .1245042340592368, .4464181795804519]

     See also functions `mean', `var' and `median'.


 -- Function: quartile_skewness (<list>)
 -- Function: quartile_skewness (<matrix>)
     The quartile skewness coefficient, defined as
                         c    - 2 c    + c
                          3/4      1/2    1/4
                         --------------------
                             c    - c
                              3/4    1/4
     where c_p is the <p>-quantile of sample <list>.

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) quartile_skewness (s1), numer;
          (%o3)                  .04761904761904762
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) quartile_skewness (s2);
          (%o5) [- 0.0408542246982353, .1467025572005382,
                 0.0336239103362392, .03780068728522298, 0.210526315789474]

     See also function `quantile'.



File: maxima.info,  Node: Functions and Variables for specific multivariate descriptive statistics,  Next: Functions and Variables for statistical graphs,  Prev: Functions and Variables for descriptive statistics,  Up: descriptive

45.4 Functions and Variables for specific multivariate descriptive statistics
=============================================================================

 -- Function: cov (<matrix>)
     The covariance matrix of the multivariate sample, defined as
                        n
                       ====
                    1  \           _        _
                S = -   >    (X  - X) (X  - X)'
                    n  /       j        j
                       ====
                       j = 1
     where X_j is the j-th row of the sample matrix.

     Example:

          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) fpprintprec : 7$  /* change precision for pretty output */
          (%i4) cov (s2);
                [ 17.22191  13.61811  14.37217  19.39624  15.42162 ]
                [                                                  ]
                [ 13.61811  14.98774  13.30448  15.15834  14.9711  ]
                [                                                  ]
          (%o4) [ 14.37217  13.30448  15.47573  17.32544  16.18171 ]
                [                                                  ]
                [ 19.39624  15.15834  17.32544  32.17651  20.44685 ]
                [                                                  ]
                [ 15.42162  14.9711   16.18171  20.44685  24.42308 ]

     See also function `cov1'.


 -- Function: cov1 (<matrix>)
     The covariance matrix of the multivariate sample, defined as
                        n
                       ====
                   1   \           _        _
             S  = ---   >    (X  - X) (X  - X)'
              1   n-1  /       j        j
                       ====
                       j = 1
     where X_j is the j-th row of the sample matrix.

     Example:

          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) fpprintprec : 7$ /* change precision for pretty output */
          (%i4) cov1 (s2);
                [ 17.39587  13.75567  14.51734  19.59216  15.5774  ]
                [                                                  ]
                [ 13.75567  15.13913  13.43887  15.31145  15.12232 ]
                [                                                  ]
          (%o4) [ 14.51734  13.43887  15.63205  17.50044  16.34516 ]
                [                                                  ]
                [ 19.59216  15.31145  17.50044  32.50153  20.65338 ]
                [                                                  ]
                [ 15.5774   15.12232  16.34516  20.65338  24.66977 ]

     See also function `cov'.


 -- Function: global_variances (<matrix>)
 -- Function: global_variances (<matrix>, <logical_value>)
     Function `global_variances' returns a list of global variance
     measures:

        * <total variance>: `trace(S_1)',

        * <mean variance>: `trace(S_1)/p',

        * <generalized variance>: `determinant(S_1)',

        * <generalized standard deviation>: `sqrt(determinant(S_1))',

        * <efective variance> `determinant(S_1)^(1/p)', (defined in:
          Pen~a, D. (2002) <Ana'lisis de datos multivariantes>;
          McGraw-Hill, Madrid.)

        * <efective standard deviation>: `determinant(S_1)^(1/(2*p))'.
     where <p> is the dimension of the multivariate random variable and
     S_1 the covariance matrix returned by `cov1'.

     Example:

          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) global_variances (s2);
          (%o3) [105.338342060606, 21.06766841212119, 12874.34690469686,
                   113.4651792608502, 6.636590811800794, 2.576158149609762]

     Function `global_variances' has an optional logical argument:
     `global_variances(x,true)' tells Maxima that `x' is the data
     matrix, making the same as `global_variances(x)'. On the other
     hand, `global_variances(x,false)' means that `x' is not the data
     matrix, but the covariance matrix, avoiding its recalculation,

          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) s : cov1 (s2)$
          (%i4) global_variances (s, false);
          (%o4) [105.338342060606, 21.06766841212119, 12874.34690469686,
                   113.4651792608502, 6.636590811800794, 2.576158149609762]

     See also `cov' and `cov1'.


 -- Function: cor (<matrix>)
 -- Function: cor (<matrix>, <logical_value>)
     The correlation matrix of the multivariate sample.

     Example:

          (%i1) load (descriptive)$
          (%i2) fpprintprec:7$
          (%i3) s2 : read_matrix (file_search ("wind.data"))$
          (%i4) cor (s2);
                [   1.0     .8476339  .8803515  .8239624  .7519506 ]
                [                                                  ]
                [ .8476339    1.0     .8735834  .6902622  0.782502 ]
                [                                                  ]
          (%o4) [ .8803515  .8735834    1.0     .7764065  .8323358 ]
                [                                                  ]
                [ .8239624  .6902622  .7764065    1.0     .7293848 ]
                [                                                  ]
                [ .7519506  0.782502  .8323358  .7293848    1.0    ]

     Function `cor' has an optional logical argument: `cor(x,true)'
     tells Maxima that `x' is the data matrix, making the same as
     `cor(x)'. On the other hand, `cor(x,false)' means that `x' is not
     the data matrix, but the covariance matrix, avoiding its
     recalculation,

          (%i1) load (descriptive)$
          (%i2) fpprintprec:7$
          (%i3) s2 : read_matrix (file_search ("wind.data"))$
          (%i4) s : cov1 (s2)$
          (%i5) cor (s, false); /* this is faster */
                [   1.0     .8476339  .8803515  .8239624  .7519506 ]
                [                                                  ]
                [ .8476339    1.0     .8735834  .6902622  0.782502 ]
                [                                                  ]
          (%o5) [ .8803515  .8735834    1.0     .7764065  .8323358 ]
                [                                                  ]
                [ .8239624  .6902622  .7764065    1.0     .7293848 ]
                [                                                  ]
                [ .7519506  0.782502  .8323358  .7293848    1.0    ]

     See also `cov' and `cov1'.


 -- Function: list_correlations (<matrix>)
 -- Function: list_correlations (<matrix>, <logical_value>)
     Function `list_correlations' returns a list of correlation
     measures:

        * <precision matrix>: the inverse of the covariance matrix S_1,
                      -1     ij
                     S   = (s  )
                      1         i,j = 1,2,...,p

        * <multiple correlation vector>:  (R_1^2, R_2^2, ..., R_p^2),
          with
                      2          1
                     R  = 1 - -------
                      i        ii
                              s   s
                                   ii
          being an indicator of the goodness of fit of the linear
          multivariate regression model on X_i when the rest of
          variables are used as regressors.

        * <partial correlation matrix>: with element (i, j) being
                                        ij
                                       s
                     r        = - ------------
                      ij.rest     / ii  jj\ 1/2
                                  |s   s  |
                                  \       /


     Example:

          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) z : list_correlations (s2)$
          (%i4) fpprintprec : 5$ /* for pretty output */
          (%i5) z[1];  /* precision matrix */
                [  .38486   - .13856   - .15626   - .10239    .031179  ]
                [                                                      ]
                [ - .13856   .34107    - .15233    .038447   - .052842 ]
                [                                                      ]
          (%o5) [ - .15626  - .15233    .47296    - .024816  - .10054  ]
                [                                                      ]
                [ - .10239   .038447   - .024816   .10937    - .034033 ]
                [                                                      ]
                [ .031179   - .052842  - .10054   - .034033   .14834   ]
          (%i6) z[2];  /* multiple correlation vector */
          (%o6)       [.85063, .80634, .86474, .71867, .72675]
          (%i7) z[3];  /* partial correlation matrix */
                 [  - 1.0     .38244   .36627   .49908   - .13049 ]
                 [                                                ]
                 [  .38244    - 1.0    .37927  - .19907   .23492  ]
                 [                                                ]
          (%o7)  [  .36627    .37927   - 1.0    .10911    .37956  ]
                 [                                                ]
                 [  .49908   - .19907  .10911   - 1.0     .26719  ]
                 [                                                ]
                 [ - .13049   .23492   .37956   .26719    - 1.0   ]

     Function `list_correlations' also has an optional logical
     argument: `list_correlations(x,true)' tells Maxima that `x' is the
     data matrix, making the same as `list_correlations(x)'. On the
     other hand, `list_correlations(x,false)' means that `x' is not the
     data matrix, but the covariance matrix, avoiding its recalculation.

     See also `cov' and `cov1'.



File: maxima.info,  Node: Functions and Variables for statistical graphs,  Prev: Functions and Variables for specific multivariate descriptive statistics,  Up: descriptive

45.5 Functions and Variables for statistical graphs
===================================================

 -- Function: histogram (<list>)
 -- Function: histogram (<list>, <option_1>, <option_2>, ...)
 -- Function: histogram (<one_column_matrix>)
 -- Function: histogram (<one_column_matrix>, <option_1>, <option_2>,
          ...)
 -- Function: histogram (<one_row_matrix>)
 -- Function: histogram (<one_row_matrix>, <option_1>, <option_2>, ...)
     This function plots an histogram from a continuous sample.  Sample
     data must be stored in a list of numbers or a one dimensional
     matrix.

     Available options are:

        * Those defined in the `draw' package. See also `bars' and
          `barsplot'.

        * <nclasses>: number of classes of the histogram (10 by
          default).

     See also `discrete_freq' and `continuous_freq' to count data, and
     `bars' and `barsplot' to display bar graphs.

     Examples:

     A simple histogram with eight classes.

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) histogram (
                  s1,
                  nclasses     = 8,
                  title        = "pi digits",
                  xlabel       = "digits",
                  ylabel       = "Absolute frequency",
                  fill_color   = grey,
                  fill_density = 0.6)$


 -- Function: scatterplot (<list>)
 -- Function: scatterplot (<list>, <option_1>, <option_2>, ...)
 -- Function: scatterplot (<matrix>)
 -- Function: scatterplot (<matrix>, <option_1>, <option_2>, ...)
     Plots scatter diagrams both for univariate (<list>) and
     multivariate (<matrix>) samples.

     Available options are:

        * Those defined in the `draw' package.

        * <nclasses>: number of classes of the histogram (10 by
          default).

     Examples:

     Univariate scatter diagram from a simulated Gaussian sample.

          (%i1) load (descriptive)$
          (%i2) load (distrib)$
          (%i3) scatterplot(
                  random_normal(0,1,200),
                  xaxis      = true,
                  point_size = 2,
                  terminal   = eps,
                  eps_width  = 10,
                  eps_height = 2)$

     Two dimensional scatter plot.

          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) scatterplot(
                  submatrix(s2, 1,2,3),
                  title      = "Data from stations #4 and #5",
                  point_type = diamant,
                  point_size = 2,
                  color      = blue)$

     Three dimensional scatter plot.

          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) scatterplot(submatrix (s2, 1,2))$

     Five dimensional scatter plot, with five classes histograms.

          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix (file_search ("wind.data"))$
          (%i3) scatterplot(
                  s2,
                  nclasses     = 5,
                  fill_color   = blue,
                  fill_density = 0.3,
                  xtics        = 5)$

     For plotting isolated or line-joined points in two and three
     dimensions, see `points'. For histogram related options, see
     `bars'.

     See also `histogram'.


 -- Function: barsplot (<list>)
 -- Function: barsplot (<list>, <option_1>, <option_2>, ...)
 -- Function: barsplot (<one_column_matrix>)
 -- Function: barsplot (<one_column_matrix>, <option_1>, <option_2>,
          ...)
 -- Function: barsplot (<one_row_matrix>)
 -- Function: barsplot (<one_row_matrix>, <option_1>, <option_2>, ...)
     Similar to `histogram' but for discrete, numeric or categorical,
     statistical variables.

     Available options are:

        * Those defined in the `draw' package.

        * <box_width>: relative width of rectangles (`3/4' by default).
          This value must be in the range `[0,1]'.

     Example:

          (%i1) load (descriptive)$
          (%i2) s3 : read_matrix (file_search ("biomed.data"))$
          (%i3) barsplot(col(s3,2),
                   title        = "Ages",
                   xlabel       = "years",
                   box_width    = 1/2,
                   fill_density = 0.3)$

     For bars diagrams related options, see `bars' of package `draw'.
     See also functions `histogram' and `piechart'.


 -- Function: piechart (<list>)
 -- Function: piechart (<list>, <option_1>, <option_2>, ...)
 -- Function: piechart (<one_column_matrix>)
 -- Function: piechart (<one_column_matrix>, <option_1>, <option_2>,
          ...)
 -- Function: piechart (<one_row_matrix>)
 -- Function: piechart (<one_row_matrix>, <option_1>, <option_2>, ...)
     Similar to `barsplot', but plots sectors instead of rectangles.

     Available options are:

        * Those defined in the `draw' package.

        * <pie_center>: diagram's center (`[0,0]' by default).

        * <pie_radius>: diagram's radius (1 by default).

     Example:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) piechart(
                  s1,
                  xrange      = [-1.1, 1.3],
                  yrange      = [-1.1, 1.1],
                  axis_top    = false,
                  axis_right  = false,
                  axis_left   = false,
                  axis_bottom = false,
                  xtics       = none,
                  ytics       = none,
                  title       = "Digit frequencies in pi")$

     See also function `barsplot'.


 -- Function: boxplot (<data>)
 -- Function: boxplot (<data>, <option_1>, <option_2>, ...)
     This function plots box-and-whishker diagrams. Argument <data> can
     be a list, which is not of great interest, since these diagrams
     are mainly used for comparing different samples, or a matrix, so
     it is possible to compare two or more components of a multivariate
     statistical variable.  But it is also allowed <data> to be a list
     of samples with possible different sample sizes, in fact this is
     the only function in package `descriptive' that admits this type
     of data structure.

     Available options are:

        * Those defined in the `draw' package.

        * <box_width>: relative width of boxes (`3/4' by default). This
          value must be in the range `[0,1]'.

     Examples:

     Box-and-whishker diagram from a multivariate sample.

          (%i1) load (descriptive)$
          (%i2) s2 : read_matrix(file_search("wind.data"))$
          (%i3) boxplot(s2,
                  box_width  = 0.2,
                  title      = "Windspeed in knots",
                  xlabel     = "Stations",
                  color      = red,
                  line_width = 2) $

     Box-and-whishker diagram from three samples of different sizes.

          (%i1) load (descriptive)$
          (%i2) A :
                 [[6, 4, 6, 2, 4, 8, 6, 4, 6, 4, 3, 2],
                  [8, 10, 7, 9, 12, 8, 10],
                  [16, 13, 17, 12, 11, 18, 13, 18, 14, 12]]$
          (%i3) boxplot (A)$



File: maxima.info,  Node: diag,  Next: distrib,  Prev: descriptive,  Up: Top

46 diag
*******

* Menu:

* Functions and Variables for diag::


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

46.1 Functions and Variables for diag
=====================================

 -- Function: diag (<lm>)
     Constructs a square matrix with the matrices of <lm> in the
     diagonal. <lm> is a list of matrices or scalars.

     Example:
          (%i1) load("diag")$

          (%i2) a1:matrix([1,2,3],[0,4,5],[0,0,6])$

          (%i3) a2:matrix([1,1],[1,0])$

          (%i4) diag([a1,x,a2]);
                             [ 1  2  3  0  0  0 ]
                             [                  ]
                             [ 0  4  5  0  0  0 ]
                             [                  ]
                             [ 0  0  6  0  0  0 ]
          (%o4)              [                  ]
                             [ 0  0  0  x  0  0 ]
                             [                  ]
                             [ 0  0  0  0  1  1 ]
                             [                  ]
                             [ 0  0  0  0  1  0 ]

     To use this function write first `load("diag")'.


 -- Function: JF (<lambda>,<n>)
     Returns the Jordan cell of order <n> with eigenvalue <lambda>.

     Example:
          (%i1) load("diag")$

          (%i2) JF(2,5);
                              [ 2  1  0  0  0 ]
                              [               ]
                              [ 0  2  1  0  0 ]
                              [               ]
          (%o2)               [ 0  0  2  1  0 ]
                              [               ]
                              [ 0  0  0  2  1 ]
                              [               ]
                              [ 0  0  0  0  2 ]
          (%i3) JF(3,2);
                                   [ 3  1 ]
          (%o3)                    [      ]
                                   [ 0  3 ]

     To use this function write first `load("diag")'.


 -- Function: jordan (<mat>)
     Returns the Jordan form of matrix <mat>, but codified in a Maxima
     list.  To get the corresponding matrix, call function `dispJordan'
     using as argument the output of `jornan'.

     Example:
          (%i1) load("diag")$

          (%i3) a:matrix([2,0,0,0,0,0,0,0],
                         [1,2,0,0,0,0,0,0],
                         [-4,1,2,0,0,0,0,0],
                         [2,0,0,2,0,0,0,0],
                         [-7,2,0,0,2,0,0,0],
                         [9,0,-2,0,1,2,0,0],
                         [-34,7,1,-2,-1,1,2,0],
                         [145,-17,-16,3,9,-2,0,3])$

          (%i34) jordan(a);
          (%o4)             [[2, 3, 3, 1], [3, 1]]
          (%i5) dispJordan(%);
                          [ 2  1  0  0  0  0  0  0 ]
                          [                        ]
                          [ 0  2  1  0  0  0  0  0 ]
                          [                        ]
                          [ 0  0  2  0  0  0  0  0 ]
                          [                        ]
                          [ 0  0  0  2  1  0  0  0 ]
          (%o5)           [                        ]
                          [ 0  0  0  0  2  1  0  0 ]
                          [                        ]
                          [ 0  0  0  0  0  2  0  0 ]
                          [                        ]
                          [ 0  0  0  0  0  0  2  0 ]
                          [                        ]
                          [ 0  0  0  0  0  0  0  3 ]

     To use this function write first `load("diag")'. See also
     `dispJordan' and `minimalPoly'.


 -- Function: dispJordan (<l>)
     Returns the Jordan matrix associated to the codification given by
     the Maxima list <l>, which is the output given by function
     `jordan'.

     Example:
          (%i1) load("diag")$

          (%i2) b1:matrix([0,0,1,1,1],
                          [0,0,0,1,1],
                          [0,0,0,0,1],
                          [0,0,0,0,0],
                          [0,0,0,0,0])$

          (%i3) jordan(b1);
          (%o3)                  [[0, 3, 2]]
          (%i4) dispJordan(%);
                              [ 0  1  0  0  0 ]
                              [               ]
                              [ 0  0  1  0  0 ]
                              [               ]
          (%o4)               [ 0  0  0  0  0 ]
                              [               ]
                              [ 0  0  0  0  1 ]
                              [               ]
                              [ 0  0  0  0  0 ]

     To use this function write first `load("diag")'. See also `jordan'
     and `minimalPoly'.


 -- Function: minimalPoly (<l>)
     Returns the minimal polynomial associated to the codification
     given by the Maxima list <l>, which is the output given by
     function `jordan'.

     Example:
          (%i1) load("diag")$

          (%i2) a:matrix([2,1,2,0],
                         [-2,2,1,2],
                         [-2,-1,-1,1],
                         [3,1,2,-1])$

          (%i3) jordan(a);
          (%o3)               [[- 1, 1], [1, 3]]
          (%i4) minimalPoly(%);
                                      3
          (%o4)                (x - 1)  (x + 1)

     To use this function write first `load("diag")'. See also `jordan'
     and `dispJordan'.


 -- Function: ModeMatrix (<A>,<l>)
     Returns the matrix <M> such that (M^^-1).A.M=J, where <J> is the
     Jordan form of <A>. The Maxima list <l> is the codified form of
     the Jordan form as returned by function `jordan'.

     Example:
          (%i1) load("diag")$

          (%i2) a:matrix([2,1,2,0],
                    [-2,2,1,2],
                    [-2,-1,-1,1],
                    [3,1,2,-1])$

          (%i3) jordan(a);
          (%o3)               [[- 1, 1], [1, 3]]
          (%i4) M: ModeMatrix(a,%);
                            [  1    - 1   1   1 ]
                            [                   ]
                            [   1               ]
                            [ - -   - 1   0   0 ]
                            [   9               ]
                            [                   ]
          (%o4)             [   13              ]
                            [ - --   1   - 1  0 ]
                            [   9               ]
                            [                   ]
                            [  17               ]
                            [  --   - 1   1   1 ]
                            [  9                ]
          (%i5) is(  (M^^-1).a.M = dispJordan(%o3)  );
          (%o5)                      true
     Note that `dispJordan(%o3)' is the Jordan form of matrix `a'.

     To use this function write first `load("diag")'. See also `jordan'
     and `dispJordan'.


 -- Function: mat_function (<f>,<mat>)
     Returns f(mat), where <f> is an analytic function and <mat> a
     matrix. This computation is based on Cauchy's integral formula,
     which states that if `f(x)' is analytic and

          mat = diag([JF(m1,n1),...,JF(mk,nk)]),

     then

          f(mat) = ModeMatrix*diag([f(JF(m1,n1)), ..., f(JF(mk,nk))])
                                                        *ModeMatrix^^(-1)

     Note that there are about 6 or 8 other methods for this
     calculation.

     Some examples follow.

     Example 1:
          (%i1) load("diag")$

          (%i2) b2:matrix([0,1,0], [0,0,1], [-1,-3,-3])$

          (%i3) mat_function(exp,t*b2);
                         2   - t
                        t  %e          - t     - t
          (%o3) matrix([-------- + t %e    + %e   ,
                           2
                  - t     - t                           - t
           2    %e      %e        - t           - t   %e
          t  (- ----- - ----- + %e   ) + t (2 %e    - -----)
                  t       2                             t
                         t
                                   - t          - t     - t
                 - t       - t   %e        2  %e      %e
           + 2 %e   , t (%e    - -----) + t  (----- - -----)
                                   t            2       t
                         2   - t            - t     - t
               - t      t  %e        2    %e      %e        - t
           + %e   ], [- --------, - t  (- ----- - ----- + %e   ),
                           2                t       2
                                                   t
                  - t     - t      2   - t
             2  %e      %e        t  %e          - t
          - t  (----- - -----)], [-------- - t %e   ,
                  2       t          2
                  - t     - t                           - t
           2    %e      %e        - t           - t   %e
          t  (- ----- - ----- + %e   ) - t (2 %e    - -----),
                  t       2                             t
                         t
                - t     - t                 - t
           2  %e      %e            - t   %e
          t  (----- - -----) - t (%e    - -----)])
                2       t                   t
          (%i4) ratsimp(%);
                         [   2              - t ]
                         [ (t  + 2 t + 2) %e    ]
                         [ -------------------- ]
                         [          2           ]
                         [                      ]
                         [         2   - t      ]
          (%o4)  Col 1 = [        t  %e         ]
                         [      - --------      ]
                         [           2          ]
                         [                      ]
                         [     2          - t   ]
                         [   (t  - 2 t) %e      ]
                         [   ----------------   ]
                         [          2           ]
                   [      2        - t    ]
                   [    (t  + t) %e       ]
                   [                      ]
           Col 2 = [     2            - t ]
                   [ - (t  - t - 1) %e    ]
                   [                      ]
                   [     2          - t   ]
                   [   (t  - 3 t) %e      ]
                   [        2   - t       ]
                   [       t  %e          ]
                   [       --------       ]
                   [          2           ]
                   [                      ]
                   [      2          - t  ]
           Col 3 = [    (t  - 2 t) %e     ]
                   [  - ----------------  ]
                   [           2          ]
                   [                      ]
                   [   2              - t ]
                   [ (t  - 4 t + 2) %e    ]
                   [ -------------------- ]
                   [          2           ]

     Example 2:
          (%i5) b1:matrix([0,0,1,1,1],
                          [0,0,0,1,1],
                          [0,0,0,0,1],
                          [0,0,0,0,0],
                          [0,0,0,0,0])$

          (%i6) mat_function(exp,t*b1);
                            [              2     ]
                            [             t      ]
                            [ 1  0  t  t  -- + t ]
                            [             2      ]
                            [                    ]
          (%o6)             [ 0  1  0  t    t    ]
                            [                    ]
                            [ 0  0  1  0    t    ]
                            [                    ]
                            [ 0  0  0  1    0    ]
                            [                    ]
                            [ 0  0  0  0    1    ]
          (%i7) minimalPoly(jordan(b1));
                                       3
          (%o7)                       x
          (%i8) ident(5)+t*b1+1/2*(t^2)*b1^^2;
                            [              2     ]
                            [             t      ]
                            [ 1  0  t  t  -- + t ]
                            [             2      ]
                            [                    ]
          (%o8)             [ 0  1  0  t    t    ]
                            [                    ]
                            [ 0  0  1  0    t    ]
                            [                    ]
                            [ 0  0  0  1    0    ]
                            [                    ]
                            [ 0  0  0  0    1    ]
          (%i9) mat_function(exp,%i*t*b1);
                       [                           2 ]
                       [                          t  ]
                       [ 1  0  %i t  %i t  %i t - -- ]
                       [                          2  ]
                       [                             ]
          (%o9)        [ 0  1   0    %i t    %i t    ]
                       [                             ]
                       [ 0  0   1     0      %i t    ]
                       [                             ]
                       [ 0  0   0     1        0     ]
                       [                             ]
                       [ 0  0   0     0        1     ]
          (%i10) mat_function(cos,t*b1)+%i*mat_function(sin,t*b1);
                        [                           2 ]
                        [                          t  ]
                        [ 1  0  %i t  %i t  %i t - -- ]
                        [                          2  ]
                        [                             ]
          (%o10)        [ 0  1   0    %i t    %i t    ]
                        [                             ]
                        [ 0  0   1     0      %i t    ]
                        [                             ]
                        [ 0  0   0     1        0     ]
                        [                             ]
                        [ 0  0   0     0        1     ]

     Example 3:
          (%i11) a1:matrix([2,1,0,0,0,0],
                           [-1,4,0,0,0,0],
                           [-1,1,2,1,0,0],
                           [-1,1,-1,4,0,0],
                           [-1,1,-1,1,3,0],
                           [-1,1,-1,1,1,2])$

          (%i12) fpow(x):=block([k],declare(k,integer),x^k)$

          (%i13) mat_function(fpow,a1);
                          [  k      k - 1 ]         [      k - 1    ]
                          [ 3  - k 3      ]         [   k 3         ]
                          [               ]         [               ]
                          [       k - 1   ]         [  k      k - 1 ]
                          [  - k 3        ]         [ 3  + k 3      ]
                          [               ]         [               ]
                          [       k - 1   ]         [      k - 1    ]
                          [  - k 3        ]         [   k 3         ]
          (%o13)  Col 1 = [               ] Col 2 = [               ]
                          [       k - 1   ]         [      k - 1    ]
                          [  - k 3        ]         [   k 3         ]
                          [               ]         [               ]
                          [       k - 1   ]         [      k - 1    ]
                          [  - k 3        ]         [   k 3         ]
                          [               ]         [               ]
                          [       k - 1   ]         [      k - 1    ]
                          [  - k 3        ]         [   k 3         ]
                   [       0       ]         [       0       ]
                   [               ]         [               ]
                   [       0       ]         [       0       ]
                   [               ]         [               ]
                   [  k      k - 1 ]         [      k - 1    ]
                   [ 3  - k 3      ]         [   k 3         ]
                   [               ]         [               ]
           Col 3 = [       k - 1   ] Col 4 = [  k      k - 1 ]
                   [  - k 3        ]         [ 3  + k 3      ]
                   [               ]         [               ]
                   [       k - 1   ]         [      k - 1    ]
                   [  - k 3        ]         [   k 3         ]
                   [               ]         [               ]
                   [       k - 1   ]         [      k - 1    ]
                   [  - k 3        ]         [   k 3         ]
                   [    0    ]
                   [         ]         [ 0  ]
                   [    0    ]         [    ]
                   [         ]         [ 0  ]
                   [    0    ]         [    ]
                   [         ]         [ 0  ]
           Col 5 = [    0    ] Col 6 = [    ]
                   [         ]         [ 0  ]
                   [    k    ]         [    ]
                   [   3     ]         [ 0  ]
                   [         ]         [    ]
                   [  k    k ]         [  k ]
                   [ 3  - 2  ]         [ 2  ]

     To use this function write first `load("diag")'.



File: maxima.info,  Node: distrib,  Next: draw,  Prev: diag,  Up: Top

47 distrib
**********

* Menu:

* Introduction to distrib::
* Functions and Variables for continuous distributions::
* Functions and Variables for discrete distributions::


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

47.1 Introduction to distrib
============================

Package `distrib' contains a set of functions for making probability
computations on both discrete and continuous univariate models.

   What follows is a short reminder of basic probabilistic related
definitions.

   Let f(x) be the <density function> of an absolute continuous random
variable X. The <distribution function> is defined as
                            x
                           /
                           [
                    F(x) = I     f(u) du
                           ]
                           /
                            minf
   which equals the probability <Pr(X <= x)>.

   The <mean> value is a localization parameter and is defined as
                          inf
                         /
                         [
                E[X]  =  I   x f(x) dx
                         ]
                         /
                          minf

   The <variance> is a measure of variation,
                      inf
                     /
                     [                    2
              V[X] = I     f(x) (x - E[X])  dx
                     ]
                     /
                      minf
   which is a positive real number. The square root of the variance is
the <standard deviation>, D[X]=sqrt(V[X]), and it is another measure of
variation.

   The <skewness coefficient> is a measure of non-symmetry,
                      inf
                     /
                 1   [                    3
       SK[X] = ----- I     f(x) (x - E[X])  dx
                   3 ]
               D[X]  /
                      minf

   And the <kurtosis coefficient> measures the peakedness of the
distribution,
                      inf
                     /
                 1   [                    4
       KU[X] = ----- I     f(x) (x - E[X])  dx - 3
                   4 ]
               D[X]  /
                      minf
   If X is gaussian, KU[X]=0. In fact, both skewness and kurtosis are
shape parameters used to measure the non-gaussianity of a distribution.

   If the random variable X is discrete, the density, or <probability>,
function f(x) takes positive values within certain countable set of
numbers x_i, and zero elsewhere. In this case, the distribution
function is
                            ====
                            \
                     F(x) =  >    f(x )
                            /        i
                            ====
                           x <= x
                            i

   The mean, variance, standard deviation, skewness coefficient and
kurtosis coefficient take the form
                            ====
                            \
                     E[X] =  >  x  f(x ) ,
                            /    i    i
                            ====
                             x
                              i

                     ====
                     \                     2
             V[X] =   >    f(x ) (x - E[X])  ,
                     /        i    i
                     ====
                      x
                       i

                    D[X] = sqrt(V[X]),

                          ====
                   1      \                     3
       SK[X] =  -------    >    f(x ) (x - E[X])
                D[X]^3    /        i    i
                          ====
                           x
                            i
   and
                          ====
                   1      \                     4
       KU[X] =  -------    >    f(x ) (x - E[X])   - 3 ,
                D[X]^4    /        i    i
                          ====
                           x
                            i
   respectively.

   There is a naming convention in package `distrib'. Every function
name has two parts, the first one makes reference to the function or
parameter we want to calculate,
     Functions:
        Density function            (pdf_*)
        Distribution function       (cdf_*)
        Quantile                    (quantile_*)
        Mean                        (mean_*)
        Variance                    (var_*)
        Standard deviation          (std_*)
        Skewness coefficient        (skewness_*)
        Kurtosis coefficient        (kurtosis_*)
        Random variate              (random_*)

   The second part is an explicit reference to the probabilistic model,
     Continuous distributions:
        Normal              (*normal)
        Student             (*student_t)
        Chi^2               (*chi2)
        Noncentral Chi^2    (*noncentral_chi2)
        F                   (*f)
        Exponential         (*exp)
        Lognormal           (*lognormal)
        Gamma               (*gamma)
        Beta                (*beta)
        Continuous uniform  (*continuous_uniform)
        Logistic            (*logistic)
        Pareto              (*pareto)
        Weibull             (*weibull)
        Rayleigh            (*rayleigh)
        Laplace             (*laplace)
        Cauchy              (*cauchy)
        Gumbel              (*gumbel)

     Discrete distributions:
        Binomial             (*binomial)
        Poisson              (*poisson)
        Bernoulli            (*bernoulli)
        Geometric            (*geometric)
        Discrete uniform     (*discrete_uniform)
        hypergeometric       (*hypergeometric)
        Negative binomial    (*negative_binomial)

   For example, `pdf_student_t(x,n)' is the density function of the
Student distribution with <n> degrees of freedom, `std_pareto(a,b)' is
the standard deviation of the Pareto distribution with parameters <a>
and <b> and `kurtosis_poisson(m)' is the kurtosis coefficient of the
Poisson distribution with mean <m>.

   In order to make use of package `distrib' you need first to load it
by typing
     (%i1) load(distrib)$

   For comments, bugs or suggestions, please contact the author at
<'mario AT edu DOT xunta DOT es'>.


File: maxima.info,  Node: Functions and Variables for continuous distributions,  Next: Functions and Variables for discrete distributions,  Prev: Introduction to distrib,  Up: distrib

47.2 Functions and Variables for continuous distributions
=========================================================

 -- Function: pdf_normal (<x>,<m>,<s>)
     Returns the value at <x> of the density function of a Normal(m,s)
     random variable, with s>0. To make use of this function, write
     first `load(distrib)'.


 -- Function: cdf_normal (<x>,<m>,<s>)
     Returns the value at <x> of the distribution function of a
     Normal(m,s) random variable, with s>0. This function is defined in
     terms of Maxima's built-in error function `erf'.

          (%i1) load (distrib)$
          (%i2) assume(s>0)$ cdf_normal(x,m,s);
                                       x - m
                                 erf(---------)
                                     sqrt(2) s    1
          (%o3)                  -------------- + -
                                       2          2

     See also `erf'.


 -- Function: quantile_normal (<q>,<m>,<s>)
     Returns the <q>-quantile of a Normal(m,s) random variable, with
     s>0; in other words, this is the inverse of `cdf_normal'. Argument
     <q> must be an element of [0,1]. To make use of this function,
     write first `load(distrib)'.


 -- Function: mean_normal (<m>,<s>)
     Returns the mean of a Normal(m,s) random variable, with s>0,
     namely <m>. To make use of this function, write first
     `load(distrib)'.


 -- Function: var_normal (<m>,<s>)
     Returns the variance of a Normal(m,s) random variable, with s>0,
     namely <s^2>. To make use of this function, write first
     `load(distrib)'.


 -- Function: std_normal (<m>,<s>)
     Returns the standard deviation of a Normal(m,s) random variable,
     with s>0, namely <s>. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_normal (<m>,<s>)
     Returns the skewness coefficient of a Normal(m,s) random variable,
     with s>0, which is always equal to 0. To make use of this
     function, write first `load(distrib)'.


 -- Function: kurtosis_normal (<m>,<s>)
     Returns the kurtosis coefficient of a Normal(m,s) random variable,
     with s>0, which is always equal to 0. To make use of this
     function, write first `load(distrib)'.


 -- Function: random_normal (<m>,<s>)
 -- Function: random_normal (<m>,<s>,<n>)
     Returns a Normal(m,s) random variate, with s>0. Calling
     `random_normal' with a third argument <n>, a random sample of size
     <n> will be simulated.

     This is an implementation of the Box-Mueller algorithm, as
     described in Knuth, D.E. (1981) <Seminumerical Algorithms. The Art
     of Computer Programming.> Addison-Wesley.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_student_t (<x>,<n>)
     Returns the value at <x> of the density function of a Student
     random variable t(n), with n>0. To make use of this function,
     write first `load(distrib)'.


 -- Function: cdf_student_t (<x>,<n>)
     Returns the value at <x> of the distribution function of a Student
     random variable t(n), with n>0. This function has no closed form
     and it is numerically computed if the global variable `numer'
     equals `true',  otherwise it returns a nominal expression.

          (%i1) load (distrib)$
          (%i2) cdf_student_t(1/2, 7/3);
                                               1  7
          (%o2)                  cdf_student_t(-, -)
                                               2  3
          (%i3) %,numer;
          (%o3)                   .6698450596140417


 -- Function: quantile_student_t (<q>,<n>)
     Returns the <q>-quantile of a Student random variable t(n), with
     n>0; in other words, this is the inverse of `cdf_student_t'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_student_t (<n>)
     Returns the mean of a Student random variable t(n), with n>0,
     which is always equal to 0. To make use of this function, write
     first `load(distrib)'.


 -- Function: var_student_t (<n>)
     Returns the variance of a Student random variable t(n), with n>2.

          (%i1) load (distrib)$
          (%i2) assume(n>2)$  var_student_t(n);
                                          n
          (%o3)                         -----
                                        n - 2


 -- Function: std_student_t (<n>)
     Returns the standard deviation of a Student random variable t(n),
     with n>2. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_student_t (<n>)
     Returns the skewness coefficient of a Student random variable
     t(n), with n>3, which is always equal to 0. To make use of this
     function, write first `load(distrib)'.


 -- Function: kurtosis_student_t (<n>)
     Returns the kurtosis coefficient of a Student random variable
     t(n), with n>4. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_student_t (<n>)
 -- Function: random_student_t (<n>,<m>)
     Returns a Student random variate t(n), with n>0. Calling
     `random_student_t' with a second argument <m>, a random sample of
     size <m> will be simulated.

     The implemented algorithm is based on the fact that if <Z> is a
     normal random variable N(0,1) and S^2 is a chi square random
     variable with <n> degrees of freedom, Chi^2(n), then
                                     Z
                           X = -------------
                               /   2  \ 1/2
                               |  S   |
                               | ---  |
                               \  n   /
     is a Student random variable with <n> degrees of freedom, t(n).

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_chi2 (<x>,<n>)
     Returns the value at <x> of the density function of a Chi-square
     random variable Chi^2(n), with n>0.

     The Chi^2(n) random variable is equivalent to the Gamma(n/2,2),
     therefore when Maxima has not enough information to get the
     result, a noun form based on the gamma density is returned.

          (%i1) load (distrib)$
          (%i2) pdf_chi2(x,n);
                                              n
          (%o2)                  pdf_gamma(x, -, 2)
                                              2
          (%i3) assume(x>0, n>0)$  pdf_chi2(x,n);
                                   n/2 - 1   - x/2
                                  x        %e
          (%o4)                   ----------------
                                    n/2       n
                                   2    gamma(-)
                                              2


 -- Function: cdf_chi2 (<x>,<n>)
     Returns the value at <x> of the distribution function of a
     Chi-square random variable Chi^2(n), with n>0.

     This function has no closed form and it is numerically computed if
     the global variable `numer' equals `true',  otherwise it returns a
     nominal expression based on the gamma distribution, since the
     Chi^2(n) random variable is equivalent to the Gamma(n/2,2).

          (%i1) load (distrib)$
          (%i2) cdf_chi2(3,4);
          (%o2)                  cdf_gamma(3, 2, 2)
          (%i3) cdf_chi2(3,4),numer;
          (%o3)                   .4421745996289249


 -- Function: quantile_chi2 (<q>,<n>)
     Returns the <q>-quantile of a Chi-square random variable Chi^2(n),
     with n>0; in other words, this is the inverse of `cdf_chi2'.
     Argument <q> must be an element of [0,1].

     This function has no closed form and it is numerically computed if
     the global variable `numer' equals `true',  otherwise it returns a
     nominal expression based on the gamma quantile function, since the
     Chi^2(n) random variable is equivalent to the Gamma(n/2,2).

          (%i1) load (distrib)$
          (%i2) quantile_chi2(0.99,9);
          (%o2)                   21.66599433346194
          (%i3) quantile_chi2(0.99,n);
                                                  n
          (%o3)              quantile_gamma(0.99, -, 2)
                                                  2


 -- Function: mean_chi2 (<n>)
     Returns the mean of a Chi-square random variable Chi^2(n), with
     n>0.

     The Chi^2(n) random variable is equivalent to the Gamma(n/2,2),
     therefore when Maxima has not enough information to get the
     result, a noun form based on the gamma mean is returned.

          (%i1) load (distrib)$
          (%i2) mean_chi2(n);
                                             n
          (%o2)                   mean_gamma(-, 2)
                                             2
          (%i3) assume(n>0)$ mean_chi2(n);
          (%o4)                           n


 -- Function: var_chi2 (<n>)
     Returns the variance of a Chi-square random variable Chi^2(n),
     with n>0.

     The Chi^2(n) random variable is equivalent to the Gamma(n/2,2),
     therefore when Maxima has not enough information to get the
     result, a noun form based on the gamma variance is returned.

          (%i1) load (distrib)$
          (%i2) var_chi2(n);
                                             n
          (%o2)                    var_gamma(-, 2)
                                             2
          (%i3) assume(n>0)$ var_chi2(n);
          (%o4)                          2 n


 -- Function: std_chi2 (<n>)
     Returns the standard deviation of a Chi-square random variable
     Chi^2(n), with n>0.

     The Chi^2(n) random variable is equivalent to the Gamma(n/2,2),
     therefore when Maxima has not enough information to get the
     result, a noun form based on the gamma standard deviation is
     returned.

          (%i1) load (distrib)$
          (%i2) std_chi2(n);
                                             n
          (%o2)                    std_gamma(-, 2)
                                             2
          (%i3) assume(n>0)$ std_chi2(n);
          (%o4)                    sqrt(2) sqrt(n)


 -- Function: skewness_chi2 (<n>)
     Returns the skewness coefficient of a Chi-square random variable
     Chi^2(n), with n>0.

     The Chi^2(n) random variable is equivalent to the Gamma(n/2,2),
     therefore when Maxima has not enough information to get the
     result, a noun form based on the gamma skewness coefficient is
     returned.

          (%i1) load (distrib)$
          (%i2) skewness_chi2(n);
                                               n
          (%o2)                 skewness_gamma(-, 2)
                                               2
          (%i3) assume(n>0)$ skewness_chi2(n);
                                      2 sqrt(2)
          (%o4)                       ---------
                                       sqrt(n)


 -- Function: kurtosis_chi2 (<n>)
     Returns the kurtosis coefficient of a Chi-square random variable
     Chi^2(n), with n>0.

     The Chi^2(n) random variable is equivalent to the Gamma(n/2,2),
     therefore when Maxima has not enough information to get the
     result, a noun form based on the gamma kurtosis coefficient is
     returned.

          (%i1) load (distrib)$
          (%i2) kurtosis_chi2(n);
                                               n
          (%o2)                 kurtosis_gamma(-, 2)
                                               2
          (%i3) assume(n>0)$ kurtosis_chi2(n);
                                         12
          (%o4)                          --
                                         n


 -- Function: random_chi2 (<n>)
 -- Function: random_chi2 (<n>,<m>)
     Returns a Chi-square random variate Chi^2(n), with n>0. Calling
     `random_chi2' with a second argument <m>, a random sample of size
     <m> will be simulated.

     The simulation is based on the Ahrens-Cheng algorithm. See
     `random_gamma' for details.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_noncentral_chi2 (<x>,<n>,<ncp>)
     Returns the value at <x> of the density function of a noncentral
     Chi-square random variable nc_Chi^2(n,ncp), with n>0 and
     noncentrality parameter ncp>=0. To make use of this function,
     write first `load(distrib)'.


 -- Function: cdf_noncentral_chi2 (<x>,<n>,<ncp>)
     Returns the value at <x> of the distribution function of a
     noncentral Chi-square random variable nc_Chi^2(n,ncp), with n>0
     and noncentrality parameter ncp>=0. To make use of this function,
     write first `load(distrib)'.


 -- Function: quantile_noncentral_chi2 (<q>,<n>,<ncp>)
     Returns the <q>-quantile of a noncentral Chi-square random
     variable nc_Chi^2(n,ncp), with n>0 and noncentrality parameter
     ncp>=0; in other words, this is the inverse of
     `cdf_noncentral_chi2'. Argument <q> must be an element of [0,1].

     This function has no closed form and it is numerically computed if
     the global variable `numer' equals `true',  otherwise it returns a
     nominal expression.


 -- Function: mean_noncentral_chi2 (<n>,<ncp>)
     Returns the mean of a noncentral Chi-square random variable
     nc_Chi^2(n,ncp), with n>0 and noncentrality parameter ncp>=0.


 -- Function: var_noncentral_chi2 (<n>,<ncp>)
     Returns the variance of a noncentral Chi-square random variable
     nc_Chi^2(n,ncp), with n>0 and noncentrality parameter ncp>=0.


 -- Function: std_noncentral_chi2 (<n>,<ncp>)
     Returns the standard deviation of a noncentral Chi-square random
     variable nc_Chi^2(n,ncp), with n>0 and noncentrality parameter
     ncp>=0.


 -- Function: skewness_noncentral_chi2 (<n>,<ncp>)
     Returns the skewness coefficient of a noncentral Chi-square random
     variable nc_Chi^2(n,ncp), with n>0 and noncentrality parameter
     ncp>=0.


 -- Function: kurtosis_noncentral_chi2 (<n>,<ncp>)
     Returns the kurtosis coefficient of a noncentral Chi-square random
     variable nc_Chi^2(n,ncp), with n>0 and noncentrality parameter
     ncp>=0.


 -- Function: random_noncentral_chi2 (<n>,<ncp>)
 -- Function: random_noncentral_chi2 (<n>,<ncp>,<m>)
     Returns a noncentral Chi-square random variate nc_Chi^2(n,ncp),
     with n>0 and noncentrality parameter ncp>=0. Calling
     `random_noncentral_chi2' with a third argument <m>, a random
     sample of size <m> will be simulated.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_f (<x>,<m>,<n>)
     Returns the value at <x> of the density function of a F random
     variable F(m,n), with m,n>0. To make use of this function, write
     first `load(distrib)'.


 -- Function: cdf_f (<x>,<m>,<n>)
     Returns the value at <x> of the distribution function of a F
     random variable F(m,n), with m,n>0. This function has no closed
     form and it is numerically computed if the global variable `numer'
     equals `true',  otherwise it returns a nominal expression.

          (%i1) load (distrib)$
          (%i2) cdf_f(2,3,9/4);
                                               9
          (%o2)                    cdf_f(2, 3, -)
                                               4
          (%i3) %,numer;
          (%o3)                   0.66756728179008


 -- Function: quantile_f (<q>,<m>,<n>)
     Returns the <q>-quantile of a F random variable F(m,n), with
     m,n>0; in other words, this is the inverse of `cdf_f'. Argument
     <q> must be an element of [0,1].

     This function has no closed form and it is numerically computed if
     the global variable `numer' equals `true',  otherwise it returns a
     nominal expression.

          (%i1) load (distrib)$
          (%i2) quantile_f(2/5,sqrt(3),5);
                                         2
          (%o2)               quantile_f(-, sqrt(3), 5)
                                         5
          (%i3) %,numer;
          (%o3)                   0.518947838573693


 -- Function: mean_f (<m>,<n>)
     Returns the mean of a F random variable F(m,n), with m>0, n>2. To
     make use of this function, write first `load(distrib)'.


 -- Function: var_f (<m>,<n>)
     Returns the variance of a F random variable F(m,n), with m>0, n>4.
     To make use of this function, write first `load(distrib)'.


 -- Function: std_f (<m>,<n>)
     Returns the standard deviation of a F random variable F(m,n), with
     m>0, n>4. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_f (<m>,<n>)
     Returns the skewness coefficient of a F random variable F(m,n),
     with m>0, n>6. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_f (<m>,<n>)
     Returns the kurtosis coefficient of a F random variable F(m,n),
     with m>0, n>8. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_f (<m>,<n>)
 -- Function: random_f (<m>,<n>,<k>)
     Returns a F random variate F(m,n), with m,n>0. Calling `random_f'
     with a third argument <k>, a random sample of size <k> will be
     simulated.

     The simulation algorithm is based on the fact that if <X> is a
     Chi^2(m) random variable and Y is a Chi^2(n) random variable, then
                                  n X
                              F = ---
                                  m Y
     is a F random variable with <m> and <n> degrees of freedom, F(m,n).

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_exp (<x>,<m>)
     Returns the value at <x> of the density function of an
     Exponential(m) random variable, with m>0.

     The Exponential(m) random variable is equivalent to the
     Weibull(1,1/m), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull density is
     returned.

          (%i1) load (distrib)$
          (%i2) pdf_exp(x,m);
                                                  1
          (%o2)                 pdf_weibull(x, 1, -)
                                                  m
          (%i3) assume(x>0,m>0)$  pdf_exp(x,m);
                                          - m x
          (%o4)                       m %e


 -- Function: cdf_exp (<x>,<m>)
     Returns the value at <x> of the distribution function of an
     Exponential(m) random variable, with m>0.

     The Exponential(m) random variable is equivalent to the
     Weibull(1,1/m), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull distribution
     is returned.

          (%i1) load (distrib)$
          (%i2) cdf_exp(x,m);
                                                  1
          (%o2)                 cdf_weibull(x, 1, -)
                                                  m
          (%i3) assume(x>0,m>0)$  cdf_exp(x,m);
                                           - m x
          (%o4)                      1 - %e


 -- Function: quantile_exp (<q>,<m>)
     Returns the <q>-quantile of an Exponential(m) random variable,
     with m>0; in other words, this is the inverse of `cdf_exp'.
     Argument <q> must be an element of [0,1].

     The Exponential(m) random variable is equivalent to the
     Weibull(1,1/m), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull quantile is
     returned.

          (%i1) load (distrib)$
          (%i2) quantile_exp(0.56,5);
          (%o2)                   .1641961104139661
          (%i3) quantile_exp(0.56,m);
                                                      1
          (%o3)             quantile_weibull(0.56, 1, -)
                                                      m


 -- Function: mean_exp (<m>)
     Returns the mean of an Exponential(m) random variable, with m>0.

     The Exponential(m) random variable is equivalent to the
     Weibull(1,1/m), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull mean is
     returned.

          (%i1) load (distrib)$
          (%i2) mean_exp(m);
                                                 1
          (%o2)                  mean_weibull(1, -)
                                                 m
          (%i3) assume(m>0)$  mean_exp(m);
                                          1
          (%o4)                           -
                                          m


 -- Function: var_exp (<m>)
     Returns the variance of an Exponential(m) random variable, with
     m>0.

     The Exponential(m) random variable is equivalent to the
     Weibull(1,1/m), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull variance is
     returned.

          (%i1) load (distrib)$
          (%i2) var_exp(m);
                                                 1
          (%o2)                   var_weibull(1, -)
                                                 m
          (%i3) assume(m>0)$  var_exp(m);
                                         1
          (%o4)                          --
                                          2
                                         m


 -- Function: std_exp (<m>)
     Returns the standard deviation of an Exponential(m) random
     variable, with m>0.

     The Exponential(m) random variable is equivalent to the
     Weibull(1,1/m), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull standard
     deviation is returned.

          (%i1) load (distrib)$
          (%i2) std_exp(m);
                                                 1
          (%o2)                   std_weibull(1, -)
                                                 m
          (%i3) assume(m>0)$  std_exp(m);
                                          1
          (%o4)                           -
                                          m


 -- Function: skewness_exp (<m>)
     Returns the skewness coefficient of an Exponential(m) random
     variable, with m>0.

     The Exponential(m) random variable is equivalent to the
     Weibull(1,1/m), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull skewness
     coefficient is returned.

          (%i1) load (distrib)$
          (%i2) skewness_exp(m);
                                                   1
          (%o2)                skewness_weibull(1, -)
                                                   m
          (%i3) assume(m>0)$  skewness_exp(m);
          (%o4)                           2


 -- Function: kurtosis_exp (<m>)
     Returns the kurtosis coefficient of an Exponential(m) random
     variable, with m>0.

     The Exponential(m) random variable is equivalent to the
     Weibull(1,1/m), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull kurtosis
     coefficient is returned.

          (%i1) load (distrib)$
          (%i2) kurtosis_exp(m);
                                                   1
          (%o2)                kurtosis_weibull(1, -)
                                                   m
          (%i3) assume(m>0)$  kurtosis_exp(m);
          (%o4)                           6


 -- Function: random_exp (<m>)
 -- Function: random_exp (<m>,<k>)
     Returns an Exponential(m) random variate, with m>0. Calling
     `random_exp' with a second argument <k>, a random sample of size
     <k> will be simulated.

     The simulation algorithm is based on the general inverse method.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_lognormal (<x>,<m>,<s>)
     Returns the value at <x> of the density function of a
     Lognormal(m,s) random variable, with s>0. To make use of this
     function, write first `load(distrib)'.


 -- Function: cdf_lognormal (<x>,<m>,<s>)
     Returns the value at <x> of the distribution function of a
     Lognormal(m,s) random variable, with s>0. This function is defined
     in terms of Maxima's built-in error function `erf'.

          (%i1) load (distrib)$
          (%i2) assume(x>0, s>0)$  cdf_lognormal(x,m,s);
                                     log(x) - m
                                 erf(----------)
                                     sqrt(2) s     1
          (%o3)                  --------------- + -
                                        2          2

     See also `erf'.


 -- Function: quantile_lognormal (<q>,<m>,<s>)
     Returns the <q>-quantile of a Lognormal(m,s) random variable, with
     s>0; in other words, this is the inverse of `cdf_lognormal'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_lognormal (<m>,<s>)
     Returns the mean of a Lognormal(m,s) random variable, with s>0. To
     make use of this function, write first `load(distrib)'.


 -- Function: var_lognormal (<m>,<s>)
     Returns the variance of a Lognormal(m,s) random variable, with
     s>0. To make use of this function, write first `load(distrib)'.


 -- Function: std_lognormal (<m>,<s>)
     Returns the standard deviation of a Lognormal(m,s) random
     variable, with s>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_lognormal (<m>,<s>)
     Returns the skewness coefficient of a Lognormal(m,s) random
     variable, with s>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_lognormal (<m>,<s>)
     Returns the kurtosis coefficient of a Lognormal(m,s) random
     variable, with s>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_lognormal (<m>,<s>)
 -- Function: random_lognormal (<m>,<s>,<n>)
     Returns a Lognormal(m,s) random variate, with s>0. Calling
     `random_lognormal' with a third argument <n>, a random sample of
     size <n> will be simulated.

     Log-normal variates are simulated by means of random normal
     variates. See `random_normal' for details.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_gamma (<x>,<a>,<b>)
     Returns the value at <x> of the density function of a Gamma(a,b)
     random variable, with a,b>0. To make use of this function, write
     first `load(distrib)'.


 -- Function: cdf_gamma (<x>,<a>,<b>)
     Returns the value at <x> of the distribution function of a
     Gamma(a,b) random variable, with a,b>0.

     This function has no closed form and it is numerically computed if
     the global variable `numer' equals `true',  otherwise it returns a
     nominal expression.

          (%i1) load (distrib)$
          (%i2) cdf_gamma(3,5,21);
          (%o2)                  cdf_gamma(3, 5, 21)
          (%i3) %,numer;
          (%o3)                 4.402663157135039E-7


 -- Function: quantile_gamma (<q>,<a>,<b>)
     Returns the <q>-quantile of a Gamma(a,b) random variable, with
     a,b>0; in other words, this is the inverse of `cdf_gamma'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_gamma (<a>,<b>)
     Returns the mean of a Gamma(a,b) random variable, with a,b>0. To
     make use of this function, write first `load(distrib)'.


 -- Function: var_gamma (<a>,<b>)
     Returns the variance of a Gamma(a,b) random variable, with a,b>0.
     To make use of this function, write first `load(distrib)'.


 -- Function: std_gamma (<a>,<b>)
     Returns the standard deviation of a Gamma(a,b) random variable,
     with a,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_gamma (<a>,<b>)
     Returns the skewness coefficient of a Gamma(a,b) random variable,
     with a,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_gamma (<a>,<b>)
     Returns the kurtosis coefficient of a Gamma(a,b) random variable,
     with a,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_gamma (<a>,<b>)
 -- Function: random_gamma (<a>,<b>,<n>)
     Returns a Gamma(a,b) random variate, with a,b>0. Calling
     `random_gamma' with a third argument <n>, a random sample of size
     <n> will be simulated.

     The implemented algorithm is a combinantion of two procedures,
     depending on the value of parameter <a>:

     For a>=1, Cheng, R.C.H. and Feast, G.M. (1979). <Some simple gamma
     variate generators>. Appl. Stat., 28, 3, 290-295.

     For 0<a<1, Ahrens, J.H. and Dieter, U. (1974). <Computer methods
     for sampling from gamma, beta, poisson and binomial
     cdf_tributions>. Computing, 12, 223-246.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_beta (<x>,<a>,<b>)
     Returns the value at <x> of the density function of a Beta(a,b)
     random variable, with a,b>0. To make use of this function, write
     first `load(distrib)'.


 -- Function: cdf_beta (<x>,<a>,<b>)
     Returns the value at <x> of the distribution function of a
     Beta(a,b) random variable, with a,b>0.

     This function has no closed form and it is numerically computed if
     the global variable `numer' equals `true',  otherwise it returns a
     nominal expression.

          (%i1) load (distrib)$
          (%i2) cdf_beta(1/3,15,2);
                                           1
          (%o2)                   cdf_beta(-, 15, 2)
                                           3
          (%i3) %,numer;
          (%o3)                 7.666089131388224E-7


 -- Function: quantile_beta (<q>,<a>,<b>)
     Returns the <q>-quantile of a Beta(a,b) random variable, with
     a,b>0; in other words, this is the inverse of `cdf_beta'. Argument
     <q> must be an element of [0,1]. To make use of this function,
     write first `load(distrib)'.


 -- Function: mean_beta (<a>,<b>)
     Returns the mean of a Beta(a,b) random variable, with a,b>0. To
     make use of this function, write first `load(distrib)'.


 -- Function: var_beta (<a>,<b>)
     Returns the variance of a Beta(a,b) random variable, with a,b>0.
     To make use of this function, write first `load(distrib)'.


 -- Function: std_beta (<a>,<b>)
     Returns the standard deviation of a Beta(a,b) random variable,
     with a,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_beta (<a>,<b>)
     Returns the skewness coefficient of a Beta(a,b) random variable,
     with a,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_beta (<a>,<b>)
     Returns the kurtosis coefficient of a Beta(a,b) random variable,
     with a,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_beta (<a>,<b>)
 -- Function: random_beta (<a>,<b>,<n>)
     Returns a Beta(a,b) random variate, with a,b>0. Calling
     `random_beta' with a third argument <n>, a random sample of size
     <n> will be simulated.

     The implemented algorithm is defined in Cheng, R.C.H.  (1978).
     <Generating Beta Variates with Nonintegral Shape Parameters>.
     Communications of the ACM, 21:317-322

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_continuous_uniform (<x>,<a>,<b>)
     Returns the value at <x> of the density function of a Continuous
     Uniform(a,b) random variable, with a<b. To make use of this
     function, write first `load(distrib)'.


 -- Function: cdf_continuous_uniform (<x>,<a>,<b>)
     Returns the value at <x> of the distribution function of a
     Continuous Uniform(a,b) random variable, with a<b. To make use of
     this function, write first `load(distrib)'.


 -- Function: quantile_continuous_uniform (<q>,<a>,<b>)
     Returns the <q>-quantile of a Continuous Uniform(a,b) random
     variable, with a<b; in other words, this is the inverse of
     `cdf_continuous_uniform'. Argument <q> must be an element of
     [0,1]. To make use of this function, write first `load(distrib)'.


 -- Function: mean_continuous_uniform (<a>,<b>)
     Returns the mean of a Continuous Uniform(a,b) random variable,
     with a<b. To make use of this function, write first
     `load(distrib)'.


 -- Function: var_continuous_uniform (<a>,<b>)
     Returns the variance of a Continuous Uniform(a,b) random variable,
     with a<b. To make use of this function, write first
     `load(distrib)'.


 -- Function: std_continuous_uniform (<a>,<b>)
     Returns the standard deviation of a Continuous Uniform(a,b) random
     variable, with a<b. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_continuous_uniform (<a>,<b>)
     Returns the skewness coefficient of a Continuous Uniform(a,b)
     random variable, with a<b. To make use of this function, write
     first `load(distrib)'.


 -- Function: kurtosis_continuous_uniform (<a>,<b>)
     Returns the kurtosis coefficient of a Continuous Uniform(a,b)
     random variable, with a<b. To make use of this function, write
     first `load(distrib)'.


 -- Function: random_continuous_uniform (<a>,<b>)
 -- Function: random_continuous_uniform (<a>,<b>,<n>)
     Returns a Continuous Uniform(a,b) random variate, with a<b.
     Calling `random_continuous_uniform' with a third argument <n>, a
     random sample of size <n> will be simulated.

     This is a direct application of the `random' built-in Maxima
     function.

     See also `random'. To make use of this function, write first
     `load(distrib)'.


 -- Function: pdf_logistic (<x>,<a>,<b>)
     Returns the value at <x> of the density function of a
     Logistic(a,b) random variable , with b>0. To make use of this
     function, write first `load(distrib)'.


 -- Function: cdf_logistic (<x>,<a>,<b>)
     Returns the value at <x> of the distribution function of a
     Logistic(a,b) random variable , with b>0. To make use of this
     function, write first `load(distrib)'.


 -- Function: quantile_logistic (<q>,<a>,<b>)
     Returns the <q>-quantile of a Logistic(a,b) random variable , with
     b>0; in other words, this is the inverse of `cdf_logistic'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_logistic (<a>,<b>)
     Returns the mean of a Logistic(a,b) random variable , with b>0. To
     make use of this function, write first `load(distrib)'.


 -- Function: var_logistic (<a>,<b>)
     Returns the variance of a Logistic(a,b) random variable , with
     b>0. To make use of this function, write first `load(distrib)'.


 -- Function: std_logistic (<a>,<b>)
     Returns the standard deviation of a Logistic(a,b) random variable
     , with b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_logistic (<a>,<b>)
     Returns the skewness coefficient of a Logistic(a,b) random
     variable , with b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_logistic (<a>,<b>)
     Returns the kurtosis coefficient of a Logistic(a,b) random
     variable , with b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_logistic (<a>,<b>)
 -- Function: random_logistic (<a>,<b>,<n>)
     Returns a Logistic(a,b) random variate, with b>0. Calling
     `random_logistic' with a third argument <n>, a random sample of
     size <n> will be simulated.

     The implemented algorithm is based on the general inverse method.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_pareto (<x>,<a>,<b>)
     Returns the value at <x> of the density function of a Pareto(a,b)
     random variable, with a,b>0. To make use of this function, write
     first `load(distrib)'.


 -- Function: cdf_pareto (<x>,<a>,<b>)
     Returns the value at <x> of the distribution function of a
     Pareto(a,b) random variable, with a,b>0. To make use of this
     function, write first `load(distrib)'.


 -- Function: quantile_pareto (<q>,<a>,<b>)
     Returns the <q>-quantile of a Pareto(a,b) random variable, with
     a,b>0; in other words, this is the inverse of `cdf_pareto'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_pareto (<a>,<b>)
     Returns the mean of a Pareto(a,b) random variable, with a>1,b>0.
     To make use of this function, write first `load(distrib)'.


 -- Function: var_pareto (<a>,<b>)
     Returns the variance of a Pareto(a,b) random variable, with
     a>2,b>0. To make use of this function, write first `load(distrib)'.


 -- Function: std_pareto (<a>,<b>)
     Returns the standard deviation of a Pareto(a,b) random variable,
     with a>2,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_pareto (<a>,<b>)
     Returns the skewness coefficient of a Pareto(a,b) random variable,
     with a>3,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_pareto (<a>,<b>)
     Returns the kurtosis coefficient of a Pareto(a,b) random variable,
     with a>4,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_pareto (<a>,<b>)
 -- Function: random_pareto (<a>,<b>,<n>)
     Returns a Pareto(a,b) random variate, with a>0,b>0. Calling
     `random_pareto' with a third argument <n>, a random sample of size
     <n> will be simulated.

     The implemented algorithm is based on the general inverse method.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_weibull (<x>,<a>,<b>)
     Returns the value at <x> of the density function of a Weibull(a,b)
     random variable, with a,b>0. To make use of this function, write
     first `load(distrib)'.


 -- Function: cdf_weibull (<x>,<a>,<b>)
     Returns the value at <x> of the distribution function of a
     Weibull(a,b) random variable, with a,b>0. To make use of this
     function, write first `load(distrib)'.


 -- Function: quantile_weibull (<q>,<a>,<b>)
     Returns the <q>-quantile of a Weibull(a,b) random variable, with
     a,b>0; in other words, this is the inverse of `cdf_weibull'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_weibull (<a>,<b>)
     Returns the mean of a Weibull(a,b) random variable, with a,b>0. To
     make use of this function, write first `load(distrib)'.


 -- Function: var_weibull (<a>,<b>)
     Returns the variance of a Weibull(a,b) random variable, with
     a,b>0. To make use of this function, write first `load(distrib)'.


 -- Function: std_weibull (<a>,<b>)
     Returns the standard deviation of a Weibull(a,b) random variable,
     with a,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_weibull (<a>,<b>)
     Returns the skewness coefficient of a Weibull(a,b) random
     variable, with a,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_weibull (<a>,<b>)
     Returns the kurtosis coefficient of a Weibull(a,b) random
     variable, with a,b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_weibull (<a>,<b>)
 -- Function: random_weibull (<a>,<b>,<n>)
     Returns a Weibull(a,b) random variate, with a,b>0. Calling
     `random_weibull' with a third argument <n>, a random sample of
     size <n> will be simulated.

     The implemented algorithm is based on the general inverse method.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_rayleigh (<x>,<b>)
     Returns the value at <x> of the density function of a Rayleigh(b)
     random variable, with b>0.

     The Rayleigh(b) random variable is equivalent to the
     Weibull(2,1/b), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull density is
     returned.

          (%i1) load (distrib)$
          (%i2) pdf_rayleigh(x,b);
                                                  1
          (%o2)                 pdf_weibull(x, 2, -)
                                                  b
          (%i3) assume(x>0,b>0)$ pdf_rayleigh(x,b);
                                              2  2
                                     2     - b  x
          (%o4)                   2 b  x %e


 -- Function: cdf_rayleigh (<x>,<b>)
     Returns the value at <x> of the distribution function of a
     Rayleigh(b) random variable, with b>0.

     The Rayleigh(b) random variable is equivalent to the
     Weibull(2,1/b), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull distribution
     is returned.

          (%i1) load (distrib)$
          (%i2) cdf_rayleigh(x,b);
                                                  1
          (%o2)                 cdf_weibull(x, 2, -)
                                                  b
          (%i3) assume(x>0,b>0)$ cdf_rayleigh(x,b);
                                             2  2
                                          - b  x
          (%o4)                     1 - %e


 -- Function: quantile_rayleigh (<q>,<b>)
     Returns the <q>-quantile of a Rayleigh(b) random variable, with
     b>0; in other words, this is the inverse of `cdf_rayleigh'.
     Argument <q> must be an element of [0,1].

     The Rayleigh(b) random variable is equivalent to the
     Weibull(2,1/b), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull quantile is
     returned.

          (%i1) load (distrib)$
          (%i2) quantile_rayleigh(0.99,b);
                                                      1
          (%o2)             quantile_weibull(0.99, 2, -)
                                                      b
          (%i3) assume(x>0,b>0)$ quantile_rayleigh(0.99,b);
                                  2.145966026289347
          (%o4)                   -----------------
                                          b


 -- Function: mean_rayleigh (<b>)
     Returns the mean of a Rayleigh(b) random variable, with b>0.

     The Rayleigh(b) random variable is equivalent to the
     Weibull(2,1/b), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull mean is
     returned.

          (%i1) load (distrib)$
          (%i2) mean_rayleigh(b);
                                                 1
          (%o2)                  mean_weibull(2, -)
                                                 b
          (%i3) assume(b>0)$ mean_rayleigh(b);
                                      sqrt(%pi)
          (%o4)                       ---------
                                         2 b


 -- Function: var_rayleigh (<b>)
     Returns the variance of a Rayleigh(b) random variable, with b>0.

     The Rayleigh(b) random variable is equivalent to the
     Weibull(2,1/b), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull variance is
     returned.

          (%i1) load (distrib)$
          (%i2) var_rayleigh(b);
                                                 1
          (%o2)                   var_weibull(2, -)
                                                 b
          (%i3) assume(b>0)$ var_rayleigh(b);
                                           %pi
                                       1 - ---
                                            4
          (%o4)                        -------
                                          2
                                         b


 -- Function: std_rayleigh (<b>)
     Returns the standard deviation of a Rayleigh(b) random variable,
     with b>0.

     The Rayleigh(b) random variable is equivalent to the
     Weibull(2,1/b), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull standard
     deviation is returned.

          (%i1) load (distrib)$
          (%i2) std_rayleigh(b);
                                                 1
          (%o2)                   std_weibull(2, -)
                                                 b
          (%i3) assume(b>0)$ std_rayleigh(b);
                                             %pi
                                    sqrt(1 - ---)
                                              4
          (%o4)                     -------------
                                          b


 -- Function: skewness_rayleigh (<b>)
     Returns the skewness coefficient of a Rayleigh(b) random variable,
     with b>0.

     The Rayleigh(b) random variable is equivalent to the
     Weibull(2,1/b), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull skewness
     coefficient is returned.

          (%i1) load (distrib)$
          (%i2) skewness_rayleigh(b);
                                                   1
          (%o2)                skewness_weibull(2, -)
                                                   b
          (%i3) assume(b>0)$ skewness_rayleigh(b);
                                   3/2
                                %pi      3 sqrt(%pi)
                                ------ - -----------
                                  4           4
          (%o4)                 --------------------
                                         %pi 3/2
                                    (1 - ---)
                                          4


 -- Function: kurtosis_rayleigh (<b>)
     Returns the kurtosis coefficient of a Rayleigh(b) random variable,
     with b>0.

     The Rayleigh(b) random variable is equivalent to the
     Weibull(2,1/b), therefore when Maxima has not enough information
     to get the result, a noun form based on the Weibull kurtosis
     coefficient is returned.

          (%i1) load (distrib)$
          (%i2) kurtosis_rayleigh(b);
                                                   1
          (%o2)                kurtosis_weibull(2, -)
                                                   b
          (%i3) assume(b>0)$ kurtosis_rayleigh(b);
                                            2
                                       3 %pi
                                   2 - ------
                                         16
          (%o4)                    ---------- - 3
                                        %pi 2
                                   (1 - ---)
                                         4


 -- Function: random_rayleigh (<b>)
 -- Function: random_rayleigh (<b>,<n>)
     Returns a Rayleigh(b) random variate, with b>0. Calling
     `random_rayleigh' with a second argument <n>, a random sample of
     size <n> will be simulated.

     The implemented algorithm is based on the general inverse method.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_laplace (<x>,<a>,<b>)
     Returns the value at <x> of the density function of a Laplace(a,b)
     random variable, with b>0. To make use of this function, write
     first `load(distrib)'.


 -- Function: cdf_laplace (<x>,<a>,<b>)
     Returns the value at <x> of the distribution function of a
     Laplace(a,b) random variable, with b>0. To make use of this
     function, write first `load(distrib)'.


 -- Function: quantile_laplace (<q>,<a>,<b>)
     Returns the <q>-quantile of a Laplace(a,b) random variable, with
     b>0; in other words, this is the inverse of `cdf_laplace'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_laplace (<a>,<b>)
     Returns the mean of a Laplace(a,b) random variable, with b>0. To
     make use of this function, write first `load(distrib)'.


 -- Function: var_laplace (<a>,<b>)
     Returns the variance of a Laplace(a,b) random variable, with b>0.
     To make use of this function, write first `load(distrib)'.


 -- Function: std_laplace (<a>,<b>)
     Returns the standard deviation of a Laplace(a,b) random variable,
     with b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_laplace (<a>,<b>)
     Returns the skewness coefficient of a Laplace(a,b) random
     variable, with b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_laplace (<a>,<b>)
     Returns the kurtosis coefficient of a Laplace(a,b) random
     variable, with b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_laplace (<a>,<b>)
 -- Function: random_laplace (<a>,<b>,<n>)
     Returns a Laplace(a,b) random variate, with b>0. Calling
     `random_laplace' with a third argument <n>, a random sample of
     size <n> will be simulated.

     The implemented algorithm is based on the general inverse method.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_cauchy (<x>,<a>,<b>)
     Returns the value at <x> of the density function of a Cauchy(a,b)
     random variable, with b>0. To make use of this function, write
     first `load(distrib)'.


 -- Function: cdf_cauchy (<x>,<a>,<b>)
     Returns the value at <x> of the distribution function of a
     Cauchy(a,b) random variable, with b>0. To make use of this
     function, write first `load(distrib)'.


 -- Function: quantile_cauchy (<q>,<a>,<b>)
     Returns the <q>-quantile of a Cauchy(a,b) random variable, with
     b>0; in other words, this is the inverse of `cdf_cauchy'. Argument
     <q> must be an element of [0,1]. To make use of this function,
     write first `load(distrib)'.


 -- Function: random_cauchy (<a>,<b>)
 -- Function: random_cauchy (<a>,<b>,<n>)
     Returns a Cauchy(a,b) random variate, with b>0. Calling
     `random_cauchy' with a third argument <n>, a random sample of size
     <n> will be simulated.

     The implemented algorithm is based on the general inverse method.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_gumbel (<x>,<a>,<b>)
     Returns the value at <x> of the density function of a Gumbel(a,b)
     random variable, with b>0. To make use of this function, write
     first `load(distrib)'.


 -- Function: cdf_gumbel (<x>,<a>,<b>)
     Returns the value at <x> of the distribution function of a
     Gumbel(a,b) random variable, with b>0. To make use of this
     function, write first `load(distrib)'.


 -- Function: quantile_gumbel (<q>,<a>,<b>)
     Returns the <q>-quantile of a Gumbel(a,b) random variable, with
     b>0; in other words, this is the inverse of `cdf_gumbel'. Argument
     <q> must be an element of [0,1]. To make use of this function,
     write first `load(distrib)'.


 -- Function: mean_gumbel (<a>,<b>)
     Returns the mean of a Gumbel(a,b) random variable, with b>0.

          (%i1) load (distrib)$
          (%i2) assume(b>0)$  mean_gumbel(a,b);
          (%o3)                     %gamma b + a
     where symbol `%gamma' stands for the Euler-Mascheroni constant.
     See also `%gamma'.


 -- Function: var_gumbel (<a>,<b>)
     Returns the variance of a Gumbel(a,b) random variable, with b>0.
     To make use of this function, write first `load(distrib)'.


 -- Function: std_gumbel (<a>,<b>)
     Returns the standard deviation of a Gumbel(a,b) random variable,
     with b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_gumbel (<a>,<b>)
     Returns the skewness coefficient of a Gumbel(a,b) random variable,
     with b>0.

          (%i1) load (distrib)$
          (%i2) assume(b>0)$ skewness_gumbel(a,b);
                                 12 sqrt(6) zeta(3)
          (%o3)                  ------------------
                                           3
                                        %pi
          (%i4) numer:true$ skewness_gumbel(a,b);
          (%o5)                   1.139547099404649
     where `zeta' stands for the Riemann's zeta function.


 -- Function: kurtosis_gumbel (<a>,<b>)
     Returns the kurtosis coefficient of a Gumbel(a,b) random variable,
     with b>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_gumbel (<a>,<b>)
 -- Function: random_gumbel (<a>,<b>,<n>)
     Returns a Gumbel(a,b) random variate, with b>0. Calling
     `random_gumbel' with a third argument <n>, a random sample of size
     <n> will be simulated.

     The implemented algorithm is based on the general inverse method.

     To make use of this function, write first `load(distrib)'.



File: maxima.info,  Node: Functions and Variables for discrete distributions,  Prev: Functions and Variables for continuous distributions,  Up: distrib

47.3 Functions and Variables for discrete distributions
=======================================================

 -- Function: pdf_binomial (<x>,<n>,<p>)
     Returns the value at <x> of the probability function of a
     Binomial(n,p) random variable, with 0<p<1 and n a positive
     integer. To make use of this function, write first `load(distrib)'.


 -- Function: cdf_binomial (<x>,<n>,<p>)
     Returns the value at <x> of the distribution function of a
     Binomial(n,p) random variable, with 0<p<1 and n a positive integer.

     This function is numerically computed if the global variable
     `numer' equals `true',  otherwise it returns a nominal expression.

          (%i1) load (distrib)$
          (%i2) cdf_binomial(5,7,1/6);
                                                   1
          (%o2)                 cdf_binomial(5, 7, -)
                                                   6
          (%i3) cdf_binomial(5,7,1/6), numer;
          (%o3)                   .9998713991769548


 -- Function: quantile_binomial (<q>,<n>,<p>)
     Returns the <q>-quantile of a Binomial(n,p) random variable, with
     0<p<1 and n a positive integer; in other words, this is the
     inverse of `cdf_binomial'. Argument <q> must be an element of
     [0,1]. To make use of this function, write first `load(distrib)'.


 -- Function: mean_binomial (<n>,<p>)
     Returns the mean of a Binomial(n,p) random variable, with 0<p<1
     and n a positive integer. To make use of this function, write
     first `load(distrib)'.


 -- Function: var_binomial (<n>,<p>)
     Returns the variance of a Binomial(n,p) random variable, with
     0<p<1 and n a positive integer. To make use of this function,
     write first `load(distrib)'.


 -- Function: std_binomial (<n>,<p>)
     Returns the standard deviation of a Binomial(n,p) random variable,
     with 0<p<1 and n a positive integer. To make use of this function,
     write first `load(distrib)'.


 -- Function: skewness_binomial (<n>,<p>)
     Returns the skewness coefficient of a Binomial(n,p) random
     variable, with 0<p<1 and n a positive integer. To make use of this
     function, write first `load(distrib)'.


 -- Function: kurtosis_binomial (<n>,<p>)
     Returns the kurtosis coefficient of a Binomial(n,p) random
     variable, with 0<p<1 and n a positive integer. To make use of this
     function, write first `load(distrib)'.


 -- Function: random_binomial (<n>,<p>)
 -- Function: random_binomial (<n>,<p>,<m>)
     Returns a Binomial(n,p) random variate, with 0<p<1 and n a
     positive integer. Calling `random_binomial' with a third argument
     <m>, a random sample of size <m> will be simulated.

     The implemented algorithm is based on the one described in
     Kachitvichyanukul, V. and Schmeiser, B.W. (1988) <Binomial Random
     Variate Generation>. Communications of the ACM, 31, Feb., 216.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_poisson (<x>,<m>)
     Returns the value at <x> of the probability function of a
     Poisson(m) random variable, with m>0. To make use of this
     function, write first `load(distrib)'.


 -- Function: cdf_poisson (<x>,<m>)
     Returns the value at <x> of the distribution function of a
     Poisson(m) random variable, with m>0.

     This function is numerically computed if the global variable
     `numer' equals `true',  otherwise it returns a nominal expression.

          (%i1) load (distrib)$
          (%i2) cdf_poisson(3,5);
          (%o2)                   cdf_poisson(3, 5)
          (%i3) cdf_poisson(3,5), numer;
          (%o3)                   .2650259152973617


 -- Function: quantile_poisson (<q>,<m>)
     Returns the <q>-quantile of a Poisson(m) random variable, with
     m>0; in other words, this is the inverse of `cdf_poisson'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_poisson (<m>)
     Returns the mean of a Poisson(m) random variable, with  m>0. To
     make use of this function, write first `load(distrib)'.


 -- Function: var_poisson (<m>)
     Returns the variance of a Poisson(m) random variable, with  m>0.
     To make use of this function, write first `load(distrib)'.


 -- Function: std_poisson (<m>)
     Returns the standard deviation of a Poisson(m) random variable,
     with m>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_poisson (<m>)
     Returns the skewness coefficient of a Poisson(m) random variable,
     with m>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_poisson (<m>)
     Returns the kurtosis coefficient of a Poisson random variable
     Poi(m), with m>0. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_poisson (<m>)
 -- Function: random_poisson (<m>,<n>)
     Returns a Poisson(m) random variate, with m>0. Calling
     `random_poisson' with a second argument <n>, a random sample of
     size <n> will be simulated.

     The implemented algorithm is the one described in Ahrens, J.H. and
     Dieter, U. (1982) <Computer Generation of Poisson Deviates From
     Modified Normal Distributions>. ACM Trans. Math. Software, 8, 2,
     June,163-179.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_bernoulli (<x>,<p>)
     Returns the value at <x> of the probability function of a
     Bernoulli(p) random variable, with 0<p<1.

     The Bernoulli(p) random variable is equivalent to the
     Binomial(1,p), therefore when Maxima has not enough information to
     get the result, a noun form based on the binomial probability
     function is returned.

          (%i1) load (distrib)$
          (%i2) pdf_bernoulli(1,p);
          (%o2)                 pdf_binomial(1, 1, p)
          (%i3) assume(0<p,p<1)$ pdf_bernoulli(1,p);
          (%o4)                           p


 -- Function: cdf_bernoulli (<x>,<p>)
     Returns the value at <x> of the distribution function of a
     Bernoulli(p) random variable, with 0<p<1. To make use of this
     function, write first `load(distrib)'.


 -- Function: quantile_bernoulli (<q>,<p>)
     Returns the <q>-quantile of a Bernoulli(p) random variable, with
     0<p<1; in other words, this is the inverse of `cdf_bernoulli'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_bernoulli (<p>)
     Returns the mean of a Bernoulli(p) random variable, with 0<p<1.

     The Bernoulli(p) random variable is equivalent to the
     Binomial(1,p), therefore when Maxima has not enough information to
     get the result, a noun form based on the binomial mean is returned.

          (%i1) load (distrib)$
          (%i2) mean_bernoulli(p);
          (%o2)                  mean_binomial(1, p)
          (%i3) assume(0<p,p<1)$ mean_bernoulli(p);
          (%o4)                           p


 -- Function: var_bernoulli (<p>)
     Returns the variance of a Bernoulli(p) random variable, with 0<p<1.

     The Bernoulli(p) random variable is equivalent to the
     Binomial(1,p), therefore when Maxima has not enough information to
     get the result, a noun form based on the binomial variance is
     returned.

          (%i1) load (distrib)$
          (%i2) var_bernoulli(p);
          (%o2)                  var_binomial(1, p)
          (%i3) assume(0<p,p<1)$ var_bernoulli(p);
          (%o4)                       (1 - p) p


 -- Function: std_bernoulli (<p>)
     Returns the standard deviation of a Bernoulli(p) random variable,
     with 0<p<1.

     The Bernoulli(p) random variable is equivalent to the
     Binomial(1,p), therefore when Maxima has not enough information to
     get the result, a noun form based on the binomial standard
     deviation is returned.

          (%i1) load (distrib)$
          (%i2) std_bernoulli(p);
          (%o2)                  std_binomial(1, p)
          (%i3) assume(0<p,p<1)$ std_bernoulli(p);
          (%o4)                  sqrt(1 - p) sqrt(p)


 -- Function: skewness_bernoulli (<p>)
     Returns the skewness coefficient of a Bernoulli(p) random
     variable, with 0<p<1.

     The Bernoulli(p) random variable is equivalent to the
     Binomial(1,p), therefore when Maxima has not enough information to
     get the result, a noun form based on the binomial skewness
     coefficient is returned.

          (%i1) load (distrib)$
          (%i2) skewness_bernoulli(p);
          (%o2)                skewness_binomial(1, p)
          (%i3) assume(0<p,p<1)$ skewness_bernoulli(p);
                                       1 - 2 p
          (%o4)                  -------------------
                                 sqrt(1 - p) sqrt(p)


 -- Function: kurtosis_bernoulli (<p>)
     Returns the kurtosis coefficient of a Bernoulli(p) random
     variable, with 0<p<1.

     The Bernoulli(p) random variable is equivalent to the
     Binomial(1,p), therefore when Maxima has not enough information to
     get the result, a noun form based on the binomial kurtosis
     coefficient is returned.

          (%i1) load (distrib)$
          (%i2) kurtosis_bernoulli(p);
          (%o2)                kurtosis_binomial(1, p)
          (%i3) assume(0<p,p<1)$ kurtosis_bernoulli(p);
                                   1 - 6 (1 - p) p
          (%o4)                    ---------------
                                      (1 - p) p


 -- Function: random_bernoulli (<p>)
 -- Function: random_bernoulli (<p>,<n>)
     Returns a Bernoulli(p) random variate, with 0<p<1. Calling
     `random_bernoulli' with a second argument <n>, a random sample of
     size <n> will be simulated.

     This is a direct application of the `random' built-in Maxima
     function.

     See also `random'. To make use of this function, write first
     `load(distrib)'.


 -- Function: pdf_geometric (<x>,<p>)
     Returns the value at <x> of the probability function of a
     Geometric(p) random variable, with 0<p<1. To make use of this
     function, write first `load(distrib)'.


 -- Function: cdf_geometric (<x>,<p>)
     Returns the value at <x> of the distribution function of a
     Geometric(p) random variable, with 0<p<1. To make use of this
     function, write first `load(distrib)'.


 -- Function: quantile_geometric (<q>,<p>)
     Returns the <q>-quantile of a Geometric(p) random variable, with
     0<p<1; in other words, this is the inverse of `cdf_geometric'.
     Argument <q> must be an element of [0,1]. To make use of this
     function, write first `load(distrib)'.


 -- Function: mean_geometric (<p>)
     Returns the mean of a Geometric(p) random variable, with 0<p<1. To
     make use of this function, write first `load(distrib)'.


 -- Function: var_geometric (<p>)
     Returns the variance of a Geometric(p) random variable, with
     0<p<1. To make use of this function, write first `load(distrib)'.


 -- Function: std_geometric (<p>)
     Returns the standard deviation of a Geometric(p) random variable,
     with 0<p<1. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_geometric (<p>)
     Returns the skewness coefficient of a Geometric(p) random
     variable, with 0<p<1. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_geometric (<p>)
     Returns the kurtosis coefficient of a geometric random variable
     Geo(p), with 0<p<1. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_geometric (<p>)
 -- Function: random_geometric (<p>,<n>)
     Returns a Geometric(p) random variate, with 0<p<1. Calling
     `random_geometric' with a second argument <n>, a random sample of
     size <n> will be simulated.

     The algorithm is based on simulation of Bernoulli trials.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_discrete_uniform (<x>,<n>)
     Returns the value at <x> of the probability function of a Discrete
     Uniform(n) random variable, with n a strictly positive integer. To
     make use of this function, write first `load(distrib)'.


 -- Function: cdf_discrete_uniform (<x>,<n>)
     Returns the value at <x> of the distribution function of a
     Discrete Uniform(n) random variable, with n a strictly positive
     integer. To make use of this function, write first `load(distrib)'.


 -- Function: quantile_discrete_uniform (<q>,<n>)
     Returns the <q>-quantile of a Discrete Uniform(n) random variable,
     with n a strictly positive integer; in other words, this is the
     inverse of `cdf_discrete_uniform'. Argument <q> must be an element
     of [0,1]. To make use of this function, write first
     `load(distrib)'.


 -- Function: mean_discrete_uniform (<n>)
     Returns the mean of a Discrete Uniform(n) random variable, with n
     a strictly positive integer. To make use of this function, write
     first `load(distrib)'.


 -- Function: var_discrete_uniform (<n>)
     Returns the variance of a Discrete Uniform(n) random variable,
     with n a strictly positive integer. To make use of this function,
     write first `load(distrib)'.


 -- Function: std_discrete_uniform (<n>)
     Returns the standard deviation of a Discrete Uniform(n) random
     variable, with n a strictly positive integer. To make use of this
     function, write first `load(distrib)'.


 -- Function: skewness_discrete_uniform (<n>)
     Returns the skewness coefficient of a Discrete Uniform(n) random
     variable, with n a strictly positive integer. To make use of this
     function, write first `load(distrib)'.


 -- Function: kurtosis_discrete_uniform (<n>)
     Returns the kurtosis coefficient of a Discrete Uniform(n) random
     variable, with n a strictly positive integer. To make use of this
     function, write first `load(distrib)'.


 -- Function: random_discrete_uniform (<n>)
 -- Function: random_discrete_uniform (<n>,<m>)
     Returns a Discrete Uniform(n) random variate, with n a strictly
     positive integer. Calling `random_discrete_uniform' with a second
     argument <m>, a random sample of size <m> will be simulated.

     This is a direct application of the `random' built-in Maxima
     function.

     See also `random'. To make use of this function, write first
     `load(distrib)'.


 -- Function: pdf_hypergeometric (<x>,<n1>,<n2>,<n>)
     Returns the value at <x> of the probability function of a
     Hypergeometric(n1,n2,n) random variable, with <n1>, <n2> and <n>
     non negative integers and n<=n1+n2. To make use of this function,
     write first `load(distrib)'.


 -- Function: cdf_hypergeometric (<x>,<n1>,<n2>,<n>)
     Returns the value at <x> of the distribution function of a
     Hypergeometric(n1,n2,n) random variable, with <n1>, <n2> and <n>
     non negative integers and n<=n1+n2. To make use of this function,
     write first `load(distrib)'.


 -- Function: quantile_hypergeometric (<q>,<n1>,<n2>,<n>)
     Returns the <q>-quantile of a Hypergeometric(n1,n2,n) random
     variable, with <n1>, <n2> and <n> non negative integers and
     n<=n1+n2; in other words, this is the inverse of
     `cdf_hypergeometric'. Argument <q> must be an element of [0,1]. To
     make use of this function, write first `load(distrib)'.


 -- Function: mean_hypergeometric (<n1>,<n2>,<n>)
     Returns the mean of a discrete uniform random variable
     Hyp(n1,n2,n), with <n1>, <n2> and <n> non negative integers and
     n<=n1+n2. To make use of this function, write first
     `load(distrib)'.


 -- Function: var_hypergeometric (<n1>,<n2>,<n>)
     Returns the variance of a hypergeometric  random variable
     Hyp(n1,n2,n), with <n1>, <n2> and <n> non negative integers and
     n<=n1+n2. To make use of this function, write first
     `load(distrib)'.


 -- Function: std_hypergeometric (<n1>,<n2>,<n>)
     Returns the standard deviation of a Hypergeometric(n1,n2,n) random
     variable, with <n1>, <n2> and <n> non negative integers and
     n<=n1+n2. To make use of this function, write first
     `load(distrib)'.


 -- Function: skewness_hypergeometric (<n1>,<n2>,<n>)
     Returns the skewness coefficient of a Hypergeometric(n1,n2,n)
     random variable, with <n1>, <n2> and <n> non negative integers and
     n<=n1+n2. To make use of this function, write first
     `load(distrib)'.


 -- Function: kurtosis_hypergeometric (<n1>,<n2>,<n>)
     Returns the kurtosis coefficient of a Hypergeometric(n1,n2,n)
     random variable, with <n1>, <n2> and <n> non negative integers and
     n<=n1+n2. To make use of this function, write first
     `load(distrib)'.


 -- Function: random_hypergeometric (<n1>,<n2>,<n>)
 -- Function: random_hypergeometric (<n1>,<n2>,<n>,<m>)
     Returns a Hypergeometric(n1,n2,n) random variate, with <n1>, <n2>
     and <n> non negative integers and n<=n1+n2. Calling
     `random_hypergeometric' with a fourth argument <m>, a random
     sample of size <m> will be simulated.

     Algorithm described in Kachitvichyanukul, V., Schmeiser, B.W.
     (1985) <Computer generation of hypergeometric random variates.>
     Journal of Statistical Computation and Simulation 22, 127-145.

     To make use of this function, write first `load(distrib)'.


 -- Function: pdf_negative_binomial (<x>,<n>,<p>)
     Returns the value at <x> of the probability function of a Negative
     Binomial(n,p) random variable, with 0<p<1 and n a positive
     integer. To make use of this function, write first `load(distrib)'.


 -- Function: cdf_negative_binomial (<x>,<n>,<p>)
     Returns the value at <x> of the distribution function of a
     Negative Binomial(n,p) random variable, with 0<p<1 and n a
     positive integer.

     This function is numerically computed if the global variable
     `numer' equals `true',  otherwise it returns a nominal expression.

          (%i1) load (distrib)$
          (%i2) cdf_negative_binomial(3,4,1/8);
                                                       1
          (%o2)            cdf_negative_binomial(3, 4, -)
                                                       8
          (%i3) cdf_negative_binomial(3,4,1/8), numer;
          (%o3)                  .006238937377929698


 -- Function: quantile_negative_binomial (<q>,<n>,<p>)
     Returns the <q>-quantile of a Negative Binomial(n,p) random
     variable, with 0<p<1 and n a positive integer; in other words,
     this is the inverse of `cdf_negative_binomial'. Argument <q> must
     be an element of [0,1]. To make use of this function, write first
     `load(distrib)'.


 -- Function: mean_negative_binomial (<n>,<p>)
     Returns the mean of a Negative Binomial(n,p) random variable, with
     0<p<1 and n a positive integer. To make use of this function,
     write first `load(distrib)'.


 -- Function: var_negative_binomial (<n>,<p>)
     Returns the variance of a Negative Binomial(n,p) random variable,
     with 0<p<1 and n a positive integer. To make use of this function,
     write first `load(distrib)'.


 -- Function: std_negative_binomial (<n>,<p>)
     Returns the standard deviation of a Negative Binomial(n,p) random
     variable, with 0<p<1 and n a positive integer. To make use of this
     function, write first `load(distrib)'.


 -- Function: skewness_negative_binomial (<n>,<p>)
     Returns the skewness coefficient of a Negative Binomial(n,p)
     random variable, with 0<p<1 and n a positive integer. To make use
     of this function, write first `load(distrib)'.


 -- Function: kurtosis_negative_binomial (<n>,<p>)
     Returns the kurtosis coefficient of a Negative Binomial(n,p)
     random variable, with 0<p<1 and n a positive integer. To make use
     of this function, write first `load(distrib)'.


 -- Function: random_negative_binomial (<n>,<p>)
 -- Function: random_negative_binomial (<n>,<p>,<m>)
     Returns a Negative Binomial(n,p) random variate, with 0<p<1 and n
     a positive integer. Calling `random_negative_binomial' with a
     third argument <m>, a random sample of size <m> will be simulated.

     Algorithm described in Devroye, L. (1986) <Non-Uniform Random
     Variate Generation>. Springer Verlag, p. 480.

     To make use of this function, write first `load(distrib)'.



File: maxima.info,  Node: draw,  Next: dynamics,  Prev: distrib,  Up: Top

48 draw
*******

* Menu:

* Introduction to draw::
* Functions and Variables for draw::
* Functions and Variables for pictures::
* Functions and Variables for worldmap::


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

48.1 Introduction to draw
=========================

`draw' is a Maxima-Gnuplot interface.

   There are three main functions to be used at Maxima level: `draw2d',
`draw3d' and `draw'.

   Follow this link for more elaborated examples of this package:

   `http://www.telefonica.net/web2/biomates/maxima/gpdraw'

   You need Gnuplot 4.2 to run this program.

