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


File: maxima.info,  Node: Einführung in die Programmierung,  Next: Funktionen und Variablen der Programmierung,  Prev: Lisp und Maxima,  Up: Programmierung

27.2 Einführung in die Programmierung
=====================================

In Maxima können Programme geschrieben werden.  Alle Maxima-Funktionen
und Maxima-Variablen können in Programmen verwendet werden.  Maxima hat
einen Übersetzer, um Maxima-Programme in Lisp-Programme zu übersetzen,
und einen Compiler, um die übersetzten Programme zu kompilieren.  Siehe
dazu das Kapitel Übersetzer.

Maxima-Programme bestehen aus Funktionen und Makros, die im Kapitel
Funktionsdefinitionen beschrieben sind.  Die Funktionen werden aus
Ausdrücken der Form '(expr_1, expr_2, ..., expr_n)' oder
'block'-Anweisungen zusammengesetzt.  Mit der Anweisung 'local' werden
Variablen definiert, deren Werte und Eigenschaften lokal zu einem Block
sind.

Konditionale Verzweigen werden mit der Anweisung 'if' definiert und
haben die Form 'if ... then ... else'.

Maxima kennt die sehr allgemeine Anweisung 'for', um Schleifen zu
programmieren.  Schlüsselworte für die Programmierung von Schleifen sind
'while', 'unless', 'do' sowie 'thru', 'step', 'in'.

Mit der Sprunganweisung 'return' kann ein Block verlassen werden und mit
der Sprunganweisung 'go' wird innerhalb eines Blockes zu eine Marke
verzweigt.  Nicht-lokale Rücksprünge aus Funktionen werden mit den
Anweisungen 'catch' und 'throw' programmiert.

Die Anweisung 'errcatch' fängt Fehler ab, so dass die Ausführung eines
Programms nicht abgebrochen wird.  Mit der Anweisungen 'error' und
'break' wird ein Programm abgebrochen.  Im ersten Fall kann eine
Fehlermelung ausgegeben werden und das Programm kehrt zur
Maxima-Kommandozeile zurück.  Mit 'break' wird der Maxima-Debugger
gestartet.

Maxima kennt die folgenden Anweisungen und Variablen um Programme zu
definieren:

   backtrace    block        break
   catch        do           eval_when
   errcatch     error        error_size
   error_syms   errormsg     for
   go           if           local
   return       throw        unless
   while


File: maxima.info,  Node: Funktionen und Variablen der Programmierung,  Prev: Einführung in die Programmierung,  Up: Programmierung

27.3 Funktionen und Variablen der Programmierung
================================================

 -- Funktion: backtrace ()
 -- Funktion: backtrace (<n>)

     Gibt den Aufruf-Stack der Funktion zurück, die ausgeführt wird.

     Das Kommando 'backtrace()' zeigt den gesamten Stack.
     'backtrace(<n>)' zeigt die letzten <n> Funktionen einschließlich
     der Funktion, die ausgeführt wird.

     'backtrace' kann in einer Batch-Datei, die zum Beispiel mit der
     Funktion 'batch' geladen wird, in einer Funktion oder von einer
     Kommandozeile aufgerufen werden.

     Beispiele:

     'backtrace()' gibt den gesamten Stack aus.

          (%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>)' gibt die letzten <n> Funktionen aus.

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

 -- Funktion: block ([<v_1>, ..., <v_m>], <expr_1>, ..., <expr_n>)
 -- Funktion: block (<expr_1>, ..., <expr_n>)

     Mit der Anweisung 'block' werden Ausdrücke in einer lokalen
     Umgebung zusammengefasst.  'block' wertet die Argument <expr_1>,
     <expr_2>, ..., <expr_n> nacheinander aus und gibt das Ergebnis des
     letzten ausgewerteten Ausdrucks zurück.  Die Liste '[v_1, ...,
     v_m]' am Anfang der 'block'-Anweisung bezeichnet Variablen, die
     innerhalb der 'block'-Anweisung lokal sind.  Alle anderen
     Variablen, die in einem Block verwendet werden, beziehen sich auf
     globale Variablen, die auÃerhalb des Block definiert sind.  Dies
     kann ein weiterer Block oder die globale Maxima-Umgebung sein.
     'block' sichert die aktuellen Werte der Variablen <v_1>, ...,
     <v_m>.  Wird 'block' verlassen, werden diese Werte
     wiederhergestellt.

     Die Deklaration 'local(<v_1>, ..., <v_m>)' innerhalb der
     'block'-Anweisung sichert nicht nur die Werte, sondern auch die
     Eigenschaften der Variablen wie sie zum Beispiel mit den Funktionen
     'declare' oder 'depends' definiert werden.  Erhalten die mit
     'local' deklarierten Variablen innerhalb der 'block'-Anweisung
     Eigenschaften, wirken sich diese nur lokal aus.  Beim Verlassen der
     'block'-Anweisung werden die globalen Eigenschaften
     wiederhergestellt.  Siehe auch 'local'.

     Die 'block'-Anweisung kann verschachtelt werden.  Jeder Block kann
     eigene lokale Variablen definieren.  Diese sind global zu jedem
     anderen Block der sich innerhalb des Blockes befindet.  Ein
     Variable die nicht als lokal definiert ist, hat den globalen Wert
     eines umgebenden Blocks oder den Wert der globalen Maxima-Umgebung.

     Der Rückgabewert eines Blocks ist der Wert des letzten Ausdrucks
     oder der Wert, der mit den 'return'-Anweisung zurückgegeben wird.
     Mit der 'go'-Anweisung kann innerhalb eines Blocks zu einer Marke
     gesprungen werden.  Weiterhin kann mit der 'throw'-Anweisung ein
     nicht-lokaler Rücksprung zu einer entsprechenden 'catch'-Anweisung
     erfolgen.

     Blöcke erscheinen typischerweise auf der rechten Seite einer
     Funktionsdefinitionen.  Sie können aber auch an anderen Stellen
     verwendet werden.

     Beispiel:

     Das Beispiel zeigt eine einfache Implementation des
     Newton-Algorithmus.  Der Block definiert die lokalen Variablen
     'xn', 's' und <numer>.  'numer' ist eine Optionsvariable, die im
     Block einen lokalen Wert erhält.  Im Block ist das Tag 'loop'
     definiert.  Zu diesem Tag wird mit der Anweisung 'go(loop)'
     gesprungen.  Der Block und damit die Funktion wird mit der
     Anweisung 'return(xn)' verlassen.  Der Wert der Variablen 'xn' ist
     das Ergebnis der Funktion 'newton'.

          newton(exp,var,x0,eps):=
             block([xn,s,numer],
                numer:true,
                s:diff(exp,var),
                xn:x0,
             loop,
                if abs(subst(xn,var,exp))<eps then return(xn),
                xn:xn-subst(xn,var,exp)/subst(xn,var,s),
                go(loop) )$

 -- Funktion: break (<expr_1>, ..., <expr_n>)

     Wertet die Ausdrücke <expr_1>, ..., <expr_n> aus, zeigt die
     Ergebnisse an und führt dann eine Unterbrechung aus.  Mit dem
     Kommando 'exit;' wird Maxima fortgesetzt.  Siehe das Kapitel

     Beispiel:

     Der Variablen 'a' wird der Wert 2 zugewiesen.  Dann wird die
     Unterbrechung ausgeführt.  Mit dem Kommando 'exit;' wird Maxima
     fortgesetzt.

          (%i1) break(a:2);
          2

          Entering a Maxima break point. Type 'exit;' to resume.
          _a;
          2
          _exit;
          (%o1)                           2

 -- Funktion: catch (<expr_1>, ..., <expr_n>)

     Wertet die Ausdrücke <expr_1>, ..., <expr_n> nacheinander aus.
     Wertet irgendeiner der Ausdrücke zu 'throw(arg)' aus, dann ist das
     Ergebnis der Wert von 'throw(arg)' und es werden keine weiteren
     Ausdrücke ausgewertet.  Diese nicht-lokale Rückgabe kehrt zu dem
     nächsten 'catch' in einer beliebigen Verschachtelungstiefe zurück.
     Wird kein 'catch' gefunden gibt Maxima eine Fehlermeldung aus.

     Führt die Auswertung der Argumente nicht zu einem 'throw', dann ist
     die Rückgabe das Ergebnis des letzten Ausdrucks 'expr_n'.

     Beispiel:

     Die Funktion 'g' gibt eine Liste mit den Werten des
     Lambda-Ausdrucks zurück.  Tritt ein negativer Wert auf, bricht die
     Funktion ab, in diesem Beispiel mit 'throw(-3)'.

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

 -- Spezieller Operator: do

     Die 'do'-Anweisung erlaubt die Definition von Iterationen.
     Aufgrund der großen Allgemeinheit der 'do'-Anweisung folgt die
     Beschreibung in zwei Teilen.  Zunächst werden die bekannteren
     Formen beschrieben, wie sie auch in anderen Programmiersprachen
     vorhanden sind.  Dann folgen die weiteren Möglichkeiten.

     Es gibt drei Varianten der 'do'-Anweisung, die sich nur durch die
     Abbruchbedingung voneinander unterscheiden.  Diese sind:

          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>

     <initial_value>, <increment>, <limit> und <body> können beliebige
     Ausdrücke sein.  Ist das Inkrement 1, kann 'step' entfallen.

     Die Ausführung der 'do'-Anweisung beginnt mit der Zuweisung von
     'initial_value' an die Kontrollvariable <variable>.  Dann folgen
     die Schritte: (1) Hat die Kontrollvariable den Wert einer
     'thru'-Anweisung überschritten oder hat die Bedingung einer
     'unless'-Anweisung den Wert 'true' oder hat die Bedingung einer
     'while'-Anweisung den Wert 'false', dann endet die Ausführung der
     'do'-Anweisung.  (2) Die Ausdrücke in <body> werden ausgewertet.
     (3) Das Inkrement wird zu der Kontrollvariablen hinzuaddiert.  Die
     Schritte (1) bis (3) werden solange ausgeführt, bis eine der
     Bedingungen für die Beendigung der 'do'-Anweisung zutrifft.

     Im Allgemeinen ist der 'thru'-Test erfüllt, wenn die
     Kontrollvariable größer als <limit> ist, falls <increment> nicht
     negativ ist.  Oder wenn die Kontrollvariable kleiner als 'limit'
     ist, für den Fall, dass das Inkrement negativ ist.  <increment> und
     <limit> können Ausdrücke sein, sofern die Bedingung zum Abbruch der
     'do'-Anweisung ausgewertet werden kann.  Soll 'increment' zu einem
     negativen Wert auswerten und kann dies jedoch bei Eintritt in die
     Schleife von Maxima nicht festgestellt werden, so wird das
     Inkrement als positiv angenommen.  Dies kann dazu führen, dass die
     Schleife nicht korrekt ausgeführt wird.

     <limit>, <increment> und die Bedingung für den Abbruch der Schleife
     werden für jeden Durchgang durch die Schleife ausgewertet.  Ändern
     diese ihren Wert nicht, kann es daher effizienter sein, die Werte
     diese Ausdrücke vor Eintritt in die Schleife zu berechnen und in
     Variablen abzulegen, die anstatt der Ausdrücke in der Schleife
     verwendet werden.

     Die 'do'-Anweisung hat den Rückgabewert 'done'.  Um einen anderen
     Wert zurückzugeben, kann die 'return'-Anweisung innerhalb von
     'body' genutzt werden.  Befindet sich die 'do'-Anweisung innerhalb
     eines Blockes, so wird dieser nicht mit einer 'return'-Anweisung
     verlassen, die sich innerhalb der 'do'-Anweisung befindet.  Auch
     kann nicht mit der 'go'-Anweisung in einen umgebenen Block
     gesprungen werden.

     Die Kontrollvariable ist immer lokal zur 'do'-Anweisung.  Nach dem
     Verlassen der 'do'-Anweisung kann auf die Kontrollvariable nicht
     mehr zugegriffen werden.

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

                                        a = 4

                                       a = 11

                                       a = 18

                                       a = 25

     Die Bedingung 'while i <= 10' ist äquivalent zu den Bedingungen
     'unless i > 10' und 'thru 10' ist.

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

     Berechne die ersten acht Terme einer Taylorreihe in einer
     'do'-Schleife.

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

     In diesem Beispiel wird die negative Wurzel von 10 mit einem
     Newton-Raphson-Algorithmus berechnet.

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

     Anstatt eines festes Inkrements mit 'step' kann die
     Kontrollvariable auch mit 'next' für jeden Schleifendurchgang
     berechnet werden.

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

                                      count = 6

                                     count = 18

     Anstatt mit der Syntax 'for <variable>: <value> ...' kann die
     Kontrollvariable auch mit 'for <variable> from <value> ...do...'
     initialisiert werden.  Wird auch 'from <value>' fortgelassen, wird
     die Kontrollvariable mit dem Wert 1 initialisiert.

     Manchmal kann es von Interesse sein, in einer Schleife keine
     Kontrollvariable zu nutzen.  In diesem Fall genügt es allein die
     Bedingung für den Abbruch der Schleife anzugeben.  Im folgenden
     wird die Wurzel aus 5 mit dem Heron-Verfahren bestimmt.

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

     Auch die Abbruchbedingung kann fortgelassen werden.  Wird allein
     'do <body>' angegeben, wird die Schleife unendlich oft ausgeführt.
     Die Schleife kann mit der 'return'-Anweisung verlassen werden.  Das
     folgende Beispiel zeigt eine Implementierung des
     Newton-Algorithmus.

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

     Eine weitere Syntax ist die folgende:

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

     Die Elemente der Liste <list> können beliebige Ausdrücke sein, die
     nacheinander der Kontrollvariablen zugewiesen werden.  Die Schleife
     bricht ab, wenn die optionale Abbruchbedingung 'end_test' zutrifft,
     wenn die Liste <list> keine weiteren Elemente enthält oder wenn die
     Schleife zum Beispiel mit der Funktion 'return' verlassen wird.

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

 -- Funktion: eval_when (<keyword>, <expr_1>, ..., <expr_n>)
 -- Funktion: eval_when ([<keyword_1>, <keyword_2>, ...], <expr_1>, ...,
          <expr_n>)

     Ein Ausdruck mit der Funktion 'eval_when' wird an oberster Stelle
     in einer Datei definiert und erlaubt die bedingte Auswertung von
     Ausdrücken beim Laden, Übersetzen oder Kompilieren einer Datei.
     Das Argument <keyword> ist eines der Schlüsselworte 'batch',
     'translate', 'compile' oder 'loadfile'.  Das erste Argument kann
     ein einzelnes Schlüsselwort oder ein Liste mit mehreren
     Schlüsselworten sein.  Trifft die mit dem Schlüsselwort angegebene
     Bedingung zu, wird eine oder mehrere der folgenden Aktionen
     ausgeführt:

     'batch'
          Wird die Datei mit einer der Funktionen 'load', 'batch',
          'batchload' oder 'demo' geladen und ist 'batch' in der Liste
          der Schlüsselworte enthalten, dann werden die Ausdrücke
          <expr1>, ..., <expr_n> genau einmal beim Laden der Datei
          ausgewertet.  Die Rückgabe der Funktion 'eval_when' ist ein
          Ausdruck 'evaluated_when(<result)>', wobei <result> das
          Ergebnis der Auswertung ist.  Ist das Schlüsselwort 'batch'
          nicht vorhanden, ist die Rückgabe das Symbol
          'not_evaluated_when'.

     'translate'
          Wird die Datei mit dem Kommando 'translate_file' oder
          'compile_file' geladen und ist 'translate' unter den
          Schlüsselworten, dann werden die Ausdrücke <expr_1>, ...,
          <expr_n> sofort ausgewertet.  Seiteneffekte wie Zuweisungen
          von Werten an Optionsvariablen oder Deklarationen sind für die
          folgende Übersetzung der Datei nach Lisp wirksam.  Die
          Ausdrücke sind jedoch nicht Teil des übersetzten Programms.

     'loadfile'
          Wird die Datei mit dem Kommando 'translate_file' oder dem
          Kommando 'compile_file' geladen und ist 'loadfile' unter den
          Schlüsselworten, dann werden die Ausdrücke <expr_1>, ...,
          <expr_n> nach Lisp übersetzt und als Block der Form '(PROGN
          EXPR_1 ... EXPR_N)' in das Lisp Programm eingesetzt.  Hier
          sind die Anweisungen <EXPR_I> die nach Lisp übersetzten
          Maxima-Ausdrücke <expr_i>.

     'compile'
          Wird die Datei mit dem Kommando 'translate_file' oder
          'compile_file' geladen und ist 'compile' unter den
          Schlüsselworten, dann werden die Ausdrücke <expr_1>, ...,
          <expr_n> nach Lisp übersetzt und als eine Lisp-Anweisung in
          das Lisp-Programm eingesetzt, die die Form '(EVAL-WHEN
          (:COMPILE-TOPLEVEL) (EXPR_1 ... EXPR_N))' hat.  Das
          Schlüsselwort 'compile' kann nicht mit dem Schlüsselwort
          'loadfile' in einem 'eval_when'-Ausdruck kombiniert werden.
          In diesem Fall wird das Schlüsselwort 'compile' ignoriert.

     Beispiele:

     Für die folgende Beispiele ist eine Datei mit den Namen
     'eval_when.mac' definiert, die verschiedene 'eval_when'-Anweisungen
     enthält.

          (%i1) file: file_search("eval_when.mac");
          (%o1)        /home/dieter/.maxima/eval_when.mac
          (%i2) printfile(file);

          eval_when(batch,     print("called in mode BATCH"));
          eval_when(loadfile,  print("called in mode LOADFILE"));
          eval_when(compile,   print("called in mode COMPILE"));
          eval_when(translate, print("called in mode TRANSLATE"));

          (%o2)        /home/dieter/.maxima/eval_when.mac

     Die Datei wird mit dem Kommando 'load' geladen.  Die Anweisung mit
     dem Schlüsselwort 'batch' wird beim Laden einmal ausgeführt.

          (%i1) file: file_search("eval_when.mac");
          (%o1)        /home/dieter/.maxima/eval_when.mac
          (%i2) load(file);
          called in mode BATCH
          (%o2)        /home/dieter/.maxima/eval_when.mac

     In diesem Fall wird die Datei mit dem Befehl 'batch' geladen.  Die
     Anweisung mit dem Schlüsselwort 'batch' wird einmal ausgeführt.
     Die anderen 'eval_when'-Anweisungen werten jeweils zum Ergebnis
     'not_evaluated_when' aus.

          (%i3) batch(file);

          read and interpret file: /home/dieter/.maxima/eval_when.mac
          (%i4)     eval_when(batch, print(called in mode BATCH))
          called in mode BATCH
          (%o4)         evaluated_when(called in mode BATCH)
          (%i5)  eval_when(loadfile, print(called in mode LOADFILE))
          (%o5)                  not_evaluated_when
          (%i6)   eval_when(compile, print(called in mode COMPILE))
          (%o6)                  not_evaluated_when
          (%i7) eval_when(translate, print(called in mode TRANSLATE))
          (%o7)                  not_evaluated_when
          (%o7)        /home/dieter/.maxima/eval_when.mac

     Jetzt wird die Datei mit dem Kommando 'translate_file' geladen und
     nach Lisp übersetzt.  Der Ausdruck mit dem Schlüsselwort
     'translate' wird sofort ausgewertet.  Das übersetzte Programm wird
     in die Ausgabedatei 'eval_when.LISP' geschrieben.  Die
     'eval_when'-Anweisung zum Schlüsselwort wird nicht ausgewertet.

          (%i1) file: file_search("eval_when.mac");
          (%o1)        /home/dieter/.maxima/eval_when.mac
          (%i2) translate_file(file);
          translator: begin translating /home/dieter/.maxima/eval_when.mac.
          called in mode TRANSLATE
          (%o2) [/home/dieter/.maxima/eval_when.mac,
          /home/dieter/.maxima/eval_when.LISP,
          /home/dieter/.maxima/eval_when.UNLISP]

     Dies ist der Inhalt der Ausgabedatei 'eval_when.LISP'.  Die
     Ausgabedatei enthält eine 'PROGN'-Anweisung mit dem Ausdruck
     '($print '"called in mode LOADFILE")' für den 'eval_when'-Ausdruck
     zum Schlüsselwort 'loadfile' sowie eine 'EVAL-WHEN'-Anweisung mit
     dem Ausdruck '($print '"called in mode COMPILE")' für den
     'eval_when'-Ausdruck mit dem Schlüsselwort 'compile'.

     ;;; -*- Mode: Lisp; package:maxima; syntax:common-lisp ;Base: 10 -*- ;;;
     ;;; Translated on: 2011-10-02 13:35:37+02:00
     ;;; Maxima version: 5.25post
     ;;; Lisp implementation: SBCL
     ;;; Lisp version: 1.0.45
     (in-package :maxima)

     [...]

     nil
     (progn ($print '"called in mode LOADFILE"))
     (eval-when (:compile-toplevel) ($print '"called in mode COMPILE"))
     nil

 -- Funktion: errcatch (<expr_1>, ..., <expr_n>)

     Wertet die Ausdrücke <expr_1>, ..., <expr_n> nacheinander aus und
     gibt das Ergebnis des letzten Ausdrucks als eine Liste '[<expr_n>]'
     zurück, wenn kein Fehler bei der Auswertung auftritt.  Tritt ein
     Fehler bei der Auswertung eines der Ausdrücke auf, ist die Rückgabe
     eine leere Liste '[]'.

     'errcatch' ist nützlich in Batch-Dateien.  Mit 'errcatch' kann ein
     möglicher Fehler abgefangen werden, ohne das die Verarbeitung der
     Batch-Datei abbricht.

     Beispiele:

          (%i1) errcatch(x:2,1/x);
                                          1
          (%o1)                          [-]
                                          2
          (%i2) errcatch(x:0,1/x);

          Division by 0
          (%o2)                          []

 -- Funktion: error (<expr_1>, ..., <expr_n>)
 -- Systemvariable: error

     Wertet die Ausdrücke <expr_1>, ..., <expr_n> aus, gibt diese auf
     der Konsole aus und generiert einen Fehler, der zur obersten Ebene
     von Maxima führt oder zu dem nächsten 'errcatch'.

     Der Systemvariablen 'error' wird eine Liste zugewiesen, die eine
     Beschreibung des Fehlers enthält.  Das erste Element der Liste ist
     eine Zeichenkette und die weiteren Elemente enthalten die Argumente
     die keine Zeichenkette sind.

     'errormsg()' formatiert und gibt die Fehlermeldung in 'error' aus.
     Damit wird die letzte Fehlermeldung erneut ausgegeben.

     Beispiel:

          (%i1) f(x):= if x=0 then
                          error("Division durch", x, "ist nicht gestattet.")
                       else 1/x$
          (%i2) f(0);

          Division durch 0 ist nicht gestattet.
          #0: f(x=0)
           -- an error. To debug this try: debugmode(true);
          (%i3) errormsg();

          Division durch 0 ist nicht gestattet.
          (%o3)                         done
          (%i4) error;
          (%o4)      [Division durch ~M ist nicht gestattet., 0]

 -- Optionsvariable: error_size
     Standardwert: 10

     'error_size' kontrolliert die Ausgabe eines Ausdrucks der zu einem
     Fehler geführt hat.  Ist der Ausdruck größer als 'error_size' wird
     der Ausdruck bei der Ausgabe einer Fehlermeldung durch ein Symbol
     ersetzt und dem Symbol wird der Ausdruck zugewiesen.  Die Symbole
     werden aus der Liste 'error_syms' ausgewählt.

     Ist der Ausdruck kleiner als 'error_size' wird dieser mit der
     Fehlermeldung ausgegeben.

     Siehe auch 'error' und 'error_syms'.

     Beispiel:

     Die Größe des Ausdrucks 'U' ist 24.

          (%i1) U: (C^D^E + B + A)/(cos(X-1) + 1)$

          (%i2) error_size: 20$

          (%i3) error ("Example expression is", U);

          Example expression is errexp1
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i4) errexp1;
                                      E
                                     D
                                    C   + B + A
          (%o4)                    --------------
                                   cos(X - 1) + 1
          (%i5) error_size: 30$

          (%i6) error ("Example expression is", U);

                                   E
                                  D
                                 C   + B + A
          Example expression is --------------
                                cos(X - 1) + 1
           -- an error.  Quitting.  To debug this try debugmode(true);

 -- Optionsvariable: error_syms
     Standardwert: '[errexp1, errexp2, errexp3]'

     In Fehlermeldungen werden Ausdrücke, die größer als 'error_size'
     sind, durch Symbole ersetzt, denen der Ausdruck zugewiesen wird.
     Die Symbole werden nacheinander der Liste 'error_syms' entnommen.

     Sind keine Symbole mehr vorhanden, werden automatisch neue Symbole
     mit 'concat('errexp, <n>)' gebildet.

     Siehe auch 'error' und 'error_size'.

 -- Funktion: errormsg ()

     Gibt die letzte Fehlermeldung erneut aus.  Die Fehlermeldung ist in
     der Systemvariablen 'errormsg' enthalten.  Die Funktion 'errormsg'
     formatiert diese und gibt sie aus.

 -- Optionsvariable: errormsg
     Standardwert: 'true'

     Hat die Optionsvariable 'errormsg' den 'false' wird die Ausgabe von
     Fehlermeldungen unterdrückt.

     Der Optionsvariablen 'errormsg' kann in einem Block kein lokaler
     Wert zugewiesen werden.  Der globale Wert von 'errormsg' ist stets
     präsent.

     Beispiele:

          (%i1) errormsg;
          (%o1)                                true
          (%i2) sin(a,b);
          Wrong number of arguments to sin
           -- an error. To debug this try: debugmode(true);
          (%i3) errormsg:false;
          (%o3)                                false
          (%i4) sin(a,b);

           -- an error. To debug this try: debugmode(true);

     Der Optionsvariablen 'errormsg' kann in einem Block kein lokaler
     Wert zugewiesen werden.

          (%i1) f(bool):=block([errormsg:bool],
                               print ("value of errormsg is",errormsg))$
          (%i2) errormsg:true;
          (%o2)                                true
          (%i3) f(false);
          value of errormsg is true
          (%o3)                                true
          (%i4) errormsg:false;
          (%o4)                                false
          (%i5) f(true);
          value of errormsg is false
          (%o5)                                false

 -- Spezieller Operator: for

     Anweisung für Interationen.  Siehe die 'do'-Anweisung für eine
     Beschreibung der Iterationsmöglichkeiten von Maxima.

 -- Funktion: go (<tag>)

     Erlaubt einen Sprung innerhalb eines Blocks zu einer Marke mit dem
     Namen 'tag'.  Um eine Anweisung mit einer Sprungmarke zu versehen,
     wird der Anweisung die Marke vorangestellt.  Ein Beispiel ist:

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

     Das Argument der Funktion 'go' muss der Name einer Marke sein, die
     in demselben Block erscheint.  Es ist nicht möglich in einen
     anderen Block zu springen.

 -- Spezieller Operator: if

     Ist die bedingte Anweisung.  Verschiedene Formen einer bedingten
     Anweisung sind möglich.

     'if <cond_1> then <expr_1> else <expr_0>' wertet zu <expr_1> aus,
     wenn die Bedingung <cond_1> den Wert 'true' hat.  Ansonsten wertet
     der Ausdruck zu <expr_0> aus.

     Die zusammengesetzte bedingte Anweisung 'if <cond_1> then <expr_1>
     elseif <cond_2> then <expr_2> elseif ... else <expr_0>' wertet zu
     <expr_k> aus, wenn die Bedingung <cond_k> den Wert 'true' hat und
     alle vorhergehenden Bedingungen den Wert 'false' haben.  Trifft
     keine der Bedingungen zu, wertet der Ausdruck zu <expr_0> aus.

     Fehlt die Anweisung 'else', wird diese zu 'else false' angenommen.
     'if <cond_1> then <expr_1>' ist daher äquivalent zu 'if <cond_1>
     then <expr_1> else false' und 'if <cond_1> then <expr_1> elseif ...
     elseif <cond_n> then <expr_n>' ist äquivalent zu 'if <cond_1> then
     <expr_1> elseif ... elseif <cond_n> then <expr_n> else false'.

     Die Anweisungen <expr_0>, ..., <expr_n> können beliebige
     Maxima-Ausdrücke einschließlich weiterer 'if'-Anweisungen sein.
     Die Anweisungen werden nicht vereinfacht oder ausgewertet, solange
     die dazugehörende Bedingung nicht das Ergebnis 'true' hat.

     Die Bedingungen <cond_1>, ..., <cond_n> sind Ausdrücke, die zu
     'true' oder 'false' ausgewertet werden können.  Kann eine Bedingung
     nicht zu 'true' oder 'false' ausgewertet werden, hängt die Reaktion
     von der Optionsvariablen 'prederror' ab.  Hat 'prederror' den Wert
     'true', dann meldet Maxima einen Fehler, wenn eine Bedingung nicht
     zu 'true' oder 'false' ausgewertet werden kann.  Ansonsten werden
     Bedingungen akzeptiert, die nicht zu 'true' oder 'false'
     ausgewertet werden können und das Ergebnis ist ein bedingter
     Ausdruck.

     Die Bedingungen können die folgenden Operatoren enthalten:

          Operation              Symbol      Typ

          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

 -- Funktion: local (<v_1>, ..., <v_n>)

     Speichert alle Eigenschaften der Symbole <v_1>, ..., <v_n>,
     entfernt die Eigenschaften und stellt die abgespeicherten
     Eigenschaften nach dem Austritt aus einem Block oder einem
     zusammengesetzten Ausdruck in dem 'local' auftritt wieder her.

     Einige Deklarationen sind als Eigenschaft eines Symbols
     implementiert.  Dazu gehören Deklarationen mit ':=', 'array',
     'dependencies', 'atvalue', 'matchdeclare', 'atomgrad', 'constant',
     'nonscalar' oder 'assume'.  Der Effekt von 'local' ist, dass solche
     Deklarationen nur lokal in dem Block wirksam sind.

     'local' kann nur in 'block'-Anweisungen oder in einer
     Funktionsdefinition oder in einem Lambda-Ausdruck verwendet werden.
     Weiterhin darf 'local' jeweils nur einmal auftreten.

     'local' wertet die Argumente aus.  'local' hat die Rückgabe 'done'.

     Beispiel:

     Eine lokale Funktionsdefinition.

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

 -- Funktion: return (<value>)

     Die 'return'-Anweisung wird in einem Block verwendet, um den Block
     mit dem Ergebnis <value> zu verlassen.  Siehe 'block' für mehr
     Informationen.

 -- Funktion: throw (<expr>)

     Wertet den Ausdruck <expr> aus und generiert eine Ausnahme mit dem
     Ergebnis der Auswertung, die von der letzten 'catch'-Anweisung
     behandelt wird.

 -- Spezieller Operator: while
 -- Spezieller Operator: unless

     Siehe den Operator 'do'.


File: maxima.info,  Node: Übersetzer,  Next: Fehlersuche,  Prev: Programmierung,  Up: Top

28 Übersetzer
*************

* Menu:

* Einführung in den Übersetzer::
* Funktionen und Variablen des Übersetzers::


File: maxima.info,  Node: Einführung in den Übersetzer,  Next: Funktionen und Variablen des Übersetzers,  Prev: Übersetzer,  Up: Übersetzer

28.1 Einführung in den Übersetzer
=================================


File: maxima.info,  Node: Funktionen und Variablen des Übersetzers,  Prev: Einführung in den Übersetzer,  Up: Übersetzer

28.2 Funktionen und Variablen des Übersetzers
=============================================

 -- Funktion: compfile (<filename>, <f_1>, ..., <f_n>)
 -- Funktion: compfile (<filename>, functions)
 -- Funktion: compfile (<filename>, all)

     Übersetzt Maxima-Funktionen nach Lisp und schreibt den übersetzten
     Code in die Datei <filename>.  Mit dem Kommando
     'compfile(<filename> <f_1>, ..., <f_n>)' werden die als Argument
     angegebenen Funktionen <f_1>, ..., <f_n> übersetzt.  Die Kommandos
     'compfile(<filename>, functions)' oder 'compfile(<filename>, all)'
     übersetzen dagegen alle vom Nutzer definierten Funktionen.

     Die Lisp-Übersetzungen werden nicht ausgewertet.  Auch wird die
     Ausgabedatei nicht kompiliert.  'translate' generiert und wertet
     Lisp-Übersetzungen aus.  Die Funktion 'compile_file' übersetzt
     Maxima nach Lisp und führt dann den Lisp-Compiler aus.

     Siehe auch die Funktionen 'translate', 'translate_file' und
     'compile_file'.

 -- Funktion: compile (<f_1>, ..., <f_n>)
 -- Funktion: compile (functions)
 -- Funktion: compile (all)

     Übersetzt die Maxima-Funktionen <f_1>, ..., <f_n> nach Lisp, wertet
     die Lisp-Übersetzungen aus und ruft den Lisp-Compiler für jede
     übersetzte Funktion auf.  'compile' gibt eine Liste mit den Namen
     der kompilierten Funktionen zurück.

     'compile(all)' oder 'compile(funtions)' kompiliert alle
     nutzerdefinierten Funktionen.

     'compile' wertet die Argumente nicht aus.  Der Quote-Quote-Operator
     '''' erzwingt die Auswertung.

 -- Funktion: compile_file (<filename>)
 -- Funktion: compile_file (<filename>, <compiled_filename>)
 -- Funktion: compile_file (<filename>, <compiled_filename>,
          <lisp_filename>)

     Übersetzt die Maxima-Datei <filename> nach Lisp, ruft den
     Lisp-Compiler auf und lädt falls erfolgreich den kompilierten Code
     in Maxima.

     'compile_file' gibt eine Liste mit den Namen von vier Dateien
     zurück: die ursprüngliche Maxima-Datei, die Lisp-Übersetzung, eine
     Datei mit Notizen zur Übersetzungen und eine Datei mit dem
     kompilierten Code.  Schlägt die Kompilierung fehlt, ist der vierte
     Eintrag 'false'.

     Einige Deklarationen und Definitionen sind bereits vorhanden,
     nachdem der Lisp-Code kompiliert ist und ohne das dieser geladen
     wurde.  Dies schließt Funktionsdefinitionen mit dem Operator ':=',
     Makros definiert mit dem Operator '::=' sowie Definitionen der
     folgenden Funktionen 'alias', 'declare', 'define_variable',
     'mode_declare', 'infix', 'matchfix', 'nofix', 'postfix', 'prefix'
     und 'compfile' ein.

     Zuweisungen und Funktionsaufrufe werden nicht ausgwertet bevor der
     komplierte Code geladen wird.  Im besonderen haben Zuweisungen an
     die Übersetzungsschalter wie 'tr_numer' und andere, die in der
     Maxima-Datei aufgeführt sind, keinen Effekt auf die Übersetzung.

     'compile_file' kann Fehler oder Warnungen ausgegeben und 'false'
     zurückgegeben, obwohl die Kompilierung erfolgreich ist.  Dies ist
     ein Programmfehler

     Die Datei <filename> darf keine ':lisp'-Anweisungen enthalten.

     'compile_file' wertet die Argumente aus.

 -- Funktion: declare_translated (<f_1>, <f_2>, ...)

     Bei der Übersetzung einer Datei von Maxima-Code nach Lisp-Code ist
     es für den Übersetzer wichtig zu wissen, welche Funktionen der
     Datei bereits übersetzte oder kompilierte Funktionen sind und
     welche Funktionen Maxima-Funktionen oder undefiniert sind.  Mit der
     Deklaration 'declare_translated' am Anfang der zu übersetzenden
     Datei wird dem Übersetzer mitgeteilt, dass die als Argumente
     aufgeführten Funktionen <f_1>, <f_2>, ... zur Laufzeit des
     Programms eine Lisp-Funktion repräsentieren.  Fehlt dem Übersetzer
     diese Information wird das Kommando '(MFUNCTION-CALL fn arg1 arg2
     ...)' generiert.

 -- Optionsvariable: mode_checkp
     Standardwert: 'true'

     Hat die Optionsvariable 'mode_checkp' den Wert 'true' und wird mit
     'mode_declare' für eine Variable, die bereits einen Wert hat, ein
     Typ festgelegt, dann prüft Maxima, ob der vorgesehene Typ zum
     vorliegenden Wert passt.

     Beispiel:

     Im folgenden hat die Variable <n> den Wert 2.0.  Wird <n> mit
     'mode_declare' als eine ganze Zahl definiert, gibt Maxima eine
     Warnung aus, wenn 'mode_checkp' den Wert 'true' hat.

          (%i1) n: 2.0;
          (%o1)                          2.0
          (%i2) mode_checkp:true;
          (%o2)                         true
          (%i3) mode_declare(n,fixnum);
          warning: n was declared with mode fixnum, but it has value: 2.0
          (%o3)                          [n]
          (%i4) mode_checkp:false;
          (%o4)                         false
          (%i5) mode_declare(n,fixnum);
          (%o5)                          [n]

 -- Optionsvariable: mode_check_errorp
     Standardwert: 'false'

     Hat 'mode_check_errorp' den Wert 'true', bricht 'mode_declare' mit
     einer Fehlermeldung ab, wenn für eine Variable die bereits einen
     Wert hat, mit 'mode_declare' ein verschiedener Typ deklariert
     werden soll.  Damit diese Optionsvariable wirksam ist, muss
     'mode_checkp' den Wert 'true' haben.  Siehe 'mode_checkp'.

          (%i1) n: 2.0;
          (%o1)                          2.0
          (%i2) mode_checkp:true;
          (%o2)                         true
          (%i3) mode_check_errorp:true;
          (%o3)                         true
          (%i4) mode_declare(n,fixnum);

          Error: n was declared mode fixnum, has value: 2.0
           -- an error. To debug this try: debugmode(true);

 -- Optionsvariable: mode_check_warnp
     Standardwert: 'true'

     Hat 'mode_check_warnp' den Wert 'true', gibt 'mode_declare' eine
     Warnung aus, wenn für eine Variable die bereits einen Wert hat, mit
     'mode_declare' ein verschiedener Typ deklariert werden soll.  Damit
     diese Optionsvariable wirksam ist, muss 'mode_checkp' den Wert
     'true' haben.  Siehe 'mode_checkp' und 'mode_check_errorp'.

 -- Funktion: mode_declare (<y_1>, <mode_1>, ..., <y_n>, <mode_n>)

     'mode_declare' deklariert den Typ von Variablen und Funktionen für
     den Übersetzer und den Kompilierer.  Typischerweise wird
     'mode_declare' am Anfang einer Funktion oder einer Datei mit
     Maxima-Code ausgeführt.

     Die Argumente werden paarweise angegeben und bezeichnen jeweils den
     Namen einer Variablen sowie deren Typ.  Folgende Typen können die
     Variablen erhalten: 'boolean', 'fixnum', 'number', 'rational' oder
     'float'.  Anstatt dem Namen einer Variablen kann auch eine Liste
     mit den Namen von Variablen angegeben werden.  In diesem Fall
     erhalten alle Variablen der Liste den angegebenen Typ.

     Ein Array sollte bereits bei seiner Deklaration einen Typ für die
     Elemente erhalten.  Haben alle Elemente des Arrays einen Wert
     sollte das Array mit der Option 'complete' deklariert werden, zum
     Beispiel 'array(a, complete, dim1, dim2, ...)'.  Sind die Elemente
     des Arrays ganze Zahlen oder Gleitkommazahlen sollte der Typ als
     'fixnum' oder 'flonum' deklariert werden.

     Mit der Funktion 'mode_declare' kann dann der Typ des Arrays für
     den Übersetzer oder Kompilierer festgelegt werden.  Ein Array der
     Größe 10 'x' 10 mit Gleitkommazahlen erhält die Deklaration
     'mode_declare(completearray(a[10, 10], float)'.

     Der Typ von Funktionen wird mit dem Argument 'function(f_1, f2,
     ...)' deklariert.  Hier sind 'f_1', 'f_2', ... die Funktionen.  Mit
     'mode_declare([function (f_1, f_2, ...)], fixnum)' werden die
     Rückgabewerte der Funktionen 'f_1', 'f_2', ... als ganze Zahlen
     definiert.

     'modedeclare' ist ein Alias-Name der Funktion 'mode_declare'.

 -- Funktion: mode_identity (<mode>, <expr>)

     Mit der Funktion 'mode_identity' wird der Typ <mode> für das
     Ergebnis des Ausdrucks <expr> festgelegt.  Hat das Ergebnis einen
     anderen Typ wird in Abhängigkeit von den Werten der
     Optionsvariablen 'mode_checkp', 'mode_check_warnp' und
     'mode_check_errorp' eine Warnung ausgegeben oder das Programm
     abgebrochen.

     Beispiel:

          (%i1) mode_identity(flonum, sin(1.0));
          (%o1)                   .8414709848078965
          (%i2) mode_identity(integer, sin(1.0));
          warning: sin(1.0) was declared with mode fixnum
                                      , but it has value: .8414709848078965
          (%o2)                   .8414709848078965
          (%i3) mode_identity(integer, sin(a));
          warning: sin(a) was declared with mode fixnum, but it has value:
                                                                     sin(a)
          (%o3)                        sin(a)

 -- Optionsvariable: savedef
     Standardwert: 'true'

     Hat 'savedef' den Wert 'true', wird die Maxima-Definition einer
     Funktion nicht gelöscht, wenn die Funktion übersetzt wird.  Damit
     kann die Definition der Funktion weiterhin mit 'dispfun' angzeigt
     werden.

     Hat 'savedef' den Wert 'false' wird die Maxima-Definition der
     Funktion gelöscht, wenn die Funktion übersetzt wird.

     Beispiele:

     'savedef' hat den Wert 'true'.  Die Funktion 'f' kann auch nach der
     Übersetzung angzeigt werden und ist in der Liste 'functions'
     enthalten.

          (%i1) savedef:true;
          (%o1)                         true
          (%i2) f(x):=x^2+sin(x);
                                          2
          (%o2)                  f(x) := x  + sin(x)
          (%i3) translate(f);
          (%o3)                          [f]
          (%i4) dispfun(f);
                                          2
          (%t4)                  f(x) := x  + sin(x)

          (%o4)                         [%t4]
          (%i5) functions;
          (%o5)                        [f(x)]

     Dasselbe für eine Funktion 'g' mit dem Wert 'false' für 'savedef'.

          (%i6) savedef:false;
          (%o6)                         false
          (%i7) g(x):=sqrt(x)+cos(x)$

          (%i8) translate(g);
          (%o8)                          [g]
          (%i9) dispfun(g);

          fundef: no such function: g
           -- an error. To debug this try: debugmode(true);
          (%i10) functions;
          (%o10)                       [f(x)]

 -- Optionsvariable: transcompile
     Standardwert: 'true'

     Hat 'transcompile' den Wert 'true', generieren die Funktionen
     'translate' und 'translate_file' Deklarationen, die das Kompilieren
     des Codes verbessern.

     'compfile' setzt den Wert von 'transcompile' zu 'true'.

 -- Funktion: translate (<f_1>, ..., <f_n>)
 -- Funktion: translate (functions)
 -- Funktion: translate (all)

     Die vom Nutzer definierten Maxima-Funktionen <f_1>, ..., <f_n>
     werden nach Lisp übersetzt.  Typischerweise sind die übersetzten
     Funktionen schneller als die Maxima-Funktionen.

     'translate(all)' oder 'translate(functions)' übersetzt alle vom
     Benutzer definierten Funktionen.

     Funktionen, die übersetzt werden sollen, sollten mit 'mode_declare'
     den Typ von Variablen und Funktionen deklarieren, um effizienteren
     Code zu erhalten.  Im Folgenden Beispiel sind <x_1>, <x_2>, ... die
     Argumente der Funktion und <v_1>, <v_2>, ... sind die lokalen
     Variablen.

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

     Die Namen von übersetzten Funktionen werden von der
     Informationsliste 'functions' entfernt, wenn die Optionsvariable
     'savedef' den Wert 'false' hat.  Sie werden der Informationsliste
     'props' hinzugefügt.

     Funktionen sollten erst übersetzt werden, wenn sie vollständig von
     Fehlern befreit wurden.

     Ausdrücke werden als vereinfacht angenommen.  Sind sie es nicht,
     wird zwar korrekter, aber nicht optimierter Code erzeugt.  Daher
     sollte der Schalter 'simp' nicht den Wert 'false' haben, wodurch
     die Vereinfachung von Ausdrücken unterdrückt wäre.

     Hat der Schalter 'translate' den Wert 'true', werden
     nutzerdefinierte Funktionen automatisch nach Lisp übersetzt.

     Das Laufzeitverhalten von übersetzten Funktionen kann sich von dem
     nicht-übersetzter Funktionen unterscheiden.  Grundsätzlich sollte
     die Funktion 'rat' nicht mit mehr als zwei Argumenten und die
     Funktion 'ratvars' nicht genutzt werden, wenn irgendeine der
     Variablen eine CRE-Form mit Deklaration mit 'mode_declare'
     aufweisen.  Auch wird 'prederror:false' nicht übersetzt.

     Hat die Optionsvariable 'savedef' den Wert 'true', wird die
     Originalversion einer Funktion nicht entfernt.  Siehe 'savedef'.
     Mit dem Wert 'false' für 'transrun' werden, wenn noch vorhanden,
     die Originalversionen der übersetzten Funktion ausgeführt.

     Das Ergebnis der Funktion 'translate' ist eine Liste der Namen der
     übersetzten Funktionen.

 -- Funktion: translate_file (<maxima_filename>)
 -- Funktion: translate_file (<maxima_filename>, <lisp_filename>)

     Übersetzt eine Datei mit Maxima-Code in eine Datei mit Lisp-Code.
     'translate_file' gibt eine Liste mit drei Dateien zurück, die den
     Namen der Maxima-Datei, den Namen der Lisp-Datei und den Namen
     einer Datei mit Informationen zur Übersetzung enthält.
     'translate_file' wertet die Argumente aus.

     Die Kommandos 'translate_file("foo.mac")' und 'load("foo.LISP")'
     haben bis auf wenige Ausnahmen dieselbe Wirkung wie
     'batch("foo.mac")'.  Zum Beispiel funktionieren '''' und '%'
     unterschiedlich.

     'translate_file(<maxima_filename>)' übersetzt die Maxima-Datei
     <maxima_filename> in ein Lisp-Datei mit einem vergleichbaren Namen.
     Zum Beispiel wird die Maxima-Datei 'foo.mac' zu 'foo.LISP'.  Der
     Name der Maxima-Datei kann Pfadangaben enthalten.  In diesem Fall
     wird die Lisp-Datei in dasselbe Verzeichnis wie die Maxima-Datei
     geschrieben.

     'translate_file(<maxima_filename>, <lisp_filename>)' übersetzt die
     Maxima-Datei <maxima_filename> in eine Lisp-Datei mit dem Namen
     'lisp_filename'.  'translate_file' ignoriert eine angegebene
     Dateiendung des Dateinamenes 'lisp_filename'.  Die Dateiendung ist
     immer '.LISP'.  Der Name der Lisp-Datei kann Pfadangaben enthalten,
     um die Lisp-Datei in das gewünschte Verzeichnis zu schreiben.

     'translate_file' schreibt eine Ausgabedatei mit Meldungen des
     Übersetzers.  Die Dateiendung der Ausgabedatei ist '.UNILISP'.  Die
     Informationen dieser Datei können für die Fehlersuche genutzt
     werden.  Die Datei wird immer in das Verzeichnis geschrieben, das
     die Maxima-Datei enthält.

     'translate_file' generiert Lisp-Code mit Deklarationen und
     Definitionen, die bereits beim Kompilieren des Codes wirksam
     werden.  Siehe 'compile_file' für mehr Informationen.

     Siehe auch die folgenden Optionsvariablen:

     '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',
     und 'tr_warn_undefined_variable'.

 -- Optionsvariable: transrun
     Standardwert: 'true'

     Hat 'transrun' den Wert 'false', werden die nicht-übersetzten
     Versionen ausgeführt, falls diese noch vorhanden sind.  Siehe
     'savedef'.

 -- Optionsvariable: tr_array_as_ref
     Standardwert: 'true'

     Hat 'translate_fast_arrays' den Wert 'false', werden Referenzen auf
     Arrays in Lisp-Code von der Variablen 'tr_array_as_ref'
     kontrolliert.  Hat 'tr_array_as_ref' den Wert 'true', werden
     Array-Namen ausgewertet.

     'tr_array_as_ref' hat keinen Effekt, wenn 'translate_fast_arrays'
     den Wert 'true' hat.

 -- Optionsvariable: tr_bound_function_applyp
     Standardwert: 'true'

     Hat 'tr_bound_function_applyp' den Wert 'true', gibt Maxima eine
     Warnung aus, wenn versucht wird, eine gebundene Variable als eine
     Funktion verwendet werden soll.  'tr_bound_function_applyp' hat
     keinen Effekt auf den generierten Code.

     Zum Beispiel gibt ein Ausdruck der Form 'g (f, x) := f (x+1)' eine
     Warnung.

 -- Optionsvariable: tr_file_tty_messagesp
     Standardwert: 'false'

     Hat 'tr_file_tty_messagesp' den Wert 'true', werden Meldungen die
     von der Funktion 'translate_file' während einer Übersetzung
     generiert werden auch auf der Konsole ausgegeben.  Ansonsten werden
     Meldungen nur in die Datei '.UNILISP' geschrieben.

 -- Optionsvariable: tr_float_can_branch_complex
     Standardwert: 'true'

     Erklärt dem Übersetzer, dass die Funktionen 'acos', 'asin', 'asec'
     und 'acsc' komplexe Werte zurückgegeben können.

 -- Optionsvariable: tr_function_call_default
     Standardwert: 'general'

     'false' bedeutet, gebe auf und rufe 'meval' auf, 'expr' bedeutet,
     nehme Lisp-Argumente an.  'general', der Standardwert, gibt Code
     der für 'MEXPRS'-Funktionen geeignet ist.  Wird Maxima-Code mit dem
     Standardwert 'general' übersetzt, ohne dass Warnmeldungen
     ausgegeben werden, kann davon ausgegangen werden, dass der
     übersetzte und komplilierte Code kompatibel mit der ursprünglichen
     Funktion ist.

 -- Optionsvariable: tr_numer
     Standardwert: 'false'

     Hat 'tr_numer' den Wert 'true', wird die 'numer'-Eigenschaft von
     Symbolen vom Übersetzer angewendet.

 -- Optionsvariable: tr_optimize_max_loop
     Standardwert: 100

     'tr_optimize_max_loop' enthält die maximale Anzahl an Durchgängen,
     um Makros zu expandieren und den Code zu optimieren.  Damit werden
     unendliche Schleifen des Übersetzers vermieden.

 -- Optionsvariable: tr_semicompile
     Standardwert: 'false'

     Hat 'tr_semicompile' den Wert 'true', geben die Funktionen
     'translate_file' und 'compfile' Code aus, in dem Makrofunktionen
     expandiert sind, der aber nicht kompliliert ist.

 -- Systemvariable: tr_state_vars
     Standardwert:
     [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]

     Enthält eine Liste der Schalter, die die Übersetzung kontrollieren.

 -- Funktion: tr_warnings_get ()

     Gebe die Liste der Warnungen aus, welche bei der letzten
     Übersetzung erzeugt wurden.

 -- Optionsvariable: tr_warn_bad_function_calls
     Standardwert: 'true'

     Gebe Warnungen aus, wenn Funktionsaufrufe generiert werden, die
     möglicherweise nicht korrekt sind, aufgrund von ungeeigneten
     Deklarationen für die Übersetzung.

 -- Optionsvariable: tr_warn_fexpr
     Standardwert: 'compfile'

     Gebe Warnungen aus, wenn 'FEXPR'-Ausdrücke im übersetzten Code
     auftreten.

 -- Optionsvariable: tr_warn_meval
     Standardwert: 'compfile'

     Gebe Warnungen aus, wenn die Funktion 'meval' aufgerufen wird.
     Dies signalisiert Probleme bei der Übersetzung.

 -- Optionsvariable: tr_warn_mode
     Standardwert: 'all'

     Gebe Warnungen aus, wenn Variablen Werte zugewiesen werden, die
     nicht zu dem deklarierten Typ passen.

 -- Optionsvariable: tr_warn_undeclared
     Standardwert: 'compile'

     Kontrolliert, wann Warnungen über nicht-deklarierte Variablen
     angezeigt werden sollen.

 -- Optionsvariable: tr_warn_undefined_variable
     Standardwert: 'all'

     Gebe eine Warnung aus, wenn undefinierte globale Variablen
     auftreten.


File: maxima.info,  Node: Fehlersuche,  Next: Verschiedenes,  Prev: Übersetzer,  Up: Top

29 Fehlersuche
**************

* Menu:

* Quellcode-Debugger::
* Debugger-Kommandos::
* Funktionen und Variablen der Fehlersuche::


File: maxima.info,  Node: Quellcode-Debugger,  Next: Debugger-Kommandos,  Up: Fehlersuche

29.1 Quellcode-Debugger
=======================

Maxima hat einen Quellcode-Debugger.  Es können Unterbrechungspunkte
gesetzt werden, um die Ausführung einer Funktion abzubrechen und um
schrittweise die Funktion zu testen.  Der Stapelspeicher und Variable
können untersucht werden.

Das Kommando ':help' oder ':h' zeigt eine Liste mit den
Debugger-Kommandos.  Innerhalb des Debuggers können alle
Maxima-Funktionen genutzt werden, um Variablen und Ausdrücke auszugeben,
zu definieren oder anderweitig zu manipulieren.

Eine Unterbrechnung wird mit dem Kommando ':br' gesetzt.  Mit dem
Kommando ':n' oder ':next' wird die nächste Programmzeile ausgeführt.
Das Kommando ':bt' oder ':backtrace' zeigt eine Liste der Stack Frames.
Mit dem Kommando ':r' oder ':resume' wird der Debugger verlassen.

Beispiele:

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

Die im obigen Beispiel geladene Datei '/tmp/foobar.mac' hat den
folgenden Inhalt:

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

Nutzung des Debuggers mit Emacs
-------------------------------

Wird Maxima unter GNU Emacs in einer Shell ausgeführt oder wird die
Nutzeroberfläche Xmaxima verwendet, dann wird in einem zweiten
Ausgabefenster die Position einer Unterbrechung im Quellcode angezeigt.
Mit dem Emacs-Kommando 'M-n' kann dann schrittweise die Funktion
ausgeführt werden.

Um diese Funktionalität zu nutzen, sollte Emacs in einer 'dbl'-Shell
ausgeführt werden.  Dazu benötigt Emacs die Datei 'dbl.el' im elisp
Verzeichnis.  Dazu müssen die elisp-Dateien installiert oder das Maxima
elisp Verzeichnis bekannt sein.  Dazu können die folgenden Kommandos der
Datei '.emacs' hinzugefügt werden:

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

Mit dem Emacs-Kommando 'M-x dbl' wird eine Shell gestartet, in der
Programme wie Maxima, gcl, gdb u.  a.  ausgeführt werden können.  In
dieser Shell kann auch der Maxima-Debugger ausgeführt werden.

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: Debugger-Kommandos,  Next: Funktionen und Variablen der Fehlersuche,  Prev: Quellcode-Debugger,  Up: Fehlersuche

29.2 Debugger-Kommandos
=======================

Es gibt spezielle Kommandos, die von Maxima nicht als ein Ausdruck
interpretiert werden.  Diese Kommandos beginnen mit einem Doppelpunkt
':' und können in der Kommandozeile oder nach einer Unterbrechung
ausgeführt werden.  Mit dem Kommando ':lisp' werden zum Beispiel
Lisp-Zeilen ausgewertet:

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

Die Anzahl der Argumente hängt vom jeweiligen Kommando ab.  Die
Kommandos können mit den ersten zwei Buchstaben abgekürzt werden.  Zum
Beispiel genügt es ':br' für das Kommando ':break' einzugeben.

Die speziellen Kommandos sind folgende:

':break F n'
     Setzte einen Unterbrechnungspunkt in der Funktion 'F' in der Zeile
     'n' vom Anfang der Funktion.  Wird 'F' als eine Zeichenkette
     angegeben, dann wird 'F' als der Name einer Datei angenommen.  'n'
     ist in diesem Fall die 'n'-te Zeile in der Datei.  Wird 'n' nicht
     angegeben, wird der Wert zu Null angenommen.

':bt'
     Gebe einen Backtrace des Stack Frames aus.

':continue'
     Setze die Ausführung der Funktion fort.

':delete'
     Lösche den spezifizierten Unterbrechnungspunkt oder alle, wenn
     keiner spezifiziert wird.

':disable'
     Schalte den spezifierten oder alle Unterbrechnungspunkte ab.

':enable'
     Schalte den spezifizierten oder alle Unterbrechnungspunkte ein.

':frame n'
     Gebe den Stack Frame 'n' oder den aktuellen aus, wenn keiner
     spezifiert wird.

':help'
     Gebe einen Hilfetext zu einem spezifierten Kommando oder zu allen
     Kommandos aus, wenn kein Kommando spezifierten wird.

':info'
     Gebe Information über einen Eintrag aus.

':lisp some-form'
     Werte 'some-form' als eine Lisp-Form aus.

':lisp-quiet some-form'
     Werte 'some-form' als eine Lisp-Form aus, ohne eine Ausgabe zu
     erzeugen.

':next'
     Wie ':step', führt aber Funktionsaufrufe als einen Schritt aus.

':quit'
     Beende den Debugger.

':resume'
     Setzte die Ausführung des Programms fort.

':step'
     Setzte die Auswertung des Programms bis zur nächsten Zeile fort.

':top'
     Beende die Auswertung und kehre zur Maxima-Eingabe zurück.


File: maxima.info,  Node: Funktionen und Variablen der Fehlersuche,  Prev: Debugger-Kommandos,  Up: Fehlersuche

29.3 Funktionen und Variablen der Fehlersuche
=============================================

 -- Optionsvariable: debugmode
     Standardwert: 'false'

     Hat die Optionsvariable 'debugmode' den Wert 'true', wird der
     Maxima-Debugger gestartet, wenn ein Programmfehler auftritt.  Nach
     der Unterbrechung des Programms kann der Debugger genutzt werden.
     Siehe das Kapitel Debugger-Kommandos für eine Liste der Kommandos
     des Debuggers.

     Der Maxima-Debugger behandelt keine Lisp-Programmfehler.

 -- Optionsvariable: refcheck
     Standardwert: 'false'

     Hat 'refcheck' den Wert 'true', gibt Maxima eine Meldung aus, wenn
     einer Variablen zum ersten Mal ein Wert zugewiesen wird.

 -- Optionsvariable: setcheck
     Standardwert: 'false'

     Der Optionsvariablen 'setcheck' kann eine Liste mit den Namen von
     Variablen zugewiesen werden.  Dies können auch indizierte Variablen
     sein.  Immer wenn einer der Variablen mit den Operatoren ':' oder
     '::' ein Wert zugewiesen wird, gibt Maxima eine Meldung aus, die
     den Namen der Variablen und den zugewiesenen Wert enthält.

     'setcheck' kann den Wert 'all' oder 'true' erhalten.  In diesem
     Fall wird für alle Variablen eine Meldung ausgegeben.

     Jede Zuweisung an 'setcheck' initialisert eine neue Liste mit
     Variablen.  Vorherige Zuweisungen werden überschrieben.

     Die Auswertung der Namen der Variablen muss mit dem Quote-Operator
     ''' unterdrückt werden, wenn den Variablen bereits Werte zugewiesen
     wurden.  Haben zum Beispiel die Variablen 'x', 'y' und 'z' Werte,
     dann werden die Variablen mit dem folgenden Befehl angegeben:

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

     Es wird keine Meldung ausgegeben, wenn eine Variable sich selbst
     zugewiesen wird, zum Beispiel 'X: 'X'.

 -- Optionsvariable: setcheckbreak
     Standardwert: 'false'

     Hat 'setcheckbreak' den Wert 'true', startet Maxima den Debugger,
     wenn einer Variablen, die in der Liste 'setcheck' enthalten ist,
     ein Wert zugewiesen wird.  Die Unterbrechung wird noch vor der
     Zuweisung des Wertes ausgeführt.  Die Variable 'setval' enhält den
     Wert, der zugewiesen werden soll.  Dieser Variablen kann ein
     anderer Wert zugewiesen werden.

     Siehe auch 'setcheck' und 'setval'.

 -- Systemvariable: setval

     Enthält den Wert, der einer Variable zugewiesen werden soll, wenn
     die Zuweisung mit der Optionsvariablen 'setcheckbreak' unterbrochen
     wurde.  'setval' kann ein anderer Wert zugewiesen werden.

     Siehe auch 'setcheck' und 'setcheckbreak'.

 -- Funktion: timer (<f_1>, ..., <f_n>)
 -- Funktion: timer (all)
 -- Funktion: timer ()

     Sammelt Statistiken über die Ausführungszeiten von Funktionen.  Die
     Argumente <f_1>, ..., <f_n> sind die Namen von Funktionen zu denen
     Statistiken gesammelt werden.  'time(g)' fügt die Funktion 'g' der
     Liste an Funktionen hinzu, zu denen Informationen gesammelt werden.

     'timer(all)' fügt alle nutzerdefinierten Funktionen, die in der
     Informationsliste 'functions' enthalten sind, der Liste der
     Funktionen hinzu, über die Informationen gesammelt werden.

     Wird 'timer()' ohne Argumente aufgerufen, wird eine Liste der
     Funktionen zurückgeben, über die Informationen gesammelt werden.

     Maxima misst die Zeit, die eine Funktion für die Ausführung
     benötigt.  'timer_info' gibt eine Statistik für alle Funktionen
     zurück, für die die Ausführungszeiten gemessen werden.  Die
     Statistik enthält die durchschnittliche Ausführungszeit der
     Funktionen und die Anzahl der Aufrufe der Funktionen.  Mit der
     Funktion 'untimer' wird die Aufzeichnung der Ausführungszeiten
     beendet.

     'timer' wertet die Argumente nicht aus.  Daher werden im Folgenden
     'f(x) := x^2$ g:f$ timer(g)$' für die Funktion 'f' keine
     Ausführungszeiten aufgezeichnet.

     Wird für die Funktion 'f' mit dem Kommando 'trace(f)' der Ablauf
     verfolgt, hat das Kommando 'timer(f)' keinen Effekt.  Für eine
     Funktion können nicht gleichzeitig Ausführungszeiten aufgezeichnet
     und der Ablauf verfolgt werden.

     Siehe auch 'timer_devalue'.

 -- Funktion: untimer (<f_1>, ..., <f_n>)
 -- Funktion: untimer ()

     'untimer' beendet die Aufzeichnung von Informationen zur
     Ausführungszeit für die Funktionen <f_1>, ..., <f_n>.

     Wird 'untimer' ohne Argument aufgerufen, wird die Aufzeichnung für
     alle Funktionen beendet.

     Die aufgezeichneten Informationen zu einer Funktion 'f' können mit
     dem Kommando 'timer_info(f)' auch dann abgerufen werden, wenn zuvor
     mit dem Kommando 'untimer(f)' die Aufzeichnung für die Funktion 'f'
     beendet wurde.  Jedoch werden die aufgezeichneten Informationen für
     die Funktion 'f' nicht mit dem Kommando 'timer_info()' angezeigt.
     Das Kommando 'timer(f)' setzt alle aufgezeichneten zurück und
     startet die Aufzeichnung für die Funktion erneut.

 -- Optionsvariable: timer_devalue
     Standardwert: 'false'

     Hat 'timer_devalue' den Wert 'true', subtrahiert Maxima bei der
     Aufzeichnung der Ausführungszeiten die Zeiten, welche eine Funktion
     in anderen Funktionen verbringt.  Ansonsten enthalten die
     aufgezeichneten Zeiten auch die Ausführungszeiten der Funktionen,
     die aufgerufen werden.

     Siehe auch 'timer' und 'timer_info'.

 -- Funktion: timer_info (<f_1>, ..., <f_n>)
 -- Funktion: timer_info ()

     Gibt eine Tabelle mit den aufgezeichneten Informationen über die
     Ausführungszeiten der Funktionen <f_1>, ..., <f_n> zurück.  Wird
     kein Argument angegeben, werden Informationen für alle Funktionen
     angezeigt, zu denen Informationen aufgezeichnet sind.

     Die Tabelle enthält die Namen der Funktionen, die Ausführungszeit
     pro Aufruf, die Anzahl der Aufrufe, die gesamte Zeit und die
     'gctime'-Zeit.  Die 'gctime'-Zeit bedeutet "Garbage Collection
     Time".

     Die Daten, die von der Funktion 'timer_info' angezeigt werden,
     können auch mit der Funktion 'get' erhalten werden:

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

     Siehe auch 'timer'.

 -- Funktion: trace (<f_1>, ..., <f_n>)
 -- Funktion: trace (all)
 -- Funktion: trace ()

     Startet die Ablaufverfolgung für die Funktionen <f_1>, ..., <f_n>.
     Mit dem Kommando 'trace(g)' kann eine weitere Funktion hinzugefügt
     werden.

     'trace(all)' startet die Ablaufverfolgung für alle
     nutzerdefinierten Funktionen, die in der Informationsliste
     'functions' enthalten sind.

     Das Kommando 'trace()' zeigt eine Liste aller Funktionen für die
     eine Ablaufverfolgung gestartet wurde.

     Mit der Funktion 'untrace' wird die Ablaufverfolgung beendet.
     Siehe auch 'trace_options'.

     'trace' wertet die Argumente nicht aus.

     Die Ablaufverfolgung kann für eine Funktion 'f' nicht gestartet
     werden, wenn für die Funktion bereits mit der Funktion 'timer'
     Informationen über die Ausführungszeiten gesammelt werden.

 -- Funktion: trace_options (<f>, <option_1>, ..., <option_n>)
 -- Funktion: trace_options (<f>)

     Setzt Optionen für die Ablaufverfolgung einer Funktion <f>.
     Bereits vorliegende Optionen werden ersetzt.

     'trace_options(<f>)' setzt alle Optionen auf die Standardwerte
     zurück.

     Die Optionen sind:

     'noprint'
          Gebe keine Meldung beim Eintritt in eine oder dem Austritt aus
          einer Funktion aus.

     'break'
          Setze eine Unterbrechnung vor dem Eintritt in eine Funktion
          und nach dem Austritt aus einer Funktion.  Siehe 'break'.

     'lisp_print'
          Zeige die Argumente und Rückgabewerte in der Lisp-Syntax an.

     'info'
          Gebe '-> true' beim Eintritt in und Austritt aus einer
          Funktion aus.

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

     Es können bedingte Optionen für die Ablaufverfolgung definiert
     werden.  Dazu wird eine Option zusammen mit einer Aussagefunktion
     angegeben.  Die Argumente der Aussagefunktion für eine bedingte
     Option sind immer '[level, direction, function, item]'.  'level'
     ist die Rekursionstiefe der Funktion, 'direction' enthält die Werte
     'enter' oder 'exit', 'function' ist der Name der Funktion und
     'item' ist eine Liste der Argumente oder der Rückgabewert beim
     Verlassen der Funktion.

     Dies ist ein Beispiel für eine Ablaufverfolgung ohne Bedingungen:

          (%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);

     In diesem Fall wird eine Aussagefunktion für eine bedingte
     Ablaufverfolgung angegeben:

          (%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);

 -- Funktion: untrace (<f_1>, ..., <f_n>)
 -- Funktion: untrace ()

     Beendet die Ablaufverfolgung für die Funktionen <f_1>, ..., <f_n>.
     Das Kommando 'untrace()' beendet die Ablaufverfolgung für alle
     Funktionen.

     'untrace' gibt eine Liste der Funktionen zurück, für die die
     Ablaufverfolgung beendet wurde.


File: maxima.info,  Node: Verschiedenes,  Next: abs_integrate,  Prev: Fehlersuche,  Up: Top

30 Verschiedenes
****************

* Menu:

* Einführung in Verschiedenes::
* Share-Pakete::
* Funktionen und Variablen für Verschiedenes::


File: maxima.info,  Node: Einführung in Verschiedenes,  Next: Share-Pakete,  Prev: Verschiedenes,  Up: Verschiedenes

30.1 Einführung in Verschiedenes
================================

Dieses Kapitel enthält verschiedene Funktionen und Optionsvariablen.


File: maxima.info,  Node: Share-Pakete,  Next: Funktionen und Variablen für Verschiedenes,  Prev: Einführung in Verschiedenes,  Up: Verschiedenes

30.2 Share-Pakete
=================

Das Maxima Share-Verzeichnis enthält viele weitere zusätzliche
Funktionen und Erweiterungen, die nicht Teil des Kernels von Maxima und
in Paketen organisiert sind.  Diese Pakete werden mit der Funktion
'load' geladen.  Einige Pakete werden automatisch geladen, wenn der
Nutzer eine Funktion des Paketes aufruft.  Mit der Funktion
'setup_autoload' können Funktionen für das automatische Laden
konfiguriert werden.

Die Lisp-Variable '*maxima-sharedir*' enthält das Verzeichnis der
Pakete.  Das Kommanod 'printfile("share.usg")' gibt eine Übersicht über
Pakete aus.  Diese ist jedoch derzeit stark veraltert.


File: maxima.info,  Node: Funktionen und Variablen für Verschiedenes,  Prev: Share-Pakete,  Up: Verschiedenes

30.3 Funktionen und Variablen für Verschiedenes
===============================================

 -- Systemvariable: askexp

     Wenn 'asksign' aufgerufen wird, enthält 'askexp' den Ausdruck, der
     von 'asksign' getestet wird.

     Es war einmal möglich, die Variable 'askexp' nach einer
     Unterbrechnung mit Control-A zu inspezieren.

 -- Function: gensym ()
 -- Function: gensym (<x>)

     'gensym()' creates and returns a fresh symbol.

     The name of the new-symbol is the concatenation of a prefix, which
     defaults to "g", and a suffix, which is the decimal representation
     of a number that defaults to the value of a Lisp internal counter.

     If <x> is supplied, and is a string, then that string is used as a
     prefix instead of "g" for this call to gensym only.

     If <x> is supplied, and is an integer, then that integer, instead
     of the value of the internal Lisp integer, is used as the suffix
     for this call to gensym only.

     If and only if no explicit suffix is supplied, the Lisp internal
     integer is incremented after it is used.

     Examples:

          (%i1) gensym();
          (%o1)                         g887
          (%i2) gensym("new");
          (%o2)                        new888
          (%i3) gensym(123);
          (%o3)                         g123

 -- Option variable: packagefile
     Default value: 'false'

     Package designers who use 'save' or 'translate' to create packages
     (files) for others to use may want to set 'packagefile: true' to
     prevent information from being added to Maxima's information-lists
     (e.g.  'values', 'functions') except where necessary when the file
     is loaded in.  In this way, the contents of the package will not
     get in the user's way when he adds his own data.  Note that this
     will not solve the problem of possible name conflicts.  Also note
     that the flag simply affects what is output to the package file.
     Setting the flag to 'true' is also useful for creating Maxima init
     files.

 -- Funktion: remvalue (<name_1>, ..., <name_n>)
 -- Funktion: remvalue (all)

     Entfernt die Werte von nutzerdefinierten Variablen <name_1>, ...,
     <name_n>.  Die Variablen können indiziert sein.  'remvalue(all)'
     entfernt die Werte aller Variablen, die in der Informationsliste
     'values' enthalten sind.

     Siehe auch 'values'.

 -- Funktion: rncombine (<expr>)

     Transformiert den Ausdruck <expr> so, dass alle Terme mit
     identischem Nenner oder Nennern, die sich nur um einen numerischen
     Faktor voneinander unterscheiden, über einen Nenner zusammengefasst
     werden.  Die Funktion 'combine' fasst ebenfalls Ausdrücke über
     einen Nenner zusammen, betrachtet aber Nenner als verschieden, die
     sich um einen Zahlenfaktor voneinander unterscheiden.

     Die Funktion wird mit dem Kommando 'rncomb' geladen.

 -- Funktion: setup_autoload (<filename>, <function_1>, ...,
          <function_n>)

     Die Funktionen <function_1>, ..., <function_n> erhalten die
     Eigenschaft, dass die Datei <filename> automatisch geladen wird,
     wenn die Funktion zum ersten Mal genutzt werden soll.  <filename>
     wird mit der Funktion 'load' geladen und enthält üblicherweise den
     Code für die Definition der zu ladenden Funktion.

     'setup_autoload' funktioniert nicht für Array-Funktionen.
     'setup_autoload' wertet die Argumente nicht aus.

     Beispiele:

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


File: maxima.info,  Node: abs_integrate,  Next: affine,  Prev: Verschiedenes,  Up: Top

31 abs_integrate
****************

* Menu:

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


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

31.1 Introduction to abs_integrate
==================================

The package 'abs_integrate' extends Maxima's integration code to some
integrands that involve the absolute value, max, min, signum, or unit
step functions.  For integrands of the form p(x) |q(x)|, where p is a
polynomial and q is a polynomial that 'factor' is able to factor into a
product of linear or constant terms, the 'abs_integrate' package
determines an antiderivative that is continuous on the entire real line.
Additionally, for an integrand that involves one or more parameters, the
function 'conditional_integrate' tries to determine an antiderivative
that is valid for all parameter values.

Examples:

To use the 'abs_integrate' package, you'll first need to load it:

     (%i1) load("abs_integrate.mac")$
     (%i2) integrate(abs(x),x);
                                 x abs(x)
     (%o2)                       --------
                                    2

To convert (%o2) into an expression involving the absolute value
function, apply 'signum_to_abs'; thus

     (%i3) signum_to_abs(%);
                                 x abs(x)
     (%o3)                       --------
                                    2

When the integrand has the form p(x) |x - c1| |x - c2| ... |x - cn|,
where p(x) is a polynomial and c1, c2, ..., cn are constants, the
'abs_integrate' package returns an antiderivative that is valid on the
entire real line; thus without making assumptions on a and b; for
example

     (%i4) factor(convert_to_signum(integrate(abs((x-a)*(x-b)),x,a,b)));
                                 3       2
                          (b - a)  signum (b - a)
     (%o4)                -----------------------
                                     6

Additionally, 'abs_integrate' is able to find antiderivatives of some
integrands involving 'max', 'min', 'signum', and 'unit_step', examples:

     (%i5) integrate(max(x,x^2),x);
                3      2                                        3    2
             2 x  - 3 x    1                   1               x    x
     (%o5) ((----------- + --) signum(x - 1) + --) signum(x) + -- + --
                 12        12                  12              6    4
     (%i6) integrate(signum(x) - signum(1-x),x);
     (%o6)                  abs(x) + abs(x - 1)

A plot indicates that indeed (%o5) and (%o6) are continuous at zero and
at one.

For definite integrals with numerical integration limits (including both
minus and plus infinity), the 'abs_integrate' package converts the
integrand to signum form and then it tries to subdivide the integration
region so that the integrand simplifies to a non-signum expression on
each subinterval; for example

     (%i1) load(abs_integrate)$
     (%i2) integrate(1 / (1 + abs(x-5)),x,-5,6);
     (%o2)                   log(11) + log(2)

Finally, 'abs_integrate' is able to determine antiderivatives of _some_
functions of the form F(x, |x - a|); examples

     (%i3) integrate(1/(1 + abs(x)),x);
           signum(x) (log(x + 1) + log(1 - x))
     (%o3) -----------------------------------
                            2
                                               log(x + 1) - log(1 - x)
                                             + -----------------------
                                                          2
     (%i4) integrate(cos(x + abs(x)),x);
              (signum(x) + 1) sin(2 x) - 2 x signum(x) + 2 x
     (%o4)    ----------------------------------------------
                                    4

Barton Willis (Professor of Mathematics, University of Nebraska at
Kearney) wrote the 'abs_integrate' package and its English language user
documentation.  This documentation also describes the 'partition'
package for integration.  Richard Fateman wrote 'partition'.  Additional
documentation for 'partition' is located at
<http://www.cs.berkeley.edu/~fateman/papers/partition.pdf>


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

31.2 Functions and Variables for abs_integrate
==============================================

 -- Option variable: extra_integration_methods
     Default value: '['signum_int, 'abs_integrate_use_if]'

     The list 'extra_integration_methods' is a list of functions for
     integration.  When 'integrate' is unable to find an antiderivative,
     Maxima uses the methods in 'extra_integration_methods' to attempt
     to determine an antiderivative.

     Each function 'f' in 'extra_integration_methods' should have the
     form 'f(integrand, variable)'.  The function 'f' may either return
     'false' to indicate failure, or it may return an expression
     involving an integration noun form.  The integration methods are
     tried from the first to the last member of
     'extra_integration_methods'; when no method returns an expression
     that does not involve an integration noun form, the value of the
     integral is the last value that does not fail (or a pure noun form
     if all methods fail).

     When the function 'abs_integrate_use_if' is successful, it returns
     a conditional expression; for example

          (%i1) load(abs_integrate)$
          (%i2) integrate(1/(1 + abs(x+1) + abs(x-1)),x);
                                     log(1 - 2 x)            2
          (%o2) %if(- (x + 1) > 0, - ------------ + log(3) - -,
                                          2                  3
                                             x   log(3)   1  log(2 x + 1)
                          %if(- (x - 1) > 0, - + ------ - -, ------------))
                                             3     2      3       2
          (%i3) integrate(exp(-abs(x-1) - abs(x)),x);
                               2 x - 1
                             %e              - 1
          (%o3) %if(- x > 0, --------- - 2 %e   ,
                                 2
                                                         - 1      1 - 2 x
                                             - 1     3 %e       %e
                        %if(- (x - 1) > 0, %e    x - -------, - ---------))
                                                        2           2

     For definite integration, these conditional expressions can cause
     trouble:

          (%i4) integrate(exp(-abs(x-1) - abs(x)),x, minf,inf);
                                         - 1    2 x
                                       %e    (%e    - 4)
          (%o4) limit     %if(- x > 0, -----------------,
                x -> inf-                      2
                               - 1                1 - 2 x
                             %e    (2 x - 3)    %e
          %if(- (x - 1) > 0, ---------------, - ---------))
                                    2               2
                                       - 1    2 x
                                     %e    (%e    - 4)
           - limit      %if(- x > 0, -----------------,
             x -> minf+                      2
                               - 1                1 - 2 x
                             %e    (2 x - 3)    %e
          %if(- (x - 1) > 0, ---------------, - ---------))
                                    2               2

     For such definite integrals, try disallowing the method
     'abs_integrate_use_if':

          (%i5) integrate(exp(-abs(x-1) - abs(x)),x, minf,inf),
                    extra_integration_methods : ['signum_int];
                                           - 1
          (%o5)                        2 %e

     Related options 'extra_definite_integration_methods'.

     To use 'load(abs_integrate)'

 -- Option variable: extra_definite_integration_methods
     Default value: '['abs_defint]'

     The list 'extra_definite_integration_methods' is a list of extra
     functions for definite integration.  When 'integrate' is unable to
     find a definite integral, Maxima uses the methods in
     'extra_definite_integration_methods' to attempt to determine an
     antiderivative.

     Each function 'f' in 'extra_definite_integration_methods' should
     have the form 'f(integrand, variable, lo, hi)', where 'lo' and 'hi'
     are the lower and upper limits of integration, respectively.  The
     function 'f' may either return 'false' to indicate failure, or it
     may return an expression involving an integration noun form.  The
     integration methods are tried from the first to the last member of
     'extra_definite_integration_methods'; when no method returns an
     expression that does not involve an integration noun form, the
     value of the integral is the last value that does not fail (or a
     pure noun form if all methods fail).

     Related options 'extra_integration_methods'.

     To use 'load(abs_integrate)'.

 -- Function: intfudu (<e>, <x>)

     This function uses the derivative divides rule for integrands of
     the form f(w(x)) * diff(w(x),x).  When 'infudu' is unable to find
     an antiderivative, it returns false.

          (%i1) load(abs_integrate)$
          (%i2) intfudu(cos(x^2) * x,x);
                                            2
                                       sin(x )
          (%o2)                        -------
                                          2
          (%i3) intfudu(x * sqrt(1+x^2),x);
                                       2     3/2
                                     (x  + 1)
          (%o3)                      -----------
                                          3
          (%i4) intfudu(x * sqrt(1 + x^4),x);
          (%o4)                         false

     For the last example, the derivative divides rule fails, so
     'intfudu' returns false.

     A hashed array 'intable' contains the antiderivative data.  To
     append a fact to the hash table, say integrate(f) = g, do this:

          (%i5) intable[f] : lambda([u],  [g(u),diff(u,%voi)]);
          (%o5)          lambda([u], [g(u), diff(u, %voi)])
          (%i6) intfudu(f(z),z);
          (%o6)                         g(z)
          (%i7) intfudu(f(w(x)) * diff(w(x),x),x);
          (%o7)                        g(w(x))

     An alternative to calling 'intfudu' directly is to use the
     'extra_integration_methods' mechanism; an example:

          (%i1) load(abs_integrate)$
          (%i2) load(basic)$
          (%i3) load("partition.mac")$

          (%i4) integrate(bessel_j(1,x^2) * x,x);
                                                 2
                                    bessel_j(0, x )
          (%o4)                   - ---------------
                                           2
          (%i5) push('intfudu, extra_integration_methods)$

          (%i6) integrate(bessel_j(1,x^2) * x,x);
                                                 2
                                    bessel_j(0, x )
          (%o6)                   - ---------------
                                           2

     To use 'load(partition)'.

     Additional documentation
     <http://www.cs.berkeley.edu/~fateman/papers/partition.pdf>.

     Related functions 'intfugudu'.

 -- Function: intfugudu (<e>, <x>)

     This function uses the derivative divides rule for integrands of
     the form f(w(x)) * g(w(x)) * diff(w(x),x).  When 'infugudu' is
     unable to find an antiderivative, it returns false.

          (%i1) load(abs_integrate)$
          (%i2) diff(jacobi_sn(x,2/3),x);
                                        2               2
          (%o2)            jacobi_cn(x, -) jacobi_dn(x, -)
                                        3               3
          (%i3) intfugudu(%,x);
                                                2
          (%o3)                    jacobi_sn(x, -)
                                                3
          (%i4) diff(jacobi_dn(x^2,a),x);
                                         2                2
          (%o4)       - 2 a x jacobi_cn(x , a) jacobi_sn(x , a)
          (%i5) intfugudu(%,x);
                                             2
          (%o5)                   jacobi_dn(x , a)

     For a method for automatically calling 'infugudu' from 'integrate',
     see the documentation for 'intfudu'.

     To use 'load(partition)'.

     Additional documentation
     <http://www.cs.berkeley.edu/~fateman/papers/partition.pdf>

     Related functions 'intfudu'.

 -- Function: signum_to_abs (<e>)

     This function replaces subexpressions of the form q signum(q) by
     abs(q).  Before it does these substitutions, it replaces
     subexpressions of the form signum(p) * signum(q) by signum(p * q);
     examples:

          (%i1) load(abs_integrate)$
          (%i2) map('signum_to_abs, [x * signum(x),
                                     x * y * signum(x)* signum(y)/2]);
                                        abs(x) abs(y)
          (%o2)                [abs(x), -------------]
                                              2

     To use 'load(abs_integrate)'.

 -- Macro: simp_assuming (<e>, <f_1>, <f_2>, ..., <f_n>)

     Appended the facts f_1, f_2, ..., f_n to the current context and
     simplify e.  The facts are removed before returning the simplified
     expression e.

          (%i1) load(abs_integrate)$
          (%i2) simp_assuming(x + abs(x), x < 0);
          (%o2)                           0

     The facts in the current context aren't ignored:

          (%i3) assume(x > 0)$
          (%i4) simp_assuming(x + abs(x),x < 0);
          (%o4)                          2 x

     Since 'simp_assuming' is a macro, effectively 'simp_assuming'
     quotes is arguments; this allows

          (%i5) simp_assuming(asksign(p), p < 0);
          (%o5)                          neg

     To use 'load(abs_integrate)'.

 -- Function: conditional_integrate (<e>, <x>)

     For an integrand with one or more parameters, this function tries
     to determine an antiderivative that is valid for all parameter
     values.  When successful, this function returns a conditional
     expression for the antiderivative.

          (%i1) load(abs_integrate)$
          (%i2) conditional_integrate(cos(m*x),x);
                                          sin(m x)
          (%o2)                %if(m # 0, --------, x)
                                             m
          (%i3) conditional_integrate(cos(m*x)*cos(x),x);

          (%o3) %if((m - 1 # 0) %and (m + 1 # 0),
          (m - 1) sin((m + 1) x) + (- m - 1) sin((1 - m) x)
          -------------------------------------------------,
                                 2
                              2 m  - 2
          sin(2 x) + 2 x
          --------------)
                4
          (%i4) sublis([m=6],%);
                               5 sin(7 x) + 7 sin(5 x)
          (%o4)                -----------------------
                                         70
          (%i5) conditional_integrate(exp(a*x^2+b*x),x);
                                            2
                                           b
                                         - ---
                                           4 a      2 a x + b
                             sqrt(%pi) %e      erf(-----------)
                                                   2 sqrt(- a)
          (%o5) %if(a # 0, - ----------------------------------,
                                        2 sqrt(- a)
                                                                   b x
                                                                 %e
                                                      %if(b # 0, -----, x))
                                                                   b

 -- Function: convert_to_signum (<e>)

     This function replaces subexpressions of the form 'abs(q),
     unit_step(q), min(q1, q2, ..., qn)' and 'max(q1, q2, ..., qn)' by
     equivalent signum terms.

          (%i1) load(abs_integrate)$
          (%i2) map('convert_to_signum, [abs(x), unit_step(x),
                                         max(a,2), min(a,2)]);

                              signum(x) (signum(x) + 1)
          (%o2) [x signum(x), -------------------------,
                                          2
            (a - 2) signum(a - 2) + a + 2  - (a - 2) signum(a - 2) + a + 2
            -----------------------------, -------------------------------]
                          2                               2

     To convert 'unit_step' to signum form, the function
     'convert_to_signum' uses unit_step(x) = (1 + signum(x))/2.

     To use 'load(abs_integrate)'.

     Related functions 'signum_to_abs'.


File: maxima.info,  Node: affine,  Next: asympa,  Prev: abs_integrate,  Up: Top

32 affine
*********

* Menu:

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


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

32.1 Introduction to Affine
===========================

'affine' is a package to work with groups of polynomials.


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

32.2 Functions and Variables for Affine
=======================================

 -- Function: fast_linsolve ([<expr_1>, ..., <expr_m>], [<x_1>, ...,
          <x_n>])

     Solves the simultaneous linear equations <expr_1>, ..., <expr_m>
     for the variables <x_1>, ..., <x_n>.  Each <expr_i> may be an
     equation or a general expression; if given as a general expression,
     it is treated as an equation of the form '<expr_i> = 0'.

     The return value is a list of equations of the form '[<x_1> =
     <a_1>, ..., <x_n> = <a_n>]' where <a_1>, ..., <a_n> are all free of
     <x_1>, ..., <x_n>.

     'fast_linsolve' is faster than 'linsolve' for system of equations
     which are sparse.

     'load(affine)' loads this function.

 -- Function: grobner_basis ([<expr_1>, ..., <expr_m>])

     Returns a Groebner basis for the equations <expr_1>, ..., <expr_m>.
     The function 'polysimp' can then be used to simplify other
     functions relative to the equations.

     'polysimp(f)' yields 0 if and only if <f> is in the ideal generated
     by <expr_1>, ..., <expr_m>, that is, if and only if <f> is a
     polynomial combination of the elements of <expr_1>, ..., <expr_m>.

     'load(affine)' loads this function.

     Beispiel:

          (%i1) load(affine)$

          (%i2) grobner_basis ([3*x^2+1, y*x]);
          eliminated one
           . 0 . 0                                   2
          (%o2)/R/                [- y, - 3 x  - 1]
          (%i3) polysimp(y^2*x+x^3*9+2);
          (%o3)/R/                    - 3 x + 2

 -- Function: set_up_dot_simplifications (<eqns>,
          <check_through_degree>)
 -- Function: set_up_dot_simplifications (<eqns>)

     The <eqns> are polynomial equations in non commutative variables.
     The value of 'current_variables' is the list of variables used for
     computing degrees.  The equations must be homogeneous, in order for
     the procedure to terminate.

     If you have checked overlapping simplifications in
     'dot_simplifications' above the degree of <f>, then the following
     is true: 'dotsimp(<f>)' yields 0 if and only if <f> is in the ideal
     generated by the equations, i.e., if and only if <f> is a
     polynomial combination of the elements of the equations.

     The degree is that returned by 'nc_degree'.  This in turn is
     influenced by the weights of individual variables.

     'load(affine)' loads this function.

 -- Function: declare_weights (<x_1>, <w_1>, ..., <x_n>, <w_n>)

     Assigns weights <w_1>, ..., <w_n> to <x_1>, ..., <x_n>,
     respectively.  These are the weights used in computing 'nc_degree'.

     'load(affine)' loads this function.

 -- Function: nc_degree (<p>)

     Returns the degree of a noncommutative polynomial <p>.  See
     'declare_weights'.

     'load(affine)' loads this function.

 -- Function: dotsimp (<f>)

     Returns 0 if and only if <f> is in the ideal generated by the
     equations, i.e., if and only if <f> is a polynomial combination of
     the elements of the equations.

     'load(affine)' loads this function.

 -- Function: fast_central_elements ([<x_1>, ..., <x_n>], <n>)

     If 'set_up_dot_simplifications' has been previously done, finds the
     central polynomials in the variables <x_1>, ..., <x_n> in the given
     degree, <n>.

     For example:

          set_up_dot_simplifications ([y.x + x.y], 3);
          fast_central_elements ([x, y], 2);
          [y.y, x.x];

     'load(affine)' loads this function.

 -- Function: check_overlaps (<n>, <add_to_simps>)

     Checks the overlaps thru degree <n>, making sure that you have
     sufficient simplification rules in each degree, for 'dotsimp' to
     work correctly.  This process can be speeded up if you know before
     hand what the dimension of the space of monomials is.  If it is of
     finite global dimension, then 'hilbert' should be used.  If you
     don't know the monomial dimensions, do not specify a
     'rank_function'.  An optional third argument 'reset', 'false' says
     don't bother to query about resetting things.

     'load(affine)' loads this function.

 -- Function: mono ([<x_1>, ..., <x_n>], <n>)

     Returns the list of independent monomials relative to the current
     dot simplifications of degree <n> in the variables <x_1>, ...,
     <x_n>.

     'load(affine)' loads this function.

 -- Function: monomial_dimensions (<n>)

     Compute the Hilbert series through degree <n> for the current
     algebra.

     'load(affine)' loads this function.

 -- Function: extract_linear_equations ([<p_1>, ..., <p_n>], [<m_1>,
          ..., <m_n>])

     Makes a list of the coefficients of the noncommutative polynomials
     <p_1>, ..., <p_n> of the noncommutative monomials <m_1>, ...,
     <m_n>.  The coefficients should be scalars.  Use
     'list_nc_monomials' to build the list of monomials.

     'load(affine)' loads this function.

 -- Function: list_nc_monomials ([<p_1>, ..., <p_n>])
 -- Function: list_nc_monomials (<p>)

     Returns a list of the non commutative monomials occurring in a
     polynomial <p> or a list of polynomials <p_1>, ..., <p_n>.

     'load(affine)' loads this function.

 -- Option variable: all_dotsimp_denoms
     Default value: 'false'

     When 'all_dotsimp_denoms' is a list, the denominators encountered
     by 'dotsimp' are appended to the list.  'all_dotsimp_denoms' may be
     initialized to an empty list '[]' before calling 'dotsimp'.

     By default, denominators are not collected by 'dotsimp'.


File: maxima.info,  Node: asympa,  Next: augmented_lagrangian,  Prev: affine,  Up: Top

33 asympa
*********

* Menu:

* Introduction to asympa::
* Functions and variables for asympa::


File: maxima.info,  Node: Introduction to asympa,  Next: Functions and variables for asympa,  Prev: asympa,  Up: asympa

33.1 Introduction to asympa
===========================

 -- Function: asympa

     'asympa' is a package for asymptotic analysis.  The package
     contains simplification functions for asymptotic analysis,
     including the "big O" and "little o" functions that are widely used
     in complexity analysis and numerical analysis.

     'load ("asympa")' loads this package.


File: maxima.info,  Node: Functions and variables for asympa,  Prev: Introduction to asympa,  Up: asympa

33.2 Functions and variables for asympa
=======================================


File: maxima.info,  Node: augmented_lagrangian,  Next: bernstein,  Prev: asympa,  Up: Top

34 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

34.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)
 -- Function: augmented_lagrangian_method ([<FOM>, <grad>], <xx>, <C>,
          <yy>)
 -- Function: augmented_lagrangian_method ([<FOM>, <grad>], <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]).

     <grad>, if present, is the gradient of <FOM> with respect to <xx>,
     represented as a list of expressions, one for each variable in
     <xx>.  If not present, the gradient is constructed automatically.

     <FOM> and each element of <grad>, if present, must be ordinary
     expressions, not names of functions or lambda expressions.

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

     Examples:

          (%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]]

     Same example as before, but this time the gradient is supplied as
     an argument.

          (%i1) load (lbfgs)$
          (%i2) load (augmented_lagrangian)$
          (%i3) FOM: x^2 + 2*y^2;
                                         2    2
          (%o3)                       2 y  + x
          (%i4) FOM: x^2 + 2*y^2;
                                         2    2
          (%o4)                       2 y  + x
          (%i5) xx: [x, y];
          (%o5)                        [x, y]
          (%i6) grad : [2*x, 4*y];
          (%o6)                      [2 x, 4 y]
          (%i7) C: [x + y - 1];
          (%o7)                      [y + x - 1]
          (%i8) yy: [1, 1];
          (%o8)                        [1, 1]
          (%i9) augmented_lagrangian_method ([FOM, grad], xx, C, yy,
                                             iprint = [-1, 0]);
          (%o9) [[x = 0.666659841080025, y = .3333402724554462],
                                           %lambda = [- 1.333337940892543]]


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

35 bernstein
************

* Menu:

* Functions and Variables for Bernstein::


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

35.1 Functions and Variables for Bernstein
==========================================

 -- Function: bernstein_poly (<k>, <n>, <x>)

     Provided 'k' is not a negative integer, the Bernstein polynomials
     are defined by 'bernstein_poly(k,n,x) = binomial(n,k) x^k
     (1-x)^(n-k)'; for a negative integer 'k', the Bernstein polynomial
     'bernstein_poly(k,n,x)' vanishes.  When either 'k' or 'n' are non
     integers, the option variable 'bernstein_explicit' controls the
     expansion of the Bernstein polynomials into its explicit form;
     example:

          (%i1) load(bernstein)$

          (%i2) bernstein_poly(k,n,x);
          (%o2)                bernstein_poly(k, n, x)
          (%i3) bernstein_poly(k,n,x), bernstein_explicit : true;
                                                 n - k  k
          (%o3)            binomial(n, k) (1 - x)      x

     The Bernstein polynomials have both a gradef property and an
     integrate property:

          (%i4) diff(bernstein_poly(k,n,x),x);
          (%o4) (bernstein_poly(k - 1, n - 1, x)
                                           - bernstein_poly(k, n - 1, x)) n
          (%i5) integrate(bernstein_poly(k,n,x),x);
          (%o5)
                                                                      k + 1
           hypergeometric([k + 1, k - n], [k + 2], x) binomial(n, k) x
           ----------------------------------------------------------------
                                        k + 1

     For numeric inputs, both real and complex, the Bernstein
     polynomials evaluate to a numeric result:

          (%i6) bernstein_poly(5,9, 1/2 + %i);
                                  39375 %i   39375
          (%o6)                   -------- + -----
                                    128       256
          (%i7) bernstein_poly(5,9, 0.5b0 + %i);
          (%o7)           3.076171875b2 %i + 1.5380859375b2

     To use 'bernstein_poly', first 'load("bernstein")'.

 -- Variable: bernstein_explicit
     Default value: 'false'

     When either 'k' or 'n' are non integers, the option variable
     'bernstein_explicit' controls the expansion of 'bernstein(k,n,x)'
     into its explicit form; example:

          (%i1) bernstein_poly(k,n,x);
          (%o1)                bernstein_poly(k, n, x)
          (%i2) bernstein_poly(k,n,x), bernstein_explicit : true;
                                                 n - k  k
          (%o2)            binomial(n, k) (1 - x)      x

     When both 'k' and 'n' are explicitly integers, 'bernstein(k,n,x)'
     _always_ expands to its explicit form.

 -- Function: multibernstein_poly (<[k1, k2, ..., kp]>, <[n1, n2, ...,
          np]>, <[x1, x2, ..., xp]>)

     The multibernstein polynomial 'multibernstein_poly (<[k1, ...,
     kp]>, <[n1, ..., np]>, <[x1, ..., xp]>)' is the product of
     bernstein polynomials 'bernstein_poly(k1, n1, x1) * ... *
     bernstein_poly(kp, np, xp)'.

     To use 'multibernstein_poly', first 'load("bernstein")'.

 -- Function: bernstein_approx (<f>, <[x1, x1, ..., xn]>, <n>)

     Return the 'n'-th order uniform Bernstein polynomial approximation
     for the function '(x1, x2, ..., xn) |--> f'.

     Examples:

          (%i1) bernstein_approx(f(x),[x], 2);
                           2       1                          2
          (%o1)      f(1) x  + 2 f(-) (1 - x) x + f(0) (1 - x)
                                   2
          (%i2) bernstein_approx(f(x,y),[x,y], 2);
                         2  2       1                2
          (%o2) f(1, 1) x  y  + 2 f(-, 1) (1 - x) x y
                                    2
                            2  2          1   2
           + f(0, 1) (1 - x)  y  + 2 f(1, -) x  (1 - y) y
                                          2
                 1  1                               1         2
           + 4 f(-, -) (1 - x) x (1 - y) y + 2 f(0, -) (1 - x)  (1 - y) y
                 2  2                               2
                      2        2       1                      2
           + f(1, 0) x  (1 - y)  + 2 f(-, 0) (1 - x) x (1 - y)
                                       2
                            2        2
           + f(0, 0) (1 - x)  (1 - y)

     To use 'bernstein_approx', first 'load("bernstein")'.

 -- Function: bernstein_expand (<e>, <[x1, x1, ..., xn]>)

     Express the _polynomial_ 'e' exactly as a linear combination of
     multi-variable Bernstein polynomials.

          (%i1) bernstein_expand(x*y+1,[x,y]);
          (%o1)    2 x y + (1 - x) y + x (1 - y) + (1 - x) (1 - y)
          (%i2) expand(%);
          (%o2)                        x y + 1

     Maxima signals an error when the first argument isn't a polynomial.

     To use 'bernstein_expand', first 'load("bernstein")'.


File: maxima.info,  Node: bode,  Next: cobyla,  Prev: bernstein,  Up: Top

36 bode
*******

* Menu:

* Functions and Variables for bode::


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

36.1 Functions and Variables for bode
=====================================

 -- Function: bode_gain (<H>, <range>, ... <plot_opts> ...)

     Function to draw Bode gain plots.  To use this function write first
     'load(bode)'.  See also 'bode_phase'.

     Examples:

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

 -- Function: bode_phase (<H>, <range>, ... <plot_opts> ...)

     Function to draw Bode phase plots.  To use this function write
     first 'load(bode)'.  See also 'bode_gain'.

     Examples:

     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 : true],
                        bode_phase (H8 (s), [w, 1/1000, 1000]));


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

37 cobyla
*********

* Menu:

* Introduction to cobyla::
* Functions and Variables for cobyla::
* Examples for cobyla::  


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

37.1 Introduction to cobyla
===========================

'fmin_cobyla' is a Common Lisp translation (via 'f2cl') of the Fortran
constrained optimization routine COBYLA by Powell[1][2][3].

COBYLA minimizes an objective function F(X) subject to M inequality
constraints of the form g(X) >= 0 on X, where X is a vector of variables
that has N components.

Equality constraints g(X)=0 can often be implemented by a pair of
inequality constraints g(X)>=0 and -g(X)>= 0.  Maxima's interface to
COBYLA allows equality constraints and internally converts the equality
constraints to a pair of inequality constraints.

The algorithm employs linear approximations to the objective and
constraint functions, the approximations being formed by linear
interpolation at N+1 points in the space of the variables.  The
interpolation points are regarded as vertices of a simplex.  The
parameter RHO controls the size of the simplex and it is reduced
automatically from RHOBEG to RHOEND. For each RHO the subroutine tries
to achieve a good vector of variables for the current size, and then RHO
is reduced until the value RHOEND is reached.  Therefore RHOBEG and
RHOEND should be set to reasonable initial changes to and the required
accuracy in the variables respectively, but this accuracy should be
viewed as a subject for experimentation because it is not guaranteed.
The routine treats each constraint individually when calculating a
change to the variables, rather than lumping the constraints together
into a single penalty function.  The name of the subroutine is derived
from the phrase Constrained Optimization BY Linear Approximations.

References:

[1] Fortran Code is from <http://plato.asu.edu/sub/nlores.html#general>

[2] M. J. D. Powell, "A direct search optimization method that models
the objective and constraint functions by linear interpolation," in
Advances in Optimization and Numerical Analysis, eds.  S. Gomez and
J.-P. Hennart (Kluwer Academic: Dordrecht, 1994), p.  51-67.

[3] M. J. D. Powell, "Direct search algorithms for optimization
calculations," Acta Numerica 7, 287-336 (1998).  Also available as
University of Cambridge, Department of Applied Mathematics and
Theoretical Physics, Numerical Analysis Group, Report NA1998/04 from
<http://www.damtp.cam.ac.uk/user/na/reports.html>


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

37.2 Functions and Variables for cobyla
=======================================

 -- Function: fmin_cobyla (<F>, <X>, <Y>)
 -- Function: fmin_cobyla (<F>, <X>, <Y>, optional_args)

     Returns an approximate minimum of the expression <F> with respect
     to the variables <X>, subject to an optional set of constraints.
     <Y> is a list of initial guesses for <X>.

     <F> must be an ordinary expressions, not names of functions or
     lambda expressions.

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

     'constraints'
          List of inequality and equality constraints that must be
          satisfied by <X>.  The inequality constraints must be actual
          inequalities of the form 'g(<X>) >= h(<X>)' or 'g(<X>) <=
          h(<X>)'.  The equality constraints must be of the form 'g(<X>)
          = h(<X>)'.

     'rhobeg'
          Initial value of the internal RHO variable which controls the
          size of simplex.  (Defaults to 1.0)

     'rhoend'
          The desired final value rho parameter.  It is approximately
          the accuracy in the variables.  (Defaults to 1d-6.)

     'iprint'
          Verbose output level.  (Defaults to 0)
             * 0 - No output
             * 1 - Summary at the end of the calculation
             * 2 - Each new value of RHO and SIGMA is printed, including
               the vector of variables, some function information when
               RHO is reduced.
             * 3 - Like 2, but information is printed when F(X) is
               computed.
     'maxfun'
          The maximum number of function evaluations.  (Defaults to
          1000).

     On return, a vector is given:

       1. The value of the variables giving the minimum.  This is a list
          of elements of the form '<var> = <value>' for each of the
          variables listed in <X>.
       2. The minimized function value
       3. The number of function evaluations.
       4. Return code with the following meanings
            1. 0 - No errors.
            2. 1 - Limit on maximum number of function evaluations
               reached.
            3. 2 - Rounding errors inhibiting progress.

     'load(fmin_cobyla)' loads this function.

 -- Function: bf_fmin_cobyla (<F>, <X>, <Y>)
 -- Function: bf_fmin_cobyla (<F>, <X>, <Y>, optional_args)

     This function is identical to 'fmin_cobyla', except that bigfloat
     operations are used, and the default value for <rhoend> is
     '10^(fpprec/2)'.

     See 'fmin_cobyla' for more information.

     'load(fmin_cobyla)' loads this function.


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

37.3 Examples for cobyla
========================

Minimize x1*x2 with 1-x1^2-x2^2 >= 0.  The theoretical solution is x1 =
1/sqrt(2), x2 = -1/sqrt(2).

     (%i1) load(fmin_cobyla)$

     (%i2) fmin_cobyla(x1*x2, [x1, x2], [1,1],
                              constraints = [x1^2+x2^2<=1], iprint=1);

        Normal return from subroutine COBYLA

        NFVALS =   66   F =-5.000000E-01    MAXCV = 1.999956E-12
        X = 7.071058E-01  -7.071077E-01
     (%o2) [[x1 = .7071058493484819, x2 = - .7071077130247994],
                                           - .499999999999263

There are additional examples in the share/cobyla/ex directory.


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

38 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

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

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

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

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

38.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. Kolokolnikov, 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.


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

39 Package 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: Package descriptive,  Up: Package descriptive

39.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: Package descriptive

39.2 Functions and Variables for data manipulation
==================================================

 -- Function: build_sample (<list>)
 -- Function: build_sample (<matrix>)
     Builds a sample from a table of absolute frequencies.  The input
     table can be a matrix or a list of lists, all of them of equal
     size.  The number of columns or the length of the lists must be
     greater than 1.  The last element of each row or list is
     interpreted as the absolute frequency.  The output is always a
     sample in matrix form.

     Examples:

     Univariate frequency table.

          (%i1) load (descriptive)$
          (%i2) sam1: build_sample([[6,1], [j,2], [2,1]]);
                                 [ 6 ]
                                 [   ]
                                 [ j ]
          (%o2)                  [   ]
                                 [ j ]
                                 [   ]
                                 [ 2 ]
          (%i3) mean(sam1);
                                2 j + 8
          (%o3)                [-------]
                                   4
          (%i4) barsplot(sam1) $

     Multivariate frequency table.

          (%i1) load (descriptive)$
          (%i2) sam2: build_sample([[6,3,1], [5,6,2], [u,2,1],[6,8,2]]) ;
                                     [ 6  3 ]
                                     [      ]
                                     [ 5  6 ]
                                     [      ]
                                     [ 5  6 ]
          (%o2)                      [      ]
                                     [ u  2 ]
                                     [      ]
                                     [ 6  8 ]
                                     [      ]
                                     [ 6  8 ]
          (%i3) cov(sam2);
                 [   2                 2                            ]
                 [  u  + 158   (u + 28)     2 u + 174   11 (u + 28) ]
                 [  -------- - ---------    --------- - ----------- ]
          (%o3)  [     6          36            6           12      ]
                 [                                                  ]
                 [ 2 u + 174   11 (u + 28)            21            ]
                 [ --------- - -----------            --            ]
                 [     6           12                 4             ]
          (%i4) barsplot(sam2, grouping=stacked) $

 -- Function: continuous_freq (<list>)
 -- Function: continuous_freq (<list>, <m>)

     The argument of 'continuous_freq' must be a list of numbers.
     Divides the range in intervals and counts how many values are
     inside them.  The second argument is optional and either equals the
     number of classes we want, '10' by default, or equals a list
     containing the class limits and the number of classes we want, or a
     list containing only the limits.  Argument <list> must be a list of
     (2 or 3) real numbers.  If sample values are all equal, this
     function returns only one class of amplitude 2.

     Examples:

     Optional argument indicates the number of classes we want.  The
     first list in the output contains the interval limits, and the
     second the corresponding counts: there are 16 digits inside the
     interval '[0, 1.8]', 24 digits in '(1.8, 3.6]', and so on.

          (%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]]

     Optional argument indicates we want 7 classes with limits '-2' and
     '12':

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) continuous_freq (s1, [-2,12,7]);
          (%o3) [[- 2, 0, 2, 4, 6, 8, 10, 12], [8, 20, 22, 17, 20, 13, 0]]

     Optional argument indicates we want the default number of classes
     with limits '-2' and '12':

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) continuous_freq (s1, [-2,12]);
                          3  4  11  18     32  39  46  53
          (%o3)  [[- 2, - -, -, --, --, 5, --, --, --, --, 12],
                          5  5  5   5      5   5   5   5
                         [0, 8, 20, 12, 18, 9, 8, 25, 0, 0]]

 -- 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 + 8144.999999999999
          (%o3) [-----------, ---, 87.178, ------------------------,
                     100      10                     100
                                                              3 NA + 19587
                                                      18.123, ------------]
                                                                  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: Package descriptive

39.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.170835096721089, 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
          (%i5) s2 : read_matrix (file_search ("wind.data"))$
          (%i6) noncentral_moment (s2, 5);
          (%o6) [319793.8724761505, 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
          (%i5) s2 : read_matrix (file_search ("wind.data"))$
          (%i6) central_moment (s2, 3);
          (%o6) [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.022500000000001,
                                      8.729999999999999, 6.649999999999999]

     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,
             - .4275233490482861, - .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)                  .009196180476450424
          (%i4) s2 : read_matrix (file_search ("wind.data"))$
          (%i5) skewness (s2);
          (%o5) [.1580509020000978, .2926379232061854, .09242174416107717,
                                      .2059984348148687, .2142520248890831]

     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, .2105263157894735]

     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: Package descriptive

39.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:
          Peña, D. (2002) <Aná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.4651792608501, 6.636590811800795, 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.4651792608501, 6.636590811800795, 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: Package descriptive

39.5 Functions and Variables for statistical graphs
===================================================

 -- Function: barsplot (<data1>, <data2>, ..., <option_1>, <option_2>,
          ...)
 -- Function: barsplot_description (...)

     Plots bars diagrams for discrete statistical variables, both for
     one or multiple samples.

     <data> can be a list of outcomes representing one sample, or a
     matrix of <m> rows and <n> columns, representing <n> samples of
     size <m> each.

     Available options are:

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

        * <grouping> (default, 'clustered'): indicates how multiple
          samples are shown.  Valid values are: 'clustered' and
          'stacked'.

        * <groups_gap> (default, '1'): a positive integer number
          representing the gap between two consecutive groups of bars.

        * <bars_colors> (default, '[]'): a list of colors for multiple
          samples.  When there are more samples than specified colors,
          the extra necesary colors are chosen at random.  See 'color'
          to learn more about them.

        * <frequency> (default, 'absolute'): indicates the scale of the
          ordinates.  Possible values are: 'absolute', 'relative', and
          'percent'.

        * <ordering> (default, 'orderlessp'): possible values are
          'orderlessp' or 'ordergreatp', indicating how statistical
          outcomes should be ordered on the 'x'-axis.

        * <sample_keys> (default, '[]'): a list with the strings to be
          used in the legend.  When the list length is other than '0' or
          the number of samples, an error message is returned.

        * <start_at> (default, '0'): indicates where the plot begins to
          be plotted on the 'x'-axis.

        * All global 'draw' options, except 'xtics', which is internally
          assigned by 'barsplot'.  If you want to set your own values
          for this option or want to build complex scenes, make use of
          'barsplot_description'.  See example below.

        * The following local 'draw' options: 'key', 'color',
          'fill_color', 'fill_density' and 'line_width'.  See also
          'bars'.

     Function 'barsplot_description' creates a graphic object suitable
     for creating complex scenes, together with other graphic objects.
     There is also a function 'wxbarsplot' for creating embedded
     histograms in interfaces wxMaxima and iMaxima.

     Examples:

     Univariate sample in matrix form.  Absolute frequencies.

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

     Two samples of different sizes, with relative frequencies and user
     declared colors.

          (%i1) load (descriptive)$
          (%i2) l1:makelist(random(10),k,1,50)$
          (%i3) l2:makelist(random(10),k,1,100)$
          (%i4) barsplot(
                  l1,l2,
                  box_width    = 1,
                  fill_density = 1,
                  bars_colors  = [black, grey],
                  frequency = relative,
                  sample_keys = ["A", "B"])$

     Four non numeric samples of equal size.

          (%i1) load (descriptive)$
          (%i2) barsplot(
                  makelist([Yes, No, Maybe][random(3)+1],k,1,50),
                  makelist([Yes, No, Maybe][random(3)+1],k,1,50),
                  makelist([Yes, No, Maybe][random(3)+1],k,1,50),
                  makelist([Yes, No, Maybe][random(3)+1],k,1,50),
                  title  = "Asking for something to four groups",
                  ylabel = "# of individuals",
                  groups_gap   = 3,
                  fill_density = 0.5,
                  ordering     = ordergreatp)$

     Stacked bars.

          (%i1) load (descriptive)$
          (%i2) barsplot(
                  makelist([Yes, No, Maybe][random(3)+1],k,1,50),
                  makelist([Yes, No, Maybe][random(3)+1],k,1,50),
                  makelist([Yes, No, Maybe][random(3)+1],k,1,50),
                  makelist([Yes, No, Maybe][random(3)+1],k,1,50),
                  title  = "Asking for something to four groups",
                  ylabel = "# of individuals",
                  grouping     = stacked,
                  fill_density = 0.5,
                  ordering     = ordergreatp)$

     'barsplot' in a multiplot context.

          (%i1) load (descriptive)$
          (%i2) l1:makelist(random(10),k,1,50)$
          (%i3) l2:makelist(random(10),k,1,100)$
          (%i4) bp1 :
                  barsplot_description(
                   l1,
                   box_width = 1,
                   fill_density = 0.5,
                   bars_colors = [blue],
                   frequency = relative)$
          (%i5) bp2 :
                  barsplot_description(
                   l2,
                   box_width = 1,
                   fill_density = 0.5,
                   bars_colors = [red],
                   frequency = relative)$
          (%i6) draw(gr2d(bp1), gr2d(bp2))$

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

 -- Function: boxplot (<data>)
 -- Function: boxplot (<data>, <option_1>, <option_2>, ...)
 -- Function: boxplot_description (...)

     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:

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

        * <box_orientation> (default, 'vertical'): possible values:
          'vertical' and 'horizontal'.

        * All 'draw' options, except 'points_joined', 'point_size',
          'point_type', 'xtics', 'ytics', 'xrange', and 'yrange', which
          are internally assigned by 'boxplot'.  If you want to set your
          own values for this options or want to build complex scenes,
          make use of 'boxplot_description'.

        * The following local 'draw' options: 'key', 'color', and
          'line_width'.

     Function 'boxplot_description' creates a graphic object suitable
     for creating complex scenes, together with other graphic objects.
     There is also a function 'wxboxplot' for creating embedded
     histograms in interfaces wxMaxima and iMaxima.

     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, box_orientation = horizontal)$

 -- 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>, ...)
 -- Function: histogram_description (...)

     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:

        * <nclasses> (default, '10'): number of classes of the
          histogram, or a list indicating the limits of the classes and
          the number of them, or only the limits.

        * <frequency> (default, 'absolute'): indicates the scale of the
          ordinates.  Possible values are: 'absolute', 'relative', and
          'percent'.

        * <htics> (default, 'auto'): format of the histogram tics.
          Possible values are: 'auto', 'endpoints', 'intervals', or a
          list of labels.

        * All global 'draw' options, except 'xrange', 'yrange', and
          'xtics', which are internally assigned by 'histogram'.  If you
          want to set your own values for these options, make use of
          'histogram_description'.  See examples bellow.

        * The following local 'draw' options: 'key', 'color',
          'fill_color', 'fill_density' and 'line_width'.  See also
          'bars'.

     Function 'histogram_description' creates a graphic object suitable
     for creating complex scenes, together with other graphic objects.
     There is also a function 'wxhistogram' for creating embedded
     histograms in interfaces wxMaxima and iMaxima.

     Examples:

     A simple 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)$

     Setting the limits of the histogram to -2 and 12, with 3 classes.
     Also, we introduce predefined tics:

          (%i1) load (descriptive)$
          (%i2) s1 : read_list (file_search ("pidigits.data"))$
          (%i3) histogram (
                     s1,
                     nclasses     = [-2,12,3],
                     htics        = ["A", "B", "C"],
                     terminal     = png,
                     fill_color   = "#23afa0",
                     fill_density = 0.6)$

     We make use of 'histogram_description' for setting the 'xrange' and
     adding an explicit curve into the scene:

          (%i1) load (descriptive)$
          (%i2) ( load("distrib"),
                  m: 14, s: 2,
                  s2: random_normal(m, s, 1000) ) $
          (%i3) draw2d(
                  grid   = true,
                  xrange = [5, 25],
                  histogram_description(
                    s2,
                    nclasses     = 9,
                    frequency    = relative,
                    fill_density = 0.5),
                  explicit(pdf_normal(x,m,s), x, m - 3*s, m + 3* s))$

 -- 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>, ...)
 -- Function: piechart_description (...)

     Similar to 'barsplot', but plots sectors instead of rectangles.

     Available options are:

        * <sector_colors> (default, '[]'): a list of colors for sectors.
          When there are more sectors than specified colors, the extra
          necesary colors are chosen at random.  See 'color' to learn
          more about them.

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

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

        * All global 'draw' options, except 'key', which is internally
          assigned by 'piechart'.  If you want to set your own values
          for this option or want to build complex scenes, make use of
          'piechart_description'.

        * The following local 'draw' options: 'key', 'color',
          'fill_density' and 'line_width'.  See also 'ellipse'.

     Function 'piechart_description' creates a graphic object suitable
     for creating complex scenes, together with other graphic objects.
     There is also a function 'wxpiechart' for creating embedded
     histograms in interfaces wxMaxima and iMaxima.

     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],
                  title   = "Digit frequencies in pi")$

     See also function 'barsplot'.

 -- Function: scatterplot (<list>)
 -- Function: scatterplot (<list>, <option_1>, <option_2>, ...)
 -- Function: scatterplot (<matrix>)
 -- Function: scatterplot (<matrix>, <option_1>, <option_2>, ...)
 -- Function: scatterplot_description (...)

     Plots scatter diagrams both for univariate (<list>) and
     multivariate (<matrix>) samples.

     Available options are the same admitted by 'histogram'.

     Function 'scatterplot_description' creates a graphic object
     suitable for creating complex scenes, together with other graphic
     objects.  There is also a function 'wxscatterplot' for creating
     embedded histograms in interfaces wxMaxima and iMaxima.

     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,
                  dimensions = [600,150])$

     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), nclasses=4)$

     Five dimensional scatter plot, with five classes histograms.

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

     For plotting isolated or line-joined points in two and three
     dimensions, see 'points'.  See also 'histogram'.

 -- Function: starplot (<data1>, <data2>, ..., <option_1>, <option_2>,
          ...)
 -- Function: starplot_description (...)

     Plots star diagrams for discrete statistical variables, both for
     one or multiple samples.

     <data> can be a list of outcomes representing one sample, or a
     matrix of <m> rows and <n> columns, representing <n> samples of
     size <m> each.

     Available options are:

        * <stars_colors> (default, '[]'): a list of colors for multiple
          samples.  When there are more samples than specified colors,
          the extra necesary colors are chosen at random.  See 'color'
          to learn more about them.

        * <frequency> (default, 'absolute'): indicates the scale of the
          radii.  Possible values are: 'absolute' and 'relative'.

        * <ordering> (default, 'orderlessp'): possible values are
          'orderlessp' or 'ordergreatp', indicating how statistical
          outcomes should be ordered.

        * <sample_keys> (default, '[]'): a list with the strings to be
          used in the legend.  When the list length is other than 0 or
          the number of samples, an error message is returned.

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

        * <star_radius> (default, '1'): diagram's radius.

        * All global 'draw' options, except 'points_joined',
          'point_type', and 'key', which are internally assigned by
          'starplot'.  If you want to set your own values for this
          options or want to build complex scenes, make use of
          'starplot_description'.

        * The following local 'draw' option: 'line_width'.

     Function 'starplot_description' creates a graphic object suitable
     for creating complex scenes, together with other graphic objects.
     There is also a function 'wxstarplot' for creating embedded
     histograms in interfaces wxMaxima and iMaxima.

     Example:

     Plot based on absolute frequencies.  Location and radius defined by
     the user.

          (%i1) load (descriptive)$
          (%i2) l1: makelist(random(10),k,1,50)$
          (%i3) l2: makelist(random(10),k,1,200)$
          (%i4) starplot(
                  l1, l2,
                  stars_colors = [blue,red],
                  sample_keys = ["1st sample", "2nd sample"],
                  star_center = [1,2],
                  star_radius = 4,
                  proportional_axes = xy,
                  line_width = 2 ) $

 -- Function: stemplot (<data>)
 -- Function: stemplot (<data>, <option>)

     Plots stem and leaf diagrams.  Unique available option is:

        * <leaf_unit> (default, '1'): indicates the unit of the leaves;
          must be a power of '10'.

     Example:

          (%i1) load (descriptive)$
          (%i2) load(distrib)$
          (%i3) stemplot(
                  random_normal(15, 6, 100),
                  leaf_unit = 0.1);
          -5|4
           0|37
           1|7
           3|6
           4|4
           5|4
           6|57
           7|0149
           8|3
           9|1334588
          10|07888
          11|01144467789
          12|12566889
          13|24778
          14|047
          15|223458
          16|4
          17|11557
          18|000247
          19|4467799
          20|00
          21|1
          22|2335
          23|01457
          24|12356
          25|455
          27|79
          key: 6|3 =  6.3
          (%o3)                  done


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

40 diag
*******

* Menu:

* Functions and Variables for diag::


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

40.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 'jordan'.

     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.

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

     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  ]


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

41 Package 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: Package distrib,  Up: Package distrib

41.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)
        Finite discrete      (*general_finite_discrete)

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: Package distrib

41.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)'.

          (%i1) load (distrib)$
          (%i2) quantile_normal(95/100,0,1);
                                                9
          (%o2)             sqrt(2) inverse_erf(--)
                                                10
          (%i3) float(%);
          (%o3)               1.644853626951472

 -- 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 degrees of freedom.  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 degrees of freedom.

          (%i1) load (distrib)$
          (%i2) cdf_student_t(1/2, 7/3);
                                                   7  1  28
                       beta_incomplete_regularized(-, -, --)
                                                   6  2  31
          (%o2)    1 - -------------------------------------
                                         2
          (%i3) float(%);
          (%o3)                .6698450596140415

 -- 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_noncentral_student_t (<x>, <n>, <ncp>)

     Returns the value at <x> of the density function of a noncentral
     Student random variable nc_t(n,ncp), with n>0 degrees of freedom
     and noncentrality parameter ncp.  To make use of this function,
     write first 'load(distrib)'.

     Sometimes an extra work is necessary to get the final result.

          (%i1) load (distrib)$
          (%i2) expand(pdf_noncentral_student_t(3,5,0.1));
                 .01370030107589574 sqrt(5)
          (%o2)  --------------------------
                 sqrt(2) sqrt(14) sqrt(%pi)
             1.654562884111515E-4 sqrt(5)
           + ----------------------------
                      sqrt(%pi)
             .02434921505438663 sqrt(5)
           + --------------------------
                        %pi
          (%i3) float(%);
          (%o3)          .02080593159405669

 -- Function: cdf_noncentral_student_t (<x>, <n>, <ncp>)

     Returns the value at <x> of the distribution function of a
     noncentral Student random variable nc_t(n,ncp), with n>0 degrees of
     freedom and noncentrality parameter ncp.  This function has no
     closed form and it is numerically computed if the global variable
     'numer' equals 'true' or at least one of the arguments is a float,
     otherwise it returns a nominal expression.

          (%i1) load (distrib)$
          (%i2) cdf_noncentral_student_t(-2,5,-5);
          (%o2) cdf_noncentral_student_t(- 2, 5, - 5)
          (%i3) cdf_noncentral_student_t(-2.0,5,-5);
          (%o3)          .9952030093319743

 -- Function: quantile_noncentral_student_t (<q>, <n>, <ncp>)

     Returns the <q>-quantile of a noncentral Student random variable
     nc_t(n,ncp), with n>0 degrees of freedom and noncentrality
     parameter ncp; in other words, this is the inverse of
     'cdf_noncentral_student_t'.  Argument <q> must be an element of
     [0,1].  To make use of this function, write first 'load(distrib)'.

 -- Function: mean_noncentral_student_t (<n>, <ncp>)

     Returns the mean of a noncentral Student random variable
     nc_t(n,ncp), with n>1 degrees of freedom and noncentrality
     parameter ncp.  To make use of this function, write first
     'load(distrib)'.

          (%i1) load (distrib)$
          (%i2) (assume(df>1), mean_noncentral_student_t(df,k));
                             df - 1
                       gamma(------) sqrt(df) k
                               2
          (%o2)        ------------------------
                                        df
                          sqrt(2) gamma(--)
                                        2

 -- Function: var_noncentral_student_t (<n>, <ncp>)

     Returns the variance of a noncentral Student random variable
     nc_t(n,ncp), with n>2 degrees of freedom and noncentrality
     parameter ncp.  To make use of this function, write first
     'load(distrib)'.

 -- Function: std_noncentral_student_t (<n>, <ncp>)

     Returns the standard deviation of a noncentral Student random
     variable nc_t(n,ncp), with n>2 degrees of freedom and noncentrality
     parameter ncp.  To make use of this function, write first
     'load(distrib)'.

 -- Function: skewness_noncentral_student_t (<n>, <ncp>)

     Returns the skewness coefficient of a noncentral Student random
     variable nc_t(n,ncp), with n>3 degrees of freedom and noncentrality
     parameter ncp.  To make use of this function, write first
     'load(distrib)'.

 -- Function: kurtosis_noncentral_student_t (<n>, <ncp>)

     Returns the kurtosis coefficient of a noncentral Student random
     variable nc_t(n,ncp), with n>4 degrees of freedom and noncentrality
     parameter ncp.  To make use of this function, write first
     'load(distrib)'.

 -- Function: random_noncentral_student_t (<n>, <ncp>)
 -- Function: random_noncentral_student_t (<n>, <ncp>, <m>)

     Returns a noncentral Student random variate nc_t(n,ncp), with n>0.
     Calling 'random_noncentral_student_t' with a third argument <m>, a
     random sample of size <m> will be simulated.

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

     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.

          (%i1) load (distrib)$
          (%i2) cdf_chi2(3,4);
                                                         3
          (%o2)      1 - gamma_incomplete_regularized(2, -)
                                                         2
          (%i3) float(%);
          (%o3)               .4421745996289256

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

          (%i1) load (distrib)$
          (%i2) cdf_f(2,3,9/4);
                                                   9  3  3
          (%o2)    1 - beta_incomplete_regularized(-, -, --)
                                                   8  2  11
          (%i3) float(%);
          (%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)'.

          (%i1) load (distrib)$
          (%i2) quantile_lognormal(95/100,0,1);
                            sqrt(2) inverse_erf(9/10)
          (%o2)           %e
          (%i3) float(%);
          (%o3)               5.180251602233015

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

          (%i1) load (distrib)$
          (%i2) cdf_gamma(3,5,21);
                                                        1
          (%o2)     1 - gamma_incomplete_regularized(5, -)
                                                        7
          (%i3) float(%);
          (%o3)              4.402663157376807E-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 combination 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.

          (%i1) load (distrib)$
          (%i2) cdf_beta(1/3,15,2);
                                       11
          (%o2)                     --------
                                    14348907
          (%i3) float(%);
          (%o3)              7.666089131388195E-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: Package distrib

41.3 Functions and Variables for discrete distributions
=======================================================

 -- Function: pdf_general_finite_discrete (<x>, <v>)

     Returns the value at <x> of the probability function of a general
     finite discrete random variable, with vector probabilities v, such
     that 'Pr(X=i) = v_i'.  Vector v can be a list of nonnegative
     expressions, whose components will be normalized to get a vector of
     probabilities.  To make use of this function, write first
     'load(distrib)'.

     Examples:

          (%i1) load (distrib)$
          (%i2) pdf_general_finite_discrete(2, [1/7, 4/7, 2/7]);
                                          4
          (%o2)                           -
                                          7
          (%i3) pdf_general_finite_discrete(2, [1, 4, 2]);
                                          4
          (%o3)                           -
                                          7

 -- Function: cdf_general_finite_discrete (<x>, <v>)

     Returns the value at <x> of the distribution function of a general
     finite discrete random variable, with vector probabilities v.

     See 'pdf_general_finite_discrete' for more details.

     Examples:

          (%i1) load (distrib)$
          (%i2) cdf_general_finite_discrete(2, [1/7, 4/7, 2/7]);
                                          5
          (%o2)                           -
                                          7
          (%i3) cdf_general_finite_discrete(2, [1, 4, 2]);
                                          5
          (%o3)                           -
                                          7
          (%i4) cdf_general_finite_discrete(2+1/2, [1, 4, 2]);
                                          5
          (%o4)                           -
                                          7

 -- Function: quantile_general_finite_discrete (<q>, <v>)

     Returns the <q>-quantile of a general finite discrete random
     variable, with vector probabilities v.

     See 'pdf_general_finite_discrete' for more details.

 -- Function: mean_general_finite_discrete (<v>)

     Returns the mean of a general finite discrete random variable, with
     vector probabilities v.

     See 'pdf_general_finite_discrete' for more details.

 -- Function: var_general_finite_discrete (<v>)

     Returns the variance of a general finite discrete random variable,
     with vector probabilities v.

     See 'pdf_general_finite_discrete' for more details.

 -- Function: std_general_finite_discrete (<v>)

     Returns the standard deviation of a general finite discrete random
     variable, with vector probabilities v.

     See 'pdf_general_finite_discrete' for more details.

 -- Function: skewness_general_finite_discrete (<v>)

     Returns the skewness coefficient of a general finite discrete
     random variable, with vector probabilities v.

     See 'pdf_general_finite_discrete' for more details.

 -- Function: kurtosis_general_finite_discrete (<v>)

     Returns the kurtosis coefficient of a general finite discrete
     random variable, with vector probabilities v.

     See 'pdf_general_finite_discrete' for more details.

 -- Function: random_general_finite_discrete (<v>)
 -- Function: random_general_finite_discrete (<v>, <m>)

     Returns a general finite discrete random variate, with vector
     probabilities v.  Calling 'random_general_finite_discrete' with a
     second argument <m>, a random sample of size <m> will be simulated.

     See 'pdf_general_finite_discrete' for more details.

     Examples:

          (%i1) load (distrib)$
          (%i2) random_general_finite_discrete([1,3,1,5]);
          (%o2)                          4
          (%i3) random_general_finite_discrete([1,3,1,5], 10);
          (%o3)           [4, 2, 2, 3, 2, 4, 4, 1, 2, 2]

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

          (%i1) load (distrib)$
          (%i2) cdf_binomial(5,7,1/6);
                                      7775
          (%o2)                       ----
                                      7776
          (%i3) float(%);
          (%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.

          (%i1) load (distrib)$
          (%i2) cdf_poisson(3,5);
          (%o2)       gamma_incomplete_regularized(4, 5)
          (%i3) float(%);
          (%o3)               .2650259152973623

 -- 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.  Being <n1> the number of
     objects of class A, <n2> the number of objects of class B, and <n>
     the size of the sample without replacement, this function returns
     the probability of event "exactly <x> objects are of class A".

     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.  See 'pdf_hypergeometric' for a
     more complete description.

     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.

          (%i1) load (distrib)$
          (%i2) cdf_negative_binomial(3,4,1/8);
                                      3271
          (%o2)                      ------
                                     524288
          (%i3) float(%);
          (%o3)              .006238937377929687

 -- 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: drawdf,  Prev: Package distrib,  Up: Top

42 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

42.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://riotorto.users.sourceforge.net/gnuplot>

You need Gnuplot 4.2 or newer to run this program.


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

42.2 Functions and Variables for draw
=====================================

42.2.1 Scenes
-------------

 -- Scene constructor: gr2d (<graphic option>, ..., <graphic object>,
          ...)

     Function 'gr2d' builds an object describing a 2D scene.  Arguments
     are graphic options, graphic objects, or lists containing both
     graphic options and objects.  This scene is interpreted
     sequentially: graphic options affect those graphic objects placed
     on its right.  Some graphic options affect the global appearence of
     the scene.

     This is the list of graphic objects available for scenes in two
     dimensions:
     'bars',
     'ellipse',
     'explicit',
     'image',
     'implicit',
     'label',
     'parametric',
     'points',
     'polar',
     'polygon',
     'quadrilateral',
     'rectangle',
     'triangle',
     'vector', and
     'geomap' (this one defined in package 'worldmap').

     See also 'draw' and 'draw2d'.  To make use of this object, write
     first 'load(draw)'.

 -- Scene constructor: gr3d (<graphic option>, ..., <graphic object>,
          ...)

     Function 'gr3d' builds an object describing a 3d scene.  Arguments
     are graphic options, graphic objects, or lists containing both
     graphic options and objects.  This scene is interpreted
     sequentially: graphic options affect those graphic objects placed
     on its right.  Some graphic options affect the global appearence of
     the scene.

     This is the list of graphic objects available for scenes in three
     dimensions:
     'cylindrical',
     'elevation_grid',
     'explicit',
     'implicit',
     'label',
     'mesh',
     'parametric',
     'parametric_surface',
     'points',
     'quadrilateral',
     'spherical',
     'triangle',
     'tube',
     'vector', and
     'geomap' (this one defined in package 'worldmap').

     See also 'draw' and 'draw3d'.  To make use of this object, write
     first 'load(draw)'.

42.2.2 Functions
----------------

 -- Function: draw (<gr2d>, ..., <gr3d>, ..., <options>, ...)

     Plots a series of scenes; its arguments are 'gr2d' and/or 'gr3d'
     objects, together with some options, or lists of scenes and
     options.  By default, the scenes are put together in one column.

     Function 'draw' accepts the following global options: 'terminal',
     'columns', 'dimensions', 'file_name' and 'delay'.

     Functions 'draw2d' and 'draw3d' are short cuts to be used when only
     one scene is required, in two or three dimensions, respectively.

     See also 'gr2d' and 'gr3d'.  To make use of this function, write
     first 'load(draw)'.

     Example:

          (%i1) load(draw)$
          (%i2) scene1: gr2d(title="Ellipse",
                             nticks=30,
                             parametric(2*cos(t),5*sin(t),t,0,2*%pi))$
          (%i3) scene2: gr2d(title="Triangle",
                             polygon([4,5,7],[6,4,2]))$
          (%i4) draw(scene1, scene2, columns = 2)$

     The two draw sentences are equivalent:

          (%i1) load(draw)$
          (%i2) draw(gr3d(explicit(x^2+y^2,x,-1,1,y,-1,1)));
          (%o2)                          [gr3d(explicit)]
          (%i3) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1));
          (%o3)                          [gr3d(explicit)]

     An animated gif file:

          (%i1) load(draw)$
          (%i2) draw(
                  delay     = 100,
                  file_name = "zzz",
                  terminal  = 'animated_gif,
                  gr2d(explicit(x^2,x,-1,1)),
                  gr2d(explicit(x^3,x,-1,1)),
                  gr2d(explicit(x^4,x,-1,1)));
          End of animation sequence
          (%o2)          [gr2d(explicit), gr2d(explicit), gr2d(explicit)]

     See also 'gr2d', 'gr3d', 'draw2d' and 'draw3d'.

 -- Function: draw2d (<option>, <graphic_object>, ...)

     This function is a short cut for 'draw(gr2d(<options>, ...,
     <graphic_object>, ...))'.

     It can be used to plot a unique scene in 2d.

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

     See also 'draw' and 'gr2d'.

 -- Function: draw3d (<option>, <graphic_object>, ...)

     This function is a short cut for 'draw(gr3d(<options>, ...,
     <graphic_object>, ...))'.

     It can be used to plot a unique scene in 3d.

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

     See also 'draw' and 'gr3d'.

 -- Function: draw_file (<graphic option>, ..., <graphic object>, ...)

     Saves the current plot into a file.  Accepted graphics options are:
     'terminal', 'dimensions', 'file_name' and 'background_color'.

     Example:

          (%i1) load(draw)$
          (%i2) /* screen plot */
                draw(gr3d(explicit(x^2+y^2,x,-1,1,y,-1,1)))$
          (%i3) /* same plot in eps format */
                draw_file(terminal  = eps,
                          dimensions = [5,5]) $

 -- Function: multiplot_mode (<term>)

     This function enables Maxima to work in one-window multiplot mode
     with terminal <term>; accepted arguments for this function are
     'screen', 'wxt', 'aquaterm' and 'none'.

     When multiplot mode is enabled, each call to 'draw' sends a new
     plot to the same window, without erasing the previous ones.  To
     disable the multiplot mode, write 'multiplot_mode(none)'.

     When multiplot mode is enabled, global option 'terminal' is blocked
     and you have to disable this working mode before changing to
     another terminal.

     This feature does not work in Windows platforms.

     Example:

          (%i1) load(draw)$
          (%i2) set_draw_defaults(
                   xrange = [-1,1],
                   yrange = [-1,1],
                   grid   = true,
                   title  = "Step by step plot" )$
          (%i3) multiplot_mode(screen)$
          (%i4) draw2d(color=blue,  explicit(x^2,x,-1,1))$
          (%i5) draw2d(color=red,   explicit(x^3,x,-1,1))$
          (%i6) draw2d(color=brown, explicit(x^4,x,-1,1))$
          (%i7) multiplot_mode(none)$

 -- Function: set_draw_defaults (<graphic option>, ..., <graphic
          object>, ...)

     Sets user graphics options.  This function is useful for plotting a
     sequence of graphics with common graphics options.  Calling this
     function without arguments removes user defaults.

     Example:

          (%i1) load(draw)$
          (%i2) set_draw_defaults(
                   xrange = [-10,10],
                   yrange = [-2, 2],
                   color  = blue,
                   grid   = true)$
          (%i3) /* plot with user defaults */
                draw2d(explicit(((1+x)**2/(1+x*x))-1,x,-10,10))$
          (%i4) set_draw_defaults()$
          (%i5) /* plot with standard defaults */
                draw2d(explicit(((1+x)**2/(1+x*x))-1,x,-10,10))$

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

42.2.3 Graphics options
-----------------------

 -- Graphic option: adapt_depth
     Default value: 10

     'adapt_depth' is the maximum number of splittings used by the
     adaptive plotting routine.

     This option is relevant only for 2d 'explicit' functions.

 -- Graphic option: axis_3d
     Default value: 'true'

     If 'axis_3d' is 'true', the <x>, <y> and <z> axis are shown in 3d
     scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(axis_3d = false,
                       explicit(sin(x^2+y^2),x,-2,2,y,-2,2) )$

     See also 'axis_bottom', 'axis_left', 'axis_top', and 'axis_right'
     for axis in 2d.

 -- Graphic option: axis_bottom
     Default value: 'true'

     If 'axis_bottom' is 'true', the bottom axis is shown in 2d scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(axis_bottom = false,
                       explicit(x^3,x,-1,1))$

     See also 'axis_left', 'axis_top', 'axis_right', and 'axis_3d'.

 -- Graphic option: axis_left
     Default value: 'true'

     If 'axis_left' is 'true', the left axis is shown in 2d scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(axis_left = false,
                       explicit(x^3,x,-1,1))$

     See also 'axis_bottom', 'axis_top', 'axis_right', and 'axis_3d'.

 -- Graphic option: axis_right
     Default value: 'true'

     If 'axis_right' is 'true', the right axis is shown in 2d scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(axis_right = false,
                       explicit(x^3,x,-1,1))$

     See also 'axis_bottom', 'axis_left', 'axis_top', and 'axis_3d'.

 -- Graphic option: axis_top
     Default value: 'true'

     If 'axis_top' is 'true', the top axis is shown in 2d scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(axis_top = false,
                       explicit(x^3,x,-1,1))$

     See also 'axis_bottom', 'axis_left', 'axis_right', and 'axis_3d'.

 -- Graphic option: background_color
     Default value: 'white'

     Sets the background color for terminals 'gif', 'png', 'jpg', and
     'gif'.  Default background color is white.

     This option das not work with terminals 'epslatex' and
     'epslatex_standalone'.

     See also 'color'.

 -- Graphic option: border
     Default value: 'true'

     If 'border' is 'true', borders of polygons are painted according to
     'line_type' and 'line_width'.

     This option affects the following graphic objects:
        * 'gr2d': 'polygon', 'rectangle', and 'ellipse'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(color       = brown,
                       line_width  = 8,
                       polygon([[3,2],[7,2],[5,5]]),
                       border      = false,
                       fill_color  = blue,
                       polygon([[5,2],[9,2],[7,5]]) )$

 -- Graphic option: cbrange
     Default value: 'auto'

     If 'cbrange' is 'auto', the range for the values which are colored
     when 'enhanced3d' is not 'false' is computed automatically.  Values
     outside of the color range use color of the nearest extreme.

     When 'enhanced3d' or 'colorbox' is 'false', option 'cbrange' has no
     effect.

     If the user wants a specific interval for the colored values, it
     must be given as a Maxima list, as in 'cbrange=[-2, 3]'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d (
                  enhanced3d     = true,
                  color          = green,
                  cbrange = [-3,10],
                  explicit(x^2+y^2, x,-2,2,y,-2,2)) $

     See also 'enhanced3d', 'colorbox' and 'cbtics'.

 -- Graphic option: cbtics
     Default value: 'auto'

     This graphic option controls the way tic marks are drawn on the
     colorbox when option 'enhanced3d' is not 'false'.

     When 'enhanced3d' or 'colorbox' is 'false', option 'cbtics' has no
     effect.

     See 'xtics' for a complete description.

     Example :

          (%i1) load(draw)$
          (%i2) draw3d (
                  enhanced3d = true,
                  color      = green,
                  cbtics  = {["High",10],["Medium",05],["Low",0]},
                  cbrange = [0, 10],
                  explicit(x^2+y^2, x,-2,2,y,-2,2)) $

     See also 'enhanced3d', 'colorbox' and 'cbrange'.

 -- Graphic option: color
     Default value: 'blue'

     'color' specifies the color for plotting lines, points, borders of
     polygons and labels.

     Colors can be given as names or in hexadecimal rgb code.

     Available color names are:
     white            black            gray0            grey0
     gray10           grey10           gray20           grey20
     gray30           grey30           gray40           grey40
     gray50           grey50           gray60           grey60
     gray70           grey70           gray80           grey80
     gray90           grey90           gray100          grey100
     gray             grey             light_gray       light_grey
     dark_gray        dark_grey        red              light_red
     dark_red         yellow           light_yellow     dark_yellow
     green            light_green      dark_green       spring_green
     forest_green     sea_green        blue             light_blue
     dark_blue        midnight_blue    navy             medium_blue
     royalblue        skyblue          cyan             light_cyan
     dark_cyan        magenta          light_magenta    dark_magenta
     turquoise        light_turquoise  dark_turquoise   pink
     light_pink       dark_pink        coral            light_coral
     orange_red       salmon           light_salmon     dark_salmon
     aquamarine       khaki            dark_khaki       goldenrod
     light_goldenrod  dark_goldenrod   gold             beige
     brown            orange           dark_orange      violet
     dark_violet      plum             purple

     Cromatic componentes in hexadecimal code are introduced in the form
     '"#rrggbb"'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^2,x,_1,1), /* default is black */
                       color = red,
                       explicit(0.5 + x^2,x,-1,1),
                       color = blue,
                       explicit(1 + x^2,x,-1,1),
                       color = light_blue,
                       explicit(1.5 + x^2,x,-1,1),
                       color = "#23ab0f",
                       label(["This is a label",0,1.2])  )$

     See also 'fill_color'.

 -- Graphic option: colorbox
     Default value: 'true'

     If 'colorbox' is 'true', a color scale without label is drawn
     together with 'image' 2D objects, or coloured 3d objects.  If
     'colorbox' is 'false', no color scale is shown.  If 'colorbox' is a
     string, a color scale with label is drawn.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

     Color scale and images.

          (%i1) load(draw)$
          (%i2) im: apply('matrix,
                           makelist(makelist(random(200),i,1,30),i,1,30))$
          (%i3) draw2d(image(im,0,0,30,30))$
          (%i4) draw2d(colorbox = false, image(im,0,0,30,30))$

     Color scale and 3D coloured object.

          (%i1) load(draw)$
          (%i2) draw3d(
                  colorbox   = "Magnitude",
                  enhanced3d = true,
                  explicit(x^2+y^2,x,-1,1,y,-1,1))$

     See also 'palette'.

 -- Graphic option: columns
     Default value: 1

     'columns' is the number of columns in multiple plots.

     Since this is a global graphics option, its position in the scene
     description does not matter.  It can be also used as an argument of
     function 'draw'.

     Example:

          (%i1) load(draw)$
          (%i2) scene1: gr2d(title="Ellipse",
                             nticks=30,
                             parametric(2*cos(t),5*sin(t),t,0,2*%pi))$
          (%i3) scene2: gr2d(title="Triangle",
                             polygon([4,5,7],[6,4,2]))$
          (%i4) draw(scene1, scene2, columns = 2)$

 -- Graphic option: contour
     Default value: 'none'

     Option 'contour' enables the user to select where to plot contour
     lines.  Possible values are:

        * 'none': no contour lines are plotted.

        * 'base': contour lines are projected on the xy plane.

        * 'surface': contour lines are plotted on the surface.

        * 'both': two contour lines are plotted: on the xy plane and on
          the surface.

        * 'map': contour lines are projected on the xy plane, and the
          view point is set just in the vertical.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(20*exp(-x^2-y^2)-10,x,0,2,y,-3,3),
                       contour_levels = 15,
                       contour        = both,
                       surface_hide   = true) $

 -- Graphic option: contour_levels
     Default value: 5

     This graphic option controls the way contours are drawn.
     'contour_levels' can be set to a positive integer number, a list of
     three numbers or an arbitrary set of numbers:

        * When option 'contour_levels' is bounded to positive integer
          <n>, <n> contour lines will be drawn at equal intervals.  By
          default, five equally spaced contours are plotted.

        * When option 'contour_levels' is bounded to a list of length
          three of the form '[lowest,s,highest]', contour lines are
          plotted from 'lowest' to 'highest' in steps of 's'.

        * When option 'contour_levels' is bounded to a set of numbers of
          the form '{n1, n2, ...}', contour lines are plotted at values
          'n1', 'n2', ...

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Examples:

     Ten equally spaced contour lines.  The actual number of levels can
     be adjusted to give simple labels.

          (%i1) load(draw)$
          (%i2) draw3d(color = green,
                       explicit(20*exp(-x^2-y^2)-10,x,0,2,y,-3,3),
                       contour_levels = 10,
                       contour        = both,
                       surface_hide   = true) $

     From -8 to 8 in steps of 4.

          (%i1) load(draw)$
          (%i2) draw3d(color = green,
                       explicit(20*exp(-x^2-y^2)-10,x,0,2,y,-3,3),
                       contour_levels = [-8,4,8],
                       contour        = both,
                       surface_hide   = true) $

     Isolines at levels -7, -6, 0.8 and 5.

          (%i1) load(draw)$
          (%i2) draw3d(color = green,
                       explicit(20*exp(-x^2-y^2)-10,x,0,2,y,-3,3),
                       contour_levels = {-7, -6, 0.8, 5},
                       contour        = both,
                       surface_hide   = true) $

     See also 'contour'.

 -- Graphic option: data_file_name
     Default value: '"data.gnuplot"'

     This is the name of the file with the numeric data needed by
     Gnuplot to build the requested plot.

     Since this is a global graphics option, its position in the scene
     description does not matter.  It can be also used as an argument of
     function 'draw'.

     See example in 'gnuplot_file_name'.

 -- Graphic option: delay
     Default value: 5

     This is the delay in 1/100 seconds of frames in animated gif files.

     Since this is a global graphics option, its position in the scene
     description does not matter.  It can be also used as an argument of
     function 'draw'.

     Example:

          (%i1) load(draw)$
          (%i2) draw(
                  delay     = 100,
                  file_name = "zzz",
                  terminal  = 'animated_gif,
                  gr2d(explicit(x^2,x,-1,1)),
                  gr2d(explicit(x^3,x,-1,1)),
                  gr2d(explicit(x^4,x,-1,1)));
          End of animation sequence
          (%o2)          [gr2d(explicit), gr2d(explicit), gr2d(explicit)]

     Option 'delay' is only active in animated gif's; it is ignored in
     any other case.

     See also 'terminal', 'dimensions'.

 -- Graphic option: dimensions
     Default value: '[600,500]'

     Dimensions of the output terminal.  Its value is a list formed by
     the width and the height.  The meaning of the two numbers depends
     on the terminal you are working with.

     With terminals 'gif', 'animated_gif', 'png', 'jpg', 'svg',
     'screen', 'wxt', and 'aquaterm', the integers represent the number
     of points in each direction.  If they are not intergers, they are
     rounded.

     With terminals 'eps', 'eps_color', 'pdf', and 'pdfcairo', both
     numbers represent hundredths of cm, which means that, by default,
     pictures in these formats are 6 cm in width and 5 cm in height.

     Since this is a global graphics option, its position in the scene
     description does not matter.  It can be also used as an argument of
     function 'draw'.

     Examples:

     Option 'dimensions' applied to file output and to wxt canvas.

          (%i1) load(draw)$
          (%i2) draw2d(
                  dimensions = [300,300],
                  terminal   = 'png,
                  explicit(x^4,x,-1,1)) $
          (%i3) draw2d(
                  dimensions = [300,300],
                  terminal   = 'wxt,
                  explicit(x^4,x,-1,1)) $

     Option 'dimensions' applied to eps output.  We want an eps file
     with A4 portrait dimensions.

          (%i1) load(draw)$
          (%i2) A4portrait: 100*[21, 29.7]$
          (%i3) draw3d(
                  dimensions = A4portrait,
                  terminal   = 'eps,
                  explicit(x^2-y^2,x,-2,2,y,-2,2)) $

 -- Graphic option: draw_realpart
     Default value: 'true'

     When 'true', functions to be drawn are considered as complex
     functions whose real part value should be plotted; when 'false',
     nothing will be plotted when the function does not give a real
     value.

     This option affects objects 'explicit' and 'parametric' in 2D and
     3D, and 'parametric_surface'.

     Example:

     Option 'draw_realpart' affects objects 'explicit' and 'parametric'.

          (%i1) load(draw)$
          (%i2) draw2d(
                  draw_realpart = false,
                  explicit(sqrt(x^2  - 4*x) - x, x, -1, 5),
                  color         = red,
                  draw_realpart = true,
                  parametric(x,sqrt(x^2  - 4*x) - x + 1, x, -1, 5) );

 -- Graphic option: enhanced3d
     Default value: 'none'

     If 'enhanced3d' is 'none', surfaces are not colored in 3D plots.
     In order to get a colored surface, a list must be assigned to
     option 'enhanced3d', where the first element is an expression and
     the rest are the names of the variables or parameters used in that
     expression.  A list such '[f(x,y,z), x, y, z]' means that point
     '[x,y,z]' of the surface is assigned number 'f(x,y,z)', which will
     be colored according to the actual 'palette'.  For those 3D graphic
     objects defined in terms of parameters, it is possible to define
     the color number in terms of the parameters, as in '[f(u), u]', as
     in objects 'parametric' and 'tube', or '[f(u,v), u, v]', as in
     object 'parametric_surface'.  While all 3D objects admit the model
     based on absolute coordinates, '[f(x,y,z), x, y, z]', only two of
     them, namely 'explicit' and 'elevation_grid', accept also models
     defined on the '[x,y]' coordinates, '[f(x,y), x, y]'.  3D graphic
     object 'implicit' accepts only the '[f(x,y,z), x, y, z]' model.
     Object 'points' accepts also the '[f(x,y,z), x, y, z]' model, but
     when points have a chronological nature, model '[f(k), k]' is also
     valid, being 'k' an ordering parameter.

     When 'enhanced3d' is assigned something different to 'none',
     options 'color' and 'surface_hide' are ignored.

     The names of the variables defined in the lists may be different to
     those used in the definitions of the graphic objects.

     In order to maintain back compatibility, 'enhanced3d = false' is
     equivalent to 'enhanced3d = none', and 'enhanced3d = true' is
     equivalent to 'enhanced3d = [z, x, y, z]'.  If an expression is
     given to 'enhanced3d', its variables must be the same used in the
     surface definition.  This is not necessary when using lists.

     See option 'palette' to learn how palettes are specified.

     Examples:

     'explicit' object with coloring defined by the '[f(x,y,z), x, y,
     z]' model.

          (%i1) load(draw)$
          (%i2) draw3d(
                   enhanced3d = [x-z/10,x,y,z],
                   palette    = gray,
                   explicit(20*exp(-x^2-y^2)-10,x,-3,3,y,-3,3))$

     'explicit' object with coloring defined by the '[f(x,y), x, y]'
     model.  The names of the variables defined in the lists may be
     different to those used in the definitions of the graphic objects;
     in this case, 'r' corresponds to 'x', and 's' to 'y'.

          (%i1) load(draw)$
          (%i2) draw3d(
                   enhanced3d = [sin(r*s),r,s],
                   explicit(20*exp(-x^2-y^2)-10,x,-3,3,y,-3,3))$

     'parametric' object with coloring defined by the '[f(x,y,z), x, y,
     z]' model.

          (%i1) load(draw)$
          (%i2) draw3d(
                   nticks = 100,
                   line_width = 2,
                   enhanced3d = [if y>= 0 then 1 else 0, x, y, z],
                   parametric(sin(u)^2,cos(u),u,u,0,4*%pi)) $

     'parametric' object with coloring defined by the '[f(u), u]' model.
     In this case, '(u-1)^2' is a shortcut for '[(u-1)^2,u]'.

          (%i1) load(draw)$
          (%i2) draw3d(
                   nticks = 60,
                   line_width = 3,
                   enhanced3d = (u-1)^2,
                   parametric(cos(5*u)^2,sin(7*u),u-2,u,0,2))$

     'elevation_grid' object with coloring defined by the '[f(x,y), x,
     y]' model.

          (%i1) load(draw)$
          (%i2) m: apply(
                     matrix,
                     makelist(makelist(cos(i^2/80-k/30),k,1,30),i,1,20)) $
          (%i3) draw3d(
                   enhanced3d = [cos(x*y*10),x,y],
                   elevation_grid(m,-1,-1,2,2),
                   xlabel = "x",
                   ylabel = "y");

     'tube' object with coloring defined by the '[f(x,y,z), x, y, z]'
     model.

          (%i1) load(draw)$
          (%i2) draw3d(
                   enhanced3d = [cos(x-y),x,y,z],
                   palette = gray,
                   xu_grid = 50,
                   tube(cos(a), a, 0, 1, a, 0, 4*%pi) )$

     'tube' object with coloring defined by the '[f(u), u]' model.
     Here, 'enhanced3d = -a' would be the shortcut for 'enhanced3d =
     [-foo,foo]'.

          (%i1) load(draw)$
          (%i2) draw3d(
                   tube_extremes = [open, closed],
                   palette = [26,15,-2],
                   enhanced3d = [-foo, foo],
                   tube(a, a, a^2, 1, a, -2, 2) )$

     'implicit' and 'points' objects with coloring defined by the
     '[f(x,y,z), x, y, z]' model.

          (%i1) load(draw)$
          (%i2) draw3d(
                   enhanced3d = [x-y,x,y,z],
                   implicit((x^2+y^2+z^2-1)*(x^2+(y-1.5)^2+z^2-0.5)=0.015,
                            x,-1,1,y,-1.2,2.3,z,-1,1)) $
          (%i3) m: makelist([random(1.0),random(1.0),random(1.0)],k,1,2000)$
          (%i4) draw3d(
                   point_type = filled_circle,
                   point_size = 2,
                   enhanced3d = [u+v-w,u,v,w],
                   points(m) ) $

     When points have a chronological nature, model '[f(k), k]' is also
     valid, being 'k' an ordering parameter.

          (%i1) load(draw)$
          (%i2) m:makelist([random(1.0), random(1.0), random(1.0)],k,1,5)$
          (%i3) draw3d(
                   enhanced3d = [sin(j), j],
                   point_size = 3,
                   point_type = filled_circle,
                   points_joined = true,
                   points(m)) $

 -- Graphic option: error_type
     Default value: 'y'

     Depending on its value, which can be 'x', 'y', or 'xy', graphic
     object 'errors' will draw points with horizontal, vertical, or
     both, error bars.  When 'error_type=boxes', boxes will be drawn
     instead of crosses.

     See also 'errors'.

 -- Graphic option: file_name
     Default value: '"maxima_out"'

     This is the name of the file where terminals 'png', 'jpg', 'gif',
     'eps', 'eps_color', 'pdf', 'pdfcairo' and 'svg' will save the
     graphic.

     Since this is a global graphics option, its position in the scene
     description does not matter.  It can be also used as an argument of
     function 'draw'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(file_name = "myfile",
                       explicit(x^2,x,-1,1),
                       terminal  = 'png)$

     See also 'terminal', 'dimensions'.

 -- Graphic option: fill_color
     Default value: '"red"'

     'fill_color' specifies the color for filling polygons and 2d
     'explicit' functions.

     See 'color' to learn how colors are specified.

 -- Graphic option: fill_density
     Default value: 0

     'fill_density' is a number between 0 and 1 that specifies the
     intensity of the 'fill_color' in 'bars' objects.

     See 'bars' for examples.

 -- Graphic option: filled_func
     Default value: 'false'

     Option 'filled_func' controls how regions limited by functions
     should be filled.  When 'filled_func' is 'true', the region bounded
     by the function defined with object 'explicit' and the bottom of
     the graphic window is filled with 'fill_color'.  When 'filled_func'
     contains a function expression, then the region bounded by this
     function and the function defined with object 'explicit' will be
     filled.  By default, explicit functions are not filled.

     This option affects only the 2d graphic object 'explicit'.

     Example:

     Region bounded by an 'explicit' object and the bottom of the
     graphic window.
          (%i1) load(draw)$
          (%i2) draw2d(fill_color  = red,
                       filled_func = true,
                       explicit(sin(x),x,0,10) )$

     Region bounded by an 'explicit' object and the function defined by
     option 'filled_func'.  Note that the variable in 'filled_func' must
     be the same as that used in 'explicit'.

          (%i1) load(draw)$
          (%i2) draw2d(fill_color  = grey,
                       filled_func = sin(x),
                       explicit(-sin(x),x,0,%pi));

     See also 'fill_color' and 'explicit'.

 -- Graphic option: font
     Default value: '""' (empty string)

     This option can be used to set the font face to be used by the
     terminal.  Only one font face and size can be used throughout the
     plot.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     See also 'font_size'

     Gnuplot doesn't handle fonts by itself, it leaves this task to the
     support libraries of the different terminals, each one with its own
     philosophy about it.  A brief summary follows:

        * x11: Uses the normal x11 font server mechanism.

          Example:
               (%i1) load(draw)$
               (%i2) draw2d(font      = "Arial",
                            font_size = 20,
                            label(["Arial font, size 20",1,1]))$

        * windows: The windows terminal doesn't support changing of
          fonts from inside the plot.  Once the plot has been generated,
          the font can be changed right-clicking on the menu of the
          graph window.

        * png, jpeg, gif: The libgd library uses the font path stored in
          the environment variable 'GDFONTPATH'; in this case, it is
          only necessary to set option 'font' to the font's name.  It is
          also possible to give the complete path to the font file.

          Examples:

          Option 'font' can be given the complete path to the font file:
               (%i1) load(draw)$
               (%i2) path: "/usr/share/fonts/truetype/freefont/" $
               (%i3) file: "FreeSerifBoldItalic.ttf" $
               (%i4) draw2d(
                       font      = concat(path, file),
                       font_size = 20,
                       color     = red,
                       label(["FreeSerifBoldItalic font, size 20",1,1]),
                       terminal  = png)$

          If environment variable 'GDFONTPATH' is set to the path where
          font files are allocated, it is possible to set graphic option
          'font' to the name of the font.

               (%i1) load(draw)$
               (%i2) draw2d(
                       font      = "FreeSerifBoldItalic",
                       font_size = 20,
                       color     = red,
                       label(["FreeSerifBoldItalic font, size 20",1,1]),
                       terminal  = png)$

        * Postscript: Standard Postscript fonts are:
          '"Times-Roman"',
          '"Times-Italic"',
          '"Times-Bold"',
          '"Times-BoldItalic"',
          '"Helvetica"',
          '"Helvetica-Oblique"',
          '"Helvetica-Bold"',
          '"Helvetic-BoldOblique"',
          '"Courier"',
          '"Courier-Oblique"',
          '"Courier-Bold"', and
          '"Courier-BoldOblique"'.

          Example:

               (%i1) load(draw)$
               (%i2) draw2d(
                       font      = "Courier-Oblique",
                       font_size = 15,
                       label(["Courier-Oblique font, size 15",1,1]),
                       terminal = eps)$

        * pdf: Uses same fonts as Postscript.

        * pdfcairo: Uses same fonts as wxt.

        * wxt: The pango library finds fonts via the 'fontconfig'
          utility.

        * aqua: Default is '"Times-Roman"'.

     The gnuplot documentation is an important source of information
     about terminals and fonts.

 -- Graphic option: font_size
     Default value: 10

     This option can be used to set the font size to be used by the
     terminal.  Only one font face and size can be used throughout the
     plot.  'font_size' is active only when option 'font' is not equal
     to the empty string.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     See also 'font'.

 -- Graphic option: gnuplot_file_name
     Default value: '"maxout.gnuplot"'

     This is the name of the file with the necessary commands to be
     processed by Gnuplot.

     Since this is a global graphics option, its position in the scene
     description does not matter.  It can be also used as an argument of
     function 'draw'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                 file_name = "my_file",
                 gnuplot_file_name = "my_commands_for_gnuplot",
                 data_file_name    = "my_data_for_gnuplot",
                 terminal          = png,
                 explicit(x^2,x,-1,1)) $

     See also 'data_file_name'.

 -- Graphic option: grid
     Default value: 'false'

     If 'grid' is 'true', a grid will be drawn on the <xy> plane.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(grid = true,
                       explicit(exp(u),u,-2,2))$

 -- Graphic option: head_angle
     Default value: 45

     'head_angle' indicates the angle, in degrees, between the arrow
     heads and the segment.

     This option is relevant only for 'vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,10],
                       yrange      = [0,9],
                       head_length = 0.7,
                       head_angle  = 10,
                       vector([1,1],[0,6]),
                       head_angle  = 20,
                       vector([2,1],[0,6]),
                       head_angle  = 30,
                       vector([3,1],[0,6]),
                       head_angle  = 40,
                       vector([4,1],[0,6]),
                       head_angle  = 60,
                       vector([5,1],[0,6]),
                       head_angle  = 90,
                       vector([6,1],[0,6]),
                       head_angle  = 120,
                       vector([7,1],[0,6]),
                       head_angle  = 160,
                       vector([8,1],[0,6]),
                       head_angle  = 180,
                       vector([9,1],[0,6]) )$

     See also 'head_both', 'head_length', and 'head_type'.

 -- Graphic option: head_both
     Default value: 'false'

     If 'head_both' is 'true', vectors are plotted with two arrow heads.
     If 'false', only one arrow is plotted.

     This option is relevant only for 'vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,8],
                       yrange      = [0,8],
                       head_length = 0.7,
                       vector([1,1],[6,0]),
                       head_both   = true,
                       vector([1,7],[6,0]) )$

     See also 'head_length', 'head_angle', and 'head_type'.

 -- Graphic option: head_length
     Default value: 2

     'head_length' indicates, in <x>-axis units, the length of arrow
     heads.

     This option is relevant only for 'vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,12],
                       yrange      = [0,8],
                       vector([0,1],[5,5]),
                       head_length = 1,
                       vector([2,1],[5,5]),
                       head_length = 0.5,
                       vector([4,1],[5,5]),
                       head_length = 0.25,
                       vector([6,1],[5,5]))$

     See also 'head_both', 'head_angle', and 'head_type'.

 -- Graphic option: head_type
     Default value: 'filled'

     'head_type' is used to specify how arrow heads are plotted.
     Possible values are: 'filled' (closed and filled arrow heads),
     'empty' (closed but not filled arrow heads), and 'nofilled' (open
     arrow heads).

     This option is relevant only for 'vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,12],
                       yrange      = [0,10],
                       head_length = 1,
                       vector([0,1],[5,5]), /* default type */
                       head_type = 'empty,
                       vector([3,1],[5,5]),
                       head_type = 'nofilled,
                       vector([6,1],[5,5]))$

     See also 'head_both', 'head_angle', and 'head_length'.

 -- Graphic option: ip_grid
     Default value: '[50, 50]'

     'ip_grid' sets the grid for the first sampling in implicit plots.

     This option is relevant only for 'implicit' objects.

 -- Graphic option: ip_grid_in
     Default value: '[5, 5]'

     'ip_grid_in' sets the grid for the second sampling in implicit
     plots.

     This option is relevant only for 'implicit' objects.

 -- Graphic option: key
     Default value: '""' (empty string)

     'key' is the name of a function in the legend.  If 'key' is an
     empty string, no key is assigned to the function.

     This option affects the following graphic objects:
        * 'gr2d': 'points', 'polygon', 'rectangle', 'ellipse', 'vector',
          'explicit', 'implicit', 'parametric', and 'polar'.

        * 'gr3d': 'points', 'explicit', 'parametric', and
          'parametric_surface'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(key   = "Sinus",
                       explicit(sin(x),x,0,10),
                       key   = "Cosinus",
                       color = red,
                       explicit(cos(x),x,0,10) )$

 -- Graphic option: label_alignment
     Default value: 'center'

     'label_alignment' is used to specify where to write labels with
     respect to the given coordinates.  Possible values are: 'center',
     'left', and 'right'.

     This option is relevant only for 'label' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange          = [0,10],
                       yrange          = [0,10],
                       points_joined   = true,
                       points([[5,0],[5,10]]),
                       color           = blue,
                       label(["Centered alignment (default)",5,2]),
                       label_alignment = 'left,
                       label(["Left alignment",5,5]),
                       label_alignment = 'right,
                       label(["Right alignment",5,8]))$

     See also 'label_orientation', and 'color'.

 -- Graphic option: label_orientation
     Default value: 'horizontal'

     'label_orientation' is used to specify orientation of labels.
     Possible values are: 'horizontal', and 'vertical'.

     This option is relevant only for 'label' objects.

     Example:

     In this example, a dummy point is added to get an image.  Package
     'draw' needs always data to draw an scene.
          (%i1) load(draw)$
          (%i2) draw2d(xrange     = [0,10],
                       yrange     = [0,10],
                       point_size = 0,
                       points([[5,5]]),
                       color      = navy,
                       label(["Horizontal orientation (default)",5,2]),
                       label_orientation = 'vertical,
                       color             = "#654321",
                       label(["Vertical orientation",1,5]))$

     See also 'label_alignment' and 'color'.

 -- Graphic option: line_type
     Default value: 'solid'

     'line_type' indicates how lines are displayed; possible values are
     'solid' and 'dots'.

     This option affects the following graphic objects:
        * 'gr2d': 'points', 'polygon', 'rectangle', 'ellipse', 'vector',
          'explicit', 'implicit', 'parametric' and 'polar'.

        * 'gr3d': 'points', 'explicit', 'parametric' and
          'parametric_surface'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(line_type = dots,
                       explicit(1 + x^2,x,-1,1),
                       line_type = solid, /* default */
                       explicit(2 + x^2,x,-1,1))$

     See also 'line_width'.

 -- Graphic option: line_width
     Default value: 1

     'line_width' is the width of plotted lines.  Its value must be a
     positive number.

     This option affects the following graphic objects:
        * 'gr2d': 'points', 'polygon', 'rectangle', 'ellipse', 'vector',
          'explicit', 'implicit', 'parametric' and 'polar'.

        * 'gr3d': 'points' and 'parametric'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^2,x,-1,1), /* default width */
                       line_width = 5.5,
                       explicit(1 + x^2,x,-1,1),
                       line_width = 10,
                       explicit(2 + x^2,x,-1,1))$

     See also 'line_type'.

 -- Graphic option: logcb
     Default value: 'false'

     If 'logcb' is 'true', the tics in the colorbox will be drawn in the
     logarithmic scale.

     When 'enhanced3d' or 'colorbox' is 'false', option 'logcb' has no
     effect.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d (
                  enhanced3d = true,
                  color      = green,
                  logcb = true,
                  logz  = true,
                  palette = [-15,24,-9],
                  explicit(exp(x^2-y^2), x,-2,2,y,-2,2)) $

     See also 'enhanced3d', 'colorbox' and 'cbrange'.

 -- Graphic option: logx
     Default value: 'false'

     If 'logx' is 'true', the <x> axis will be drawn in the logarithmic
     scale.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(log(x),x,0.01,5),
                       logx = true)$

     See also 'logy' and 'logz'.

 -- Graphic option: logy
     Default value: 'false'

     If 'logy' is 'true', the <y> axis will be drawn in the logarithmic
     scale.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(logy = true,
                       explicit(exp(x),x,0,5))$

     See also 'logx' and 'logz'.

 -- Graphic option: logz
     Default value: 'false'

     If 'logz' is 'true', the <z> axis will be drawn in the logarithmic
     scale.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(logz = true,
                       explicit(exp(u^2+v^2),u,-2,2,v,-2,2))$

     See also 'logx' and 'logy'.

 -- Graphic option: nticks
     Default value: 29

     In 2d, 'nticks' gives the initial number of points used by the
     adaptive plotting routine for explicit objects.  It is also the
     number of points that will be shown in parametric and polar curves.

     This option affects the following graphic objects:
        * 'gr2d': 'ellipse', 'explicit', 'parametric' and 'polar'.

        * 'gr3d': 'parametric'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(transparent = true,
                       ellipse(0,0,4,2,0,180),
                       nticks = 5,
                       ellipse(0,0,4,2,180,180) )$

 -- Graphic option: palette
     Default value: 'color'

     'palette' indicates how to map gray levels onto color components.
     It works together with option 'enhanced3d' in 3D graphics, who
     associates every point of a surfaces to a real number or gray
     level.  It also works with gray images.  With 'palette', levels are
     transformed into colors.

     There are two ways for defining these transformations.

     First, 'palette' can be a vector of length three with components
     ranging from -36 to +36; each value is an index for a formula
     mapping the levels onto red, green and blue colors, respectively:

           0: 0               1: 0.5           2: 1
           3: x               4: x^2           5: x^3
           6: x^4             7: sqrt(x)       8: sqrt(sqrt(x))
           9: sin(90x)       10: cos(90x)     11: |x-0.5|
          12: (2x-1)^2       13: sin(180x)    14: |cos(180x)|
          15: sin(360x)      16: cos(360x)    17: |sin(360x)|
          18: |cos(360x)|    19: |sin(720x)|  20: |cos(720x)|
          21: 3x             22: 3x-1         23: 3x-2
          24: |3x-1|         25: |3x-2|       26: (3x-1)/2
          27: (3x-2)/2       28: |(3x-1)/2|   29: |(3x-2)/2|
          30: x/0.32-0.78125 31: 2*x-0.84     32: 4x;1;-2x+1.84;x/0.08-11.5
          33: |2*x - 0.5|    34: 2*x          35: 2*x - 0.5
          36: 2*x - 1

     negative numbers mean negative colour component.  'palette = gray'
     and 'palette = color' are short cuts for 'palette = [3,3,3]' and
     'palette = [7,5,15]', respectively.

     Second, 'palette' can be a user defined lookup table.  In this
     case, the format for building a lookup table of length 'n' is
     'palette = [color_1, color_2, ..., color_n]', where 'color_i' is a
     well formed color (see option 'color'), such that 'color_1' is
     assigned to the lowest gray level and 'color_n' to the highest.
     The rest of colors are interpolated.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Examples:

     It works together with option 'enhanced3d' in 3D graphics.

          (%i1) load(draw)$
          (%i2) draw3d(
                  enhanced3d = [z-x+2*y,x,y,z],
                  palette = [32, -8, 17],
                  explicit(20*exp(-x^2-y^2)-10,x,-3,3,y,-3,3))$

     It also works with gray images.

          (%i1) load(draw)$
          (%i2) im: apply(
                     'matrix,
                      makelist(makelist(random(200),i,1,30),i,1,30))$
          (%i3) /* palette = color, default */
                draw2d(image(im,0,0,30,30))$
          (%i4) draw2d(palette = gray, image(im,0,0,30,30))$
          (%i5) draw2d(palette = [15,20,-4],
                       colorbox=false,
                       image(im,0,0,30,30))$

     'palette' can be a user defined lookup table.  In this example, low
     values of 'x' are colored in red, and higher values in yellow.

          (%i1) load(draw)$
          (%i2) draw3d(
                   palette = [red, blue, yellow],
                   enhanced3d = x,
                   explicit(x^2+y^2,x,-1,1,y,-1,1)) $

     See also 'colorbox' and 'enhanced3d'.

 -- Graphic option: point_size
     Default value: 1

     'point_size' sets the size for plotted points.  It must be a non
     negative number.

     This option has no effect when graphic option 'point_type' is set
     to 'dot'.

     This option affects the following graphic objects:
        * 'gr2d': 'points'.

        * 'gr3d': 'points'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(points(makelist([random(20),random(50)],k,1,10)),
                  point_size = 5,
                  points(makelist(k,k,1,20),makelist(random(30),k,1,20)))$

 -- Graphic option: point_type
     Default value: 1

     'point_type' indicates how isolated points are displayed; the value
     of this option can be any integer index greater or equal than -1,
     or the name of a point style: '$none' (-1), 'dot' (0), 'plus' (1),
     'multiply' (2), 'asterisk' (3), 'square' (4), 'filled_square' (5),
     'circle' (6), 'filled_circle' (7), 'up_triangle' (8),
     'filled_up_triangle' (9), 'down_triangle' (10),
     'filled_down_triangle' (11), 'diamant' (12) and 'filled_diamant'
     (13).

     This option affects the following graphic objects:
        * 'gr2d': 'points'.

        * 'gr3d': 'points'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange = [0,10],
                       yrange = [0,10],
                       point_size = 3,
                       point_type = diamant,
                       points([[1,1],[5,1],[9,1]]),
                       point_type = filled_down_triangle,
                       points([[1,2],[5,2],[9,2]]),
                       point_type = asterisk,
                       points([[1,3],[5,3],[9,3]]),
                       point_type = filled_diamant,
                       points([[1,4],[5,4],[9,4]]),
                       point_type = 5,
                       points([[1,5],[5,5],[9,5]]),
                       point_type = 6,
                       points([[1,6],[5,6],[9,6]]),
                       point_type = filled_circle,
                       points([[1,7],[5,7],[9,7]]),
                       point_type = 8,
                       points([[1,8],[5,8],[9,8]]),
                       point_type = filled_diamant,
                       points([[1,9],[5,9],[9,9]]) )$

 -- Graphic option: points_joined
     Default value: 'false'

     When 'points_joined' is 'true', points are joined by lines; when
     'false', isolated points are drawn.  A third possible value for
     this graphic option is 'impulses'; in such case, vertical segments
     are drawn from points to the x-axis (2D) or to the xy-plane (3D).

     This option affects the following graphic objects:
        * 'gr2d': 'points'.

        * 'gr3d': 'points'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange        = [0,10],
                       yrange        = [0,4],
                       point_size    = 3,
                       point_type    = up_triangle,
                       color         = blue,
                       points([[1,1],[5,1],[9,1]]),
                       points_joined = true,
                       point_type    = square,
                       line_type     = dots,
                       points([[1,2],[5,2],[9,2]]),
                       point_type    = circle,
                       color         = red,
                       line_width    = 7,
                       points([[1,3],[5,3],[9,3]]) )$

 -- Graphic option: proportional_axes
     Default value: 'none'

     When 'proportional_axes' is equal to 'xy' or 'xyz', a 2D or 3D
     scene will be drawn with axes proportional to their relative
     lengths.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     This option works with Gnuplot version 4.2.6 or greater.

     Examples:

     Single 2D plot.

          (%i1) load(draw)$
          (%i2) draw2d(
                  ellipse(0,0,1,1,0,360),
                  transparent=true,
                  color = blue,
                  line_width = 4,
                  ellipse(0,0,2,1/2,0,360),
                  proportional_axes = xy) $

     Multiplot.

          (%i1) load(draw)$
          (%i2) draw(
                  terminal = wxt,
                  gr2d(proportional_axes = xy,
                       explicit(x^2,x,0,1)),
                  gr2d(explicit(x^2,x,0,1),
                       xrange = [0,1],
                       yrange = [0,2],
                       proportional_axes=xy),
                  gr2d(explicit(x^2,x,0,1)))$

 -- Graphic option: surface_hide
     Default value: 'false'

     If 'surface_hide' is 'true', hidden parts are not plotted in 3d
     surfaces.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw(columns=2,
                     gr3d(explicit(exp(sin(x)+cos(x^2)),x,-3,3,y,-3,3)),
                     gr3d(surface_hide = true,
                          explicit(exp(sin(x)+cos(x^2)),x,-3,3,y,-3,3)) )$

 -- Graphic option: terminal
     Default value: 'screen'

     Selects the terminal to be used by Gnuplot; possible values are:
     'screen' (default), 'png', 'pngcairo', 'jpg', 'eps', 'eps_color',
     'pdf', 'pdfcairo', 'gif', 'animated_gif', 'wxt', 'svg', and
     'aquaterm'.

     Terminals 'screen', 'wxt' and 'aquaterm' can be also defined as a
     list with two elements: the name of the terminal itself and a non
     negative integer number.  In this form, multiple windows can be
     opened at the same time, each with its corresponding number.  This
     feature does not work in Windows platforms.

     Since this is a global graphics option, its position in the scene
     description does not matter.  It can be also used as an argument of
     function 'draw'.

     N.B. pdfcairo requires Gnuplot 4.3 or newer.  'pdf' requires
     Gnuplot to be compiled with the option '--enable-pdf' and libpdf
     must be installed.  The pdf library is available from:
     <http://www.pdflib.com/en/download/pdflib-family/pdflib-lite/>

     Examples:

          (%i1) load(draw)$
          (%i2) /* screen terminal (default) */
                draw2d(explicit(x^2,x,-1,1))$
          (%i3) /* png file */
                draw2d(terminal  = 'png,
                       explicit(x^2,x,-1,1))$
          (%i4) /* jpg file */
                draw2d(terminal   = 'jpg,
                       dimensions = [300,300],
                       explicit(x^2,x,-1,1))$
          (%i5) /* eps file */
                draw2d(file_name = "myfile",
                       explicit(x^2,x,-1,1),
                       terminal  = 'eps)$
          (%i6) /* pdf file */
                draw2d(file_name = "mypdf",
                       dimensions = 100*[12.0,8.0],
                       explicit(x^2,x,-1,1),
                       terminal  = 'pdf)$
          (%i7) /* wxwidgets window */
                draw2d(explicit(x^2,x,-1,1),
                       terminal  = 'wxt)$

     Multiple windows.

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^5,x,-2,2), terminal=[screen, 3])$
          (%i3) draw2d(explicit(x^2,x,-2,2), terminal=[screen, 0])$

     An animated gif file.

          (%i1) load(draw)$
          (%i2) draw(
                  delay     = 100,
                  file_name = "zzz",
                  terminal  = 'animated_gif,
                  gr2d(explicit(x^2,x,-1,1)),
                  gr2d(explicit(x^3,x,-1,1)),
                  gr2d(explicit(x^4,x,-1,1)));
          End of animation sequence
          (%o2)          [gr2d(explicit), gr2d(explicit), gr2d(explicit)]

     Option 'delay' is only active in animated gif's; it is ignored in
     any other case.

     See also 'file_name', 'dimensions' and 'delay'.

 -- Graphic option: title
     Default value: '""' (empty string)

     Option 'title', a string, is the main title for the scene.  By
     default, no title is written.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(exp(u),u,-2,2),
                       title = "Exponential function")$

 -- Graphic option: transform
     Default value: 'none'

     If 'transform' is 'none', the space is not transformed and graphic
     objects are drawn as defined.  When a space transformation is
     desired, a list must be assigned to option 'transform'.  In case of
     a 2D scene, the list takes the form '[f1(x,y), f2(x,y), x, y]'.  In
     case of a 3D scene, the list is of the form '[f1(x,y,z), f2(x,y,z),
     f3(x,y,z), x, y, z]'.

     The names of the variables defined in the lists may be different to
     those used in the definitions of the graphic objects.

     Examples:

     Rotation in 2D.

          (%i1) load(draw)$
          (%i2) th : %pi / 4$
          (%i3) draw2d(
                  color = "#e245f0",
                  proportional_axes = 'xy,
                  line_width = 8,
                  triangle([3,2],[7,2],[5,5]),
                  border     = false,
                  fill_color = yellow,
                  transform  = [cos(th)*x - sin(th)*y,
                                sin(th)*x + cos(th)*y, x, y],
                  triangle([3,2],[7,2],[5,5]) )$

     Translation in 3D.

          (%i1) load(draw)$
          (%i2) draw3d(
                  color     = "#a02c00",
                  explicit(20*exp(-x^2-y^2)-10,x,-3,3,y,-3,3),
                  transform = [x+10,y+10,z+10,x,y,z],
                  color     = blue,
                  explicit(20*exp(-x^2-y^2)-10,x,-3,3,y,-3,3) )$

 -- Graphic option: transparent
     Default value: 'false'

     If 'transparent' is 'false', interior regions of polygons are
     filled according to 'fill_color'.

     This option affects the following graphic objects:
        * 'gr2d': 'polygon', 'rectangle', and 'ellipse'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(polygon([[3,2],[7,2],[5,5]]),
                       transparent = true,
                       color       = blue,
                       polygon([[5,2],[9,2],[7,5]]) )$

 -- Graphic option: tube_extremes
     Default value: '[open, open]'

     A list with two possible elements, 'open' and 'closed', indicating
     whether the extremes of a graphic object 'tube' remain open or must
     be closed.  By default, both extremes are left open.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(
                  tube_extremes = [open, closed],
                  tube(0, 0, a, 1,
                       a, 0, 8) )$

 -- Graphic option: unit_vectors
     Default value: 'false'

     If 'unit_vectors' is 'true', vectors are plotted with module 1.
     This is useful for plotting vector fields.  If 'unit_vectors' is
     'false', vectors are plotted with its original length.

     This option is relevant only for 'vector' objects.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [-1,6],
                       yrange      = [-1,6],
                       head_length = 0.1,
                       vector([0,0],[5,2]),
                       unit_vectors = true,
                       color        = red,
                       vector([0,3],[5,2]))$

 -- Graphic option: user_preamble
     Default value: '""' (empty string)

     Expert Gnuplot users can make use of this option to fine tune
     Gnuplot's behaviour by writing settings to be sent before the
     'plot' or 'splot' command.

     The value of this option must be a string or a list of strings (one
     per line).

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

     The dumb terminal is not supported by package 'draw', but it is
     possible to set it by making use of option 'user_preamble',
          (%i1) load(draw)$
          (%i2) draw2d(explicit(exp(x)-1,x,-1,1),
                       parametric(cos(u),sin(u),u,0,2*%pi),
                       user_preamble="set terminal dumb")$

 -- Graphic option: view
     Default value: '[60,30]'

     A pair of angles, measured in degrees, indicating the view
     direction in a 3D scene.  The first angle is the vertical rotation
     around the <x> axis, in the range [0, 180].  The second one is the
     horizontal rotation around the <z> axis, in the range [0, 360].

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(view = [170, 360],
                       explicit(sin(x^2+y^2),x,-2,2,y,-2,2) )$

 -- Graphic option: wired_surface
     Default value: 'false'

     Indicates whether 3D surfaces in 'enhanced3d' mode show the grid
     joinning the points or not.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(
                  enhanced3d    = [sin(x),x,y],
                  wired_surface = true,
                  explicit(x^2+y^2,x,-1,1,y,-1,1)) $

 -- Graphic option: x_voxel
     Default value: 10

     'x_voxel' is the number of voxels in the x direction to be used by
     the marching cubes algorithm implemented by the 3d 'implicit'
     object.  It is also used by graphic object 'region'.

 -- Graphic option: xaxis
     Default value: 'false'

     If 'xaxis' is 'true', the <x> axis is drawn.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       xaxis       = true,
                       xaxis_color = blue)$

     See also 'xaxis_width', 'xaxis_type' and 'xaxis_color'.

 -- Graphic option: xaxis_color
     Default value: '"black"'

     'xaxis_color' specifies the color for the <x> axis.  See 'color' to
     know how colors are defined.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       xaxis       = true,
                       xaxis_color = red)$

     See also 'xaxis', 'xaxis_width' and 'xaxis_type'.

 -- Graphic option: xaxis_secondary
     Default value: 'false'

     If 'xaxis_secondary' is 'true', function values can be plotted with
     respect to the second <x> axis, which will be drawn on top of the
     scene.

     Note that this is a local graphics option which only affects to 2d
     plots.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                   key   = "Bottom x-axis",
                   explicit(x+1,x,1,2),
                   color = red,
                   key   = "Above x-axis",
                   xtics_secondary = true,
                   xaxis_secondary = true,
                   explicit(x^2,x,-1,1)) $

     See also 'xrange_secondary', 'xtics_secondary',
     'xtics_rotate_secondary', 'xtics_axis_secondary' and
     'xaxis_secondary'.

 -- Graphic option: xaxis_type
     Default value: 'dots'

     'xaxis_type' indicates how the <x> axis is displayed; possible
     values are 'solid' and 'dots'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       xaxis       = true,
                       xaxis_type  = solid)$

     See also 'xaxis', 'xaxis_width' and 'xaxis_color'.

 -- Graphic option: xaxis_width
     Default value: 1

     'xaxis_width' is the width of the <x> axis.  Its value must be a
     positive number.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       xaxis       = true,
                       xaxis_width = 3)$

     See also 'xaxis', 'xaxis_type' and 'xaxis_color'.

 -- Graphic option: xlabel
     Default value: '""' (empty string)

     Option 'xlabel', a string, is the label for the <x> axis.  By
     default, no label is written.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xlabel = "Time",
                       explicit(exp(u),u,-2,2),
                       ylabel = "Population")$

     See also 'ylabel', and 'zlabel'.

 -- Graphic option: xrange
     Default value: 'auto'

     If 'xrange' is 'auto', the range for the <x> coordinate is computed
     automatically.

     If the user wants a specific interval for <x>, it must be given as
     a Maxima list, as in 'xrange=[-2, 3]'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange = [-3,5],
                       explicit(x^2,x,-1,1))$

     See also 'yrange' and 'zrange'.

 -- Graphic option: xrange_secondary
     Default value: 'auto'

     If 'xrange_secondary' is 'auto', the range for the second <x> axis
     is computed automatically.

     If the user wants a specific interval for the second <x> axis, it
     must be given as a Maxima list, as in 'xrange_secondary=[-2, 3]'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     See also 'xrange', 'yrange', 'zrange' and 'yrange_secondary'.

 -- Graphic option: xtics
     Default value: 'auto'

     This graphic option controls the way tic marks are drawn on the <x>
     axis.

        * When option 'xtics' is bounded to symbol <auto>, tic marks are
          drawn automatically.

        * When option 'xtics' is bounded to symbol <none>, tic marks are
          not drawn.

        * When option 'xtics' is bounded to a positive number, this is
          the distance between two consecutive tic marks.

        * When option 'xtics' is bounded to a list of length three of
          the form '[start,incr,end]', tic marks are plotted from
          'start' to 'end' at intervals of length 'incr'.

        * When option 'xtics' is bounded to a set of numbers of the form
          '{n1, n2, ...}', tic marks are plotted at values 'n1', 'n2',
          ...

        * When option 'xtics' is bounded to a set of pairs of the form
          '{["label1", n1], ["label2", n2], ...}', tic marks
          corresponding to values 'n1', 'n2', ... are labeled with
          '"label1"', '"label2"', ..., respectively.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Examples:

     Disable tics.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = 'none,
                       explicit(x^3,x,-1,1)  )$

     Tics every 1/4 units.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = 1/4,
                       explicit(x^3,x,-1,1)  )$

     Tics from -3/4 to 3/4 in steps of 1/8.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = [-3/4,1/8,3/4],
                       explicit(x^3,x,-1,1)  )$

     Tics at points -1/2, -1/4 and 3/4.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = {-1/2,-1/4,3/4},
                       explicit(x^3,x,-1,1)  )$

     Labeled tics.
          (%i1) load(draw)$
          (%i2) draw2d(xtics = {["High",0.75],["Medium",0],["Low",-0.75]},
                       explicit(x^3,x,-1,1)  )$

     See also 'ytics', and 'ztics'.

 -- Graphic option: xtics_axis
     Default value: 'false'

     If 'xtics_axis' is 'true', tic marks and their labels are plotted
     just along the <x> axis, if it is 'false' tics are plotted on the
     border.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: xtics_rotate
     Default value: 'false'

     If 'xtics_rotate' is 'true', tic marks on the <x> axis are rotated
     90 degrees.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: xtics_rotate_secondary
     Default value: 'false'

     If 'xtics_rotate_secondary' is 'true', tic marks on the secondary
     <x> axis are rotated 90 degrees.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: xtics_secondary
     Default value: 'auto'

     This graphic option controls the way tic marks are drawn on the
     second <x> axis.

     See 'xtics' for a complete description.

 -- Graphic option: xtics_secondary_axis
     Default value: 'false'

     If 'xtics_secondary_axis' is 'true', tic marks and their labels are
     plotted just along the secondary <x> axis, if it is 'false' tics
     are plotted on the border.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: xu_grid
     Default value: 30

     'xu_grid' is the number of coordinates of the first variable ('x'
     in explicit and 'u' in parametric 3d surfaces) to build the grid of
     sample points.

     This option affects the following graphic objects:
        * 'gr3d': 'explicit' and 'parametric_surface'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(xu_grid = 10,
                       yv_grid = 50,
                       explicit(x^2+y^2,x,-3,3,y,-3,3) )$

     See also 'yv_grid'.

 -- Graphic option: xy_file
     Default value: '""' (empty string)

     'xy_file' is the name of the file where the coordinates will be
     saved after clicking with the mouse button and hitting the 'x' key.
     By default, no coordinates are saved.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: xyplane
     Default value: 'false'

     Allocates the xy-plane in 3D scenes.  When 'xyplane' is 'false',
     the xy-plane is placed automatically; when it is a real number, the
     xy-plane intersects the z-axis at this level.  This option has no
     effect in 2D scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(xyplane = %e-2,
                       explicit(x^2+y^2,x,-1,1,y,-1,1))$

 -- Graphic option: y_voxel
     Default value: 10

     'y_voxel' is the number of voxels in the y direction to be used by
     the marching cubes algorithm implemented by the 3d 'implicit'
     object.  It is also used by graphic object 'region'.

 -- Graphic option: yaxis
     Default value: 'false'

     If 'yaxis' is 'true', the <y> axis is drawn.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       yaxis       = true,
                       yaxis_color = blue)$

     See also 'yaxis_width', 'yaxis_type' and 'yaxis_color'.

 -- Graphic option: yaxis_color
     Default value: '"black"'

     'yaxis_color' specifies the color for the <y> axis.  See 'color' to
     know how colors are defined.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       yaxis       = true,
                       yaxis_color = red)$

     See also 'yaxis', 'yaxis_width' and 'yaxis_type'.

 -- Graphic option: yaxis_secondary
     Default value: 'false'

     If 'yaxis_secondary' is 'true', function values can be plotted with
     respect to the second <y> axis, which will be drawn on the right
     side of the scene.

     Note that this is a local graphics option which only affects to 2d
     plots.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                   explicit(sin(x),x,0,10),
                   yaxis_secondary = true,
                   ytics_secondary = true,
                   color = blue,
                   explicit(100*sin(x+0.1)+2,x,0,10));

     See also 'yrange_secondary', 'ytics_secondary',
     'ytics_rotate_secondary' and 'ytics_axis_secondary'.

 -- Graphic option: yaxis_type
     Default value: 'dots'

     'yaxis_type' indicates how the <y> axis is displayed; possible
     values are 'solid' and 'dots'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       yaxis       = true,
                       yaxis_type  = solid)$

     See also 'yaxis', 'yaxis_width' and 'yaxis_color'.

 -- Graphic option: yaxis_width
     Default value: 1

     'yaxis_width' is the width of the <y> axis.  Its value must be a
     positive number.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(x^3,x,-1,1),
                       yaxis       = true,
                       yaxis_width = 3)$

     See also 'yaxis', 'yaxis_type' and 'yaxis_color'.

 -- Graphic option: ylabel
     Default value: '""' (empty string)

     Option 'ylabel', a string, is the label for the <y> axis.  By
     default, no label is written.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xlabel = "Time",
                       ylabel = "Population",
                       explicit(exp(u),u,-2,2) )$

     See also 'xlabel', and 'zlabel'.

 -- Graphic option: yrange
     Default value: 'auto'

     If 'yrange' is 'auto', the range for the <y> coordinate is computed
     automatically.

     If the user wants a specific interval for <y>, it must be given as
     a Maxima list, as in 'yrange=[-2, 3]'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(yrange = [-2,3],
                       explicit(x^2,x,-1,1),
                       xrange = [-3,3])$

     See also 'xrange', 'yrange_secondary' and 'zrange'.

 -- Graphic option: yrange_secondary
     Default value: 'auto'

     If 'yrange_secondary' is 'auto', the range for the second <y> axis
     is computed automatically.

     If the user wants a specific interval for the second <y> axis, it
     must be given as a Maxima list, as in 'yrange_secondary=[-2, 3]'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                   explicit(sin(x),x,0,10),
                   yaxis_secondary = true,
                   ytics_secondary = true,
                   yrange = [-3, 3],
                   yrange_secondary = [-20, 20],
                   color = blue,
                   explicit(100*sin(x+0.1)+2,x,0,10)) $

     See also 'xrange', 'yrange' and 'zrange'.

 -- Graphic option: ytics
     Default value: 'auto'

     This graphic option controls the way tic marks are drawn on the <y>
     axis.

     See 'xtics' for a complete description.

 -- Graphic option: ytics_axis
     Default value: 'false'

     If 'ytics_axis' is 'true', tic marks and their labels are plotted
     just along the <y> axis, if it is 'false' tics are plotted on the
     border.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: ytics_rotate
     Default value: 'false'

     If 'ytics_rotate' is 'true', tic marks on the <y> axis are rotated
     90 degrees.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: ytics_rotate_secondary
     Default value: 'false'

     If 'ytics_rotate_secondary' is 'true', tic marks on the secondary
     <y> axis are rotated 90 degrees.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: ytics_secondary
     Default value: 'auto'

     This graphic option controls the way tic marks are drawn on the
     second <y> axis.

     See 'xtics' for a complete description.

 -- Graphic option: ytics_secondary_axis
     Default value: 'false'

     If 'ytics_secondary_axis' is 'true', tic marks and their labels are
     plotted just along the secondary <y> axis, if it is 'false' tics
     are plotted on the border.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: yv_grid
     Default value: 30

     'yv_grid' is the number of coordinates of the second variable ('y'
     in explicit and 'v' in parametric 3d surfaces) to build the grid of
     sample points.

     This option affects the following graphic objects:
        * 'gr3d': 'explicit' and 'parametric_surface'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(xu_grid = 10,
                       yv_grid = 50,
                       explicit(x^2+y^2,x,-3,3,y,-3,3) )$

     See also 'xu_grid'.

 -- Graphic option: z_voxel
     Default value: 10

     'z_voxel' is the number of voxels in the z direction to be used by
     the marching cubes algorithm implemented by the 3d 'implicit'
     object.

 -- Graphic option: zaxis
     Default value: 'false'

     If 'zaxis' is 'true', the <z> axis is drawn in 3D plots.  This
     option has no effect in 2D scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1),
                       zaxis       = true,
                       zaxis_type  = solid,
                       zaxis_color = blue)$

     See also 'zaxis_width', 'zaxis_type' and 'zaxis_color'.

 -- Graphic option: zaxis_color
     Default value: '"black"'

     'zaxis_color' specifies the color for the <z> axis.  See 'color' to
     know how colors are defined.  This option has no effect in 2D
     scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1),
                       zaxis       = true,
                       zaxis_type  = solid,
                       zaxis_color = red)$

     See also 'zaxis', 'zaxis_width' and 'zaxis_type'.

 -- Graphic option: zaxis_type
     Default value: 'dots'

     'zaxis_type' indicates how the <z> axis is displayed; possible
     values are 'solid' and 'dots'.  This option has no effect in 2D
     scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1),
                       zaxis       = true,
                       zaxis_type  = solid)$

     See also 'zaxis', 'zaxis_width' and 'zaxis_color'.

 -- Graphic option: zaxis_width
     Default value: 1

     'zaxis_width' is the width of the <z> axis.  Its value must be a
     positive number.  This option has no effect in 2D scenes.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1),
                       zaxis       = true,
                       zaxis_type  = solid,
                       zaxis_width = 3)$

     See also 'zaxis', 'zaxis_type' and 'zaxis_color'.

 -- Graphic option: zlabel
     Default value: '""' (empty string)

     Option 'zlabel', a string, is the label for the <z> axis.  By
     default, no label is written.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(zlabel = "Z variable",
                       ylabel = "Y variable",
                       explicit(sin(x^2+y^2),x,-2,2,y,-2,2),
                       xlabel = "X variable" )$

     See also 'xlabel', and 'ylabel'.

 -- Graphic option: zrange
     Default value: 'auto'

     If 'zrange' is 'auto', the range for the <z> coordinate is computed
     automatically.

     If the user wants a specific interval for <z>, it must be given as
     a Maxima list, as in 'zrange=[-2, 3]'.

     Since this is a global graphics option, its position in the scene
     description does not matter.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(yrange = [-3,3],
                       zrange = [-2,5],
                       explicit(x^2+y^2,x,-1,1,y,-1,1),
                       xrange = [-3,3])$

     See also 'xrange' and 'yrange'.

 -- Graphic option: ztics
     Default value: 'auto'

     This graphic option controls the way tic marks are drawn on the <z>
     axis.

     See 'xtics' for a complete description.

 -- Graphic option: ztics_axis
     Default value: 'false'

     If 'ztics_axis' is 'true', tic marks and their labels are plotted
     just along the <z> axis, if it is 'false' tics are plotted on the
     border.

     Since this is a global graphics option, its position in the scene
     description does not matter.

 -- Graphic option: ztics_rotate
     Default value: 'false'

     If 'ztics_rotate' is 'true', tic marks on the <z> axis are rotated
     90 degrees.

     Since this is a global graphics option, its position in the scene
     description does not matter.

42.2.4 Graphics objects
-----------------------

 -- Graphic object: bars ([<x1>, <h1>, <w1>], [<x2>, <h2>, <w2>, ...])

     Draws vertical bars in 2D.

     2D

     'bars([<x1>, <h1>, <w1>], [<x2>, <h2>, <w2>, ...])' draws bars
     centered at values <x1>, <x2>, ... with heights <h1>, <h2>, ... and
     widths <w1>, <w2>, ...

     This object is affected by the following graphic options: 'key',
     'fill_color', 'fill_density' and 'line_width'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                 key          = "Group A",
                 fill_color   = blue,
                 fill_density = 0.2,
                 bars([0.8,5,0.4],[1.8,7,0.4],[2.8,-4,0.4]),
                 key          = "Group B",
                 fill_color   = red,
                 fill_density = 0.6,
                 line_width   = 4,
                 bars([1.2,4,0.4],[2.2,-2,0.4],[3.2,5,0.4]),
                 xaxis = true);

 -- Graphic object: cylindrical (<radius>, <z>, <minz>, <maxz>, <azi>,
          <minazi>, <maxazi>)

     Draws 3D functions defined in cylindrical coordinates.

     3D

     'cylindrical(<radius>, <z>, <minz>, <maxz>, <azi>, <minazi>,
     <maxazi>)' plots function '<radius>(<z>, <azi>)' defined in
     cylindrical coordinates, with variable <z> taking values from
     <minz> to <maxz> and azimuth <azi> taking values from <minazi> to
     <maxazi>.

     This object is affected by the following graphic options:
     'xu_grid', 'yv_grid', 'line_type', 'key', 'wired_surface',
     'enhanced3d' and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(cylindrical(1,z,-2,2,az,0,2*%pi))$

 -- Graphic object: elevation_grid (<mat>, <x0>, <y0>, <width>,
          <height>)

     Draws matrix <mat> in 3D space.  <z> values are taken from <mat>,
     the abscissas range from <x0> to <x0> + <width> and ordinates from
     <y0> to <y0> + <height>.  Element a(1,1) is projected on point
     (x0,y0+height), a(1,n) on (x0+width,y0+height), a(m,1) on (x0,y0),
     and a(m,n) on (x0+width,y0).

     This object is affected by the following graphic options:
     'line_type', 'line_width', 'key', 'wired_surface', 'enhanced3d',
     and 'color'.

     In older versions of Maxima, 'elevation_grid' was called 'mesh'.
     See also 'mesh'.

     Example:

          (%i1) load(draw)$
          (%i2) m: apply(
                      matrix,
                      makelist(makelist(random(10.0),k,1,30),i,1,20)) $
          (%i3) draw3d(
                   color = blue,
                   elevation_grid(m,0,0,3,2),
                   xlabel = "x",
                   ylabel = "y",
                   surface_hide = true);

 -- Graphic object: ellipse (<xc>, <yc>, <a>, <b>, <ang1>, <ang2>)

     Draws ellipses and circles in 2D.

     2D

     'ellipse (<xc>, <yc>, <a>, <b>, <ang1>, <ang2>)' plots an ellipse
     centered at '[<xc>, <yc>]' with horizontal and vertical semi axis
     <a> and <b>, respectively, starting at angle <ang1> with an
     amplitude equal to angle <ang2>.

     This object is affected by the following graphic options: 'nticks',
     'transparent', 'fill_color', 'border', 'line_width', 'line_type',
     'key' and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(transparent = false,
                       fill_color  = red,
                       color       = gray30,
                       transparent = false,
                       line_width  = 5,
                       ellipse(0,6,3,2,270,-270),
                       /* center (x,y), a, b, start & end in degrees */
                       transparent = true,
                       color       = blue,
                       line_width  = 3,
                       ellipse(2.5,6,2,3,30,-90),
                       xrange      = [-3,6],
                       yrange      = [2,9] )$

 -- Graphic object: errors ([<x1>, <x2>, ...], [<y1>, <y2>, ...])

     Draws points with error bars, horizontally, vertically or both,
     depending on the value of option 'error_type'.

     2D

     If 'error_type = x', arguments to 'errors' must be of the form '[x,
     y, xdelta]' or '[x, y, xlow, xhigh]'.  If 'error_type = y',
     arguments must be of the form '[x, y, ydelta]' or '[x, y, ylow,
     yhigh]'.  If 'error_type = xy' or 'error_type = boxes', arguments
     to 'errors' must be of the form '[x, y, xdelta, ydelta]' or '[x, y,
     xlow, xhigh, ylow, yhigh]'.

     See also 'error_type'.

     This object is affected by the following graphic options:
     'error_type', 'points_joined', 'line_width', 'key', 'line_type',
     'color', 'fill_density', 'xaxis_secondary', and 'yaxis_secondary'.

     Option 'fill_density' is only relevant when 'error_type=boxes'.

     Examples:

     Horizontal error bars.

          (%i1) load(draw)$
          (%i2) draw2d(
                  error_type = y,
                  errors([[1,2,1], [3,5,3], [10,3,1], [17,6,2]]))$

     Vertical and horizontal error bars.

          (%i1) load(draw)$
          (%i2) draw2d(
                  error_type = xy,
                  points_joined = true,
                  color = blue,
                  errors([[1,2,1,2], [3,5,2,1], [10,3,1,1], [17,6,1/2,2]]));

 -- Graphic object: explicit (<fcn>, <var>, <minval>, <maxval>)
 -- Graphic object: explicit (<fcn>, <var1>, <minval1>, <maxval1>,
          <var2>, <minval2>, <maxval2>)

     Draws explicit functions in 2D and 3D.

     2D

     'explicit(<fcn>,<var>,<minval>,<maxval>)' plots explicit function
     <fcn>, with variable <var> taking values from <minval> to <maxval>.

     This object is affected by the following graphic options: 'nticks',
     'adapt_depth', 'draw_realpart', 'line_width', 'line_type', 'key',
     'filled_func', 'fill_color' and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(line_width = 3,
                       color      = blue,
                       explicit(x^2,x,-3,3) )$
          (%i3) draw2d(fill_color  = brown,
                       filled_func = true,
                       explicit(x^2,x,-3,3) )$

     3D

     'explicit (<fcn>, <var1>, <minval1>, <maxval1>, <var2>, <minval2>,
     <maxval2>)' plots the explicit function <fcn>, with the variable
     <var1> taking values from <minval1> to <maxval1> and the variable
     <var2> taking values from <minval2> to <maxval2>.

     This object is affected by the following graphic options:
     'draw_realpart', 'xu_grid', 'yv_grid', 'line_type', 'line_width',
     'key', 'wired_surface', 'enhanced3d', and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(key   = "Gauss",
                       color = "#a02c00",
                       explicit(20*exp(-x^2-y^2)-10,x,-3,3,y,-3,3),
                       yv_grid     = 10,
                       color = blue,
                       key   = "Plane",
                       explicit(x+y,x,-5,5,y,-5,5),
                       surface_hide = true)$

     See also 'filled_func' for filled functions.

 -- Graphic object: image (<im>, <x0>, <y0>, <width>, <height>)

     Renders images in 2D.

     2D

     'image(<im>, <x0>, <y0>, <width>, <height>)' plots image <im> in
     the rectangular region from vertex '(<x0>, <y0>)' to '(x0+<width>,
     y0+<height>)' on the real plane.  Argument <im> must be a matrix of
     real numbers, a matrix of vectors of length three or a <picture>
     object.

     If <im> is a matrix of real numbers or a <levels picture> object,
     pixel values are interpreted according to graphic option 'palette',
     which is a vector of length three with components ranging from -36
     to +36; each value is an index for a formula mapping the levels
     onto red, green and blue colors, respectively:
           0: 0               1: 0.5           2: 1
           3: x               4: x^2           5: x^3
           6: x^4             7: sqrt(x)       8: sqrt(sqrt(x))
           9: sin(90x)       10: cos(90x)     11: |x-0.5|
          12: (2x-1)^2       13: sin(180x)    14: |cos(180x)|
          15: sin(360x)      16: cos(360x)    17: |sin(360x)|
          18: |cos(360x)|    19: |sin(720x)|  20: |cos(720x)|
          21: 3x             22: 3x-1         23: 3x-2
          24: |3x-1|         25: |3x-2|       26: (3x-1)/2
          27: (3x-2)/2       28: |(3x-1)/2|   29: |(3x-2)/2|
          30: x/0.32-0.78125                  31: 2*x-0.84
          32: 4x;1;-2x+1.84;x/0.08-11.5
          33: |2*x - 0.5|    34: 2*x          35: 2*x - 0.5
          36: 2*x - 1
     negative numbers mean negative colour component.

     'palette = gray' and 'palette = color' are short cuts for 'palette
     = [3,3,3]' and 'palette = [7,5,15]', respectively.

     If <im> is a matrix of vectors of length three or an <rgb picture>
     object, they are interpreted as red, green and blue color
     components.

     Examples:

     If <im> is a matrix of real numbers, pixel values are interpreted
     according to graphic option 'palette'.

          (%i1) load(draw)$
          (%i2) im: apply(
                     'matrix,
                      makelist(makelist(random(200),i,1,30),i,1,30))$
          (%i3) /* palette = color, default */
                draw2d(image(im,0,0,30,30))$
          (%i4) draw2d(palette = gray, image(im,0,0,30,30))$
          (%i5) draw2d(palette = [15,20,-4],
                       colorbox=false,
                       image(im,0,0,30,30))$

     See also 'colorbox'.

     If <im> is a matrix of vectors of length three, they are
     interpreted as red, green and blue color components.
          (%i1) load(draw)$
          (%i2) im: apply(
                      'matrix,
                       makelist(
                         makelist([random(300),
                                   random(300),
                                   random(300)],i,1,30),i,1,30))$
          (%i3) draw2d(image(im,0,0,30,30))$

     Package 'draw' automatically loads package 'picture'.  In this
     example, a level picture object is built by hand and then rendered.
          (%i1) load(draw)$
          (%i2) im: make_level_picture([45,87,2,134,204,16],3,2);
          (%o2)       picture(level, 3, 2, {Array:  #(45 87 2 134 204 16)})
          (%i3) /* default color palette */
                draw2d(image(im,0,0,30,30))$
          (%i4) /* gray palette */
                draw2d(palette = gray,
                       image(im,0,0,30,30))$

     An xpm file is read and then rendered.
          (%i1) load(draw)$
          (%i2) im: read_xpm("myfile.xpm")$
          (%i3) draw2d(image(im,0,0,10,7))$

     See also 'make_level_picture', 'make_rgb_picture' and 'read_xpm'.

     <http://www.telefonica.net/web2/biomates/maxima/gpdraw/image> contains more
     elaborated examples.

 -- Graphic object: implicit (<fcn>, <x>, <xmin>, <xmax>, <y>, <ymin>,
          <ymax>)
 -- Graphic object: implicit (<fcn>, <x>, <xmin>, <xmax>, <y>, <ymin>,
          <ymax>, <z>, <zmin>, <zmax>)

     Draws implicit functions in 2D and 3D.

     2D

     'implicit(<fcn>, <x>, <xmin>, <xmax>, <y>, <ymin>, <ymax>)' plots
     the implicit function defined by <fcn>, with variable <x> taking
     values from <xmin> to <xmax>, and variable <y> taking values from
     <ymin> to <ymax>.

     This object is affected by the following graphic options:
     'ip_grid', 'ip_grid_in', 'line_width', 'line_type', 'key' and
     'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(terminal  = eps,
                       grid      = true,
                       line_type = solid,
                       key       = "y^2=x^3-2*x+1",
                       implicit(y^2=x^3-2*x+1, x, -4,4, y, -4,4),
                       line_type = dots,
                       key       = "x^3+y^3 = 3*x*y^2-x-1",
                       implicit(x^3+y^3 = 3*x*y^2-x-1, x,-4,4, y,-4,4),
                       title     = "Two implicit functions" )$

     3D

     'implicit(<fcn>, <x>, <xmin>, <xmax>, <y>, <ymin>, <ymax>, <z>,
     <zmin>, <zmax>)' plots the implicit surface defined by <fcn>, with
     variable <x> taking values from <xmin> to <xmax>, variable <y>
     taking values from <ymin> to <ymax> and variable <z> taking values
     from <zmin> to <zmax>.  This object implements the marching cubes
     algorithm.

     This object is affected by the following graphic options:
     'x_voxel', 'y_voxel', 'z_voxel', 'line_width', 'line_type', 'key',
     'wired_surface', 'enhanced3d', and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(
                  color=blue,
                  implicit((x^2+y^2+z^2-1)*(x^2+(y-1.5)^2+z^2-0.5)=0.015,
                           x,-1,1,y,-1.2,2.3,z,-1,1),
                  surface_hide=true);

 -- Graphic object: label ([<string>, <x>, <y>], ...)
 -- Graphic object: label ([<string>, <x>, <y>, <z>], ...)

     Writes labels in 2D and 3D.

     Colored labels work only with Gnuplot 4.3.  This is a known bug in
     package 'draw'.

     This object is affected by the following graphic options:
     'label_alignment', 'label_orientation' and 'color'.

     2D

     'label([<string>, <x>, <y>])' writes the <string> at point '[<x>,
     <y>]'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(yrange = [0.1,1.4],
                       color = red,
                       label(["Label in red",0,0.3]),
                       color = "#0000ff",
                       label(["Label in blue",0,0.6]),
                       color = light_blue,
                       label(["Label in light-blue",0,0.9],
                             ["Another light-blue",0,1.2])  )$

     3D

     'label([<string>, <x>, <y>, <z>])' writes the <string> at point
     '[<x>, <y>, <z>]'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(exp(sin(x)+cos(x^2)),x,-3,3,y,-3,3),
                       color = red,
                       label(["UP 1",-2,0,3], ["UP 2",1.5,0,4]),
                       color = blue,
                       label(["DOWN 1",2,0,-3]) )$

 -- Graphic object: mesh (<row_1>, <row_2>, ...)

     Draws a quadrangular mesh in 3D.

     3D

     Argument <row_i> is a list of <n> 3D points of the form
     '[[x_i1,y_i1,z_i1], ...,[x_in,y_in,z_in]]', and all rows are of
     equal length.  All these points define an arbitrary surface in 3D
     and in some sense it's a generalization of the 'elevation_grid'
     object.

     This object is affected by the following graphic options:
     'line_type', 'line_width', 'color', 'key', 'wired_surface',
     'enhanced3d', and 'transform'.

     Examples:

     A simple example.

          (%i1) load(draw)$
          (%i2) draw3d(
                   mesh([[1,1,3],   [7,3,1],[12,-2,4],[15,0,5]],
                        [[2,7,8],   [4,3,1],[10,5,8], [12,7,1]],
                        [[-2,11,10],[6,9,5],[6,15,1], [20,15,2]])) $

     Plotting a triangle in 3D.

          (%i1) load(draw)$
          (%i2) draw3d(
                  line_width = 2,
                  mesh([[1,0,0],[0,1,0]],
                       [[0,0,1],[0,0,1]])) $

     Two quadrilaterals.

          (%i1) load(draw)$
          (%i2) draw3d(
                  surface_hide = true,
                  line_width   = 3,
                  color = red,
                  mesh([[0,0,0], [0,1,0]],
                       [[2,0,2], [2,2,2]]),
                  color = blue,
                  mesh([[0,0,2], [0,1,2]],
                       [[2,0,4], [2,2,4]])) $

 -- Graphic object: parametric (<xfun>, <yfun>, <par>, <parmin>,
          <parmax>)
 -- Graphic object: parametric (<xfun>, <yfun>, <zfun>, <par>, <parmin>,
          <parmax>)

     Draws parametric functions in 2D and 3D.

     This object is affected by the following graphic options: 'nticks',
     'line_width', 'line_type', 'key', 'color' and 'enhanced3d'.

     2D

     'parametric(<xfun>, <yfun>, <par>, <parmin>, <parmax>)' plots the
     parametric function '[<xfun>, <yfun>]', with the parameter <par>
     taking values from <parmin> to <parmax>.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(explicit(exp(x),x,-1,3),
                       color = red,
                       key   = "This is the parametric one!!",
                       parametric(2*cos(rrr),rrr^2,rrr,0,2*%pi))$

     3D

     The command 'parametric(<xfun>, <yfun>, <zfun>, <par>, <parmin>,
     <parmax>)' plots the parametric curve '[<xfun>, <yfun>, <zfun>]',
     with the parameter <par> taking values from <parmin> to <parmax>.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(explicit(exp(sin(x)+cos(x^2)),x,-3,3,y,-3,3),
                       color = royalblue,
                       parametric(cos(5*u)^2,sin(7*u),u-2,u,0,2),
                       color      = turquoise,
                       line_width = 2,
                       parametric(t^2,sin(t),2+t,t,0,2),
                       surface_hide = true,
                       title = "Surface & curves" )$

 -- Graphic object: parametric_surface (<xfun>, <yfun>, <zfun>, <par1>,
          <par1min>, <par1max>, <par2>, <par2min>, <par2max>)

     Draws parametric surfaces in 3D.

     3D

     'parametric_surface(<xfun>, <yfun>, <zfun>, <par1>, <par1min>,
     <par1max>, <par2>,
     <par2min>, <par2max>)' plots the parametric surface '[<xfun>,
     <yfun>, <zfun>]', with the parameter <par1> taking values from
     <par1min> to <par1max> and the parameter <par2> taking values from
     <par2min> to <par2max>.

     This object is affected by the following graphic options:
     'draw_realpart', 'xu_grid', 'yv_grid', 'line_type', 'line_width',
     'key', 'wired_surface', 'enhanced3d', and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(title          = "Sea shell",
                       xu_grid        = 100,
                       yv_grid        = 25,
                       view           = [100,20],
                       surface_hide   = true,
                       parametric_surface(0.5*u*cos(u)*(cos(v)+1),
                                     0.5*u*sin(u)*(cos(v)+1),
                                     u*sin(v) - ((u+3)/8*%pi)^2 - 20,
                                     u, 0, 13*%pi, v, -%pi, %pi) )$

 -- Graphic object: points ([[<x1>, <y1>], [<x2>, <y2>], ...])
 -- Graphic object: points ([<x1>, <x2>, ...], [<y1>, <y2>, ...])
 -- Graphic object: points ([<y1>, <y2>, ...])
 -- Graphic object: points ([[<x1>, <y1>, <z1>], [<x2>, <y2>, <z2>],
          ...])
 -- Graphic object: points ([<x1>, <x2>, ...], [<y1>, <y2>, ...], [<z1>,
          <z2>, ...])
 -- Graphic object: points (<matrix>)
 -- Graphic object: points (<1d_y_array>)
 -- Graphic object: points (<1d_x_array>, <1d_y_array>)
 -- Graphic object: points (<1d_x_array>, <1d_y_array>, <1d_z_array>)
 -- Graphic object: points (<2d_xy_array>)
 -- Graphic object: points (<2d_xyz_array>)

     Draws points in 2D and 3D.

     This object is affected by the following graphic options:
     'point_size', 'point_type', 'points_joined', 'line_width', 'key',
     'line_type' and 'color'.  In 3D mode, it is also affected by
     'enhanced3d'.

     2D

     'points([[<x1>, <y1>], [<x2>, <y2>], ...])' or 'points([<x1>, <x2>,
     ...], [<y1>, <y2>, ...])' plots points '[x1, y1]', '[x2, y2]', etc.
     If abscissas are not given, they are set to consecutive positive
     integers, so that 'points([<y1>, <y2>, ...])' draws points '[1,
     <y1>]', '[2, <y2>]', etc.  If <matrix> is a two-column or two-row
     matrix, 'points (<matrix>)' draws the associated points.  If
     <matrix> is a one-column or one-row matrix, abscissas are assigned
     automatically.

     If <1d_y_array> is a 1D lisp array of numbers,
     'points(<1d_y_array>)' plots them setting abscissas to consecutive
     positive integers.  'points(<1d_x_array>, <1d_y_array>)' plots
     points with their coordinates taken from the two arrays passed as
     arguments.  If <2d_xy_array> is a 2D array with two columns, or
     with two rows, 'points(<2d_xy_array>)' plots the corresponding
     points on the plane.

     Examples:

     Two types of arguments for 'points', a list of pairs and two lists
     of separate coordinates.
          (%i1) load(draw)$
          (%i2) draw2d(
                  key = "Small points",
                  points(makelist([random(20),random(50)],k,1,10)),
                  point_type    = circle,
                  point_size    = 3,
                  points_joined = true,
                  key           = "Great points",
                  points(makelist(k,k,1,20),makelist(random(30),k,1,20)),
                  point_type    = filled_down_triangle,
                  key           = "Automatic abscissas",
                  color         = red,
                  points([2,12,8]))$

     Drawing impulses.
          (%i1) load(draw)$
          (%i2) draw2d(
                  points_joined = impulses,
                  line_width    = 2,
                  color         = red,
                  points(makelist([random(20),random(50)],k,1,10)))$

     Array with ordinates.
          (%i1) load(draw)$
          (%i2) a: make_array (flonum, 100) $
          (%i3) for i:0 thru 99 do a[i]: random(1.0) $
          (%i4) draw2d(points(a)) $

     Two arrays with separate coordinates.
          (%i1) load(draw)$
          (%i2) x: make_array (flonum, 100) $
          (%i3) y: make_array (fixnum, 100) $
          (%i4) for i:0 thru 99 do (
                  x[i]: float(i/100),
                  y[i]: random(10) ) $
          (%i5) draw2d(points(x, y)) $

     A two-column 2D array.
          (%i1) load(draw)$
          (%i2) xy: make_array(flonum, 100, 2) $
          (%i3) for i:0 thru 99 do (
                  xy[i, 0]: float(i/100),
                  xy[i, 1]: random(10) ) $
          (%i4) draw2d(points(xy)) $

     Drawing an array filled with function 'read_array'.
          (%i1) load(draw)$
          (%i2) a: make_array(flonum,100) $
          (%i3) read_array (file_search ("pidigits.data"), a) $
          (%i4) draw2d(points(a)) $

     3D

     'points([[<x1>, <y1>, <z1>], [<x2>, <y2>, <z2>], ...])' or
     'points([<x1>, <x2>, ...], [<y1>, <y2>, ...], [<z1>, <z2>, ...])'
     plots points '[<x1>, <y1>, <z1>]', '[<x2>, <y2>, <z2>]', etc.  If
     <matrix> is a three-column or three-row matrix, 'points (<matrix>)'
     draws the associated points.

     When arguments are lisp arrays, 'points(<1d_x_array>, <1d_y_array>,
     <1d_z_array>)' takes coordinates from the three 1D arrays.  If
     <2d_xyz_array> is a 2D array with three columns, or with three
     rows, 'points(<2d_xyz_array>)' plots the corresponding points.

     Examples:

     One tridimensional sample,

          (%i1) load(draw)$
          (%i2) load (numericalio)$
          (%i3) s2 : read_matrix (file_search ("wind.data"))$
          (%i4) draw3d(title = "Daily average wind speeds",
                       point_size = 2,
                       points(args(submatrix (s2, 4, 5))) )$

     Two tridimensional samples,

          (%i1) load(draw)$
          (%i2) load (numericalio)$
          (%i3) s2 : read_matrix (file_search ("wind.data"))$
          (%i4) draw3d(
                   title = "Daily average wind speeds. Two data sets",
                   point_size = 2,
                   key        = "Sample from stations 1, 2 and 3",
                   points(args(submatrix (s2, 4, 5))),
                   point_type = 4,
                   key        = "Sample from stations 1, 4 and 5",
                   points(args(submatrix (s2, 2, 3))) )$

     Unidimensional arrays,

          (%i1) load(draw)$
          (%i2) x: make_array (fixnum, 10) $
          (%i3) y: make_array (fixnum, 10) $
          (%i4) z: make_array (fixnum, 10) $
          (%i5) for i:0 thru 9 do (
                  x[i]: random(10),
                  y[i]: random(10),
                  z[i]: random(10) ) $
          (%i6) draw3d(points(x,y,z)) $

     Bidimensional colored array,

          (%i1) load(draw)$
          (%i2) xyz: make_array(fixnum, 10, 3) $
          (%i3) for i:0 thru 9 do (
                  xyz[i, 0]: random(10),
                  xyz[i, 1]: random(10),
                  xyz[i, 2]: random(10) ) $
          (%i4) draw3d(
                   enhanced3d = true,
                   points_joined = true,
                   points(xyz)) $

     Color numbers explicitly specified by the user.

          (%i1) load(draw)$
          (%i2) pts: makelist([t,t^2,cos(t)], t, 0, 15)$
          (%i3) col_num: makelist(k, k, 1, length(pts))$
          (%i4) draw3d(
                  enhanced3d = ['part(col_num,k),k],
                  point_size = 3,
                  point_type = filled_circle,
                  points(pts))$

 -- Graphic object: polar (<radius>, <ang>, <minang>, <maxang>)

     Draws 2D functions defined in polar coordinates.

     2D

     'polar(<radius>, <ang>, <minang>, <maxang>)' plots function
     '<radius>(<ang>)' defined in polar coordinates, with variable <ang>
     taking values from <minang> to <maxang>.

     This object is affected by the following graphic options: 'nticks',
     'line_width', 'line_type', 'key' and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(user_preamble = "set grid polar",
                       nticks        = 200,
                       xrange        = [-5,5],
                       yrange        = [-5,5],
                       color         = blue,
                       line_width    = 3,
                       title         = "Hyperbolic Spiral",
                       polar(10/theta,theta,1,10*%pi) )$

 -- Graphic object: polygon ([[<x1>, <y1>], [<x2>, <y2>], ...])
 -- Graphic object: polygon ([<x1>, <x2>, ...], [<y1>, <y2>, ...])

     Draws polygons in 2D.

     2D

     'polygon([[<x1>, <y1>], [<x2>, <y2>], ...])' or
     'polygon([<x1>, <x2>, ...], [<y1>,<y2>, ...])': plots on the plane
     a polygon with vertices '[<x1>, <y1>]', '[<x2>, <y2>]', etc.

     This object is affected by the following graphic options:
     'transparent', 'fill_color', 'border', 'line_width', 'key',
     'line_type' and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(color      = "#e245f0",
                       line_width = 8,
                       polygon([[3,2],[7,2],[5,5]]),
                       border      = false,
                       fill_color  = yellow,
                       polygon([[5,2],[9,2],[7,5]]) )$

 -- Graphic object: quadrilateral (<point_1>, <point_2>, <point_3>,
          <point_4>)

     Draws a quadrilateral.

     2D

     'quadrilateral([<x1>, <y1>], [<x2>, <y2>], [<x3>, <y3>], [<x4>,
     <y4>])' draws a quadrilateral with vertices '[<x1>, <y1>]', '[<x2>,
     <y2>]', '[<x3>, <y3>]', and '[<x4>, <y4>]'.

     This object is affected by the following graphic options:
     'transparent', 'fill_color', 'border', 'line_width',
     'key', 'xaxis_secondary', 'yaxis_secondary', 'line_type',
     'transform' and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                  quadrilateral([1,1],[2,2],[3,-1],[2,-2]))$

     3D

     'quadrilateral ([<x1>, <y1>, <z1>], [<x2>, <y2>, <z2>], [<x3>,
     <y3>, <z3>], [<x4>, <y4>, <z4>])'
     draws a quadrilateral with vertices '[<x1>, <y1>, <z1>]', '[<x2>,
     <y2>, <z2>]', '[<x3>, <y3>, <z3>]', and '[<x4>, <y4>, <z4>]'.

     This object is affected by the following graphic options:
     'line_type', 'line_width', 'color', 'key', 'enhanced3d', and
     'transform'.

 -- Graphic object: rectangle ([<x1>, <y1>], [<x2>, <y2>])

     Draws rectangles in 2D.

     2D

     'rectangle([<x1>, <y1>], [<x2>, <y2>])' draws a rectangle with
     opposite vertices '[<x1>, <y1>]' and '[<x2>, <y2>]'.

     This object is affected by the following graphic options:
     'transparent', 'fill_color', 'border', 'line_width', 'key',
     'line_type' and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(fill_color  = red,
                       line_width  = 6,
                       line_type   = dots,
                       transparent = false,
                       fill_color  = blue,
                       rectangle([-2,-2],[8,-1]), /* opposite vertices */
                       transparent = true,
                       line_type   = solid,
                       line_width  = 1,
                       rectangle([9,4],[2,-1.5]),
                       xrange      = [-3,10],
                       yrange      = [-3,4.5] )$

 -- Graphic object: region (<expr>, <var1>, <minval1>, <maxval1>,
          <var2>, <minval2>, <maxval2>)

     Plots a region on the plane defined by inequalities.

     2D <expr> is an expression formed by inequalities and boolean
     operators 'and', 'or', and 'not'.  The region is bounded by the
     rectangle defined by [<minval1>, <maxval1>] and [<minval2>,
     <maxval2>].

     This object is affected by the following graphic options:
     'fill_color', 'key', 'x_voxel', and 'y_voxel'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                  x_voxel = 30,
                  y_voxel = 30,
                  region(x^2+y^2<1 and x^2+y^2 > 1/2,
                         x, -1.5, 1.5, y, -1.5, 1.5));

 -- Graphic object: spherical (<radius>, <azi>, <minazi>, <maxazi>,
          <zen>, <minzen>, <maxzen>)

     Draws 3D functions defined in spherical coordinates.

     3D

     'spherical(<radius>, <azi>, <minazi>, <maxazi>, <zen>, <minzen>,
     <maxzen>)' plots function '<radius>(<azi>, <zen>)' defined in
     spherical coordinates, with azimuth <azi> taking values from
     <minazi> to <maxazi> and zenith <zen> taking values from <minzen>
     to <maxzen>.

     This object is affected by the following graphic options:
     'xu_grid', 'yv_grid', 'line_type', 'key', 'wired_surface',
     'enhanced3d', and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(spherical(1,a,0,2*%pi,z,0,%pi))$

 -- Graphic object: triangle (<point_1>, <point_2>, <point_3>)

     Draws a triangle.

     2D

     'triangle([<x1>, <y1>], [<x2>, <y2>], [<x3>, <y3>])' draws a
     triangle with vertices '[<x1>, <y1>]', '[<x2>, <y2>]', and
     '[<x3>,<y3>]'.

     This object is affected by the following graphic options:
     'transparent', 'fill_color', 'border', 'line_width',
     'key', 'xaxis_secondary', 'yaxis_secondary', 'line_type',
     'transform', and 'color'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(
                  triangle([1,1],[2,2],[3,-1]))$

     3D

     'triangle([<x1>, <y1>, <z1>], [<x2>, <y2>, <z2>], [<x3>, <y3>,
     <z3>])' draws a triangle with vertices '[<x1>, <y1>, <z1>]',
     '[<x2>, <y2>, <z2>]', and '[<x3>, <y3>, <z3>]'.

     This object is affected by the following graphic options:
     'line_type', 'line_width', 'color', 'key', 'enhanced3d', and
     'transform'.

 -- Graphic object: tube (<xfun>, <yfun>, <zfun>, <rfun>, <p>, <pmin>,
          <pmax>)

     Draws a tube in 3D with varying diameter.

     3D

     '[<xfun>,<yfun>,<zfun>]' is the parametric curve with parameter <p>
     taking values from <pmin> to <pmax>.  Circles of radius <rfun> are
     placed with their centers on the parametric curve and perpendicular
     to it.

     This object is affected by the following graphic options:
     'xu_grid', 'yv_grid', 'line_type', 'line_width', 'key',
     'wired_surface', 'enhanced3d', 'color', and 'tube_extremes'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(
                  enhanced3d = true,
                  xu_grid = 50,
                  tube(cos(a), a, 0, cos(a/10)^2,
                       a, 0, 4*%pi) )$

 -- Graphic object: vector ([<x>, <y>], [<dx>, <dy>])
 -- Graphic object: vector ([<x>, <y>, <z>], [<dx>, <dy>, <dz>])

     Draws vectors in 2D and 3D.

     This object is affected by the following graphic options:
     'head_both', 'head_length', 'head_angle', 'head_type',
     'line_width', 'line_type', 'key' and 'color'.

     2D

     'vector([<x>, <y>], [<dx>,<dy>])' plots vector '[<dx>, <dy>]' with
     origin in '[<x>, <y>]'.

     Example:

          (%i1) load(draw)$
          (%i2) draw2d(xrange      = [0,12],
                       yrange      = [0,10],
                       head_length = 1,
                       vector([0,1],[5,5]), /* default type */
                       head_type = 'empty,
                       vector([3,1],[5,5]),
                       head_both = true,
                       head_type = 'nofilled,
                       line_type = dots,
                       vector([6,1],[5,5]))$

     3D

     'vector([<x>, <y>, <z>], [<dx>, <dy>, <dz>])' plots vector
     '[<dx>,<dy>,<dz>]' with origin in '[<x>, <y>, <z>]'.

     Example:

          (%i1) load(draw)$
          (%i2) draw3d(color = cyan,
                       vector([0,0,0],[1,1,1]/sqrt(3)),
                       vector([0,0,0],[1,-1,0]/sqrt(2)),
                       vector([0,0,0],[1,1,-2]/sqrt(6)) )$

