This is maxima.info, produced by makeinfo version 4.13 from
/home/robert/maxima/maxima-code/doc/info//include-maxima.texi.

This is a Texinfo Maxima Manual

   Copyright 1994,2001 William F. Schelter

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


File: maxima.info,  Node: Top,  Next: Introduction to Maxima,  Prev: (dir),  Up: (dir)

Maxima 5.33.0 Manual
********************

Maxima is a computer algebra system, implemented in Lisp.

   Maxima is derived from the Macsyma system, developed at MIT in the
years 1968 through 1982 as part of Project MAC.  MIT turned over a copy
of the Macsyma source code to the Department of Energy in 1982; that
version is now known as DOE Macsyma.  A copy of DOE Macsyma was
maintained by Professor William F. Schelter of the University of Texas
from 1982 until his death in 2001.  In 1998, Schelter obtained
permission from the Department of Energy to release the DOE Macsyma
source code under the GNU Public License, and in 2000 he initiated the
Maxima project at SourceForge to maintain and develop DOE Macsyma, now
called Maxima.

* Menu:


Maxima infrastructure

* Introduction to Maxima::      Sample Maxima sessions.
* Bug Detection and Reporting:: Finding and reporting bugs in Maxima.
* Help::                        Asking for help from within a Maxima session.
* Command Line::                Maxima command line syntax, Input, and Output.
* Data Types and Structures::   Numbers, Strings, Lists, Arrays, and Structures.
* Expressions::                 Expressions in Maxima.
* Operators::                   Operators used in Maxima expressions.
* Evaluation::                  Evaluating expressions.
* Simplification::              Simplifying expressions.
* Mathematical Functions::      Mathematical functions in Maxima.
* Maximas Database::            Declarations, Contexts, Facts, and Properties.
* Plotting::                    2D and 3D graphical output.
* File Input and Output::       File input and output.

Support for specific areas of mathematics
* Polynomials::                 Standard forms for polynomials, and
                                functions operating on them.
* Special Functions::           Special functions
* Elliptic Functions::          Elliptic Functions and Integrals
* Limits::                      Limits of expressions.
* Differentiation::             Differential calculus.
* Integration::                 Integral calculus.
* Equations::                   Defining and solving equations.
* Differential Equations::      Defining and solving differential equations.
* Numerical::                   Numerical integration, Fourier
                                transforms, Equations, ODE's, etc.
* Matrices and Linear Algebra:: Matrix operations.
* Affine::
* itensor::                     Indicial Tensor Manipulation.
* ctensor::                     Component Tensor Manipulation.
* atensor::                     Algebraic Tensor Manipulation.
* Sums Products and Series::    Sums, Products, Taylor and power series.
* Number Theory::               Number theory.
* Symmetries::
* Groups::                      Abstract algebra.

Advanced facilities and programming
* Runtime Environment::         Customization of the Maxima environment.
* Miscellaneous Options::       Options with a global effect on Maxima.
* Rules and Patterns::          User defined pattern matching and
                                simplification rules.
* Sets::                        Manipulation of sets.
* Function Definition::         Defining functions.
* Program Flow::                Defining Maxima programs.
* Debugging::                   Debugging Maxima programs.

Additional packages
* alt-display::                 Alternative display package.
* asympa::                      Asymptotic analysis package.
* augmented_lagrangian::        augmented_lagrangian package.
* Bernstein::                   Bernstein polynomials.
* bode::                        Bode gain and phase plots.
* cobyla::                      Nonlinear optimization with inequality constraints.
* contrib_ode::                 Additional routines for ODEs
* descriptive::                 Descriptive statistics.
* diag::                        Jordan matrices.
* distrib::                     Probability distributions.
* draw::                        A Maxima-Gnuplot interface.
* drawdf::                      Direction fields with Gnuplot.
* dynamics::                    Graphics for dynamical systems and fractals.
* ezunits::                     Dimensional quantities.
* f90::                         Maxima to fortran translator.
* finance::                     Financial package.
* fractals::                    Fractals.
* ggf::                         Generating function of sequences.
* graphs::                      Graph theory package.
* grobner::                     Functions for working with Groebner bases.
* impdiff::                     Implicit derivatives.
* interpol::                    Interpolation package.
* lapack::                      LAPACK functions for linear algebra.
* lbfgs::                       L-BFGS unconstrained minimization package.
* lindstedt::                   Lindstedt package.
* linearalgebra::               Functions for linear algebra.
* lsquares::                    Least squares.
* makeOrders::                  Polynomial utility.
* minpack::                     MINPACK functions for minimization and roots
* mnewton::                     Newton's method.
* numericalio::                 Reading and writing files.
* opsubst::                     Substitutions utility.
* orthopoly::                   Orthogonal polynomials.
* romberg::                     Romberg method for numerical integration.
* simplex::                     Linear programming.
* simplification::              Simplification rules and functions.
* solve_rec::                   Linear recurrences.
* stats::                       Statistical inference package.
* stirling::                    Stirling formula.
* stringproc::                  String processing.
* to_poly_solve::               to_poly_solve package.
* unit::                        Units and dimensions package.
* zeilberger::                  Functions for hypergeometric summation.

Index
* Function and Variable Index:: Index.

 --- The Detailed Node Listing ---

Introduction
* Introduction to Maxima::

Bugs
* Bug Detection and Reporting::

Help
* Documentation::
* Functions and Variables for Help::

Command Line
* Introduction to Command Line::
* Functions and Variables for Command Line::
* Functions and Variables for Display::

Data Types and Structures
* Numbers::
* Strings::
* Constants::
* Lists::
* Arrays::
* Structures::

Expressions
* Introduction to Expressions::
* Nouns and Verbs::
* Identifiers::
* Inequality::
* Functions and Variables for Expressions::

Operators
* Introduction to operators::
* Arithmetic operators::
* Relational operators::
* Logical operators::
* Operators for Equations::
* Assignment operators::
* User defined operators::

Evaluation
* Functions and Variables for Evaluation::

Simplification
* Functions and Variables for Simplification::

Mathematical Functions
* Functions for Numbers::
* Functions for Complex Numbers::
* Combinatorial Functions::
* Root Exponential and Logarithmic Functions::
* Trigonometric Functions::
* Random Numbers::

Maximas Database
* Introduction to Maximas Database::
* Functions and Variables for Properties::
* Functions and Variables for Facts::
* Functions and Variables for Predicates::

Plotting
* Introduction to Plotting::
* Plotting Formats::
* Functions and Variables for Plotting::
* Plotting Options::
* Gnuplot Options::
* Gnuplot_pipes Format Functions::

File Input and Output
* Comments::
* Files::
* Functions and Variables for File Input and Output::
* Functions and Variables for TeX Output::
* Functions and Variables for Fortran Output::

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

Special Functions
* Introduction to Special Functions::
* Bessel Functions::
* Airy Functions::
* Gamma and factorial Functions::
* Exponential Integrals::
* Error Function::
* Struve Functions::
* Hypergeometric Functions::
* Parabolic Cylinder Functions::
* Functions and Variables for Special Functions::

Elliptic Functions
* Introduction to Elliptic Functions and Integrals::
* Functions and Variables for Elliptic Functions::
* Functions and Variables for Elliptic Integrals::

Limits
* Functions and Variables for Limits::

Differentiation
* Functions and Variables for Differentiation::

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

Equations
* Functions and Variables for Equations::

Differential Equations
* Introduction to Differential Equations::
* Functions and Variables for Differential Equations::

Numerical
* Introduction to fast Fourier transform::
* Functions and Variables for fast Fourier transform::
* Functions for numerical solution of equations::
* Introduction to numerical solution of differential equations::
* Functions for numerical solution of differential equations::

Matrices and Linear Algebra
* Introduction to Matrices and Linear Algebra::
* Dot::
* Vectors::
* eigen::
* Functions and Variables for Matrices and Linear Algebra::

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

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

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

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

Sums, Products, and Series
* Functions and Variables for Sums and Products::
* Introduction to Series::
* Functions and Variables for Series::
* Introduction to Fourier series::
* Functions and Variables for Fourier series::

Number Theory
* Functions and Variables for Number Theory::

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

Groups
* Functions and Variables for Groups::

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

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

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

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

Function Definition
* Introduction to Function Definition::
* Function::
* Macros::
* Functions and Variables for Function Definition::

Program Flow
* Lisp and Maxima::
* Garbage Collection::
* Introduction to Program Flow::
* Functions and Variables for Program Flow::

Debugging
* Functions and Variables for Debugging::

alt-display
* Introduction to alt-display::
* Functions and Variables for alt-display::

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

augmented_lagrangian
* Functions and Variables for augmented_lagrangian::

Bernstein
* Functions and Variables for Bernstein::

bode
* Functions and Variables for bode::

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

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

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

diag
* Functions and Variables for diag::

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

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

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

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

ezunits
* Introduction to ezunits::
* Introduction to physical_constants::
* Functions and Variables for ezunits::

f90
* Functions and Variables for f90::

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

fractals
* Introduction to fractals::
* Definitions for IFS fractals::
* Definitions for complex fractals::
* Definitions for Koch snowflakes::
* Definitions for Peano maps::

ggf
* Functions and Variables for ggf::

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

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

impdiff
* Functions and Variables for impdiff::

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

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

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

lindstedt
* Functions and Variables for lindstedt::

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

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

makeOrders
* Functions and Variables for makeOrders::

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

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

numericalio
* Introduction to numericalio::
* Functions and Variables for plain-text input and output::
* Functions and Variables for binary input and output::

opsubst
* Functions and Variables for opsubst::

orthopoly
* Introduction to orthogonal polynomials::
* Functions and Variables for orthogonal polynomials::

romberg
* Functions and Variables for romberg::

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

simplification
* Introduction to simplification::
* Package absimp::
* Package facexp::
* Package functs::
* Package ineq::
* Package rducon::
* Package scifac::
* Package sqdnst::

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

stats
* Introduction to stats::
* Functions and Variables for inference_result::
* Functions and Variables for stats::
* Functions and Variables for special distributions::

stirling
* Functions and Variables for stirling::

stringproc
* Introduction to string processing::
* Functions and Variables for input and output::
* Functions and Variables for characters::
* Functions and Variables for strings::

to_poly_solve
* Functions and Variables for to_poly_solve::

unit
* Introduction to Units::
* Functions and Variables for Units::

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


File: maxima.info,  Node: Introduction to Maxima,  Next: Bug Detection and Reporting,  Prev: Top,  Up: Top

1 Introduction to Maxima
************************

Start Maxima with the command "maxima".  Maxima will display version
information and a prompt.  End each Maxima command with a semicolon.
End the session with the command "quit();".  Here's a sample session:

     [wfs@chromium]$ maxima
     Maxima 5.9.1 http://maxima.sourceforge.net
     Using Lisp CMU Common Lisp 19a
     Distributed under the GNU Public License. See the file COPYING.
     Dedicated to the memory of William Schelter.
     This is a development version of Maxima. The function bug_report()
     provides bug reporting information.
     (%i1) factor(10!);
                                 8  4  2
     (%o1)                      2  3  5  7
     (%i2) expand ((x + y)^6);
            6        5       2  4       3  3       4  2      5      6
     (%o2) y  + 6 x y  + 15 x  y  + 20 x  y  + 15 x  y  + 6 x  y + x
     (%i3) factor (x^6 - 1);
                                   2            2
     (%o3)       (x - 1) (x + 1) (x  - x + 1) (x  + x + 1)
     (%i4) quit();
     [wfs@chromium]$

   Maxima can search the info pages.  Use the `describe' command to show
information about the command or all the commands and variables
containing a string.  The question mark `?' (exact search) and double
question mark `??' (inexact search) are abbreviations for `describe':

     (%i1) ?? integ
      0: Functions and Variables for Elliptic Integrals
      1: Functions and Variables for Integration
      2: Introduction to Elliptic Functions and Integrals
      3: Introduction to Integration
      4: askinteger  (Functions and Variables for Simplification)
      5: integerp  (Functions and Variables for Miscellaneous Options)
      6: integer_partitions  (Functions and Variables for Sets)
      7: integrate  (Functions and Variables for Integration)
      8: integrate_use_rootsof  (Functions and Variables for Integration)
      9: integration_constant_counter  (Functions and Variables for
         Integration)
      10: nonnegintegerp  (Functions and Variables for linearalgebra)
     Enter space-separated numbers, `all' or `none': 5 4

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

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

          Examples:

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

      -- Function: askinteger (<expr>, integer)
      -- Function: askinteger (<expr>)
      -- Function: askinteger (<expr>, even)
      -- Function: askinteger (<expr>, odd)
          `askinteger (<expr>, integer)' attempts to determine from the
          `assume' database whether <expr> is an integer.  `askinteger'
          prompts the user if it cannot tell otherwise, and attempt to
          install the information in the database if possible.  `askinteger
          (<expr>)' is equivalent to `askinteger (<expr>, integer)'.

          `askinteger (<expr>, even)' and `askinteger (<expr>, odd)'
          likewise attempt to determine if <expr> is an even integer or odd
          integer, respectively.

     (%o1)                                true

   To use a result in later calculations, you can assign it to a
variable or refer to it by its automatically supplied label.  In
addition, `%' refers to the most recent calculated result:

     (%i1) u: expand ((x + y)^6);
            6        5       2  4       3  3       4  2      5      6
     (%o1) y  + 6 x y  + 15 x  y  + 20 x  y  + 15 x  y  + 6 x  y + x
     (%i2) diff (u, x);
              5         4       2  3       3  2       4        5
     (%o2) 6 y  + 30 x y  + 60 x  y  + 60 x  y  + 30 x  y + 6 x
     (%i3) factor (%o2);
                                         5
     (%o3)                      6 (y + x)

   Maxima knows about complex numbers and numerical constants:

     (%i1) cos(%pi);
     (%o1)                          - 1
     (%i2) exp(%i*%pi);
     (%o2)                          - 1

   Maxima can do differential and integral calculus:

     (%i1) u: expand ((x + y)^6);
            6        5       2  4       3  3       4  2      5      6
     (%o1) y  + 6 x y  + 15 x  y  + 20 x  y  + 15 x  y  + 6 x  y + x
     (%i2) diff (%, x);
              5         4       2  3       3  2       4        5
     (%o2) 6 y  + 30 x y  + 60 x  y  + 60 x  y  + 30 x  y + 6 x
     (%i3) integrate (1/(1 + x^3), x);
                                       2 x - 1
                     2            atan(-------)
                log(x  - x + 1)        sqrt(3)    log(x + 1)
     (%o3)    - --------------- + ------------- + ----------
                       6             sqrt(3)          3

   Maxima can solve linear systems and cubic equations:

     (%i1) linsolve ([3*x + 4*y = 7, 2*x + a*y = 13], [x, y]);
                             7 a - 52        25
     (%o1)              [x = --------, y = -------]
                             3 a - 8       3 a - 8
     (%i2) solve (x^3 - 3*x^2 + 5*x = 15, x);
     (%o2)       [x = - sqrt(5) %i, x = sqrt(5) %i, x = 3]

   Maxima can solve nonlinear sets of equations.  Note that if you don't
want a result printed, you can finish your command with `$' instead of
`;'.

     (%i1) eq_1: x^2 + 3*x*y + y^2 = 0$
     (%i2) eq_2: 3*x + y = 1$
     (%i3) solve ([eq_1, eq_2]);
                   3 sqrt(5) + 7      sqrt(5) + 3
     (%o3) [[y = - -------------, x = -----------],
                         2                 2

                                    3 sqrt(5) - 7        sqrt(5) - 3
                               [y = -------------, x = - -----------]]
                                          2                   2

   Maxima can generate plots of one or more functions:

     (%i1) plot2d (sin(x)/x, [x, -20, 20])$

     (%i2) plot2d ([atan(x), erf(x), tanh(x)], [x, -5, 5], [y, -1.5, 2])$

     (%i3) plot3d (sin(sqrt(x^2 + y^2))/sqrt(x^2 + y^2),
              [x, -12, 12], [y, -12, 12])$


File: maxima.info,  Node: Bug Detection and Reporting,  Next: Help,  Prev: Introduction to Maxima,  Up: Top

2 Bug Detection and Reporting
*****************************

* Menu:

* Functions and Variables for Bug Detection and Reporting::


File: maxima.info,  Node: Functions and Variables for Bug Detection and Reporting,  Up: Bug Detection and Reporting

2.1 Functions and Variables for Bug Detection and Reporting
===========================================================

 -- Function: run_testsuite ([<options>])
     Run the Maxima test suite.  Tests producing the desired answer are
     considered "passes," as are tests that do not produce the desired
     answer, but are marked as known bugs.

     `run_testsuite' takes the following optional keyword arguments

    `display_all'
          Display all tests.  Normally, the tests are not displayed,
          unless the test fails.  (Defaults to `false').

    `display_known_bugs'
          Displays tests that are marked as known bugs.  (Default is
          `false').

    `tests'
          This is a single test or a list of tests that should be run.
          Each test can be specified by either a string or a symbol.
          By default, all tests are run.  The complete set of tests is
          specified by `testsuite_files'.

    `time'
          Display time information.  If `true', the time taken for each
          test file is displayed.  If `all', the time for each
          individual test is shown if `display_all' is `true'.  The
          default is `false', so no timing information is shown.

     For example `run_testsuite(display_known_bugs = true,
     tests=[rtest5])' runs just test `rtest5' and displays the test
     that are marked as known bugs.

     `run_testsuite(display_all = true, tests=["rtest1", rtest1a])' will
     run tests `rtest1' and `rtest2', and displays each test.

     `run_testsuite' changes the Maxima environment.  Typically a test
     script executes `kill' to establish a known environment (namely
     one without user-defined functions and variables) and then defines
     functions and variables appropriate to the test.

     `run_testsuite' returns `done'.


 -- Option variable: testsuite_files
     `testsuite_files' is the set of tests to be run by
     `run_testsuite'.  It is a list of names of the files containing
     the tests to run.  If some of the tests in a file are known to
     fail, then instead of listing the name of the file, a list
     containing the file name and the test numbers that fail is used.

     For example, this is a part of the default set of tests:

           ["rtest13s", ["rtest14", 57, 63]]

     This specifies the testsuite consists of the files "rtest13s" and
     "rtest14", but "rtest14" contains two tests that are known to
     fail: 57 and 63.


 -- Function: bug_report ()
     Prints out Maxima and Lisp version numbers, and gives a link to
     the Maxima project bug report web page.  The version information
     is the same as reported by `build_info'.

     When a bug is reported, it is helpful to copy the Maxima and Lisp
     version information into the bug report.

     `bug_report' returns an empty string `""'.


 -- Function: build_info ()
     Returns a summary of the parameters of the Maxima build, as a
     Maxima structure (defined by `defstruct').  The fields of the
     structure are: `version', `timestamp', `host', `lisp_name', and
     `lisp_version'.  When the pretty-printer is enabled (via
     `display2d'), the structure is displayed as a short table.

     See also `bug_report'.

     Examples:

          (%i1) build_info ();
          (%o1)
          Maxima version: "5.26.0_16_gb72c64c_dirty"
          Maxima build date: "2012-01-29 12:29:04"
          Host type: "i686-pc-linux-gnu"
          Lisp implementation type: "CMU Common Lisp"
          Lisp implementation version: "CVS release-19a 19a-release-20040728 + minimal debian patches"
          (%i2) x : build_info ()$
          (%i3) x@version;
          (%o3)               5.26.0_16_gb72c64c_dirty
          (%i4) x@timestamp;
          (%o4)                  2012-01-29 12:29:04
          (%i5) x@host;
          (%o5)                   i686-pc-linux-gnu
          (%i6) x@lisp_name;
          (%o6)                    CMU Common Lisp
          (%i7) x@lisp_version;
          (%o7)
              CVS release-19a 19a-release-20040728 + minimal debian patches
          (%i8) x;
          (%o8)
          Maxima version: "5.26.0_16_gb72c64c_dirty"
          Maxima build date: "2012-01-29 12:29:04"
          Host type: "i686-pc-linux-gnu"
          Lisp implementation type: "CMU Common Lisp"
          Lisp implementation version: "CVS release-19a 19a-release-20040728 + minimal debian patches"



File: maxima.info,  Node: Help,  Next: Command Line,  Prev: Bug Detection and Reporting,  Up: Top

3 Help
******

* Menu:

* Documentation::
* Functions and Variables for Help::


File: maxima.info,  Node: Documentation,  Next: Functions and Variables for Help,  Prev: Help,  Up: Help

3.1 Documentation
=================

The Maxima on-line user's manual can be viewed in different forms.
From the Maxima interactive prompt, the user's manual is viewed as
plain text by the `?' command (i.e., the `describe' function).  The
user's manual is viewed as `info' hypertext by the `info' viewer
program and as a web page by any ordinary web browser.

   `example' displays examples for many Maxima functions.  For example,

     (%i1) example (integrate);

   yields

     (%i2) test(f):=block([u],u:integrate(f,x),ratsimp(f-diff(u,x)))
     (%o2) test(f) := block([u], u : integrate(f, x),
                                              ratsimp(f - diff(u, x)))
     (%i3) test(sin(x))
     (%o3)                           0
     (%i4) test(1/(x+1))
     (%o4)                           0
     (%i5) test(1/(x^2+1))
     (%o5)                           0

   and additional output.


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

3.2 Functions and Variables for Help
====================================

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

     `apropos("")' returns a list with all Maxima names.

     `apropos' returns the empty list `[]', if no name is found.

     Example:

     Show all Maxima symbols which have `"gamma"' in the name:

          (%i1) apropos("gamma");
          (%o1) [%gamma, gamma, gammalim, gamma_expand, gamma_greek,
          gamma_incomplete, gamma_incomplete_generalized,
          gamma_incomplete_regularized, Gamma, log_gamma, makegamma,
          prefer_gamma_incomplete,
          gamma_incomplete_generalized_regularized]


 -- Function: demo (<filename>)
     Evaluates Maxima expressions in <filename> and displays the
     results.  `demo' pauses after evaluating each expression and
     continues after the user enters a carriage return.  (If running in
     Xmaxima, `demo' may need to see a semicolon `;' followed by a
     carriage return.)

     `demo' searches the list of directories `file_search_demo' to find
     `filename'.  If the file has the suffix `dem', the suffix may be
     omitted.  See also `file_search'.

     `demo' evaluates its argument.  `demo' returns the name of the
     demonstration file.

     Example:

          (%i1) demo ("disol");

          batching /home/wfs/maxima/share/simplification/disol.dem
           At the _ prompt, type ';' followed by enter to get next demo
          (%i2)                      load(disol)

          _
          (%i3)           exp1 : a (e (g + f) + b (d + c))
          (%o3)               a (e (g + f) + b (d + c))

          _
          (%i4)                disolate(exp1, a, b, e)
          (%t4)                         d + c

          (%t5)                         g + f

          (%o5)                   a (%t5 e + %t4 b)

          _


 -- Function: describe (<string>)
 -- Function: describe (<string>, exact)
 -- Function: describe (<string>, inexact)
     `describe(<string>)' is equivalent to `describe(<string>, exact)'.

     `describe(<string>, exact)' finds an item with title equal
     (case-insensitive) to <string>, if there is any such item.

     `describe(<string>, inexact)' finds all documented items which
     contain <string> in their titles.  If there is more than one such
     item, Maxima asks the user to select an item or items to display.

     At the interactive prompt, `? foo' (with a space between `?' and
     `foo') is equivalent to `describe("foo", exact)', and `?? foo' is
     equivalent to `describe("foo", inexact)'.

     `describe("", inexact)' yields a list of all topics documented in
     the on-line manual.

     `describe' quotes its argument.  `describe' returns `true' if some
     documentation is found, otherwise `false'.

     See also *note Documentation::.

     Example:

          (%i1) ?? integ
           0: Functions and Variables for Elliptic Integrals
           1: Functions and Variables for Integration
           2: Introduction to Elliptic Functions and Integrals
           3: Introduction to Integration
           4: askinteger  (Functions and Variables for Simplification)
           5: integerp  (Functions and Variables for Miscellaneous Options)
           6: integer_partitions  (Functions and Variables for Sets)
           7: integrate  (Functions and Variables for Integration)
           8: integrate_use_rootsof  (Functions and Variables for
              Integration)
           9: integration_constant_counter  (Functions and Variables for
              Integration)
           10: nonnegintegerp  (Functions and Variables for linearalgebra)
          Enter space-separated numbers, `all' or `none': 7 8

           -- Function: integrate (<expr>, <x>)
           -- Function: integrate (<expr>, <x>, <a>, <b>)
               Attempts to symbolically compute the integral of <expr> with
               respect to <x>.  `integrate (<expr>, <x>)' is an indefinite
               integral, while `integrate (<expr>, <x>, <a>, <b>)' is a
               definite integral, [...]

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

               When `integrate_use_rootsof' is `true' and the denominator of
               a rational function cannot be factored, `integrate' returns
               the integral in a form which is a sum over the roots (not yet
               known) of the denominator.
               [...]

     In this example, items 7 and 8 were selected (output is shortened
     as indicated by `[...]').  All or none of the items could have
     been selected by entering `all' or `none', which can be
     abbreviated `a' or `n', respectively.


 -- Function: example (<topic>)
 -- Function: example ()
     `example (<topic>)' displays some examples of <topic>, which is a
     symbol or a string.  To get examples for operators like `if', `do',
     or `lambda' the argument must be a string, e.g. `example ("do")'.
     `example' is not case sensitive.  Most topics are function names.

     `example ()' returns the list of all recognized topics.

     The name of the file containing the examples is given by the
     global option variable `manual_demo', which defaults to
     `"manual.demo"'.

     `example' quotes its argument.  `example' returns `done' unless no
     examples are found or there is no argument, in which case `example'
     returns the list of all recognized topics.

     Examples:

          (%i1) example(append);
          (%i2) append([x+y,0,-3.2],[2.5e+20,x])
          (%o2)             [y + x, 0, - 3.2, 2.5e+20, x]
          (%o2)                         done
          (%i3) example("lambda");

          (%i4) lambda([x,y,z],z^2+y^2+x^2)
                                              2    2    2
          (%o4)            lambda([x, y, z], z  + y  + x )
          (%i5) %(1,2,a)
                                        2
          (%o5)                        a  + 5
          (%i6) a+2+1
          (%o6)                         a + 3
          (%o6)                         done


 -- Option variable: manual_demo
     Default value: `"manual.demo"'

     `manual_demo' specifies the name of the file containing the
     examples for the function `example'.  See `example'.



File: maxima.info,  Node: Command Line,  Next: Data Types and Structures,  Prev: Help,  Up: Top

4 Command Line
**************

* Menu:

* Introduction to Command Line::
* Functions and Variables for Command Line::
* Functions and Variables for Display::


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

4.1 Introduction to Command Line
================================


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

4.2 Functions and Variables for Command Line
============================================

 -- System variable: __
     `__' is the input expression currently being evaluated.  That is,
     while an input expression <expr> is being evaluated, `__' is
     <expr>.

     `__' is assigned the input expression before the input is
     simplified or evaluated.  However, the value of `__' is simplified
     (but not evaluated) when it is displayed.

     `__' is recognized by `batch' and `load'.  In a file processed by
     `batch', `__' has the same meaning as at the interactive prompt.
     In a file processed by `load', `__' is bound to the input
     expression most recently entered at the interactive prompt or in a
     batch file; `__' is not bound to the input expressions in the file
     being processed.  In particular, when `load (<filename>)' is
     called from the interactive prompt, `__' is bound to `load
     (<filename>)' while the file is being processed.

     See also `_' and `%'.

     Examples:

          (%i1) print ("I was called as", __);
          I was called as print(I was called as, __)
          (%o1)              print(I was called as, __)
          (%i2) foo (__);
          (%o2)                     foo(foo(__))
          (%i3) g (x) := (print ("Current input expression =", __), 0);
          (%o3) g(x) := (print("Current input expression =", __), 0)
          (%i4) [aa : 1, bb : 2, cc : 3];
          (%o4)                       [1, 2, 3]
          (%i5) (aa + bb + cc)/(dd + ee + g(x));
                                      cc + bb + aa
          Current input expression = --------------
                                     g(x) + ee + dd
                                          6
          (%o5)                        -------
                                       ee + dd


 -- System variable: _
     `_' is the most recent input expression (e.g., `%i1', `%i2',
     `%i3', ...).

     `_' is assigned the input expression before the input is
     simplified or evaluated.  However, the value of `_' is simplified
     (but not evaluated) when it is displayed.

     `_' is recognized by `batch' and `load'.  In a file processed by
     `batch', `_' has the same meaning as at the interactive prompt.
     In a file processed by `load', `_' is bound to the input expression
     most recently evaluated at the interactive prompt or in a batch
     file; `_' is not bound to the input expressions in the file being
     processed.

     See also `__' and `%'.

     Examples:

          (%i1) 13 + 29;
          (%o1)                          42
          (%i2) :lisp $_
          ((MPLUS) 13 29)
          (%i2) _;
          (%o2)                          42
          (%i3) sin (%pi/2);
          (%o3)                           1
          (%i4) :lisp $_
          ((%SIN) ((MQUOTIENT) $%PI 2))
          (%i4) _;
          (%o4)                           1
          (%i5) a: 13$
          (%i6) b: 29$
          (%i7) a + b;
          (%o7)                          42
          (%i8) :lisp $_
          ((MPLUS) $A $B)
          (%i8) _;
          (%o8)                         b + a
          (%i9) a + b;
          (%o9)                          42
          (%i10) ev (_);
          (%o10)                         42


 -- System variable: %
     `%' is the output expression (e.g., `%o1', `%o2', `%o3', ...) most
     recently computed by Maxima, whether or not it was displayed.

     `%' is recognized by `batch' and `load'.  In a file processed by
     `batch', `%' has the same meaning as at the interactive prompt.
     In a file processed by `load', `%' is bound to the output
     expression most recently computed at the interactive prompt or in
     a batch file; `%' is not bound to output expressions in the file
     being processed.

     See also `_', `%%', and `%th'.


 -- System variable: %%
     In compound statements, namely `block', `lambda', or `(<s_1>, ...,
     <s_n>)', `%%' is the value of the previous statement.

     At the first statement in a compound statement, or outside of a
     compound statement, `%%' is undefined.

     `%%' is recognized by `batch' and `load', and it has the same
     meaning as at the interactive prompt.

     See also `%'.

     Examples:

     The following two examples yield the same result.

          (%i1) block (integrate (x^5, x), ev (%%, x=2) - ev (%%, x=1));
                                         21
          (%o1)                          --
                                         2
          (%i2) block ([prev], prev: integrate (x^5, x),
                         ev (prev, x=2) - ev (prev, x=1));
                                         21
          (%o2)                          --
                                         2

     A compound statement may comprise other compound statements.
     Whether a statement be simple or compound, `%%' is the value of
     the previous statement.

          (%i3) block (block (a^n, %%*42), %%/6);
                                           n
          (%o3)                         7 a

     Within a compound statement, the value of `%%' may be inspected at
     a break prompt, which is opened by executing the `break' function.
     For example, entering `%%;' in the following example yields `42'.

          (%i4) block (a: 42, break ())$

          Entering a Maxima break point. Type 'exit;' to resume.
          _%%;
          42
          _


 -- Function: %th (<i>)
     The value of the <i>'th previous output expression.  That is, if
     the next expression to be computed is the <n>'th output, `%th
     (<m>)' is the (<n> - <m>)'th output.

     `%th' is recognized by `batch' and `load'.  In a file processed by
     `batch', `%th' has the same meaning as at the interactive prompt.
     In a file processed by `load', `%th' refers to output expressions
     most recently computed at the interactive prompt or in a batch
     file; `%th' does not refer to output expressions in the file being
     processed.

     See also `%' and `%%'.

     Example:

     `%th' is useful in `batch' files or for referring to a group of
     output expressions.  This example sets `s' to the sum of the last
     five output expressions.

          (%i1) 1;2;3;4;5;
          (%o1)                           1
          (%o2)                           2
          (%o3)                           3
          (%o4)                           4
          (%o5)                           5
          (%i6) block (s: 0, for i:1 thru 5 do s: s + %th(i), s);
          (%o6)                          15


 -- Special symbol: ?
     As prefix to a function or variable name, `?' signifies that the
     name is a Lisp name, not a Maxima name.  For example, `?round'
     signifies the Lisp function `ROUND'.  See *note Lisp and Maxima::
     for more on this point.

     The notation `? word' (a question mark followed a word, separated
     by whitespace) is equivalent to `describe("word")'.  The question
     mark must occur at the beginning of an input line; otherwise it is
     not recognized as a request for documentation.  See also
     `describe'.


 -- Special symbol: ??
     The notation `?? word' (`??' followed a word, separated by
     whitespace) is equivalent to `describe("word", inexact)'.  The
     question mark must occur at the beginning of an input line;
     otherwise it is not recognized as a request for documentation.
     See also `describe'.


 -- Option variable: inchar
     Default value: `%i'

     `inchar' is the prefix of the labels of expressions entered by the
     user.  Maxima automatically constructs a label for each input
     expression by concatenating `inchar' and `linenum'.

     `inchar' may be assigned any string or symbol, not necessarily a
     single character.  Because Maxima internally takes into account
     only the first char of the prefix, the prefixes `inchar',
     `outchar', and `linechar' should have a different first char.
     Otherwise some commands like `kill(inlables)' do not work as
     expected.

     See also `labels'.

     Example:

          (%i1) inchar: "input";
          (%o1)                         input
          (input2) expand((a+b)^3);
                               3        2      2      3
          (%o2)               b  + 3 a b  + 3 a  b + a
          (input3)


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

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

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

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

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

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

    `macros'
          All user-defined macro functions, created by `::='.

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

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

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

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

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

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

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


 -- Function: kill (<a_1>, ..., <a_n>)
 -- Function: kill (labels)
 -- Function: kill (inlabels, outlabels, linelabels)
 -- Function: kill (<n>)
 -- Function: kill ([<m>, <n>])
 -- Function: kill (values, functions, arrays, ...)
 -- Function: kill (all)
 -- Function: kill (allbut (<a_1>, ..., <a_n>))
     Removes all bindings (value, function, array, or rule) from the
     arguments <a_1>, ..., <a_n>.  An argument <a_k> may be a symbol or
     a single array element.  When <a_k> is a single array element,
     `kill' unbinds that element without affecting any other elements
     of the array.

     Several special arguments are recognized.  Different kinds of
     arguments may be combined, e.g., `kill (inlabels, functions,
     allbut (foo, bar))'.

     `kill (labels)' unbinds all input, output, and intermediate
     expression labels created so far.  `kill (inlabels)' unbinds only
     input labels which begin with the current value of `inchar'.
     Likewise, `kill (outlabels)' unbinds only output labels which
     begin with the current value of `outchar', and `kill (linelabels)'
     unbinds only intermediate expression labels which begin with the
     current value of `linechar'.

     `kill (<n>)', where <n> is an integer, unbinds the <n> most recent
     input and output labels.

     `kill ([<m>, <n>])' unbinds input and output labels <m> through
     <n>.

     `kill (<infolist>)', where <infolist> is any item in `infolists'
     (such as `values', `functions', or `arrays') unbinds all items in
     <infolist>.  See also `infolists'.

     `kill (all)' unbinds all items on all infolists.  `kill (all)' does
     not reset global variables to their default values; see `reset' on
     this point.

     `kill (allbut (<a_1>, ..., <a_n>))' unbinds all items on all
     infolists except for <a_1>, ..., <a_n>.  `kill (allbut
     (<infolist>))' unbinds all items except for the ones on
     <infolist>, where <infolist> is `values', `functions', `arrays',
     etc.

     The memory taken up by a bound property is not released until all
     symbols are unbound from it.  In particular, to release the memory
     taken up by the value of a symbol, one unbinds the output label
     which shows the bound value, as well as unbinding the symbol
     itself.

     `kill' quotes its arguments.  The quote-quote operator `'''
     defeats quotation.

     `kill (<symbol>)' unbinds all properties of <symbol>.  In contrast,
     the functions `remvalue', `remfunction', `remarray', and `remrule'
     unbind a specific property.

     `kill' always returns `done', even if an argument has no binding.


 -- Function: labels (<symbol>)
 -- System variable: labels
     Returns the list of input, output, or intermediate expression
     labels which begin with <symbol>.  Typically <symbol> is the value
     of `inchar', `outchar', or `linechar'.  If no labels begin with
     <symbol>, `labels' returns an empty list.

     The variable `labels' is the list of input, output, and
     intermediate expression labels, including all previous labels if
     `inchar', `outchar', or `linechar' were redefined.

     By default, Maxima displays the result of each user input
     expression, giving the result an output label.  The output display
     is suppressed by terminating the input with `$' (dollar sign)
     instead of `;' (semicolon).  An output label is constructed and
     bound to the result, but not displayed, and the label may be
     referenced in the same way as displayed output labels.  See also
     `%', `%%', and `%th'.

     Intermediate expression labels can be generated by some functions.
     The option variable `programmode' controls whether `solve' and
     some other functions generate intermediate expression labels
     instead of returning a list of expressions.  Some other functions,
     such as `ldisplay', always generate intermediate expression labels.

     See also `inchar', `outchar', `linechar', and `infolists'.


 -- Option variable: linechar
     Default value: `%t'

     `linechar' is the prefix of the labels of intermediate expressions
     generated by Maxima.  Maxima constructs a label for each
     intermediate expression (if displayed) by concatenating `linechar'
     and `linenum'.

     `linechar' may be assigned any string or symbol, not necessarily a
     single character.  Because Maxima internally takes into account
     only the first char of the prefix, the prefixes `inchar',
     `outchar', and `linechar' should have a different first char.
     Otherwise some commands like `kill(inlables)' do not work as
     expected.

     Intermediate expressions might or might not be displayed.  See
     `programmode' and `labels'.


 -- System variable: linenum
     The line number of the current pair of input and output
     expressions.


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

     `myoptions' is the list of all options ever reset by the user,
     whether or not they get reset to their default value.


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

     When `nolabels' is `true', input and output result labels (`%i'
     and `%o', respectively) are displayed, but the labels are not
     bound to results, and the labels are not appended to the `labels'
     list.  Since labels are not bound to results, garbage collection
     can recover the memory taken up by the results.

     Otherwise input and output result labels are bound to results, and
     the labels are appended to the `labels' list.

     Intermediate expression labels (`%t') are not affected by
     `nolabels'; whether `nolabels' is `true' or `false', intermediate
     expression labels are bound and appended to the `labels' list.

     See also `batch', `load', and `labels'.


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

     When `optionset' is `true', Maxima prints out a message whenever a
     Maxima option is reset.  This is useful if the user is doubtful of
     the spelling of some option and wants to make sure that the
     variable he assigned a value to was truly an option variable.

     Example:

          (%i1) optionset:true;
          assignment: assigning to option optionset
          (%o1)                         true
          (%i2) gamma_expand:true;
          assignment: assigning to option gamma_expand
          (%o2)                         true


 -- Option variable: outchar
     Default value: `%o'

     `outchar' is the prefix of the labels of expressions computed by
     Maxima.  Maxima automatically constructs a label for each computed
     expression by concatenating `outchar' and `linenum'.

     `outchar' may be assigned any string or symbol, not necessarily a
     single character.  Because Maxima internally takes into account
     only the first char of the prefix, the prefixes `inchar',
     `outchar' and `linechar' should have a different first char.
     Otherwise some commands like `kill(inlables)' do not work as
     expected.

     See also `labels'.

     Example:

          (%i1) outchar: "output";
          (output1)                    output
          (%i2) expand((a+b)^3);
                               3        2      2      3
          (output2)           b  + 3 a b  + 3 a  b + a
          (%i3)


 -- Function: playback ()
 -- Function: playback (<n>)
 -- Function: playback ([<m>, <n>])
 -- Function: playback ([<m>])
 -- Function: playback (input)
 -- Function: playback (slow)
 -- Function: playback (time)
 -- Function: playback (grind)
     Displays input, output, and intermediate expressions, without
     recomputing them.  `playback' only displays the expressions bound
     to labels; any other output (such as text printed by `print' or
     `describe', or error messages) is not displayed.  See also
     `labels'.

     `playback' quotes its arguments.  The quote-quote operator `'''
     defeats quotation.  `playback' always returns `done'.

     `playback ()' (with no arguments) displays all input, output, and
     intermediate expressions generated so far.  An output expression
     is displayed even if it was suppressed by the `$' terminator when
     it was originally computed.

     `playback (<n>)' displays the most recent <n> expressions.  Each
     input, output, and intermediate expression counts as one.

     `playback ([<m>, <n>])' displays input, output, and intermediate
     expressions with numbers from <m> through <n>, inclusive.

     `playback ([<m>])' is equivalent to `playback ([<m>, <m>])'; this
     usually prints one pair of input and output expressions.

     `playback (input)' displays all input expressions generated so far.

     `playback (slow)' pauses between expressions and waits for the
     user to press `enter'.  This behavior is similar to `demo'.
     `playback (slow)' is useful in conjunction with `save' or
     `stringout' when creating a secondary-storage file in order to
     pick out useful expressions.

     `playback (time)' displays the computation time for each
     expression.

     `playback (grind)' displays input expressions in the same format
     as the `grind' function.  Output expressions are not affected by
     the `grind' option.  See `grind'.

     Arguments may be combined, e.g., `playback ([5, 10], grind, time,
     slow)'.


 -- Option variable: prompt
     Default value: `_'

     `prompt' is the prompt symbol of the `demo' function, `playback
     (slow)' mode, and the Maxima break loop (as invoked by `break').


 -- Function: quit ()
     Terminates the Maxima session.  Note that the function must be
     invoked as `quit();' or `quit()$', not `quit' by itself.

     To stop a lengthy computation, type `control-C'.  The default
     action is to return to the Maxima prompt.  If `*debugger-hook*' is
     `nil', `control-C' opens the Lisp debugger.  See also *note
     Debugging::.


 -- Function: read (<expr_1>, ..., <expr_n>)
     Prints <expr_1>, ..., <expr_n>, then reads one expression from the
     console and returns the evaluated expression.  The expression is
     terminated with a semicolon `;' or dollar sign `$'.

     See also `readonly'

     Example:

          (%i1) foo: 42$
          (%i2) foo: read ("foo is", foo, " -- enter new value.")$
          foo is 42  -- enter new value.
          (a+b)^3;
          (%i3) foo;
                                               3
          (%o3)                         (b + a)


 -- Function: readonly (<expr_1>, ..., <expr_n>)
     Prints <expr_1>, ..., <expr_n>, then reads one expression from the
     console and returns the expression (without evaluation).  The
     expression is terminated with a `;' (semicolon) or `$' (dollar
     sign).

     See also `read'.

     Examples:

          (%i1) aa: 7$
          (%i2) foo: readonly ("Enter an expression:");
          Enter an expression:
          2^aa;
                                            aa
          (%o2)                            2
          (%i3) foo: read ("Enter an expression:");
          Enter an expression:
          2^aa;
          (%o3)                            128


 -- Function: reset ()
     Resets many global variables and options, and some other
     variables, to their default values.

     `reset' processes the variables on the Lisp list
     `*variable-initial-values*'.  The Lisp macro `defmvar' puts
     variables on this list (among other actions).  Many, but not all,
     global variables and options are defined by `defmvar', and some
     variables defined by `defmvar' are not global variables or options.


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

     When `showtime' is `true', the computation time and elapsed time is
     printed with each output expression.

     The computation time is always recorded, so `time' and `playback'
     can display the computation time even when `showtime' is `false'.

     See also `timer'.


 -- Function: to_lisp ()
     Enters the Lisp system under Maxima.  `(to-maxima)' returns to
     Maxima.

     Example:

     Define a function and enter the Lisp system under Maxima.  The
     definition is inspected on the property list, then the function
     definition is extracted, factored and stored in the variable
     $result.  The variable can be used in Maxima after returning to
     Maxima.

          (%i1) f(x):=x^2+x;
                                            2
          (%o1)                    f(x) := x  + x
          (%i2) to_lisp();
          Type (to-maxima) to restart, ($quit) to quit Maxima.
          MAXIMA> (symbol-plist '$f)
          (MPROPS (NIL MEXPR ((LAMBDA) ((MLIST) $X)
                                       ((MPLUS) ((MEXPT) $X 2) $X))))
          MAXIMA> (setq $result ($factor (caddr (mget '$f 'mexpr))))
          ((MTIMES SIMP FACTORED) $X ((MPLUS SIMP IRREDUCIBLE) 1 $X))
          MAXIMA> (to-maxima)
          Returning to Maxima
          (%o2)                         true
          (%i3) result;
          (%o3)                       x (x + 1)


 -- System variable: values
     Initial value: `[]'

     `values' is a list of all bound user variables (not Maxima options
     or switches).  The list comprises symbols bound by `:', or `::'.

     If the value of a variable is removed with the commands `kill',
     `remove', or `remvalue' the variable is deleted from `values'.

     See `functions' for a list of user defined functions.

     Examples:

     First, `values' shows the symbols `a', `b', and `c', but not `d',
     it is not bound to a value, and not the user function `f'.  The
     values are removed from the variables.  `values' is the empty list.

          (%i1) [a:99, b::a-90, c:a-b, d, f(x):= x^2];
                                                     2
          (%o1)              [99, 9, 90, d, f(x) := x ]
          (%i2) values;
          (%o2)                       [a, b, c]
          (%i3) [kill(a), remove(b,value), remvalue(c)];
          (%o3)                   [done, done, [c]]
          (%i4) values;
          (%o4)                          []



File: maxima.info,  Node: Functions and Variables for Display,  Prev: Functions and Variables for Command Line,  Up: Command Line

4.3 Functions and Variables for Display
=======================================

 -- Option variable: %edispflag
     Default value: `false'

     When `%edispflag' is `true', Maxima displays `%e' to a negative
     exponent as a quotient.  For example, `%e^-x' is displayed as
     `1/%e^x'.  See also `exptdispflag'.

     Example:

          (%i1) %e^-10;
                                         - 10
          (%o1)                        %e
          (%i2) %edispflag:true$
          (%i3) %e^-10;
                                         1
          (%o3)                         ----
                                          10
                                        %e


 -- Option variable: absboxchar
     Default value: `!'

     `absboxchar' is the character used to draw absolute value signs
     around expressions which are more than one line tall.

     Example:

          (%i1) abs((x^3+1));
                                      ! 3    !
          (%o1)                       !x  + 1!


 -- Function: disp (<expr_1>, <expr_2>, ...)
     is like `display' but only the value of the arguments are
     displayed rather than equations.  This is useful for complicated
     arguments which don't have names or where only the value of the
     argument is of interest and not the name.

     See also `ldisp' and `print'.

     Example:

          (%i1) b[1,2]:x-x^2$
          (%i2) x:123$
          (%i3) disp(x, b[1,2], sin(1.0));
                                         123

                                            2
                                       x - x

                                  .8414709848078965

          (%o3)                         done


 -- Function: display (<expr_1>, <expr_2>, ...)
     Displays equations whose left side is <expr_i> unevaluated, and
     whose right side is the value of the expression centered on the
     line.  This function is useful in blocks and `for' statements in
     order to have intermediate results displayed.  The arguments to
     `display' are usually atoms, subscripted variables, or function
     calls.

     See also `ldisplay', `disp', and `ldisp'.

     Example:

          (%i1) b[1,2]:x-x^2$
          (%i2) x:123$
          (%i3) display(x, b[1,2], sin(1.0));
                                       x = 123

                                                2
                                   b     = x - x
                                    1, 2

                            sin(1.0) = .8414709848078965

          (%o3)                         done


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

     When `display2d' is `false', the console display is a string
     (1-dimensional) form rather than a display (2-dimensional) form.

     See also `leftjust' to switch between a left justified and a
     centered display of equations.

     Example:

          (%i1) x/(x^2+1);
                                         x
          (%o1)                        ------
                                        2
                                       x  + 1
          (%i2) display2d:false$
          (%i3) x/(x^2+1);
          (%o3) x/(x^2+1)


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

     When `display_format_internal' is `true', expressions are displayed
     without being transformed in ways that hide the internal
     mathematical representation.  The display then corresponds to what
     `inpart' returns rather than `part'.

     Examples:

          User     part       inpart
          a-b;      a - b     a + (- 1) b

                     a            - 1
          a/b;       -         a b
                     b
                                 1/2
          sqrt(x);   sqrt(x)    x

                    4 X        4
          X*4/3;    ---        - X
                     3         3


 -- Function: dispterms (<expr>)
     Displays <expr> in parts one below the other.  That is, first the
     operator of <expr> is displayed, then each term in a sum, or
     factor in a product, or part of a more general expression is
     displayed separately.  This is useful if <expr> is too large to be
     otherwise displayed.  For example if `P1', `P2', ...  are very
     large expressions then the display program may run out of storage
     space in trying to display `P1 + P2 + ...'  all at once.  However,
     `dispterms (P1 + P2 + ...)' displays `P1', then below it `P2',
     etc.  When not using `dispterms', if an exponential expression is
     too wide to be displayed as `A^B' it appears as `expt (A, B)' (or
     as `ncexpt (A, B)' in the case of `A^^B').

     Example:

          (%i1) dispterms(2*a*sin(x)+%e^x);

          +

          2 a sin(x)

            x
          %e

          (%o1)                         done


 -- Special symbol: expt (<a>, <b>)
 -- Special symbol: ncexpt (<a>, <b>)
     If an exponential expression is too wide to be displayed as
     `<a>^<b>' it appears as `expt (<a>, <b>)' (or as `ncexpt (<a>,
     <b>)' in the case of `<a>^^<b>').

     `expt' and `ncexpt' are not recognized in input.

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

     When `exptdispflag' is `true', Maxima displays expressions with
     negative exponents using quotients.  See also `%edispflag'.

     Example:

          (%i1) exptdispflag:true;
          (%o1)                         true
          (%i2) 10^-x;
                                          1
          (%o2)                          ---
                                           x
                                         10
          (%i3) exptdispflag:false;
          (%o3)                         false
          (%i4) 10^-x;
                                          - x
          (%o4)                         10


 -- Function: grind (<expr>)
 -- Option variable: grind
     The function `grind' prints <expr> to the console in a form
     suitable for input to Maxima.  `grind' always returns `done'.

     When <expr> is the name of a function or macro, `grind' prints the
     function or macro definition instead of just the name.

     See also `string', which returns a string instead of printing its
     output.  `grind' attempts to print the expression in a manner
     which makes it slightly easier to read than the output of `string'.

     When the variable `grind' is `true', the output of `string' and
     `stringout' has the same format as that of `grind'; otherwise no
     attempt is made to specially format the output of those functions.
     The default value of the variable `grind' is `false'.

     `grind' can also be specified as an argument of `playback'.  When
     `grind' is present, `playback' prints input expressions in the same
     format as the `grind' function.  Otherwise, no attempt is made to
     specially format input expressions.

     `grind' evaluates its argument.

     Examples:

          (%i1) aa + 1729;
          (%o1)                       aa + 1729
          (%i2) grind (%);
          aa+1729$
          (%o2)                         done
          (%i3) [aa, 1729, aa + 1729];
          (%o3)                 [aa, 1729, aa + 1729]
          (%i4) grind (%);
          [aa,1729,aa+1729]$
          (%o4)                         done
          (%i5) matrix ([aa, 17], [29, bb]);
                                     [ aa  17 ]
          (%o5)                      [        ]
                                     [ 29  bb ]
          (%i6) grind (%);
          matrix([aa,17],[29,bb])$
          (%o6)                         done
          (%i7) set (aa, 17, 29, bb);
          (%o7)                   {17, 29, aa, bb}
          (%i8) grind (%);
          {17,29,aa,bb}$
          (%o8)                         done
          (%i9) exp (aa / (bb + 17)^29);
                                          aa
                                      -----------
                                               29
                                      (bb + 17)
          (%o9)                     %e
          (%i10) grind (%);
          %e^(aa/(bb+17)^29)$
          (%o10)                        done
          (%i11) expr: expand ((aa + bb)^10);
                   10           9        2   8         3   7         4   6
          (%o11) bb   + 10 aa bb  + 45 aa  bb  + 120 aa  bb  + 210 aa  bb
                   5   5         6   4         7   3        8   2
           + 252 aa  bb  + 210 aa  bb  + 120 aa  bb  + 45 aa  bb
                  9        10
           + 10 aa  bb + aa
          (%i12) grind (expr);
          bb^10+10*aa*bb^9+45*aa^2*bb^8+120*aa^3*bb^7+210*aa^4*bb^6
               +252*aa^5*bb^5+210*aa^6*bb^4+120*aa^7*bb^3+45*aa^8*bb^2
               +10*aa^9*bb+aa^10$
          (%o12)                        done
          (%i13) string (expr);
          (%o13) bb^10+10*aa*bb^9+45*aa^2*bb^8+120*aa^3*bb^7+210*aa^4*bb^6\
          +252*aa^5*bb^5+210*aa^6*bb^4+120*aa^7*bb^3+45*aa^8*bb^2+10*aa^9*\
          bb+aa^10
          (%i14) cholesky (A):= block ([n : length (A), L : copymatrix (A),
            p : makelist (0, i, 1, length (A))], for i thru n do
            for j : i thru n do
            (x : L[i, j], x : x - sum (L[j, k] * L[i, k], k, 1, i - 1),
            if i = j then p[i] : 1 / sqrt(x) else L[j, i] : x * p[i]),
            for i thru n do L[i, i] : 1 / p[i],
            for i thru n do for j : i + 1 thru n do L[i, j] : 0, L)$
          (%i15) grind (cholesky);
          cholesky(A):=block(
                   [n:length(A),L:copymatrix(A),
                    p:makelist(0,i,1,length(A))],
                   for i thru n do
                       (for j from i thru n do
                            (x:L[i,j],x:x-sum(L[j,k]*L[i,k],k,1,i-1),
                             if i = j then p[i]:1/sqrt(x)
                                 else L[j,i]:x*p[i])),
                   for i thru n do L[i,i]:1/p[i],
                   for i thru n do (for j from i+1 thru n do L[i,j]:0),L)$
          (%o15)                        done
          (%i16) string (fundef (cholesky));
          (%o16) cholesky(A):=block([n:length(A),L:copymatrix(A),p:makelis\
          t(0,i,1,length(A))],for i thru n do (for j from i thru n do (x:L\
          [i,j],x:x-sum(L[j,k]*L[i,k],k,1,i-1),if i = j then p[i]:1/sqrt(x\
          ) else L[j,i]:x*p[i])),for i thru n do L[i,i]:1/p[i],for i thru \
          n do (for j from i+1 thru n do L[i,j]:0),L)


 -- Option variable: ibase
     Default value: `10'

     `ibase' is the base for integers read by Maxima.

     `ibase' may be assigned any integer between 2 and 36 (decimal),
     inclusive.  When `ibase' is greater than 10, the numerals comprise
     the decimal numerals 0 through 9 plus letters of the alphabet A,
     B, C, ..., as needed to make `ibase' digits in all.  Letters are
     interpreted as digits only if the first digit is 0 through 9.
     Uppercase and lowercase letters are not distinguished.  The
     numerals for base 36, the largest acceptable base, comprise 0
     through 9 and A through Z.

     Whatever the value of `ibase', when an integer is terminated by a
     decimal point, it is interpreted in base 10.

     See also `obase'.

     Examples:

     `ibase' less than 10.

          (%i1) ibase : 2 $
          (%i2) obase;
          (%o2)                          10
          (%i3) 1111111111111111;
          (%o3)                         65535

     `ibase' greater than 10.  Letters are interpreted as digits only
     if the first digit is 0 through 9.

          (%i1) ibase : 16 $
          (%i2) obase;
          (%o2)                          10
          (%i3) 1000;
          (%o3)                         4096
          (%i4) abcd;
          (%o4)                         abcd
          (%i5) symbolp (abcd);
          (%o5)                         true
          (%i6) 0abcd;
          (%o6)                         43981
          (%i7) symbolp (0abcd);
          (%o7)                         false

     When an integer is terminated by a decimal point, it is
     interpreted in base 10.

          (%i1) ibase : 36 $
          (%i2) obase;
          (%o2)                          10
          (%i3) 1234;
          (%o3)                         49360
          (%i4) 1234.;
          (%o4)                         1234


 -- Function: ldisp (<expr_1>, ..., <expr_n>)
     Displays expressions <expr_1>, ..., <expr_n> to the console as
     printed output.  `ldisp' assigns an intermediate expression label
     to each argument and returns the list of labels.

     See also `disp', `display', and `ldisplay'.

     Examples:

          (%i1) e: (a+b)^3;
                                             3
          (%o1)                       (b + a)
          (%i2) f: expand (e);
                               3        2      2      3
          (%o2)               b  + 3 a b  + 3 a  b + a
          (%i3) ldisp (e, f);
                                             3
          (%t3)                       (b + a)

                               3        2      2      3
          (%t4)               b  + 3 a b  + 3 a  b + a

          (%o4)                      [%t3, %t4]
          (%i4) %t3;
                                             3
          (%o4)                       (b + a)
          (%i5) %t4;
                               3        2      2      3
          (%o5)               b  + 3 a b  + 3 a  b + a


 -- Function: ldisplay (<expr_1>, ..., <expr_n>)
     Displays expressions <expr_1>, ..., <expr_n> to the console as
     printed output.  Each expression is printed as an equation of the
     form `lhs = rhs' in which `lhs' is one of the arguments of
     `ldisplay' and `rhs' is its value.  Typically each argument is a
     variable.  `ldisp' assigns an intermediate expression label to
     each equation and returns the list of labels.

     See also `display', `disp', and `ldisp'.

     Examples:

          (%i1) e: (a+b)^3;
                                             3
          (%o1)                       (b + a)
          (%i2) f: expand (e);
                               3        2      2      3
          (%o2)               b  + 3 a b  + 3 a  b + a
          (%i3) ldisplay (e, f);
                                               3
          (%t3)                     e = (b + a)

                                 3        2      2      3
          (%t4)             f = b  + 3 a b  + 3 a  b + a

          (%o4)                      [%t3, %t4]
          (%i4) %t3;
                                               3
          (%o4)                     e = (b + a)
          (%i5) %t4;
                                 3        2      2      3
          (%o5)             f = b  + 3 a b  + 3 a  b + a


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

     When `leftjust' is `true', equations in 2D-display are drawn left
     justified rather than centered.

     See also `display2d' to switch between 1D- and 2D-display.

     Example:

          (%i1) expand((x+1)^3);
                                  3      2
          (%o1)                  x  + 3 x  + 3 x + 1
          (%i2) leftjust:true$
          (%i3) expand((x+1)^3);
                 3      2
          (%o3) x  + 3 x  + 3 x + 1


 -- Option variable: linel
     Default value: `79'

     `linel' is the assumed width (in characters) of the console
     display for the purpose of displaying expressions.  `linel' may be
     assigned any value by the user, although very small or very large
     values may be impractical.  Text printed by built-in Maxima
     functions, such as error messages and the output of `describe', is
     not affected by `linel'.


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

     When `lispdisp' is `true', Lisp symbols are displayed with a
     leading question mark `?'.  Otherwise, Lisp symbols are displayed
     with no leading mark.

     Examples:

          (%i1) lispdisp: false$
          (%i2) ?foo + ?bar;
          (%o2)                       foo + bar
          (%i3) lispdisp: true$
          (%i4) ?foo + ?bar;
          (%o4)                      ?foo + ?bar


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

     When `negsumdispflag' is `true', `x - y' displays as `x - y'
     instead of as `- y + x'.  Setting it to `false' causes the special
     check in display for the difference of two expressions to not be
     done.  One application is that thus `a + %i*b' and `a - %i*b' may
     both be displayed the same way.


 -- Option variable: obase
     Default value: `10'

     `obase' is the base for integers displayed by Maxima.

     `obase' may be assigned any integer between 2 and 36 (decimal),
     inclusive.  When `obase' is greater than 10, the numerals comprise
     the decimal numerals 0 through 9 plus capital letters of the
     alphabet A, B, C, ..., as needed.  A leading 0 digit is displayed
     if the leading digit is otherwise a letter.  The numerals for base
     36, the largest acceptable base, comprise 0 through 9, and A
     through Z.

     See also `ibase'.

     Examples:

          (%i1) obase : 2;
          (%o1)                          10
          (%i2) 2^8 - 1;
          (%o10)                      11111111
          (%i3) obase : 8;
          (%o3)                          10
          (%i4) 8^8 - 1;
          (%o4)                       77777777
          (%i5) obase : 16;
          (%o5)                          10
          (%i6) 16^8 - 1;
          (%o6)                       0FFFFFFFF
          (%i7) obase : 36;
          (%o7)                          10
          (%i8) 36^8 - 1;
          (%o8)                       0ZZZZZZZZ


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

     When `pfeformat' is `true', a ratio of integers is displayed with
     the solidus (forward slash) character, and an integer denominator
     `n' is displayed as a leading multiplicative term `1/n'.

     Examples:

          (%i1) pfeformat: false$
          (%i2) 2^16/7^3;
                                        65536
          (%o2)                         -----
                                         343
          (%i3) (a+b)/8;
                                        b + a
          (%o3)                         -----
                                          8
          (%i4) pfeformat: true$
          (%i5) 2^16/7^3;
          (%o5)                       65536/343
          (%i6) (a+b)/8;
          (%o6)                      1/8 (b + a)


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

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

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

     Example:

          (%i1) powerdisp:true;
          (%o1)                         true
          (%i2) x^2+x^3+x^4;
                                     2    3    4
          (%o2)                     x  + x  + x
          (%i3) powerdisp:false;
          (%o3)                         false
          (%i4) x^2+x^3+x^4;
                                     4    3    2
          (%o4)                     x  + x  + x


 -- Function: print (<expr_1>, ..., <expr_n>)
     Evaluates and displays <expr_1>, ..., <expr_n> one after another,
     from left to right, starting at the left edge of the console
     display.

     The value returned by `print' is the value of its last argument.
     `print' does not generate intermediate expression labels.

     See also `display', `disp', `ldisplay', and `ldisp'.  Those
     functions display one expression per line, while `print' attempts
     to display two or more expressions per line.

     To display the contents of a file, see `printfile'.

     Examples:

          (%i1) r: print ("(a+b)^3 is", expand ((a+b)^3), "log (a^10/b) is",
                radcan (log (a^10/b)))$
                      3        2      2      3
          (a+b)^3 is b  + 3 a b  + 3 a  b + a  log (a^10/b) is

                                                        10 log(a) - log(b)
          (%i2) r;
          (%o2)                  10 log(a) - log(b)
          (%i3) disp ("(a+b)^3 is", expand ((a+b)^3), "log (a^10/b) is",
                radcan (log (a^10/b)))$
                                     (a+b)^3 is

                               3        2      2      3
                              b  + 3 a b  + 3 a  b + a

                                   log (a^10/b) is

                                 10 log(a) - log(b)


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

     When `sqrtdispflag' is `false', causes `sqrt' to display with
     exponent 1/2.


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

     When `stardisp' is `true', multiplication is displayed with an
     asterisk `*' between operands.


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

     When `ttyoff' is `true', output expressions are not displayed.
     Output expressions are still computed and assigned labels.  See
     `labels'.

     Text printed by built-in Maxima functions, such as error messages
     and the output of `describe', is not affected by `ttyoff'.



File: maxima.info,  Node: Data Types and Structures,  Next: Expressions,  Prev: Command Line,  Up: Top

5 Data Types and Structures
***************************

* Menu:

* Numbers::
* Strings::
* Constants::
* Lists::
* Arrays::
* Structures::


File: maxima.info,  Node: Numbers,  Next: Strings,  Prev: Data Types and Structures,  Up: Data Types and Structures

5.1 Numbers
===========

* Menu:

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


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

5.1.1 Introduction to Numbers
-----------------------------

Complex numbers
---------------

A complex expression is specified in Maxima by adding the real part of
the expression to `%i' times the imaginary part.  Thus the roots of the
equation `x^2 - 4*x + 13 = 0' are `2 + 3*%i' and `2 - 3*%i'.  Note that
simplification of products of complex expressions can be effected by
expanding the product.  Simplification of quotients, roots, and other
functions of complex expressions can usually be accomplished by using
the `realpart', `imagpart', `rectform', `polarform', `abs', `carg'
functions.

Floating point numbers
----------------------

Maxima has two types of floating point number. The first is just called
a "float" (but will be called a "machine float" for the rest of this
section to avoid ambiguity). This is stored in the underlying lisp's
DOUBLE-FLOAT type which will almost certainly be IEEE 754 double
precision floating point. To type a literal floating point number, just
type its decimal expansion (for example, `0.01') or type it with an
explicit exponent (such as `1e-2' or `0.1e-1').

   The second type of floating point number in Maxima is called a
"bigfloat". Bigfloats are stored as a mantissa and exponent in the same
way as machine floats but the exponent is an arbitrary precision
integer, so they can represent arbitrarily large or small numbers. The
user can also customise the precision of bigfloat arithmetic (which
corresponds to choosing the range of the mantissa). See `fpprec' for
more information. To type a literal bigfloat, use the exponent notation
as above but with the character `b' in place of `e'. The example of
`0.01' from above could be entered as a bigfloat with `1b-2' or
`0.001b0'.

   Calculations using machine floats can be significantly faster than
using bigfloats since modern computer processors have dedicated
hardware for them. This is particularly noticeable with compiled Maxima
code. However, machine floats suffer from the problem of overflow,
where a number can become too large for its exponent to be represented
in the bits available. In interpreted code, the default behaviour is
that a calculation that would cause a floating point overflow instead
generates a bigfloat number. To configure this, see the
`promote_float_to_bigfloat' variable.


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

5.1.2 Functions and Variables for Numbers
-----------------------------------------

 -- Function: bfloat (<expr>)
     Converts all numbers and functions of numbers in <expr> to
     bigfloat numbers.  The number of significant digits in the
     resulting bigfloats is specified by the global variable `fpprec'.

     When `float2bf' is `false' a warning message is printed when a
     floating point number is converted into a bigfloat number (since
     this may lead to loss of precision).


 -- Function: bfloatp (<expr>)
     Returns `true' if <expr> is a bigfloat number, otherwise `false'.


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

     `bftorat' controls the conversion of bfloats to rational numbers.
     When `bftorat' is `false', `ratepsilon' will be used to control the
     conversion (this results in relatively small rational numbers).
     When `bftorat' is `true', the rational number generated will
     accurately represent the bfloat.

     Note: `bftorat' has no effect on the transformation to rational
     numbers with the function `rationalize'.

     Example:

          (%i1) ratepsilon:1e-4;
          (%o1)                         1.e-4
          (%i2) rat(bfloat(11111/111111)), bftorat:false;
          `rat' replaced 9.99990999991B-2 by 1/10 = 1.0B-1
                                         1
          (%o2)/R/                       --
                                         10
          (%i3) rat(bfloat(11111/111111)), bftorat:true;
          `rat' replaced 9.99990999991B-2 by 11111/111111 = 9.99990999991B-2
                                       11111
          (%o3)/R/                     ------
                                       111111


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

     `bftrunc' causes trailing zeroes in non-zero bigfloat numbers not
     to be displayed.  Thus, if `bftrunc' is `false', `bfloat (1)'
     displays as `1.000000000000000B0'.  Otherwise, this is displayed as
     `1.0B0'.


 -- Function: evenp (<expr>)
     Returns `true' if <expr> is an even integer.  `false' is returned
     in all other cases.


 -- Function: float (<expr>)
     Converts integers, rational numbers and bigfloats in <expr> to
     floating point numbers.  It is also an `evflag', `float' causes
     non-integral rational numbers and bigfloat numbers to be converted
     to floating point.


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

     When `float2bf' is `false', a warning message is printed when a
     floating point number is converted into a bigfloat number (since
     this may lead to loss of precision).


 -- Function: floatnump (<expr>)
     Returns `true' if <expr> is a floating point number, otherwise
     `false'.


 -- Option variable: fpprec
     Default value: 16

     `fpprec' is the number of significant digits for arithmetic on
     bigfloat numbers.  `fpprec' does not affect computations on
     ordinary floating point numbers.

     See also `bfloat' and `fpprintprec'.


 -- Option variable: fpprintprec
     Default value: 0

     `fpprintprec' is the number of digits to print when printing an
     ordinary float or bigfloat number.

     For ordinary floating point numbers, when `fpprintprec' has a
     value between 2 and 16 (inclusive), the number of digits printed
     is equal to `fpprintprec'.  Otherwise, `fpprintprec' is 0, or
     greater than 16, and the number of digits printed is 16.

     For bigfloat numbers, when `fpprintprec' has a value between 2 and
     `fpprec' (inclusive), the number of digits printed is equal to
     `fpprintprec'.  Otherwise, `fpprintprec' is 0, or greater than
     `fpprec', and the number of digits printed is equal to `fpprec'.

     `fpprintprec' cannot be 1.


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

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

     Examples:

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


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

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

                        domain:real

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

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


 -- Function: nonnegintegerp (<n>)
     Return `true' if and only if `<n> >= 0' and <n> is an integer.


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

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

     Examples:

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


 -- Option variable: numer
     `numer' causes some mathematical functions (including
     exponentiation) with numerical arguments to be evaluated in
     floating point.  It causes variables in `expr' which have been
     given numerals to be replaced by their values.  It also sets the
     `float' switch on.

     See also `%enumer'.

     Examples:

          (%i1) [sqrt(2), sin(1), 1/(1+sqrt(3))];
                                                  1
          (%o1)            [sqrt(2), sin(1), -----------]
                                             sqrt(3) + 1
          (%i2) [sqrt(2), sin(1), 1/(1+sqrt(3))],numer;
          (%o2) [1.414213562373095, .8414709848078965, .3660254037844387]


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

     The option variable `numer_pbranch' controls the numerical
     evaluation of the power of a negative integer, rational, or
     floating point number.  When `numer_pbranch' is `true' and the
     exponent is a floating point number or the option variable `numer'
     is `true' too, Maxima evaluates the numerical result using the
     principal branch.  Otherwise a simplified, but not an evaluated
     result is returned.

     Examples:

          (%i1) (-2)^0.75;
          (%o1) (-2)^0.75

          (%i2) (-2)^0.75,numer_pbranch:true;
          (%o2) 1.189207115002721*%i-1.189207115002721

          (%i3) (-2)^(3/4);
          (%o3) (-1)^(3/4)*2^(3/4)

          (%i4) (-2)^(3/4),numer;
          (%o4) 1.681792830507429*(-1)^0.75

          (%i5) (-2)^(3/4),numer,numer_pbranch:true;
          (%o5) 1.189207115002721*%i-1.189207115002721


 -- Function: numerval (<x_1>, <expr_1>, ..., <var_n>, <expr_n>)
     Declares the variables `x_1', ..., <x_n> to have numeric values
     equal to `expr_1', ..., `expr_n'.  The numeric value is evaluated
     and substituted for the variable in any expressions in which the
     variable occurs if the `numer' flag is `true'.  See also `ev'.

     The expressions `expr_1', ..., `expr_n' can be any expressions,
     not necessarily numeric.


 -- Function: oddp (<expr>)
     is `true' if <expr> is an odd integer.  `false' is returned in all
     other cases.


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

     When `promote_float_to_bigfloat' is true, the result of any
     floating point calculation that would normally cause a floating
     point overflow is replaced by a bigfloat number that represents the
     result. Note that this automatic promotion only happens in
     interpreted code: compiled code is not affected.

     This automatic conversion is often convenient, but can be
     unhelpful in some cases. For example, it can actually cause a loss
     of precision if `fpprec' is currently smaller than the precision
     in a floating point number. To disable this behaviour, set
     `promote_float_to_bigfloat' to false.


 -- Option variable: ratepsilon
     Default value: `2.0e-15'

     `ratepsilon' is the tolerance used in the conversion of floating
     point numbers to rational numbers, when the option variable
     `bftorat' has the value `false'.  See `bftorat' for an example.


 -- Function: rationalize (<expr>)
     Convert all double floats and big floats in the Maxima expression
     <expr> to their exact rational equivalents.  If you are not
     familiar with the binary representation of floating point numbers,
     you might be surprised that `rationalize (0.1)' does not equal
     1/10.  This behavior isn't special to Maxima - the number 1/10 has
     a repeating, not a terminating, binary representation.

          (%i1) rationalize (0.5);
                                          1
          (%o1)                           -
                                          2
          (%i2) rationalize (0.1);
                                         1
          (%o2)                          --
                                         10
          (%i3) fpprec : 5$
          (%i4) rationalize (0.1b0);
                                       209715
          (%o4)                        -------
                                       2097152
          (%i5) fpprec : 20$
          (%i6) rationalize (0.1b0);
                               236118324143482260685
          (%o6)                ----------------------
                               2361183241434822606848
          (%i7) rationalize (sin (0.1*x + 5.6));
                                        x    28
          (%o7)                     sin(-- + --)
                                        10   5


 -- Function: ratnump (<expr>)
     Returns `true' if <expr> is a literal integer or ratio of literal
     integers, otherwise `false'.



File: maxima.info,  Node: Strings,  Next: Constants,  Prev: Numbers,  Up: Data Types and Structures

5.2 Strings
===========

* Menu:

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


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

5.2.1 Introduction to Strings
-----------------------------

Strings (quoted character sequences) are enclosed in double quote marks
`"' for input, and displayed with or without the quote marks, depending
on the global variable `stringdisp'.

   Strings may contain any characters, including embedded tab, newline,
and carriage return characters.  The sequence `\"' is recognized as a
literal double quote, and `\\' as a literal backslash.  When backslash
appears at the end of a line, the backslash and the line termination
(either newline or carriage return and newline) are ignored, so that
the string continues with the next line.  No other special combinations
of backslash with another character are recognized; when backslash
appears before any character other than `"', `\', or a line
termination, the backslash is ignored.  There is no way to represent a
special character (such as tab, newline, or carriage return) except by
embedding the literal character in the string.

   There is no character type in Maxima; a single character is
represented as a one-character string.

   The `stringproc' add-on package contains many functions for working
with strings.

   Examples:

     (%i1) s_1 : "This is a string.";
     (%o1)               This is a string.
     (%i2) s_2 : "Embedded \"double quotes\" and backslash \\ characters.";
     (%o2) Embedded "double quotes" and backslash \ characters.
     (%i3) s_3 : "Embedded line termination
     in this string.";
     (%o3) Embedded line termination
     in this string.
     (%i4) s_4 : "Ignore the \
     line termination \
     characters in \
     this string.";
     (%o4) Ignore the line termination characters in this string.
     (%i5) stringdisp : false;
     (%o5)                         false
     (%i6) s_1;
     (%o6)                   This is a string.
     (%i7) stringdisp : true;
     (%o7)                         true
     (%i8) s_1;
     (%o8)                  "This is a string."


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

5.2.2 Functions and Variables for Strings
-----------------------------------------

 -- Function: concat (<arg_1>, <arg_2>, ...)
     Concatenates its arguments.  The arguments must evaluate to atoms.
     The return value is a symbol if the first argument is a symbol and
     a string otherwise.

     `concat' evaluates its arguments.  The single quote `'' prevents
     evaluation.

          (%i1) y: 7$
          (%i2) z: 88$
          (%i3) concat (y, z/2);
          (%o3)                          744
          (%i4) concat ('y, z/2);
          (%o4)                          y44

     A symbol constructed by `concat' may be assigned a value and
     appear in expressions.  The `::' (double colon) assignment
     operator evaluates its left-hand side.

          (%i5) a: concat ('y, z/2);
          (%o5)                          y44
          (%i6) a:: 123;
          (%o6)                          123
          (%i7) y44;
          (%o7)                          123
          (%i8) b^a;
                                         y44
          (%o8)                         b
          (%i9) %, numer;
                                         123
          (%o9)                         b

     Note that although `concat (1, 2)' looks like a number, it is a
     string.

          (%i10) concat (1, 2) + 3;
          (%o10)                       12 + 3


 -- Function: sconcat (<arg_1>, <arg_2>, ...)
     Concatenates its arguments into a string.  Unlike `concat', the
     arguments do not need to be atoms.

          (%i1) sconcat ("xx[", 3, "]:", expand ((x+y)^3));
          (%o1)               xx[3]:y^3+3*x*y^2+3*x^2*y+x^3


 -- Function: string (<expr>)
     Converts `expr' to Maxima's linear notation just as if it had been
     typed in.

     The return value of `string' is a string, and thus it cannot be
     used in a computation.


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

     When `stringdisp' is `true', strings are displayed enclosed in
     double quote marks.  Otherwise, quote marks are not displayed.

     `stringdisp' is always `true' when displaying a function
     definition.

     Examples:

          (%i1) stringdisp: false$
          (%i2) "This is an example string.";
          (%o2)              This is an example string.
          (%i3) foo () :=
                print ("This is a string in a function definition.");
          (%o3) foo() :=
                        print("This is a string in a function definition.")
          (%i4) stringdisp: true$
          (%i5) "This is an example string.";
          (%o5)             "This is an example string."



File: maxima.info,  Node: Constants,  Next: Lists,  Prev: Strings,  Up: Data Types and Structures

5.3 Constants
=============

* Menu:

* Functions and Variables for Constants::


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

5.3.1 Functions and Variables for Constants
-------------------------------------------

 -- Constant: %e
     `%e' represents the base of the natural logarithm, also known as
     Euler's number.  The numeric value of `%e' is the double-precision
     floating-point value 2.718281828459045d0.


 -- Constant: %i
     `%i' represents the imaginary unit, sqrt(- 1).


 -- Constant: false
     `false' represents the Boolean constant of the same name.  Maxima
     implements `false' by the value `NIL' in Lisp.


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


 -- Constant: ind
     `ind' represents a bounded, indefinite result.

     See also `limit'.

     Example:

          (%i1) limit (sin(1/x), x, 0);
          (%o1)                          ind


 -- Constant: inf
     `inf' represents real positive infinity.


 -- Constant: infinity
     `infinity' represents complex infinity.


 -- Constant: minf
     `minf' represents real minus (i.e., negative) infinity.


 -- Constant: %phi
     `%phi' represents the so-called golden mean, (1 + sqrt(5))/2.  The
     numeric value of `%phi' is the double-precision floating-point
     value 1.618033988749895d0.

     `fibtophi' expresses Fibonacci numbers `fib(n)' in terms of `%phi'.

     By default, Maxima does not know the algebraic properties of
     `%phi'.  After evaluating `tellrat(%phi^2 - %phi - 1)' and
     `algebraic: true', `ratsimp' can simplify some expressions
     containing `%phi'.

     Examples:

     `fibtophi' expresses Fibonacci numbers `fib(n)' in terms of `%phi'.

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

     By default, Maxima does not know the algebraic properties of
     `%phi'.  After evaluating `tellrat (%phi^2 - %phi - 1)' and
     `algebraic: true', `ratsimp' can simplify some expressions
     containing `%phi'.

          (%i1) e : expand ((%phi^2 - %phi - 1) * (A + 1));
                           2                      2
          (%o1)        %phi  A - %phi A - A + %phi  - %phi - 1
          (%i2) ratsimp (e);
                            2                     2
          (%o2)        (%phi  - %phi - 1) A + %phi  - %phi - 1
          (%i3) tellrat (%phi^2 - %phi - 1);
                                      2
          (%o3)                  [%phi  - %phi - 1]
          (%i4) algebraic : true;
          (%o4)                         true
          (%i5) ratsimp (e);
          (%o5)                           0


 -- Constant: %pi
     `%pi' represents the ratio of the perimeter of a circle to its
     diameter.  The numeric value of `%pi' is the double-precision
     floating-point value 3.141592653589793d0.


 -- Constant: true
     `true' represents the Boolean constant of the same name.  Maxima
     implements `true' by the value `T' in Lisp.


 -- Constant: und
     `und' represents an undefined result.

     See also `limit'.

     Example:

          (%i1) limit (x*sin(x), x, inf);
          (%o1)                          und


 -- Constant: zeroa
     `zeroa' represents an infinitesimal above zero.  `zeroa' can be
     used in expressions.  `limit' simplifies expressions which contain
     infinitesimals.

     See also `zerob' and `limit'.

     Example:

     `limit' simplifies expressions which contain infinitesimals:

          (%i1) limit(zeroa);
          (%o1)                           0
          (%i2) limit(x+zeroa);
          (%o2)                           x


 -- Constant: zerob
     `zerob' represents an infinitesimal below zero.  `zerob' can be
     used in expressions.  `limit' simplifies expressions which contain
     infinitesimals.

     See also `zeroa' and `limit'.



File: maxima.info,  Node: Lists,  Next: Arrays,  Prev: Constants,  Up: Data Types and Structures

5.4 Lists
=========

* Menu:

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


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

5.4.1 Introduction to Lists
---------------------------

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

     ((MPLUS) $A 2)

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

     [1, 2, 7, x+y]

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

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

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

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


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

5.4.2 Functions and Variables for Lists
---------------------------------------

 -- Operator: [
 -- Operator: ]
     `[' and `]' mark the beginning and end, respectively, of a list.

     `[' and `]' also enclose the subscripts of a list, array, hash
     array, or array function.

     Examples:

          (%i1) x: [a, b, c];
          (%o1)                       [a, b, c]
          (%i2) x[3];
          (%o2)                           c
          (%i3) array (y, fixnum, 3);
          (%o3)                           y
          (%i4) y[2]: %pi;
          (%o4)                          %pi
          (%i5) y[2];
          (%o5)                          %pi
          (%i6) z['foo]: 'bar;
          (%o6)                          bar
          (%i7) z['foo];
          (%o7)                          bar
          (%i8) g[k] := 1/(k^2+1);
                                            1
          (%o8)                     g  := ------
                                     k     2
                                          k  + 1
          (%i9) g[10];
                                          1
          (%o9)                          ---
                                         101


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

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


 -- Function: assoc (<key>, <list>, <default>)
 -- Function: assoc (<key>, <list>)
     This function searches for <key> in the left hand side of the
     input <list>. The <list> argument should be a list, each of whose
     elements is an expression with exactly two parts. Most usually,
     the elements of <list> are themselves lists, each with two
     elements.

     The `assoc' function iterates along <list>, checking the first
     part of each element for equality with <key>. If an element is
     found where the comparison is true, `assoc' returns the second
     part of that element. If there is no such element in the list,
     `assoc' returns either `false' or <default>, if given.

     For example, in the expression `assoc (y, [[x,1], [y,2], [z,3]])',
     the `assoc' function searches for `x' in the left hand side of the
     list `[[y,1],[x,2]]' and finds it at the second term, returning
     `2'. In `assoc (z, [[x,1], [z,2], [z,3]])', the search stops at
     the first term starting with `z' and returns `2'. In `assoc(x,
     [[y,1]])', there is no matching element, so `assoc' returns
     `false'.

          (%i1)                 assoc(y, [[x, 1], [y, 2], [z, 3]])
          (%o1)                                  2
          (%i2)                 assoc(z, [[x, 1], [z, 2], [z, 3]])
          (%o2)                                  2
          (%i3)                         assoc(x, [[y, 1]])
          (%o3)                                false


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


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


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

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

     With a double iteration:

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

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

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

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


 -- Function: delete (<expr_1>, <expr_2>)
 -- Function: delete (<expr_1>, <expr_2>, <n>)
     `delete(<expr_1>, <expr_2>)' removes from <expr_2> any arguments
     of its top-level operator which are the same (as determined by
     "=") as <expr_1>.  Note that "=" tests for formal equality, not
     equivalence.  Note also that arguments of subexpressions are not
     affected.

     <expr_1> may be an atom or a non-atomic expression.  <expr_2> may
     be any non-atomic expression.  `delete' returns a new expression;
     it does not modify <expr_2>.

     `delete(<expr_1>, <expr_2>, <n>)' removes from <expr_2> the first
     <n> arguments of the top-level operator which are the same as
     <expr_1>.  If there are fewer than <n> such arguments, then all
     such arguments are removed.

     Examples:

     Removing elements from a list.

          (%i1) delete (y, [w, x, y, z, z, y, x, w]);
          (%o1)                  [w, x, z, z, x, w]

     Removing terms from a sum.

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

     Removing factors from a product.

          (%i1) delete (u - x, (u - w)*(u - x)*(u - y)*(u - z));
          (%o1)                (u - w) (u - y) (u - z)

     Removing arguments from an arbitrary expression.

          (%i1) delete (a, foo (a, b, c, d, a));
          (%o1)                     foo(b, c, d)

     Limit the number of removed arguments.

          (%i1) delete (a, foo (a, b, a, c, d, a), 2);
          (%o1)                    foo(b, c, d, a)

     Whether arguments are the same as <expr_1> is determined by "=".
     Arguments which are `equal' but not "=" are not removed.

          (%i1) [is (equal (0, 0)), is (equal (0, 0.0)), is (equal (0, 0b0))];
          rat: replaced 0.0 by 0/1 = 0.0
          `rat' replaced 0.0B0 by 0/1 = 0.0B0
          (%o1)                  [true, true, true]
          (%i2) [is (0 = 0), is (0 = 0.0), is (0 = 0b0)];
          (%o2)                 [true, false, false]
          (%i3) delete (0, [0, 0.0, 0b0]);
          (%o3)                     [0.0, 0.0b0]
          (%i4) is (equal ((x + y)*(x - y), x^2 - y^2));
          (%o4)                         true
          (%i5) is ((x + y)*(x - y) = x^2 - y^2);
          (%o5)                         false
          (%i6) delete ((x + y)*(x - y), [(x + y)*(x - y), x^2 - y^2]);
                                        2    2
          (%o6)                       [x  - y ]


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


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


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


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


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


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

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

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

     Examples:

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


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


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

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


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

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


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


 -- Function: makelist ()
 -- Function: makelist (<expr>, <n>)
 -- Function: makelist (<expr>, <i>, <i_max>)
 -- Function: makelist (<expr>, <i>, <i_0>, <i_max>)
 -- Function: makelist (<expr>, <i>, <i_0>, <i_max>, <step>)
 -- Function: makelist (<expr>, <x>, <list>)
     The first form, `makelist ()', creates an empty list. The second
     form, `makelist (<expr>)', creates a list with <expr> as its single
     element. `makelist (<expr>, <n>)' creates a list of <n> elements
     generated from <expr>.

     The most general form, `makelist (<expr>, <i>, <i_0>, <i_max>,
     <step>)', returns the list of elements obtained when `ev (<expr>,
     <i>=<j>)' is applied to the elements <j> of the sequence: <i_0>,
     <i_0> + <step>, <i_0> + 2*<step>, ..., with <|j|> less than or
     equal to <|i_max|>.

     The increment <step> can be a number (positive or negative) or an
     expression. If it is omitted, the default value 1 will be used. If
     both <i_0> and <step> are omitted, they will both have a default
     value of 1.

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

     Examples:

          (%i1) makelist (concat (x,i), i, 6);
          (%o1)               [x1, x2, x3, x4, x5, x6]
          (%i2) makelist (x=y, y, [a, b, c]);
          (%o2)                 [x = a, x = b, x = c]
          (%i3) makelist (x^2, x, 3, 2*%pi, 2);
          (%o3)                        [9, 25]
          (%i4) makelist (random(6), 4);
          (%o4)                     [2, 0, 2, 5]
          (%i5) flatten (makelist (makelist (i^2, 3), i, 4));
          (%o5)        [1, 1, 1, 4, 4, 4, 9, 9, 9, 16, 16, 16]
          (%i6) flatten (makelist (makelist (i^2, i, 3), 4));
          (%o6)         [1, 4, 9, 1, 4, 9, 1, 4, 9, 1, 4, 9]


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

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

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

     See also `elementp'.

     Examples:

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


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


 -- Function: pop (<list>)
     `pop' removes the first element from the list <list> and returns
     this element.  <list> must be a symbol, which is bound to a list
     and not the list itself.

     If the argument <list> is not bound to a list or the list is
     empty, Maxima generates an error message.

     See also `push' for examples.

     To use this function, the additional package "basic" must be loaded
     first: `load("basic")'.


 -- Function: push (<item>, <list>)
     `push' prepends the item <item> to the list <list> and returns a
     copy of the new list.  <list> must be a symbol, which is bound to
     a list and not the list itself.  <item> can be any Maxima symbol
     or expression.

     If the argument <list> is not bound to a list, Maxima generates an
     error message.

     See also `pop' to remove the first item from a list.

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

     Examples:

          (%i1) load ("basic")$
          (%i2) ll: [];
          (%o2)                          []
          (%i3) push (x, ll);
          (%o3)                          [x]
          (%i4) push (x^2+y, ll);
                                           2
          (%o4)                      [y + x , x]
          (%i5) a: push ("string", ll);
                                               2
          (%o5)                  [string, y + x , x]
          (%i6) pop (ll);
          (%o6)                        string
          (%i7) pop (ll);
                                            2
          (%o7)                        y + x
          (%i8) pop (ll);
          (%o8)                           x
          (%i9) ll;
          (%o9)                          []
          (%i10) a;
                                               2
          (%o10)                 [string, y + x , x]


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


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


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


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


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


 -- Function: sort (<L>, <P>)
 -- Function: sort (<L>)
     `sort(<L>, <P>)' sorts a list <L> according to a predicate `P' of
     two arguments which defines a strict weak order on the elements of
     <L>.  If `<P>(a, b)' is `true', then `a' appears before `b' in the
     result.  If neither `<P>(a, b)' nor `<P>(b, a)' are `true', then
     `a' and `b' are equivalent, and appear in the result in the same
     order as in the input.  That is, `sort' is a stable sort.

     If `<P>(a, b)' and `<P>(b, a)' are both `true' for some elements
     of <L>, then <P> is not a valid sort predicate, and the result is
     undefined.  If `<P>(a, b)' is something other than `true' or
     `false', `sort' signals an error.

     The predicate may be specified as the name of a function or binary
     infix operator, or as a `lambda' expression.  If specified as the
     name of an operator, the name must be enclosed in double quotes.

     The sorted list is returned as a new object; the argument <L> is
     not modified.

     `sort(<L>)' is equivalent to `sort(<L>, orderlessp)'.

     The default sorting order is ascending, as determined by
     `orderlessp'. The predicate `ordergreatp' sorts a list in
     descending order.

     All Maxima atoms and expressions are comparable under `orderlessp'
     and `ordergreatp'.

     Operators `<' and `>' order numbers, constants, and constant
     expressions by magnitude.  Note that `orderlessp' and
     `ordergreatp' do not order numbers, constants, and constant
     expressions by magnitude.

     `ordermagnitudep' orders numbers, constants, and constant
     expressions the same as `<', and all other elements the same as
     `orderlessp'.

     Examples:

     `sort' sorts a list according to a predicate of two arguments
     which defines a strict weak order on the elements of the list.

          (%i1) sort ([1, a, b, 2, 3, c], 'orderlessp);
          (%o1)                  [1, 2, 3, a, b, c]
          (%i2) sort ([1, a, b, 2, 3, c], 'ordergreatp);
          (%o2)                  [c, b, a, 3, 2, 1]

     The predicate may be specified as the name of a function or binary
     infix operator, or as a `lambda' expression.  If specified as the
     name of an operator, the name must be enclosed in double quotes.

          (%i1) L : [[1, x], [3, y], [4, w], [2, z]];
          (%o1)           [[1, x], [3, y], [4, w], [2, z]]
          (%i2) foo (a, b) := a[1] > b[1];
          (%o2)                 foo(a, b) := a  > b
                                              1    1
          (%i3) sort (L, 'foo);
          (%o3)           [[4, w], [3, y], [2, z], [1, x]]
          (%i4) infix (">>");
          (%o4)                          >>
          (%i5) a >> b := a[1] > b[1];
          (%o5)                   a >> b := a  > b
                                             1    1
          (%i6) sort (L, ">>");
          (%o6)           [[4, w], [3, y], [2, z], [1, x]]
          (%i7) sort (L, lambda ([a, b], a[1] > b[1]));
          (%o7)           [[4, w], [3, y], [2, z], [1, x]]

     `sort(<L>)' is equivalent to `sort(<L>, orderlessp)'.

          (%i1) L : [a, 2*b, -5, 7, 1 + %e, %pi];
          (%o1)             [a, 2 b, - 5, 7, %e + 1, %pi]
          (%i2) sort (L);
          (%o2)             [- 5, 7, %e + 1, %pi, a, 2 b]
          (%i3) sort (L, 'orderlessp);
          (%o3)             [- 5, 7, %e + 1, %pi, a, 2 b]

     The default sorting order is ascending, as determined by
     `orderlessp'. The predicate `ordergreatp' sorts a list in
     descending order.

          (%i1) L : [a, 2*b, -5, 7, 1 + %e, %pi];
          (%o1)                    [a, 2 b, - 5, 7, %e + 1, %pi]
          (%i2) sort (L);
          (%o2)                    [- 5, 7, %e + 1, %pi, a, 2 b]
          (%i3) sort (L, 'ordergreatp);
          (%o3)                    [2 b, a, %pi, %e + 1, 7, - 5]

     All Maxima atoms and expressions are comparable under `orderlessp'
     and `ordergreatp'.

          (%i1) L : [11, -17, 29b0, 9*c, 7.55, foo(x, y), -5/2, b + a];
                                                           5
          (%o1)  [11, - 17, 2.9b1, 9 c, 7.55, foo(x, y), - -, b + a]
                                                           2
          (%i2) sort (L, orderlessp);
                          5
          (%o2)  [- 17, - -, 7.55, 11, 2.9b1, b + a, 9 c, foo(x, y)]
                          2
          (%i3) sort (L, ordergreatp);
                                                            5
          (%o3)  [foo(x, y), 9 c, b + a, 2.9b1, 11, 7.55, - -, - 17]
                                                            2

     Operators `<' and `>' order numbers, constants, and constant
     expressions by magnitude.  Note that `orderlessp' and
     `ordergreatp' do not order numbers, constants, and constant
     expressions by magnitude.

          (%i1) L : [%pi, 3, 4, %e, %gamma];
          (%o1)                [%pi, 3, 4, %e, %gamma]
          (%i2) sort (L, ">");
          (%o2)                [4, %pi, 3, %e, %gamma]
          (%i3) sort (L, ordergreatp);
          (%o3)                [%pi, %gamma, %e, 4, 3]

     `ordermagnitudep' orders numbers, constants, and constant
     expressions the same as `<', and all other elements the same as
     `orderlessp'.

          (%i1) L : [%i, 1+%i, 2*x, minf, inf, %e, sin(1), 0, 1, 2, 3, 1.0, 1.0b0];
          (%o1) [%i, %i + 1, 2 x, minf, inf, %e, sin(1), 0, 1, 2, 3, 1.0,
                                                                     1.0b0]
          (%i2) sort (L, ordermagnitudep);
          (%o2) [minf, 0, sin(1), 1, 1.0, 1.0b0, 2, %e, 3, inf, %i,
                                                               %i + 1, 2 x]
          (%i3) sort (L, orderlessp);
          (%o3) [0, 1, 1.0, 2, 3, %e, %i, %i + 1, inf, minf, sin(1),
                                                                1.0b0, 2 x]


 -- Function: sublist (<list>, <p>)
     Returns the list of elements of <list> for which the predicate `p'
     returns `true'.

     Example:

          (%i1) L: [1, 2, 3, 4, 5, 6];
          (%o1)                  [1, 2, 3, 4, 5, 6]
          (%i2) sublist (L, evenp);
          (%o2)                       [2, 4, 6]


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

     Examples:

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


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

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

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

     Example:

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

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


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



File: maxima.info,  Node: Arrays,  Next: Structures,  Prev: Lists,  Up: Data Types and Structures

5.5 Arrays
==========

* Menu:

* Functions and Variables for Arrays::


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

5.5.1 Functions and Variables for Arrays
----------------------------------------

 -- Function: array (<name>, <dim_1>, ..., <dim_n>)
 -- Function: array (<name>, <type>, <dim_1>, ..., <dim_n>)
 -- Function: array ([<name_1>, ..., <name_m>], <dim_1>, ..., <dim_n>)
     Creates an n-dimensional array.  n may be less than or equal to 5.
     The subscripts for the i'th dimension are the integers running
     from 0 to <dim_i>.

     `array (<name>, <dim_1>, ..., <dim_n>)' creates a general array.

     `array (<name>, <type>, <dim_1>, ..., <dim_n>)' creates an array,
     with elements of a specified type.  <type> can be `fixnum' for
     integers of limited size or `flonum' for floating-point numbers.

     `array ([<name_1>, ..., <name_m>], <dim_1>, ..., <dim_n>)' creates
     m arrays, all of the same dimensions.

     If the user assigns to a subscripted variable before declaring the
     corresponding array, an undeclared array is created.  Undeclared
     arrays, otherwise known as hashed arrays (because hash coding is
     done on the subscripts), are more general than declared arrays.
     The user does not declare their maximum size, and they grow
     dynamically by hashing as more elements are assigned values.  The
     subscripts of undeclared arrays need not even be numbers.  However,
     unless an array is rather sparse, it is probably more efficient to
     declare it when possible than to leave it undeclared.  The `array'
     function can be used to transform an undeclared array into a
     declared array.


 -- Function: arrayapply (<A>, [<i_1>, ..., <i_n>])
     Evaluates `<A> [<i_1>, ..., <i_n>]', where <A> is an array and
     <i_1>, ..., <i_n> are integers.

     This is reminiscent of `apply', except the first argument is an
     array instead of a function.


 -- Function: arrayinfo (<A>)
     Returns information about the array <A>.  The argument <A> may be
     a declared array, an undeclared (hashed) array, an array function,
     or a subscripted function.

     For declared arrays, `arrayinfo' returns a list comprising the atom
     `declared', the number of dimensions, and the size of each
     dimension.  The elements of the array, both bound and unbound, are
     returned by `listarray'.

     For undeclared arrays (hashed arrays), `arrayinfo' returns a list
     comprising the atom `hashed', the number of subscripts, and the
     subscripts of every element which has a value.  The values are
     returned by `listarray'.

     For array functions, `arrayinfo' returns a list comprising the atom
     `hashed', the number of subscripts, and any subscript values for
     which there are stored function values.  The stored function
     values are returned by `listarray'.

     For subscripted functions, `arrayinfo' returns a list comprising
     the atom `hashed', the number of subscripts, and any subscript
     values for which there are lambda expressions.  The lambda
     expressions are returned by `listarray'.

     See also `listarray'.

     Examples:

     `arrayinfo' and `listarray' applied to a declared array.

          (%i1) array (aa, 2, 3);
          (%o1)                          aa
          (%i2) aa [2, 3] : %pi;
          (%o2)                          %pi
          (%i3) aa [1, 2] : %e;
          (%o3)                          %e
          (%i4) arrayinfo (aa);
          (%o4)                 [declared, 2, [2, 3]]
          (%i5) listarray (aa);
          (%o5) [#####, #####, #####, #####, #####, #####, %e, #####,
                                                  #####, #####, #####, %pi]

     `arrayinfo' and `listarray' applied to an undeclared (hashed)
     array.

          (%i1) bb [FOO] : (a + b)^2;
                                             2
          (%o1)                       (b + a)
          (%i2) bb [BAR] : (c - d)^3;
                                             3
          (%o2)                       (c - d)
          (%i3) arrayinfo (bb);
          (%o3)               [hashed, 1, [BAR], [FOO]]
          (%i4) listarray (bb);
                                        3         2
          (%o4)                 [(c - d) , (b + a) ]

     `arrayinfo' and `listarray' applied to an array function.

          (%i1) cc [x, y] := y / x;
                                               y
          (%o1)                      cc     := -
                                       x, y    x
          (%i2) cc [u, v];
                                          v
          (%o2)                           -
                                          u
          (%i3) cc [4, z];
                                          z
          (%o3)                           -
                                          4
          (%i4) arrayinfo (cc);
          (%o4)              [hashed, 2, [4, z], [u, v]]
          (%i5) listarray (cc);
                                        z  v
          (%o5)                        [-, -]
                                        4  u

     `arrayinfo' and `listarray' applied to a subscripted function.

          (%i1) dd [x] (y) := y ^ x;
                                               x
          (%o1)                     dd (y) := y
                                      x
          (%i2) dd [a + b];
                                              b + a
          (%o2)                  lambda([y], y     )
          (%i3) dd [v - u];
                                              v - u
          (%o3)                  lambda([y], y     )
          (%i4) arrayinfo (dd);
          (%o4)             [hashed, 1, [b + a], [v - u]]
          (%i5) listarray (dd);
                                   b + a                v - u
          (%o5)      [lambda([y], y     ), lambda([y], y     )]


 -- Function: arraymake (<A>, [<i_1>, ..., <i_n>])
     Returns the expression `<A>[<i_1>, ..., <i_n>]'.  The result is an
     unevaluated array reference.

     `arraymake' is reminiscent of `funmake', except the return value
     is an unevaluated array reference instead of an unevaluated
     function call.

     Examples:
          (%i1) arraymake (A, [1]);
          (%o1)                          A
                                          1
          (%i2) arraymake (A, [k]);
          (%o2)                          A
                                          k
          (%i3) arraymake (A, [i, j, 3]);
          (%o3)                       A
                                       i, j, 3
          (%i4) array (A, fixnum, 10);
          (%o4)                           A
          (%i5) fillarray (A, makelist (i^2, i, 1, 11));
          (%o5)                           A
          (%i6) arraymake (A, [5]);
          (%o6)                          A
                                          5
          (%i7) ''%;
          (%o7)                          36
          (%i8) L : [a, b, c, d, e];
          (%o8)                    [a, b, c, d, e]
          (%i9) arraymake ('L, [n]);
          (%o9)                          L
                                          n
          (%i10) ''%, n = 3;
          (%o10)                          c
          (%i11) A2 : make_array (fixnum, 10);
          (%o11)          {Array:  #(0 0 0 0 0 0 0 0 0 0)}
          (%i12) fillarray (A2, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
          (%o12)          {Array:  #(1 2 3 4 5 6 7 8 9 10)}
          (%i13) arraymake ('A2, [8]);
          (%o13)                         A2
                                           8
          (%i14) ''%;
          (%o14)                          9


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

     `arrays' is a list of arrays that have been allocated.  These
     comprise arrays declared by `array', hashed arrays constructed by
     implicit definition (assigning something to an array element), and
     array functions defined by `:=' and `define'.  Arrays defined by
     `make_array' are not included.

     See also `array', `arrayapply', `arrayinfo', `arraymake',
     `fillarray', `listarray', and `rearray'.

     Examples:

          (%i1) array (aa, 5, 7);
          (%o1)                          aa
          (%i2) bb [FOO] : (a + b)^2;
                                             2
          (%o2)                       (b + a)
          (%i3) cc [x] := x/100;
                                             x
          (%o3)                      cc  := ---
                                       x    100
          (%i4) dd : make_array ('any, 7);
          (%o4)       {Array:  #(NIL NIL NIL NIL NIL NIL NIL)}
          (%i5) arrays;
          (%o5)                     [aa, bb, cc]


 -- Function: arraysetapply (<A>, [<i_1>, ..., <i_n>], <x>)
     Assigns <x> to `<A>[<i_1>, ..., <i_n>]', where <A> is an array and
     <i_1>, ..., <i_n> are integers.

     `arraysetapply' evaluates its arguments.


 -- Function: fillarray (<A>, <B>)
     Fills array <A> from <B>, which is a list or an array.

     If a specific type was declared for <A> when it was created, it
     can only be filled with elements of that same type; it is an error
     if an attempt is made to copy an element of a different type.

     If the dimensions of the arrays <A> and <B> are different, <A> is
     filled in row-major order.  If there are not enough elements in
     <B> the last element is used to fill out the rest of <A>.  If
     there are too many, the remaining ones are ignored.

     `fillarray' returns its first argument.

     Examples:

     Create an array of 9 elements and fill it from a list.
          (%i1) array (a1, fixnum, 8);
          (%o1)                          a1
          (%i2) listarray (a1);
          (%o2)              [0, 0, 0, 0, 0, 0, 0, 0, 0]
          (%i3) fillarray (a1, [1, 2, 3, 4, 5, 6, 7, 8, 9]);
          (%o3)                          a1
          (%i4) listarray (a1);
          (%o4)              [1, 2, 3, 4, 5, 6, 7, 8, 9]

     When there are too few elements to fill the array, the last
     element is repeated.  When there are too many elements, the extra
     elements are ignored.
          (%i1) a2 : make_array (fixnum, 8);
          (%o1)             {Array:  #(0 0 0 0 0 0 0 0)}
          (%i2) fillarray (a2, [1, 2, 3, 4, 5]);
          (%o2)             {Array:  #(1 2 3 4 5 5 5 5)}
          (%i3) fillarray (a2, [4]);
          (%o3)             {Array:  #(4 4 4 4 4 4 4 4)}
          (%i4) fillarray (a2, makelist (i, i, 1, 100));
          (%o4)             {Array:  #(1 2 3 4 5 6 7 8)}

     Multple-dimension arrays are filled in row-major order.

          (%i1) a3 : make_array (fixnum, 2, 5);
          (%o1)        {Array:  #2A((0 0 0 0 0) (0 0 0 0 0))}
          (%i2) fillarray (a3, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
          (%o2)        {Array:  #2A((1 2 3 4 5) (6 7 8 9 10))}
          (%i3) a4 : make_array (fixnum, 5, 2);
          (%o3)     {Array:  #2A((0 0) (0 0) (0 0) (0 0) (0 0))}
          (%i4) fillarray (a4, a3);
          (%o4)     {Array:  #2A((1 2) (3 4) (5 6) (7 8) (9 10))}


 -- Function: listarray (<A>)
     Returns a list of the elements of the array <A>.  The argument <A>
     may be a declared array, an undeclared (hashed) array, an array
     function, or a subscripted function.

     Elements are listed in row-major order.  That is, elements are
     sorted according to the first index, then according to the second
     index, and so on.  The sorting order of index values is the same as
     the order established by `orderless'.

     For undeclared arrays, array functions, and subscripted functions,
     the elements correspond to the index values returned by
     `arrayinfo'.

     Unbound elements of declared general arrays (that is, not `fixnum'
     and not `flonum') are returned as `#####'.  Unbound elements of
     declared `fixnum' or `flonum' arrays are returned as 0 or 0.0,
     respectively.  Unbound elements of undeclared arrays, array
     functions, and subscripted functions are not returned.

     Examples:

     `listarray' and `arrayinfo' applied to a declared array.

          (%i1) array (aa, 2, 3);
          (%o1)                          aa
          (%i2) aa [2, 3] : %pi;
          (%o2)                          %pi
          (%i3) aa [1, 2] : %e;
          (%o3)                          %e
          (%i4) listarray (aa);
          (%o4) [#####, #####, #####, #####, #####, #####, %e, #####,
                                                  #####, #####, #####, %pi]
          (%i5) arrayinfo (aa);
          (%o5)                 [declared, 2, [2, 3]]

     `listarray' and `arrayinfo' applied to an undeclared (hashed)
     array.

          (%i1) bb [FOO] : (a + b)^2;
                                             2
          (%o1)                       (b + a)
          (%i2) bb [BAR] : (c - d)^3;
                                             3
          (%o2)                       (c - d)
          (%i3) listarray (bb);
                                        3         2
          (%o3)                 [(c - d) , (b + a) ]
          (%i4) arrayinfo (bb);
          (%o4)               [hashed, 1, [BAR], [FOO]]

     `listarray' and `arrayinfo' applied to an array function.

          (%i1) cc [x, y] := y / x;
                                               y
          (%o1)                      cc     := -
                                       x, y    x
          (%i2) cc [u, v];
                                          v
          (%o2)                           -
                                          u
          (%i3) cc [4, z];
                                          z
          (%o3)                           -
                                          4
          (%i4) listarray (cc);
                                        z  v
          (%o4)                        [-, -]
                                        4  u
          (%i5) arrayinfo (cc);
          (%o5)              [hashed, 2, [4, z], [u, v]]

     `listarray' and `arrayinfo' applied to a subscripted function.

          (%i1) dd [x] (y) := y ^ x;
                                               x
          (%o1)                     dd (y) := y
                                      x
          (%i2) dd [a + b];
                                              b + a
          (%o2)                  lambda([y], y     )
          (%i3) dd [v - u];
                                              v - u
          (%o3)                  lambda([y], y     )
          (%i4) listarray (dd);
                                   b + a                v - u
          (%o4)      [lambda([y], y     ), lambda([y], y     )]
          (%i5) arrayinfo (dd);
          (%o5)             [hashed, 1, [b + a], [v - u]]


 -- Function: make_array (<type>, <dim_1>, ..., <dim_n>)
     Creates and returns a Lisp array.  <type> may be `any', `flonum',
     `fixnum', `hashed' or `functional'.  There are n indices, and the
     i'th index runs from 0 to <dim_i> - 1.

     The advantage of `make_array' over `array' is that the return value
     doesn't have a name, and once a pointer to it goes away, it will
     also go away.  For example, if `y: make_array (...)' then `y'
     points to an object which takes up space, but after `y: false',
     `y' no longer points to that object, so the object can be garbage
     collected.

     Examples:

          (%i1) A1 : make_array (fixnum, 10);
          (%o1)           {Array:  #(0 0 0 0 0 0 0 0 0 0)}
          (%i2) A1 [8] : 1729;
          (%o2)                         1729
          (%i3) A1;
          (%o3)          {Array:  #(0 0 0 0 0 0 0 0 1729 0)}
          (%i4) A2 : make_array (flonum, 10);
          (%o4) {Array:  #(0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0)}
          (%i5) A2 [2] : 2.718281828;
          (%o5)                      2.718281828
          (%i6) A2;
          (%o6)
               {Array:  #(0.0 0.0 2.718281828 0.0 0.0 0.0 0.0 0.0 0.0 0.0)}
          (%i7) A3 : make_array (any, 10);
          (%o7) {Array:  #(NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)}
          (%i8) A3 [4] : x - y - z;
          (%o8)                      - z - y + x
          (%i9) A3;
          (%o9) {Array:  #(NIL NIL NIL NIL ((MPLUS SIMP) $X ((MTIMES SIMP)\
           -1 $Y) ((MTIMES SIMP) -1 $Z))
            NIL NIL NIL NIL NIL)}
          (%i10) A4 : make_array (fixnum, 2, 3, 5);
          (%o10) {Array:  #3A(((0 0 0 0 0) (0 0 0 0 0) (0 0 0 0 0)) ((0 0 \
          0 0 0) (0 0 0 0 0) (0 0 0 0 0)))}
          (%i11) fillarray (A4, makelist (i, i, 1, 2*3*5));
          (%o11) {Array:  #3A(((1 2 3 4 5) (6 7 8 9 10) (11 12 13 14 15))
              ((16 17 18 19 20) (21 22 23 24 25) (26 27 28 29 30)))}
          (%i12) A4 [0, 2, 1];
          (%o12)                         12


 -- Function: rearray (<A>, <dim_1>, ..., <dim_n>)
     Changes the dimensions of an array.  The new array will be filled
     with the elements of the old one in row-major order.  If the old
     array was too small, the remaining elements are filled with
     `false', `0.0' or `0', depending on the type of the array.  The
     type of the array cannot be changed.


 -- Function: remarray (<A_1>, ..., <A_n>)
 -- Function: remarray (all)
     Removes arrays and array associated functions and frees the
     storage occupied.  The arguments may be declared arrays,
     undeclared (hashed) arrays, array functions, and subscripted
     functions.

     `remarray (all)' removes all items in the global list `arrays'.

     It may be necessary to use this function if it is desired to
     redefine the values in a hashed array.

     `remarray' returns the list of arrays removed.

     `remarray' quotes its arguments.


 -- Function: subvar (<x>, <i>)
     Evaluates the subscripted expression `<x>[<i>]'.

     `subvar' evaluates its arguments.

     `arraymake (<x>, [<i>])' constructs the expression `<x>[<i>]', but
     does not evaluate it.

     Examples:

          (%i1) x : foo $
          (%i2) i : 3 $
          (%i3) subvar (x, i);
          (%o3)                         foo
                                           3
          (%i4) foo : [aa, bb, cc, dd, ee]$
          (%i5) subvar (x, i);
          (%o5)                          cc
          (%i6) arraymake (x, [i]);
          (%o6)                         foo
                                           3
          (%i7) ''%;
          (%o7)                          cc


 -- Function: subvarp (<expr>)
     Returns `true' if <expr> is a subscripted variable, for example
     `a[i]'.


 -- Option variable: use_fast_arrays
     If `true' then only two types of arrays are recognized:

       1. The art-q array (t in Common Lisp) which may have several
          dimensions indexed by integers, and may hold any Lisp or
          Maxima object as an entry.  To construct such an array, enter
          `a:make_array(any,3,4);' then `a' will have as value, an
          array with twelve slots, and the indexing is zero based.

       2. The Hash_table array which is the default type of array
          created if one does `b[x+1]:y^2' (and `b' is not already an
          array, a list, or a matrix - if it were one of these an error
          would be caused since `x+1' would not be a valid subscript
          for an art-q array, a list or a matrix).  Its indices (also
          known as keys) may be any object.  It only takes one key at a
          time (`b[x+1,u]:y' would ignore the `u').  Referencing is
          done by `b[x+1] ==> y^2'.  Of course the key may be a list,
          e.g. `b[[x+1,u]]:y' would be valid.  This is incompatible
          with the old Maxima hash arrays, but saves consing.

     An advantage of storing the arrays as values of the symbol is that
     the usual conventions about local variables of a function apply to
     arrays as well.  The Hash_table type also uses less consing and is
     more efficient than the old type of Maxima hashar.  To obtain
     consistent behaviour in translated and compiled code set
     `translate_fast_arrays' to be `true'.



File: maxima.info,  Node: Structures,  Prev: Arrays,  Up: Data Types and Structures

5.6 Structures
==============

* Menu:

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


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

5.6.1 Introduction to Structures
--------------------------------

Maxima provides a simple data aggregate called a structure.  A
structure is an expression in which arguments are identified by name
(the field name) and the expression as a whole is identified by its
operator (the structure name).  A field value can be any expression.

   A structure is defined by the `defstruct' function; the global
variable `structures' is the list of user-defined structures.  The
function `new' creates instances of structures.  The `@' operator
refers to fields.  `kill(<S>)' removes the structure definition <S>,
and `kill(<x>@ <a>)' unbinds the field <a> of the structure instance
<x>.

   In the pretty-printing console display (with `display2d' equal to
`true'), structure instances are displayed with the value of each field
represented as an equation, with the field name on the left-hand side
and the value on the right-hand side.  (The equation is only a display
construct; only the value is actually stored.)  In 1-dimensional
display (via `grind' or with `display2d' equal to `false'), structure
instances are displayed without the field names.

   There is no way to use a field name as a function name, although a
field value can be a lambda expression.  Nor can the values of fields
be restricted to certain types; any field can be assigned any kind of
expression.  There is no way to make some fields accessible or
inaccessible in different contexts; all fields are always visible.


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

5.6.2 Functions and Variables for Structures
--------------------------------------------

 -- Global variable: structures
     `structures' is the list of user-defined structures defined by
     `defstruct'.


 -- Function: defstruct (<S>(<a_1>, ..., <a_n>))
 -- Function: defstruct (<S>(<a_1> = <v_1>, ..., <a_n> = <v_n>))
     Define a structure, which is a list of named fields <a_1>, ...,
     <a_n> associated with a symbol <S>.  An instance of a structure is
     just an expression which has operator <S> and exactly `n'
     arguments.  `new(<S>)' creates a new instance of structure <S>.

     An argument which is just a symbol <a> specifies the name of a
     field.  An argument which is an equation `<a> = <v>' specifies the
     field name <a> and its default value <v>.  The default value can
     be any expression.

     `defstruct' puts <S> on the list of user-defined structures,
     `structures'.

     `kill(<S>)' removes <S> from the list of user-defined structures,
     and removes the structure definition.

     Examples:

          (%i1) defstruct (foo (a, b, c));
          (%o1)                    [foo(a, b, c)]
          (%i2) structures;
          (%o2)                    [foo(a, b, c)]
          (%i3) new (foo);
          (%o3)                     foo(a, b, c)
          (%i4) defstruct (bar (v, w, x = 123, y = %pi));
          (%o4)             [bar(v, w, x = 123, y = %pi)]
          (%i5) structures;
          (%o5)      [foo(a, b, c), bar(v, w, x = 123, y = %pi)]
          (%i6) new (bar);
          (%o6)              bar(v, w, x = 123, y = %pi)
          (%i7) kill (foo);
          (%o7)                         done
          (%i8) structures;
          (%o8)             [bar(v, w, x = 123, y = %pi)]


 -- Function: new (<S>)
 -- Function: new (<S> (<v_1>, ..., <v_n>))
     `new' creates new instances of structures.

     `new(<S>)' creates a new instance of structure <S> in which each
     field is assigned its default value, if any, or no value at all if
     no default was specified in the structure definition.

     `new(<S>(<v_1>, ..., <v_n>))' creates a new instance of <S> in
     which fields are assigned the values <v_1>, ..., <v_n>.

     Examples:

          (%i1) defstruct (foo (w, x = %e, y = 42, z));
          (%o1)              [foo(w, x = %e, y = 42, z)]
          (%i2) new (foo);
          (%o2)               foo(w, x = %e, y = 42, z)
          (%i3) new (foo (1, 2, 4, 8));
          (%o3)            foo(w = 1, x = 2, y = 4, z = 8)


 -- Operator: @
     `@' is the structure field access operator.  The expression `<x>@
     <a>' refers to the value of field <a> of the structure instance
     <x>.  The field name is not evaluated.

     If the field <a> in <x> has not been assigned a value, `<x>@ <a>'
     evaluates to itself.

     `kill(<x>@ <a>)' removes the value of field <a> in <x>.

     Examples:

          (%i1) defstruct (foo (x, y, z));
          (%o1)                    [foo(x, y, z)]
          (%i2) u : new (foo (123, a - b, %pi));
          (%o2)           foo(x = 123, y = a - b, z = %pi)
          (%i3) u@z;
          (%o3)                          %pi
          (%i4) u@z : %e;
          (%o4)                          %e
          (%i5) u;
          (%o5)            foo(x = 123, y = a - b, z = %e)
          (%i6) kill (u@z);
          (%o6)                         done
          (%i7) u;
          (%o7)              foo(x = 123, y = a - b, z)
          (%i8) u@z;
          (%o8)                          u@z

     The field name is not evaluated.

          (%i1) defstruct (bar (g, h));
          (%o1)                      [bar(g, h)]
          (%i2) x : new (bar);
          (%o2)                       bar(g, h)
          (%i3) x@h : 42;
          (%o3)                          42
          (%i4) h : 123;
          (%o4)                          123
          (%i5) x@h;
          (%o5)                          42
          (%i6) x@h : 19;
          (%o6)                          19
          (%i7) x;
          (%o7)                    bar(g, h = 19)
          (%i8) h;
          (%o8)                          123



File: maxima.info,  Node: Expressions,  Next: Operators,  Prev: Data Types and Structures,  Up: Top

6 Expressions
*************

* Menu:

* Introduction to Expressions::
* Nouns and Verbs::
* Identifiers::
* Inequality::
* Functions and Variables for Expressions::


File: maxima.info,  Node: Introduction to Expressions,  Next: Nouns and Verbs,  Prev: Expressions,  Up: Expressions

6.1 Introduction to Expressions
===============================

There are a number of reserved words which should not be used as
variable names.  Their use would cause a possibly cryptic syntax error.

     integrate            next           from                 diff
     in                   at             limit                sum
     for                  and            elseif               then
     else                 do             or                   if
     unless               product        while                thru
     step

   Most things in Maxima are expressions.  A sequence of expressions
can be made into an expression by separating them by commas and putting
parentheses around them.  This is similar to the C comma expression.

     (%i1) x: 3$
     (%i2) (x: x+1, x: x^2);
     (%o2)                          16
     (%i3) (if (x > 17) then 2 else 4);
     (%o3)                           4
     (%i4) (if (x > 17) then x: 2 else y: 4, y+x);
     (%o4)                          20

   Even loops in Maxima are expressions, although the value they return
is the not too useful `done'.

     (%i1) y: (x: 1, for i from 1 thru 10 do (x: x*i))$
     (%i2) y;
     (%o2)                         done

   Whereas what you really want is probably to include a third term in
the comma expression which actually gives back the value.

     (%i3) y: (x: 1, for i from 1 thru 10 do (x: x*i), x)$
     (%i4) y;
     (%o4)                        3628800


File: maxima.info,  Node: Nouns and Verbs,  Next: Identifiers,  Prev: Introduction to Expressions,  Up: Expressions

6.2 Nouns and Verbs
===================

Maxima distinguishes between operators which are "nouns" and operators
which are "verbs".  A verb is an operator which can be executed.  A
noun is an operator which appears as a symbol in an expression, without
being executed.  By default, function names are verbs.  A verb can be
changed into a noun by quoting the function name or applying the
`nounify' function.  A noun can be changed into a verb by applying the
`verbify' function.  The evaluation flag `nouns' causes `ev' to
evaluate nouns in an expression.

   The verb form is distinguished by a leading dollar sign `$' on the
corresponding Lisp symbol.  In contrast, the noun form is distinguished
by a leading percent sign `%' on the corresponding Lisp symbol.  Some
nouns have special display properties, such as `'integrate' and
`'derivative' (returned by `diff'), but most do not.  By default, the
noun and verb forms of a function are identical when displayed.  The
global flag `noundisp' causes Maxima to display nouns with a leading
quote mark `''.

   See also `noun', `nouns', `nounify', and `verbify'.

   Examples:

     (%i1) foo (x) := x^2;
                                          2
     (%o1)                     foo(x) := x
     (%i2) foo (42);
     (%o2)                         1764
     (%i3) 'foo (42);
     (%o3)                        foo(42)
     (%i4) 'foo (42), nouns;
     (%o4)                         1764
     (%i5) declare (bar, noun);
     (%o5)                         done
     (%i6) bar (x) := x/17;
                                          x
     (%o6)                    ''bar(x) := --
                                          17
     (%i7) bar (52);
     (%o7)                        bar(52)
     (%i8) bar (52), nouns;
                                    52
     (%o8)                          --
                                    17
     (%i9) integrate (1/x, x, 1, 42);
     (%o9)                        log(42)
     (%i10) 'integrate (1/x, x, 1, 42);
                                  42
                                 /
                                 [   1
     (%o10)                      I   - dx
                                 ]   x
                                 /
                                  1
     (%i11) ev (%, nouns);
     (%o11)                       log(42)


File: maxima.info,  Node: Identifiers,  Next: Inequality,  Prev: Nouns and Verbs,  Up: Expressions

6.3 Identifiers
===============

Maxima identifiers may comprise alphabetic characters, plus the
numerals 0 through 9, plus any special character preceded by the
backslash `\' character.

   A numeral may be the first character of an identifier if it is
preceded by a backslash.  Numerals which are the second or later
characters need not be preceded by a backslash.

   Characters may be declared alphabetic by the `declare' function.  If
so declared, they need not be preceded by a backslash in an identifier.
The alphabetic characters are initially `A' through `Z', `a' through
`z', `%', and `_'.

   Maxima is case-sensitive.  The identifiers `foo', `FOO', and `Foo'
are distinct.  See *note Lisp and Maxima:: for more on this point.

   A Maxima identifier is a Lisp symbol which begins with a dollar sign
`$'.  Any other Lisp symbol is preceded by a question mark `?' when it
appears in Maxima.  See *note Lisp and Maxima:: for more on this point.

   Examples:

     (%i1) %an_ordinary_identifier42;
     (%o1)               %an_ordinary_identifier42
     (%i2) embedded\ spaces\ in\ an\ identifier;
     (%o2)           embedded spaces in an identifier
     (%i3) symbolp (%);
     (%o3)                         true
     (%i4) [foo+bar, foo\+bar];
     (%o4)                 [foo + bar, foo+bar]
     (%i5) [1729, \1729];
     (%o5)                     [1729, 1729]
     (%i6) [symbolp (foo\+bar), symbolp (\1729)];
     (%o6)                     [true, true]
     (%i7) [is (foo\+bar = foo+bar), is (\1729 = 1729)];
     (%o7)                    [false, false]
     (%i8) baz\~quux;
     (%o8)                       baz~quux
     (%i9) declare ("~", alphabetic);
     (%o9)                         done
     (%i10) baz~quux;
     (%o10)                      baz~quux
     (%i11) [is (foo = FOO), is (FOO = Foo), is (Foo = foo)];
     (%o11)                [false, false, false]
     (%i12) :lisp (defvar *my-lisp-variable* '$foo)
     *MY-LISP-VARIABLE*
     (%i12) ?\*my\-lisp\-variable\*;
     (%o12)                         foo


File: maxima.info,  Node: Inequality,  Next: Functions and Variables for Expressions,  Prev: Identifiers,  Up: Expressions

6.4 Inequality
==============

Maxima has the inequality operators `<', `<=', `>=', `>', `#', and
`notequal'.  See `if' for a description of conditional expressions.


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

6.5 Functions and Variables for Expressions
===========================================

 -- Function: alias (<new_name_1>, <old_name_1>, ..., <new_name_n>,
          <old_name_n>)
     provides an alternate name for a (user or system) function,
     variable, array, etc.  Any even number of arguments may be used.


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

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


 -- Keyword: allbut
     works with the `part' commands (i.e.  `part', `inpart',
     `substpart', `substinpart', `dpart', and `lpart').  For example,

          (%i1) expr : e + d + c + b + a;
          (%o1)                   e + d + c + b + a
          (%i2) part (expr, [2, 5]);
          (%o2)                         d + a

     while

          (%i1) expr : e + d + c + b + a;
          (%o1)                   e + d + c + b + a
          (%i2) part (expr, allbut (2, 5));
          (%o2)                       e + c + b

     `allbut' is also recognized by `kill'.

          (%i1) [aa : 11, bb : 22, cc : 33, dd : 44, ee : 55];
          (%o1)                 [11, 22, 33, 44, 55]
          (%i2) kill (allbut (cc, dd));
          (%o0)                         done
          (%i1) [aa, bb, cc, dd];
          (%o1)                   [aa, bb, 33, 44]

     `kill(allbut(<a_1>, <a_2>, ...))' has the effect of `kill(all)'
     except that it does not kill the symbols <a_1>, <a_2>, ...

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

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

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


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


 -- Function: box (<expr>)
 -- Function: box (<expr>, <a>)
     Returns <expr> enclosed in a box.  The return value is an
     expression with `box' as the operator and <expr> as the argument.
     A box is drawn on the display when `display2d' is `true'.

     `box (<expr>, <a>)' encloses <expr> in a box labelled by the
     symbol <a>.  The label is truncated if it is longer than the width
     of the box.

     `box' evaluates its argument.  However, a boxed expression does not
     evaluate to its content, so boxed expressions are effectively
     excluded from computations.

     `boxchar' is the character used to draw the box in `box' and in the
     `dpart' and `lpart' functions.

     Examples:

          (%i1) box (a^2 + b^2);
                                      """""""""
                                      " 2    2"
          (%o1)                       "b  + a "
                                      """""""""
          (%i2) a : 1234;
          (%o2)                         1234
          (%i3) b : c - d;
          (%o3)                         c - d
          (%i4) box (a^2 + b^2);
                                """"""""""""""""""""
                                "       2          "
          (%o4)                 "(c - d)  + 1522756"
                                """"""""""""""""""""
          (%i5) box (a^2 + b^2, term_1);
                                term_1""""""""""""""
                                "       2          "
          (%o5)                 "(c - d)  + 1522756"
                                """"""""""""""""""""
          (%i6) 1729 - box (1729);
                                           """"""
          (%o6)                     1729 - "1729"
                                           """"""
          (%i7) boxchar: "-";
          (%o7)                           -
          (%i8) box (sin(x) + cos(y));
                                  -----------------
          (%o8)                   -cos(y) + sin(x)-
                                  -----------------


 -- Option variable: boxchar
     Default value: `"'

     `boxchar' is the character used to draw the box in the `box' and
     in the `dpart' and `lpart' functions.

     All boxes in an expression are drawn with the current value of
     `boxchar'; the drawing character is not stored with the box
     expression.


 -- Function: collapse (<expr>)
     Collapses <expr> by causing all of its common (i.e., equal)
     subexpressions to share (i.e., use the same cells), thereby saving
     space.  (`collapse' is a subroutine used by the `optimize'
     command.)  Thus, calling `collapse' may be useful after loading in
     a `save' file.  You can collapse several expressions together by
     using `collapse ([<expr_1>, ..., <expr_n>])'.  Similarly, you can
     collapse the elements of the array `A' by doing `collapse
     (listarray ('A))'.


 -- Function: disolate (<expr>, <x_1>, ..., <x_n>)
     is similar to `isolate (<expr>, <x>)' except that it enables the
     user to isolate more than one variable simultaneously.  This might
     be useful, for example, if one were attempting to change variables
     in a multiple integration, and that variable change involved two
     or more of the integration variables.  This function is autoloaded
     from `simplification/disol.mac'.  A demo is available by
     `demo("disol")$'.


 -- Function: dispform (<expr>)
 -- Function: dispform (<expr>, all)
     Returns the external representation of <expr>.

     `dispform(<expr>)' returns the external representation with
     respect to the main (top-level) operator.  `dispform(<expr>, all)'
     returns the external representation with respect to all operators
     in <expr>.

     See also `part', `inpart', and `inflag'.

     Examples:

     The internal representation of `- x' is "negative one times `x'"
     while the external representation is "minus `x'".

          (%i1) - x;
          (%o1)                          - x
          (%i2) ?format (true, "~S~%", %);
          ((MTIMES SIMP) -1 $X)
          (%o2)                         false
          (%i3) dispform (- x);
          (%o3)                          - x
          (%i4) ?format (true, "~S~%", %);
          ((MMINUS SIMP) $X)
          (%o4)                         false

     The internal representation of `sqrt(x)' is "`x' to the power 1/2"
     while the external representation is "square root of `x'".

          (%i1) sqrt (x);
          (%o1)                        sqrt(x)
          (%i2) ?format (true, "~S~%", %);
          ((MEXPT SIMP) $X ((RAT SIMP) 1 2))
          (%o2)                         false
          (%i3) dispform (sqrt (x));
          (%o3)                        sqrt(x)
          (%i4) ?format (true, "~S~%", %);
          ((%SQRT SIMP) $X)
          (%o4)                         false

     Use of the optional argument `all'.

          (%i1) expr : sin (sqrt (x));
          (%o1)                     sin(sqrt(x))
          (%i2) freeof (sqrt, expr);
          (%o2)                         true
          (%i3) freeof (sqrt, dispform (expr));
          (%o3)                         true
          (%i4) freeof (sqrt, dispform (expr, all));
          (%o4)                         false


 -- Function: dpart (<expr>, <n_1>, ..., <n_k>)
     Selects the same subexpression as `part', but instead of just
     returning that subexpression as its value, it returns the whole
     expression with the selected subexpression displayed inside a box.
     The box is actually part of the expression.

          (%i1) dpart (x+y/z^2, 1, 2, 1);
                                       y
          (%o1)                       ---- + x
                                         2
                                      """
                                      "z"
                                      """


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

     `exptisolate', when `true', causes `isolate (expr, var)' to
     examine exponents of atoms (such as `%e') which contain `var'.


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

     `exptsubst', when `true', permits substitutions such as `y' for
     `%e^x' in `%e^(a x)'.

          (%i1) %e^(a*x);
                                                 a x
          (%o1)                                %e
          (%i2) exptsubst;
          (%o2)                                false
          (%i3) subst(y, %e^x, %e^(a*x));
                                                 a x
          (%o3)                                %e
          (%i4) exptsubst: not exptsubst;
          (%o4)                                true
          (%i5) subst(y, %e^x, %e^(a*x));
                                                 a
          (%o5)                                 y


 -- Function: freeof (<x_1>, ..., <x_n>, <expr>)
     `freeof (<x_1>, <expr>)' returns `true' if no subexpression of
     <expr> is equal to <x_1> or if <x_1> occurs only as a dummy
     variable in <expr>, or if <x_1> is neither the noun nor verb form
     of any operator in <expr>, and returns `false' otherwise.

     `freeof (<x_1>, ..., <x_n>, <expr>)' is equivalent to `freeof
     (<x_1>, <expr>) and ... and freeof (<x_n>, <expr>)'.

     The arguments <x_1>, ..., <x_n> may be names of functions and
     variables, subscripted names, operators (enclosed in double
     quotes), or general expressions.  `freeof' evaluates its arguments.

     `freeof' operates only on <expr> as it stands (after
     simplification and evaluation) and does not attempt to determine
     if some equivalent expression would give a different result.  In
     particular, simplification may yield an equivalent but different
     expression which comprises some different elements than the
     original form of <expr>.

     A variable is a dummy variable in an expression if it has no
     binding outside of the expression.  Dummy variables recognized by
     `freeof' are the index of a sum or product, the limit variable in
     `limit', the integration variable in the definite integral form of
     `integrate', the original variable in `laplace', formal variables
     in `at' expressions, and arguments in `lambda' expressions.

     The indefinite form of `integrate' is not free of its variable of
     integration.

     Examples:

     Arguments are names of functions, variables, subscripted names,
     operators, and expressions.  `freeof (a, b, expr)' is equivalent to
     `freeof (a, expr) and freeof (b, expr)'.

          (%i1) expr: z^3 * cos (a[1]) * b^(c+d);
                                           d + c  3
          (%o1)                   cos(a ) b      z
                                       1
          (%i2) freeof (z, expr);
          (%o2)                         false
          (%i3) freeof (cos, expr);
          (%o3)                         false
          (%i4) freeof (a[1], expr);
          (%o4)                         false
          (%i5) freeof (cos (a[1]), expr);
          (%o5)                         false
          (%i6) freeof (b^(c+d), expr);
          (%o6)                         false
          (%i7) freeof ("^", expr);
          (%o7)                         false
          (%i8) freeof (w, sin, a[2], sin (a[2]), b*(c+d), expr);
          (%o8)                         true

     `freeof' evaluates its arguments.

          (%i1) expr: (a+b)^5$
          (%i2) c: a$
          (%i3) freeof (c, expr);
          (%o3)                         false

     `freeof' does not consider equivalent expressions.  Simplification
     may yield an equivalent but different expression.

          (%i1) expr: (a+b)^5$
          (%i2) expand (expr);
                    5        4       2  3       3  2      4      5
          (%o2)    b  + 5 a b  + 10 a  b  + 10 a  b  + 5 a  b + a
          (%i3) freeof (a+b, %);
          (%o3)                         true
          (%i4) freeof (a+b, expr);
          (%o4)                         false
          (%i5) exp (x);
                                           x
          (%o5)                          %e
          (%i6) freeof (exp, exp (x));
          (%o6)                         true

     A summation or definite integral is free of its dummy variable.
     An indefinite integral is not free of its variable of integration.

          (%i1) freeof (i, 'sum (f(i), i, 0, n));
          (%o1)                         true
          (%i2) freeof (x, 'integrate (x^2, x, 0, 1));
          (%o2)                         true
          (%i3) freeof (x, 'integrate (x^2, x));
          (%o3)                         false


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

     When `inflag' is `true', functions for part extraction inspect the
     internal form of `expr'.

     Note that the simplifier re-orders expressions.  Thus `first (x +
     y)' returns `x' if `inflag' is `true' and `y' if `inflag' is
     `false'.  (`first (y + x)' gives the same results.)

     Also, setting `inflag' to `true' and calling `part' or `substpart'
     is the same as calling `inpart' or `substinpart'.

     Functions affected by the setting of `inflag' are: `part',
     `substpart', `first', `rest', `last', `length', the `for' ... `in'
     construct, `map', `fullmap', `maplist', `reveal' and `pickapart'.


 -- Function: inpart (<expr>, <n_1>, ..., <n_k>)
     is similar to `part' but works on the internal representation of
     the expression rather than the displayed form and thus may be
     faster since no formatting is done.  Care should be taken with
     respect to the order of subexpressions in sums and products (since
     the order of variables in the internal form is often different
     from that in the displayed form) and in dealing with unary minus,
     subtraction, and division (since these operators are removed from
     the expression).  `part (x+y, 0)' or `inpart (x+y, 0)' yield `+',
     though in order to refer to the operator it must be enclosed in "s.
     For example `... if inpart (%o9,0) = "+" then ...'.

     Examples:

          (%i1) x + y + w*z;
          (%o1)                      w z + y + x
          (%i2) inpart (%, 3, 2);
          (%o2)                           z
          (%i3) part (%th (2), 1, 2);
          (%o3)                           z
          (%i4) 'limit (f(x)^g(x+1), x, 0, minus);
                                            g(x + 1)
          (%o4)                 limit   f(x)
                                x -> 0-
          (%i5) inpart (%, 1, 2);
          (%o5)                       g(x + 1)


 -- Function: isolate (<expr>, <x>)
     Returns <expr> with subexpressions which are sums and which do not
     contain <var> replaced by intermediate expression labels (these
     being atomic symbols like `%t1', `%t2', ...).  This is often
     useful to avoid unnecessary expansion of subexpressions which
     don't contain the variable of interest.  Since the intermediate
     labels are bound to the subexpressions they can all be substituted
     back by evaluating the expression in which they occur.

     `exptisolate' (default value: `false') if `true' will cause
     `isolate' to examine exponents of atoms (like `%e') which contain
     <var>.

     `isolate_wrt_times' if `true', then `isolate' will also isolate
     with respect to products.  See `isolate_wrt_times'.

     Do `example (isolate)' for examples.


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

     When `isolate_wrt_times' is `true', `isolate' will also isolate
     with respect to products.  E.g. compare both settings of the
     switch on

          (%i1) isolate_wrt_times: true$
          (%i2) isolate (expand ((a+b+c)^2), c);

          (%t2)                          2 a


          (%t3)                          2 b


                                    2            2
          (%t4)                    b  + 2 a b + a

                               2
          (%o4)               c  + %t3 c + %t2 c + %t4
          (%i4) isolate_wrt_times: false$
          (%i5) isolate (expand ((a+b+c)^2), c);
                               2
          (%o5)               c  + 2 b c + 2 a c + %t4


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

     When `listconstvars' is `true' the list returned by `listofvars'
     contains constant variables, such as `%e', `%pi', `%i' or any
     variables declared as constant that occur in <expr>. A variable is
     declared as `constant' type via `declare', and `constantp' returns
     `true' for all variables declared as `constant'. The default is to
     omit constant variables from `listofvars' return value.

     Example:

          (%i1) lfreeof ([ a, x], x^2+b);
          (%o1)                                false
          lfreeof ([ b, x], x^2+b);
          (%o2)                                false
          lfreeof ([ a, y], x^2+b);
          (%o3)                                true


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

     When `listdummyvars' is `false', "dummy variables" in the
     expression will not be included in the list returned by
     `listofvars'.  (The meaning of "dummy variables" is as given in
     `freeof'.  "Dummy variables" are mathematical things like the
     index of a sum or product, the limit variable, and the definite
     integration variable.)

     Example:

          (%i1) listdummyvars: true$
          (%i2) listofvars ('sum(f(i), i, 0, n));
          (%o2)                        [i, n]
          (%i3) listdummyvars: false$
          (%i4) listofvars ('sum(f(i), i, 0, n));
          (%o4)                          [n]


 -- Function: listofvars (<expr>)
     Returns a list of the variables in <expr>.

     `listconstvars' if `true' causes `listofvars' to include `%e',
     `%pi', `%i', and any variables declared constant in the list it
     returns if they appear in <expr>.  The default is to omit these.

     See also the option variable `listdummyvars' to exclude or include
     "dummy variables" in the list of variables.

          (%i1) listofvars (f (x[1]+y) / g^(2+a));
          (%o1)                     [g, a, x , y]
                                            1


 -- Function: lfreeof (<list>, <expr>)
     For each member <m> of <list>, calls `freeof (<m>, <expr>)'.  It
     returns `false' if any call to `freeof' does and `true' otherwise.


 -- Function: lpart (<label>, <expr>, <n_1>, ..., <n_k>)
     is similar to `dpart' but uses a labelled box.  A labelled box is
     similar to the one produced by `dpart' but it has a name in the
     top line.


 -- Property: mainvar
     You may declare variables to be `mainvar'.  The ordering scale for
     atoms is essentially: numbers < constants (e.g., `%e', `%pi') <
     scalars < other variables < mainvars.  E.g., compare `expand
     ((X+Y)^4)' with `(declare (x, mainvar), expand ((x+y)^4))'.
     (Note: Care should be taken if you elect to use the above feature.
     E.g., if you subtract an expression in which `x' is a `mainvar'
     from one in which `x' isn't a `mainvar', resimplification e.g.
     with `ev (expr, simp)' may be necessary if cancellation is to
     occur.  Also, if you save an expression in which `x' is a
     `mainvar', you probably should also save `x'.)


 -- Property: noun
     `noun' is one of the options of the `declare' command.  It makes a
     function so declared a "noun", meaning that it won't be evaluated
     automatically.

     Example:

          (%i1) factor (12345678);
                                       2
          (%o1)                     2 3  47 14593
          (%i2) declare (factor, noun);
          (%o2)                         done
          (%i3) factor (12345678);
          (%o3)                   factor(12345678)
          (%i4) ''%, nouns;
                                       2
          (%o4)                     2 3  47 14593


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

     When `noundisp' is `true', nouns display with a single quote.
     This switch is always `true' when displaying function definitions.


 -- Function: nounify (<f>)
     Returns the noun form of the function name <f>.  This is needed if
     one wishes to refer to the name of a verb function as if it were a
     noun.  Note that some verb functions will return their noun forms
     if they can't be evaluated for certain arguments.  This is also
     the form returned if a function call is preceded by a quote.

     See also `verbify'.


 -- Function: nterms (<expr>)
     Returns the number of terms that <expr> would have if it were fully
     expanded out and no cancellations or combination of terms occurred.
     Note that expressions like `sin (<expr>)', `sqrt (<expr>)', `exp
     (<expr>)', etc. count as just one term regardless of how many
     terms <expr> has (if it is a sum).


 -- Function: op (<expr>)
     Returns the main operator of the expression <expr>.  `op (<expr>)'
     is equivalent to `part (<expr>, 0)'.

     `op' returns a string if the main operator is a built-in or
     user-defined prefix, binary or n-ary infix, postfix, matchfix, or
     nofix operator.  Otherwise, if <expr> is a subscripted function
     expression, `op' returns the subscripted function; in this case
     the return value is not an atom.  Otherwise, <expr> is an array
     function or ordinary function expression, and `op' returns a
     symbol.

     `op' observes the value of the global flag `inflag'.

     `op' evaluates it argument.

     See also `args'.

     Examples:

          (%i1) stringdisp: true$
          (%i2) op (a * b * c);
          (%o2)                          "*"
          (%i3) op (a * b + c);
          (%o3)                          "+"
          (%i4) op ('sin (a + b));
          (%o4)                          sin
          (%i5) op (a!);
          (%o5)                          "!"
          (%i6) op (-a);
          (%o6)                          "-"
          (%i7) op ([a, b, c]);
          (%o7)                          "["
          (%i8) op ('(if a > b then c else d));
          (%o8)                         "if"
          (%i9) op ('foo (a));
          (%o9)                          foo
          (%i10) prefix (foo);
          (%o10)                        "foo"
          (%i11) op (foo a);
          (%o11)                        "foo"
          (%i12) op (F [x, y] (a, b, c));
          (%o12)                        F
                                         x, y
          (%i13) op (G [u, v, w]);
          (%o13)                          G


 -- Function: operatorp (<expr>, <op>)
 -- Function: operatorp (<expr>, [<op_1>, ..., <op_n>])
     `operatorp (<expr>, <op>)' returns `true' if <op> is equal to the
     operator of <expr>.

     `operatorp (<expr>, [<op_1>, ..., <op_n>])' returns `true' if some
     element <op_1>, ..., <op_n> is equal to the operator of <expr>.


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

     When `opsubst' is `false', `subst' does not attempt to substitute
     into the operator of an expression.  E.g., `(opsubst: false, subst
     (x^2, r, r+r[0]))' will work.

          (%i1) r+r[0];
          (%o1)                               r + r
                                                   0
          (%i2) opsubst;
          (%o2)                                true
          (%i3) subst (x^2, r, r+r[0]);
                                             2     2
          (%o3)                             x  + (x )
                                                     0
          (%i4) opsubst: not opsubst;
          (%o4)                                false
          (%i5) subst (x^2, r, r+r[0]);
                                               2
          (%o5)                               x  + r
                                                    0


 -- Function: optimize (<expr>)
     Returns an expression that produces the same value and side
     effects as <expr> but does so more efficiently by avoiding the
     recomputation of common subexpressions.  `optimize' also has the
     side effect of "collapsing" its argument so that all common
     subexpressions are shared.  Do `example (optimize)' for examples.


 -- Option variable: optimprefix
     Default value: `%'

     `optimprefix' is the prefix used for generated symbols by the
     `optimize' command.


 -- Function: ordergreat (<v_1>, ..., <v_n>)
 -- Function: orderless (<v_1>, ..., <v_n>)
     `ordergreat' changes the canonical ordering of Maxima expressions
     such that <v_1> succeeds <v_2> succeeds ...  succeeds <v_n>, and
     <v_n> succeeds any other symbol not mentioned as an argument.

     `orderless' changes the canonical ordering of Maxima expressions
     such that <v_1> precedes <v_2> precedes ... precedes <v_n>, and
     <v_n> precedes any other variable not mentioned as an argument.

     The order established by `ordergreat' and `orderless' is dissolved
     by `unorder'.  `ordergreat' and `orderless' can be called only
     once each, unless `unorder' is called; only the last call to
     `ordergreat' and `orderless' has any effect.

     See also `ordergreatp'.


 -- Function: ordergreatp (<expr_1>, <expr_2>)
 -- Function: orderlessp (<expr_1>, <expr_2>)
     `ordergreatp' returns `true' if <expr_1> succeeds <expr_2> in the
     canonical ordering of Maxima expressions, and `false' otherwise.

     `orderlessp' returns `true' if <expr_1> precedes <expr_2> in the
     canonical ordering of Maxima expressions, and `false' otherwise.

     All Maxima atoms and expressions are comparable under
     `ordergreatp' and `orderlessp', although there are isolated
     examples of expressions for which these predicates are not
     transitive; that is a bug.

     The canonical ordering of atoms (symbols, literal numbers, and
     strings) is the following.

     (integers and floats) precede (bigfloats) precede (declared
     constants) precede (strings) precede (declared scalars) precede
     (first argument to `orderless') precedes ... precedes (last
     argument to `orderless') precedes (other symbols) precede (last
     argument to `ordergreat') precedes ... precedes (first argument to
     `ordergreat') precedes (declared main variables)

     For non-atomic expressions, the canonical ordering is derived from
     the ordering for atoms.  For the built-in `+' `*' and `^'
     operators, the ordering is not easily summarized.  For other
     built-in operators and all other functions and operators,
     expressions are ordered by their arguments (beginning with the
     first argument), then by the name of the operator or function.  In
     the case of subscripted expressions, the subscripted symbol is
     considered the operator and the subscript is considered an
     argument.

     The canonical ordering of expressions is modified by the functions
     `ordergreat' and `orderless', and the `mainvar', `constant', and
     `scalar' declarations.

     See also `sort'.

     Examples:

     Ordering ordinary symbols and constants.  Note that `%pi' is not
     ordered according to its numerical value.

          (%i1) stringdisp : true;
          (%o1)                         true
          (%i2) sort([%pi, 3b0, 3.0, x, X, "foo", 3, a, 4, "bar", 4.0, 4b0]);
          (%o2) [3, 3.0, 4, 4.0, 3.0b0, 4.0b0, %pi, "bar", "foo", a, x, X]

     Effect of `ordergreat' and `orderless' functions.

          (%i1) sort ([M, H, K, T, E, W, G, A, P, J, S]);
          (%o1)           [A, E, G, H, J, K, M, P, S, T, W]
          (%i2) ordergreat (S, J);
          (%o2)                         done
          (%i3) orderless (M, H);
          (%o3)                         done
          (%i4) sort ([M, H, K, T, E, W, G, A, P, J, S]);
          (%o4)           [M, H, A, E, G, K, P, T, W, J, S]

     Effect of `mainvar', `constant', and `scalar' declarations.

          (%i1) sort ([aa, foo, bar, bb, baz, quux, cc, dd, A1, B1, C1]);
          (%o1)   [aa, bar, baz, bb, cc, dd, foo, quux, A1, B1, C1]
          (%i2) declare (aa, mainvar);
          (%o2)                         done
          (%i3) declare ([baz, quux], constant);
          (%o3)                         done
          (%i4) declare ([A1, B1], scalar);
          (%o4)                         done
          (%i5) sort ([aa, foo, bar, bb, baz, quux, cc, dd, A1, B1, C1]);
          (%o5)   [baz, quux, A1, B1, bar, bb, cc, dd, foo, C1, aa]

     Ordering non-atomic expressions.

          (%i1) sort([1, 2, n, f(1), f(2), f(2, 1), g(1), g(1, 2), g(n),
                      f(n, 1)]);
          (%o1) [1, 2, f(1), g(1), g(1, 2), f(2), f(2, 1), n, g(n),
                                                                   f(n, 1)]
          (%i2) sort ([foo(1), X[1], X[k], foo(k), 1, k]);
          (%o2)            [1, foo(1), X , k, foo(k), X ]
                                        1              k


 -- Function: part (<expr>, <n_1>, ..., <n_k>)
     Returns parts of the displayed form of `expr'.  It obtains the
     part of `expr' as specified by the indices <n_1>, ..., <n_k>.
     First part <n_1> of `expr' is obtained, then part <n_2> of that,
     etc.  The result is part <n_k> of ... part <n_2> of part <n_1> of
     `expr'.  If no indices are specified `expr' is returned.

     `part' can be used to obtain an element of a list, a row of a
     matrix, etc.

     If the last argument to a `part' function is a list of indices then
     several subexpressions are picked out, each one corresponding to an
     index of the list.  Thus `part (x + y + z, [1, 3])' is `z+x'.

     `piece' holds the last expression selected when using the `part'
     functions.  It is set during the execution of the function and thus
     may be referred to in the function itself as shown below.

     If `partswitch' is set to `true' then `end' is returned when a
     selected part of an expression doesn't exist, otherwise an error
     message is given.

     See also `inpart', `substpart', `substinpart', `dpart', and
     `lpart'.

     Examples:

          (%i1) part(z+2*y+a,2);
          (%o1)                                 2 y
          (%i2) part(z+2*y+a,[1,3]);
          (%o2)                                z + a
          (%i3) part(z+2*y+a,2,1);
          (%o3)                                  2

     `example (part)' displays additional examples.


 -- Function: partition (<expr>, <x>)
     Returns a list of two expressions.  They are (1) the factors of
     <expr> (if it is a product), the terms of <expr> (if it is a sum),
     or the list (if it is a list) which don't contain <x> and, (2) the
     factors, terms, or list which do.

     Examples:

          (%i1) partition (2*a*x*f(x), x);
          (%o1)                     [2 a, x f(x)]
          (%i2) partition (a+b, x);
          (%o2)                      [b + a, 0]
          (%i3) partition ([a, b, f(a), c], a);
          (%o3)                  [[b, c], [a, f(a)]]


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

     When `partswitch' is `true', `end' is returned when a selected
     part of an expression doesn't exist, otherwise an error message is
     given.


 -- Function: pickapart (<expr>, <n>)
     Assigns intermediate expression labels to subexpressions of <expr>
     at depth <n>, an integer.  Subexpressions at greater or lesser
     depths are not assigned labels.  `pickapart' returns an expression
     in terms of intermediate expressions equivalent to the original
     expression <expr>.

     See also `part', `dpart', `lpart', `inpart', and `reveal'.

     Examples:

          (%i1) expr: (a+b)/2 + sin (x^2)/3 - log (1 + sqrt(x+1));
                                                    2
                                               sin(x )   b + a
          (%o1)       - log(sqrt(x + 1) + 1) + ------- + -----
                                                  3        2
          (%i2) pickapart (expr, 0);
                                                    2
                                               sin(x )   b + a
          (%t2)       - log(sqrt(x + 1) + 1) + ------- + -----
                                                  3        2
          (%o2)                          %t2
          (%i3) pickapart (expr, 1);

          (%t3)                - log(sqrt(x + 1) + 1)


                                            2
                                       sin(x )
          (%t4)                        -------
                                          3


                                        b + a
          (%t5)                         -----
                                          2

          (%o5)                    %t5 + %t4 + %t3
          (%i5) pickapart (expr, 2);

          (%t6)                 log(sqrt(x + 1) + 1)


                                            2
          (%t7)                        sin(x )


          (%t8)                         b + a

                                   %t8   %t7
          (%o8)                    --- + --- - %t6
                                    2     3
          (%i8) pickapart (expr, 3);

          (%t9)                    sqrt(x + 1) + 1


                                          2
          (%t10)                         x

                            b + a              sin(%t10)
          (%o10)            ----- - log(%t9) + ---------
                              2                    3
          (%i10) pickapart (expr, 4);

          (%t11)                     sqrt(x + 1)
                                2
                           sin(x )   b + a
          (%o11)           ------- + ----- - log(%t11 + 1)
                              3        2
          (%i11) pickapart (expr, 5);

          (%t12)                        x + 1

                             2
                        sin(x )   b + a
          (%o12)        ------- + ----- - log(sqrt(%t12) + 1)
                           3        2
          (%i12) pickapart (expr, 6);
                            2
                       sin(x )   b + a
          (%o12)       ------- + ----- - log(sqrt(x + 1) + 1)
                          3        2


 -- System variable: piece
     Holds the last expression selected when using the `part' functions.
     It is set during the execution of the function and thus may be
     referred to in the function itself.


 -- Function: psubst (<list>, <expr>)
 -- Function: psubst (<a>, <b>, <expr>)
     `psubst(<a>, <b>, <expr>)' is simliar to `subst'.  See `subst'.

     In distinction from `subst' the function `psubst' makes parallel
     substitutions, if the first argument <list> is a list of equations.

     See also `sublis' for making parallel substitutions.

     Example:

     The first example shows parallel substitution with `psubst'.  The
     second example shows the result for the function `subst', which
     does a serial substitution.

          (%i4) psubst ([a^2=b, b=a], sin(a^2) + sin(b));
          (%o4)                           sin(b) + sin(a)
          (%i5) subst ([a^2=b, b=a], sin(a^2) + sin(b));
          (%o5)                              2 sin(a)


 -- Function: rembox (<expr>, unlabelled)
 -- Function: rembox (<expr>, <label>)
 -- Function: rembox (<expr>)
     Removes boxes from <expr>.

     `rembox (<expr>, unlabelled)' removes all unlabelled boxes from
     <expr>.

     `rembox (<expr>, <label>)' removes only boxes bearing <label>.

     `rembox (<expr>)' removes all boxes, labelled and unlabelled.

     Boxes are drawn by the `box', `dpart', and `lpart' functions.

     Examples:

          (%i1) expr: (a*d - b*c)/h^2 + sin(%pi*x);
                                            a d - b c
          (%o1)                sin(%pi x) + ---------
                                                2
                                               h
          (%i2) dpart (dpart (expr, 1, 1), 2, 2);
                                  """""""    a d - b c
          (%o2)               sin("%pi x") + ---------
                                  """""""      """"
                                               " 2"
                                               "h "
                                               """"
          (%i3) expr2: lpart (BAR, lpart (FOO, %, 1), 2);
                            FOO"""""""""""   BAR""""""""
                            "    """"""" "   "a d - b c"
          (%o3)             "sin("%pi x")" + "---------"
                            "    """"""" "   "  """"   "
                            """"""""""""""   "  " 2"   "
                                             "  "h "   "
                                             "  """"   "
                                             """""""""""
          (%i4) rembox (expr2, unlabelled);
                                            BAR""""""""
                             FOO"""""""""   "a d - b c"
          (%o4)              "sin(%pi x)" + "---------"
                             """"""""""""   "    2    "
                                            "   h     "
                                            """""""""""
          (%i5) rembox (expr2, FOO);
                                            BAR""""""""
                                 """""""    "a d - b c"
          (%o5)              sin("%pi x") + "---------"
                                 """""""    "  """"   "
                                            "  " 2"   "
                                            "  "h "   "
                                            "  """"   "
                                            """""""""""
          (%i6) rembox (expr2, BAR);
                             FOO"""""""""""
                             "    """"""" "   a d - b c
          (%o6)              "sin("%pi x")" + ---------
                             "    """"""" "     """"
                             """"""""""""""     " 2"
                                                "h "
                                                """"
          (%i7) rembox (expr2);
                                            a d - b c
          (%o7)                sin(%pi x) + ---------
                                                2
                                               h


 -- Function: reveal (<expr>, <depth>)
     Replaces parts of <expr> at the specified integer <depth> with
     descriptive summaries.

        * Sums and differences are replaced by `Sum(<n>)' where <n> is
          the number of operands of the sum.

        * Products are replaced by `Product(<n>)' where <n> is the
          number of operands of the product.

        * Exponentials are replaced by `Expt'.

        * Quotients are replaced by `Quotient'.

        * Unary negation is replaced by `Negterm'.

        * Lists are replaced by `List(<n>)' where <n> ist the number of
          elements of the list.

     When <depth> is greater than or equal to the maximum depth of
     <expr>, `reveal (<expr>, <depth>)' returns <expr> unmodified.

     `reveal' evaluates its arguments.  `reveal' returns the summarized
     expression.

     Example:

          (%i1) e: expand ((a - b)^2)/expand ((exp(a) + exp(b))^2);
                                    2            2
                                   b  - 2 a b + a
          (%o1)               -------------------------
                                  b + a     2 b     2 a
                              2 %e      + %e    + %e
          (%i2) reveal (e, 1);
          (%o2)                       Quotient
          (%i3) reveal (e, 2);
                                       Sum(3)
          (%o3)                        ------
                                       Sum(3)
          (%i4) reveal (e, 3);
                               Expt + Negterm + Expt
          (%o4)               ------------------------
                              Product(2) + Expt + Expt
          (%i5) reveal (e, 4);
                                 2                 2
                                b  - Product(3) + a
          (%o5)         ------------------------------------
                                   Product(2)     Product(2)
                        2 Expt + %e           + %e
          (%i6) reveal (e, 5);
                                   2            2
                                  b  - 2 a b + a
          (%o6)              --------------------------
                                 Sum(2)     2 b     2 a
                             2 %e       + %e    + %e
          (%i7) reveal (e, 6);
                                    2            2
                                   b  - 2 a b + a
          (%o7)               -------------------------
                                  b + a     2 b     2 a
                              2 %e      + %e    + %e


 -- Function: sublis (<list>, <expr>)
     Makes multiple parallel substitutions into an expression.  <list>
     is a list of equations.  The left hand side of the equations must
     be an atom.

     The variable `sublis_apply_lambda' controls simplification after
     `sublis'.

     See also `psubst' for making parallel substitutions.

     Example:

          (%i1) sublis ([a=b, b=a], sin(a) + cos(b));
          (%o1)                    sin(b) + cos(a)


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

     Controls whether `lambda''s substituted are applied in
     simplification after `sublis' is used or whether you have to do an
     `ev' to get things to apply.  `true' means do the application.


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

     If `true' then the functions `subst' and `psubst' can substitute a
     subscripted variable `f[x]' with a number, when only the symbol `f'
     is given.

     See also `subst'.

          (%i1) subst(100,g,g[x]+2);

          subst: cannot substitute 100 for operator g in expression g
                                                                     x
           -- an error. To debug this try: debugmode(true);

          (%i2) subst(100,g,g[x]+2),subnumsimp:true;
          (%o2)                          102


 -- Function: subst (<a>, <b>, <c>)
     Substitutes <a> for <b> in <c>.  <b> must be an atom or a complete
     subexpression of <c>.  For example, `x+y+z' is a complete
     subexpression of `2*(x+y+z)/w' while `x+y' is not.  When <b> does
     not have these characteristics, one may sometimes use `substpart'
     or `ratsubst' (see below).  Alternatively, if <b> is of the form
     `e/f' then one could use `subst (a*f, e, c)' while if <b> is of
     the form `e^(1/f)' then one could use `subst (a^f, e, c)'.  The
     `subst' command also discerns the `x^y' in `x^-y' so that `subst
     (a, sqrt(x), 1/sqrt(x))' yields `1/a'.  <a> and <b> may also be
     operators of an expression enclosed in double-quotes `"' or they
     may be function names.  If one wishes to substitute for the
     independent variable in derivative forms then the `at' function
     (see below) should be used.

     `subst' is an alias for `substitute'.

     The commands `subst (<eq_1>, <expr>)' or `subst ([<eq_1>, ...,
     <eq_k>], <expr>)' are other permissible forms.  The <eq_i> are
     equations indicating substitutions to be made.  For each equation,
     the right side will be substituted for the left in the expression
     <expr>.  The equations are substituted in serial from left to
     right in <expr>.  See the functions `sublis' and `psubst' for
     making parallel substitutions.

     `exptsubst' if `true' permits substitutions like `y' for `%e^x' in
     `%e^(a*x)' to take place.

     When `opsubst' is `false', `subst' will not attempt to substitute
     into the operator of an expression.  E.g. `(opsubst: false, subst
     (x^2, r, r+r[0]))' will work.

     Examples:

          (%i1) subst (a, x+y, x + (x+y)^2 + y);
                                              2
          (%o1)                      y + x + a
          (%i2) subst (-%i, %i, a + b*%i);
          (%o2)                       a - %i b

     The substitution is done in serial for a list of equations.
     Compare this with a parallel substitution:

          (%i3) subst([a=b, b=c], a+b);
          (%o3)                                 2 c
          (%i4) sublis([a=b, b=c], a+b);
          (%o4)                                c + b

     For further examples, do `example (subst)'.


 -- Function: substinpart (<x>, <expr>, <n_1>, ..., <n_k>)
     Similar to `substpart', but `substinpart' works on the internal
     representation of <expr>.

     Examples:

          (%i1) x . 'diff (f(x), x, 2);
                                        2
                                       d
          (%o1)                   x . (--- (f(x)))
                                         2
                                       dx
          (%i2) substinpart (d^2, %, 2);
                                            2
          (%o2)                        x . d
          (%i3) substinpart (f1, f[1](x + 1), 0);
          (%o3)                       f1(x + 1)

     If the last argument to a `part' function is a list of indices then
     several subexpressions are picked out, each one corresponding to an
     index of the list.  Thus

          (%i1) part (x + y + z, [1, 3]);
          (%o1)                         z + x

     `piece' holds the value of the last expression selected when using
     the `part' functions.  It is set during the execution of the
     function and thus may be referred to in the function itself as
     shown below.  If `partswitch' is set to `true' then `end' is
     returned when a selected part of an expression doesn't exist,
     otherwise an error message is given.

          (%i1) expr: 27*y^3 + 54*x*y^2 + 36*x^2*y + y + 8*x^3 + x + 1;
                        3         2       2            3
          (%o1)     27 y  + 54 x y  + 36 x  y + y + 8 x  + x + 1
          (%i2) part (expr, 2, [1, 3]);
                                            2
          (%o2)                         54 y
          (%i3) sqrt (piece/54);
          (%o3)                        abs(y)
          (%i4) substpart (factor (piece), expr, [1, 2, 3, 5]);
                                         3
          (%o4)               (3 y + 2 x)  + y + x + 1
          (%i5) expr: 1/x + y/x - 1/z;
                                       1   y   1
          (%o5)                      - - + - + -
                                       z   x   x
          (%i6) substpart (xthru (piece), expr, [2, 3]);
                                      y + 1   1
          (%o6)                       ----- - -
                                        x     z

     Also, setting the option `inflag' to `true' and calling `part' or
     `substpart' is the same as calling `inpart' or `substinpart'.


 -- Function: substpart (<x>, <expr>, <n_1>, ..., <n_k>)
     Substitutes <x> for the subexpression picked out by the rest of the
     arguments as in `part'.  It returns the new value of <expr>.  <x>
     may be some operator to be substituted for an operator of <expr>.
     In some cases <x> needs to be enclosed in double-quotes `"' (e.g.
     `substpart ("+", a*b, 0)' yields `b + a').

     Example:

          (%i1) 1/(x^2 + 2);
                                         1
          (%o1)                        ------
                                        2
                                       x  + 2
          (%i2) substpart (3/2, %, 2, 1, 2);
                                         1
          (%o2)                       --------
                                       3/2
                                      x    + 2
          (%i3) a*x + f(b, y);
          (%o3)                     a x + f(b, y)
          (%i4) substpart ("+", %, 1, 0);
          (%o4)                    x + f(b, y) + a

     Also, setting the option `inflag' to `true' and calling `part' or
     `substpart' is the same as calling `inpart' or `substinpart'.


 -- Function: symbolp (<expr>)
     Returns `true' if <expr> is a symbol, else `false'.  In effect,
     `symbolp(x)' is equivalent to the predicate `atom(x) and not
     numberp(x)'.

     See also *note Identifiers::.


 -- Function: unorder ()
     Disables the aliasing created by the last use of the ordering
     commands `ordergreat' and `orderless'.  `ordergreat' and
     `orderless' may not be used more than one time each without
     calling `unorder'.  `unorder' does not substitute back in
     expressions the original symbols for the aliases introduced by
     `ordergreat' and `orderless'.  Therefore, after execution of
     `unorder' the aliases appear in previous expressions.

     See also `ordergreat' and `orderless'.

     Examples:

     `ordergreat(a)' introduces an alias for the symbol `a'.  Therefore,
     the difference of `%o2' and `%o4' does not vanish.  `unorder' does
     not substitute back the symbol `a' and the alias appears in the
     output `%o7'.

          (%i1) unorder();
          (%o1)                          []
          (%i2) b*x+a^2;
                                             2
          (%o2)                       b x + a
          (%i3) ordergreat(a);
          (%o3)                         done
          (%i4) b*x+a^2;
                                       2
          (%o4)                       a  + b x
          (%i5) %th(1)-%th(3);
                                        2    2
          (%o5)                        a  - a
          (%i6) unorder();
          (%o6)                          [a]
          (%i7) %th(2);
                                          2    2
          (%o7)                      _101a  - a


 -- Function: verbify (<f>)
     Returns the verb form of the function name <f>.  See also `verb',
     `noun', and `nounify'.

     Examples:

          (%i1) verbify ('foo);
          (%o1)                          foo
          (%i2) :lisp $%
          $FOO
          (%i2) nounify (foo);
          (%o2)                          foo
          (%i3) :lisp $%
          %FOO



File: maxima.info,  Node: Operators,  Next: Evaluation,  Prev: Expressions,  Up: Top

7 Operators
***********

* Menu:

* Introduction to operators::
* Arithmetic operators::
* Relational operators::
* Logical operators::
* Operators for Equations::
* Assignment operators::
* User defined operators::


File: maxima.info,  Node: Introduction to operators,  Next: Arithmetic operators,  Prev: Operators,  Up: Operators

7.1 Introduction to operators
=============================

It is possible to define new operators with specified precedence, to
undefine existing operators, or to redefine the precedence of existing
operators.  An operator may be unary prefix or unary postfix, binary
infix, n-ary infix, matchfix, or nofix.  "Matchfix" means a pair of
symbols which enclose their argument or arguments, and "nofix" means an
operator which takes no arguments.  As examples of the different types
of operators, there are the following.

unary prefix
     negation `- a'

unary postfix
     factorial `a!'

binary infix
     exponentiation `a^b'

n-ary infix
     addition `a + b'

matchfix
     list construction `[a, b]'

   (There are no built-in nofix operators; for an example of such an
operator, see `nofix'.)

   The mechanism to define a new operator is straightforward.  It is
only necessary to declare a function as an operator; the operator
function might or might not be defined.

   An example of user-defined operators is the following.  Note that
the explicit function call `"dd" (a)' is equivalent to `dd a', likewise
`"<-" (a, b)' is equivalent to `a <- b'.  Note also that the functions
`"dd"' and `"<-"' are undefined in this example.

     (%i1) prefix ("dd");
     (%o1)                          dd
     (%i2) dd a;
     (%o2)                         dd a
     (%i3) "dd" (a);
     (%o3)                         dd a
     (%i4) infix ("<-");
     (%o4)                          <-
     (%i5) a <- dd b;
     (%o5)                      a <- dd b
     (%i6) "<-" (a, "dd" (b));
     (%o6)                      a <- dd b

   The Maxima functions which define new operators are summarized in
this table, stating the default left and right binding powers (lbp and
rbp, respectively).  (Binding power determines operator precedence.
However, since left and right binding powers can differ, binding power
is somewhat more complicated than precedence.) Some of the operation
definition functions take additional arguments; see the function
descriptions for details.

`prefix'
     rbp=180

`postfix'
     lbp=180

`infix'
     lbp=180, rbp=180

`nary'
     lbp=180, rbp=180

`matchfix'
     (binding power not applicable)

`nofix'
     (binding power not applicable)

   For comparison, here are some built-in operators and their left and
right binding powers.

     Operator   lbp     rbp

       :        180     20
       ::       180     20
       :=       180     20
       ::=      180     20
       !        160
       !!       160
       ^        140     139
       .        130     129
       *        120
       /        120     120
       +        100     100
       -        100     134
       =        80      80
       #        80      80
       >        80      80
       >=       80      80
       <        80      80
       <=       80      80
       not              70
       and      65
       or       60
       ,        10
       $        -1
       ;        -1

   `remove' and `kill' remove operator properties from an atom.
`remove ("<a>", op)' removes only the operator properties of <a>.
`kill ("<a>")' removes all properties of <a>, including the operator
properties.  Note that the name of the operator must be enclosed in
quotation marks.

     (%i1) infix ("##");
     (%o1)                          ##
     (%i2) "##" (a, b) := a^b;
                                          b
     (%o2)                     a ## b := a
     (%i3) 5 ## 3;
     (%o3)                          125
     (%i4) remove ("##", op);
     (%o4)                         done
     (%i5) 5 ## 3;
     Incorrect syntax: # is not a prefix operator
     5 ##
       ^
     (%i5) "##" (5, 3);
     (%o5)                          125
     (%i6) infix ("##");
     (%o6)                          ##
     (%i7) 5 ## 3;
     (%o7)                          125
     (%i8) kill ("##");
     (%o8)                         done
     (%i9) 5 ## 3;
     Incorrect syntax: # is not a prefix operator
     5 ##
       ^
     (%i9) "##" (5, 3);
     (%o9)                       ##(5, 3)


File: maxima.info,  Node: Arithmetic operators,  Next: Relational operators,  Prev: Introduction to operators,  Up: Operators

7.2 Arithmetic operators
========================

 -- Operator: +
 -- Operator: -
 -- Operator: *
 -- Operator: /
 -- Operator: ^
     The symbols `+' `*' `/' and `^' represent addition,
     multiplication, division, and exponentiation, respectively.  The
     names of these operators are `"+"' `"*"' `"/"' and `"^"', which
     may appear where the name of a function or operator is required.

     The symbols `+' and `-' represent unary addition and negation,
     respectively, and the names of these operators are `"+"' and `"-"',
     respectively.

     Subtraction `a - b' is represented within Maxima as addition, `a +
     (- b)'.  Expressions such as `a + (- b)' are displayed as
     subtraction.  Maxima recognizes `"-"' only as the name of the unary
     negation operator, and not as the name of the binary subtraction
     operator.

     Division `a / b' is represented within Maxima as multiplication,
     `a * b^(- 1)'.  Expressions such as `a * b^(- 1)' are displayed as
     division.  Maxima recognizes `"/"' as the name of the division
     operator.

     Addition and multiplication are n-ary, commutative operators.
     Division and exponentiation are binary, noncommutative operators.

     Maxima sorts the operands of commutative operators to construct a
     canonical representation.  For internal storage, the ordering is
     determined by `orderlessp'.  For display, the ordering for
     addition is determined by `ordergreatp', and for multiplication,
     it is the same as the internal ordering.

     Arithmetic computations are carried out on literal numbers
     (integers, rationals, ordinary floats, and bigfloats).  Except for
     exponentiation, all arithmetic operations on numbers are
     simplified to numbers.  Exponentiation is simplified to a number
     if either operand is an ordinary float or bigfloat or if the result
     is an exact integer or rational; otherwise an exponentiation may
     be simplified to `sqrt' or another exponentiation or left
     unchanged.

     Floating-point contagion applies to arithmetic computations: if
     any operand is a bigfloat, the result is a bigfloat; otherwise, if
     any operand is an ordinary float, the result is an ordinary float;
     otherwise, the operands are rationals or integers and the result
     is a rational or integer.

     Arithmetic computations are a simplification, not an evaluation.
     Thus arithmetic is carried out in quoted (but simplified)
     expressions.

     Arithmetic operations are applied element-by-element to lists when
     the global flag `listarith' is `true', and always applied
     element-by-element to matrices.  When one operand is a list or
     matrix and another is an operand of some other type, the other
     operand is combined with each of the elements of the list or
     matrix.

     Examples:

     Addition and multiplication are n-ary, commutative operators.
     Maxima sorts the operands to construct a canonical representation.
     The names of these operators are `"+"' and `"*"'.

          (%i1) c + g + d + a + b + e + f;
          (%o1)               g + f + e + d + c + b + a
          (%i2) [op (%), args (%)];
          (%o2)              [+, [g, f, e, d, c, b, a]]
          (%i3) c * g * d * a * b * e * f;
          (%o3)                     a b c d e f g
          (%i4) [op (%), args (%)];
          (%o4)              [*, [a, b, c, d, e, f, g]]
          (%i5) apply ("+", [a, 8, x, 2, 9, x, x, a]);
          (%o5)                    3 x + 2 a + 19
          (%i6) apply ("*", [a, 8, x, 2, 9, x, x, a]);
                                           2  3
          (%o6)                       144 a  x

     Division and exponentiation are binary, noncommutative operators.
     The names of these operators are `"/"' and `"^"'.

          (%i1) [a / b, a ^ b];
                                        a   b
          (%o1)                        [-, a ]
                                        b
          (%i2) [map (op, %), map (args, %)];
          (%o2)              [[/, ^], [[a, b], [a, b]]]
          (%i3) [apply ("/", [a, b]), apply ("^", [a, b])];
                                        a   b
          (%o3)                        [-, a ]
                                        b

     Subtraction and division are represented internally in terms of
     addition and multiplication, respectively.

          (%i1) [inpart (a - b, 0), inpart (a - b, 1), inpart (a - b, 2)];
          (%o1)                      [+, a, - b]
          (%i2) [inpart (a / b, 0), inpart (a / b, 1), inpart (a / b, 2)];
                                             1
          (%o2)                       [*, a, -]
                                             b

     Computations are carried out on literal numbers.  Floating-point
     contagion applies.

          (%i1) 17 + b - (1/2)*29 + 11^(2/4);
                                                 5
          (%o1)                   b + sqrt(11) + -
                                                 2
          (%i2) [17 + 29, 17 + 29.0, 17 + 29b0];
          (%o2)                   [46, 46.0, 4.6b1]

     Arithmetic computations are a simplification, not an evaluation.

          (%i1) simp : false;
          (%o1)                         false
          (%i2) '(17 + 29*11/7 - 5^3);
                                        29 11    3
          (%o2)                    17 + ----- - 5
                                          7
          (%i3) simp : true;
          (%o3)                         true
          (%i4) '(17 + 29*11/7 - 5^3);
                                          437
          (%o4)                         - ---
                                           7

     Arithmetic is carried out element-by-element for lists (depending
     on `listarith') and matrices.

          (%i1) matrix ([a, x], [h, u]) - matrix ([1, 2], [3, 4]);
                                  [ a - 1  x - 2 ]
          (%o1)                   [              ]
                                  [ h - 3  u - 4 ]
          (%i2) 5 * matrix ([a, x], [h, u]);
                                    [ 5 a  5 x ]
          (%o2)                     [          ]
                                    [ 5 h  5 u ]
          (%i3) listarith : false;
          (%o3)                         false
          (%i4) [a, c, m, t] / [1, 7, 2, 9];
                                    [a, c, m, t]
          (%o4)                     ------------
                                    [1, 7, 2, 9]
          (%i5) [a, c, m, t] ^ x;
                                                x
          (%o5)                     [a, c, m, t]
          (%i6) listarith : true;
          (%o6)                         true
          (%i7) [a, c, m, t] / [1, 7, 2, 9];
                                        c  m  t
          (%o7)                     [a, -, -, -]
                                        7  2  9
          (%i8) [a, c, m, t] ^ x;
                                    x   x   x   x
          (%o8)                   [a , c , m , t ]


 -- Operator: **
     Exponentiation operator.  Maxima recognizes `**' as the same
     operator as `^' in input, and it is displayed as `^' in
     1-dimensional output, or by placing the exponent as a superscript
     in 2-dimensional output.

     The `fortran' function displays the exponentiation operator as
     `**', whether it was input as `**' or `^'.

     Examples:

          (%i1) is (a**b = a^b);
          (%o1)                         true
          (%i2) x**y + x^z;
                                        z    y
          (%o2)                        x  + x
          (%i3) string (x**y + x^z);
          (%o3)                        x^z+x^y
          (%i4) fortran (x**y + x^z);
                x**z+x**y
          (%o4)                         done


 -- Operator: ^^
     Noncommutative exponentiation operator.  `^^' is the
     exponentiation operator corresponding to noncommutative
     multiplication `.', just as the ordinary exponentiation operator
     `^' corresponds to commutative multiplication `*'.

     Noncommutative exponentiation is displayed by `^^' in
     1-dimensional output, and by placing the exponent as a superscript
     within angle brackets `< >' in 2-dimensional output.

     Examples:

          (%i1) a . a . b . b . b + a * a * a * b * b;
                                  3  2    <2>    <3>
          (%o1)                  a  b  + a    . b
          (%i2) string (a . a . b . b . b + a * a * a * b * b);
          (%o2)                  a^3*b^2+a^^2 . b^^3


 -- Operator: .
     The dot operator, for matrix (non-commutative) multiplication.
     When `"."' is used in this way, spaces should be left on both
     sides of it, e.g.  `A . B'.  This distinguishes it plainly from a
     decimal point in a floating point number.

     See also `dot', `dot0nscsimp', `dot0simp', `dot1simp', `dotassoc',
     `dotconstrules', `dotdistrib', `dotexptsimp', `dotident', and
     `dotscrules'.



File: maxima.info,  Node: Relational operators,  Next: Logical operators,  Prev: Arithmetic operators,  Up: Operators

7.3 Relational operators
========================

 -- Operator: <
 -- Operator: <=
 -- Operator: >=
 -- Operator: >
     The symbols `<' `<=' `>=' and `>' represent less than, less than
     or equal, greater than or equal, and greater than, respectively.
     The names of these operators are `"<"' `"<="' `">="' and `">"',
     which may appear where the name of a function or operator is
     required.

     These relational operators are all binary operators; constructs
     such as `a < b < c' are not recognized by Maxima.

     Relational expressions are evaluated to Boolean values by the
     functions `is' and `maybe', and the programming constructs `if',
     `while', and `unless'.  Relational expressions are not otherwise
     evaluated or simplified to Boolean values, although the arguments
     of relational expressions are evaluated (when evaluation is not
     otherwise prevented by quotation).

     When a relational expression cannot be evaluated to `true' or
     `false', the behavior of `is' and `if' are governed by the global
     flag `prederror'.  When `prederror' is `true', `is' and `if'
     trigger an error.  When `prederror' is `false', `is' returns
     `unknown', and `if' returns a partially-evaluated conditional
     expression.

     `maybe' always behaves as if `prederror' were `false', and `while'
     and `unless' always behave as if `prederror' were `true'.

     Relational operators do not distribute over lists or other
     aggregates.

     See also `=', `#', `equal', and `notequal'.

     Examples:

     Relational expressions are evaluated to Boolean values by some
     functions and programming constructs.

          (%i1) [x, y, z] : [123, 456, 789];
          (%o1)                    [123, 456, 789]
          (%i2) is (x < y);
          (%o2)                         true
          (%i3) maybe (y > z);
          (%o3)                         false
          (%i4) if x >= z then 1 else 0;
          (%o4)                           0
          (%i5) block ([S], S : 0, for i:1 while i <= 100 do S : S + i,
                       return (S));
          (%o5)                         5050

     Relational expressions are not otherwise evaluated or simplified
     to Boolean values, although the arguments of relational
     expressions are evaluated.

          (%o1)                    [123, 456, 789]
          (%i2) [x < y, y <= z, z >= y, y > z];
          (%o2)    [123 < 456, 456 <= 789, 789 >= 456, 456 > 789]
          (%i3) map (is, %);
          (%o3)               [true, true, true, false]



File: maxima.info,  Node: Logical operators,  Next: Operators for Equations,  Prev: Relational operators,  Up: Operators

7.4 Logical operators
=====================

 -- Operator: and
     The logical conjunction operator.  `and' is an n-ary infix
     operator; its operands are Boolean expressions, and its result is
     a Boolean value.

     `and' forces evaluation (like `is') of one or more operands, and
     may force evaluation of all operands.

     Operands are evaluated in the order in which they appear.  `and'
     evaluates only as many of its operands as necessary to determine
     the result.  If any operand is `false', the result is `false' and
     no further operands are evaluated.

     The global flag `prederror' governs the behavior of `and' when an
     evaluated operand cannot be determined to be `true' or `false'.
     `and' prints an error message when `prederror' is `true'.
     Otherwise, operands which do not evaluate to `true' or `false' are
     accepted, and the result is a Boolean expression.

     `and' is not commutative: `a and b' might not be equal to `b and
     a' due to the treatment of indeterminate operands.


 -- Operator: not
     The logical negation operator.  `not' is a prefix operator; its
     operand is a Boolean expression, and its result is a Boolean value.

     `not' forces evaluation (like `is') of its operand.

     The global flag `prederror' governs the behavior of `not' when its
     operand cannot be determined to be `true' or `false'.  `not'
     prints an error message when `prederror' is `true'.  Otherwise,
     operands which do not evaluate to `true' or `false' are accepted,
     and the result is a Boolean expression.


 -- Operator: or
     The logical disjunction operator.  `or' is an n-ary infix operator;
     its operands are Boolean expressions, and its result is a Boolean
     value.

     `or' forces evaluation (like `is') of one or more operands, and
     may force evaluation of all operands.

     Operands are evaluated in the order in which they appear.  `or'
     evaluates only as many of its operands as necessary to determine
     the result.  If any operand is `true', the result is `true' and no
     further operands are evaluated.

     The global flag `prederror' governs the behavior of `or' when an
     evaluated operand cannot be determined to be `true' or `false'.
     `or' prints an error message when `prederror' is `true'.
     Otherwise, operands which do not evaluate to `true' or `false' are
     accepted, and the result is a Boolean expression.

     `or' is not commutative: `a or b' might not be equal to `b or a'
     due to the treatment of indeterminate operands.



File: maxima.info,  Node: Operators for Equations,  Next: Assignment operators,  Prev: Logical operators,  Up: Operators

7.5 Operators for Equations
===========================

 -- Operator: #
     Represents the negation of syntactic equality `='.

     Note that because of the rules for evaluation of predicate
     expressions (in particular because `not <expr>' causes evaluation
     of <expr>), `not <a> = <b>' is equivalent to `is(<a> # <b>)',
     instead of `<a> # <b>'.

     Examples:

          (%i1) a = b;
          (%o1)                         a = b
          (%i2) is (a = b);
          (%o2)                         false
          (%i3) a # b;
          (%o3)                         a # b
          (%i4) not a = b;
          (%o4)                         true
          (%i5) is (a # b);
          (%o5)                         true
          (%i6) is (not a = b);
          (%o6)                         true


 -- Operator: =
     The equation operator.

     An expression `<a> = <b>', by itself, represents an unevaluated
     equation, which might or might not hold.  Unevaluated equations
     may appear as arguments to `solve' and `algsys' or some other
     functions.

     The function `is' evaluates `=' to a Boolean value.  `is(<a> =
     <b>)' evaluates `<a> = <b>' to `true' when <a> and <b> are
     identical.  That is, <a> and <b> are atoms which are identical, or
     they are not atoms and their operators are identical and their
     arguments are identical.  Otherwise, `is(<a> = <b>)' evaluates to
     `false'; it never evaluates to `unknown'.  When `is(<a> = <b>)' is
     `true', <a> and <b> are said to be syntactically equal, in
     contrast to equivalent expressions, for which `is(equal(<a>,
     <b>))' is `true'.  Expressions can be equivalent and not
     syntactically equal.

     The negation of `=' is represented by `#'.  As with `=', an
     expression `<a> # <b>', by itself, is not evaluated.  `is(<a> #
     <b>)' evaluates `<a> # <b>' to `true' or `false'.

     In addition to `is', some other operators evaluate `=' and `#' to
     `true' or `false', namely `if', `and', `or', and `not'.

     Note that because of the rules for evaluation of predicate
     expressions (in particular because `not <expr>' causes evaluation
     of <expr>), `not <a> = <b>' is equivalent to `is(<a> # <b>)',
     instead of `<a> # <b>'.

     `rhs' and `lhs' return the right-hand and left-hand sides,
     respectively, of an equation or inequation.

     See also `equal' and `notequal'.

     Examples:

     An expression `<a> = <b>', by itself, represents an unevaluated
     equation, which might or might not hold.

          (%i1) eq_1 : a * x - 5 * y = 17;
          (%o1)                    a x - 5 y = 17
          (%i2) eq_2 : b * x + 3 * y = 29;
          (%o2)                    3 y + b x = 29
          (%i3) solve ([eq_1, eq_2], [x, y]);
                                  196         29 a - 17 b
          (%o3)          [[x = ---------, y = -----------]]
                               5 b + 3 a       5 b + 3 a
          (%i4) subst (%, [eq_1, eq_2]);
                   196 a     5 (29 a - 17 b)
          (%o4) [--------- - --------------- = 17,
                 5 b + 3 a      5 b + 3 a
                                            196 b     3 (29 a - 17 b)
                                          --------- + --------------- = 29]
                                          5 b + 3 a      5 b + 3 a
          (%i5) ratsimp (%);
          (%o5)                  [17 = 17, 29 = 29]

     `is(<a> = <b>)' evaluates `<a> = <b>' to `true' when <a> and <b>
     are syntactically equal (that is, identical).  Expressions can be
     equivalent and not syntactically equal.

          (%i1) a : (x + 1) * (x - 1);
          (%o1)                    (x - 1) (x + 1)
          (%i2) b : x^2 - 1;
                                        2
          (%o2)                        x  - 1
          (%i3) [is (a = b), is (a # b)];
          (%o3)                     [false, true]
          (%i4) [is (equal (a, b)), is (notequal (a, b))];
          (%o4)                     [true, false]

     Some operators evaluate `=' and `#' to `true' or `false'.

          (%i1) if expand ((x + y)^2) = x^2 + 2 * x * y + y^2 then FOO else
                BAR;
          (%o1)                          FOO
          (%i2) eq_3 : 2 * x = 3 * x;
          (%o2)                       2 x = 3 x
          (%i3) eq_4 : exp (2) = %e^2;
                                        2     2
          (%o3)                       %e  = %e
          (%i4) [eq_3 and eq_4, eq_3 or eq_4, not eq_3];
          (%o4)                  [false, true, true]

     Because `not <expr>' causes evaluation of <expr>, `not <a> = <b>'
     is equivalent to `is(<a> # <b>)'.

          (%i1) [2 * x # 3 * x, not (2 * x = 3 * x)];
          (%o1)                   [2 x # 3 x, true]
          (%i2) is (2 * x # 3 * x);
          (%o2)                         true



File: maxima.info,  Node: Assignment operators,  Next: User defined operators,  Prev: Operators for Equations,  Up: Operators

7.6 Assignment operators
========================

 -- Operator: :
     Assignment operator.

     When the left-hand side is a simple variable (not subscripted), `:'
     evaluates its right-hand side and associates that value with the
     left-hand side.

     When the left-hand side is a subscripted element of a list,
     matrix, declared Maxima array, or Lisp array, the right-hand side
     is assigned to that element.  The subscript must name an existing
     element; such objects cannot be extended by naming nonexistent
     elements.

     When the left-hand side is a subscripted element of an undeclared
     Maxima array, the right-hand side is assigned to that element, if
     it already exists, or a new element is allocated, if it does not
     already exist.

     When the left-hand side is a list of simple and/or subscripted
     variables, the right-hand side must evaluate to a list, and the
     elements of the right-hand side are assigned to the elements of
     the left-hand side, in parallel.

     See also `kill' and `remvalue', which undo the association between
     the left-hand side and its value.

     Examples:

     Assignment to a simple variable.

          (%i1) a;
          (%o1)                           a
          (%i2) a : 123;
          (%o2)                          123
          (%i3) a;
          (%o3)                          123

     Assignment to an element of a list.

          (%i1) b : [1, 2, 3];
          (%o1)                       [1, 2, 3]
          (%i2) b[3] : 456;
          (%o2)                          456
          (%i3) b;
          (%o3)                      [1, 2, 456]

     Assignment creates an undeclared array.

          (%i1) c[99] : 789;
          (%o1)                          789
          (%i2) c[99];
          (%o2)                          789
          (%i3) c;
          (%o3)                           c
          (%i4) arrayinfo (c);
          (%o4)                   [hashed, 1, [99]]
          (%i5) listarray (c);
          (%o5)                         [789]

     Multiple assignment.

          (%i1) [a, b, c] : [45, 67, 89];
          (%o1)                     [45, 67, 89]
          (%i2) a;
          (%o2)                          45
          (%i3) b;
          (%o3)                          67
          (%i4) c;
          (%o4)                          89

     Multiple assignment is carried out in parallel.  The values of `a'
     and `b' are exchanged in this example.

          (%i1) [a, b] : [33, 55];
          (%o1)                       [33, 55]
          (%i2) [a, b] : [b, a];
          (%o2)                       [55, 33]
          (%i3) a;
          (%o3)                          55
          (%i4) b;
          (%o4)                          33


 -- Operator: ::
     Assignment operator.

     `::' is the same as `:' (which see) except that `::' evaluates its
     left-hand side as well as its right-hand side.

     Examples:

          (%i1) x : 'foo;
          (%o1)                          foo
          (%i2) x :: 123;
          (%o2)                          123
          (%i3) foo;
          (%o3)                          123
          (%i4) x : '[a, b, c];
          (%o4)                       [a, b, c]
          (%i5) x :: [11, 22, 33];
          (%o5)                     [11, 22, 33]
          (%i6) a;
          (%o6)                          11
          (%i7) b;
          (%o7)                          22
          (%i8) c;
          (%o8)                          33


 -- Operator: ::=
     Macro function definition operator.  `::=' defines a function
     (called a "macro" for historical reasons) which quotes its
     arguments, and the expression which it returns (called the "macro
     expansion") is evaluated in the context from which the macro was
     called.  A macro function is otherwise the same as an ordinary
     function.

     `macroexpand' returns a macro expansion (without evaluating it).
     `macroexpand (foo (x))' followed by `''%' is equivalent to `foo
     (x)' when `foo' is a macro function.

     `::=' puts the name of the new macro function onto the global list
     `macros'.  `kill', `remove', and `remfunction' unbind macro
     function definitions and remove names from `macros'.

     `fundef' or `dispfun' return a macro function definition or assign
     it to a label, respectively.

     Macro functions commonly contain `buildq' and `splice' expressions
     to construct an expression, which is then evaluated.

     Examples

     A macro function quotes its arguments, so message (1) shows `y -
     z', not the value of `y - z'.  The macro expansion (the quoted
     expression `'(print ("(2) x is equal to", x))') is evaluated in
     the context from which the macro was called, printing message (2).

          (%i1) x: %pi$
          (%i2) y: 1234$
          (%i3) z: 1729 * w$
          (%i4) printq1 (x) ::= block (print ("(1) x is equal to", x),
                '(print ("(2) x is equal to", x)))$
          (%i5) printq1 (y - z);
          (1) x is equal to y - z
          (2) x is equal to %pi
          (%o5)                                 %pi

     An ordinary function evaluates its arguments, so message (1) shows
     the value of `y - z'.  The return value is not evaluated, so
     message (2) is not printed until the explicit evaluation `''%'.

          (%i1) x: %pi$
          (%i2) y: 1234$
          (%i3) z: 1729 * w$
          (%i4) printe1 (x) := block (print ("(1) x is equal to", x),
                '(print ("(2) x is equal to", x)))$
          (%i5) printe1 (y - z);
          (1) x is equal to 1234 - 1729 w
          (%o5)                     print((2) x is equal to, x)
          (%i6) ''%;
          (2) x is equal to %pi
          (%o6)                                 %pi

     `macroexpand' returns a macro expansion.  `macroexpand (foo (x))'
     followed by `''%' is equivalent to `foo (x)' when `foo' is a macro
     function.

          (%i1) x: %pi$
          (%i2) y: 1234$
          (%i3) z: 1729 * w$
          (%i4) g (x) ::= buildq ([x], print ("x is equal to", x))$
          (%i5) macroexpand (g (y - z));
          (%o5)                     print(x is equal to, y - z)
          (%i6) ''%;
          x is equal to 1234 - 1729 w
          (%o6)                            1234 - 1729 w
          (%i7) g (y - z);
          x is equal to 1234 - 1729 w
          (%o7)                            1234 - 1729 w


 -- Operator: :=
     The function definition operator.  `<f>(<x_1>, ..., <x_n>) :=
     <expr>' defines a function named <f> with arguments <x_1>, ...,
     <x_n> and function body <expr>.  `:=' never evaluates the function
     body (unless explicitly evaluated by quote-quote `''').  The
     function so defined may be an ordinary Maxima function (with
     arguments enclosed in parentheses) or an array function (with
     arguments enclosed in square brackets).

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

     All function definitions appear in the same namespace; defining a
     function `f' within another function `g' does not automatically
     limit the scope of `f' to `g'.  However, `local(f)' makes the
     definition of function `f' effective only within the block or
     other compound expression in which `local' appears.

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

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

     Examples:

     `:=' never evaluates the function body (unless explicitly
     evaluated by quote-quote).

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

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

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

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

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

     `local' makes a local function definition.

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



File: maxima.info,  Node: User defined operators,  Prev: Assignment operators,  Up: Operators

7.7 User defined operators
==========================

 -- Function: infix (<op>)
 -- Function: infix (<op>, <lbp>, <rbp>)
 -- Function: infix (<op>, <lbp>, <rbp>, <lpos>, <rpos>, <pos>)
     Declares <op> to be an infix operator.  An infix operator is a
     function of two arguments, with the name of the function written
     between the arguments.  For example, the subtraction operator `-'
     is an infix operator.

     `infix (<op>)' declares <op> to be an infix operator with default
     binding powers (left and right both equal to 180) and parts of
     speech (left and right both equal to `any').

     `infix (<op>, <lbp>, <rbp>)' declares <op> to be an infix operator
     with stated left and right binding powers and default parts of
     speech (left and right both equal to `any').

     `infix (<op>, <lbp>, <rbp>, <lpos>, <rpos>, <pos>)' declares <op>
     to be an infix operator with stated left and right binding powers
     and parts of speech <lpos>, <rpos>, and <pos> for the left
     operand, the right operand, and the operator result, respectively.

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

     The precedence of <op> with respect to other operators derives
     from the left and right binding powers of the operators in
     question.  If the left and right binding powers of <op> are both
     greater the left and right binding powers of some other operator,
     then <op> takes precedence over the other operator.  If the
     binding powers are not both greater or less, some more complicated
     relation holds.

     The associativity of <op> depends on its binding powers.  Greater
     left binding power (<lbp>) implies an instance of <op> is
     evaluated before other operators to its left in an expression,
     while greater right binding power (<rbp>) implies  an instance of
     <op> is evaluated before other operators to its right in an
     expression.  Thus greater <lbp> makes <op> right-associative,
     while greater <rbp> makes <op> left-associative.  If <lbp> is
     equal to <rbp>, <op> is left-associative.

     See also *note Introduction to operators::.

     Examples:

     If the left and right binding powers of <op> are both greater the
     left and right binding powers of some other operator, then <op>
     takes precedence over the other operator.

          (%i1) :lisp (get '$+ 'lbp)
          100
          (%i1) :lisp (get '$+ 'rbp)
          100
          (%i1) infix ("##", 101, 101);
          (%o1)                          ##
          (%i2) "##"(a, b) := sconcat("(", a, ",", b, ")");
          (%o2)       (a ## b) := sconcat("(", a, ",", b, ")")
          (%i3) 1 + a ## b + 2;
          (%o3)                       (a,b) + 3
          (%i4) infix ("##", 99, 99);
          (%o4)                          ##
          (%i5) 1 + a ## b + 2;
          (%o5)                       (a+1,b+2)

     Greater <lbp> makes <op> right-associative, while greater <rbp>
     makes <op> left-associative.

          (%i1) infix ("##", 100, 99);
          (%o1)                          ##
          (%i2) "##"(a, b) := sconcat("(", a, ",", b, ")")$
          (%i3) foo ## bar ## baz;
          (%o3)                    (foo,(bar,baz))
          (%i4) infix ("##", 100, 101);
          (%o4)                          ##
          (%i5) foo ## bar ## baz;
          (%o5)                    ((foo,bar),baz)

     Maxima can detect some syntax errors by comparing the declared
     part of speech to an actual expression.

          (%i1) infix ("##", 100, 99, expr, expr, expr);
          (%o1)                          ##
          (%i2) if x ## y then 1 else 0;
          Incorrect syntax: Found algebraic expression where logical
          expression expected
          if x ## y then
                       ^
          (%i2) infix ("##", 100, 99, expr, expr, clause);
          (%o2)                          ##
          (%i3) if x ## y then 1 else 0;
          (%o3)                if x ## y then 1 else 0


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

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

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

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

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

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

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

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

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

     Examples:

     Delimiters may be almost any strings.

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

     Matchfix operators are ordinary user-defined functions.

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

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


 -- Function: nary (<op>)
 -- Function: nary (<op>, <bp>, <arg_pos>, <pos>)
     An `nary' operator is used to denote a function of any number of
     arguments, each of which is separated by an occurrence of the
     operator, e.g.  A+B or A+B+C.  The `nary("x")' function is a
     syntax extension function to declare `x' to be an `nary' operator.
     Functions may be declared to be `nary'.  If `declare(j,nary);' is
     done, this tells the simplifier to simplify, e.g.
     `j(j(a,b),j(c,d))' to `j(a, b, c, d)'.

     See also *note Introduction to operators::.


 -- Function: nofix (<op>)
 -- Function: nofix (<op>, <pos>)
     `nofix' operators are used to denote functions of no arguments.
     The mere presence of such an operator in a command will cause the
     corresponding function to be evaluated.  For example, when one
     types "exit;" to exit from a Maxima break, "exit" is behaving
     similar to a `nofix' operator.  The function `nofix("x")' is a
     syntax extension function which declares `x' to be a `nofix'
     operator.

     See also *note Introduction to operators::.


 -- Function: postfix (<op>)
 -- Function: postfix (<op>, <lbp>, <lpos>, <pos>)
     `postfix' operators like the `prefix' variety denote functions of a
     single argument, but in this case the argument immediately
     precedes an occurrence of the operator in the input string, e.g.
     3!.  The `postfix("x")' function is a syntax extension function to
     declare `x' to be a `postfix' operator.

     See also *note Introduction to operators::.


 -- Function: prefix (<op>)
 -- Function: prefix (<op>, <rbp>, <rpos>, <pos>)
     A `prefix' operator is one which signifies a function of one
     argument, which argument immediately follows an occurrence of the
     operator.  `prefix("x")' is a syntax extension function to declare
     `x' to be a `prefix' operator.

     See also *note Introduction to operators::.



File: maxima.info,  Node: Evaluation,  Next: Simplification,  Prev: Operators,  Up: Top

8 Evaluation
************

* Menu:

* Functions and Variables for Evaluation::


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

8.1 Functions and Variables for Evaluation
==========================================

 -- Operator: '
     The single quote operator `'' prevents evaluation.

     Applied to a symbol, the single quote prevents evaluation of the
     symbol.

     Applied to a function call, the single quote prevents evaluation
     of the function call, although the arguments of the function are
     still evaluated (if evaluation is not otherwise prevented).  The
     result is the noun form of the function call.

     Applied to a parenthesized expression, the single quote prevents
     evaluation of all symbols and function calls in the expression.
     E.g., `'(f(x))' means do not evaluate the expression `f(x)'.
     `'f(x)' (with the single quote applied to `f' instead of `f(x)')
     means return the noun form of `f' applied to `[x]'.

     The single quote does not prevent simplification.

     When the global flag `noundisp' is `true', nouns display with a
     single quote.  This switch is always `true' when displaying
     function definitions.

     See also the quote-quote operator `''' and `nouns'.

     Examples:

     Applied to a symbol, the single quote prevents evaluation of the
     symbol.

          (%i1) aa: 1024;
          (%o1)                         1024
          (%i2) aa^2;
          (%o2)                        1048576
          (%i3) 'aa^2;
                                           2
          (%o3)                          aa
          (%i4) ''%;
          (%o4)                        1048576

     Applied to a function call, the single quote prevents evaluation
     of the function call.  The result is the noun form of the function
     call.

          (%i1) x0: 5;
          (%o1)                           5
          (%i2) x1: 7;
          (%o2)                           7
          (%i3) integrate (x^2, x, x0, x1);
                                         218
          (%o3)                          ---
                                          3
          (%i4) 'integrate (x^2, x, x0, x1);
                                       7
                                      /
                                      [   2
          (%o4)                       I  x  dx
                                      ]
                                      /
                                       5
          (%i5) %, nouns;
                                         218
          (%o5)                          ---
                                          3

     Applied to a parenthesized expression, the single quote prevents
     evaluation of all symbols and function calls in the expression.

          (%i1) aa: 1024;
          (%o1)                         1024
          (%i2) bb: 19;
          (%o2)                          19
          (%i3) sqrt(aa) + bb;
          (%o3)                          51
          (%i4) '(sqrt(aa) + bb);
          (%o4)                     bb + sqrt(aa)
          (%i5) ''%;
          (%o5)                          51

     The single quote does not prevent simplification.

          (%i1) sin (17 * %pi) + cos (17 * %pi);
          (%o1)                          - 1
          (%i2) '(sin (17 * %pi) + cos (17 * %pi));
          (%o2)                          - 1

     Maxima considers floating point operations by its in-built
     mathematical functions to be a simplification.

          (%i1) sin(1.0);
          (%o1)                          .8414709848078965
          (%i2) '(sin(1.0));
          (%o2)                          .8414709848078965

     When the global flag `noundisp' is `true', nouns display with a
     single quote.

          (%i1) x:%pi;
          (%o1)                                 %pi
          (%i2) bfloat(x);
          (%o2)                         3.141592653589793b0
          (%i3) sin(x);
          (%o3)                                  0
          (%i4) noundisp;
          (%o4)                                false
          (%i5) 'bfloat(x);
          (%o5)                             bfloat(%pi)
          (%i6) bfloat('x);
          (%o6)                                  x
          (%i7) 'sin(x);
          (%o7)                                  0
          (%i8) sin('x);
          (%o8)                               sin(x)
          (%i9) noundisp : not noundisp;
          (%o9)                                true
          (%i10) 'bfloat(x);
          (%o10)                           'bfloat(%pi)
          (%i11) bfloat('x);
          (%o11)                                 x
          (%i12) 'sin(x);
          (%o12)                                 0
          (%i13) sin('x);
          (%o13)                              sin(x)
          (%i14)


 -- Operator: "
     The quote-quote operator `''' (two single quote marks) modifies
     evaluation in input expressions.

     Applied to a general expression <expr>, quote-quote causes the
     value of <expr> to be substituted for <expr> in the input
     expression.

     Applied to the operator of an expression, quote-quote changes the
     operator from a noun to a verb (if it is not already a verb).

     The quote-quote operator is applied by the input parser; it is not
     stored as part of a parsed input expression.  The quote-quote
     operator is always applied as soon as it is parsed, and cannot be
     quoted.  Thus quote-quote causes evaluation when evaluation is
     otherwise suppressed, such as in function definitions, lambda
     expressions, and expressions quoted by single quote `''.

     Quote-quote is recognized by `batch' and `load'.

     See also the single-quote operator `'' and `nouns'.

     Examples:

     Applied to a general expression <expr>, quote-quote causes the
     value of <expr> to be substituted for <expr> in the input
     expression.

          (%i1) expand ((a + b)^3);
                               3        2      2      3
          (%o1)               b  + 3 a b  + 3 a  b + a
          (%i2) [_, ''_];
                                   3    3        2      2      3
          (%o2)     [expand((b + a) ), b  + 3 a b  + 3 a  b + a ]
          (%i3) [%i1, ''%i1];
                                   3    3        2      2      3
          (%o3)     [expand((b + a) ), b  + 3 a b  + 3 a  b + a ]
          (%i4) [aa : cc, bb : dd, cc : 17, dd : 29];
          (%o4)                   [cc, dd, 17, 29]
          (%i5) foo_1 (x) := aa - bb * x;
          (%o5)                 foo_1(x) := aa - bb x
          (%i6) foo_1 (10);
          (%o6)                      cc - 10 dd
          (%i7) ''%;
          (%o7)                         - 273
          (%i8) ''(foo_1 (10));
          (%o8)                         - 273
          (%i9) foo_2 (x) := ''aa - ''bb * x;
          (%o9)                 foo_2(x) := cc - dd x
          (%i10) foo_2 (10);
          (%o10)                        - 273
          (%i11) [x0 : x1, x1 : x2, x2 : x3];
          (%o11)                    [x1, x2, x3]
          (%i12) x0;
          (%o12)                         x1
          (%i13) ''x0;
          (%o13)                         x2
          (%i14) '' ''x0;
          (%o14)                         x3

     Applied to the operator of an expression, quote-quote changes the
     operator from a noun to a verb (if it is not already a verb).

          (%i1) declare (foo, noun);
          (%o1)                         done
          (%i2) foo (x) := x - 1729;
          (%o2)                 ''foo(x) := x - 1729
          (%i3) foo (100);
          (%o3)                       foo(100)
          (%i4) ''foo (100);
          (%o4)                        - 1629

     The quote-quote operator is applied by the input parser; it is not
     stored as part of a parsed input expression.

          (%i1) [aa : bb, cc : dd, bb : 1234, dd : 5678];
          (%o1)                 [bb, dd, 1234, 5678]
          (%i2) aa + cc;
          (%o2)                        dd + bb
          (%i3) display (_, op (_), args (_));
                                     _ = cc + aa

                                   op(cc + aa) = +

                              args(cc + aa) = [cc, aa]

          (%o3)                         done
          (%i4) ''(aa + cc);
          (%o4)                         6912
          (%i5) display (_, op (_), args (_));
                                     _ = dd + bb

                                   op(dd + bb) = +

                              args(dd + bb) = [dd, bb]

          (%o5)                         done

     Quote-quote causes evaluation when evaluation is otherwise
     suppressed, such as in function definitions, lambda expressions,
     and expressions quoted by single quote `''.

          (%i1) foo_1a (x) := ''(integrate (log (x), x));
          (%o1)               foo_1a(x) := x log(x) - x
          (%i2) foo_1b (x) := integrate (log (x), x);
          (%o2)           foo_1b(x) := integrate(log(x), x)
          (%i3) dispfun (foo_1a, foo_1b);
          (%t3)               foo_1a(x) := x log(x) - x

          (%t4)           foo_1b(x) := integrate(log(x), x)

          (%o4)                      [%t3, %t4]
          (%i5) integrate (log (x), x);
          (%o5)                     x log(x) - x
          (%i6) foo_2a (x) := ''%;
          (%o6)               foo_2a(x) := x log(x) - x
          (%i7) foo_2b (x) := %;
          (%o7)                    foo_2b(x) := %
          (%i8) dispfun (foo_2a, foo_2b);
          (%t8)               foo_2a(x) := x log(x) - x

          (%t9)                    foo_2b(x) := %

          (%o9)                      [%t7, %t8]
          (%i10) F : lambda ([u], diff (sin (u), u));
          (%o10)             lambda([u], diff(sin(u), u))
          (%i11) G : lambda ([u], ''(diff (sin (u), u)));
          (%o11)                  lambda([u], cos(u))
          (%i12) '(sum (a[k], k, 1, 3) + sum (b[k], k, 1, 3));
          (%o12)         sum(b , k, 1, 3) + sum(a , k, 1, 3)
                              k                  k
          (%i13) '(''(sum (a[k], k, 1, 3)) + ''(sum (b[k], k, 1, 3)));
          (%o13)             b  + a  + b  + a  + b  + a
                              3    3    2    2    1    1


 -- Function: ev (<expr>, <arg_1>, ..., <arg_n>)
     Evaluates the expression <expr> in the environment specified by the
     arguments <arg_1>, ..., <arg_n>.  The arguments are switches
     (Boolean flags), assignments, equations, and functions.  `ev'
     returns the result (another expression) of the evaluation.

     The evaluation is carried out in steps, as follows.

       1. First the environment is set up by scanning the arguments
          which may be any or all of the following.

             * `simp' causes <expr> to be simplified regardless of the
               setting of the switch `simp' which inhibits
               simplification if `false'.

             * `noeval' suppresses the evaluation phase of `ev' (see
               step (4) below).  This is useful in conjunction with the
               other switches and in causing <expr> to be resimplified
               without being reevaluated.

             * `nouns' causes the evaluation of noun forms (typically
               unevaluated functions such as `'integrate' or `'diff')
               in <expr>.

             * `expand' causes expansion.

             * `expand (<m>, <n>)' causes expansion, setting the values
               of `maxposex' and `maxnegex' to <m> and <n> respectively.

             * `detout' causes any matrix inverses computed in <expr>
               to have their determinant kept outside of the inverse
               rather than dividing through each element.

             * `diff' causes all differentiations indicated in <expr>
               to be performed.

             * `derivlist (<x>, <y>, <z>, ...)' causes only
               differentiations with respect to the indicated
               variables.  See also `derivlist'.

             * `risch' causes integrals in <expr> to be evaluated using
               the Risch algorithm.  See `risch'.  The standard
               integration routine is invoked when using the special
               symbol `nouns'.

             * `float' causes non-integral rational numbers to be
               converted to floating point.

             * `numer' causes some mathematical functions (including
               exponentiation) with numerical arguments to be evaluated
               in floating point.  It causes variables in <expr> which
               have been given numervals to be replaced by their
               values.  It also sets the `float' switch on.

             * `pred' causes predicates (expressions which evaluate to
               `true' or `false') to be evaluated.

             * `eval' causes an extra post-evaluation of <expr> to
               occur.  (See step (5) below.)  `eval' may occur multiple
               times.  For each instance of `eval', the expression is
               evaluated again.

             * `A' where `A' is an atom declared to be an evaluation
               flag `evflag' causes `A' to be bound to `true' during
               the evaluation of <expr>.

             * `V: expression' (or alternately `V=expression') causes
               `V' to be bound to the value of `expression' during the
               evaluation of <expr>.  Note that if `V' is a Maxima
               option, then `expression' is used for its value during
               the evaluation of <expr>.  If more than one argument to
               `ev' is of this type then the binding is done in
               parallel.  If `V' is a non-atomic expression then a
               substitution rather than a binding is performed.

             * `F' where `F', a function name, has been declared to be
               an evaluation function `evfun' causes `F' to be applied
               to <expr>.

             * Any other function names, e.g. `sum', cause evaluation
               of occurrences of those names in <expr> as though they
               were verbs.

             * In addition a function occurring in <expr> (say `F(x)')
               may be defined locally for the purpose of this
               evaluation of <expr> by giving `F(x) := expression' as
               an argument to `ev'.

             * If an atom not mentioned above or a subscripted variable
               or subscripted expression was given as an argument, it
               is evaluated and if the result is an equation or
               assignment then the indicated binding or substitution is
               performed.  If the result is a list then the members of
               the list are treated as if they were additional
               arguments given to `ev'.  This permits a list of
               equations to be given (e.g. `[X=1, Y=A**2]') or a list
               of names of equations (e.g., `[%t1, %t2]' where `%t1'
               and `%t2' are equations) such as that returned by
               `solve'.

          The arguments of `ev' may be given in any order with the
          exception of substitution equations which are handled in
          sequence, left to right, and evaluation functions which are
          composed, e.g., `ev (<expr>, ratsimp, realpart)' is handled
          as `realpart (ratsimp (<expr>))'.

          The `simp', `numer', and `float' switches may also be set
          locally in a block, or globally in Maxima so that they will
          remain in effect until being reset.

          If <expr> is a canonical rational expression (CRE), then the
          expression returned by `ev' is also a CRE, provided the
          `numer' and `float' switches are not both `true'.

       2. During step (1), a list is made of the non-subscripted
          variables appearing on the left side of equations in the
          arguments or in the value of some arguments if the value is
          an equation.  The variables (subscripted variables which do
          not have associated array functions as well as
          non-subscripted variables) in the expression <expr> are
          replaced by their global values, except for those appearing
          in this list.  Usually, <expr> is just a label or `%' (as in
          `%i2' in the example below), so this step simply retrieves
          the expression named by the label, so that `ev' may work on
          it.

       3. If any substitutions are indicated by the arguments, they are
          carried out now.

       4. The resulting expression is then re-evaluated (unless one of
          the arguments was `noeval') and simplified according to the
          arguments.  Note that any function calls in <expr> will be
          carried out after the variables in it are evaluated and that
          `ev(F(x))' thus may behave like `F(ev(x))'.

       5. For each instance of `eval' in the arguments, steps (3) and
          (4) are repeated.

     Examples:

          (%i1) sin(x) + cos(y) + (w+1)^2 + 'diff (sin(w), w);
                                               d                    2
          (%o1)              cos(y) + sin(x) + -- (sin(w)) + (w + 1)
                                               dw
          (%i2) ev (%, numer, expand, diff, x=2, y=1);
                                         2
          (%o2)                cos(w) + w  + 2 w + 2.449599732693821

     An alternate top level syntax has been provided for `ev', whereby
     one may just type in its arguments, without the `ev()'.  That is,
     one may write simply

          <expr>, <arg_1>, ..., <arg_n>

     This is not permitted as part of another expression, e.g., in
     functions, blocks, etc.

     Notice the parallel binding process in the following example.

          (%i3) programmode: false;
          (%o3)                                false
          (%i4) x+y, x: a+y, y: 2;
          (%o4)                              y + a + 2
          (%i5) 2*x - 3*y = 3$
          (%i6) -3*x + 2*y = -4$
          (%i7) solve ([%o5, %o6]);
          Solution

                                                    1
          (%t7)                               y = - -
                                                    5

                                                   6
          (%t8)                                x = -
                                                   5
          (%o8)                            [[%t7, %t8]]
          (%i8) %o6, %o8;
          (%o8)                              - 4 = - 4
          (%i9) x + 1/x > gamma (1/2);
                                             1
          (%o9)                          x + - > sqrt(%pi)
                                             x
          (%i10) %, numer, x=1/2;
          (%o10)                      2.5 > 1.772453850905516
          (%i11) %, pred;
          (%o11)                               true


 -- Special symbol: eval
     As an argument in a call to `ev (<expr>)', `eval' causes an extra
     evaluation of <expr>.  See `ev'.

     Example:

          (%i1) [a:b,b:c,c:d,d:e];
          (%o1)                            [b, c, d, e]
          (%i2) a;
          (%o2)                                  b
          (%i3) ev(a);
          (%o3)                                  c
          (%i4) ev(a),eval;
          (%o4)                                  e
          (%i5) a,eval,eval;
          (%o5)                                  e


 -- Property: evflag
     When a symbol <x> has the `evflag' property, the expressions
     `ev(<expr>, <x>)' and `<expr>, <x>' (at the interactive prompt)
     are equivalent to `ev(<expr>, <x> = true)'.  That is, <x> is bound
     to `true' while <expr> is evaluated.

     The expression `declare(<x>, evflag)' gives the `evflag' property
     to the variable <x>.

     The flags which have the `evflag' property by default are the
     following:

        algebraic          cauchysum       demoivre
        dotscrules         %emode          %enumer
        exponentialize     exptisolate     factorflag
        float              halfangles      infeval
        isolate_wrt_times  keepfloat       letrat
        listarith          logabs          logarc
        logexpand          lognegint
        m1pbranch          numer_pbranch   programmode
        radexpand          ratalgdenom     ratfac
        ratmx              ratsimpexpons   simp
        simpproduct        simpsum         sumexpand
        trigexpand

     Examples:

          (%i1) sin (1/2);
                                           1
          (%o1)                        sin(-)
                                           2
          (%i2) sin (1/2), float;
          (%o2)                   0.479425538604203
          (%i3) sin (1/2), float=true;
          (%o3)                   0.479425538604203
          (%i4) simp : false;
          (%o4)                         false
          (%i5) 1 + 1;
          (%o5)                         1 + 1
          (%i6) 1 + 1, simp;
          (%o6)                           2
          (%i7) simp : true;
          (%o7)                         true
          (%i8) sum (1/k^2, k, 1, inf);
                                      inf
                                      ====
                                      \     1
          (%o8)                        >    --
                                      /      2
                                      ====  k
                                      k = 1
          (%i9) sum (1/k^2, k, 1, inf), simpsum;
                                           2
                                        %pi
          (%o9)                         ----
                                         6
          (%i10) declare (aa, evflag);
          (%o10)                        done
          (%i11) if aa = true then YES else NO;
          (%o11)                         NO
          (%i12) if aa = true then YES else NO, aa;
          (%o12)                         YES


 -- Property: evfun
     When a function <F> has the `evfun' property, the expressions
     `ev(<expr>, <F>)' and `<expr>, <F>' (at the interactive prompt)
     are equivalent to `<F>(ev(<expr>))'.

     If two or more `evfun' functions <F>, <G>, etc., are specified,
     the functions are applied in the order that they are specified.

     The expression `declare(<F>, evfun)' gives the `evfun' property to
     the function <F>.  The functions which have the `evfun' property by
     default are the following:

        bfloat          factor       fullratsimp
        logcontract     polarform    radcan
        ratexpand       ratsimp      rectform
        rootscontract   trigexpand   trigreduce

     Examples:

          (%i1) x^3 - 1;
                                        3
          (%o1)                        x  - 1
          (%i2) x^3 - 1, factor;
                                          2
          (%o2)                 (x - 1) (x  + x + 1)
          (%i3) factor (x^3 - 1);
                                          2
          (%o3)                 (x - 1) (x  + x + 1)
          (%i4) cos(4 * x) / sin(x)^4;
                                      cos(4 x)
          (%o4)                       --------
                                         4
                                      sin (x)
          (%i5) cos(4 * x) / sin(x)^4, trigexpand;
                           4           2       2         4
                        sin (x) - 6 cos (x) sin (x) + cos (x)
          (%o5)         -------------------------------------
                                          4
                                       sin (x)
          (%i6) cos(4 * x) / sin(x)^4, trigexpand, ratexpand;
                                     2         4
                                6 cos (x)   cos (x)
          (%o6)               - --------- + ------- + 1
                                    2          4
                                 sin (x)    sin (x)
          (%i7) ratexpand (trigexpand (cos(4 * x) / sin(x)^4));
                                     2         4
                                6 cos (x)   cos (x)
          (%o7)               - --------- + ------- + 1
                                    2          4
                                 sin (x)    sin (x)
          (%i8) declare ([F, G], evfun);
          (%o8)                         done
          (%i9) (aa : bb, bb : cc, cc : dd);
          (%o9)                          dd
          (%i10) aa;
          (%o10)                         bb
          (%i11) aa, F;
          (%o11)                        F(cc)
          (%i12) F (aa);
          (%o12)                        F(bb)
          (%i13) F (ev (aa));
          (%o13)                        F(cc)
          (%i14) aa, F, G;
          (%o14)                      G(F(cc))
          (%i15) G (F (ev (aa)));
          (%o15)                      G(F(cc))


 -- Option variable: infeval
     Enables "infinite evaluation" mode.  `ev' repeatedly evaluates an
     expression until it stops changing.  To prevent a variable, say
     `X', from being evaluated away in this mode, simply include `X='X'
     as an argument to `ev'.  Of course expressions such as `ev (X,
     X=X+1, infeval)' will generate an infinite loop.


 -- Special symbol: noeval
     `noeval' suppresses the evaluation phase of `ev'.  This is useful
     in conjunction with other switches and in causing expressions to
     be resimplified without being reevaluated.


 -- Special symbol: nouns
     `nouns' is an `evflag'.  When used as an option to the `ev'
     command, `nouns' converts all "noun" forms occurring in the
     expression being `ev''d to "verbs", i.e., evaluates them.  See also
     `noun', `nounify', `verb', and `verbify'.


 -- Special symbol: pred
     As an argument in a call to `ev (<expr>)', `pred' causes
     predicates (expressions which evaluate to `true' or `false') to be
     evaluated.  See `ev'.

     Example:

          (%i1) 1<2;
          (%o1)                                1 < 2
          (%i2) 1<2,pred;
          (%o2)                                true



File: maxima.info,  Node: Simplification,  Next: Mathematical Functions,  Prev: Evaluation,  Up: Top

9 Simplification
****************

* Menu:

* Functions and Variables for Simplification::


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

9.1 Functions and Variables for Simplification
==============================================

 -- Property: additive
     If `declare(f,additive)' has been executed, then:

     (1) If `f' is univariate, whenever the simplifier encounters `f'
     applied to a sum, `f' will be distributed over that sum.  I.e.
     `f(y+x)' will simplify to `f(y)+f(x)'.

     (2) If `f' is a function of 2 or more arguments, additivity is
     defined as additivity in the first argument to `f', as in the case
     of `sum' or `integrate', i.e.  `f(h(x)+g(x),x)' will simplify to
     `f(h(x),x)+f(g(x),x)'.  This simplification does not occur when
     `f' is applied to expressions of the form
     `sum(x[i],i,lower-limit,upper-limit)'.

     Example:

          (%i1) F3 (a + b + c);
          (%o1)                     F3(c + b + a)
          (%i2) declare (F3, additive);
          (%o2)                         done
          (%i3) F3 (a + b + c);
          (%o3)                 F3(c) + F3(b) + F3(a)


 -- Property: antisymmetric
     If `declare(h,antisymmetric)' is done, this tells the simplifier
     that `h' is antisymmetric.  E.g.  `h(x,z,y)' will simplify to `-
     h(x, y, z)'.  That is, it will give (-1)^n times the result given
     by `symmetric' or `commutative', where n is the number of
     interchanges of two arguments necessary to convert it to that form.

     Examples:

          (%i1) S (b, a);
          (%o1)                        S(b, a)
          (%i2) declare (S, symmetric);
          (%o2)                         done
          (%i3) S (b, a);
          (%o3)                        S(a, b)
          (%i4) S (a, c, e, d, b);
          (%o4)                   S(a, b, c, d, e)
          (%i5) T (b, a);
          (%o5)                        T(b, a)
          (%i6) declare (T, antisymmetric);
          (%o6)                         done
          (%i7) T (b, a);
          (%o7)                       - T(a, b)
          (%i8) T (a, c, e, d, b);
          (%o8)                   T(a, b, c, d, e)


 -- Function: combine (<expr>)
     Simplifies the sum <expr> by combining terms with the same
     denominator into a single term.

     Example:

          (%i1) 1*f/2*b + 2*c/3*a + 3*f/4*b +c/5*b*a;
                                       5 b f   a b c   2 a c
          (%o1)                        ----- + ----- + -----
                                         4       5       3
          (%i2) combine (%);
                                   75 b f + 4 (3 a b c + 10 a c)
          (%o2)                    -----------------------------
                                                60


 -- Property: commutative
     If `declare(h, commutative)' is done, this tells the simplifier
     that `h' is a commutative function.  E.g.  `h(x, z, y)' will
     simplify to `h(x, y, z)'.  This is the same as `symmetric'.

     Exemplo:

          (%i1) S (b, a);
          (%o1)                               S(b, a)
          (%i2) S (a, b) + S (b, a);
          (%o2)                          S(b, a) + S(a, b)
          (%i3) declare (S, commutative);
          (%o3)                                done
          (%i4) S (b, a);
          (%o4)                               S(a, b)
          (%i5) S (a, b) + S (b, a);
          (%o5)                              2 S(a, b)
          (%i6) S (a, c, e, d, b);
          (%o6)                          S(a, b, c, d, e)


 -- Function: demoivre (<expr>)
 -- Option variable: demoivre
     The function `demoivre (expr)' converts one expression without
     setting the global variable `demoivre'.

     When the variable `demoivre' is `true', complex exponentials are
     converted into equivalent expressions in terms of circular
     functions: `exp (a + b*%i)' simplifies to `%e^a * (cos(b) +
     %i*sin(b))' if `b' is free of `%i'.  `a' and `b' are not expanded.

     The default value of `demoivre' is `false'.

     `exponentialize' converts circular and hyperbolic functions to
     exponential form.  `demoivre' and `exponentialize' cannot both be
     true at the same time.


 -- Function: distrib (<expr>)
     Distributes sums over products.  It differs from `expand' in that
     it works at only the top level of an expression, i.e., it doesn't
     recurse and it is faster than `expand'.  It differs from
     `multthru' in that it expands all sums at that level.

     Examples:

          (%i1) distrib ((a+b) * (c+d));
          (%o1)                 b d + a d + b c + a c
          (%i2) multthru ((a+b) * (c+d));
          (%o2)                 (b + a) d + (b + a) c
          (%i3) distrib (1/((a+b) * (c+d)));
                                          1
          (%o3)                    ---------------
                                   (b + a) (d + c)
          (%i4) expand (1/((a+b) * (c+d)), 1, 0);
                                          1
          (%o4)                 ---------------------
                                b d + a d + b c + a c


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

     `distribute_over' controls the mapping of functions over bags like
     lists, matrices, and equations.  At this time not all Maxima
     functions have this property.  It is possible to look up this
     property with the command `properties'.

     The mapping of functions is switched off, when setting
     `distribute_over' to the value `false'.

     Examples:

     The `sin' function maps over a list:

          (%i1) sin([x,1,1.0]);
          (%o1)                 [sin(x), sin(1), .8414709848078965]

     `mod' is a function with two arguments which maps over lists.
     Mapping over nested lists is possible too:

          (%i2) mod([x,11,2*a],10);
          (%o2)                    [mod(x, 10), 1, 2 mod(a, 5)]
          (%i3) mod([[x,y,z],11,2*a],10);
          (%o3)       [[mod(x, 10), mod(y, 10), mod(z, 10)], 1, 2 mod(a, 5)]

     Mapping of the `floor' function over a matrix and an equation:

          (%i4) floor(matrix([a,b],[c,d]));
                                      [ floor(a)  floor(b) ]
          (%o4)                       [                    ]
                                      [ floor(c)  floor(d) ]
          (%i5) floor(a=b);
          (%o5)                         floor(a) = floor(b)

     Functions with more than one argument map over any of the
     arguments or all arguments:

          (%i6) expintegral_e([1,2],[x,y]);
          (%o6) [[expintegral_e(1, x), expintegral_e(1, y)],
                 [expintegral_e(2, x), expintegral_e(2, y)]]

     Check if a function has the property distribute_over:

          (%i7) properties(abs);
          (%o7) [integral, distributes over bags, noun, rule, gradef]

     The mapping of functions is switched off, when setting
     `distribute_over' to the value `false'.

          (%i1) distribute_over;
          (%o1)                                true
          (%i2) sin([x,1,1.0]);
          (%o2)                [sin(x), sin(1), 0.8414709848078965]
          (%i3) distribute_over : not distribute_over;
          (%o3)                                false
          (%i4) sin([x,1,1.0]);
          (%o4)                          sin([x, 1, 1.0])
          (%i5)


 -- Option variable: domain
     Default value: `real'

     When `domain' is set to `complex', `sqrt (x^2)' will remain `sqrt
     (x^2)' instead of returning `abs(x)'.


 -- Property: evenfun
 -- Property: oddfun
     `declare(f, evenfun)' or `declare(f, oddfun)' tells Maxima to
     recognize the function `f' as an even or odd function.

     Examples:

          (%i1) o (- x) + o (x);
          (%o1)                     o(x) + o(- x)
          (%i2) declare (o, oddfun);
          (%o2)                         done
          (%i3) o (- x) + o (x);
          (%o3)                           0
          (%i4) e (- x) - e (x);
          (%o4)                     e(- x) - e(x)
          (%i5) declare (e, evenfun);
          (%o5)                         done
          (%i6) e (- x) - e (x);
          (%o6)                           0

 -- Function: expand (<expr>)
 -- Function: expand (<expr>, <p>, <n>)
     Expand expression <expr>.  Products of sums and exponentiated sums
     are multiplied out, numerators of rational expressions which are
     sums are split into their respective terms, and multiplication
     (commutative and non-commutative) are distributed over addition at
     all levels of <expr>.

     For polynomials one should usually use `ratexpand' which uses a
     more efficient algorithm.

     `maxnegex' and `maxposex' control the maximum negative and
     positive exponents, respectively, which will expand.

     `expand (<expr>, <p>, <n>)' expands <expr>, using <p> for
     `maxposex' and <n> for `maxnegex'.  This is useful in order to
     expand part but not all of an expression.

     `expon' - the exponent of the largest negative power which is
     automatically expanded (independent of calls to `expand').  For
     example if `expon' is 4 then `(x+1)^(-5)' will not be
     automatically expanded.

     `expop' - the highest positive exponent which is automatically
     expanded.  Thus `(x+1)^3', when typed, will be automatically
     expanded only if `expop' is greater than or equal to 3.  If it is
     desired to have `(x+1)^n' expanded where `n' is greater than
     `expop' then executing `expand ((x+1)^n)' will work only if
     `maxposex' is not less than `n'.

     `expand(expr, 0, 0)' causes a resimplification of `expr'.  `expr'
     is not reevaluated.  In distinction from `ev(expr, noeval)' a
     special representation (e. g. a CRE form) is removed.  See also
     `ev'.

     The `expand' flag used with `ev' causes expansion.

     The file `share/simplification/facexp.mac' contains several
     related functions (in particular `facsum', `factorfacsum' and
     `collectterms', which are autoloaded) and variables
     (`nextlayerfactor' and `facsum_combine') that provide the user with
     the ability to structure expressions by controlled expansion.
     Brief function descriptions are available in
     `simplification/facexp.usg'.  A demo is available by doing
     `demo("facexp")'.

     Examples:

          (%i1) expr:(x+1)^2*(y+1)^3;
                                         2        3
          (%o1)                   (x + 1)  (y + 1)
          (%i2) expand(expr);
                 2  3        3    3      2  2        2      2      2
          (%o2) x  y  + 2 x y  + y  + 3 x  y  + 6 x y  + 3 y  + 3 x  y
                                                                2
                                               + 6 x y + 3 y + x  + 2 x + 1
          (%i3) expand(expr,2);
                         2        3              3          3
          (%o3)         x  (y + 1)  + 2 x (y + 1)  + (y + 1)
          (%i4) expr:(x+1)^-2*(y+1)^3;
                                             3
                                      (y + 1)
          (%o4)                       --------
                                             2
                                      (x + 1)
          (%i5) expand(expr);
                      3               2
                     y             3 y            3 y             1
          (%o5) ------------ + ------------ + ------------ + ------------
                 2              2              2              2
                x  + 2 x + 1   x  + 2 x + 1   x  + 2 x + 1   x  + 2 x + 1
          (%i6) expand(expr,2,2);
                                             3
                                      (y + 1)
          (%o6)                     ------------
                                     2
                                    x  + 2 x + 1

     Resimplify an expression without expansion:

          (%i7) expr:(1+x)^2*sin(x);
                                                 2
          (%o7)                           (x + 1)  sin(x)
          (%i8) exponentialize:true;
          (%o8)                                true
          (%i9) expand(expr,0,0);
                                             2    %i x     - %i x
                                   %i (x + 1)  (%e     - %e      )
          (%o9)                  - -------------------------------
                                                  2


 -- Function: expandwrt (<expr>, <x_1>, ..., <x_n>)
     Expands expression `expr' with respect to the variables <x_1>,
     ..., <x_n>.  All products involving the variables appear
     explicitly.  The form returned will be free of products of sums of
     expressions that are not free of the variables.  <x_1>, ..., <x_n>
     may be variables, operators, or expressions.

     By default, denominators are not expanded, but this can be
     controlled by means of the switch `expandwrt_denom'.

     This function is autoloaded from `simplification/stopex.mac'.


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

     `expandwrt_denom' controls the treatment of rational expressions
     by `expandwrt'.  If `true', then both the numerator and
     denominator of the expression will be expanded according to the
     arguments of `expandwrt', but if `expandwrt_denom' is `false',
     then only the numerator will be expanded in that way.


 -- Function: expandwrt_factored (<expr>, <x_1>, ..., <x_n>)
     is similar to `expandwrt', but treats expressions that are products
     somewhat differently.  `expandwrt_factored' expands only on those
     factors of `expr' that contain the variables <x_1>, ..., <x_n>.

     This function is autoloaded from `simplification/stopex.mac'.


 -- Option variable: expon
     Default value: 0

     `expon' is the exponent of the largest negative power which is
     automatically expanded (independent of calls to `expand').  For
     example, if `expon' is 4 then `(x+1)^(-5)' will not be
     automatically expanded.


 -- Function: exponentialize (<expr>)
 -- Option variable: exponentialize
     The function `exponentialize (expr)' converts circular and
     hyperbolic functions in <expr> to exponentials, without setting
     the global variable `exponentialize'.

     When the variable `exponentialize' is `true', all circular and
     hyperbolic functions are converted to exponential form.  The
     default value is `false'.

     `demoivre' converts complex exponentials into circular functions.
     `exponentialize' and `demoivre' cannot both be true at the same
     time.


 -- Option variable: expop
     Default value: 0

     `expop' is the highest positive exponent which is automatically
     expanded.  Thus `(x + 1)^3', when typed, will be automatically
     expanded only if `expop' is greater than or equal to 3.  If it is
     desired to have `(x + 1)^n' expanded where `n' is greater than
     `expop' then executing `expand ((x + 1)^n)' will work only if
     `maxposex' is not less than n.


 -- Property: lassociative
     `declare (g, lassociative)' tells the Maxima simplifier that `g' is
     left-associative.  E.g., `g (g (a, b), g (c, d))' will simplify to
     `g (g (g (a, b), c), d)'.


 -- Property: linear
     One of Maxima's operator properties.  For univariate `f' so
     declared, "expansion" `f(x + y)' yields `f(x) + f(y)', `f(a*x)'
     yields `a*f(x)' takes place where `a' is a "constant".  For
     functions of two or more arguments, "linearity" is defined to be
     as in the case of `sum' or `integrate', i.e., `f (a*x + b, x)'
     yields `a*f(x,x) + b*f(1,x)' for `a' and `b' free of `x'.

     Example:

          (%i1) declare (f, linear);
          (%o1)                                done
          (%i2) f(x+y);
          (%o2)                             f(y) + f(x)
          (%i3) declare (a, constant);
          (%o3)                                done
          (%i4) f(a*x);
          (%o4)                               a f(x)

     `linear' is equivalent to `additive' and `outative'.  See also
     `opproperties'.

     Example:

          (%i1) 'sum (F(k) + G(k), k, 1, inf);
                                 inf
                                 ====
                                 \
          (%o1)                   >    (G(k) + F(k))
                                 /
                                 ====
                                 k = 1
          (%i2) declare (nounify (sum), linear);
          (%o2)                         done
          (%i3) 'sum (F(k) + G(k), k, 1, inf);
                               inf          inf
                               ====         ====
                               \            \
          (%o3)                 >    G(k) +  >    F(k)
                               /            /
                               ====         ====
                               k = 1        k = 1


 -- Option variable: maxnegex
     Default value: 1000

     `maxnegex' is the largest negative exponent which will be expanded
     by the `expand' command (see also `maxposex').


 -- Option variable: maxposex
     Default value: 1000

     `maxposex' is the largest exponent which will be expanded with the
     `expand' command (see also `maxnegex').


 -- Property: multiplicative
     `declare(f, multiplicative)' tells the Maxima simplifier that `f'
     is multiplicative.

       1. If `f' is univariate, whenever the simplifier encounters `f'
          applied to a product, `f' distributes over that product.
          E.g., `f(x*y)' simplifies to `f(x)*f(y)'.

       2. If `f' is a function of 2 or more arguments, multiplicativity
          is defined as multiplicativity in the first argument to `f',
          e.g., `f (g(x) * h(x), x)' simplifies to `f (g(x) ,x) * f
          (h(x), x)'.

     This simplification does not occur when `f' is applied to
     expressions of the form `product (x[i], i, m, n)'.

     Example:

          (%i1) F2 (a * b * c);
          (%o1)                       F2(a b c)
          (%i2) declare (F2, multiplicative);
          (%o2)                         done
          (%i3) F2 (a * b * c);
          (%o3)                   F2(a) F2(b) F2(c)


 -- Function: multthru (<expr>)
 -- Function: multthru (<expr_1>, <expr_2>)
     Multiplies a factor (which should be a sum) of <expr> by the other
     factors of <expr>.  That is, <expr> is `<f_1> <f_2> ... <f_n>'
     where at least one factor, say <f_i>, is a sum of terms.  Each
     term in that sum is multiplied by the other factors in the
     product.  (Namely all the factors except <f_i>).  `multthru' does
     not expand exponentiated sums.  This function is the fastest way
     to distribute products (commutative or noncommutative) over sums.
     Since quotients are represented as products `multthru' can be used
     to divide sums by products as well.

     `multthru (<expr_1>, <expr_2>)' multiplies each term in <expr_2>
     (which should be a sum or an equation) by <expr_1>.  If <expr_1>
     is not itself a sum then this form is equivalent to `multthru
     (<expr_1>*<expr_2>)'.

          (%i1) x/(x-y)^2 - 1/(x-y) - f(x)/(x-y)^3;
                                1        x         f(x)
          (%o1)             - ----- + -------- - --------
                              x - y          2          3
                                      (x - y)    (x - y)
          (%i2) multthru ((x-y)^3, %);
                                     2
          (%o2)             - (x - y)  + x (x - y) - f(x)
          (%i3) ratexpand (%);
                                     2
          (%o3)                   - y  + x y - f(x)
          (%i4) ((a+b)^10*s^2 + 2*a*b*s + (a*b)^2)/(a*b*s^2);
                                  10  2              2  2
                           (b + a)   s  + 2 a b s + a  b
          (%o4)            ------------------------------
                                            2
                                       a b s
          (%i5) multthru (%);  /* note that this does not expand (b+a)^10 */
                                                  10
                                 2   a b   (b + a)
          (%o5)                  - + --- + ---------
                                 s    2       a b
                                     s
          (%i6) multthru (a.(b+c.(d+e)+f));
          (%o6)            a . f + a . c . (e + d) + a . b
          (%i7) expand (a.(b+c.(d+e)+f));
          (%o7)         a . f + a . c . e + a . c . d + a . b


 -- Property: nary
     `declare(f, nary)' tells Maxima to recognize the function `f' as an
     n-ary function.

     The `nary' declaration is not the same as calling the `nary'
     function.  The sole effect of `declare(f, nary)' is to instruct
     the Maxima simplifier to flatten nested expressions, for example,
     to simplify `foo(x, foo(y, z))' to `foo(x, y, z)'.  See also
     `declare'.

     Example:

          (%i1) H (H (a, b), H (c, H (d, e)));
          (%o1)               H(H(a, b), H(c, H(d, e)))
          (%i2) declare (H, nary);
          (%o2)                         done
          (%i3) H (H (a, b), H (c, H (d, e)));
          (%o3)                   H(a, b, c, d, e)

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

     When `negdistrib' is `true', -1 distributes over an expression.
     E.g., `-(x + y)' becomes `- y - x'.  Setting it to `false' will
     allow `- (x + y)' to be displayed like that.  This is sometimes
     useful but be very careful: like the `simp' flag, this is one flag
     you do not want to set to `false' as a matter of course or
     necessarily for other than local use in your Maxima.

     Example:

          (%i1) negdistrib;
          (%o1)                                true
          (%i2) -(x+y);
          (%o2)                               - y - x
          (%i3) negdistrib : not negdistrib ;
          (%o3)                                false
          (%i4) -(x+y);
          (%o4)                              - (y + x)


 -- System variable: opproperties
     `opproperties' is the list of the special operator properties
     recognized by the Maxima simplifier:

     Example:

          (%i1) opproperties;
          (%o1) [linear, additive, multiplicative, outative, evenfun, oddfun,.
                 commutative, symmetric, antisymmetric, nary, lassociative, rassociative]


 -- Property: outative
     `declare(f, outative)' tells the Maxima simplifier that constant
     factors in the argument of `f' can be pulled out.

       1. If `f' is univariate, whenever the simplifier encounters `f'
          applied to a product, that product will be partitioned into
          factors that are constant and factors that are not and the
          constant factors will be pulled out.  E.g., `f(a*x)' will
          simplify to `a*f(x)' where `a' is a constant.  Non-atomic
          constant factors will not be pulled out.

       2. If `f' is a function of 2 or more arguments, outativity is
          defined as in the case of `sum' or `integrate', i.e., `f
          (a*g(x), x)' will simplify to `a * f(g(x), x)' for `a' free
          of `x'.

     `sum', `integrate', and `limit' are all `outative'.

     Example:

          (%i1) F1 (100 * x);
          (%o1)                       F1(100 x)
          (%i2) declare (F1, outative);
          (%o2)                         done
          (%i3) F1 (100 * x);
          (%o3)                       100 F1(x)
          (%i4) declare (zz, constant);
          (%o4)                         done
          (%i5) F1 (zz * y);
          (%o5)                       zz F1(y)


 -- Function: radcan (<expr>)
     Simplifies <expr>, which can contain logs, exponentials, and
     radicals, by converting it into a form which is canonical over a
     large class of expressions and a given ordering of variables; that
     is, all functionally equivalent forms are mapped into a unique
     form.  For a somewhat larger class of expressions, `radcan'
     produces a regular form.  Two equivalent expressions in this class
     do not necessarily have the same appearance, but their difference
     can be simplified by `radcan' to zero.

     For some expressions `radcan' is quite time consuming.  This is
     the cost of exploring certain relationships among the components
     of the expression for simplifications based on factoring and
     partial-fraction expansions of exponents.

     Examples:

          (%i1) radcan((log(x+x^2)-log(x))^a/log(1+x)^(a/2));
                                                     a/2
          (%o1)                            log(x + 1)

          (%i2) radcan((log(1+2*a^x+a^(2*x))/log(1+a^x)));
          (%o2)                                  2

          (%i3) radcan((%e^x-1)/(1+%e^(x/2)));
                                               x/2
          (%o3)                              %e    - 1


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

     `radexpand' controls some simplifications of radicals.

     When `radexpand' is `all', causes nth roots of factors of a product
     which are powers of n to be pulled outside of the radical.  E.g. if
     `radexpand' is `all', `sqrt (16*x^2)' simplifies to `4*x'.

     More particularly, consider `sqrt (x^2)'.
        * If `radexpand' is `all' or `assume (x > 0)' has been executed,
          `sqrt(x^2)' simplifies to `x'.

        * If `radexpand' is `true' and `domain' is `real' (its
          default), `sqrt(x^2)' simplifies to `abs(x)'.

        * If `radexpand' is `false', or `radexpand' is `true' and
          `domain' is `complex', `sqrt(x^2)' is not simplified.

     Note that `domain' only matters when `radexpand' is `true'.


 -- Property: rassociative
     `declare (g, rassociative)' tells the Maxima simplifier that `g'
     is right-associative.  E.g., `g(g(a, b), g(c, d))' simplifies to
     `g(a, g(b, g(c, d)))'.


 -- Function: scsimp (<expr>, <rule_1>, ..., <rule_n>)
     Sequential Comparative Simplification (method due to Stoute).
     `scsimp' attempts to simplify <expr> according to the rules
     <rule_1>, ..., <rule_n>.  If a smaller expression is obtained, the
     process repeats.  Otherwise after all simplifications are tried,
     it returns the original answer.

     `example (scsimp)' displays some examples.


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

     `simp' enables simplification.  This is the standard.  `simp' is
     also an `evflag', which is recognized by the function `ev'.  See
     `ev'.

     When `simp' is used as an `evflag' with a value `false', the
     simplification is suppressed only during the evaluation phase of
     an expression.  The flag can not suppress the simplification which
     follows the evaluation phase.

     Examples:

     The simplification is switched off globally.  The expression
     `sin(1.0)' is not simplified to its numerical value.  The
     `simp'-flag switches the simplification on.

          (%i1) simp:false;
          (%o1)                                false
          (%i2) sin(1.0);
          (%o2)                              sin(1.0)
          (%i3) sin(1.0),simp;
          (%o3)                          .8414709848078965

     The simplification is switched on again.  The `simp'-flag cannot
     suppress the simplification completely.  The output shows a
     simplified expression, but the variable `x' has an unsimplified
     expression as a value, because the assignment has occurred during
     the evaluation phase of the expression.

          (%i4) simp:true;
          (%o4)                                true
          (%i5) x:sin(1.0),simp:false;
          (%o5)                          .8414709848078965
          (%i6) :lisp $X
          ((%SIN) 1.0)


 -- Property: symmetric
     `declare (h, symmetric)' tells the Maxima simplifier that `h' is a
     symmetric function.  E.g., `h (x, z, y)' simplifies to `h (x, y,
     z)'.

     `commutative' is synonymous with `symmetric'.


 -- Function: xthru (<expr>)
     Combines all terms of <expr> (which should be a sum) over a common
     denominator without expanding products and exponentiated sums as
     `ratsimp' does.  `xthru' cancels common factors in the numerator
     and denominator of rational expressions but only if the factors
     are explicit.

     Sometimes it is better to use `xthru' before `ratsimp'ing an
     expression in order to cause explicit factors of the gcd of the
     numerator and denominator to be canceled thus simplifying the
     expression to be `ratsimp'ed.

     Examples:

          (%i1) ((x+2)^20 - 2*y)/(x+y)^20 + (x+y)^(-19) - x/(x+y)^20;
                                          20
                           1       (x + 2)   - 2 y       x
          (%o1)        --------- + --------------- - ---------
                              19             20             20
                       (y + x)        (y + x)        (y + x)
          (%i2) xthru (%);
                                           20
                                    (x + 2)   - y
          (%o2)                     -------------
                                             20
                                      (y + x)



File: maxima.info,  Node: Mathematical Functions,  Next: Maximas Database,  Prev: Simplification,  Up: Top

10 Mathematical Functions
*************************

* Menu:

* Functions for Numbers::
* Functions for Complex Numbers::
* Combinatorial Functions::
* Root Exponential and Logarithmic Functions::
* Trigonometric Functions::
* Random Numbers::


File: maxima.info,  Node: Functions for Numbers,  Next: Functions for Complex Numbers,  Prev: Mathematical Functions,  Up: Mathematical Functions

10.1 Functions for Numbers
==========================

 -- Function: abs (<z>)
     The `abs' function represents the mathematical absolute value
     function and works for both numerical and symbolic values. If the
     argument, <z>, is a real or complex number, `abs' returns the
     absolute value of <z>. If possible, symbolic expressions using the
     absolute value function are also simplified.

     Maxima can differentiate, integrate and calculate limits for
     expressions containing `abs'. The `abs_integrate' package further
     extends Maxima's ability to calculate integrals involving the abs
     function. See (%i12) in the examples below.

     When applied to a list or matrix, `abs' automatically distributes
     over the terms. Similarly, it distributes over both sides of an
     equation. To alter this behaviour, see the variable
     `distribute_over'.

     Examples:

     Calculation of `abs' for real and complex numbers, including
     numerical constants and various infinities. The first example
     shows how `abs' distributes over the elements of a list.

          (%i1) abs([-4, 0, 1, 1+%i]);
          (%o1)                  [4, 0, 1, sqrt(2)]

          (%i2) abs((1+%i)*(1-%i));
          (%o2)                           2
          (%i3) abs(%e+%i);
                                          2
          (%o3)                    sqrt(%e  + 1)
          (%i4) abs([inf, infinity, minf]);
          (%o4)                   [inf, inf, inf]

     Simplification of expressions containing `abs':

          (%i5) abs(x^2);
                                          2
          (%o5)                          x
          (%i6) abs(x^3);
                                       2
          (%o6)                       x  abs(x)

          (%i7) abs(abs(x));
          (%o7)                       abs(x)
          (%i8) abs(conjugate(x));
          (%o8)                       abs(x)

     Integrating and differentiating with the `abs' function. Note that
     more integrals involving the `abs' function can be performed, if
     the `abs_integrate' package is loaded. The last example shows the
     Laplace transform of `abs': see `laplace'.

          (%i9) diff(x*abs(x),x),expand;
          (%o9)                       2 abs(x)

          (%i10) integrate(abs(x),x);
                                       x abs(x)
          (%o10)                       --------
                                          2

          (%i11) integrate(x*abs(x),x);
                                     /
                                     [
          (%o11)                     I x abs(x) dx
                                     ]
                                     /

          (%i12) load(abs_integrate)$
          (%i13) integrate(x*abs(x),x);
                                2           3
                               x  abs(x)   x  signum(x)
          (%o13)               --------- - ------------
                                   2            6

          (%i14) integrate(abs(x),x,-2,%pi);
                                         2
                                      %pi
          (%o14)                      ---- + 2
                                       2

          (%i15) laplace(abs(x),x,s);
                                         1
          (%o15)                         --
                                          2
                                         s


 -- Function: ceiling (<x>)
     When <x> is a real number, return the least integer that is
     greater than or equal to <x>.

     If <x> is a constant expression (`10 * %pi', for example),
     `ceiling' evaluates <x> using big floating point numbers, and
     applies `ceiling' to the resulting big float.  Because `ceiling'
     uses floating point evaluation, it's possible, although unlikely,
     that `ceiling' could return an erroneous value for constant
     inputs.  To guard against errors, the floating point evaluation is
     done using three values for `fpprec'.

     For non-constant inputs, `ceiling' tries to return a simplified
     value.  Here are examples of the simplifications that `ceiling'
     knows about:

          (%i1) ceiling (ceiling (x));
          (%o1)                      ceiling(x)
          (%i2) ceiling (floor (x));
          (%o2)                       floor(x)
          (%i3) declare (n, integer)$
          (%i4) [ceiling (n), ceiling (abs (n)), ceiling (max (n, 6))];
          (%o4)                [n, abs(n), max(n, 6)]
          (%i5) assume (x > 0, x < 1)$
          (%i6) ceiling (x);
          (%o6)                           1
          (%i7) tex (ceiling (a));
          $$\left \lceil a \right \rceil$$
          (%o7)                         false

     The `ceiling' function distributes over lists, matrices and
     equations.  See `distribute_over'.

     Finally, for all inputs that are manifestly complex, `ceiling'
     returns a noun form.

     If the range of a function is a subset of the integers, it can be
     declared to be `integervalued'.  Both the `ceiling' and `floor'
     functions can use this information; for example:

          (%i1) declare (f, integervalued)$
          (%i2) floor (f(x));
          (%o2)                         f(x)
          (%i3) ceiling (f(x) - 1);
          (%o3)                       f(x) - 1

     Example use:

          (%i1) unitfrac(r) := block([uf : [], q],
              if not(ratnump(r)) then
                 error("unitfrac: argument must be a rational number"),
              while r # 0 do (
                  uf : cons(q : 1/ceiling(1/r), uf),
                  r : r - q),
              reverse(uf))$
          (%i2) unitfrac (9/10);
                                      1  1  1
          (%o2)                      [-, -, --]
                                      2  3  15
          (%i3) apply ("+", %);
                                         9
          (%o3)                          --
                                         10
          (%i4) unitfrac (-9/10);
                                            1
          (%o4)                       [- 1, --]
                                            10
          (%i5) apply ("+", %);
                                          9
          (%o5)                         - --
                                          10
          (%i6) unitfrac (36/37);
                                  1  1  1  1    1
          (%o6)                  [-, -, -, --, ----]
                                  2  3  8  69  6808
          (%i7) apply ("+", %);
                                         36
          (%o7)                          --
                                         37


 -- Function: entier (<x>)
     Returns the largest integer less than or equal to <x> where <x> is
     numeric.  `fix' (as in `fixnum') is a synonym for this, so
     `fix(<x>)' is precisely the same.


 -- Function: floor (<x>)
     When <x> is a real number, return the largest integer that is less
     than or equal to <x>.

     If <x> is a constant expression (`10 * %pi', for example), `floor'
     evaluates <x> using big floating point numbers, and applies
     `floor' to the resulting big float. Because `floor' uses floating
     point evaluation, it's possible, although unlikely, that `floor'
     could return an erroneous value for constant inputs.  To guard
     against errors, the floating point evaluation is done using three
     values for `fpprec'.

     For non-constant inputs, `floor' tries to return a simplified
     value.  Here are examples of the simplifications that `floor'
     knows about:

          (%i1) floor (ceiling (x));
          (%o1)                      ceiling(x)
          (%i2) floor (floor (x));
          (%o2)                       floor(x)
          (%i3) declare (n, integer)$
          (%i4) [floor (n), floor (abs (n)), floor (min (n, 6))];
          (%o4)                [n, abs(n), min(n, 6)]
          (%i5) assume (x > 0, x < 1)$
          (%i6) floor (x);
          (%o6)                           0
          (%i7) tex (floor (a));
          $$\left \lfloor a \right \rfloor$$
          (%o7)                         false

     The `floor' function distributes over lists, matrices and
     equations.  See `distribute_over'.

     Finally, for all inputs that are manifestly complex, `floor'
     returns a noun form.

     If the range of a function is a subset of the integers, it can be
     declared to be `integervalued'.  Both the `ceiling' and `floor'
     functions can use this information; for example:

          (%i1) declare (f, integervalued)$
          (%i2) floor (f(x));
          (%o2)                         f(x)
          (%i3) ceiling (f(x) - 1);
          (%o3)                       f(x) - 1


 -- Function: fix (<x>)
     A synonym for `entier (<x>)'.


 -- Function: lmax (<L>)
     When <L> is a list or a set, return `apply ('max, args (<L>))'.
     When <L> is not a list or a set, signal an error.  See also `lmin'
     and `max'.


 -- Function: lmin (<L>)
     When <L> is a list or a set, return `apply ('min, args (<L>))'.
     When <L> is not a list or a set, signal an error.  See also `lmax'
     and `min'.


 -- Function: max (<x_1>, ..., <x_n>)
     Return a simplified value for the maximum of the expressions <x_1>
     through <x_n>.  When `get (trylevel, maxmin)', is 2 or greater,
     `max' uses the simplification `max (e, -e) --> |e|'.  When `get
     (trylevel, maxmin)' is 3 or greater, <max> tries to eliminate
     expressions that are between two other arguments; for example,
     `max (x, 2*x, 3*x) --> max (x, 3*x)'.  To set the value of
     `trylevel' to 2, use `put (trylevel, 2, maxmin)'.

     See also `min' and `lmax'.


 -- Function: min (<x_1>, ..., <x_n>)
     Return a simplified value for the minimum of the expressions `x_1'
     through `x_n'.  When `get (trylevel, maxmin)', is 2 or greater,
     `min' uses the simplification `min (e, -e) --> -|e|'.  When `get
     (trylevel, maxmin)' is 3 or greater, `min' tries to eliminate
     expressions that are between two other arguments; for example,
     `min (x, 2*x, 3*x) --> min (x, 3*x)'.  To set the value of
     `trylevel' to 2, use `put (trylevel, 2, maxmin)'.

     See also `max' and `lmin'.


 -- Function: round (<x>)
     When <x> is a real number, returns the closest integer to <x>.
     Multiples of 1/2 are rounded to the nearest even integer.
     Evaluation of <x> is similar to `floor' and `ceiling'.

     The `round' function distributes over lists, matrices and
     equations.  See `distribute_over'.


 -- Function: signum (<x>)
     For either real or complex numbers <x>, the signum function returns
     0 if <x> is zero; for a nonzero numeric input <x>, the signum
     function returns `x/abs(x)'.

     For non-numeric inputs, Maxima attempts to determine the sign of
     the input.  When the sign is negative, zero, or positive, `signum'
     returns -1,0, 1, respectively.  For all other values for the sign,
     `signum' a simplified but equivalent form.  The simplifications
     include reflection (`signum(-x)' gives `-signum(x)') and
     multiplicative identity (`signum(x*y)' gives `signum(x) *
     signum(y)').

     The `signum' function distributes over a list, a matrix, or an
     equation.  See `distribute_over'.


 -- Function: truncate (<x>)
     When <x> is a real number, return the closest integer to <x> not
     greater in absolute value than <x>.  Evaluation of <x> is similar
     to `floor' and `ceiling'.

     The `truncate' function distributes over lists, matrices and
     equations.  See `distribute_over'.



File: maxima.info,  Node: Functions for Complex Numbers,  Next: Combinatorial Functions,  Prev: Functions for Numbers,  Up: Mathematical Functions

10.2 Functions for Complex Numbers
==================================

 -- Function: cabs (<expr>)
     Calculates the absolute value of an expression representing a
     complex number.  Unlike the function `abs', the `cabs' function
     always decomposes its argument into a real and an imaginary part.
     If `x' and `y' represent real variables or expressions, the `cabs'
     function calculates the absolute value of `x + %i*y' as
                                     2    2
                               sqrt(y  + x )

     The `cabs' function can use known properties like symmetry
     properties of complex functions to help it calculate the absolute
     value of an expression.  If such identities exist, they can be
     advertised to `cabs' using function properties.  The symmetries
     that `cabs' understands are: mirror symmetry, conjugate function
     and complex characteristic.

     `cabs' is a verb function and is not suitable for symbolic
     calculations.  For such calculations (including integration,
     differentiation and taking limits of expressions containing
     absolute values), use `abs'.

     The result of `cabs' can include the absolute value function,
     `abs', and the arc tangent, `atan2'.

     When applied to a list or matrix, `cabs' automatically distributes
     over the terms.  Similarly, it distributes over both sides of an
     equation.

     For further ways to compute with complex numbers, see the functions
     `rectform', `realpart', `imagpart', `carg', `conjugate' and
     `polarform'.

     Examples:

     Examples with `sqrt' and `sin'.

          (%i1) cabs(sqrt(1+%i*x));
                                       2     1/4
          (%o1)                      (x  + 1)
          (%i2) cabs(sin(x+%i*y));
                              2        2         2        2
          (%o2)       sqrt(cos (x) sinh (y) + sin (x) cosh (y))

     The error function, `erf', has mirror symmetry, which is used here
     in the calculation of the absolute value with a complex argument:

          (%i3) cabs(erf(x+%i*y));
                                                    2
                     (erf(%i y + x) - erf(%i y - x))
          (%o3) sqrt(--------------------------------
                                    4
                                                                         2
                                          (erf(%i y + x) + erf(%i y - x))
                                        - --------------------------------)
                                                         4

     Maxima knows complex identities for the Bessel functions, which
     allow it to compute the absolute value for complex arguments.
     Here is an example for `bessel_j'.

          (%i4) cabs(bessel_j(1,%i));
          (%o4)                 abs(bessel_j(1, %i))


 -- Function: carg (<z>)
     Returns the complex argument of <z>.  The complex argument is an
     angle `theta' in `(-%pi, %pi]' such that `r exp (theta %i) = <z>'
     where `r' is the magnitude of <z>.

     `carg' is a computational function, not a simplifying function.

     See also `abs' (complex magnitude), `polarform', `rectform',
     `realpart', and `imagpart'.

     Examples:

          (%i1) carg (1);
          (%o1)                           0
          (%i2) carg (1 + %i);
                                         %pi
          (%o2)                          ---
                                          4
          (%i3) carg (exp (%i));
          (%o3)                           1
          (%i4) carg (exp (%pi * %i));
          (%o4)                          %pi
          (%i5) carg (exp (3/2 * %pi * %i));
                                          %pi
          (%o5)                         - ---
                                           2
          (%i6) carg (17 * exp (2 * %i));
          (%o6)                           2


 -- Function: conjugate (<x>)
     Returns the complex conjugate of <x>.

          (%i1) declare ([aa, bb], real, cc, complex, ii, imaginary);

          (%o1)                         done
          (%i2) conjugate (aa + bb*%i);

          (%o2)                      aa - %i bb
          (%i3) conjugate (cc);

          (%o3)                     conjugate(cc)
          (%i4) conjugate (ii);

          (%o4)                         - ii
          (%i5) conjugate (xx + yy);

          (%o5)             conjugate(yy) + conjugate(xx)


 -- Function: imagpart (<expr>)
     Returns the imaginary part of the expression <expr>.

     `imagpart' is a computational function, not a simplifying function.

     See also `abs', `carg', `polarform', `rectform', and `realpart'.

     Example:

          (%i1) imagpart (a+b*%i);
          (%o1)                                  b
          (%i2) imagpart (1+sqrt(2)*%i);
          (%o2)                               sqrt(2)
          (%i3) imagpart (1);
          (%o3)                                  0
          (%i4) imagpart (sqrt(2)*%i);
          (%o4)                               sqrt(2)


 -- Function: polarform (<expr>)
     Returns an expression `r %e^(%i theta)' equivalent to <expr>, such
     that `r' and `theta' are purely real.

     Example:

          (%i1) polarform(a+b*%i);
                                        2    2    %i atan2(b, a)
          (%o1)                   sqrt(b  + a ) %e
          (%i2) polarform(1+%i);
                                                   %i %pi
                                                   ------
                                                     4
          (%o2)                          sqrt(2) %e
          (%i3) polarform(1+2*%i);
                                                 %i atan(2)
          (%o3)                        sqrt(5) %e


 -- Function: realpart (<expr>)
     Returns the real part of <expr>.  `realpart' and `imagpart' will
     work on expressions involving trigonometric and hyperbolic
     functions, as well as square root, logarithm, and exponentiation.

     Example:

          (%i1) realpart (a+b*%i);
          (%o1)                                  a
          (%i2) realpart (1+sqrt(2)*%i);
          (%o2)                                  1
          (%i3) realpart (sqrt(2)*%i);
          (%o3)                                  0
          (%i4) realpart (1);
          (%o4)                                  1


 -- Function: rectform (<expr>)
     Returns an expression `a + b %i' equivalent to <expr>, such that
     <a> and <b> are purely real.

     Example:

          (%i1) rectform(sqrt(2)*%e^(%i*%pi/4));
          (%o1)                               %i + 1
          (%i2) rectform(sqrt(b^2+a^2)*%e^(%i*atan2(b, a)));
          (%o2)                              %i b + a
          (%i3) rectform(sqrt(5)*%e^(%i*atan(2)));
          (%o3)                              2 %i + 1



File: maxima.info,  Node: Combinatorial Functions,  Next: Root Exponential and Logarithmic Functions,  Prev: Functions for Complex Numbers,  Up: Mathematical Functions

10.3 Combinatorial Functions
============================

 -- Operator: !!
     The double factorial operator.

     For an integer, float, or rational number `n', `n!!' evaluates to
     the product `n (n-2) (n-4) (n-6) ... (n - 2 (k-1))' where `k' is
     equal to `entier (n/2)', that is, the largest integer less than or
     equal to `n/2'.  Note that this definition does not coincide with
     other published definitions for arguments which are not integers.

     For an even (or odd) integer `n', `n!!' evaluates to the product of
     all the consecutive even (or odd) integers from 2 (or 1) through
     `n' inclusive.

     For an argument `n' which is not an integer, float, or rational,
     `n!!' yields a noun form `genfact (n, n/2, 2)'.


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

     Examples:

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


 -- Function: factcomb (<expr>)
     Tries to combine the coefficients of factorials in <expr> with the
     factorials themselves by converting, for example, `(n + 1)*n!'
     into `(n + 1)!'.

     `sumsplitfact' if set to `false' will cause `minfactorial' to be
     applied after a `factcomb'.

     Example:

          (%i1) sumsplitfact;
          (%o1)                                true
          (%i2) (n + 1)*(n + 1)*n!;
                                                   2
          (%o2)                             (n + 1)  n!
          (%i3) factcomb (%);
          (%o3)                         (n + 2)! - (n + 1)!
          (%i4) sumsplitfact: not sumsplitfact;
          (%o4)                                false
          (%i5) (n + 1)*(n + 1)*n!;
                                                    2
          (%o5)                             (n + 1)  n!
          (%i6) factcomb (%);
          (%o6)                        n (n + 1)! + (n + 1)!


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

     For any complex number `x', except for negative integers, `x!' is
     defined as `gamma(x+1)'.

     For an integer `x', `x!' simplifies to the product of the integers
     from 1 to `x' inclusive.  `0!' simplifies to 1.  For a real or
     complex number in float or bigfloat precision `x', `x!' simplifies
     to the value of `gamma (x+1)'.  For `x' equal to `n/2' where `n' is
     an odd integer, `x!' simplifies to a rational factor times `sqrt
     (%pi)' (since `gamma (1/2)' is equal to `sqrt (%pi)').

     The option variables `factlim' and `gammalim' control the numerical
     evaluation of factorials for integer and rational arguments.  The
     functions `minfactorial' and `factcomb' simplifies expressions
     containing factorials.

     The functions `gamma', `bffac', and `cbffac' are varieties of the
     gamma function.  `bffac' and `cbffac' are called internally by
     `gamma' to evaluate the gamma function for real and complex
     numbers in bigfloat precision.

     `makegamma' substitutes `gamma' for factorials and related
     functions.

     Maxima knows the derivative of the factorial function and the
     limits for specific values like negative integers.

     The option variable `factorial_expand' controls the simplification
     of expressions like `(n+x)!', where `n' is an integer.

     See also `binomial'.

     The factorial of an integer is simplified to an exact number
     unless the operand is greater than `factlim'.  The factorial for
     real and complex numbers is evaluated in float or bigfloat
     precision.

          (%i1) factlim:10;
          (%o1)                                 10
          (%i2) [0!, (7/2)!, 8!, 20!];
                                      105 sqrt(%pi)
          (%o2)                   [1, -------------, 40320, 20!]
                                           16
          (%i3) [4.77!, (1.0+%i)!];
          (%o3)    [81.44668037931197,
                    .3430658398165454 %i + .6529654964201665]
          (%i4) [2.86b0!, (1.0b0+%i)!];
          (%o4) [5.046635586910012b0,
                 3.430658398165454b-1 %i + 6.529654964201667b-1]

     The factorial of a known constant, or general expression is not
     simplified.  Even so it may be possible to simplify the factorial
     after evaluating the operand.

          (%i1) [(%i + 1)!, %pi!, %e!, (cos(1) + sin(1))!];
          (%o1)      [(%i + 1)!, %pi!, %e!, (sin(1) + cos(1))!]
          (%i2) ev (%, numer, %enumer);
          (%o2) [.3430658398165454 %i + .6529654964201665,
                 7.188082728976031,
                 4.260820476357003, 1.227580202486819]

     Factorials are simplified, not evaluated.  Thus `x!' may be
     replaced even in a quoted expression.

          (%i1) '([0!, (7/2)!, 4.77!, 8!, 20!]);
                    105 sqrt(%pi)
          (%o1) [1, -------------, 81.44668037931199, 40320,
                         16
                                                       2432902008176640000]

     Maxima knows the derivative of the factorial function.

          (%i1) diff(x!,x);
          (%o1)                           x! psi (x + 1)
                                                0

     The option variable `factorial_expand' controls expansion and
     simplification of expressions with the factorial function.

          (%i1) (n+1)!/n!,factorial_expand:true;
          (%o1)                                n + 1


 -- Option variable: factlim
     Default value: -1

     `factlim' specifies the highest factorial which is automatically
     expanded.  If it is -1 then all integers are expanded.


 -- Option variable: factorial_expand
     Default value: false

     The option variable `factorial_expand' controls the simplification
     of expressions like `(n+1)!', where `n' is an integer.  See
     `factorial' for an example.


 -- Function: genfact (<x>, <y>, <z>)
     Returns the generalized factorial, defined as `x (x-z) (x - 2 z)
     ... (x - (y - 1) z)'.  Thus, when <x> is an integer, `genfact (x,
     x, 1) = x!' and `genfact (x, x/2, 2) = x!!'.


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

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


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

     When `sumsplitfact' is `false', `minfactorial' is applied after a
     `factcomb'.



File: maxima.info,  Node: Root Exponential and Logarithmic Functions,  Next: Trigonometric Functions,  Prev: Combinatorial Functions,  Up: Mathematical Functions

10.4 Root, Exponential and Logarithmic Functions
================================================

 -- Option variable: %e_to_numlog
     Default value: `false'

     When `true', `r' some rational number, and `x' some expression,
     `%e^(r*log(x))' will be simplified into `x^r' .  It should be noted
     that the `radcan' command also does this transformation, and more
     complicated transformations of this ilk as well.  The `logcontract'
     command "contracts" expressions containing `log'.


 -- Option variable: %emode
     Default value: `true'

     When `%emode' is `true', `%e^(%pi %i x)' is simplified as follows.

     `%e^(%pi %i x)' simplifies to `cos (%pi x) + %i sin (%pi x)' if
     `x' is a floating point number, an integer, or a multiple of 1/2,
     1/3, 1/4, or 1/6, and then further simplified.

     For other numerical `x', `%e^(%pi %i x)' simplifies to `%e^(%pi %i
     y)' where `y' is `x - 2 k' for some integer `k' such that `abs(y)
     < 1'.

     When `%emode' is `false', no special simplification of `%e^(%pi %i
     x)' is carried out.


 -- Option variable: %enumer
     Default value: `false'

     When `%enumer' is `true', `%e' is replaced by its numeric value
     2.718...  whenever `numer' is `true'.

     When `%enumer' is `false', this substitution is carried out only
     if the exponent in `%e^x' evaluates to a number.

     See also `ev' and `numer'.


 -- Function: exp (<x>)
     Represents the exponential function.  Instances of `exp (<x>)' in
     input are simplified to `%e^<x>'; `exp' does not appear in
     simplified expressions.

     `demoivre' if `true' causes `%e^(a + b %i)' to simplify to `%e^(a
     (cos(b) + %i sin(b)))' if `b' is free of `%i'.  See `demoivre'.

     `%emode', when `true', causes `%e^(%pi %i x)' to be simplified.
     See `%emode'.

     `%enumer', when `true' causes `%e' to be replaced by 2.718...
     whenever `numer' is `true'.  See `%enumer'.


 -- Function: li [<s>] (<z>)
     Represents the polylogarithm function of order <s> and argument
     <z>, defined by the infinite series

                                           inf
                                           ====   k
                                           \     z
                                  Li (z) =  >    --
                                    s      /      s
                                           ====  k
                                           k = 1

     `li [1]' is `- log (1 - z)'.  `li [2]' and `li [3]' are the
     dilogarithm and trilogarithm functions, respectively.

     When the order is 1, the polylogarithm simplifies to `- log (1 -
     z)', which in turn simplifies to a numerical value if <z> is a
     real or complex floating point number or the `numer' evaluation
     flag is present.

     When the order is 2 or 3, the polylogarithm simplifies to a
     numerical value if <z> is a real floating point number or the
     `numer' evaluation flag is present.

     Examples:

          (%i1) assume (x > 0);
          (%o1)                        [x > 0]
          (%i2) integrate ((log (1 - t)) / t, t, 0, x);
          (%o2)                       - li (x)
                                          2
          (%i3) li [2] (7);
          (%o3)                        li (7)
                                         2
          (%i4) li [2] (7), numer;
          (%o4)        1.24827317833392 - 6.113257021832577 %i
          (%i5) li [3] (7);
          (%o5)                        li (7)
                                         3
          (%i6) li [2] (7), numer;
          (%o6)        1.24827317833392 - 6.113257021832577 %i
          (%i7) L : makelist (i / 4.0, i, 0, 8);
          (%o7)   [0.0, 0.25, 0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2.0]
          (%i8) map (lambda ([x], li [2] (x)), L);
          (%o8) [0, .2676526384986274, .5822405249432515,
          .9784693966661848, 1.64493407, 2.190177004178597
           - .7010261407036192 %i, 2.374395264042415
           - 1.273806203464065 %i, 2.448686757245154
           - 1.758084846201883 %i, 2.467401098097648
           - 2.177586087815347 %i]
          (%i9) map (lambda ([x], li [3] (x)), L);
          (%o9) [0, .2584613953442624, 0.537213192678042,
          .8444258046482203, 1.2020569, 1.642866878950322
           - .07821473130035025 %i, 2.060877505514697
           - .2582419849982037 %i, 2.433418896388322
           - .4919260182322965 %i, 2.762071904015935
           - .7546938285978846 %i]


 -- Function: log (<x>)
     Represents the natural (base e) logarithm of <x>.

     Maxima does not have a built-in function for the base 10 logarithm
     or other bases. `log10(x) := log(x) / log(10)' is a useful
     definition.

     Simplification and evaluation of logarithms is governed by several
     global flags:

    ``logexpand''
          causes `log(a^b)' to become `b*log(a)'. If it is set to
          `all', `log(a*b)' will also simplify to `log(a)+log(b)'.  If
          it is set to `super', then `log(a/b)' will also simplify to
          `log(a)-log(b)' for rational numbers `a/b', `a#1'.
          (`log(1/b)', for `b' integer, always simplifies.) If it is
          set to `false', all of these simplifications will be turned
          off.

    ``logsimp''
          if `false' then no simplification of `%e' to a power
          containing `log''s is done.

    ``lognegint''
          if `true' implements the rule `log(-n)' -> `log(n)+%i*%pi' for
          `n' a positive integer.

    ``%e_to_numlog''
          when `true', `r' some rational number, and `x' some
          expression, the expression `%e^(r*log(x))' will be simplified
          into `x^r'.  It should be noted that the `radcan' command
          also does this transformation, and more complicated
          transformations of this as well. The `logcontract' command
          "contracts" expressions containing `log'.


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

     When doing indefinite integration where logs are generated, e.g.
     `integrate(1/x,x)', the answer is given in terms of `log(abs(...))'
     if `logabs' is `true', but in terms of `log(...)' if `logabs' is
     `false'.  For definite integration, the `logabs:true' setting is
     used, because here "evaluation" of the indefinite integral at the
     endpoints is often needed.


 -- Option variable: logarc
 -- Function: logarc (<expr>)
     When the global variable `logarc' is `true', inverse circular and
     hyperbolic functions are replaced by equivalent logarithmic
     functions.  The default value of `logarc' is `false'.

     The function `logarc(<expr>)' carries out that replacement for an
     expression <expr> without setting the global variable `logarc'.


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

     Controls which coefficients are contracted when using
     `logcontract'.  It may be set to the name of a predicate function
     of one argument.  E.g. if you like to generate SQRTs, you can do
     `logconcoeffp:'logconfun$ logconfun(m):=featurep(m,integer) or
     ratnump(m)$' .  Then `logcontract(1/2*log(x));' will give
     `log(sqrt(x))'.


 -- Function: logcontract (<expr>)
     Recursively scans the expression <expr>, transforming
     subexpressions of the form `a1*log(b1) + a2*log(b2) + c' into
     `log(ratsimp(b1^a1 * b2^a2)) + c'

          (%i1) 2*(a*log(x) + 2*a*log(y))$
          (%i2) logcontract(%);
                                           2  4
          (%o2)                     a log(x  y )

     The declaration `declare(n,integer)' causes
     `logcontract(2*a*n*log(x))' to simplify to `a*log(x^(2*n))'.  The
     coefficients that "contract" in this manner are those such as the
     2 and the `n' here which satisfy `featurep(coeff,integer)'.  The
     user can control which coefficients are contracted by setting the
     option `logconcoeffp' to the name of a predicate function of one
     argument.  E.g. if you like to generate SQRTs, you can do
     `logconcoeffp:'logconfun$ logconfun(m):=featurep(m,integer) or
     ratnump(m)$' .  Then `logcontract(1/2*log(x));' will give
     `log(sqrt(x))'.


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

     If `true', that is the default value, causes `log(a^b)' to become
     `b*log(a)'.  If it is set to `all', `log(a*b)' will also simplify
     to `log(a)+log(b)'.  If it is set to `super', then `log(a/b)' will
     also simplify to `log(a)-log(b)' for rational numbers `a/b',
     `a#1'.  (`log(1/b)', for integer `b', always simplifies.) If it is
     set to `false', all of these simplifications will be turned off.


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

     If `true' implements the rule `log(-n)' -> `log(n)+%i*%pi' for `n'
     a positive integer.


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

     If `false' then no simplification of `%e' to a power containing
     `log''s is done.


 -- Function: plog (<x>)
     Represents the principal branch of the complex-valued natural
     logarithm with `-%pi' < `carg(<x>)' <= `+%pi' .


 -- Function: sqrt (<x>)
     The square root of <x>.  It is represented internally by
     `<x>^(1/2)'.  See also `rootscontract'.

     `radexpand' if `true' will cause nth roots of factors of a product
     which are powers of n to be pulled outside of the radical, e.g.
     `sqrt(16*x^2)' will become `4*x' only if `radexpand' is `true'.



File: maxima.info,  Node: Trigonometric Functions,  Next: Random Numbers,  Prev: Root Exponential and Logarithmic Functions,  Up: Mathematical Functions

10.5 Trigonometric Functions
============================

* Menu:

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


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

10.5.1 Introduction to Trigonometric
------------------------------------

Maxima has many trigonometric functions defined.  Not all trigonometric
identities are programmed, but it is possible for the user to add many
of them using the pattern matching capabilities of the system.  The
trigonometric functions defined in Maxima are: `acos', `acosh', `acot',
`acoth', `acsc', `acsch', `asec', `asech', `asin', `asinh', `atan',
`atanh', `cos', `cosh', `cot', `coth', `csc', `csch', `sec', `sech',
`sin', `sinh', `tan', and `tanh'.  There are a number of commands
especially for handling trigonometric functions, see `trigexpand',
`trigreduce', and the switch `trigsign'.  Two share packages extend the
simplification rules built into Maxima, `ntrig' and `atrig1'.  Do
`describe(<command>)' for details.


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

10.5.2 Functions and Variables for Trigonometric
------------------------------------------------

 -- Option variable: %piargs
     Default value: `true'

     When `%piargs' is `true', trigonometric functions are simplified
     to algebraic constants when the argument is an integer multiple of
     %pi, %pi/2, %pi/3, %pi/4, or %pi/6.

     Maxima knows some identities which can be applied when %pi, etc.,
     are multiplied by an integer variable (that is, a symbol declared
     to be integer).

     Examples:

          (%i1) %piargs : false$
          (%i2) [sin (%pi), sin (%pi/2), sin (%pi/3)];
                                          %pi       %pi
          (%o2)            [sin(%pi), sin(---), sin(---)]
                                           2         3
          (%i3) [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
                                %pi       %pi       %pi
          (%o3)            [sin(---), sin(---), sin(---)]
                                 4         5         6
          (%i4) %piargs : true$
          (%i5) [sin (%pi), sin (%pi/2), sin (%pi/3)];
                                          sqrt(3)
          (%o5)                    [0, 1, -------]
                                             2
          (%i6) [sin (%pi/4), sin (%pi/5), sin (%pi/6)];
                                   1         %pi   1
          (%o6)                [-------, sin(---), -]
                                sqrt(2)       5    2
          (%i7) [cos (%pi/3), cos (10*%pi/3), tan (10*%pi/3),
                 cos (sqrt(2)*%pi/3)];
                          1    1               sqrt(2) %pi
          (%o7)          [-, - -, sqrt(3), cos(-----------)]
                          2    2                    3

     Some identities are applied when %pi and %pi/2 are multiplied by
     an integer variable.

          (%i1) declare (n, integer, m, even)$
          (%i2) [sin (%pi * n), cos (%pi * m), sin (%pi/2 * m),
                 cos (%pi/2 * m)];
                                                m/2
          (%o2)                  [0, 1, 0, (- 1)   ]


 -- Option variable: %iargs
     Default value: `true'

     When `%iargs' is `true', trigonometric functions are simplified to
     hyperbolic functions when the argument is apparently a multiple of
     the imaginary unit %i.

     Even when the argument is demonstrably real, the simplification is
     applied; Maxima considers only whether the argument is a literal
     multiple of %i.

     Examples:

          (%i1) %iargs : false$
          (%i2) [sin (%i * x), cos (%i * x), tan (%i * x)];
          (%o2)           [sin(%i x), cos(%i x), tan(%i x)]
          (%i3) %iargs : true$
          (%i4) [sin (%i * x), cos (%i * x), tan (%i * x)];
          (%o4)           [%i sinh(x), cosh(x), %i tanh(x)]

     Even when the argument is demonstrably real, the simplification is
     applied.

          (%i1) declare (x, imaginary)$
          (%i2) [featurep (x, imaginary), featurep (x, real)];
          (%o2)                     [true, false]
          (%i3) sin (%i * x);
          (%o3)                      %i sinh(x)


 -- Function: acos (<x>)
     - Arc Cosine.


 -- Function: acosh (<x>)
     - Hyperbolic Arc Cosine.


 -- Function: acot (<x>)
     - Arc Cotangent.


 -- Function: acoth (<x>)
     - Hyperbolic Arc Cotangent.


 -- Function: acsc (<x>)
     - Arc Cosecant.


 -- Function: acsch (<x>)
     - Hyperbolic Arc Cosecant.


 -- Function: asec (<x>)
     - Arc Secant.


 -- Function: asech (<x>)
     - Hyperbolic Arc Secant.


 -- Function: asin (<x>)
     - Arc Sine.


 -- Function: asinh (<x>)
     - Hyperbolic Arc Sine.


 -- Function: atan (<x>)
     - Arc Tangent.


 -- Function: atan2 (<y>, <x>)
     - yields the value of `atan(<y>/<x>)' in the interval `-%pi' to
     `%pi'.


 -- Function: atanh (<x>)
     - Hyperbolic Arc Tangent.


 -- Package: atrig1
     The `atrig1' package contains several additional simplification
     rules for inverse trigonometric functions.  Together with rules
     already known to Maxima, the following angles are fully
     implemented: `0', `%pi/6', `%pi/4', `%pi/3', and `%pi/2'.
     Corresponding angles in the other three quadrants are also
     available.  Do `load(atrig1);' to use them.


 -- Function: cos (<x>)
     - Cosine.


 -- Function: cosh (<x>)
     - Hyperbolic Cosine.


 -- Function: cot (<x>)
     - Cotangent.


 -- Function: coth (<x>)
     - Hyperbolic Cotangent.


 -- Function: csc (<x>)
     - Cosecant.


 -- Function: csch (<x>)
     - Hyperbolic Cosecant.


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

     When `halfangles' is `true', trigonometric functions of arguments
     `<expr>/2' are simplified to functions of <expr>.

     For a real argument <x> in the interval `0 < x < 2*%pi' the sine of
     the half-angle simplifies to a simple formula:

                                   sqrt(1 - cos(x))
                                   ----------------
                                       sqrt(2)

     A complicated factor is needed to make this formula correct for
     all complex arguments <z>:

                realpart(z)
          floor(-----------)
                   2 %pi
     (- 1)                   (1 - unit_step(- imagpart(z))

                                 realpart(z)            realpart(z)
                           floor(-----------) - ceiling(-----------)
                                    2 %pi                  2 %pi
                     ((- 1)                                          + 1))

     Maxima knows this factor and similar factors for the functions
     `sin', `cos', `sinh', and `cosh'.  For special values of the
     argument z these factors simplify accordingly.

     Examples:

          (%i1) halfangles:false;
          (%o1)                                false
          (%i2) sin(x/2);
                                                  x
          (%o2)                               sin(-)
                                                  2
          (%i3) halfangles:true;
          (%o3)                                true
          (%i4) sin(x/2);
                                                              x
                                                      floor(-----)
                                                            2 %pi
                                sqrt(1 - cos(x)) (- 1)
          (%o4)                 ----------------------------------
                                             sqrt(2)
          (%i5) assume(x>0, x<2*%pi)$
          (%i6) sin(x/2);
                                         sqrt(1 - cos(x))
          (%o6)                          ----------------
                                             sqrt(2)


 -- Package: ntrig
     The `ntrig' package contains a set of simplification rules that are
     used to simplify trigonometric function whose arguments are of the
     form `<f>(<n> %pi/10)' where <f> is any of the functions `sin',
     `cos', `tan', `csc', `sec' and `cot'.


 -- Function: sec (<x>)
     - Secant.


 -- Function: sech (<x>)
     - Hyperbolic Secant.


 -- Function: sin (<x>)
     - Sine.


 -- Function: sinh (<x>)
     - Hyperbolic Sine.


 -- Function: tan (<x>)
     - Tangent.


 -- Function: tanh (<x>)
     - Hyperbolic Tangent.


 -- Function: trigexpand (<expr>)
     Expands trigonometric and hyperbolic functions of sums of angles
     and of multiple angles occurring in <expr>.  For best results,
     <expr> should be expanded.  To enhance user control of
     simplification, this function expands only one level at a time,
     expanding sums of angles or multiple angles.  To obtain full
     expansion into sines and cosines immediately, set the switch
     `trigexpand: true'.

     `trigexpand' is governed by the following global flags:

    `trigexpand'
          If `true' causes expansion of all expressions containing
          sin's and cos's occurring subsequently.

    `halfangles'
          If `true' causes half-angles to be simplified away.

    `trigexpandplus'
          Controls the "sum" rule for `trigexpand', expansion of sums
          (e.g. `sin(x + y)') will take place only if `trigexpandplus'
          is `true'.

    `trigexpandtimes'
          Controls the "product" rule for `trigexpand', expansion of
          products (e.g. `sin(2 x)') will take place only if
          `trigexpandtimes' is `true'.

     Examples:

          (%i1) x+sin(3*x)/sin(x),trigexpand=true,expand;
                                   2           2
          (%o1)               - sin (x) + 3 cos (x) + x
          (%i2) trigexpand(sin(10*x+y));
          (%o2)          cos(10 x) sin(y) + sin(10 x) cos(y)


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

     `trigexpandplus' controls the "sum" rule for `trigexpand'.  Thus,
     when the `trigexpand' command is used or the `trigexpand' switch
     set to `true', expansion of sums (e.g. `sin(x+y))' will take place
     only if `trigexpandplus' is `true'.


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

     `trigexpandtimes' controls the "product" rule for `trigexpand'.
     Thus, when the `trigexpand' command is used or the `trigexpand'
     switch set to `true', expansion of products (e.g. `sin(2*x)') will
     take place only if `trigexpandtimes' is `true'.


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

     `triginverses' controls the simplification of the composition of
     trigonometric and hyperbolic functions with their inverse
     functions.

     If `all', both e.g. `atan(tan(<x>))' and `tan(atan(<x>))' simplify
     to <x>.

     If `true', the `<arcfun>(<fun>(<x>))' simplification is turned off.

     If `false', both the `<arcfun>(<fun>(<x>))' and
     `<fun>(<arcfun>(<x>))' simplifications are turned off.


 -- Function: trigreduce (<expr>, <x>)
 -- Function: trigreduce (<expr>)
     Combines products and powers of trigonometric and hyperbolic sin's
     and cos's of <x> into those of multiples of <x>.  It also tries to
     eliminate these functions when they occur in denominators.  If <x>
     is omitted then all variables in <expr> are used.

     See also `poissimp'.

          (%i1) trigreduce(-sin(x)^2+3*cos(x)^2+x);
                         cos(2 x)      cos(2 x)   1        1
          (%o1)          -------- + 3 (-------- + -) + x - -
                            2             2       2        2


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

     When `trigsign' is `true', it permits simplification of negative
     arguments to trigonometric functions.  E.g., `sin(-x)' will become
     `-sin(x)' only if `trigsign' is `true'.


 -- Function: trigsimp (<expr>)
     Employs the identities sin(x)^2 + cos(x)^2 = 1 and cosh(x)^2 -
     sinh(x)^2 = 1 to simplify expressions containing `tan', `sec',
     etc., to `sin', `cos', `sinh', `cosh'.

     `trigreduce', `ratsimp', and `radcan' may be able to further
     simplify the result.

     `demo ("trgsmp.dem")' displays some examples of `trigsimp'.


 -- Function: trigrat (<expr>)
     Gives a canonical simplified quasilinear form of a trigonometrical
     expression; <expr> is a rational fraction of several `sin', `cos'
     or `tan', the arguments of them are linear forms in some variables
     (or kernels) and `%pi/<n>' (<n> integer) with integer coefficients.
     The result is a simplified fraction with numerator and denominator
     linear in `sin' and `cos'.  Thus `trigrat' linearize always when
     it is possible.

          (%i1) trigrat(sin(3*a)/sin(a+%pi/3));
          (%o1)            sqrt(3) sin(2 a) + cos(2 a) - 1

     The following example is taken from Davenport, Siret, and
     Tournier, Calcul Formel, Masson (or in English, Addison-Wesley),
     section 1.5.5, Morley theorem.

          (%i1) c : %pi/3 - a - b$
          (%i2) bc : sin(a)*sin(3*c)/sin(a+b);
                                                    %pi
                            sin(a) sin(3 (- b - a + ---))
                                                     3
          (%o2)             -----------------------------
                                     sin(b + a)
          (%i3) ba : bc, c=a, a=c;
                                                   %pi
                              sin(3 a) sin(b + a - ---)
                                                    3
          (%o3)               -------------------------
                                            %pi
                                    sin(a - ---)
                                             3
          (%i4) ac2 : ba^2 + bc^2 - 2*bc*ba*cos(b);
                   2         2         %pi
                sin (3 a) sin (b + a - ---)
                                        3
          (%o4) ---------------------------
                          2     %pi
                       sin (a - ---)
                                 3
                                                 %pi
           - (2 sin(a) sin(3 a) sin(3 (- b - a + ---)) cos(b)
                                                  3
                       %pi            %pi
           sin(b + a - ---))/(sin(a - ---) sin(b + a))
                        3              3
                2       2              %pi
             sin (a) sin (3 (- b - a + ---))
                                        3
           + -------------------------------
                          2
                       sin (b + a)
          (%i5) trigrat (ac2);
          (%o5) - (sqrt(3) sin(4 b + 4 a) - cos(4 b + 4 a)
           - 2 sqrt(3) sin(4 b + 2 a) + 2 cos(4 b + 2 a)
           - 2 sqrt(3) sin(2 b + 4 a) + 2 cos(2 b + 4 a)
           + 4 sqrt(3) sin(2 b + 2 a) - 8 cos(2 b + 2 a) - 4 cos(2 b - 2 a)
           + sqrt(3) sin(4 b) - cos(4 b) - 2 sqrt(3) sin(2 b) + 10 cos(2 b)
           + sqrt(3) sin(4 a) - cos(4 a) - 2 sqrt(3) sin(2 a) + 10 cos(2 a)
           - 9)/4



File: maxima.info,  Node: Random Numbers,  Prev: Trigonometric Functions,  Up: Mathematical Functions

10.6 Random Numbers
===================

 -- Function: make_random_state (<n>)
 -- Function: make_random_state (<s>)
 -- Function: make_random_state (true)
 -- Function: make_random_state (false)
     A random state object represents the state of the random number
     generator.  The state comprises 627 32-bit words.

     `make_random_state (<n>)' returns a new random state object
     created from an integer seed value equal to <n> modulo 2^32.  <n>
     may be negative.

     `make_random_state (<s>)' returns a copy of the random state <s>.

     `make_random_state (true)' returns a new random state object,
     using the current computer clock time as the seed.

     `make_random_state (false)' returns a copy of the current state of
     the random number generator.


 -- Function: set_random_state (<s>)
     Copies <s> to the random number generator state.

     `set_random_state' always returns `done'.


 -- Function: random (<x>)
     Returns a pseudorandom number.  If <x> is an integer, `random
     (<x>)' returns an integer from 0 through `<x> - 1' inclusive.  If
     <x> is a floating point number, `random (<x>)' returns a
     nonnegative floating point number less than <x>.  `random'
     complains with an error if <x> is neither an integer nor a float,
     or if <x> is not positive.

     The functions `make_random_state' and `set_random_state' maintain
     the state of the random number generator.

     The Maxima random number generator is an implementation of the
     Mersenne twister MT 19937.

     Examples:

          (%i1) s1: make_random_state (654321)$
          (%i2) set_random_state (s1);
          (%o2)                         done
          (%i3) random (1000);
          (%o3)                          768
          (%i4) random (9573684);
          (%o4)                        7657880
          (%i5) random (2^75);
          (%o5)                11804491615036831636390
          (%i6) s2: make_random_state (false)$
          (%i7) random (1.0);
          (%o7)                   .2310127244107132
          (%i8) random (10.0);
          (%o8)                   4.394553645870825
          (%i9) random (100.0);
          (%o9)                   32.28666704056853
          (%i10) set_random_state (s2);
          (%o10)                        done
          (%i11) random (1.0);
          (%o11)                  .2310127244107132
          (%i12) random (10.0);
          (%o12)                  4.394553645870825
          (%i13) random (100.0);
          (%o13)                  32.28666704056853



File: maxima.info,  Node: Maximas Database,  Next: Plotting,  Prev: Mathematical Functions,  Up: Top

11 Maximas Database
*******************

* Menu:

* Introduction to Maximas Database::
* Functions and Variables for Properties::
* Functions and Variables for Facts::
* Functions and Variables for Predicates::


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

11.1 Introduction to Maximas Database
=====================================


File: maxima.info,  Node: Functions and Variables for Properties,  Next: Functions and Variables for Facts,  Prev: Introduction to Maximas Database,  Up: Maximas Database

11.2 Functions and Variables for Properties
===========================================

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

     See also *note Identifiers::.

     Example:

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


 -- Property: bindtest
     The command `declare(<x>, bindtest)' tells Maxima to trigger an
     error when the symbol <x> is evaluated unbound.

          (%i1) aa + bb;
          (%o1)                        bb + aa
          (%i2) declare (aa, bindtest);
          (%o2)                         done
          (%i3) aa + bb;
          aa unbound variable
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i4) aa : 1234;
          (%o4)                         1234
          (%i5) aa + bb;
          (%o5)                       bb + 1234

 -- Property: constant
     `declare(<a>, constant)' declares <a> to be a constant.  The
     declaration of a symbol to be constant does not prevent the
     assignment of a nonconstant value to the symbol.

     See `constantp' and `declare'.

     Example:

          (%i1) declare(c, constant);
          (%o1)                         done
          (%i2) constantp(c);
          (%o2)                         true
          (%i3) c : x;
          (%o3)                           x
          (%i4) constantp(c);
          (%o4)                         false


 -- Function: constantp (<expr>)
     Returns `true' if <expr> is a constant expression, otherwise
     returns `false'.

     An expression is considered a constant expression if its arguments
     are numbers (including rational numbers, as displayed with `/R/'),
     symbolic constants such as `%pi', `%e', and `%i', variables bound
     to a constant or declared constant by `declare', or functions
     whose arguments are constant.

     `constantp' evaluates its arguments.

     See the property `constant' which declares a symbol to be constant.

     Examples:

          (%i1) constantp (7 * sin(2));
          (%o1)                                true
          (%i2) constantp (rat (17/29));
          (%o2)                                true
          (%i3) constantp (%pi * sin(%e));
          (%o3)                                true
          (%i4) constantp (exp (x));
          (%o4)                                false
          (%i5) declare (x, constant);
          (%o5)                                done
          (%i6) constantp (exp (x));
          (%o6)                                true
          (%i7) constantp (foo (x) + bar (%e) + baz (2));
          (%o7)                                false
          (%i8)


 -- Function: declare (<a_1>, <p_1>, <a_2>, <p_2>, ...)
     Assigns the atom or list of atoms <a_i> the property or list of
     properties <p_i>.  When <a_i> and/or <p_i> are lists, each of the
     atoms gets all of the properties.

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

     As noted in the description for each declaration flag, for some
     flags `featurep(<object>, <feature>)' returns `true' if <object>
     has been declared to have <feature>.

     For more information about the features system, see `features'. To
     remove a property from an atom, use `remove'.

     `declare' recognizes the following properties:

    `additive'
          Tells Maxima to simplify <a_i> expressions by the substitution
               `<a_i>(x + y + z + ...)' `-->'       `<a_i>(x) +
          <a_i>(y) + <a_i>(z) + ...'.        The substitution is
          carried out on the first argument only.

    `alphabetic'
          Tells Maxima to recognize all characters in <a_i> (which must
          be a       string) as alphabetic characters.

    `antisymmetric, commutative, symmetric'
          Tells Maxima to recognize <a_i> as a symmetric or
          antisymmetric       function.  `commutative' is the same as
          `symmetric'.

    `bindtest'
          Tells Maxima to trigger an error when <a_i> is evaluated
          unbound.

    `constant'
          Tells Maxima to consider <a_i> a symbolic constant.

    `even, odd'
          Tells Maxima to recognize <a_i> as an even or odd integer
          variable.

    `evenfun, oddfun'
          Tells Maxima to recognize <a_i> as an odd or even function.

    `evflag'
          Makes <a_i> known to the `ev' function so that <a_i> is bound
               to `true' during the execution of `ev' when <a_i>
          appears as       a flag argument of `ev'.  See `evflag'.

    `evfun'
          Makes <a_i> known to `ev' so that the function named by <a_i>
               is applied when <a_i> appears as a flag argument of `ev'.
               See `evfun'.

    `feature'
          Tells Maxima to recognize <a_i> as the name of a feature.
            Other atoms may then be declared to have the <a_i> property.

    `increasing, decreasing'
          Tells Maxima to recognize <a_i> as an increasing or decreasing
               function.

    `integer, noninteger'
          Tells Maxima to recognize <a_i> as an integer or noninteger
          variable.

    `integervalued'
          Tells Maxima to recognize <a_i> as an integer-valued function.

    `lassociative, rassociative'
          Tells Maxima to recognize <a_i> as a right-associative or
           left-associative function.

    `linear'
          Equivalent to declaring <a_i> both `outative' and
          `additive'.

    `mainvar'
          Tells Maxima to consider <a_i> a "main variable".  A main
          variable       succeeds all other constants and variables in
          the canonical ordering of       Maxima expressions, as
          determined by `ordergreatp'.

    `multiplicative'
          Tells Maxima to simplify <a_i> expressions by the substitution
               `<a_i>(x * y * z * ...)' `-->'       `<a_i>(x) *
          <a_i>(y) * <a_i>(z) * ...'.        The substitution is
          carried out on the first argument only.

    `nary'
          Tells Maxima to recognize <a_i> as an n-ary function.

          The `nary' declaration is not the same as calling the `nary'
              function.  The sole effect of `declare(foo, nary)' is to
          instruct the       Maxima simplifier to flatten nested
          expressions, for example, to simplify       `foo(x, foo(y,
          z))' to `foo(x, y, z)'.

    `nonarray'
          Tells Maxima to consider <a_i> not an array.  This declaration
               prevents multiple evaluation of a subscripted variable
          name.

    `nonscalar'
          Tells Maxima to consider <a_i> a nonscalar variable.  The
          usual       application is to declare a variable as a
          symbolic vector or matrix.

    `noun'
          Tells Maxima to parse <a_i> as a noun.  The effect of this is
          to       replace instances of <a_i> with `'<a_i>' or
          `nounify(<a_i>)', depending on the context.

    `outative'
          Tells Maxima to simplify <a_i> expressions by pulling
          constant factors       out of the first argument.

          When <a_i> has one argument, a factor is considered constant
          if it is       a literal or declared constant.

          When <a_i> has two or more arguments, a factor is considered
          constant       if the second argument is a symbol and the
          factor is free of the second       argument.

    `posfun'
          Tells Maxima to recognize <a_i> as a positive function.

    `rational, irrational'
          Tells Maxima to recognize <a_i> as a rational or irrational
          real       variable.

    `real, imaginary, complex'
          Tells Maxima to recognize <a_i> as a real, pure imaginary, or
          complex       variable.

    `scalar'
          Tells Maxima to consider <a_i> a scalar variable.


     Examples of the usage of the properties are available in the
     documentation for each separate description of a property.


 -- Property: decreasing
 -- Property: increasing
     The commands `declare(<f>, decreasing)' or `declare(<f>,
     increasing)' tell Maxima to recognize the function <f> as an
     decreasing or increasing function.

     See also `declare' for more properties.

     Example:

          (%i1) assume(a > b);
          (%o1)                        [a > b]
          (%i2) is(f(a) > f(b));
          (%o2)                        unknown
          (%i3) declare(f, increasing);
          (%o3)                         done
          (%i4) is(f(a) > f(b));
          (%o4)                         true


 -- Property: even
 -- Property: odd
     `declare(<a>, even)' or `declare(<a>, odd)' tells Maxima to
     recognize the symbol <a> as an even or odd integer variable.  The
     properties `even' and `odd' are not recognized by the functions
     `evenp', `oddp', and `integerp'.

     See also `declare' and `askinteger'.

     Example:

          (%i1) declare(n, even);
          (%o1)                         done
          (%i2) askinteger(n, even);
          (%o2)                          yes
          (%i3) askinteger(n);
          (%o3)                          yes
          (%i4) evenp(n);
          (%o4)                         false


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

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

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

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

     `featurep' evaluates its argument.

     See also `declare' and `features'.

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


 -- Declaration: features
     Maxima recognizes certain mathematical properties of functions and
     variables.  These are called "features".

     `declare (<x>, <foo>)' gives the property <foo> to the function or
     variable <x>.

     `declare (<foo>, feature)' declares a new feature <foo>.  For
     example, `declare ([red, green, blue], feature)' declares three
     new features, `red', `green', and `blue'.

     The predicate `featurep (<x>, <foo>)' returns `true' if <x> has
     the <foo> property, and `false' otherwise.

     The infolist `features' is a list of known features.  These are

        integer        noninteger      even
        odd            rational        irrational
        real           imaginary       complex
        analytic       increasing      decreasing
        oddfun         evenfun         posfun
        commutative    lassociative    rassociative
        symmetric      antisymmetric

     plus any user-defined features.

     `features' is a list of mathematical features.  There is also a
     list of non-mathematical, system-dependent features.  See `status'.

     Example:

          (%i1) declare (FOO, feature);
          (%o1)                         done
          (%i2) declare (x, FOO);
          (%o2)                         done
          (%i3) featurep (x, FOO);
          (%o3)                         true


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

     `get' evaluates its arguments.

     See also `put' and `qput'.

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


 -- Property: integer
 -- Property: noninteger
     `declare(<a>, integer)' or `declare(<a>, noninteger)' tells Maxima
     to recognize <a> as an integer or noninteger variable.

     See also `declare'.

     Example:

          (%i1) declare(n, integer, x, noninteger);
          (%o1)                         done
          (%i2) askinteger(n);
          (%o2)                          yes
          (%i3) askinteger(x);
          (%o3)                          no


 -- Property: integervalued
     `declare(<f>, integervalued)' tells Maxima to recognize <f> as an
     integer-valued function.

     See also `declare'.

     Example:

          (%i1) exp(%i)^f(x);
                                        %i f(x)
          (%o1)                      (%e  )
          (%i2) declare(f, integervalued);
          (%o2)                         done
          (%i3) exp(%i)^f(x);
                                        %i f(x)
          (%o3)                       %e


 -- Property: nonarray
     The command `declare(a, nonarray)' tells Maxima to consider <a> not
     an array.  This declaration prevents multiple evaluation, if <a>
     is a subscripted variable.

     See also `declare'.

     Example:

          (%i1) a:'b$ b:'c$ c:'d$

          (%i4) a[x];
          (%o4)                          d
                                          x
          (%i5) declare(a, nonarray);
          (%o5)                         done
          (%i6) a[x];
          (%o6)                          a
                                          x


 -- Property: nonscalar
     Makes atoms behave as does a list or matrix with respect to the
     dot operator.

     See also `declare'.


 -- Function: nonscalarp (<expr>)
     Returns `true' if <expr> is a non-scalar, i.e., it contains atoms
     declared as non-scalars, lists, or matrices.

     See also the predicate function `scalarp' and `declare'.


 -- Property: posfun
     `declare (f, posfun)' declares `f' to be a positive function.  `is
     (f(x) > 0)' yields `true'.

     See also `declare'.


 -- Function: printprops (<a>, <i>)
 -- Function: printprops ([<a_1>, ..., <a_n>], <i>)
 -- Function: printprops (all, <i>)
     Displays the property with the indicator <i> associated with the
     atom <a>.  <a> may also be a list of atoms or the atom `all' in
     which case all of the atoms with the given property will be used.
     For example, `printprops ([f, g], atvalue)'.  `printprops' is for
     properties that cannot otherwise be displayed, i.e.  for `atvalue',
     `atomgrad', `gradef', and `matchdeclare'.


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


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

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


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


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

     `rem' reverses the effect of `put'.

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

     See also `qput' and `get'.

     Examples:

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


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

     See also `get'.

     Example:

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


 -- Property: rational
 -- Property: irrational
     `declare(<a>, rational)' or `declare(<a>, irrational)' tells
     Maxima to recognize <a> as a rational or irrational real variable.

     See also `declare'.


 -- Property: real
 -- Property: imaginary
 -- Property: complex
     `declare(<a>, real)', `declare(<a>, imaginary)', or `declare(<a>,
     complex)' tells Maxima to recognize <a> as a real, pure imaginary,
     or complex variable.

     See also `declare'.


 -- Function: rem (<atom>, <indicator>)
     Removes the property indicated by <indicator> from <atom>.  `rem'
     reverses the effect of `put'.

     `rem' returns `done' if <atom> had an <indicator> property when
     `rem' was called, or `false' if it had no such property.


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

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

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

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

     The removed properties may be system-defined properties such as
     `function', `macro', or `mode_declare'.  `remove' does not remove
     properties defined by `put'.

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

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

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

     `remove' quotes its arguments.


 -- Property: scalar
     `declare(<a>, scalar)' tells Maxima to consider <a> a scalar
     variable.

     See also `declare'.


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

     See also the predicate function `nonscalarp'.



File: maxima.info,  Node: Functions and Variables for Facts,  Next: Functions and Variables for Predicates,  Prev: Functions and Variables for Properties,  Up: Maximas Database

11.3 Functions and Variables for Facts
======================================

 -- Function: activate (<context_1>, ..., <context_n>)
     Activates the contexts <context_1>, ..., <context_n>.  The facts
     in these contexts are then available to make deductions and
     retrieve information.  The facts in these contexts are not listed
     by `facts ()'.

     The variable `activecontexts' is the list of contexts which are
     active by way of the `activate' function.


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

     `activecontexts' is a list of the contexts which are active by way
     of the `activate' function, as opposed to being active because
     they are subcontexts of the current context.


 -- Function: askinteger (<expr>, integer)
 -- Function: askinteger (<expr>)
 -- Function: askinteger (<expr>, even)
 -- Function: askinteger (<expr>, odd)
     `askinteger (<expr>, integer)' attempts to determine from the
     `assume' database whether <expr> is an integer.  `askinteger'
     prompts the user if it cannot tell otherwise, and attempt to
     install the information in the database if possible.  `askinteger
     (<expr>)' is equivalent to `askinteger (<expr>, integer)'.

     `askinteger (<expr>, even)' and `askinteger (<expr>, odd)'
     likewise attempt to determine if <expr> is an even integer or odd
     integer, respectively.


 -- Function: asksign (<expr>)
     First attempts to determine whether the specified expression is
     positive, negative, or zero.  If it cannot, it asks the user the
     necessary questions to complete its deduction.  The user's answer
     is recorded in the data base for the duration of the current
     computation.  The return value of `asksign' is one of `pos',
     `neg', or `zero'.


 -- Function: assume (<pred_1>, ..., <pred_n>)
     Adds predicates <pred_1>, ..., <pred_n> to the current context.
     If a predicate is inconsistent or redundant with the predicates in
     the current context, it is not added to the context.  The context
     accumulates predicates from each call to `assume'.

     `assume' returns a list whose elements are the predicates added to
     the context or the atoms `redundant' or `inconsistent' where
     applicable.

     The predicates <pred_1>, ..., <pred_n> can only be expressions
     with the relational operators `< <= equal notequal >=' and `>'.
     Predicates cannot be literal equality `=' or literal inequality `#'
     expressions, nor can they be predicate functions such as
     `integerp'.

     Compound predicates of the form `<pred_1> and ... and <pred_n>'
     are recognized, but not `<pred_1> or ... or <pred_n>'.  `not
     <pred_k>' is recognized if <pred_k> is a relational predicate.
     Expressions of the form `not (<pred_1> and <pred_2>)' and `not
     (<pred_1> or <pred_2>)' are not recognized.

     Maxima's deduction mechanism is not very strong; there are many
     obvious consequences which cannot be determined by `is'.  This is
     a known weakness.

     `assume' does not handle predicates with complex numbers.  If a
     predicate contains a complex number `assume' returns
     `inconsistent' or `redunant'.

     `assume' evaluates its arguments.

     See also `is', `facts', `forget', `context', and `declare'.

     Examples:

          (%i1) assume (xx > 0, yy < -1, zz >= 0);
          (%o1)              [xx > 0, yy < - 1, zz >= 0]
          (%i2) assume (aa < bb and bb < cc);
          (%o2)                  [bb > aa, cc > bb]
          (%i3) facts ();
          (%o3)     [xx > 0, - 1 > yy, zz >= 0, bb > aa, cc > bb]
          (%i4) is (xx > yy);
          (%o4)                         true
          (%i5) is (yy < -yy);
          (%o5)                         true
          (%i6) is (sinh (bb - aa) > 0);
          (%o6)                         true
          (%i7) forget (bb > aa);
          (%o7)                       [bb > aa]
          (%i8) prederror : false;
          (%o8)                         false
          (%i9) is (sinh (bb - aa) > 0);
          (%o9)                        unknown
          (%i10) is (bb^2 < cc^2);
          (%o10)                       unknown


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

     `assumescalar' helps govern whether expressions `expr' for which
     `nonscalarp (expr)' is `false' are assumed to behave like scalars
     for certain transformations.

     Let `expr' represent any expression other than a list or a matrix,
     and let `[1, 2, 3]' represent any list or matrix.  Then `expr .
     [1, 2, 3]' yields `[expr, 2 expr, 3 expr]' if `assumescalar' is
     `true', or `scalarp (expr)' is `true', or `constantp (expr)' is
     `true'.

     If `assumescalar' is `true', such expressions will behave like
     scalars only for commutative operators, but not for noncommutative
     multiplication `.'.

     When `assumescalar' is `false', such expressions will behave like
     non-scalars.

     When `assumescalar' is `all', such expressions will behave like
     scalars for all the operators listed above.


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

     When `assume_pos' is `true' and the sign of a parameter <x> cannot
     be determined from the current context or other considerations,
     `sign' and `asksign (<x>)' return `true'.  This may forestall some
     automatically-generated `asksign' queries, such as may arise from
     `integrate' or other computations.

     By default, a parameter is <x> such that `symbolp (<x>)' or
     `subvarp (<x>)'.  The class of expressions considered parameters
     can be modified to some extent via the variable `assume_pos_pred'.

     `sign' and `asksign' attempt to deduce the sign of expressions
     from the sign of operands within the expression.  For example, if
     `a' and `b' are both positive, then `a + b' is also positive.

     However, there is no way to bypass all `asksign' queries.  In
     particular, when the `asksign' argument is a difference `<x> -
     <y>' or a logarithm `log(<x>)', `asksign' always requests an input
     from the user, even when `assume_pos' is `true' and
     `assume_pos_pred' is a function which returns `true' for all
     arguments.


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

     When `assume_pos_pred' is assigned the name of a function or a
     lambda expression of one argument <x>, that function is called to
     determine whether <x> is considered a parameter for the purpose of
     `assume_pos'.  `assume_pos_pred' is ignored when `assume_pos' is
     `false'.

     The `assume_pos_pred' function is called by `sign' and `asksign'
     with an argument <x> which is either an atom, a subscripted
     variable, or a function call expression.  If the `assume_pos_pred'
     function returns `true', <x> is considered a parameter for the
     purpose of `assume_pos'.

     By default, a parameter is <x> such that `symbolp (<x>)' or
     `subvarp (<x>)'.

     See also `assume' and `assume_pos'.

     Examples:

          (%i1) assume_pos: true$
          (%i2) assume_pos_pred: symbolp$
          (%i3) sign (a);
          (%o3)                          pos
          (%i4) sign (a[1]);
          (%o4)                          pnz
          (%i5) assume_pos_pred: lambda ([x], display (x), true)$
          (%i6) asksign (a);
                                        x = a

          (%o6)                          pos
          (%i7) asksign (a[1]);
                                       x = a
                                            1

          (%o7)                          pos
          (%i8) asksign (foo (a));
                                     x = foo(a)

          (%o8)                          pos
          (%i9) asksign (foo (a) + bar (b));
                                     x = foo(a)

                                     x = bar(b)

          (%o9)                          pos
          (%i10) asksign (log (a));
                                        x = a

          Is  a - 1  positive, negative, or zero?

          p;
          (%o10)                         pos
          (%i11) asksign (a - b);
                                        x = a

                                        x = b

                                        x = a

                                        x = b

          Is  b - a  positive, negative, or zero?

          p;
          (%o11)                         neg


 -- Option variable: context
     Default value: `initial'

     `context' names the collection of facts maintained by `assume' and
     `forget'.  `assume' adds facts to the collection named by
     `context', while `forget' removes facts.

     Binding `context' to a name <foo> changes the current context to
     <foo>.  If the specified context <foo> does not yet exist, it is
     created automatically by a call to `newcontext'.  The specified
     context is activated automatically.

     See `contexts' for a general description of the context mechanism.


 -- Option variable: contexts
     Default value: `[initial, global]'

     `contexts' is a list of the contexts which currently exist,
     including the currently active context.

     The context mechanism makes it possible for a user to bind together
     and name a collection of facts, called a context.  Once this is
     done, the user can have Maxima assume or forget large numbers of
     facts merely by activating or deactivating their context.

     Any symbolic atom can be a context, and the facts contained in that
     context will be retained in storage until destroyed one by one by
     calling `forget' or destroyed as a whole by calling `kill' to
     destroy the context to which they belong.

     Contexts exist in a hierarchy, with the root always being the
     context `global', which contains information about Maxima that some
     functions need.  When in a given context, all the facts in that
     context are "active" (meaning that they are used in deductions and
     retrievals) as are all the facts in any context which is a
     subcontext of the active context.

     When a fresh Maxima is started up, the user is in a context called
     `initial', which has `global' as a subcontext.

     See also `facts', `newcontext', `supcontext', `killcontext',
     `activate', `deactivate', `assume', and `forget'.


 -- Function: deactivate (<context_1>, ..., <context_n>)
     Deactivates the specified contexts <context_1>, ..., <context_n>.


 -- Function: facts (<item>)
 -- Function: facts ()
     If <item> is the name of a context, `facts (<item>)' returns a
     list of the facts in the specified context.

     If <item> is not the name of a context, `facts (<item>)' returns a
     list of the facts known about <item> in the current context.
     Facts that are active, but in a different context, are not listed.

     `facts ()' (i.e., without an argument) lists the current context.


 -- Function: forget (<pred_1>, ..., <pred_n>)
 -- Function: forget (<L>)
     Removes predicates established by `assume'.  The predicates may be
     expressions equivalent to (but not necessarily identical to) those
     previously assumed.

     `forget (<L>)', where <L> is a list of predicates, forgets each
     item on the list.


 -- Function: is (<expr>)
     Attempts to determine whether the predicate <expr> is provable
     from the facts in the `assume' database.

     If the predicate is provably `true' or `false', `is' returns
     `true' or `false', respectively.  Otherwise, the return value is
     governed by the global flag `prederror'.  When `prederror' is
     `true', `is' complains with an error message.  Otherwise, `is'
     returns `unknown'.

     `ev(<expr>, pred)' (which can be written  `<expr>, pred' at the
     interactive prompt) is equivalent to `is(<expr>)'.

     See also `assume', `facts', and `maybe'.

     Examples:

     `is' causes evaluation of predicates.

          (%i1) %pi > %e;
          (%o1)                       %pi > %e
          (%i2) is (%pi > %e);
          (%o2)                         true

     `is' attempts to derive predicates from the `assume' database.

          (%i1) assume (a > b);
          (%o1)                        [a > b]
          (%i2) assume (b > c);
          (%o2)                        [b > c]
          (%i3) is (a < b);
          (%o3)                         false
          (%i4) is (a > c);
          (%o4)                         true
          (%i5) is (equal (a, c));
          (%o5)                         false

     If `is' can neither prove nor disprove a predicate from the
     `assume' database, the global flag `prederror' governs the
     behavior of `is'.

          (%i1) assume (a > b);
          (%o1)                        [a > b]
          (%i2) prederror: true$
          (%i3) is (a > 0);
          Maxima was unable to evaluate the predicate:
          a > 0
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i4) prederror: false$
          (%i5) is (a > 0);
          (%o5)                        unknown


 -- Function: killcontext (<context_1>, ..., <context_n>)
     Kills the contexts <context_1>, ..., <context_n>.

     If one of the contexts is the current context, the new current
     context will become the first available subcontext of the current
     context which has not been killed.  If the first available
     unkilled context is `global' then `initial' is used instead.  If
     the `initial' context is killed, a new, empty `initial' context is
     created.

     `killcontext' refuses to kill a context which is currently active,
     either because it is a subcontext of the current context, or by
     use of the function `activate'.

     `killcontext' evaluates its arguments.  `killcontext' returns
     `done'.


 -- Function: maybe (<expr>)
     Attempts to determine whether the predicate <expr> is provable
     from the facts in the `assume' database.

     If the predicate is provably `true' or `false', `maybe' returns
     `true' or `false', respectively.  Otherwise, `maybe' returns
     `unknown'.

     `maybe' is functionally equivalent to `is' with `prederror:
     false', but the result is computed without actually assigning a
     value to `prederror'.

     See also `assume', `facts', and `is'.

     Examples:

          (%i1) maybe (x > 0);
          (%o1)                        unknown
          (%i2) assume (x > 1);
          (%o2)                        [x > 1]
          (%i3) maybe (x > 0);
          (%o3)                         true


 -- Function: newcontext (<name>)
     Creates a new, empty context, called <name>, which has `global' as
     its only subcontext.  The newly-created context becomes the
     currently active context.

     `newcontext' evaluates its argument.  `newcontext' returns <name>.


 -- Function: sign (<expr>)
     Attempts to determine the sign of <expr> on the basis of the facts
     in the current data base.  It returns one of the following
     answers: `pos' (positive), `neg' (negative), `zero', `pz'
     (positive or zero), `nz' (negative or zero), `pn' (positive or
     negative), or `pnz' (positive, negative, or zero, i.e. nothing
     known).


 -- Function: supcontext (<name>, <context>)
 -- Function: supcontext (<name>)
     Creates a new context, called <name>, which has <context> as a
     subcontext.  <context> must exist.

     If <context> is not specified, the current context is assumed.



File: maxima.info,  Node: Functions and Variables for Predicates,  Prev: Functions and Variables for Facts,  Up: Maximas Database

11.4 Functions and Variables for Predicates
===========================================

 -- Function: charfun (<p>)
     Return 0 when the predicate <p> evaluates to `false'; return 1 when
     the predicate evaluates to `true'.  When the predicate evaluates to
     something other than `true' or `false' (unknown),  return a noun
     form.

     Examples:

          (%i1) charfun (x < 1);
          (%o1)                    charfun(x < 1)
          (%i2) subst (x = -1, %);
          (%o2)                           1
          (%i3) e : charfun ('"and" (-1 < x, x < 1))$
          (%i4) [subst (x = -1, e), subst (x = 0, e), subst (x = 1, e)];
          (%o4)                       [0, 1, 0]


 -- Function: compare (<x>, <y>)
     Return a comparison operator <op> (`<', `<=', `>', `>=', `=', or
     `#') such that `is (<x> <op> <y>)' evaluates to `true'; when
     either <x> or <y> depends on `%i' and `<x> # <y>', return
     `notcomparable'; when there is no such operator or Maxima isn't
     able to determine the operator, return `unknown'.

     Examples:

          (%i1) compare (1, 2);
          (%o1)                           <
          (%i2) compare (1, x);
          (%o2)                        unknown
          (%i3) compare (%i, %i);
          (%o3)                           =
          (%i4) compare (%i, %i + 1);
          (%o4)                     notcomparable
          (%i5) compare (1/x, 0);
          (%o5)                           #
          (%i6) compare (x, abs(x));
          (%o6)                          <=

     The function `compare' doesn't try to determine whether the real
     domains of its arguments are nonempty; thus

          (%i1) compare (acos (x^2 + 1), acos (x^2 + 1) + 1);
          (%o1)                           <

     The real domain of `acos (x^2 + 1)' is empty.


 -- Function: equal (<a>, <b>)
     Represents equivalence, that is, equal value.

     By itself, `equal' does not evaluate or simplify.  The function
     `is' attempts to evaluate `equal' to a Boolean value.
     `is(equal(<a>, <b>))' returns `true' (or `false') if and only if
     <a> and <b> are equal (or not equal) for all possible values of
     their variables, as determined by evaluating `ratsimp(<a> - <b>)';
     if `ratsimp' returns 0, the two expressions are considered
     equivalent.  Two expressions may be equivalent even if they are
     not syntactically equal (i.e., identical).

     When `is' fails to reduce `equal' to `true' or `false', the result
     is governed by the global flag `prederror'.  When `prederror' is
     `true', `is' complains with an error message.  Otherwise, `is'
     returns `unknown'.

     In addition to `is', some other operators evaluate `equal' and
     `notequal' to `true' or `false', namely `if', `and', `or', and
     `not'.

     The negation of `equal' is `notequal'.

     Examples:

     By itself, `equal' does not evaluate or simplify.

          (%i1) equal (x^2 - 1, (x + 1) * (x - 1));
                                  2
          (%o1)            equal(x  - 1, (x - 1) (x + 1))
          (%i2) equal (x, x + 1);
          (%o2)                    equal(x, x + 1)
          (%i3) equal (x, y);
          (%o3)                      equal(x, y)

     The function `is' attempts to evaluate `equal' to a Boolean value.
     `is(equal(<a>, <b>))' returns `true' when `ratsimp(<a> - <b>)'
     returns 0.  Two expressions may be equivalent even if they are not
     syntactically equal (i.e., identical).

          (%i1) ratsimp (x^2 - 1 - (x + 1) * (x - 1));
          (%o1)                           0
          (%i2) is (equal (x^2 - 1, (x + 1) * (x - 1)));
          (%o2)                         true
          (%i3) is (x^2 - 1 = (x + 1) * (x - 1));
          (%o3)                         false
          (%i4) ratsimp (x - (x + 1));
          (%o4)                          - 1
          (%i5) is (equal (x, x + 1));
          (%o5)                         false
          (%i6) is (x = x + 1);
          (%o6)                         false
          (%i7) ratsimp (x - y);
          (%o7)                         x - y
          (%i8) is (equal (x, y));
          (%o8)                        unknown
          (%i9) is (x = y);
          (%o9)                         false

     When `is' fails to reduce `equal' to `true' or `false', the result
     is governed by the global flag `prederror'.

          (%i1) [aa : x^2 + 2*x + 1, bb : x^2 - 2*x - 1];
                              2             2
          (%o1)             [x  + 2 x + 1, x  - 2 x - 1]
          (%i2) ratsimp (aa - bb);
          (%o2)                        4 x + 2
          (%i3) prederror : true;
          (%o3)                         true
          (%i4) is (equal (aa, bb));
          Maxima was unable to evaluate the predicate:
                 2             2
          equal(x  + 2 x + 1, x  - 2 x - 1)
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i5) prederror : false;
          (%o5)                         false
          (%i6) is (equal (aa, bb));
          (%o6)                        unknown

     Some operators evaluate `equal' and `notequal' to `true' or
     `false'.

          (%i1) if equal (y, y - 1) then FOO else BAR;
          (%o1)                          BAR
          (%i2) eq_1 : equal (x, x + 1);
          (%o2)                    equal(x, x + 1)
          (%i3) eq_2 : equal (y^2 + 2*y + 1, (y + 1)^2);
                                   2                   2
          (%o3)             equal(y  + 2 y + 1, (y + 1) )
          (%i4) [eq_1 and eq_2, eq_1 or eq_2, not eq_1];
          (%o4)                  [false, true, true]

     Because `not <expr>' causes evaluation of <expr>, `not equal(<a>,
     <b>)' is equivalent to `is(notequal(<a>, <b>))'.

          (%i1) [notequal (2*z, 2*z - 1), not equal (2*z, 2*z - 1)];
          (%o1)            [notequal(2 z, 2 z - 1), true]
          (%i2) is (notequal (2*z, 2*z - 1));
          (%o2)                         true


 -- Function: notequal (<a>, <b>)
     Represents the negation of `equal(<a>, <b>)'.

     Examples:

          (%i1) equal (a, b);
          (%o1)                      equal(a, b)
          (%i2) maybe (equal (a, b));
          (%o2)                        unknown
          (%i3) notequal (a, b);
          (%o3)                    notequal(a, b)
          (%i4) not equal (a, b);
          (%o4)                    notequal(a, b)
          (%i5) maybe (notequal (a, b));
          (%o5)                        unknown
          (%i6) assume (a > b);
          (%o6)                        [a > b]
          (%i7) equal (a, b);
          (%o7)                      equal(a, b)
          (%i8) maybe (equal (a, b));
          (%o8)                         false
          (%i9) notequal (a, b);
          (%o9)                    notequal(a, b)
          (%i10) maybe (notequal (a, b));
          (%o10)                        true


 -- Function: unknown (<expr>)
     Returns `true' if and only if <expr> contains an operator or
     function not recognized by the Maxima simplifier.


 -- Function: zeroequiv (<expr>, <v>)
     Tests whether the expression <expr> in the variable <v> is
     equivalent to zero, returning `true', `false', or `dontknow'.

     `zeroequiv' has these restrictions:

       1. Do not use functions that Maxima does not know how to
          differentiate and evaluate.

       2. If the expression has poles on the real line, there may be
          errors in the result (but this is unlikely to occur).

       3. If the expression contains functions which are not solutions
          to first order differential equations (e.g. Bessel functions)
          there may be incorrect results.

       4. The algorithm uses evaluation at randomly chosen points for
          carefully selected subexpressions.  This is always a somewhat
          hazardous business, although the algorithm tries to minimize
          the potential for error.

     For example `zeroequiv (sin(2 * x) - 2 * sin(x) * cos(x), x)'
     returns `true' and `zeroequiv (%e^x + x, x)' returns `false'.  On
     the other hand `zeroequiv (log(a * b) - log(a) - log(b), a)'
     returns `dontknow' because of the presence of an extra parameter
     `b'.



File: maxima.info,  Node: Plotting,  Next: File Input and Output,  Prev: Maximas Database,  Up: Top

12 Plotting
***********

* Menu:

* Introduction to Plotting::
* Plotting Formats::
* Functions and Variables for Plotting::
* Plotting Options::
* Gnuplot Options::
* Gnuplot_pipes Format Functions::


File: maxima.info,  Node: Introduction to Plotting,  Next: Plotting Formats,  Prev: Plotting,  Up: Plotting

12.1 Introduction to Plotting
=============================

Maxima uses an external plotting package to make the plots (see the
section on Plotting formats).  The plotting functions calculate a set of
points and pass them to the plotting package together with a set of
commands.  That information can be passed to the external program either
through a pipe or by calling the program with the name of a file where
the data has been saved.  The data file is given the name
`maxout.interface', where `interface' is the name of the plotting
interface being used (gnuplot, xmaxima, mgnuplot or gnuplot_pipes).

   There are options that can be used to save the plot in a graphic
format file. In those cases, the file `maxout.interface' will be created
and then executed by the external plotting program to save the result in
another file; if the name of that graphic file is not given by the
options used, the default name `maxplot.format' will be used, where
`format' is the format being used.

   The `maxout.interface' and `maxplot.format' files (or the plot name
given by the options), in the cases when they are used, are created in
the directory specified by the system variable `maxima_tempdir'. That
location can be changed; by assigning to that variable (or to the
environment variable MAXIMA_TEMPDIR) a string that represents a valid
directory where Maxima can create new files. The name of the file, or
files, created will be shown as the output of the plotting command.

   After a plot has been created, the file `maxout.interface' can be
executed again with the appropriate external program.  If a Maxima
plotting command fails to show anything, that file can be inspected to
look for possible sources of problems.

   Together with the plotting functions described in this chapter,
package *note draw:: adds other functionalities.  Note that some
plotting options are named equal in both plotting contexts, but with
different syntax; if you want to access the draw information related to
these options, you have to type `?? opt', where `opt' is the name of
the option.


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

12.2 Plotting Formats
=====================

There are currently two external plotting programs that Maxima use:
Gnuplot and Xmaxima.  There are various different formats for those
programs, which can be selected with the option `plot_format' (see the
Plotting Options section).

   The plotting formats are the following:

   * *gnuplot* (default on Windows)

     Used to launch the external program gnuplot, which must be
     installed in your system.  All plotting commands and data are
     saved into the file `maxout.gnuplot'.

   * *gnuplot_pipes* (default on non-Windows platforms)

     This format is not available in Windows platforms.  It is similar
     to the `gnuplot' format except that the commands are sent to
     gnuplot through a pipe, while the data are saved into the file
     `maxout.gnuplot_pipes'.  A single gnuplot process is kept open and
     subsequent plot commands will be sent to the same process,
     replacing previous plots, unless the gnuplot pipe is closed with
     the function `gnuplot_close'.  When this format is used, the
     function `gnuplot_replot' can be used to modify a plot that has
     already displayed on the screen.

     This format is only used to plot to the screen; whenever graphic
     files are created, the format will be switched automatically to
     `gnuplot' and the gnuplot commands needed to created the graphic
     file will be saved in `maxout.gnuplot'.

   * *mgnuplot*

     Mgnuplot is a Tk-based wrapper around gnuplot.  It is included in
     the Maxima distribution.  Mgnuplot offers a rudimentary GUI for
     gnuplot, but has fewer overall features than the plain gnuplot
     interface.  Mgnuplot requires an external gnuplot installation
     and, in Unix systems, the Tcl/Tk system.

   * *xmaxima*

     Xmaxima is a Tcl/Tk graphical interface for Maxima that can also
     be used to display plots created when Maxima is run from the
     console or from other graphical interfaces.  To use this format,
     the xmaxima program, which is distributed together with Maxima,
     should be installed.  If Maxima is being run from xmaxima itself,
     this format will make the plot functions send the data and
     commands through the same socket used for the communication
     between Maxima and Xmaxima.  When used from the console or from
     other interface, the commands and data will be saved in the file
     `maxout.xmaxima', and the xmaxima program will be launched with the
     name of the location of that file as argument.

     In previous versions this format used to be called `openmath'; that
     old name will still be accepted as a synonym for `xmaxima'.


File: maxima.info,  Node: Functions and Variables for Plotting,  Next: Plotting Options,  Prev: Plotting Formats,  Up: Plotting

12.3 Functions and Variables for Plotting
=========================================

 -- Function: contour_plot (<expr>, <x_range>, <y_range>, <options>,
          ...)
     It plots the contours (curves of equal value) of <expr> over the
     region <x_range> by <y_range>.  Any additional arguments are
     treated the same as in `plot3d'.

     This function only works when the plot format is either `gnuplot'
     or `gnuplot_pipes'.  The additional package `implicit_plot' can
     also be used to plot contours and it works for any format.  See
     `implicit_plot'.

     Examples:

          (%i1) contour_plot (x^2 + y^2, [x, -4, 4], [y, -4, 4])$

     You can add any options accepted by `plot3d'; for instance, the
     option `legend' with a value of false, to remove the legend.
     Gnuplot chooses, by default, 3 contours to show.  To increase the
     number of levels, it is necessary to specify a custom gnuplot
     preamble:

          (%i1) contour_plot (u^3 + v^2, [u, -4, 4], [v, -4, 4],
                        [legend,false],
                        [gnuplot_preamble, "set cntrparam levels 12"])$


 -- Function: get_plot_option (<keyword>, <index>)
     Returns the current default value of the option named <keyword>.  A
     value of 1 for the index will return the keyword itself, a value
     of 2 returns the first parameter following the keyword, and so on.

     See also `set_plot_option', `remove_plot_option' and the section
     on Plotting Options.

 -- System variable: gnuplot_command
     This variable stores the name of the command used to run the
     gnuplot program when the plot format is `gnuplot'. Its default
     value is "wgnuplot" in Windows and "gnuplot" in other systems. If
     the gnuplot program is not found unless you give its complete path
     or if you want to try a different version of it, you may change
     the value of this variable. For instance,

          (%i1) gnuplot_command: "/usr/local/bin/my_gnuplot"$


 -- System variable: gnuplot_file_args
     When the a graphic file is going to be created using `gnuplot',
     this variable is used to specify the way the file name should be
     passed to gnuplot. Its default value is "~s", which means that
     that the name of the file will be passed directly. The contents of
     this variable can be changed in order to add options for the
     gnuplot program, adding those options before the string "~s".


 -- System variable: gnuplot_view_args
     This variable is used to parse the argument that will be passed to
     the gnuplot program when the plot format is `gnuplot'. Its default
     value is "-persist ~s", where "~s" will be replaced with the name
     of the file where the gnuplot commands have been written (usually
     "maxout.gnuplot"). The option `-persist' tells gnuplot to exit
     after the commands in the file have been executed, without closing
     the window that displays the plot.

     Those familiar with gnuplot, might want to change the value of this
     variable. For example, by changing it to:

          (%i1) gnuplot_view_args: "~s -"$

     gnuplot will not be closed after the commands in the file have been
     executed; thus, the window with the plot will remain, as well as
     the gnuplot interactive shell where other commands can be issued
     in order to modify the plot.

     In Windows versions of gnuplot older than 4.6.3 the behavior of
     "~s -" and "-persist ~s" were the opposite; namely, "-persist ~s"
     made the plot window and the gnuplot interactive shell remain,
     while "~s -" closed the gnuplot shell keeping the plot window.
     Therefore, when older gnuplot versions are used in Windows, it
     might be necessary to adjust the value of `gnuplot_view_args'.


 -- Function: implicit_plot (<expr>, <x_range>, <y_range>)
 -- Function: implicit_plot ([<expr_1>, ..., <expr_n>], <x_range>,
          <y_range>)
     Displays a plot of one or more expressions in implicit form.
     <expr> is the expression to be plotted, <x_range> the range of the
     horizontal axis and <y_range> the range of vertical axis.
     `implicit_plot' respects global setting for the Gnuplot driver set
     by the <set_plot_option> function.  Options can also be passed to
     `implicit_plot' function as optional arguments.

     `implicit_plot' works by tracking sign changes on the area given
     by <x_range> and <y_range> and can fail for complicated
     expressions.

     `load(implicit_plot)' loads this function.

     Example:
          (%i1) load(implicit_plot)$
          (%i2) implicit_plot (x^2 = y^3 - 3*y + 1, [x, -4, 4], [y, -4, 4])$


 -- Function: julia (<x>, <y>, ...<options>...)
     Creates a graphic representation of the Julia set for the complex
     number (<x> + i <y>). The two mandatory parameters <x> and <y>
     must be real. This program is part of the additional package
     `dynamics', but that package does not have to be loaded; the first
     time julia is used, it will be loaded automatically.

     Each pixel in the grid is given a color corresponding to the
     number of iterations it takes the sequence that starts at that
     point to move out of the convergence circle of radius 2 centered
     at the origin. The number of pixels in the grid is controlled by
     the `grid' plot option (default 30 by 30). The maximum number of
     iterations is set with the option `iterations'. The program uses
     its own default palette: magenta,violet, blue, cyan, green,
     yellow, orange, red, brown and black, but it can be changed by
     adding an explicit `palette' option in the command.

     The default domain used goes from -2 to 2 in both axes and can be
     changed with the `x' and `y' options. By default, the two axes are
     shown with the same scale, unless the option `yx_ratio' is used or
     the option `same_xy' is disabled. Other general plot options are
     also accepted.

     The following example shows a region of the Julia set for the
     number -0.55 + i0.6. The option `color_bar_tics' is used to prevent
     Gnuplot from adjusting the color box up to 40, in which case the
     points corresponding the maximum 36 iterations would not be black.

          (%i1) julia (-0.55, 0.6, [iterations, 36], [x, -0.3, 0.2], [y, 0.3, 0.9],
                [grid, 400, 400], [color_bar_tics, 0, 6, 36])$


 -- Function: make_transform ([<var1>, <var2>, <var3>], <fx>, <fy>,
          <fz>)
     Returns a function suitable to be used in the option `transform_xy'
     of plot3d.  The three variables <var1>, <var2>, <var3> are three
     dummy variable names, which represent the 3 variables given by the
     plot3d command (first the two independent variables and then the
     function that depends on those two variables).  The three functions
     <fx>, <fy>, <fz> must depend only on those 3 variables, and will
     give the corresponding x, y and z coordinates that should be
     plotted.  There are two transformations defined by default:
     `polar_to_xy' and `spherical_to_xyz'. See the documentation for
     those two transformations.


 -- Function: mandelbrot (<options>)
     Creates a graphic representation of the Mandelbrot set. This
     program is part of the additional package `dynamics', but that
     package does not have to be loaded; the first time mandelbrot is
     used, the package will be loaded automatically.

     This program can be called without any arguments, in which case it
     will use a default value of 9 iterations per point, a grid with
     dimensions set by the `grid' plot option (default 30 by 30) and a
     region that extends from -2 to 2 in both axes. The options are all
     the same that plot2d accepts, plus an option `iterations' to
     change the number of iterations.

     Each pixel in the grid is given a color corresponding to the
     number of iterations it takes the sequence starting at zero to
     move out of the convergence circle of radius 2, centered at the
     origin. The maximum number of iterations is set by the option
     `iterations'.  The program uses its own default palette:
     magenta,violet, blue, cyan, green, yellow, orange, red, brown and
     black, but it can be changed by adding an explicit `palette'
     option in the command. By default, the two axes are shown with the
     same scale, unless the option `yx_ratio' is used or the option
     `same_xy' is disabled.

     Example:

          (%i1) mandelbrot ([iterations, 30], [x, -2, 1], [y, -1.2, 1.2], [grid,400,400])$


 -- System function: polar_to_xy
     It can be given as value for the `transform_xy' option of plot3d.
     Its effect will be to interpret the two independent variables in
     plot3d as the distance from the z axis and the azimuthal angle
     (polar coordinates), and transform them into x and y coordinates.


 -- Function: plot2d (<plot>, <x_range>, ..., <options>, ...)
 -- Function: plot2d ([<plot_1>, ..., <plot_n>], ..., <options>, ...)
 -- Function: plot2d ([<plot_1>, ..., <plot_n>], <x_range>, ...,
          <options>, ...)
     Where <plot>, <plot_1>, ..., <plot_n> can be either expressions,
     function names or a list with the any of the forms: `[discrete,
     [<x1>, ..., <xn>], [<y1>, ..., <yn>]]', `[discrete, [[<x1>, <y1>],
     ..., [<xn>, ..., <yn>]]]' or `[parametric, <x_expr>, <y_expr>,
     <t_range>]'.

     Displays a plot of one or more expressions as a function of one
     variable or parameter.

     `plot2d' displays one or several plots in two dimensions.  When
     expressions or function name are used to define the plots, they
     should all depend on only one variable <var> and the use of
     <x_range> will be mandatory, to provide the name of the variable
     and its minimum and maximum values; the syntax for <x_range> is:
     `[<variable>, <min>, <max>]'.

     A plot can also be defined in the discrete or parametric forms.
     The discrete form is used to plot a set of points with given
     coordinates.  A discrete plot is defined by a list starting with
     the keyword <discrete>, followed by one or two lists of values.
     If two lists are given, they must have the same length; the first
     list will be interpreted as the x coordinates of the points to be
     plotted and the second list as the y coordinates.  If only one
     list is given after the <discrete> keyword, each element on the
     list could also be a list with two values that correspond to the x
     and y coordinates of a point, or it could be a sequence o
     numerical values which will be plotted at consecutive integer
     values (1,2,3,...) on the x axis.

     A parametric plot is defined by a list starting with the keyword
     <parametric>, followed by two expressions or function names and a
     range for the parameter.  The range for the parameter must be a
     list with the name of the parameter followed by its minimum and
     maximum values: `[<param>, <min>, <max>]'.  The plot will show the
     path traced out by the point with coordinates given by the two
     expressions or functions, as <param> increases from <min> to <max>.

     A range for the vertical axis is an optional argument with the
     form: `[y, <min>, <max>]' (the keyword <y> is always used for the
     vertical axis).  If that option is used, the plot will show that
     exact vertical range, independently of the values reached by the
     plot.  If the vertical range is not specified, it will be set up
     according to the minimum and maximum values of the second
     coordinate of the plot points.

     All other options should also be lists, starting with a keyword and
     followed by one or more values.  See `plot_options'.

     If there are several plots to be plotted, a legend will be written
     to identity each of the expressions.  The labels that should be
     used in that legend can be given with the option `legend'.  If that
     option is not used, Maxima will create labels from the expressions
     or function names.

     *Examples:*

     Plot of a common function:

          (%i1) plot2d (sin(x), [x, -%pi, %pi])$

     If the function grows too fast, it might be necessary to limit the
     values in the vertical axis using the `y' option:

          (%i1) plot2d (sec(x), [x, -2, 2], [y, -20, 20])$

     When the plot box is disabled, no labels are created for the axes.
     In that case, instead of using `xlabel' and `ylabel' to set the
     names of the axes, it is better to use option `label', which
     allows more flexibility. Option `yx_ratio' is used to change the
     default rectangular shape of the plot; in this example the plot
     will fill a square.

          (%i1) plot2d ( x^2 - 1, [x, -3, 3], [box, false], grid2d, [yx_ratio, 1],
                [axes, solid], [xtics, -2, 4, 2], [ytics, 2, 2, 6],
                [label, ["x", 2.9, -0.3], ["x^2-1", 0.1, 8]], [title, "A parabola"])$

     A plot with a logarithmic scale in the vertical axis:

          (%i1) plot2d (exp(3*s), [s, -2, 2], logy)$

     Plotting functions by name:

          (%i1) F(x) := x^2 $
          (%i2) :lisp (defun |$g| (x) (m* x x x))
          $g
          (%i2) H(x) := if x < 0 then x^4 - 1 else 1 - x^5 $
          (%i3) plot2d ([F, G, H], [u, -1, 1], [y, -1.5, 1.5])$

     A plot of the butterfly curve, defined parametrically:

          (%i1) r: (exp(cos(t))-2*cos(4*t)-sin(t/12)^5)$
          (%i2) plot2d([parametric, r*sin(t), r*cos(t), [t, -8*%pi, 8*%pi]])$

     Plot of a circle, using its parametric representation, together
     with the function -|x|. The circle will only look like a circle if
     the scale in the two axes is the same, which is done with the
     option `same_xy'.

          (%i1) plot2d([[parametric, cos(t), sin(t), [t,0,2*%pi]], -abs(x)],
                   [x, -sqrt(2), sqrt(2)], same_xy)$

     A plot of 200 random numbers between 0 and 9:

          (%i1) plot2d ([discrete, makelist ( random(10), 200)])$

     A plot of a discrete set of points, defining x and y coordinates
     separately:

          (%i1) plot2d ([discrete, makelist(i*%pi, i, 1, 5), [.6, .9, 0.2, 1.3, 1]])$

     In the next example a table with three columns is saved in a file
     "data.txt" which is then read and the second and third column are
     plotted on the two axes:

          (%i1) with_stdout ("data.txt", for x:0 thru 10 do
                                       print (x, x^2, x^3))$
          (%i2) data: read_matrix ("data.txt")$
          (%i3) plot2d ([discrete, transpose(data)[2], transpose(data)[3]],
            [style,points], [point_type,diamond], [color,red])$

     A plot of discrete data points together with a continuous function:

          (%i1) xy: [[10, .6], [20, .9], [30, 1.1], [40, 1.3], [50, 1.4]]$
          (%i2) plot2d([[discrete, xy], 2*%pi*sqrt(l/980)], [l,0,50],
                  [style, points, lines], [color, red, blue],
                  [point_type, asterisk],
                  [legend, "experiment", "theory"],
                  [xlabel, "pendulum's length (cm)"],
                  [ylabel, "period (s)"])$

     See also the section about Plotting Options.


 -- Function: plot3d (<expr>, <x_range>, <y_range>, ..., <options>, ...)
 -- Function: plot3d ([<expr_1>, ..., <expr_n>], <x_range>, <y_range>,
          ..., <options>, ...)
     Displays a plot of one or more surfaces defined as functions of two
     variables or in parametric form.

     The functions to be plotted may be specified as expressions or
     function names.  The mouse can be used to rotate the plot looking
     at the surface from different sides.

     *Examples:*

     Plot of a function of two variables:

          (%i1) plot3d (u^2 - v^2, [u, -2, 2], [v, -3, 3], [grid, 100, 100],
                  [mesh_lines_color,false])$

     Use of the `z' option to limit a function that goes to infinity
     (in this case the function is minus infinity on the x and y axes);
     this also shows how to plot with only lines and no shading:

          (%i1) plot3d ( log ( x^2*y^2 ), [x, -2, 2], [y, -2, 2], [z, -8, 4],
                   [palette, false], [color, magenta])$

     The infinite values of z can also be avoided by choosing a grid
     that does not fall on any asymptotes; next example also shows how
     to change the palette and how to show the color bar that relates
     the colors used with the values of the z variable:

          (%i1) plot3d (log (x^2*y^2), [x, -2, 2], [y, -2, 2],[grid, 29, 29],
                 [palette, [gradient, red, orange, yellow, green]], color_bar,
                 [xtics, 1], [ytics, 1], [ztics, 4],[color_bar_tics, 4])$

     Two surfaces in the same plot. Ranges specific to one of the
     surfaces can be given by placing the expression and the ranges
     inside a common list; in this example each surface is defined in a
     domain different from the domain of the complete plot.

          (%i1) plot3d ([[-3*x - y, [x, -2, 2], [y, -2, 2]],
             4*sin(3*(x^2 + y^2))/(x^2 + y^2), [x, -3, 3], [y, -3, 3]],
             [x, -4, 4], [y, -4, 4])$

     Plot of a Klein bottle, defined parametrically:

          (%i1) expr_1: 5*cos(x)*(cos(x/2)*cos(y) + sin(x/2)*sin(2*y) + 3.0) - 10.0$
          (%i2) expr_2: -5*sin(x)*(cos(x/2)*cos(y) + sin(x/2)*sin(2*y) + 3.0)$
          (%i3) expr_3: 5*(-sin(x/2)*cos(y) + cos(x/2)*sin(2*y))$
          (%i4) plot3d ([expr_1, expr_2, expr_3], [x, -%pi, %pi],
                  [y, -%pi, %pi], [grid, 50, 50])$

     Plot of a "spherical harmonic" function, using the predefined
     transformation, `spherical_to_xyz' to transform from spherical
     coordinates to rectangular coordinates. See the documentation for
     `spherical_to_xyz'.

          (%i1) plot3d (sin(2*theta)*cos(phi), [theta, 0, %pi],
                  [phi, 0, 2*%pi],
                  [transform_xy, spherical_to_xyz], [grid,30,60],
             [legend,false])$

     Use of the pre-defined function `polar_to_xy' to transform from
     cylindrical to rectangular coordinates.  See the documentation for
     `polar_to_xy'.

          (%i1) plot3d (r^.33*cos(th/3), [r, 0, 1], [th, 0, 6*%pi], [box, false],
             [grid, 12, 80], [transform_xy, polar_to_xy], [legend, false])$

     Plot of a sphere using the transformation from spherical to
     rectangular coordinates. Option `same_xyz' is used to get the
     three axes scaled in the same proportion. When transformations are
     used, it is not convenient to eliminate the mesh lines, because
     Gnuplot will not show the surface correctly.

          (%i1) plot3d ( 5, [theta, 0, %pi], [phi, 0, 2*%pi], same_xyz,
            [transform_xy, spherical_to_xyz], [mesh_lines_color,blue],
            [palette,[gradient,"#1b1b4e", "#8c8cf8"]], [legend, false])$

     Definition of a function of two-variables using a matrix.  Notice
     the single quote in the definition of the function, to prevent
     plot3d from failing when it realizes that the matrix will require
     integer indices.

          (%i1) M: matrix([1, 2, 3, 4], [1, 2, 3, 2], [1, 2, 3, 4], [1, 2, 3, 3])$
          (%i2) f(x, y) := float('M [round(x), round(y)])$
          (%i3) plot3d (f(x,y), [x, 1, 4], [y, 1, 4], [grid, 3, 3], [legend, false])$

     By setting the elevation equal to zero, a surface can be seen as a
     map in which each color represents a different level.

          (%i1) plot3d (cos (-x^2 + y^3/4), [x, -4, 4], [y, -4, 4], [zlabel, ""],
                  [mesh_lines_color, false], [elevation, 0], [azimuth, 0],
                  color_bar, [grid, 80, 80], [ztics, false], [color_bar_tics, 1])$

     See also the section about Plotting Options.


 -- System variable: plot_options
     This option is being kept for compatibility with older versions,
     but its use is deprecated. To set global plotting options, see
     their current values or remove options, use `set_plot_option',
     `get_plot_option' and `remove_plot_option'.


 -- Function: remove_plot_option (<name>)
     Removes the default value of an option. The name of the option
     must be given.

     See also `set_plot_option', `get_plot_option' and the section on
     Plotting Options.


 -- Function: set_plot_option (<option>)
     Accepts any of the options listed in the section Plotting Options,
     and saves them for use in plotting commands. The values of the
     options set in each plotting command will have precedence, but if
     those options are not given, the default values set with this
     function will be used.

     `set_plot_option' evaluates its argument and returns the complete
     list of options (after modifying the option given). If called
     without any arguments, it will simply show the list of current
     default options.

     See also `remove_plot_option', `get_plot_option' and the section
     on Plotting Options.

     Example:

     Modification of the `grid' values.

          (%i1) set_plot_option ([grid, 30, 40]);
          (%o1) [[plot_format, gnuplot_pipes], [grid, 30, 40],
          [run_viewer, true], [axes, true], [nticks, 29], [adapt_depth, 5],
          [color, blue, red, green, magenta, black, cyan],
          [point_type, bullet, box, triangle, plus, times, asterisk],
          [palette, [gradient, green, cyan, blue, violet],
          [gradient, magenta, violet, blue, cyan, green, yellow, orange,
          red, brown, black]], [gnuplot_preamble, ], [gnuplot_term, default]]


 -- System function: spherical_to_xyz
     It can be given as value for the `transform_xy' option of
     `plot3d'. Its effect will be to interpret the two independent
     variables and the function in `plot3d' as the spherical coordinates
     of a point (first, the angle with the z axis, then the angle of
     the xy projection with the x axis and finally the distance from
     the origin) and transform them into x, y and z coordinates.



File: maxima.info,  Node: Plotting Options,  Next: Gnuplot Options,  Prev: Functions and Variables for Plotting,  Up: Plotting

12.4 Plotting Options
=====================

All options consist of a list starting with one of the keywords in this
section, followed by one or more values. Some of the options may have
different effects in different plotting commands as it will be pointed
out in the following list. The options that accept among their possible
values true or false, can also be set to true by simply writing their
names. For instance, typing logx as an option is equivalent to writing
[logx, true].

 -- Plot option: adapt_depth [adapt_depth, <integer>]
     Default value: `5'

     The maximum number of splittings used by the adaptive plotting
     routine.


 -- Plot option: axes [axes, <symbol>]
     Default value: `true'

     Where <symbol> can be either `true', `false', `x', `y' or `solid'.
     If `false', no axes are shown; if equal to `x' or `y' only the x
     or y axis will be shown; if it is equal to `true', both axes will
     be shown and `solid' will show the two axes with a solid line,
     rather than the default broken line. This option does not have any
     effect in the 3 dimensional plots.


 -- Plot option: azimuth [azimuth, <number>]
     Default value: `30'

     A plot3d plot can be thought of as starting with the x and y axis
     in the horizontal and vertical axis, as in plot2d, and the z axis
     coming out of the screen.  The z axis is then rotated around the x
     axis through an angle equal to `elevation' and then the new xy
     plane is rotated around the new z axis through an angle `azimuth'.
     This option sets the value for the azimuth, in degrees.

     See also `elevation'.


 -- Plot option: box [box, <symbol>]
     Default value: `true'

     If set to `true', a bounding box will be drawn for the plot; if set
     to `false', no box will be drawn.


 -- Plot option: color [color, <color_1>, ..., <color_n>]
     In 2d plots it defines the color (or colors) for the various
     curves.  In `plot3d', it defines the colors used for the mesh
     lines of the surfaces, when no palette is being used.

     If there are more curves or surfaces than colors, the colors will
     be repeated in sequence. The valid colors are `red', `green',
     `blue', `magenta', `cyan', `yellow', `orange', `violet', `brown',
     `gray', `black', `white', or a string starting with the character
     # and followed by six hexadecimal digits: two for the red
     component, two for green component and two for the blue component.
     If the name of a given color is unknown color, black will be used
     instead.


 -- Plot option: color_bar [color_bar, <symbol>]
     Default value: `false' in plot3d, `true' in mandelbrot and julia-

     Where <symbol> can be either `true' or `false'.  If `true',
     whenever `plot3d', `mandelbrot' or `julia' use a palette to
     represent different values, a box will be shown on the right,
     showing the corresponding between colors and values.


 -- Plot option: color_bar_tics [color_bar_tics, <x1>, <x2>, <x3>]
     Defines the values at which a mark and a number will be placed in
     the color bar. The first number is the initial value, the second
     the increments and the third is the last value where a mark is
     placed. The second and third numbers can be omitted. When only one
     number is given, it will be used as the increment from an initial
     value that will be chosen automatically


 -- Plot option: elevation [elevation, <number>]
     Default value: `60'

     A plot3d plot can be thought of as starting with the x and y axis
     in the horizontal and vertical axis, as in plot2d, and the z axis
     coming out of the screen.  The z axis is then rotated around the x
     axis through an angle equal to `elevation' and then the new xy
     plane is rotated around the new z axis through an angle `azimuth'.
     This option sets the value for the azimuth, in degrees.

     See also `azimuth'.


 -- Plot option: grid [grid, <integer>, <integer>]
     Default value: `30', `30'

     Sets the number of grid points to use in the x- and y-directions
     for three-dimensional plotting or for the `julia' and `mandelbrot'
     programs.


 -- Plot option: grid2d [grid, <value>]
     Default value: `false'

     Shows a grid of lines on the xy plane. The points where the grid
     lines are placed are the same points where tics are marked in the
     x and y axes, which can be controlled with the `xtics' and `ytics'
     options.


 -- Plot option: iterations [grid, <value>]
     Default value: `9'

     Number of iterations made by the programs mandelbrot and julia.


 -- Plot option: label [label, [<string>, <x>, <y>], ...]
     Writes one or several labels in the points with <x>, <y>
     coordinates indicated after each label.


 -- Plot option: legend [legend, <string_1>, ..., <string_n>]
 -- Plot option: legend [legend, <false>]
     It specifies the labels for the plots when various plots are
     shown.  If there are more plots than the number of labels given,
     they will be repeated.  If given the value `false', no legends
     will be shown.  By default, the names of the expressions or
     functions will be used, or the words discrete1, discrete2, ...,
     for discrete sets of points.


 -- Plot option: logx [logx, <value>]
     Makes the horizontal axes to be scaled logarithmically. It can be
     either true or false.


 -- Plot option: logy [logy, <value>]
     Makes the vertical axes to be scaled logarithmically. It can be
     either true or false.


 -- Plot option: mesh_lines_color [mesh_lines_color, <color>]
     Default value: `black'

     It sets the color used by plot3d to draw the mesh lines, when a
     palette is being used.  It accepts the same colors as for the
     option `color' (see the list of allowed colors in `color').  It
     can also be given a value `false' to eliminate completely the mesh
     lines.


 -- Plot option: nticks [nticks, <integer>]
     Default value: `29'

     When plotting functions with `plot2d', it is gives the initial
     number of points used by the adaptive plotting routine for plotting
     functions.  When plotting parametric functions with `plot3d', it
     sets the number of points that will be shown for the plot.


 -- Plot option: palette [palette, [<palette_1>], ..., [<palette_n>]]
 -- Plot option: palette [palette, <false>]
     It can consist of one palette or a list of several palettes.  Each
     palette is a list with a keyword followed by values. If the
     keyword is gradient, it should be followed by a list of valid
     colors.

     If the keyword is hue, saturation or value, it must be followed by
     4 numbers. The first three numbers, which must be between 0 and 1,
     define the hue, saturation and value of a basic color to be
     assigned to the minimum value of z. The keyword specifies which of
     the three attributes (hue, saturation or value) will be increased
     according to the values of z.  The last number indicates the
     increase corresponding to the maximum value of z.  That last
     number can be bigger than 1 or negative; the corresponding values
     of the modified attribute will be rounded modulo 1.

     Gnuplot only uses the first palette in the list; xmaxima will use
     the palettes in the list sequentially, when several surfaces are
     plotted together; if the number of palettes is exhausted, they
     will be repeated sequentially.

     The color of the mesh lines will be given by the option
     `mesh_lines_color'.  If `palette' is given the value `false', the
     surfaces will not be shaded but represented with a mesh of curves
     only.  In that case, the colors of the lines will be determined by
     the option `color'.


 -- Plot option: plot_format [plot_format, <format>]
     Default value: `gnuplot', in Windows systems, or `gnuplot_pipes' in
     other systems.

     Where <format> is one of the following: gnuplot, xmaxima, mgnuplot
     or gnuplot_pipes.

     It sets the format to be used for plotting.


 -- Plot option: plot_realpart [plot_realpart, <symbol>]
     Default value: `false'

     If set to `true', the functions to be plotted will be considered
     as complex functions whose real value should be plotted; this is
     equivalent to plotting `realpart(<function>)'.  If set to `false',
     nothing will be plotted when the function does not give a real
     value.  For instance, when `x' is negative, `log(x)' gives a
     complex value, with real value equal to `log(abs(x))'; if
     `plot_realpart' were `true', `log(-5)' would be plotted as
     `log(5)', while nothing would be plotted if `plot_realpart' were
     `false'.


 -- Plot option: point_type [point_type, <type_1>, ..., <type_n>]
     In gnuplot, each set of points to be plotted with the style
     "points" or "linespoints" will be represented with objects taken
     from this list, in sequential order.  If there are more sets of
     points than objects in this list, they will be repeated
     sequentially.  The possible objects that can be used are:
     `bullet', `circle', `plus', `times', `asterisk', `box', `square',
     `triangle', `delta', `wedge', `nabla', `diamond', `lozenge'


 -- Plot option: pdf_file [pdf_file, <file_name>]
     Saves the plot into a PDF file with name equal to <file_name>,
     rather than showing it in the screen.  By default, the file will be
     created in the directory defined by the variable `maxima_tempdir',
     unless <file_name> contains the character "/", in which case it
     will be assumed to contain the complete path where the file should
     be created. The value of `maxima_tempdir' can be changed to save
     the file in a different directory. When the option
     `gnuplot_pdf_term_command' is also given, it will be used to set up
     Gnuplot's PDF terminal; otherwise, Gnuplot's pdfcairo terminal
     will be used with solid colored lines of width 3, plot size of
     17.2 cm, 12.9 cm and font of 18 points.


 -- Plot option: png_file [png_file, <file_name>]
     Saves the plot into a PNG graphics file with name equal to
     <file_name>, rather than showing it in the screen. By default, the
     file will be created in the directory defined by the variable
     `maxima_tempdir', unless <file_name> contains the character "/",
     in which case it will be assumed to contain the complete path where
     the file should be created. The value of `maxima_tempdir' can be
     changed to save the file in a different directory. When the option
     `gnuplot_png_term_command' is also given, it will be used to set up
     Gnuplot's PNG terminal; otherwise, Gnuplot's pngcairo terminal
     will be used, with a font of size 12.


 -- Plot option: ps_file [ps_file, <file_name>]
     Saves the plot into a Postscript file with name equal to
     <file_name>, rather than showing it in the screen.  By default,
     the file will be created in the directory defined by the variable
     `maxima_tempdir', unless <file_name> contains the character "/",
     in which case it will be assumed to contain the complete path where
     the file should be created. The value of `maxima_tempdir' can be
     changed to save the file in a different directory. When the option
     `gnuplot_ps_term_command' is also given, it will be used to set up
     Gnuplot's Postscript terminal; otherwise, Gnuplot's postscript
     terminal will be used with the EPS option, solid colored lines of
     width 2, plot size of 16.4 cm by 12.3 cm and font of 24 points.


 -- Plot option: run_viewer [run_viewer, <symbol>]
     This option is only used when the plot format is `gnuplot' and the
     terminal is `default' or when the Gnuplot terminal is set to
     `dumb' (see `gnuplot_term') and can have a true or false value.

     If the terminal is `default', a file `maxout.gnuplot' (or other
     name specified with `gnuplot_out_file') is created with the
     gnuplot commands necessary to generate the plot. Option
     `run_viewer' controls whether or not Gnuplot will be launched to
     execute those commands and show the plot.

     If the terminal is `default', gnuplot is run to execute the
     commands in `maxout.gnuplot', producing another file `maxplot.txt'
     (or other name specified with `gnuplot_out_file'). Option
     `run_viewer' controls whether or not that file, with an ASCII
     representation of the plot, will be shown in the Maxima or Xmaxima
     console.

     The default value for this option is true, making the plots to be
     shown in either the console or a separate graphics window.


 -- Plot option: same_xy [same_xy , <value>]
     It can be either true or false. If true, the scales used in the x
     and y axes will be the same, in either 2d or 3d plots. See also
     `yx_ratio'.


 -- Plot option: same_xyz [same_xyz , <value>]
     It can be either true or false. If true, the scales used in the 3
     axes of a 3d plot will be the same.


 -- Plot option: style [style, <type_1>, ..., <type1_n>]
 -- Plot option: style [style, [<style_1>], ..., [<style_n>]]
     The styles that will be used for the various functions or sets of
     data in a 2d plot.  The word <style> must be followed by one or
     more styles.  If there are more functions and data sets than the
     styles given, the styles will be repeated.  Each style can be
     either <lines> for line segments, <points> for isolated points,
     <linespoints> for segments and points, or <dots> for small
     isolated dots.  Gnuplot accepts also an <impulses> style.

     Each of the styles can be enclosed inside a list with some
     additional parameters.  <lines> accepts one or two numbers: the
     width of the line and an integer that identifies a color.  The
     default color codes are: 1: blue, 2: red, 3: magenta, 4: orange,
     5: brown, 6: lime and 7: aqua.  If you use Gnuplot with a terminal
     different than X11, those colors might be different; for example,
     if you use the option [<gnuplot_term>, <ps>], color index 4 will
     correspond to black, instead of orange.

     <points> accepts one two or three parameters; the first parameter
     is the radius of the points, the second parameter is an integer
     that selects the color, using the same code used for <lines> and
     the third parameter is currently used only by Gnuplot and it
     corresponds to several objects instead of points.  The default
     types of objects are: 1: filled circles, 2: open circles, 3: plus
     signs, 4: x, 5: *, 6: filled squares, 7: open squares, 8: filled
     triangles, 9: open triangles, 10: filled inverted triangles, 11:
     open inverted triangles, 12: filled lozenges and 13: open lozenges.

     <linesdots> accepts up to four parameters: line width, points
     radius, color and type of object to replace the points.

     See also `color' and `point_type'.


 -- Plot option: svg_file [svg_file, <file_name>]
     Saves the plot into an SVG file with name equal to <file_name>,
     rather than showing it in the screen.  By default, the file will be
     created in the directory defined by the variable `maxima_tempdir',
     unless <file_name> contains the character "/", in which case it
     will be assumed to contain the complete path where the file should
     be created. The value of `maxima_tempdir' can be changed to save
     the file in a different directory. When the option
     `gnuplot_svg_term_command' is also given, it will be used to set up
     Gnuplot's SVG terminal; otherwise, Gnuplot's svg terminal will be
     used with font of 14 points.


 -- Plot option: t [t, <min>, <max>]
     Default range for parametric plots.


 -- Plot option: title [title, <text>]
     Defines a title that will be written at the top of the plot.


 -- Plot option: transform_xy [transform_xy, <symbol>]
     Where <symbol> is either `false' or the result obtained by using
     the function `transform_xy'.  If different from `false', it will
     be used to transform the 3 coordinates in plot3d.

     See `make_transform', `polar_to_xy' and `spherical_to_xyz'.


 -- Plot option: x [x, <min>, <max>]
     When used as the first option in a `plot2d' command (or any of the
     first two in `plot3d'), it indicates that the first independent
     variable is x and it sets its range.  It can also be used again
     after the first option (or after the second option in plot3d) to
     define the effective horizontal domain that will be shown in the
     plot.


 -- Plot option: xlabel [xlabel, <string>]
     Specifies the <string> that will label the first axis; if this
     option is not used, that label will be the name of the independent
     variable, when plotting functions with `plot2d' or
     `implicit_plot', or the name of the first variable, when plotting
     surfaces with `plot3d' or contours with `contour_plot', or the
     first expression in the case of a parametric plot.  It can not be
     used with `set_plot_option'.


 -- Plot option: xtics [xtics, <x1>, <x2>, <x3>]
     Defines the values at which a mark and a number will be placed in
     the x axis. The first number is the initial value, the second the
     increments and the third is the last value where a mark is placed.
     The second and third numbers can be omitted. When only one number
     is given, it will be used as the increment from an initial value
     that will be chosen automatically


 -- Plot option: xy_scale [xy_scale, <sx>, <sy>]
     In a 2d plot, it defines the ratio of the total size of the Window
     to the size that will be used for the plot. The two numbers given
     as arguments are the scale factors for the x and y axes.


 -- Plot option: y [y, <min>, <max>]
     When used as one of the first two options in `plot3d', it indicates
     that one of the independent variables is y and it sets its range.
     Otherwise, it defines the effective domain of the second variable
     that will be shown in the plot.


 -- Plot option: ylabel [ylabel, <string>]
     Specifies the <string> that will label the second axis; if this
     option is not used, that label will be "y", when plotting functions
     with `plot2d' or `implicit_plot', or the name of the second
     variable, when plotting surfaces with `plot3d' or contours with
     `contour_plot', or the second expression in the case of a
     parametric plot.  It can not be used with `set_plot_option'.


 -- Plot option: ytics [ytics, <y1>, <y2>, <y3>]
     Defines the values at which a mark and a number will be placed in
     the y axis. The first number is the initial value, the second the
     increments and the third is the last value where a mark is placed.
     The second and third numbers can be omitted. When only one number
     is given, it will be used as the increment from an initial value
     that will be chosen automatically


 -- Plot option: yx_ratio [yx_ratio, <r>]
     In a 2d plot, the ratio between the vertical and the horizontal
     sides of the rectangle used to make the plot. See also `same_xy'.


 -- Plot option: z [z, <min>, <max>]
     Used in `plot3d' to set the effective range of values of z that
     will be shown in the plot.


 -- Plot option: zlabel [zlabel, <string>]
     Specifies the <string> that will label the third axis, when using
     `plot3d'.  If this option is not used, that label will be "z", when
     plotting surfaces, or the third expression in the case of a
     parametric plot.  It can not be used with `set_plot_option' and it
     will be ignored by `plot2d' and `implicit_plot'.


 -- Plot option: zmin [zmin, <z>]
     In 3d plots, the value of z that will be at the bottom of the plot
     box.



File: maxima.info,  Node: Gnuplot Options,  Next: Gnuplot_pipes Format Functions,  Prev: Plotting Options,  Up: Plotting

12.5 Gnuplot Options
====================

There are several plot options specific to gnuplot.  All of them consist
of a keyword (the name of the option), followed by a string that should
be a valid gnuplot command, to be passed directly to gnuplot.  In most
cases, there exist a corresponding plotting option that will produce a
similar result and whose use is more recommended than the gnuplot
specific option.

 -- Plot option: gnuplot_term [gnuplot_term, <terminal_name>]
     Sets the output terminal type for gnuplot. The argument
     <terminal_name> can be a string or one of the following 3 special
     symbols
        * *default* (default value)

          Gnuplot output is displayed in a separate graphical window
          and the gnuplot terminal used will be specified by the value
          of the option `gnuplot_default_term_command'.

        * *dumb*

          Gnuplot output is saved to a file `maxout.gnuplot' using
          "ASCII art" approximation to graphics. If the option
          `gnuplot_out_file' is set to <filename>, the plot will be
          saved there, instead of the default `maxout.gnuplot'. The
          settings for the "dumb" terminal of Gnuplot are given by the
          value of option `gnuplot_dumb_term_command'. If option
          `run_viewer' is set to true and the plot_format is `gnuplot'
          that ASCII representation will also be shown in the Maxima or
          Xmaxima console.

        * *ps*

          Gnuplot generates commands in the PostScript page description
          language.  If the option `gnuplot_out_file' is set to
          <filename>, gnuplot writes the PostScript commands to
          <filename>.  Otherwise, it is saved as `maxplot.ps' file. The
          settings for this terminal of are given by the value of
          option `gnuplot_dumb_term_command'.

        * A string representing any valid gnuplot term specification

          Gnuplot can generate output in many other graphical formats
          such as png, jpeg, svg etc. To use those formats, option
          `gnuplot_term' can be set to any supported gnuplot term name
          (for example symbol) or even a full gnuplot term
          specification with any valid options (string).  For example
          `[gnuplot_term, png]' creates output in PNG (Portable Network
          Graphics) format while `[gnuplot_term, "png size 1000,1000"]'
          creates PNG of 1000 x 1000 pixels size.  If the option
          `gnuplot_out_file' is set to <filename>, gnuplot writes the
          output to <filename>.  Otherwise, it is saved as
          `maxplot.<term>' file, where <term> is gnuplot terminal name.


 -- Plot option: gnuplot_out_file [gnuplot_out_file, <file_name>]
     It can be used to replace the default name for the file that
     contains the commands that will interpreted by gnuplot, when the
     terminal is set to `default', or to replace the default name of
     the graphic file that gnuplot creates, when the terminal is
     different from `default'. If it contains one or more slashes, "/",
     the name of the file will be left as it is; otherwise, it will be
     appended to the path of the temporary directory. The complete name
     of the files created by the plotting commands is always sent as
     output of those commands so they can be seen if the command is
     ended by semi-colon.

     When used in conjunction with the `gnuplot_term' option, it can be
     used to save the plot in a file, in one of the graphic formats
     supported by Gnuplot. To create PNG, PDF, Postscript or SVG, it is
     easier to use options `png_file', `pdf_file', `ps_file', or
     `svg_file'.


 -- Plot option: gnuplot_pm3d [gnuplot_pm3d, <value>]
     With a value of `false', it can be used to disable the use of PM3D
     mode, which is enabled by default.


 -- Plot option: gnuplot_preamble [gnuplot_preamble, <string>]
     This option inserts gnuplot commands before any other commands
     sent to Gnuplot. Any valid gnuplot commands may be used. Multiple
     commands should be separated with a semi-colon. See also
     `gnuplot_postamble'.


 -- Plot option: gnuplot_postamble [gnuplot_postamble, <string>]
     This option inserts gnuplot commands after other commands sent to
     Gnuplot and right before the plot command is sent. Any valid
     gnuplot commands may be used. Multiple commands should be
     separated with a semi-colon. See also `gnuplot_preamble'.


 -- Plot option: gnuplot_default_term_command
     [gnuplot_default_term_command, <command>]

     The gnuplot command to set the terminal type for the default
     terminal. It this option is not set, the command used will be:
     `"set term wxt size 640,480 font \",12\"; set term pop"'.


 -- Plot option: gnuplot_dumb_term_command
     [gnuplot_dumb_term_command, <command>]

     The gnuplot command to set the terminal type for the dumb
     terminal.  It this option is not set, the command used will be:
     `"set term dumb 79 22"', which makes the text output 79 characters
     by 22 characters.


 -- Plot option: gnuplot_pdf_term_command [gnuplot_pdf_term_command,
          <command>]
     The gnuplot command to set the terminal type for the PDF terminal.
     It this option is not set, the command used will be: `"set term
     pdfcairo color solid lw 3 size 17.2 cm, 12.9 cm font \",18\""'.
     See the gnuplot documentation for more information.


 -- Plot option: gnuplot_png_term_command [gnuplot_png_term_command,
          <command>]
     The gnuplot command to set the terminal type for the PNG terminal.
     It this option is not set, the command used will be: `"set term
     pngcairo font \",12\""'. See the gnuplot documentation for more
     information.


 -- Plot option: gnuplot_ps_term_command [gnuplot_ps_term_command,
          <command>]
     The gnuplot command to set the terminal type for the PostScript
     terminal.  It this option is not set, the command used will be:
     `"set term postscript eps color solid lw 2 size 16.4 cm, 12.3 cm
     font \",24\""'. See the gnuplot documentation for `set term
     postscript' for more information.


 -- Plot option: gnuplot_svg_term_command [gnuplot_svg_term_command,
          <command>]
     The gnuplot command to set the terminal type for the SVG terminal.
     It this option is not set, the command used will be: `"set term
     svg font \",14\""'. See the gnuplot documentation for more
     information.


 -- Plot option: gnuplot_curve_titles
     This is an obsolete option that has been replaced `legend'
     described above.


 -- Plot option: gnuplot_curve_styles
     This is an obsolete option that has been replaced by `style'.



File: maxima.info,  Node: Gnuplot_pipes Format Functions,  Prev: Gnuplot Options,  Up: Plotting

12.6 Gnuplot_pipes Format Functions
===================================

 -- Function: gnuplot_start ()
     Opens the pipe to gnuplot used for plotting with the
     `gnuplot_pipes' format.  Is not necessary to manually open the
     pipe before plotting.


 -- Function: gnuplot_close ()
     Closes the pipe to gnuplot which is used with the `gnuplot_pipes'
     format.


 -- Function: gnuplot_restart ()
     Closes the pipe to gnuplot which is used with the `gnuplot_pipes'
     format and opens a new pipe.


 -- Function: gnuplot_replot ()
 -- Function: gnuplot_replot (<s>)
     Updates the gnuplot window.  If `gnuplot_replot' is called with a
     gnuplot command in a string <s>, then `s' is sent to gnuplot
     before reploting the window.


 -- Function: gnuplot_reset ()
     Resets the state of gnuplot used with the `gnuplot_pipes' format
     To update the gnuplot window call `gnuplot_replot' after
     `gnuplot_reset'.



File: maxima.info,  Node: File Input and Output,  Next: Polynomials,  Prev: Plotting,  Up: Top

13 File Input and Output
************************

* Menu:

* Comments::
* Files::
* Functions and Variables for File Input and Output::
* Functions and Variables for TeX Output::
* Functions and Variables for Fortran Output::


File: maxima.info,  Node: Comments,  Next: Files,  Prev: File Input and Output,  Up: File Input and Output

13.1 Comments
=============

A comment in Maxima input is any text between `/*' and `*/'.

   The Maxima parser treats a comment as whitespace for the purpose of
finding tokens in the input stream; a token always ends at a comment.
An input such as `a/* foo */b' contains two tokens, `a' and `b', and
not a single token `ab'.  Comments are otherwise ignored by Maxima;
neither the content nor the location of comments is stored in parsed
input expressions.

   Comments can be nested to arbitrary depth.  The `/*' and `*/'
delimiters form matching pairs.  There must be the same number of `/*'
as there are `*/'.

   Examples:

     (%i1) /* aa is a variable of interest */  aa : 1234;
     (%o1)                         1234
     (%i2) /* Value of bb depends on aa */  bb : aa^2;
     (%o2)                        1522756
     (%i3) /* User-defined infix operator */  infix ("b");
     (%o3)                           b
     (%i4) /* Parses same as a b c, not abc */  a/* foo */b/* bar */c;
     (%o4)                         a b c
     (%i5) /* Comments /* can be nested /* to any depth */ */ */  1 + xyz;
     (%o5)                        xyz + 1


File: maxima.info,  Node: Files,  Next: Functions and Variables for File Input and Output,  Prev: Comments,  Up: File Input and Output

13.2 Files
==========

A file is simply an area on a particular storage device which contains
data or text.  Files on the disks are figuratively grouped into
"directories".  A directory is just a list of files.  Commands which
deal with files are:

   appendfile           batch                 batchload
   closefile            file_output_append    filename_merge
   file_search          file_search_maxima    file_search_lisp
   file_search_demo     file_search_usage     file_search_tests
   file_type            file_type_lisp        file_type_maxima
   load                 load_pathname         loadfile
   loadprint            pathname_directory    pathname_name
   pathname_type        printfile             save
   stringout            with_stdout           writefile

   When a file name is passed to functions like `plot2d', `save', or
`writefile' and the file name does not include a path, Maxima stores
the file in the current working directory.  The current working
directory depends on the system like Windows or Linux and on the
installation.


File: maxima.info,  Node: Functions and Variables for File Input and Output,  Next: Functions and Variables for TeX Output,  Prev: Files,  Up: File Input and Output

13.3 Functions and Variables for File Input and Output
======================================================

 -- Function: appendfile (<filename>)
     Appends a console transcript to <filename>.  `appendfile' is the
     same as `writefile', except that the transcript file, if it
     exists, is always appended.

     `closefile' closes the transcript file opened by `appendfile' or
     `writefile'.


 -- Function: batch (<filename>)
 -- Function: batch (<filename>, `option')
     `batch(<filename>)' reads Maxima expressions from <filename> and
     evaluates them.  `batch' searches for <filename> in the list
     `file_search_maxima'.  See also `file_search'.

     `batch(<filename>, `demo')' is like `demo(<filename>)'.  In this
     case `batch' searches for <filename> in the list
     `file_search_demo'.  See `demo'.

     `batch(<filename>, `test')' is like `run_testsuite' with the
     option `display_all=true'.  For this case `batch' searches
     <filename> in the list `file_search_maxima' and not in the list
     `file_search_tests' like `run_testsuite'.  Furthermore,
     `run_testsuite' runs tests which are in the list
     `testsuite_files'.  With `batch' it is possible to run any file in
     a test mode, which can be found in the list `file_search_maxima'.
     This is useful, when writing a test file.

     <filename> comprises a sequence of Maxima expressions, each
     terminated with `;' or `$'.  The special variable `%' and the
     function `%th' refer to previous results within the file.  The
     file may include `:lisp' constructs.  Spaces, tabs, and newlines
     in the file are ignored.  A suitable input file may be created by
     a text editor or by the `stringout' function.

     `batch' reads each input expression from <filename>, displays the
     input to the console, computes the corresponding output
     expression, and displays the output expression.  Input labels are
     assigned to the input expressions and output labels are assigned
     to the output expressions.  `batch' evaluates every input
     expression in the file unless there is an error.  If user input is
     requested (by `asksign' or `askinteger', for example) `batch'
     pauses to collect the requisite input and then continue.

     It may be possible to halt `batch' by typing `control-C' at the
     console.  The effect of `control-C' depends on the underlying Lisp
     implementation.

     `batch' has several uses, such as to provide a reservoir for
     working command lines, to give error-free demonstrations, or to
     help organize one's thinking in solving complex problems.

     `batch' evaluates its argument.  `batch' returns the path of
     <filename> as a string, when called with no second argument or
     with the option `demo'.  When called with the option `test', the
     return value is a an empty list `[]' or a list with <filename> and
     the numbers of the tests which have failed.

     See also `load', `batchload', and `demo'.


 -- Function: batchload (<filename>)
     Reads Maxima expressions from <filename> and evaluates them,
     without displaying the input or output expressions and without
     assigning labels to output expressions.  Printed output (such as
     produced by `print' or `describe')) is displayed, however.

     The special variable `%' and the function `%th' refer to previous
     results from the interactive interpreter, not results within the
     file.  The file cannot include `:lisp' constructs.

     `batchload' returns the path of <filename>, as a string.
     `batchload' evaluates its argument.

     See also `batch', and `load'.


 -- Function: closefile ()
     Closes the transcript file opened by `writefile' or `appendfile'.


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

     `file_output_append' governs whether file output functions append
     or truncate their output file.  When `file_output_append' is
     `true', such functions append to their output file.  Otherwise,
     the output file is truncated.

     `save', `stringout', and `with_stdout' respect
     `file_output_append'.  Other functions which write output files do
     not respect `file_output_append'.  In particular, plotting and
     translation functions always truncate their output file, and `tex'
     and `appendfile' always append.


 -- Function: filename_merge (<path>, <filename>)
     Constructs a modified path from <path> and <filename>.  If the
     final component of <path> is of the form `###.<something>', the
     component is replaced with `<filename>.<something>'.  Otherwise,
     the final component is simply replaced by <filename>.

     The result is a Lisp pathname object.


 -- Function: file_search (<filename>)
 -- Function: file_search (<filename>, <pathlist>)
     `file_search' searches for the file <filename> and returns the
     path to the file (as a string) if it can be found; otherwise
     `file_search' returns `false'.  `file_search (<filename>)'
     searches in the default search directories, which are specified by
     the `file_search_maxima', `file_search_lisp', and
     `file_search_demo' variables.

     `file_search' first checks if the actual name passed exists,
     before attempting to match it to "wildcard" file search patterns.
     See `file_search_maxima' concerning file search patterns.

     The argument <filename> can be a path and file name, or just a
     file name, or, if a file search directory includes a file search
     pattern, just the base of the file name (without an extension).
     For example,

          file_search ("/home/wfs/special/zeta.mac");
          file_search ("zeta.mac");
          file_search ("zeta");

     all find the same file, assuming the file exists and
     `/home/wfs/special/###.mac' is in `file_search_maxima'.

     `file_search (<filename>, <pathlist>)' searches only in the
     directories specified by <pathlist>, which is a list of strings.
     The argument <pathlist> supersedes the default search directories,
     so if the path list is given, `file_search' searches only the ones
     specified, and not any of the default search directories.  Even if
     there is only one directory in <pathlist>, it must still be given
     as a one-element list.

     The user may modify the default search directories.  See
     `file_search_maxima'.

     `file_search' is invoked by `load' with `file_search_maxima' and
     `file_search_lisp' as the search directories.


 -- Option variable: file_search_maxima
 -- Option variable: file_search_lisp
 -- Option variable: file_search_demo
 -- Option variable: file_search_usage
 -- Option variable: file_search_tests
     These variables specify lists of directories to be searched by
     `load', `demo', and some other Maxima functions.  The default
     values of these variables name various directories in the Maxima
     installation.

     The user can modify these variables, either to replace the default
     values or to append additional directories.  For example,

          file_search_maxima: ["/usr/local/foo/###.mac",
              "/usr/local/bar/###.mac"]$

     replaces the default value of `file_search_maxima', while

          file_search_maxima: append (file_search_maxima,
              ["/usr/local/foo/###.mac", "/usr/local/bar/###.mac"])$

     appends two additional directories.  It may be convenient to put
     such an expression in the file `maxima-init.mac' so that the file
     search path is assigned automatically when Maxima starts.  See
     also *note Introduction for Runtime Environment::.

     Multiple filename extensions and multiple paths can be specified
     by special "wildcard" constructions.  The string `###' expands
     into the sought-after name, while a comma-separated list enclosed
     in curly braces `{foo,bar,baz}' expands into multiple strings.
     For example, supposing the sought-after name is `neumann',

          "/home/{wfs,gcj}/###.{lisp,mac}"

     expands into `/home/wfs/neumann.lisp', `/home/gcj/neumann.lisp',
     `/home/wfs/neumann.mac', and `/home/gcj/neumann.mac'.


 -- Function: file_type (<filename>)
     Returns a guess about the content of <filename>, based on the
     filename extension.  <filename> need not refer to an actual file;
     no attempt is made to open the file and inspect the content.

     The return value is a symbol, either `object', `lisp', or
     `maxima'.  If the extension is matches one of the values in
     `file_type_maxima', `file_type' returns `maxima'.  If the
     extension matches one of the values in `file_type_lisp',
     `file_type' returns `lisp'.  If none of the above, `file_type'
     returns `object'.

     See also `pathname_type'.

     See `file_type_maxima' and `file_type_lisp' for the default values.

     Examples:

          (%i2) map('file_type,
                    ["test.lisp", "test.mac", "test.dem", "test.txt"]);
          (%o2)            [lisp, maxima, maxima, object]


 -- Option variable: file_type_lisp
     Default value:  `[l, lsp, lisp]'

     `file_type_lisp' is a list of file extensions that maxima
     recognizes as denoting a Lisp source file.

     See also `file_type'.

 -- Option variable: file_type_maxima
     Default value:  `[mac, mc, demo, dem, dm1, dm2, dm3, dmt]'

     `file_type_maxima' is a list of file extensions that maxima
     recognizes as denoting a Maxima source file.

     See also `file_type'.

 -- Function: load (<filename>)
     Evaluates expressions in <filename>, thus bringing variables,
     functions, and other objects into Maxima.  The binding of any
     existing object is clobbered by the binding recovered from
     <filename>.  To find the file, `load' calls `file_search' with
     `file_search_maxima' and `file_search_lisp' as the search
     directories.  If `load' succeeds, it returns the name of the file.
     Otherwise `load' prints an error message.

     `load' works equally well for Lisp code and Maxima code.  Files
     created by `save', `translate_file', and `compile_file', which
     create Lisp code, and `stringout', which creates Maxima code, can
     all be processed by `load'.  `load' calls `loadfile' to load Lisp
     files and `batchload' to load Maxima files.

     `load' does not recognize `:lisp' constructs in Maxima files, and
     while processing <filename>, the global variables `_', `__', `%',
     and `%th' have whatever bindings they had when `load' was called.

     See also `loadfile', `batch', `batchload', and `demo'.  `loadfile'
     processes Lisp files; `batch', `batchload', and `demo' process
     Maxima files.

     See `file_search' for more detail about the file search mechanism.

     `load' evaluates its argument.


 -- System variable: load_pathname
     Default value: `false'

     When a file is loaded with the functions `load', `loadfile' or
     `batchload' the system variable `load_pathname' is bound to the
     pathname of the file which is processed.

     The variable `load_pathname' can be accessed from the file during
     the loading.

     Example:

     Suppose we have a batchfile `test.mac' in the directory
     `"/home/dieter/workspace/mymaxima/temp/"' with the following commands

          print("The value of load_pathname is: ", load_pathname)$
          print("End of batchfile")$

     then we get the following output

          (%i1) load("/home/dieter/workspace/mymaxima/temp/test.mac")$
          The value of load_pathname is:
                             /home/dieter/workspace/mymaxima/temp/test.mac
          End of batchfile


 -- Function: loadfile (<filename>)
     Evaluates Lisp expressions in <filename>.  `loadfile' does not
     invoke `file_search', so `filename' must include the file
     extension and as much of the path as needed to find the file.

     `loadfile' can process files created by `save', `translate_file',
     and `compile_file'.  The user may find it more convenient to use
     `load' instead of `loadfile'.


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

     `loadprint' tells whether to print a message when a file is loaded.

        * When `loadprint' is `true', always print a message.

        * When `loadprint' is `'loadfile', print a message only if a
          file is loaded by the function `loadfile'.

        * When `loadprint' is `'autoload', print a message only if a
          file is automatically loaded.  See `setup_autoload'.

        * When `loadprint' is `false', never print a message.


 -- Function: pathname_directory (<pathname>)
 -- Function: pathname_name (<pathname>)
 -- Function: pathname_type (<pathname>)
     These functions return the components of <pathname>.

     Examples:

          (%i1) pathname_directory("/home/dieter/maxima/changelog.txt");
          (%o1)                 /home/dieter/maxima/
          (%i2) pathname_name("/home/dieter/maxima/changelog.txt");
          (%o2)                       changelog
          (%i3) pathname_type("/home/dieter/maxima/changelog.txt");
          (%o3)                          txt


 -- Function: printfile (<path>)
     Prints the file named by <path> to the console.  <path> may be a
     string or a symbol; if it is a symbol, it is converted to a string.

     If <path> names a file which is accessible from the current working
     directory, that file is printed to the console.  Otherwise,
     `printfile' attempts to locate the file by appending <path> to
     each of the elements of `file_search_usage' via `filename_merge'.

     `printfile' returns <path> if it names an existing file, or
     otherwise the result of a successful filename merge.


 -- Function: save (<filename>, <name_1>, <name_2>, <name_3>, ...)
 -- Function: save (<filename>, values, functions, labels, ...)
 -- Function: save (<filename>, [<m>, <n>])
 -- Function: save (<filename>, <name_1>=<expr_1>, ...)
 -- Function: save (<filename>, all)
 -- Function: save (<filename>, <name_1>=<expr_1>, <name_2>=<expr_2>,
          ...)
     Stores the current values of <name_1>, <name_2>, <name_3>, ..., in
     <filename>.  The arguments are the names of variables, functions,
     or other objects.  If a name has no value or function associated
     with it, it is ignored.  `save' returns <filename>.

     `save' stores data in the form of Lisp expressions.  The data
     stored by `save' may be recovered by `load (<filename>)'.  See
     `load'.

     The global flag `file_output_append' governs whether `save'
     appends or truncates the output file.  When `file_output_append'
     is `true', `save' appends to the output file.  Otherwise, `save'
     truncates the output file.  In either case, `save' creates the
     file if it does not yet exist.

     The special form `save (<filename>, values, functions, labels,
     ...)'  stores the items named by `values', `functions', `labels',
     etc.  The names may be any specified by the variable `infolists'.
     `values' comprises all user-defined variables.

     The special form `save (<filename>, [<m>, <n>])' stores the values
     of input and output labels <m> through <n>.  Note that <m> and <n>
     must be literal integers.  Input and output labels may also be
     stored one by one, e.g., `save ("foo.1", %i42, %o42)'.  `save
     (<filename>, labels)' stores all input and output labels.  When
     the stored labels are recovered, they clobber existing labels.

     The special form `save (<filename>, <name_1>=<expr_1>,
     <name_2>=<expr_2>, ...)' stores the values of <expr_1>, <expr_2>,
     ..., with names <name_1>, <name_2>, ...  It is useful to apply
     this form to input and output labels, e.g., `save ("foo.1",
     aa=%o88)'.  The right-hand side of the equality in this form may
     be any expression, which is evaluated.  This form does not
     introduce the new names into the current Maxima environment, but
     only stores them in <filename>.

     These special forms and the general form of `save' may be mixed at
     will.  For example, `save (<filename>, aa, bb, cc=42, functions,
     [11, 17])'.

     The special form `save (<filename>, all)' stores the current state
     of Maxima.  This includes all user-defined variables, functions,
     arrays, etc., as well as some automatically defined items.  The
     saved items include system variables, such as `file_search_maxima'
     or `showtime', if they have been assigned new values by the user;
     see `myoptions'.

     `save' evaluates <filename> and quotes all other arguments.


 -- Function: stringout (<filename>, <expr_1>, <expr_2>, <expr_3>, ...)
 -- Function: stringout (<filename>, [<m>, <n>])
 -- Function: stringout (<filename>, input)
 -- Function: stringout (<filename>, functions)
 -- Function: stringout (<filename>, values)
     `stringout' writes expressions to a file in the same form the
     expressions would be typed for input.  The file can then be used
     as input for the `batch' or `demo' commands, and it may be edited
     for any purpose.  `stringout' can be executed while `writefile' is
     in progress.

     The global flag `file_output_append' governs whether `stringout'
     appends or truncates the output file.  When `file_output_append' is
     `true', `stringout' appends to the output file.  Otherwise,
     `stringout' truncates the output file.  In either case, `stringout'
     creates the file if it does not yet exist.

     The general form of `stringout' writes the values of one or more
     expressions to the output file.  Note that if an expression is a
     variable, only the value of the variable is written and not the
     name of the variable.  As a useful special case, the expressions
     may be input labels (`%i1', `%i2', `%i3', ...) or output labels
     (`%o1', `%o2', `%o3', ...).

     If `grind' is `true', `stringout' formats the output using the
     `grind' format.  Otherwise the `string' format is used.  See
     `grind' and `string'.

     The special form `stringout (<filename>, [<m>, <n>])' writes the
     values of input labels m through n, inclusive.

     The special form `stringout (<filename>, input)' writes all input
     labels to the file.

     The special form `stringout (<filename>, functions)' writes all
     user-defined functions (named by the global list `functions')) to
     the file.

     The special form `stringout (<filename>, values)' writes all
     user-assigned variables (named by the global list `values')) to
     the file.  Each variable is printed as an assignment statement,
     with the name of the variable, a colon, and its value.  Note that
     the general form of `stringout' does not print variables as
     assignment statements.


 -- Function: with_stdout (<f>, <expr_1>, <expr_2>, <expr_3>, ...)
 -- Function: with_stdout (<s>, <expr_1>, <expr_2>, <expr_3>, ...)
     Evaluates <expr_1>, <expr_2>, <expr_3>, ... and writes any output
     thus generated to a file <f> or output stream <s>.  The evaluated
     expressions are not written to the output.  Output may be
     generated by `print', `display', `grind', among other functions.

     The global flag `file_output_append' governs whether `with_stdout'
     appends or truncates the output file <f>.  When
     `file_output_append' is `true', `with_stdout' appends to the
     output file.  Otherwise, `with_stdout' truncates the output file.
     In either case, `with_stdout' creates the file if it does not yet
     exist.

     `with_stdout' returns the value of its final argument.

     See also `writefile'.

          (%i1) with_stdout ("tmp.out", for i:5 thru 10 do
                print (i, "! yields", i!))$
          (%i2) printfile ("tmp.out")$
          5 ! yields 120
          6 ! yields 720
          7 ! yields 5040
          8 ! yields 40320
          9 ! yields 362880
          10 ! yields 3628800


 -- Function: writefile (<filename>)
     Begins writing a transcript of the Maxima session to <filename>.
     All interaction between the user and Maxima is then recorded in
     this file, just as it appears on the console.

     As the transcript is printed in the console output format, it
     cannot be reloaded into Maxima.  To make a file containing
     expressions which can be reloaded, see `save' and `stringout'.
     `save' stores expressions in Lisp form, while `stringout' stores
     expressions in Maxima form.

     The effect of executing `writefile' when <filename> already exists
     depends on the underlying Lisp implementation; the transcript file
     may be clobbered, or the file may be appended.  `appendfile'
     always appends to the transcript file.

     It may be convenient to execute `playback' after `writefile' to
     save the display of previous interactions.  As `playback' displays
     only the input and output variables (`%i1', `%o1', etc.), any
     output generated by a print statement in a function (as opposed to
     a return value) is not displayed by `playback'.

     `closefile' closes the transcript file opened by `writefile' or
     `appendfile'.



File: maxima.info,  Node: Functions and Variables for TeX Output,  Next: Functions and Variables for Fortran Output,  Prev: Functions and Variables for File Input and Output,  Up: File Input and Output

13.4 Functions and Variables for TeX Output
===========================================

 -- Function: tex (<expr>)
 -- Function: tex (<expr>, <destination>)
 -- Function: tex (<expr>, false)
 -- Function: tex (<label>)
 -- Function: tex (<label>, <destination>)
 -- Function: tex (<label>, false)
     Prints a representation of an expression suitable for the TeX
     document preparation system.  The result is a fragment of a
     document, which can be copied into a larger document but not
     processed by itself.

     `tex (<expr>)' prints a TeX representation of <expr> on the
     console.

     `tex (<label>)' prints a TeX representation of the expression
     named by <label> and assigns it an equation label (to be displayed
     to the left of the expression).  The TeX equation label is the
     same as the Maxima label.

     <destination> may be an output stream or file name.  When
     <destination> is a file name, `tex' appends its output to the
     file.  The functions `openw' and `opena' create output streams.

     `tex (<expr>, false)' and `tex (<label>, false)' return their TeX
     output as a string.

     `tex' evaluates its first argument after testing it to see if it
     is a label.  Quote-quote `''' forces evaluation of the argument,
     thereby defeating the test and preventing the label.

     See also `texput'.

     Examples:

          (%i1) integrate (1/(1+x^3), x);
                                              2 x - 1
                            2            atan(-------)
                       log(x  - x + 1)        sqrt(3)    log(x + 1)
          (%o1)      - --------------- + ------------- + ----------
                              6             sqrt(3)          3
          (%i2) tex (%o1);
          $$-{{\log \left(x^2-x+1\right)}\over{6}}+{{\arctan \left({{2\,x-1
           }\over{\sqrt{3}}}\right)}\over{\sqrt{3}}}+{{\log \left(x+1\right)
           }\over{3}}\leqno{\tt (\%o1)}$$
          (%o2)                          (\%o1)
          (%i3) tex (integrate (sin(x), x));
          $$-\cos x$$
          (%o3)                           false
          (%i4) tex (%o1, "foo.tex");
          (%o4)                          (\%o1)

     `tex (<expr>, false)' returns its TeX output as a string.

          (%i1) S : tex (x * y * z, false);
          (%o1) $$x\,y\,z$$
          (%i2) S;
          (%o2) $$x\,y\,z$$


 -- Function: tex1 (<e>)
     Returns a string which represents the TeX output for the
     expressions <e>.  The TeX output is not enclosed in delimiters for
     an equation or any other environment.

     Examples:

          (%i1) tex1 (sin(x) + cos(x));
          (%o1)                     \sin x+\cos x

 -- Function: texput (<a>, <s>)
 -- Function: texput (<a>, <f>)
 -- Function: texput (<a>, <s>, <operator_type>)
 -- Function: texput (<a>, [<s_1>, <s_2>], matchfix)
 -- Function: texput (<a>, [<s_1>, <s_2>, <s_3>], matchfix)
     Assign the TeX output for the atom <a>, which can be a symbol or
     the name of an operator.

     `texput (<a>, <s>)' causes the `tex' function to interpolate the
     string <s> into the TeX output in place of <a>.

     `texput (<a>, <f>)' causes the `tex' function to call the function
     <f> to generate TeX output.  <f> must accept one argument, which
     is an expression which has operator <a>, and must return a string
     (the TeX output).  <f> may call `tex1' to generate TeX output for
     the arguments of the input expression.

     `texput (<a>, <s>, <operator_type>)', where <operator_type> is
     `prefix', `infix', `postfix', `nary', or `nofix', causes the `tex'
     function to interpolate <s> into the TeX output in place of <a>,
     and to place the interpolated text in the appropriate position.

     `texput (<a>, [<s_1>, <s_2>], matchfix)' causes the `tex' function
     to interpolate <s_1> and <s_2> into the TeX output on either side
     of the arguments of <a>.  The arguments (if more than one) are
     separated by commas.

     `texput (<a>, [<s_1>, <s_2>, <s_3>], matchfix)' causes the `tex'
     function to interpolate <s_1> and <s_2> into the TeX output on
     either side of the arguments of <a>, with <s_3> separating the
     arguments.

     Examples:

     Assign TeX output for a variable.

          (%i1) texput (me,"\\mu_e");
          (%o1)                         \mu_e
          (%i2) tex (me);
          $$\mu_e$$
          (%o2)                         false

     Assign TeX output for an ordinary function (not an operator).

          (%i1) texput (lcm, "\\mathrm{lcm}");
          (%o1)                     \mathrm{lcm}
          (%i2) tex (lcm (a, b));
          $$\mathrm{lcm}\left(a , b\right)$$
          (%o2)                         false

     Call a function to generate TeX output.

          (%i1) texfoo (e) := block ([a, b], [a, b] : args (e),
            concat("\\left[\\stackrel{",tex1(b),"}{",tex1(a),"}\\right]"))$
          (%i2) texput (foo, texfoo);
          (%o2)                        texfoo
          (%i3) tex (foo (2^x, %pi));
          $$\left[\stackrel{\pi}{2^{x}}\right]$$
          (%o3)                         false

     Assign TeX output for a prefix operator.

          (%i1) prefix ("grad");
          (%o1)                         grad
          (%i2) texput ("grad", " \\nabla ", prefix);
          (%o2)                        \nabla
          (%i3) tex (grad f);
          $$ \nabla f$$
          (%o3)                         false

     Assign TeX output for an infix operator.

          (%i1) infix ("~");
          (%o1)                           ~
          (%i2) texput ("~", " \\times ", infix);
          (%o2)                        \times
          (%i3) tex (a ~ b);
          $$a \times b$$
          (%o3)                         false

     Assign TeX output for a postfix operator.

          (%i1) postfix ("##");
          (%o1)                          ##
          (%i2) texput ("##", "!!", postfix);
          (%o2)                          !!
          (%i3) tex (x ##);
          $$x!!$$
          (%o3)                         false

     Assign TeX output for a nary operator.

          (%i1) nary ("@@");
          (%o1)                          @@
          (%i2) texput ("@@", " \\circ ", nary);
          (%o2)                         \circ
          (%i3) tex (a @@ b @@ c @@ d);
          $$a \circ b \circ c \circ d$$
          (%o3)                         false

     Assign TeX output for a nofix operator.

          (%i1) nofix ("foo");
          (%o1)                          foo
          (%i2) texput ("foo", "\\mathsc{foo}", nofix);
          (%o2)                     \mathsc{foo}
          (%i3) tex (foo);
          $$\mathsc{foo}$$
          (%o3)                         false

     Assign TeX output for a matchfix operator.

          (%i1) matchfix ("<<", ">>");
          (%o1)                          <<
          (%i2) texput ("<<", [" \\langle ", " \\rangle "], matchfix);
          (%o2)                [ \langle ,  \rangle ]
          (%i3) tex (<<a>>);
          $$ \langle a \rangle $$
          (%o3)                         false
          (%i4) tex (<<a, b>>);
          $$ \langle a , b \rangle $$
          (%o4)                         false
          (%i5) texput ("<<", [" \\langle ", " \\rangle ", " \\, | \\,"],
                matchfix);
          (%o5)           [ \langle ,  \rangle ,  \, | \,]
          (%i6) tex (<<a>>);
          $$ \langle a \rangle $$
          (%o6)                         false
          (%i7) tex (<<a, b>>);
          $$ \langle a \, | \,b \rangle $$
          (%o7)                         false


 -- Function: get_tex_environment (<op>)
 -- Function: set_tex_environment (<op>, <before>, <after>)
     Customize the TeX environment output by `tex'.  As maintained by
     these functions, the TeX environment comprises two strings: one is
     printed before any other TeX output, and the other is printed
     after.

     Only the TeX environment of the top-level operator in an expression
     is output; TeX environments associated with other operators are
     ignored.

     `get_tex_environment' returns the TeX enviroment which is applied
     to the operator <op>; returns the default if no other environment
     has been assigned.

     `set_tex_environment' assigns the TeX environment for the operator
     <op>.

     Examples:

          (%i1) get_tex_environment (":=");
          (%o1) [
          \begin{verbatim}
          , ;
          \end{verbatim}
          ]
          (%i2) tex (f (x) := 1 - x);

          \begin{verbatim}
          f(x):=1-x;
          \end{verbatim}

          (%o2)                         false
          (%i3) set_tex_environment (":=", "$$", "$$");
          (%o3)                       [$$, $$]
          (%i4) tex (f (x) := 1 - x);
          $$f(x):=1-x$$
          (%o4)                         false


 -- Function: get_tex_environment_default ()
 -- Function: set_tex_environment_default (<before>, <after>)
     Customize the TeX environment output by `tex'.  As maintained by
     these functions, the TeX environment comprises two strings: one is
     printed before any other TeX output, and the other is printed
     after.

     `get_tex_environment_default' returns the TeX environment which is
     applied to expressions for which the top-level operator has no
     specific TeX environment (as assigned by `set_tex_environment').

     `set_tex_environment_default' assigns the default TeX environment.

     Examples:

          (%i1) get_tex_environment_default ();
          (%o1)                       [$$, $$]
          (%i2) tex (f(x) + g(x));
          $$g\left(x\right)+f\left(x\right)$$
          (%o2)                         false
          (%i3) set_tex_environment_default ("\\begin{equation}
          ", "
          \\end{equation}");
          (%o3) [\begin{equation}
          ,
          \end{equation}]
          (%i4) tex (f(x) + g(x));
          \begin{equation}
          g\left(x\right)+f\left(x\right)
          \end{equation}
          (%o4)                         false



File: maxima.info,  Node: Functions and Variables for Fortran Output,  Prev: Functions and Variables for TeX Output,  Up: File Input and Output

13.5 Functions and Variables for Fortran Output
===============================================

 -- Option variable: fortindent
     Default value: `0'

     `fortindent' controls the left margin indentation of expressions
     printed out by the `fortran' command.  `0' gives normal printout
     (i.e., 6 spaces), and positive values will causes the expressions
     to be printed farther to the right.


 -- Function: fortran (<expr>)
     Prints <expr> as a Fortran statement.  The output line is indented
     with spaces.  If the line is too long, `fortran' prints
     continuation lines.  `fortran' prints the exponentiation operator
     `^' as `**', and prints a complex number `a + b %i' in the form
     `(a,b)'.

     <expr> may be an equation.  If so, `fortran' prints an assignment
     statement, assigning the right-hand side of the equation to the
     left-hand side.  In particular, if the right-hand side of <expr>
     is the name of a matrix, then `fortran' prints an assignment
     statement for each element of the matrix.

     If <expr> is not something recognized by `fortran', the expression
     is printed in `grind' format without complaint.  `fortran' does
     not know about lists, arrays, or functions.

     `fortindent' controls the left margin of the printed lines.  `0'
     is the normal margin (i.e., indented 6 spaces).  Increasing
     `fortindent' causes expressions to be printed further to the right.

     When `fortspaces' is `true', `fortran' fills out each printed line
     with spaces to 80 columns.

     `fortran' evaluates its arguments; quoting an argument defeats
     evaluation.  `fortran' always returns `done'.

     See also the function `f90' for printing one or more expressions
     as a Fortran 90 program.

     Examples:

     (%i1) expr: (a + b)^12$
     (%i2) fortran (expr);
           (b+a)**12
     (%o2)                         done
     (%i3) fortran ('x=expr);
           x = (b+a)**12
     (%o3)                         done
     (%i4) fortran ('x=expand (expr));
           x = b**12+12*a*b**11+66*a**2*b**10+220*a**3*b**9+495*a**4*b**8+792
          1   *a**5*b**7+924*a**6*b**6+792*a**7*b**5+495*a**8*b**4+220*a**9*b
          2   **3+66*a**10*b**2+12*a**11*b+a**12
     (%o4)                         done
     (%i5) fortran ('x=7+5*%i);
           x = (7,5)
     (%o5)                         done
     (%i6) fortran ('x=[1,2,3,4]);
           x = [1,2,3,4]
     (%o6)                         done
     (%i7) f(x) := x^2$
     (%i8) fortran (f);
           f
     (%o8)                         done


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

     When `fortspaces' is `true', `fortran' fills out each printed line
     with spaces to 80 columns.



File: maxima.info,  Node: Polynomials,  Next: Special Functions,  Prev: File Input and Output,  Up: Top

14 Polynomials
**************

* Menu:

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


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

14.1 Introduction to Polynomials
================================

Polynomials are stored in Maxima either in General Form or as Canonical
Rational Expressions (CRE) form.  The latter is a standard form, and is
used internally by operations such as factor, ratsimp, and so on.

   Canonical Rational Expressions constitute a kind of representation
which is especially suitable for expanded polynomials and rational
functions (as well as for partially factored polynomials and rational
functions when RATFAC is set to `true').  In this CRE form an ordering
of variables (from most to least main) is assumed for each expression.
Polynomials are represented recursively by a list consisting of the
main variable followed by a series of pairs of expressions, one for
each term of the polynomial.  The first member of each pair is the
exponent of the main variable in that term and the second member is the
coefficient of that term which could be a number or a polynomial in
another variable again represented in this form.  Thus the principal
part of the CRE form of 3*X^2-1 is (X 2 3 0 -1) and that of 2*X*Y+X-3
is (Y 1 (X 1 2) 0 (X 1 1 0 -3)) assuming Y is the main variable, and is
(X 1 (Y 1 2 0 1) 0 -3) assuming X is the main variable.  "Main"-ness is
usually determined by reverse alphabetical order.  The "variables" of a
CRE expression needn't be atomic.  In fact any subexpression whose main
operator is not + - * / or ^ with integer power will be considered a
"variable" of the expression (in CRE form) in which it occurs.  For
example the CRE variables of the expression X+SIN(X+1)+2*SQRT(X)+1 are
X, SQRT(X), and SIN(X+1).  If the user does not specify an ordering of
variables by using the RATVARS function Maxima will choose an
alphabetic one.  In general, CRE's represent rational expressions, that
is, ratios of polynomials, where the numerator and denominator have no
common factors, and the denominator is positive.  The internal form is
essentially a pair of polynomials (the numerator and denominator)
preceded by the variable ordering list.  If an expression to be
displayed is in CRE form or if it contains any subexpressions in CRE
form, the symbol /R/ will follow the line label.  See the RAT function
for converting an expression to CRE form.  An extended CRE form is used
for the representation of Taylor series.  The notion of a rational
expression is extended so that the exponents of the variables can be
positive or negative rational numbers rather than just positive
integers and the coefficients can themselves be rational expressions as
described above rather than just polynomials.  These are represented
internally by a recursive polynomial form which is similar to and is a
generalization of CRE form, but carries additional information such as
the degree of truncation.  As with CRE form, the symbol /T/ follows the
line label of such expressions.


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

14.2 Functions and Variables for Polynomials
============================================

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

     `algebraic' must be set to `true' in order for the simplification
     of algebraic integers to take effect.


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

     When `berlefact' is `false' then the Kronecker factoring algorithm
     will be used otherwise the Berlekamp algorithm, which is the
     default, will be used.


 -- Function: bezout (<p1>, <p2>, <x>)
     an alternative to the `resultant' command.  It returns a matrix.
     `determinant' of this matrix is the desired resultant.

     Examples:

          (%i1) bezout(a*x+b, c*x^2+d, x);
                                   [ b c  - a d ]
          (%o1)                    [            ]
                                   [  a     b   ]
          (%i2) determinant(%);
                                      2      2
          (%o2)                      a  d + b  c
          (%i3) resultant(a*x+b, c*x^2+d, x);
                                      2      2
          (%o3)                      a  d + b  c


 -- Function: bothcoef (<expr>, <x>)
     Returns a list whose first member is the coefficient of <x> in
     <expr> (as found by `ratcoef' if <expr> is in CRE form otherwise
     by `coeff') and whose second member is the remaining part of
     <expr>.  That is, `[A, B]' where `<expr> = A*<x> + B'.

     Example:

          (%i1) islinear (expr, x) := block ([c],
                  c: bothcoef (rat (expr, x), x),
                  is (freeof (x, c) and c[1] # 0))$
          (%i2) islinear ((r^2 - (x - r)^2)/x, x);
          (%o2)                         true


 -- Function: coeff (<expr>, <x>, <n>)
 -- Function: coeff (<expr>, <x>)
     Returns the coefficient of `<x>^<n>' in <expr>, where <expr> is a
     polynomial or a monomial term in <x>.

     `coeff(<expr>, <x>^<n>)' is equivalent to `coeff(<expr>, <x>,
     <n>)'.  `coeff(<expr>, <x>, 0)' returns the remainder of <expr>
     which is free of <x>.  If omitted, <n> is assumed to be 1.

     <x> may be a simple variable or a subscripted variable, or a
     subexpression of <expr> which comprises an operator and all of its
     arguments.

     It may be possible to compute coefficients of expressions which
     are equivalent to <expr> by applying `expand' or `factor'.
     `coeff' itself does not apply `expand' or `factor' or any other
     function.

     `coeff' distributes over lists, matrices, and equations.

     Examples:

     `coeff' returns the coefficient `<x>^<n>' in <expr>.

          (%i1) coeff (b^3*a^3 + b^2*a^2 + b*a + 1, a^3);
                                          3
          (%o1)                          b

     `coeff(<expr>, <x>^<n>)' is equivalent to `coeff(<expr>, <x>,
     <n>)'.

          (%i1) coeff (c[4]*z^4 - c[3]*z^3 - c[2]*z^2 + c[1]*z, z, 3);
          (%o1)                         - c
                                           3
          (%i2) coeff (c[4]*z^4 - c[3]*z^3 - c[2]*z^2 + c[1]*z, z^3);
          (%o2)                         - c
                                           3

     `coeff(<expr>, <x>, 0)' returns the remainder of <expr> which is
     free of <x>.

          (%i1) coeff (a*u + b^2*u^2 + c^3*u^3, b, 0);
                                      3  3
          (%o1)                      c  u  + a u

     <x> may be a simple variable or a subscripted variable, or a
     subexpression of <expr> which comprises an operator and all of its
     arguments.

          (%i1) coeff (h^4 - 2*%pi*h^2 + 1, h, 2);
          (%o1)                        - 2 %pi
          (%i2) coeff (v[1]^4 - 2*%pi*v[1]^2 + 1, v[1], 2);
          (%o2)                        - 2 %pi
          (%i3) coeff (sin(1+x)*sin(x) + sin(1+x)^3*sin(x)^3, sin(1+x)^3);
                                          3
          (%o3)                        sin (x)
          (%i4) coeff ((d - a)^2*(b + c)^3 + (a + b)^4*(c - d), a + b, 4);
          (%o4)                         c - d

     `coeff' itself does not apply `expand' or `factor' or any other
     function.

          (%i1) coeff (c*(a + b)^3, a);
          (%o1)                           0
          (%i2) expand (c*(a + b)^3);
                           3          2        2        3
          (%o2)           b  c + 3 a b  c + 3 a  b c + a  c
          (%i3) coeff (%, a);
                                          2
          (%o3)                        3 b  c
          (%i4) coeff (b^3*c + 3*a*b^2*c + 3*a^2*b*c + a^3*c, (a + b)^3);
          (%o4)                           0
          (%i5) factor (b^3*c + 3*a*b^2*c + 3*a^2*b*c + a^3*c);
                                            3
          (%o5)                      (b + a)  c
          (%i6) coeff (%, (a + b)^3);
          (%o6)                           c

     `coeff' distributes over lists, matrices, and equations.

          (%i1) coeff ([4*a, -3*a, 2*a], a);
          (%o1)                      [4, - 3, 2]
          (%i2) coeff (matrix ([a*x, b*x], [-c*x, -d*x]), x);
                                    [  a    b  ]
          (%o2)                     [          ]
                                    [ - c  - d ]
          (%i3) coeff (a*u - b*v = 7*u + 3*v, u);
          (%o3)                         a = 7


 -- Function: content (<p_1>, <x_1>, ..., <x_n>)
     Returns a list whose first element is the greatest common divisor
     of the coefficients of the terms of the polynomial <p_1> in the
     variable <x_n> (this is the content) and whose second element is
     the polynomial <p_1> divided by the content.

     Examples:

          (%i1) content (2*x*y + 4*x^2*y^2, y);
                                             2
          (%o1)                   [2 x, 2 x y  + y]


 -- Function: denom (<expr>)
     Returns the denominator of the rational expression <expr>.


 -- Function: divide (<p_1>, <p_2>, <x_1>, ..., <x_n>)
     computes the quotient and remainder of the polynomial <p_1>
     divided by the polynomial <p_2>, in a main polynomial variable,
     <x_n>.  The other variables are as in the `ratvars' function.  The
     result is a list whose first element is the quotient and whose
     second element is the remainder.

     Examples:

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

     Note that `y' is the main variable in the second example.


 -- Function: eliminate ([<eqn_1>, ..., <eqn_n>], [<x_1>, ..., <x_k>])
     Eliminates variables from equations (or expressions assumed equal
     to zero) by taking successive resultants. This returns a list of
     `<n> - <k>' expressions with the <k> variables <x_1>, ..., <x_k>
     eliminated.  First <x_1> is eliminated yielding `<n> - 1'
     expressions, then `x_2' is eliminated, etc.  If `<k> = <n>' then a
     single expression in a list is returned free of the variables
     <x_1>, ..., <x_k>.  In this case `solve' is called to solve the
     last resultant for the last variable.

     Example:

          (%i1) expr1: 2*x^2 + y*x + z;
                                                2
          (%o1)                    z + x y + 2 x
          (%i2) expr2: 3*x + 5*y - z - 1;
          (%o2)                  - z + 5 y + 3 x - 1
          (%i3) expr3: z^2 + x - y^2 + 5;
                                    2    2
          (%o3)                    z  - y  + x + 5
          (%i4) eliminate ([expr3, expr2, expr1], [y, z]);
                       8         7         6          5          4
          (%o4) [7425 x  - 1170 x  + 1299 x  + 12076 x  + 22887 x

                                              3         2
                                      - 5154 x  - 1291 x  + 7688 x + 15376]


 -- Function: ezgcd (<p_1>, <p_2>, <p_3>, ...)
     Returns a list whose first element is the greatest common divisor
     of the polynomials <p_1>, <p_2>, <p_3>, ... and whose remaining
     elements are the polynomials divided by the greatest common
     divisor.  This always uses the `ezgcd' algorithm.

     See also `gcd', `gcdex', `gcdivide', and `poly_gcd'.

     Examples:

     The three polynomials have the greatest common divisor `2*x-3'.
     The gcd is first calculated with the function `gcd' and then with
     the function `ezgcd'.

          (%i1) p1 : 6*x^3-17*x^2+14*x-3;
                                  3       2
          (%o1)                6 x  - 17 x  + 14 x - 3
          (%i2) p2 : 4*x^4-14*x^3+12*x^2+2*x-3;
                              4       3       2
          (%o2)            4 x  - 14 x  + 12 x  + 2 x - 3
          (%i3) p3 : -8*x^3+14*x^2-x-3;
                                    3       2
          (%o3)                - 8 x  + 14 x  - x - 3

          (%i4) gcd(p1, gcd(p2, p3));
          (%o4)                        2 x - 3

          (%i5) ezgcd(p1, p2, p3);
                             2               3      2           2
          (%o5) [2 x - 3, 3 x  - 4 x + 1, 2 x  - 4 x  + 1, - 4 x  + x + 1]


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

     `facexpand' controls whether the irreducible factors returned by
     `factor' are in expanded (the default) or recursive (normal CRE)
     form.


 -- Function: factor (<expr>)
 -- Function: factor (<expr>, <p>)
     Factors the expression <expr>, containing any number of variables
     or functions, into factors irreducible over the integers.  `factor
     (<expr>, <p>)' factors <expr> over the field of rationals with an
     element adjoined whose minimum polynomial is <p>.

     `factor' uses `ifactors' function for factoring integers.

     `factorflag' if `false' suppresses the factoring of integer factors
     of rational expressions.

     `dontfactor' may be set to a list of variables with respect to
     which factoring is not to occur.  (It is initially empty).
     Factoring also will not take place with respect to any variables
     which are less important (using the variable ordering assumed for
     CRE form) than those on the `dontfactor' list.

     `savefactors' if `true' causes the factors of an expression which
     is a product of factors to be saved by certain functions in order
     to speed up later factorizations of expressions containing some of
     the same factors.

     `berlefact' if `false' then the Kronecker factoring algorithm will
     be used otherwise the Berlekamp algorithm, which is the default,
     will be used.

     `intfaclim' if `true' maxima will give up factorization of
     integers if no factor is found after trial divisions and Pollard's
     rho method.  If set to `false' (this is the case when the user
     calls `factor' explicitly), complete factorization of the integer
     will be attempted.  The user's setting of `intfaclim' is used for
     internal calls to `factor'.  Thus, `intfaclim' may be reset to
     prevent Maxima from taking an inordinately long time factoring
     large integers.

     Examples:

          (%i1) factor (2^63 - 1);
                              2
          (%o1)              7  73 127 337 92737 649657
          (%i2) factor (-8*y - 4*x + z^2*(2*y + x));
          (%o2)               (2 y + x) (z - 2) (z + 2)
          (%i3) -1 - 2*x - x^2 + y^2 + 2*x*y^2 + x^2*y^2;
                          2  2        2    2    2
          (%o3)          x  y  + 2 x y  + y  - x  - 2 x - 1
          (%i4) block ([dontfactor: [x]], factor (%/36/(1 + 2*y + y^2)));
                                 2
                               (x  + 2 x + 1) (y - 1)
          (%o4)                ----------------------
                                     36 (y + 1)
          (%i5) factor (1 + %e^(3*x));
                                x         2 x     x
          (%o5)              (%e  + 1) (%e    - %e  + 1)
          (%i6) factor (1 + x^4, a^2 - 2);
                              2              2
          (%o6)             (x  - a x + 1) (x  + a x + 1)
          (%i7) factor (-y^2*z^2 - x*z^2 + x^2*y^2 + x^3);
                                 2
          (%o7)              - (y  + x) (z - x) (z + x)
          (%i8) (2 + x)/(3 + x)/(b + x)/(c + x)^2;
                                       x + 2
          (%o8)               ------------------------
                                                     2
                              (x + 3) (x + b) (x + c)
          (%i9) ratsimp (%);
                          4                  3
          (%o9) (x + 2)/(x  + (2 c + b + 3) x

               2                       2             2                   2
           + (c  + (2 b + 6) c + 3 b) x  + ((b + 3) c  + 6 b c) x + 3 b c )
          (%i10) partfrac (%, x);
                     2                   4                3
          (%o10) - (c  - 4 c - b + 6)/((c  + (- 2 b - 6) c

               2              2         2                2
           + (b  + 12 b + 9) c  + (- 6 b  - 18 b) c + 9 b ) (x + c))

                           c - 2
           - ---------------------------------
               2                             2
             (c  + (- b - 3) c + 3 b) (x + c)

                                   b - 2
           + -------------------------------------------------
                       2             2       3      2
             ((b - 3) c  + (6 b - 2 b ) c + b  - 3 b ) (x + b)

                                   1
           - ----------------------------------------------
                       2
             ((b - 3) c  + (18 - 6 b) c + 9 b - 27) (x + 3)
          (%i11) map ('factor, %);
                        2
                       c  - 4 c - b + 6                 c - 2
          (%o11) - ------------------------- - ------------------------
                          2        2                                  2
                   (c - 3)  (c - b)  (x + c)   (c - 3) (c - b) (x + c)

                                 b - 2                        1
                      + ------------------------ - ------------------------
                                       2                          2
                        (b - 3) (c - b)  (x + b)   (b - 3) (c - 3)  (x + 3)
          (%i12) ratsimp ((x^5 - 1)/(x - 1));
                                 4    3    2
          (%o12)                x  + x  + x  + x + 1
          (%i13) subst (a, x, %);
                                 4    3    2
          (%o13)                a  + a  + a  + a + 1
          (%i14) factor (%th(2), %);
                                 2        3        3    2
          (%o14)   (x - a) (x - a ) (x - a ) (x + a  + a  + a + 1)
          (%i15) factor (1 + x^12);
                                 4        8    4
          (%o15)               (x  + 1) (x  - x  + 1)
          (%i16) factor (1 + x^99);
                           2            6    3
          (%o16) (x + 1) (x  - x + 1) (x  - x  + 1)

             10    9    8    7    6    5    4    3    2
           (x   - x  + x  - x  + x  - x  + x  - x  + x  - x + 1)

             20    19    17    16    14    13    11    10    9    7    6
           (x   + x   - x   - x   + x   + x   - x   - x   - x  + x  + x

              4    3            60    57    51    48    42    39    33
           - x  - x  + x + 1) (x   + x   - x   - x   + x   + x   - x

              30    27    21    18    12    9    3
           - x   - x   + x   + x   - x   - x  + x  + 1)


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

     When `factorflag' is `false', suppresses the factoring of integer
     factors of rational expressions.


 -- Function: factorout (<expr>, <x_1>, <x_2>, ...)
     Rearranges the sum <expr> into a sum of terms of the form `f
     (<x_1>, <x_2>, ...)*g' where `g' is a product of expressions not
     containing any <x_i> and `f' is factored.

     Note that the option variable `keepfloat' is ignored by
     `factorout'.

     Example:

          (%i1) expand (a*(x+1)*(x-1)*(u+1)^2);
                       2  2          2      2      2
          (%o1)     a u  x  + 2 a u x  + a x  - a u  - 2 a u - a
          (%i2) factorout(%,x);
                   2
          (%o2) a u  (x - 1) (x + 1) + 2 a u (x - 1) (x + 1)
                                                        + a (x - 1) (x + 1)


 -- Function: factorsum (<expr>)
     Tries to group terms in factors of <expr> which are sums into
     groups of terms such that their sum is factorable.  `factorsum'
     can recover the result of `expand ((x + y)^2 + (z + w)^2)' but it
     can't recover `expand ((x + 1)^2 + (x + y)^2)' because the terms
     have variables in common.

     Example:

          (%i1) expand ((x + 1)*((u + v)^2 + a*(w + z)^2));
                     2      2                            2      2
          (%o1) a x z  + a z  + 2 a w x z + 2 a w z + a w  x + v  x

                                               2        2    2            2
                                  + 2 u v x + u  x + a w  + v  + 2 u v + u
          (%i2) factorsum (%);
                                             2          2
          (%o2)            (x + 1) (a (z + w)  + (v + u) )


 -- Function: fasttimes (<p_1>, <p_2>)
     Returns the product of the polynomials <p_1> and <p_2> by using a
     special algorithm for multiplication of polynomials.  `p_1' and
     `p_2' should be multivariate, dense, and nearly the same size.
     Classical multiplication is of order `n_1 n_2' where `n_1' is the
     degree of `p_1' and `n_2' is the degree of `p_2'.  `fasttimes' is
     of order `max (n_1, n_2)^1.585'.


 -- Function: fullratsimp (<expr>)
     `fullratsimp' repeatedly applies `ratsimp' followed by
     non-rational simplification to an expression until no further
     change occurs, and returns the result.

     When non-rational expressions are involved, one call to `ratsimp'
     followed as is usual by non-rational ("general") simplification
     may not be sufficient to return a simplified result.  Sometimes,
     more than one such call may be necessary.  `fullratsimp' makes
     this process convenient.

     `fullratsimp (<expr>, <x_1>, ..., <x_n>)' takes one or more
     arguments similar to `ratsimp' and `rat'.

     Example:

          (%i1) expr: (x^(a/2) + 1)^2*(x^(a/2) - 1)^2/(x^a - 1);
                                 a/2     2   a/2     2
                               (x    - 1)  (x    + 1)
          (%o1)                -----------------------
                                        a
                                       x  - 1
          (%i2) ratsimp (expr);
                                    2 a      a
                                   x    - 2 x  + 1
          (%o2)                    ---------------
                                        a
                                       x  - 1
          (%i3) fullratsimp (expr);
                                        a
          (%o3)                        x  - 1
          (%i4) rat (expr);
                                 a/2 4       a/2 2
                               (x   )  - 2 (x   )  + 1
          (%o4)/R/             -----------------------
                                        a
                                       x  - 1


 -- Function: fullratsubst (<a>, <b>, <c>)
     is the same as `ratsubst' except that it calls itself recursively
     on its result until that result stops changing.  This function is
     useful when the replacement expression and the replaced expression
     have one or more variables in common.

     `fullratsubst' will also accept its arguments in the format of
     `lratsubst'.  That is, the first argument may be a single
     substitution equation or a list of such equations, while the
     second argument is the expression being processed.

     `load ("lrats")' loads `fullratsubst' and `lratsubst'.

     Examples:

          (%i1) load ("lrats")$

        * `subst' can carry out multiple substitutions.  `lratsubst' is
          analogous to `subst'.

          (%i2) subst ([a = b, c = d], a + c);
          (%o2)                         d + b
          (%i3) lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
          (%o3)                (d + a c) e + a d + b c

        * If only one substitution is desired, then a single equation
          may be given as first argument.

          (%i4) lratsubst (a^2 = b, a^3);
          (%o4)                          a b

        * `fullratsubst' is equivalent to `ratsubst' except that it
          recurses until its result stops changing.

          (%i5) ratsubst (b*a, a^2, a^3);
                                         2
          (%o5)                         a  b
          (%i6) fullratsubst (b*a, a^2, a^3);
                                           2
          (%o6)                         a b

        * `fullratsubst' also accepts a list of equations or a single
          equation as first argument.

          (%i7) fullratsubst ([a^2 = b, b^2 = c, c^2 = a], a^3*b*c);
          (%o7)                           b
          (%i8) fullratsubst (a^2 = b*a, a^3);
                                           2
          (%o8)                         a b

        * `fullratsubst' may cause an indefinite recursion.

          (%i9) errcatch (fullratsubst (b*a^2, a^2, a^3));

          *** - Lisp stack overflow. RESET


 -- Function: gcd (<p_1>, <p_2>, <x_1>, ...)
     Returns the greatest common divisor of <p_1> and <p_2>.  The flag
     `gcd' determines which algorithm is employed.  Setting `gcd' to
     `ez', `subres', `red', or `spmod' selects the `ezgcd',
     subresultant `prs', reduced, or modular algorithm, respectively.
     If `gcd' `false' then `gcd (<p_1>, <p_2>, <x>)' always returns 1
     for all <x>.  Many functions (e.g. `ratsimp', `factor', etc.)
     cause gcd's to be taken implicitly.  For homogeneous polynomials
     it is recommended that `gcd' equal to `subres' be used.  To take
     the gcd when an algebraic is present, e.g., `gcd (<x>^2 -
     2*sqrt(2)* <x> + 2, <x> - sqrt(2))', the option variable
     `algebraic' must be `true' and `gcd' must not be `ez'.

     The `gcd' flag, default: `spmod', if `false' will also prevent the
     greatest common divisor from being taken when expressions are
     converted to canonical rational expression (CRE) form.  This will
     sometimes speed the calculation if gcds are not required.

     See also `ezgcd', `gcdex', `gcdivide', and `poly_gcd'.

     Example:

          (%i1) p1:6*x^3+19*x^2+19*x+6;
                                  3       2
          (%o1)                6 x  + 19 x  + 19 x + 6
          (%i2) p2:6*x^5+13*x^4+12*x^3+13*x^2+6*x;
                            5       4       3       2
          (%o2)          6 x  + 13 x  + 12 x  + 13 x  + 6 x
          (%i3) gcd(p1, p2);
                                      2
          (%o3)                    6 x  + 13 x + 6
          (%i4) p1/gcd(p1, p2), ratsimp;
          (%o4)                         x + 1
          (%i5) p2/gcd(p1, p2), ratsimp;
                                        3
          (%o5)                        x  + x

     `ezgcd' returns a list whose first element is the greatest common
     divisor of the polynomials <p_1> and <p_2>, and whose remaining
     elements are the polynomials divided by the greatest common
     divisor.

          (%i6) ezgcd(p1, p2);
                              2                     3
          (%o6)           [6 x  + 13 x + 6, x + 1, x  + x]


 -- Function: gcdex (<f>, <g>)
 -- Function: gcdex (<f>, <g>, <x>)
     Returns a list `[<a>, <b>, <u>]' where <u> is the greatest common
     divisor (gcd) of <f> and <g>, and <u> is equal to `<a> <f> + <b>
     <g>'.  The arguments <f> and <g> should be univariate polynomials,
     or else polynomials in <x> a supplied main variable since we need
     to be in a principal ideal domain for this to work.  The gcd means
     the gcd regarding <f> and <g> as univariate polynomials with
     coefficients being rational functions in the other variables.

     `gcdex' implements the Euclidean algorithm, where we have a
     sequence of `L[i]: [a[i], b[i], r[i]]' which are all perpendicular
     to `[f, g, -1]' and the next one is built as if `q =
     quotient(r[i]/r[i+1])' then `L[i+2]: L[i] - q L[i+1]', and it
     terminates at `L[i+1]' when the remainder `r[i+2]' is zero.

     The arguments <f> and <g> can be integers.  For this case the
     function `igcdex' is called by `gcdex'.

     See also `ezgcd', `gcd', `gcdivide', and `poly_gcd'.

     Examples:

          (%i1) gcdex (x^2 + 1, x^3 + 4);
                                 2
                                x  + 4 x - 1  x + 4
          (%o1)/R/           [- ------------, -----, 1]
                                     17        17
          (%i2) % . [x^2 + 1, x^3 + 4, -1];
          (%o2)/R/                        0

     Note that the gcd in the following is `1' since we work in
     `k(y)[x]', not the  `y+1' we would expect in `k[y, x]'.

          (%i1) gcdex (x*(y + 1), y^2 - 1, x);
                                         1
          (%o1)/R/                 [0, ------, 1]
                                        2
                                       y  - 1


 -- Function: gcfactor (<n>)
     Factors the Gaussian integer <n> over the Gaussian integers, i.e.,
     numbers of the form `<a> + <b> `%i'' where <a> and <b> are
     rational integers (i.e.,  ordinary integers).  Factors are
     normalized by making <a> and <b> non-negative.


 -- Function: gfactor (<expr>)
     Factors the polynomial <expr> over the Gaussian integers (that is,
     the integers with the imaginary unit `%i' adjoined).  This is like
     `factor (<expr>, <a>^2+1)' where <a> is `%i'.

     Example:

          (%i1) gfactor (x^4 - 1);
          (%o1)           (x - 1) (x + 1) (x - %i) (x + %i)


 -- Function: gfactorsum (<expr>)
     is similar to `factorsum' but applies `gfactor' instead of
     `factor'.


 -- Function: hipow (<expr>, <x>)
     Returns the highest explicit exponent of <x> in <expr>.  <x> may
     be a variable or a general expression.  If <x> does not appear in
     <expr>, `hipow' returns `0'.

     `hipow' does not consider expressions equivalent to `expr'.  In
     particular, `hipow' does not expand `expr', so `hipow (<expr>,
     <x>)' and `hipow (expand (<expr>, <x>))' may yield different
     results.

     Examples:

          (%i1) hipow (y^3 * x^2 + x * y^4, x);
          (%o1)                           2
          (%i2) hipow ((x + y)^5, x);
          (%o2)                           1
          (%i3) hipow (expand ((x + y)^5), x);
          (%o3)                           5
          (%i4) hipow ((x + y)^5, x + y);
          (%o4)                           5
          (%i5) hipow (expand ((x + y)^5), x + y);
          (%o5)                           0


 -- Option variable: intfaclim
     Default value: true

     If `true', maxima will give up factorization of integers if no
     factor is found after trial divisions and Pollard's rho method and
     factorization will not be complete.

     When `intfaclim' is `false' (this is the case when the user calls
     `factor' explicitly), complete factorization will be attempted.
     `intfaclim' is set to `false' when factors are computed in
     `divisors', `divsum' and `totient'.

     Internal calls to `factor' respect the user-specified value of
     `intfaclim'.  Setting `intfaclim' to `true' may reduce the time
     spent factoring large integers.


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

     When `keepfloat' is `true', prevents floating point numbers from
     being rationalized when expressions which contain them are
     converted to canonical rational expression (CRE) form.

     Note that the function `solve' and those functions calling it
     (`eigenvalues', for example) currently ignore this flag, converting
     floating point numbers anyway.

     Examples:

          (%i1) rat(x/2.0);

          `rat' replaced 0.5 by 1/2 = 0.5
                                                 x
          (%o1)/R/                               -
                                                 2
          (%i2) rat(x/2.0), keepfloat;

          (%o2)/R/                             0.5 x

     `solve' ignores `keepfloat':

          (%i3) solve(1.0-x,x), keepfloat;

          `rat' replaced 1.0 by 1/1 = 1.0
          (%o3)                               [x = 1]


 -- Function: lopow (<expr>, <x>)
     Returns the lowest exponent of <x> which explicitly appears in
     <expr>.  Thus

          (%i1) lopow ((x+y)^2 + (x+y)^a, x+y);
          (%o1)                       min(a, 2)


 -- Function: lratsubst (<L>, <expr>)
     is analogous to `subst (<L>, <expr>)' except that it uses
     `ratsubst' instead of `subst'.

     The first argument of `lratsubst' is an equation or a list of
     equations identical in format to that accepted by `subst'.  The
     substitutions are made in the order given by the list of equations,
     that is, from left to right.

     `load ("lrats")' loads `fullratsubst' and `lratsubst'.

     Examples:

          (%i1) load ("lrats")$

        * `subst' can carry out multiple substitutions.  `lratsubst' is
          analogous to `subst'.

          (%i2) subst ([a = b, c = d], a + c);
          (%o2)                         d + b
          (%i3) lratsubst ([a^2 = b, c^2 = d], (a + e)*c*(a + c));
          (%o3)                (d + a c) e + a d + b c

        * If only one substitution is desired, then a single equation
          may be given as first argument.

          (%i4) lratsubst (a^2 = b, a^3);
          (%o4)                          a b


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

     When `modulus' is a positive number <p>, operations on rational
     numbers (as returned by `rat' and related functions) are carried
     out modulo <p>, using the so-called "balanced" modulus system in
     which `<n> modulo <p>' is defined as an integer <k> in
     `[-(<p>-1)/2, ..., 0, ..., (<p>-1)/2]' when <p> is odd, or
     `[-(<p>/2 - 1), ..., 0, ...., <p>/2]' when <p> is even, such that
     `<a> <p> + <k>' equals <n> for some integer <a>.

     If <expr> is already in canonical rational expression (CRE) form
     when `modulus' is reset, then you may need to re-rat <expr>, e.g.,
     `expr: rat (ratdisrep (expr))', in order to get correct results.

     Typically `modulus' is set to a prime number.  If `modulus' is set
     to a positive non-prime integer, this setting is accepted, but a
     warning message is displayed.  Maxima signals an error, when zero
     or a negative integer is assigned to `modulus'.

     Examples:

          (%i1) modulus:7;
          (%o1)                           7
          (%i2) polymod([0,1,2,3,4,5,6,7]);
          (%o2)            [0, 1, 2, 3, - 3, - 2, - 1, 0]
          (%i3) modulus:false;
          (%o3)                         false
          (%i4) poly:x^6+x^2+1;
                                      6    2
          (%o4)                      x  + x  + 1
          (%i5) factor(poly);
                                      6    2
          (%o5)                      x  + x  + 1
          (%i6) modulus:13;
          (%o6)                          13
          (%i7) factor(poly);
                                2        4      2
          (%o7)               (x  + 6) (x  - 6 x  - 2)
          (%i8) polymod(%);
                                      6    2
          (%o8)                      x  + x  + 1


 -- Function: num (<expr>)
     Returns the numerator of <expr> if it is a ratio.  If <expr> is
     not a ratio, <expr> is returned.

     `num' evaluates its argument.


 -- Function: polydecomp (<p>, <x>)
     Decomposes the polynomial <p> in the variable <x> into the
     functional composition of polynomials in <x>.  `polydecomp'
     returns a list `[<p_1>, ..., <p_n>]' such that

          lambda ([x], p_1) (lambda ([x], p_2) (... (lambda ([x], p_n) (x))
            ...))

     is equal to <p>.  The degree of <p_i> is greater than 1 for <i>
     less than <n>.

     Such a decomposition is not unique.

     Examples:

          (%i1) polydecomp (x^210, x);
                                    7   5   3   2
          (%o1)                   [x , x , x , x ]
          (%i2) p : expand (subst (x^3 - x - 1, x, x^2 - a));
                          6      4      3    2
          (%o2)          x  - 2 x  - 2 x  + x  + 2 x - a + 1
          (%i3) polydecomp (p, x);
                                  2       3
          (%o3)                 [x  - a, x  - x - 1]

     The following function composes `L = [e_1, ..., e_n]' as functions
     in `x'; it is the inverse of polydecomp:

          compose (L, x) :=
            block ([r : x], for e in L do r : subst (e, x, r), r) $

     Re-express above example using `compose':

          (%i3) polydecomp (compose ([x^2 - a, x^3 - x - 1], x), x);
                                  2       3
          (%o3)                 [x  - a, x  - x - 1]

     Note that though `compose (polydecomp (<p>, <x>), <x>)' always
     returns <p> (unexpanded), `polydecomp (compose ([<p_1>, ...,
     <p_n>], <x>), <x>)' does not necessarily return `[<p_1>, ...,
     <p_n>]':

          (%i4) polydecomp (compose ([x^2 + 2*x + 3, x^2], x), x);
                                    2       2
          (%o4)                   [x  + 2, x  + 1]
          (%i5) polydecomp (compose ([x^2 + x + 1, x^2 + x + 1], x), x);
                                2       2
                               x  + 3  x  + 5
          (%o5)               [------, ------, 2 x + 1]
                                 4       2


 -- Function: polymod (<p>)
 -- Function: polymod (<p>, <m>)
     Converts the polynomial <p> to a modular representation with
     respect to the current modulus which is the value of the variable
     `modulus'.

     `polymod (<p>, <m>)' specifies a modulus <m> to be used instead of
     the current value of `modulus'.

     See `modulus'.


 -- Function: quotient (<p_1>, <p_2>)
 -- Function: quotient (<p_1>, <p_2>, <x_1>, ..., <x_n>)
     Returns the polynomial <p_1> divided by the polynomial <p_2>.  The
     arguments <x_1>, ..., <x_n> are interpreted as in `ratvars'.

     `quotient' returns the first element of the two-element list
     returned by `divide'.


 -- Function: rat (<expr>)
 -- Function: rat (<expr>, <x_1>, ..., <x_n>)
     Converts <expr> to canonical rational expression (CRE) form by
     expanding and combining all terms over a common denominator and
     cancelling out the greatest common divisor of the numerator and
     denominator, as well as converting floating point numbers to
     rational numbers within a tolerance of `ratepsilon'.  The
     variables are ordered according to the <x_1>, ..., <x_n>, if
     specified, as in `ratvars'.

     `rat' does not generally simplify functions other than addition
     `+', subtraction `-', multiplication `*', division `/', and
     exponentiation to an integer power, whereas `ratsimp' does handle
     those cases.  Note that atoms (numbers and variables) in CRE form
     are not the same as they are in the general form.  For example,
     `rat(x)- x' yields `rat(0)' which has a different internal
     representation than 0.

     When `ratfac' is `true', `rat' yields a partially factored form
     for CRE.  During rational operations the expression is maintained
     as fully factored as possible without an actual call to the factor
     package.  This should always save space and may save some time in
     some computations.  The numerator and denominator are still made
     relatively prime (e.g.,  `rat((x^2 - 1)^4/(x + 1)^2)' yields `(x -
     1)^4 (x + 1)^2' when `ratfac' is `true'), but the factors within
     each part may not be relatively prime.

     `ratprint' if `false' suppresses the printout of the message
     informing the user of the conversion of floating point numbers to
     rational numbers.

     `keepfloat' if `true' prevents floating point numbers from being
     converted to rational numbers.

     See also `ratexpand' and  `ratsimp'.

     Examples:
          (%i1) ((x - 2*y)^4/(x^2 - 4*y^2)^2 + 1)*(y + a)*(2*y + x) /
                (4*y^2 + x^2);
                                                     4
                                            (x - 2 y)
                        (y + a) (2 y + x) (------------ + 1)
                                             2      2 2
                                           (x  - 4 y )
          (%o1)         ------------------------------------
                                        2    2
                                     4 y  + x
          (%i2) rat (%, y, a, x);
                                      2 a + 2 y
          (%o2)/R/                    ---------
                                       x + 2 y


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

     When `ratalgdenom' is `true', allows rationalization of
     denominators with respect to radicals to take effect.
     `ratalgdenom' has an effect only when canonical rational
     expressions (CRE) are used in algebraic mode.


 -- Function: ratcoef (<expr>, <x>, <n>)
 -- Function: ratcoef (<expr>, <x>)
     Returns the coefficient of the expression `<x>^<n>' in the
     expression <expr>.  If omitted, <n> is assumed to be 1.

     The return value is free (except possibly in a non-rational sense)
     of the variables in <x>.  If no coefficient of this type exists, 0
     is returned.

     `ratcoef' expands and rationally simplifies its first argument and
     thus it may produce answers different from those of `coeff' which
     is purely syntactic.  Thus `ratcoef ((x + 1)/y + x, x)' returns
     `(y + 1)/y' whereas `coeff' returns 1.

     `ratcoef (<expr>, <x>, 0)', viewing <expr> as a sum, returns a sum
     of those terms which do not contain <x>.  Therefore if <x> occurs
     to any negative powers, `ratcoef' should not be used.

     Since <expr> is rationally simplified before it is examined,
     coefficients may not appear quite the way they were envisioned.

     Example:

          (%i1) s: a*x + b*x + 5$
          (%i2) ratcoef (s, a + b);
          (%o2)                           x


 -- Function: ratdenom (<expr>)
     Returns the denominator of <expr>, after coercing <expr> to a
     canonical rational expression (CRE).  The return value is a CRE.

     <expr> is coerced to a CRE by `rat' if it is not already a CRE.
     This conversion may change the form of <expr> by putting all terms
     over a common denominator.

     `denom' is similar, but returns an ordinary expression instead of
     a CRE.  Also, `denom' does not attempt to place all terms over a
     common denominator, and thus some expressions which are considered
     ratios by `ratdenom' are not considered ratios by `denom'.


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

     When `ratdenomdivide' is `true', `ratexpand' expands a ratio in
     which the numerator is a sum into a sum of ratios, all having a
     common denominator.  Otherwise, `ratexpand' collapses a sum of
     ratios into a single ratio, the numerator of which is the sum of
     the numerators of each ratio.

     Examples:

          (%i1) expr: (x^2 + x + 1)/(y^2 + 7);
                                      2
                                     x  + x + 1
          (%o1)                      ----------
                                        2
                                       y  + 7
          (%i2) ratdenomdivide: true$
          (%i3) ratexpand (expr);
                                 2
                                x        x        1
          (%o3)               ------ + ------ + ------
                               2        2        2
                              y  + 7   y  + 7   y  + 7
          (%i4) ratdenomdivide: false$
          (%i5) ratexpand (expr);
                                      2
                                     x  + x + 1
          (%o5)                      ----------
                                        2
                                       y  + 7
          (%i6) expr2: a^2/(b^2 + 3) + b/(b^2 + 3);
                                               2
                                     b        a
          (%o6)                    ------ + ------
                                    2        2
                                   b  + 3   b  + 3
          (%i7) ratexpand (expr2);
                                            2
                                       b + a
          (%o7)                        ------
                                        2
                                       b  + 3


 -- Function: ratdiff (<expr>, <x>)
     Differentiates the rational expression <expr> with respect to <x>.
     <expr> must be a ratio of polynomials or a polynomial in <x>.  The
     argument <x> may be a variable or a subexpression of <expr>.

     The result is equivalent to `diff', although perhaps in a
     different form.  `ratdiff' may be faster than `diff', for rational
     expressions.

     `ratdiff' returns a canonical rational expression (CRE) if `expr'
     is a CRE.  Otherwise, `ratdiff' returns a general expression.

     `ratdiff' considers only the dependence of <expr> on <x>, and
     ignores any dependencies established by `depends'.

     Example:

          (%i1) expr: (4*x^3 + 10*x - 11)/(x^5 + 5);
                                     3
                                  4 x  + 10 x - 11
          (%o1)                   ----------------
                                        5
                                       x  + 5
          (%i2) ratdiff (expr, x);
                              7       5       4       2
                           8 x  + 40 x  - 55 x  - 60 x  - 50
          (%o2)          - ---------------------------------
                                    10       5
                                   x   + 10 x  + 25
          (%i3) expr: f(x)^3 - f(x)^2 + 7;
                                   3       2
          (%o3)                   f (x) - f (x) + 7
          (%i4) ratdiff (expr, f(x));
                                     2
          (%o4)                   3 f (x) - 2 f(x)
          (%i5) expr: (a + b)^3 + (a + b)^2;
                                        3          2
          (%o5)                  (b + a)  + (b + a)
          (%i6) ratdiff (expr, a + b);
                              2                    2
          (%o6)            3 b  + (6 a + 2) b + 3 a  + 2 a


 -- Function: ratdisrep (<expr>)
     Returns its argument as a general expression.  If <expr> is a
     general expression, it is returned unchanged.

     Typically `ratdisrep' is called to convert a canonical rational
     expression (CRE) into a general expression.  This is sometimes
     convenient if one wishes to stop the "contagion", or use rational
     functions in non-rational contexts.

     See also `totaldisrep'.


 -- Function: ratexpand (<expr>)
 -- Option variable: ratexpand
     Expands <expr> by multiplying out products of sums and
     exponentiated sums, combining fractions over a common denominator,
     cancelling the greatest common divisor of the numerator and
     denominator, then splitting the numerator (if a sum) into its
     respective terms divided by the denominator.

     The return value of `ratexpand' is a general expression, even if
     <expr> is a canonical rational expression (CRE).

     The switch `ratexpand' if `true' will cause CRE expressions to be
     fully expanded when they are converted back to general form or
     displayed, while if it is `false' then they will be put into a
     recursive form.  See also `ratsimp'.

     When `ratdenomdivide' is `true', `ratexpand' expands a ratio in
     which the numerator is a sum into a sum of ratios, all having a
     common denominator.  Otherwise, `ratexpand' collapses a sum of
     ratios into a single ratio, the numerator of which is the sum of
     the numerators of each ratio.

     When `keepfloat' is `true', prevents floating point numbers from
     being rationalized when expressions which contain them are
     converted to canonical rational expression (CRE) form.

     Examples:

          (%i1) ratexpand ((2*x - 3*y)^3);
                               3         2       2        3
          (%o1)          - 27 y  + 54 x y  - 36 x  y + 8 x
          (%i2) expr: (x - 1)/(x + 1)^2 + 1/(x - 1);
                                   x - 1       1
          (%o2)                   -------- + -----
                                         2   x - 1
                                  (x + 1)
          (%i3) expand (expr);
                              x              1           1
          (%o3)          ------------ - ------------ + -----
                          2              2             x - 1
                         x  + 2 x + 1   x  + 2 x + 1
          (%i4) ratexpand (expr);
                                  2
                               2 x                 2
          (%o4)           --------------- + ---------------
                           3    2            3    2
                          x  + x  - x - 1   x  + x  - x - 1


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

     When `ratfac' is `true', canonical rational expressions (CRE) are
     manipulated in a partially factored form.

     During rational operations the expression is maintained as fully
     factored as possible without calling `factor'.  This should always
     save space and may save time in some computations.  The numerator
     and denominator are made relatively prime, for example `factor
     ((x^2 - 1)^4/(x + 1)^2)' yields `(x - 1)^4 (x + 1)^2', but the
     factors within each part may not be relatively prime.

     In the `ctensr' (Component Tensor Manipulation) package, Ricci,
     Einstein, Riemann, and Weyl tensors and the scalar curvature are
     factored automatically when `ratfac' is `true'.  `ratfac' should
     only be set for cases where the tensorial components are known to
     consist of few terms.

     The `ratfac' and `ratweight' schemes are incompatible and may not
     both be used at the same time.


 -- Function: ratnumer (<expr>)
     Returns the numerator of <expr>, after coercing <expr> to a
     canonical rational expression (CRE).  The return value is a CRE.

     <expr> is coerced to a CRE by `rat' if it is not already a CRE.
     This conversion may change the form of <expr> by putting all terms
     over a common denominator.

     `num' is similar, but returns an ordinary expression instead of a
     CRE.  Also, `num' does not attempt to place all terms over a
     common denominator, and thus some expressions which are considered
     ratios by `ratnumer' are not considered ratios by `num'.


 -- Function: ratp (<expr>)
     Returns `true' if <expr> is a canonical rational expression (CRE)
     or extended CRE, otherwise `false'.

     CRE are created by `rat' and related functions.  Extended CRE are
     created by `taylor' and related functions.


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

     When `ratprint' is `true', a message informing the user of the
     conversion of floating point numbers to rational numbers is
     displayed.


 -- Function: ratsimp (<expr>)
 -- Function: ratsimp (<expr>, <x_1>, ..., <x_n>)
     Simplifies the expression <expr> and all of its subexpressions,
     including the arguments to non-rational functions.  The result is
     returned as the quotient of two polynomials in a recursive form,
     that is, the coefficients of the main variable are polynomials in
     the other variables.  Variables may include non-rational functions
     (e.g., `sin (x^2 + 1)') and the arguments to any such functions
     are also rationally simplified.

     `ratsimp (<expr>, <x_1>, ..., <x_n>)' enables rational
     simplification with the specification of variable ordering as in
     `ratvars'.

     When `ratsimpexpons' is `true', `ratsimp' is applied to the
     exponents of expressions during simplification.

     See also `ratexpand'.  Note that `ratsimp' is affected by some of
     the flags which affect `ratexpand'.

     Examples:

          (%i1) sin (x/(x^2 + x)) = exp ((log(x) + 1)^2 - log(x)^2);
                                                   2      2
                             x         (log(x) + 1)  - log (x)
          (%o1)        sin(------) = %e
                            2
                           x  + x
          (%i2) ratsimp (%);
                                       1          2
          (%o2)                  sin(-----) = %e x
                                     x + 1
          (%i3) ((x - 1)^(3/2) - (x + 1)*sqrt(x - 1))/sqrt((x - 1)*(x + 1));
                                 3/2
                          (x - 1)    - sqrt(x - 1) (x + 1)
          (%o3)           --------------------------------
                               sqrt((x - 1) (x + 1))
          (%i4) ratsimp (%);
                                     2 sqrt(x - 1)
          (%o4)                    - -------------
                                           2
                                     sqrt(x  - 1)
          (%i5) x^(a + 1/a), ratsimpexpons: true;
                                         2
                                        a  + 1
                                        ------
                                          a
          (%o5)                        x


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

     When `ratsimpexpons' is `true', `ratsimp' is applied to the
     exponents of expressions during simplification.


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

     `radsubstflag', if `true', permits `ratsubst' to make
     substitutions such as `u' for `sqrt (x)' in `x'.


 -- Function: ratsubst (<a>, <b>, <c>)
     Substitutes <a> for <b> in <c> and returns the resulting
     expression.  <b> may be a sum, product, power, etc.

     `ratsubst' knows something of the meaning of expressions whereas
     `subst' does a purely syntactic substitution.  Thus `subst (a, x +
     y, x + y + z)' returns `x + y + z' whereas `ratsubst' returns `z +
     a'.

     When `radsubstflag' is `true', `ratsubst' makes substitutions for
     radicals in expressions which don't explicitly contain them.

     `ratsubst' ignores the value `true' of the option variable
     `keepfloat'.

     Examples:

          (%i1) ratsubst (a, x*y^2, x^4*y^3 + x^4*y^8);
                                        3      4
          (%o1)                      a x  y + a
          (%i2) cos(x)^4 + cos(x)^3 + cos(x)^2 + cos(x) + 1;
                         4         3         2
          (%o2)       cos (x) + cos (x) + cos (x) + cos(x) + 1
          (%i3) ratsubst (1 - sin(x)^2, cos(x)^2, %);
                      4           2                     2
          (%o3)    sin (x) - 3 sin (x) + cos(x) (2 - sin (x)) + 3
          (%i4) ratsubst (1 - cos(x)^2, sin(x)^2, sin(x)^4);
                                  4           2
          (%o4)                cos (x) - 2 cos (x) + 1
          (%i5) radsubstflag: false$
          (%i6) ratsubst (u, sqrt(x), x);
          (%o6)                           x
          (%i7) radsubstflag: true$
          (%i8) ratsubst (u, sqrt(x), x);
                                          2
          (%o8)                          u


 -- Function: ratvars (<x_1>, ..., <x_n>)
 -- Function: ratvars ()
 -- System variable: ratvars
     Declares main variables <x_1>, ..., <x_n> for rational expressions.
     <x_n>, if present in a rational expression, is considered the main
     variable.  Otherwise, <x_[n-1]> is considered the main variable if
     present, and so on through the preceding variables to <x_1>, which
     is considered the main variable only if none of the succeeding
     variables are present.

     If a variable in a rational expression is not present in the
     `ratvars' list, it is given a lower priority than <x_1>.

     The arguments to `ratvars' can be either variables or non-rational
     functions such as `sin(x)'.

     The variable `ratvars' is a list of the arguments of the function
     `ratvars' when it was called most recently.  Each call to the
     function `ratvars' resets the list.  `ratvars ()' clears the list.


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

     Maxima keeps an internal list in the Lisp variable `VARLIST' of
     the main variables for rational expressions.  If `ratvarswitch' is
     `true', every evaluation starts with a fresh list `VARLIST'.  This
     is the default behavior.  Otherwise, the main variables from
     previous evaluations are not removed from the internal list
     `VARLIST'.

     The main variables, which are declared with the function `ratvars'
     are not affected by the option variable `ratvarswitch'.

     Examples:

     If `ratvarswitch' is `true', every evaluation starts with a fresh
     list `VARLIST'.

          (%i1) ratvarswitch:true$

          (%i2) rat(2*x+y^2);
                                       2
          (%o2)/R/                    y  + 2 x
          (%i3) :lisp varlist
          ($X $Y)

          (%i3) rat(2*a+b^2);
                                       2
          (%o3)/R/                    b  + 2 a

          (%i4) :lisp varlist
          ($A $B)

     If `ratvarswitch' is `false', the main variables from the last
     evaluation are still present.

          (%i4) ratvarswitch:false$

          (%i5) rat(2*x+y^2);
                                       2
          (%o5)/R/                    y  + 2 x
          (%i6) :lisp varlist
          ($X $Y)

          (%i6) rat(2*a+b^2);
                                       2
          (%o6)/R/                    b  + 2 a

          (%i7) :lisp varlist
          ($A $B $X $Y)


 -- Function: ratweight (<x_1>, <w_1>, ..., <x_n>, <w_n>)
 -- Function: ratweight ()
     Assigns a weight <w_i> to the variable <x_i>.  This causes a term
     to be replaced by 0 if its weight exceeds the value of the
     variable `ratwtlvl' (default yields no truncation).  The weight of
     a term is the sum of the products of the weight of a variable in
     the term times its power.  For example, the weight of `3 x_1^2
     x_2' is `2 w_1 + w_2'.  Truncation according to `ratwtlvl' is
     carried out only when multiplying or exponentiating canonical
     rational expressions (CRE).

     `ratweight ()' returns the cumulative list of weight assignments.

     Note: The `ratfac' and `ratweight' schemes are incompatible and may
     not both be used at the same time.

     Examples:

          (%i1) ratweight (a, 1, b, 1);
          (%o1)                     [a, 1, b, 1]
          (%i2) expr1: rat(a + b + 1)$
          (%i3) expr1^2;
                            2                  2
          (%o3)/R/         b  + (2 a + 2) b + a  + 2 a + 1
          (%i4) ratwtlvl: 1$
          (%i5) expr1^2;
          (%o5)/R/                  2 b + 2 a + 1


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

     `ratweights' is the list of weights assigned by `ratweight'.  The
     list is cumulative: each call to `ratweight' places additional
     items in the list.

     `kill (ratweights)' and `save (ratweights)' both work as expected.


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

     `ratwtlvl' is used in combination with the `ratweight' function to
     control the truncation of canonical rational expressions (CRE).
     For the default value of `false', no truncation occurs.


 -- Function: remainder (<p_1>, <p_2>)
 -- Function: remainder (<p_1>, <p_2>, <x_1>, ..., <x_n>)
     Returns the remainder of the polynomial <p_1> divided by the
     polynomial <p_2>.  The arguments <x_1>, ..., <x_n> are interpreted
     as in `ratvars'.

     `remainder' returns the second element of the two-element list
     returned by `divide'.


 -- Function: resultant (<p_1>, <p_2>, <x>)
     The function `resultant' computes the resultant of the two
     polynomials <p_1> and <p_2>, eliminating the variable <x>.  The
     resultant is a determinant of the coefficients of <x> in <p_1> and
     <p_2>, which equals zero if and only if <p_1> and <p_2> have a
     non-constant factor in common.

     If <p_1> or <p_2> can be factored, it may be desirable to call
     `factor' before calling `resultant'.

     The option variable `resultant' controls which algorithm will be
     used to compute the resultant.  See the option variable
     `resultant'.

     The function `bezout' takes the same arguments as `resultant' and
     returns a matrix.  The determinant of the return value is the
     desired resultant.

     Examples:

          (%i1) resultant(2*x^2+3*x+1, 2*x^2+x+1, x);
          (%o1)                           8
          (%i2) resultant(x+1, x+1, x);
          (%o2)                           0
          (%i3) resultant((x+1)*x, (x+1), x);
          (%o3)                           0
          (%i4) resultant(a*x^2+b*x+1, c*x + 2, x);
                                   2
          (%o4)                   c  - 2 b c + 4 a

          (%i5) bezout(a*x^2+b*x+1, c*x+2, x);
                                  [ 2 a  2 b - c ]
          (%o5)                   [              ]
                                  [  c      2    ]
          (%i6) determinant(%);
          (%o6)                   4 a - (2 b - c) c


 -- Option variable: resultant
     Default value: `subres'

     The option variable `resultant' controls which algorithm will be
     used to compute the resultant with the function `resultant'.  The
     possible values are:

    `subres'
          for the subresultant polynomial remainder sequence (PRS)
          algorithm,

    `mod'
          for the modular resultant algorithm, and

    `red'
          for the reduced polynomial remainder sequence (PRS) algorithm.

     On most problems the default value `subres' should be best.  On
     some large degree univariate or bivariate problems `mod' may be
     better.


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

     When `savefactors' is `true', causes the factors of an expression
     which is a product of factors to be saved by certain functions in
     order to speed up later factorizations of expressions containing
     some of the same factors.


 -- Function: showratvars (<expr>)
     Returns a list of the canonical rational expression (CRE)
     variables in expression `expr'.

     See also `ratvars'.


 -- Function: sqfr (<expr>)
     is similar to `factor' except that the polynomial factors are
     "square-free."  That is, they have factors only of degree one.
     This algorithm, which is also used by the first stage of `factor',
     utilizes the fact that a polynomial has in common with its n'th
     derivative all its factors of degree greater than n.  Thus by
     taking greatest common divisors with the polynomial of the
     derivatives with respect to each variable in the polynomial, all
     factors of degree greater than 1 can be found.

     Example:

          (%i1) sqfr (4*x^4 + 4*x^3 - 3*x^2 - 4*x - 1);
                                          2   2
          (%o1)                  (2 x + 1)  (x  - 1)


 -- Function: tellrat (<p_1>, ..., <p_n>)
 -- Function: tellrat ()
     Adds to the ring of algebraic integers known to Maxima the
     elements which are the solutions of the polynomials <p_1>, ...,
     <p_n>.  Each argument <p_i> is a polynomial with integer
     coefficients.

     `tellrat (<x>)' effectively means substitute 0 for <x> in rational
     functions.

     `tellrat ()' returns a list of the current substitutions.

     `algebraic' must be set to `true' in order for the simplification
     of algebraic integers to take effect.

     Maxima initially knows about the imaginary unit `%i' and all roots
     of integers.

     There is a command `untellrat' which takes kernels and removes
     `tellrat' properties.

     When `tellrat''ing a multivariate polynomial, e.g., `tellrat (x^2
     - y^2)', there would be an ambiguity as to whether to substitute
     `<y>^2' for `<x>^2' or vice versa.  Maxima picks a particular
     ordering, but if the user wants to specify which, e.g.  `tellrat
     (y^2 = x^2)' provides a syntax which says replace `<y>^2' by
     `<x>^2'.

     Examples:

          (%i1) 10*(%i + 1)/(%i + 3^(1/3));
                                     10 (%i + 1)
          (%o1)                      -----------
                                            1/3
                                      %i + 3
          (%i2) ev (ratdisrep (rat(%)), algebraic);
                       2/3      1/3              2/3      1/3
          (%o2)    (4 3    - 2 3    - 4) %i + 2 3    + 4 3    - 2
          (%i3) tellrat (1 + a + a^2);
                                      2
          (%o3)                     [a  + a + 1]
          (%i4) 1/(a*sqrt(2) - 1) + a/(sqrt(3) + sqrt(2));
                                1                 a
          (%o4)           ------------- + -----------------
                          sqrt(2) a - 1   sqrt(3) + sqrt(2)
          (%i5) ev (ratdisrep (rat(%)), algebraic);
                   (7 sqrt(3) - 10 sqrt(2) + 2) a - 2 sqrt(2) - 1
          (%o5)    ----------------------------------------------
                                         7
          (%i6) tellrat (y^2 = x^2);
                                  2    2   2
          (%o6)                 [y  - x , a  + a + 1]


 -- Function: totaldisrep (<expr>)
     Converts every subexpression of <expr> from canonical rational
     expressions (CRE) to general form and returns the result.  If
     <expr> is itself in CRE form then `totaldisrep' is identical to
     `ratdisrep'.

     `totaldisrep' may be useful for ratdisrepping expressions such as
     equations, lists, matrices, etc., which have some subexpressions
     in CRE form.


 -- Function: untellrat (<x_1>, ..., <x_n>)
     Removes `tellrat' properties from <x_1>, ..., <x_n>.



File: maxima.info,  Node: Special Functions,  Next: Elliptic Functions,  Prev: Polynomials,  Up: Top

15 Special Functions
********************

* Menu:

* Introduction to Special Functions::
* Bessel Functions::
* Airy Functions::
* Gamma and factorial Functions::
* Exponential Integrals::
* Error Function::
* Struve Functions::
* Hypergeometric Functions::
* Parabolic Cylinder Functions::
* Functions and Variables for Special Functions::


File: maxima.info,  Node: Introduction to Special Functions,  Next: Bessel Functions,  Prev: Special Functions,  Up: Special Functions

15.1 Introduction to Special Functions
======================================

Special function notation follows:

     bessel_j (index, expr)         Bessel function, 1st kind
     bessel_y (index, expr)         Bessel function, 2nd kind
     bessel_i (index, expr)         Modified Bessel function, 1st kind
     bessel_k (index, expr)         Modified Bessel function, 2nd kind

     hankel_1 (v,z)                 Hankel function of the 1st kind
     hankel_2 (v,z)                 Hankel function of the 2nd kind
     struve_h (v,z)                 Struve H function
     struve_l (v,z)                 Struve L function

     assoc_legendre_p[v,u] (z)      Legendre function of degree v and order u
     assoc_legendre_q[v,u] (z)      Legendre function, 2nd kind

     %f[p,q] ([], [], expr)         Generalized Hypergeometric function
     gamma (z)                      Gamma function
     gamma_greek (a,z)              Incomplete gamma function
     gamma_incomplete (a,z)         Tail of incomplete gamma function
     hypergeometric (l1, l2, z)     Hypergeometric function
     slommel
     %m[u,k] (z)                    Whittaker function, 1st kind
     %w[u,k] (z)                    Whittaker function, 2nd kind
     erfc (z)                       Complement of the erf function

     expintegral_e (v,z)            Exponential integral E
     expintegral_e1 (z)             Exponential integral E1
     expintegral_ei (z)             Exponential integral Ei
     expintegral_li (z)             Logarithmic integral Li
     expintegral_si (z)             Exponential integral Si
     expintegral_ci (z)             Exponential integral Ci
     expintegral_shi (z)            Exponential integral Shi
     expintegral_chi (z)            Exponential integral Chi

     kelliptic (z)                  Complete elliptic integral of the first
                                    kind (K)
     parabolic_cylinder_d (v,z)     Parabolic cylinder D function


File: maxima.info,  Node: Bessel Functions,  Next: Airy Functions,  Prev: Introduction to Special Functions,  Up: Special Functions

15.2 Bessel Functions
=====================

 -- Function: bessel_j (<v>, <z>)
     The Bessel function of the first kind of order v and argument z.

     `bessel_j' is defined as

                          inf
                          ====       k  - v - 2 k  v + 2 k
                          \     (- 1)  2          z
                           >    --------------------------
                          /        k! gamma(v + k + 1)
                          ====
                          k = 0

     although the infinite series is not used for computations.


 -- Function: bessel_y (<v>, <z>)
     The Bessel function of the second kind of order v and argument z.

     `bessel_y' is defined as
                        cos(%pi v) bessel_j(v, z) - bessel_j(-v, z)
                        -------------------------------------------
                                       sin(%pi v)

     when v is not an integer.  When v is an integer n, the limit as v
     approaches n is taken.


 -- Function: bessel_i (<v>, <z>)
     The modified Bessel function of the first kind of order v and
     argument z.

     `bessel_i' is defined as
                              inf
                              ====   - v - 2 k  v + 2 k
                              \     2          z
                               >    -------------------
                              /     k! gamma(v + k + 1)
                              ====
                              k = 0

     although the infinite series is not used for computations.


 -- Function: bessel_k (<v>, <z>)
     The modified Bessel function of the second kind of order v and
     argument z.

     `bessel_k' is defined as
                     %pi csc(%pi v) (bessel_i(-v, z) - bessel_i(v, z))
                     -------------------------------------------------
                                            2

     when v is not an integer.  If v is an integer n, then the limit as
     v approaches n is taken.


 -- Function: hankel_1 (<v>, <z>)
     The Hankel function of the first kind of order v and argument z
     (A&S 9.1.3). `hankel_1' is defined as

             bessel_j(v,z) + %i * bessel_y(v,z)

     Maxima evaluates `hankel_1' numerically for a complex order v and
     complex argument z in float precision. The numerical evaluation in
     bigfloat precision is not supported.

     When `besselexpand' is `true', `hankel_1' is expanded in terms of
     elementary functions when the order v is half of an odd integer.
     See `besselexpand'.

     Maxima knows the derivative of `hankel_1' wrt the argument z.

     Examples:

     Numerical evaluation:

          (%i1) hankel_1(1,0.5);
          (%o1)        0.24226845767487 - 1.471472392670243 %i
          (%i2) hankel_1(1,0.5+%i);
          (%o2)       - 0.25582879948621 %i - 0.23957560188301

     Expansion of `hankel_1' when `besselexpand' is `true':

          (%i1) hankel_1(1/2,z),besselexpand:true;
                         sqrt(2) sin(z) - sqrt(2) %i cos(z)
          (%o1)          ----------------------------------
                                 sqrt(%pi) sqrt(z)

     Derivative of `hankel_1' wrt the argument z. The derivative wrt the
     order v is not supported. Maxima returns a noun form:

          (%i1) diff(hankel_1(v,z),z);
                       hankel_1(v - 1, z) - hankel_1(v + 1, z)
          (%o1)        ---------------------------------------
                                          2
          (%i2) diff(hankel_1(v,z),v);
                                 d
          (%o2)                  -- (hankel_1(v, z))
                                 dv


 -- Function: hankel_2 (<v>, <z>)
     The Hankel function of the second kind of order v and argument z
     (A&S 9.1.4). `hankel_2' is defined as

             bessel_j(v,z) - %i * bessel_y(v,z)

     Maxima evaluates `hankel_2' numerically for a complex order v and
     complex argument z in float precision. The numerical evaluation in
     bigfloat precision is not supported.

     When `besselexpand' is `true', `hankel_2' is expanded in terms of
     elementary functions when the order v is half of an odd integer.
     See `besselexpand'.

     Maxima knows the derivative of `hankel_2' wrt the argument z.

     For examples see `hankel_1'.


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

     Controls expansion of the Bessel functions when the order is half
     of an odd integer.  In this case, the Bessel functions can be
     expanded in terms of other elementary functions.  When
     `besselexpand' is `true', the Bessel function is expanded.

          (%i1) besselexpand: false$
          (%i2) bessel_j (3/2, z);
                                              3
          (%o2)                      bessel_j(-, z)
                                              2
          (%i3) besselexpand: true$
          (%i4) bessel_j (3/2, z);
                                                  sin(z)   cos(z)
                                 sqrt(2) sqrt(z) (------ - ------)
                                                     2       z
                                                    z
          (%o4)                  ---------------------------------
                                             sqrt(%pi)


 -- Function: scaled_bessel_i (<v>, <z>)
     The scaled modified Bessel function of the first kind of order v
     and argument z.  That is, scaled_bessel_i(v,z) =
     exp(-abs(z))*bessel_i(v, z).  This function is particularly useful
     for calculating bessel_i for large z, which is large.  However,
     maxima does not otherwise know much about this function.  For
     symbolic work, it is probably preferable to work with the
     expression `exp(-abs(z))*bessel_i(v, z)'.


 -- Function: scaled_bessel_i0 (<z>)
     Identical to `scaled_bessel_i(0,z)'.


 -- Function: scaled_bessel_i1 (<z>)
     Identical to `scaled_bessel_i(1,z)'.


 -- Function: %s [<u>,<v>] (<z>)
     Lommel's little s[u,v](z) function.  Probably Gradshteyn & Ryzhik
     8.570.1.



File: maxima.info,  Node: Airy Functions,  Next: Gamma and factorial Functions,  Prev: Bessel Functions,  Up: Special Functions

15.3 Airy Functions
===================

The Airy functions Ai(x) and Bi(x) are defined in Abramowitz and Stegun,
Handbook of Mathematical Functions, Section 10.4.

   `y = Ai(x)' and `y = Bi(x)' are two linearly independent solutions
of the Airy differential equation `diff (y(x), x, 2) - x y(x) = 0'.

   If the argument `x' is a real or complex floating point number, the
numerical value of the function is returned.

 -- Function: airy_ai (<x>)
     The Airy function Ai(x).  (A&S 10.4.2)

     The derivative `diff (airy_ai(x), x)' is `airy_dai(x)'.

     See also `airy_bi', `airy_dai', `airy_dbi'.


 -- Function: airy_dai (<x>)
     The derivative of the Airy function Ai `airy_ai(x)'.

     See `airy_ai'.


 -- Function: airy_bi (<x>)
     The Airy function Bi(x).  (A&S 10.4.3)

     The derivative `diff (airy_bi(x), x)' is `airy_dbi(x)'.

     See `airy_ai', `airy_dbi'.


 -- Function: airy_dbi (<x>)
     The derivative of the Airy Bi function `airy_bi(x)'.

     See `airy_ai' and `airy_bi'.



File: maxima.info,  Node: Gamma and factorial Functions,  Next: Exponential Integrals,  Prev: Airy Functions,  Up: Special Functions

15.4 Gamma and factorial Functions
==================================

The gamma function and the related beta, psi and incomplete gamma
functions are defined in Abramowitz and Stegun, Handbook of
Mathematical Functions, Chapter 6.

 -- Function: bffac (<expr>, <n>)
     Bigfloat version of the factorial (shifted gamma) function.  The
     second argument is how many digits to retain and return, it's a
     good idea to request a couple of extra.


 -- Function: bfpsi (<n>, <z>, <fpprec>)
 -- Function: bfpsi0 (<z>, <fpprec>)
     `bfpsi' is the polygamma function of real argument <z> and integer
     order <n>.  `bfpsi0' is the digamma function.  `bfpsi0 (<z>,
     <fpprec>)' is equivalent to `bfpsi (0, <z>, <fpprec>)'.

     These functions return bigfloat values.  <fpprec> is the bigfloat
     precision of the return value.


 -- Function: cbffac (<z>, <fpprec>)
     Complex bigfloat factorial.

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


 -- Function: gamma (<z>)
     The basic definition of the gamma function (A&S 6.1.1) is

                                   inf
                                  /
                                  [     z - 1   - t
                       gamma(z) = I    t      %e    dt
                                  ]
                                  /
                                   0

     Maxima simplifies `gamma' for positive integer and positive and
     negative rational numbers. For half integral values the result is
     a rational number times `sqrt(%pi)'. The simplification for
     integer values is controlled by `factlim'. For integers greater
     than `factlim' the numerical result of the factorial function,
     which is used to calculate `gamma', will overflow.  The
     simplification for rational numbers is controlled by `gammalim' to
     avoid internal overflow. See `factlim' and `gammalim'.

     For negative integers `gamma' is not defined.

     Maxima can evalute `gamma' numerically for real and complex values
     in float and bigfloat precision.

     `gamma' has mirror symmetry.

     When `gamma_expand' is `true', Maxima expands `gamma' for
     arguments `z+n' and `z-n' where `n' is an integer.

     Maxima knows the derivate of `gamma'.

     Examples:

     Simplification for integer, half integral, and rational numbers:

          (%i1) map('gamma,[1,2,3,4,5,6,7,8,9]);
          (%o1)        [1, 1, 2, 6, 24, 120, 720, 5040, 40320]
          (%i2) map('gamma,[1/2,3/2,5/2,7/2]);
                              sqrt(%pi)  3 sqrt(%pi)  15 sqrt(%pi)
          (%o2)   [sqrt(%pi), ---------, -----------, ------------]
                                  2           4            8
          (%i3) map('gamma,[2/3,5/3,7/3]);
                                            2           1
                                    2 gamma(-)  4 gamma(-)
                                2           3           3
          (%o3)          [gamma(-), ----------, ----------]
                                3       3           9

     Numerical evaluation for real and complex values:

          (%i4) map('gamma,[2.5,2.5b0]);
          (%o4)     [1.329340388179137, 1.3293403881791370205b0]
          (%i5) map('gamma,[1.0+%i,1.0b0+%i]);
          (%o5) [0.498015668118356 - .1549498283018107 %i,
                    4.9801566811835604272b-1 - 1.5494982830181068513b-1 %i]

     `gamma' has mirror symmetry:

          (%i6) declare(z,complex)$
          (%i7) conjugate(gamma(z));
          (%o7)                  gamma(conjugate(z))

     Maxima expands `gamma(z+n)' and `gamma(z-n)', when `gamma_expand'
     is `true':

          (%i8) gamma_expand:true$

          (%i9) [gamma(z+1),gamma(z-1),gamma(z+2)/gamma(z+1)];
                                         gamma(z)
          (%o9)             [z gamma(z), --------, z + 1]
                                          z - 1

     The deriviative of `gamma':

          (%i10) diff(gamma(z),z);
          (%o10)                  psi (z) gamma(z)
                                     0

     See also `makegamma'.

     The Euler-Mascheroni constant is `%gamma'.


 -- Function: log_gamma (<z>)
     The natural logarithm of the gamma function.


 -- Function: gamma_greek (<a>, <z>)
     The lower incomplete gamma function (A&S 6.5.2):

                                   z
                                  /
                                  [  a - 1   - t
              gamma_greek(a, z) = I t      %e    dt
                                  ]
                                  /
                                   0

     See also `gamma_incomplete' (upper incomplete gamma function).


 -- Function: gamma_incomplete (<a>, <z>)
     The incomplete upper gamma function A&S 6.5.3:

                                        inf
                                       /
                                       [     a - 1   - t
              gamma_incomplete(a, z) = I    t      %e    dt
                                       ]
                                       /
                                        z

     See also `gamma_expand' for controlling how `gamma_incomplete' is
     expressed in terms of elementary functions and `erfc'.

     Also see the related functions `gamma_incomplete_regularized' and
     `gamma_incomplete_generalized'.


 -- Function: gamma_incomplete_regularized (<a>, <z>)
     The regularized incomplete upper gamma function A&S 6.5.1:

          gamma_incomplete_regularized(a, z) =
                                                  gamma_incomplete(a, z)
                                                  ----------------------
                                                         gamma(a)

     See also `gamma_expand' for controlling how `gamma_incomplete' is
     expressed in terms of elementary functions and `erfc'.

     Also see `gamma_incomplete'.


 -- Function: gamma_incomplete_generalized (<a>, <z1>, <z1>)
     The generalized incomplete gamma function.

          gamma_incomplete_generalized(a, z1, z2) =
                                                         z2
                                                        /
                                                        [    a - 1   - t
                                                        I   t      %e    dt
                                                        ]
                                                        /
                                                         z1

     Also see `gamma_incomplete' and `gamma_incomplete_regularized'.


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

     `gamma_expand' controls expansion of `gamma_incomplete'.  When
     `gamma_expand' is `true', `gamma_incomplete(v,z)' is expanded in
     terms of `z', `exp(z)', and `erfc(z)' when possible.

          (%i1) gamma_incomplete(2,z);
          (%o1)                       gamma_incomplete(2, z)
          (%i2) gamma_expand:true;
          (%o2)                                true
          (%i3) gamma_incomplete(2,z);
                                                     - z
          (%o3)                            (z + 1) %e
          (%i4) gamma_incomplete(3/2,z);
                                        - z   sqrt(%pi) erfc(sqrt(z))
          (%o4)               sqrt(z) %e    + -----------------------
                                                         2


 -- Option variable: gammalim
     Default value: 10000

     `gammalim' controls simplification of the gamma function for
     integral and rational number arguments.  If the absolute value of
     the argument is not greater than `gammalim', then simplification
     will occur.  Note that the `factlim' switch controls
     simplification of the result of `gamma' of an integer argument as
     well.


 -- Function: makegamma (<expr>)
     Transforms instances of binomial, factorial, and beta functions in
     <expr> into gamma functions.

     See also `makefact'.


 -- Function: beta (<a>, <b>)
     The beta function is defined as `gamma(a) gamma(b)/gamma(a+b)'
     (A&S 6.2.1).

     Maxima simplifies the beta function for positive integers and
     rational numbers, which sum to an integer. When
     `beta_args_sum_to_integer' is `true', Maxima simplifies also
     general expressions which sum to an integer.

     For <a> or <b> equal to zero the beta function is not defined.

     In general the beta function is not defined for negative integers
     as an argument. The exception is for <a=-n>, <n> a positive integer
     and <b> a positive integer with <b<=n>, it is possible to define an
     analytic continuation. Maxima gives for this case a result.

     When `beta_expand' is `true', expressions like `beta(a+n,b)' and
     `beta(a-n,b)' or `beta(a,b+n)' and `beta(a,b-n)' with `n' an
     integer are simplified.

     Maxima can evaluate the beta function for real and complex values
     in float and bigfloat precision. For numerical evaluation Maxima
     uses `log_gamma':

                     - log_gamma(b + a) + log_gamma(b) + log_gamma(a)
                   %e

     Maxima knows that the beta function is symmetric and has mirror
     symmetry.

     Maxima knows the derivatives of the beta function with respect to
     <a> or <b>.

     To express the beta function as a ratio of gamma functions see
     `makegamma'.

     Examples:

     Simplification, when one of the arguments is an integer:

          (%i1) [beta(2,3),beta(2,1/3),beta(2,a)];
                                         1   9      1
          (%o1)                         [--, -, ---------]
                                         12  4  a (a + 1)

     Simplification for two rational numbers as arguments which sum to
     an integer:

          (%i2) [beta(1/2,5/2),beta(1/3,2/3),beta(1/4,3/4)];
                                    3 %pi   2 %pi
          (%o2)                    [-----, -------, sqrt(2) %pi]
                                      8    sqrt(3)

     When setting `beta_args_sum_to_integer' to `true' more general
     expression are simplified, when the sum of the arguments is an
     integer:

          (%i3) beta_args_sum_to_integer:true$
          (%i4) beta(a+1,-a+2);
                                          %pi (a - 1) a
          (%o4)                         ------------------
                                        2 sin(%pi (2 - a))

     The possible results, when one of the arguments is a negative
     integer:

          (%i5) [beta(-3,1),beta(-3,2),beta(-3,3)];
                                              1  1    1
          (%o5)                            [- -, -, - -]
                                              3  6    3

     `beta(a+n,b)' or `beta(a-n)' with `n' an integer simplifies when
     `beta_expand' is `true':

          (%i6) beta_expand:true$
          (%i7) [beta(a+1,b),beta(a-1,b),beta(a+1,b)/beta(a,b+1)];
                              a beta(a, b)  beta(a, b) (b + a - 1)  a
          (%o7)              [------------, ----------------------, -]
                                 b + a              a - 1           b

     Beta is not defined, when one of the arguments is zero:

          (%i7) beta(0,b);
          beta: expected nonzero arguments; found 0, b
           -- an error.  To debug this try debugmode(true);

     Numercial evaluation for real and complex arguments in float or
     bigfloat precision:

          (%i8) beta(2.5,2.3);
          (%o8) .08694748611299981

          (%i9) beta(2.5,1.4+%i);
          (%o9) 0.0640144950796695 - .1502078053286415 %i

          (%i10) beta(2.5b0,2.3b0);
          (%o10) 8.694748611299969b-2

          (%i11) beta(2.5b0,1.4b0+%i);
          (%o11) 6.401449507966944b-2 - 1.502078053286415b-1 %i

     Beta is symmetric and has mirror symmetry:

          (%i14) beta(a,b)-beta(b,a);
          (%o14)                                 0
          (%i15) declare(a,complex,b,complex)$
          (%i16) conjugate(beta(a,b));
          (%o16)                 beta(conjugate(a), conjugate(b))

     The derivative of the beta function wrt `a':
          (%i17) diff(beta(a,b),a);
          (%o17)               - beta(a, b) (psi (b + a) - psi (a))
                                                0             0


 -- Function: beta_incomplete (<a>, <b>, <z>)
     The basic definition of the incomplete beta function (A&S 6.6.1) is

                  z
                 /
                 [         b - 1  a - 1
                 I  (1 - t)      t      dt
                 ]
                 /
                  0

     This definition is possible for realpart(a)>0 and realpart(b)>0
     and abs(z)<1. For other values the incomplete beta function can be
     defined through a generalized hypergeometric function:

             gamma(a) hypergeometric_generalized([a, 1 - b], [a + 1], z) z

     (See functions.wolfram.com for a complete definition of the
     incomplete beta function.)

     For negative integers a = -n and positive integers b=m with m<=n
     the incomplete beta function is defined through

                                      m - 1           k
                                      ====  (1 - m)  z
                                n - 1 \            k
                               z       >    -----------
                                      /     k! (n - k)
                                      ====
                                      k = 0

     Maxima uses this definition to simplify `beta_incomplete' for <a> a
     negative integer.

     For <a> a positive integer, `beta_incomplete' simplifies for any
     argument <b> and <z> and for <b> a positive integer for any
     argument <a> and <z>, with the exception of <a> a negative integer.

     For z=0 and realpart(a)>0, `beta_incomplete' has the specific
     value zero. For <z=1> and realpart(b)>0, `beta_incomplete'
     simplifies to the beta function `beta(a,b)'.

     Maxima evaluates `beta_incomplete' numerically for real and
     complex values in float or bigfloat precision. For the numerical
     evaluation an expansion of the incomplete beta function in
     continued fractions is used.

     When the option variable `beta_expand' is `true', Maxima expands
     expressions like `beta_incomplete(a+n,b,z)' and
     `beta_incomplete(a-n,b,z)' where n is a positive integer.

     Maxima knows the derivatives of `beta_incomplete' with respect to
     the variables <a>, <b> and <z> and the integral with respect to the
     variable <z>.

     Examples:

     Simplification for <a> a positive integer:

          (%i1) beta_incomplete(2,b,z);
                                                 b
                                      1 - (1 - z)  (b z + 1)
          (%o1)                       ----------------------
                                            b (b + 1)

     Simplification for <b> a positive integer:

          (%i2) beta_incomplete(a,2,z);
                                                         a
                                        (a (1 - z) + 1) z
          (%o2)                         ------------------
                                            a (a + 1)

     Simplification for <a> and <b> a positive integer:

          (%i3) beta_incomplete(3,2,z);
                                                         3
                                        (3 (1 - z) + 1) z
          (%o3)                         ------------------
                                                12

     <a> is a negative integer and b<=(-a), Maxima simplifies:

          (%i4) beta_incomplete(-3,1,z);
                                                 1
          (%o4)                              - ----
                                                  3
                                               3 z

     For the specific values z=0 and z=1, Maxima simplifies:

          (%i5) assume(a>0,b>0)$
          (%i6) beta_incomplete(a,b,0);
          (%o6)                                 0
          (%i7) beta_incomplete(a,b,1);
          (%o7)                            beta(a, b)

     Numerical evaluation in float or bigfloat precision:

          (%i8) beta_incomplete(0.25,0.50,0.9);
          (%o8)                          4.594959440269333
          (%i9)  fpprec:25$
          (%i10) beta_incomplete(0.25,0.50,0.9b0);
          (%o10)                    4.594959440269324086971203b0

     For abs(z)>1 `beta_incomplete' returns a complex result:

          (%i11) beta_incomplete(0.25,0.50,1.7);
          (%o11)              5.244115108584249 - 1.45518047787844 %i

     Results for more general complex arguments:

          (%i14) beta_incomplete(0.25+%i,1.0+%i,1.7+%i);
          (%o14)             2.726960675662536 - .3831175704269199 %i
          (%i15) beta_incomplete(1/2,5/4*%i,2.8+%i);
          (%o15)             13.04649635168716 %i - 5.802067956270001
          (%i16)

     Expansion, when `beta_expand' is `true':

          (%i23) beta_incomplete(a+1,b,z),beta_expand:true;
                                                                 b  a
                             a beta_incomplete(a, b, z)   (1 - z)  z
          (%o23)             -------------------------- - -----------
                                       b + a                 b + a

          (%i24) beta_incomplete(a-1,b,z),beta_expand:true;
                                                                     b  a - 1
                     beta_incomplete(a, b, z) (- b - a + 1)   (1 - z)  z
          (%o24)     -------------------------------------- - ---------------
                                     1 - a                         1 - a

     Derivative and integral for `beta_incomplete':

          (%i34) diff(beta_incomplete(a, b, z), z);
                                        b - 1  a - 1
          (%o34)                 (1 - z)      z
          (%i35) integrate(beta_incomplete(a, b, z), z);
                        b  a
                 (1 - z)  z
          (%o35) ----------- + beta_incomplete(a, b, z) z
                    b + a
                                                 a beta_incomplete(a, b, z)
                                               - --------------------------
                                                           b + a
          (%i36) factor(diff(%, z));
          (%o36)              beta_incomplete(a, b, z)


 -- Function: beta_incomplete_regularized (<a>, <b>, <z>)
     The regularized incomplete beta function A&S 6.6.2, defined as

          beta_incomplete_regularized(a, b, z) =
                                                beta_incomplete(a, b, z)
                                                ------------------------
                                                       beta(a, b)

     As for `beta_incomplete' this definition is not complete. See
     functions.wolfram.com for a complete definition of
     `beta_incomplete_regularized'.

     `beta_incomplete_regularized' simplifies <a> or <b> a positive
     integer.

     For z=0 and realpart(a)>0, `beta_incomplete_regularized' has the
     specific value 0. For <z=1> and realpart(b)>0,
     `beta_incomplete_regularized' simplifies to 1.

     Maxima can evaluate `beta_incomplete_regularized' for real and
     complex arguments in float and bigfloat precision.

     When `beta_expand' is `true', Maxima expands
     `beta_incomplete_regularized' for arguments a+n or a-n, where n is
     an integer.

     Maxima knows the derivatives of `beta_incomplete_regularized' with
     respect to the variables <a>, <b>, and <z> and the integral with
     respect to the variable <z>.

     Examples:

     Simplification for <a> or <b> a positive integer:

          (%i1) beta_incomplete_regularized(2,b,z);
                                                 b
          (%o1)                       1 - (1 - z)  (b z + 1)

          (%i2) beta_incomplete_regularized(a,2,z);
                                                         a
          (%o2)                         (a (1 - z) + 1) z

          (%i3) beta_incomplete_regularized(3,2,z);
                                                         3
          (%o3)                         (3 (1 - z) + 1) z

     For the specific values z=0 and z=1, Maxima simplifies:

          (%i4) assume(a>0,b>0)$
          (%i5) beta_incomplete_regularized(a,b,0);
          (%o5)                                 0
          (%i6) beta_incomplete_regularized(a,b,1);
          (%o6)                                 1

     Numerical evaluation for real and complex arguments in float and
     bigfloat precision:

          (%i7) beta_incomplete_regularized(0.12,0.43,0.9);
          (%o7)                         .9114011367359802
          (%i8) fpprec:32$
          (%i9) beta_incomplete_regularized(0.12,0.43,0.9b0);
          (%o9)               9.1140113673598075519946998779975b-1
          (%i10) beta_incomplete_regularized(1+%i,3/3,1.5*%i);
          (%o10)             .2865367499935403 %i - 0.122995963334684
          (%i11) fpprec:20$
          (%i12) beta_incomplete_regularized(1+%i,3/3,1.5b0*%i);
          (%o12)      2.8653674999354036142b-1 %i - 1.2299596333468400163b-1

     Expansion, when `beta_expand' is `true':

          (%i13) beta_incomplete_regularized(a+1,b,z);
                                                               b  a
                                                        (1 - z)  z
          (%o13) beta_incomplete_regularized(a, b, z) - ------------
                                                        a beta(a, b)
          (%i14) beta_incomplete_regularized(a-1,b,z);
          (%o14) beta_incomplete_regularized(a, b, z)
                                                               b  a - 1
                                                        (1 - z)  z
                                                   - ----------------------
                                                     beta(a, b) (b + a - 1)

     The derivative and the integral wrt <z>:

          (%i15) diff(beta_incomplete_regularized(a,b,z),z);
                                        b - 1  a - 1
                                 (1 - z)      z
          (%o15)                 -------------------
                                     beta(a, b)
          (%i16) integrate(beta_incomplete_regularized(a,b,z),z);
          (%o16) beta_incomplete_regularized(a, b, z) z
                                                                     b  a
                                                              (1 - z)  z
                    a (beta_incomplete_regularized(a, b, z) - ------------)
                                                              a beta(a, b)
                  - -------------------------------------------------------
                                             b + a


 -- Function: beta_incomplete_generalized (<a>, <b>, <z1>, <z2>)
     The basic definition of the generalized incomplete beta function is

                       z2
                     /
                     [          b - 1  a - 1
                     I   (1 - t)      t      dt
                     ]
                     /
                      z1

     Maxima simplifies `beta_incomplete_regularized' for <a> and <b> a
     positive integer.

     For realpart(a)>0 and z1=0 or z2=0, Maxima simplifies
     `beta_incomplete_generalized' to `beta_incomplete'. For
     realpart(b)>0 and z1=1 or <z2=1>, Maxima simplifies to an
     expression with `beta' and `beta_incomplete'.

     Maxima evaluates `beta_incomplete_regularized' for real and
     complex values in float and bigfloat precision.

     When `beta_expand' is `true', Maxima expands
     `beta_incomplete_generalized' for a+n and a-n, <n> a positive
     integer.

     Maxima knows the derivative of `beta_incomplete_generalized' with
     respect to the variables <a>, <b>, <z1>, and <z2> and the
     integrals with respect to the variables <z1> and <z2>.

     Examples:

     Maxima simplifies `beta_incomplete_generalized' for <a> and <b> a
     positive integer:

          (%i1) beta_incomplete_generalized(2,b,z1,z2);
                             b                      b
                     (1 - z1)  (b z1 + 1) - (1 - z2)  (b z2 + 1)
          (%o1)      -------------------------------------------
                                      b (b + 1)
          (%i2) beta_incomplete_generalized(a,2,z1,z2);
                                        a                      a
                     (a (1 - z2) + 1) z2  - (a (1 - z1) + 1) z1
          (%o2)      -------------------------------------------
                                      a (a + 1)
          (%i3) beta_incomplete_generalized(3,2,z1,z2);
                        2      2                       2      2
                (1 - z1)  (3 z1  + 2 z1 + 1) - (1 - z2)  (3 z2  + 2 z2 + 1)
          (%o3) -----------------------------------------------------------
                                            12

     Simplification for specific values z1=0, z2=0, z1=1, or z2=1:

          (%i4) assume(a > 0, b > 0)$
          (%i5) beta_incomplete_generalized(a,b,z1,0);
          (%o5)                    - beta_incomplete(a, b, z1)

          (%i6) beta_incomplete_generalized(a,b,0,z2);
          (%o6)                    - beta_incomplete(a, b, z2)

          (%i7) beta_incomplete_generalized(a,b,z1,1);
          (%o7)              beta(a, b) - beta_incomplete(a, b, z1)

          (%i8) beta_incomplete_generalized(a,b,1,z2);
          (%o8)              beta_incomplete(a, b, z2) - beta(a, b)

     Numerical evaluation for real arguments in float or bigfloat
     precision:

          (%i9) beta_incomplete_generalized(1/2,3/2,0.25,0.31);
          (%o9)                        .09638178086368676

          (%i10) fpprec:32$
          (%i10) beta_incomplete_generalized(1/2,3/2,0.25,0.31b0);
          (%o10)               9.6381780863686935309170054689964b-2

     Numerical evaluation for complex arguments in float or bigfloat
     precision:

          (%i11) beta_incomplete_generalized(1/2+%i,3/2+%i,0.25,0.31);
          (%o11)           - .09625463003205376 %i - .003323847735353769
          (%i12) fpprec:20$
          (%i13) beta_incomplete_generalized(1/2+%i,3/2+%i,0.25,0.31b0);
          (%o13)     - 9.6254630032054178691b-2 %i - 3.3238477353543591914b-3

     Expansion for a+n or a-n, <n> a positive integer, when
     `beta_expand' is `true':

          (%i14) beta_expand:true$

          (%i15) beta_incomplete_generalized(a+1,b,z1,z2);

                         b   a           b   a
                 (1 - z1)  z1  - (1 - z2)  z2
          (%o15) -----------------------------
                             b + a
                                a beta_incomplete_generalized(a, b, z1, z2)
                              + -------------------------------------------
                                                   b + a
          (%i16) beta_incomplete_generalized(a-1,b,z1,z2);

                 beta_incomplete_generalized(a, b, z1, z2) (- b - a + 1)
          (%o16) -------------------------------------------------------
                                          1 - a
                                              b   a - 1           b   a - 1
                                      (1 - z2)  z2      - (1 - z1)  z1
                                    - -------------------------------------
                                                      1 - a

     Derivative wrt the variable <z1> and integrals wrt <z1> and <z2>:

          (%i17) diff(beta_incomplete_generalized(a,b,z1,z2),z1);
                                         b - 1   a - 1
          (%o17)               - (1 - z1)      z1
          (%i18) integrate(beta_incomplete_generalized(a,b,z1,z2),z1);
          (%o18) beta_incomplete_generalized(a, b, z1, z2) z1
                                            + beta_incomplete(a + 1, b, z1)
          (%i19) integrate(beta_incomplete_generalized(a,b,z1,z2),z2);
          (%o19) beta_incomplete_generalized(a, b, z1, z2) z2
                                            - beta_incomplete(a + 1, b, z2)


 -- Option variable: beta_expand
     Default value: false

     When `beta_expand' is `true', `beta(a,b)' and related functions
     are expanded for arguments like a+n or a-n, where n is an integer.


 -- Option variable: beta_args_sum_to_integer
     Default value: false

     When `beta_args_sum_to_integer' is `true', Maxima simplifies
     `beta(a,b)', when the arguments <a> and <b> sum to an integer.


 -- Function: psi [<n>](<x>)
     The derivative of `log (gamma (<x>))' of order `<n>+1'.  Thus,
     `psi[0](<x>)' is the first derivative, `psi[1](<x>)' is the second
     derivative, etc.

     Maxima does not know how, in general, to compute a numerical value
     of `psi', but it can compute some exact values for rational args.
     Several variables control what range of rational args `psi' will
     return an exact value, if possible.  See `maxpsiposint',
     `maxpsinegint', `maxpsifracnum', and `maxpsifracdenom'.  That is,
     <x> must lie between `maxpsinegint' and `maxpsiposint'.  If the
     absolute value of the fractional part of <x> is rational and has a
     numerator less than `maxpsifracnum' and has a denominator less
     than `maxpsifracdenom', `psi' will return an exact value.

     The function `bfpsi' in the `bffac' package can compute numerical
     values.


 -- Option variable: maxpsiposint
     Default value: 20

     `maxpsiposint' is the largest positive value for which `psi[n](x)'
     will try to compute an exact value.


 -- Option variable: maxpsinegint
     Default value: -10

     `maxpsinegint' is the most negative value for which `psi[n](x)'
     will try to compute an exact value.  That is if <x> is less than
     `maxnegint', `psi[n](<x>)' will not return simplified answer, even
     if it could.


 -- Option variable: maxpsifracnum
     Default value: 6

     Let <x> be a rational number less than one of the form `p/q'.  If
     `p' is greater than `maxpsifracnum', then `psi[<n>](<x>)' will not
     try to return a simplified value.


 -- Option variable: maxpsifracdenom
     Default value: 6

     Let <x> be a rational number less than one of the form `p/q'.  If
     `q' is greater than `maxpsifracdenom', then `psi[<n>](<x>)' will
     not try to return a simplified value.


 -- Function: makefact (<expr>)
     Transforms instances of binomial, gamma, and beta functions in
     <expr> into factorials.

     See also `makegamma'.


 -- Function: numfactor (<expr>)
     Returns the numerical factor multiplying the expression <expr>,
     which should be a single term.

     `content' returns the greatest common divisor (gcd) of all terms
     in a sum.

          (%i1) gamma (7/2);
                                    15 sqrt(%pi)
          (%o1)                     ------------
                                         8
          (%i2) numfactor (%);
                                         15
          (%o2)                          --
                                         8



File: maxima.info,  Node: Exponential Integrals,  Next: Error Function,  Prev: Gamma and factorial Functions,  Up: Special Functions

15.5 Exponential Integrals
==========================

The Exponential Integral and related funtions are defined in Abramowitz
and Stegun, Handbook of Mathematical Functions, Chapter 5

 -- Function: expintegral_e1 (<z>)
     The Exponential Integral E1(z) (A&S 5.1.1)


 -- Function: expintegral_ei (<z>)
     The Exponential Integral Ei(z) (A&S 5.1.2)


 -- Function: expintegral_li (<z>)
     The Exponential Integral Li(z)  (A&S 5.1.3)


 -- Function: expintegral_e (<n>,<z>)
     The Exponential Integral En(z)  (A&S 5.1.4)


 -- Function: expintegral_si (<z>)
     The Exponential Integral Si(z) (A&S 5.2.1)


 -- Function: expintegral_ci (<z>)
     The Exponential Integral Ci(z) (A&S 5.2.2)


 -- Function: expintegral_shi (<z>)
     The Exponential Integral Shi(z) (A&S 5.2.3)


 -- Function: expintegral_chi (<z>)
     The Exponential Integral Chi(z) (A&S 5.2.4)


 -- Option variable: expintrep
     Default value: false

     Change the representation of the Exponential Integral to
     gamma_incomplete, expintegral_e1, expintegral_ei,
     expintegral_li, expintegral_trig, expintegral_hyp


 -- Option variable: expintexpand
     Default value: false

     Expand the Exponential Integral E[n](z) for half integral values
     in terms of Erfc or Erf and for positive integers in terms of Ei



File: maxima.info,  Node: Error Function,  Next: Struve Functions,  Prev: Exponential Integrals,  Up: Special Functions

15.6 Error Function
===================

The Error function and related funtions are defined in Abramowitz and
Stegun, Handbook of Mathematical Functions, Chapter 7

 -- Function: erf (<z>)
     The Error Function erf(z) (A&S 7.1.1)

     See also flag `erfflag'.


 -- Function: erfc (<z>)
     The Complementary Error Function erfc(z) (A&S 7.1.2)

     `erfc(z) = 1-erf(z)'


 -- Function: erfi (<z>)
     The Imaginary Error Function.

     `erfi(z) = -%i*erf(%i*z)'


 -- Function: erf_generalized (<z1>,<z2>)
     Generalized Error function Erf(z1,z2)


 -- Function: fresnel_c (<z>)
     The Fresnel Integral C(z) = integrate(cos((%pi/2)*t^2),t,0,z).
     (A&S 7.3.1)

     The simplification fresnel_c(-x) = -fresnel_c(x) is applied when
     flag `trigsign' is true.

     The simplification fresnel_c(%i*x) =  %i*fresnel_c(x) is applied
     when flag `%iargs' is true.

     See flags `erf_representation' and `hypergeometric_representation'.


 -- Function: fresnel_s (<z>)
     The Fresnel Integral S(z) = integrate(sin((%pi/2)*t^2),t,0,z).
     (A&S 7.3.2)

     The simplification fresnel_s(-x) = -fresnel_s(x) is applied when
     flag `trigsign' is true.

     The simplification fresnel_s(%i*x) =  -%i*fresnel_s(x) is applied
     when flag `%iargs' is true.

     See flags `erf_representation' and `hypergeometric_representation'.


 -- Option variable: erf_representation
     Default value: false

     When T erfc, erfi, erf_generalized, fresnel_s and fresnel_c are
     transformed to erf.

 -- Option variable: hypergeometric_representation
     Default value: false

     Enables transformation to a Hypergeometric representation for
     fresnel_s and fresnel_c


File: maxima.info,  Node: Struve Functions,  Next: Hypergeometric Functions,  Prev: Error Function,  Up: Special Functions

15.7 Struve Functions
=====================

The Struve functions are defined in Abramowitz and Stegun, Handbook of
Mathematical Functions, Chapter 12.

 -- Function: struve_h (<v>, <z>)
     The Struve Function H of order v and argument z. (A&S 12.1.1)


 -- Function: struve_l (<v>, <z>)
     The Modified Struve Function L of order v and argument z. (A&S
     12.2.1)



File: maxima.info,  Node: Hypergeometric Functions,  Next: Parabolic Cylinder Functions,  Prev: Struve Functions,  Up: Special Functions

15.8 Hypergeometric Functions
=============================

The Hypergeometric Functions are defined in Abramowitz and Stegun,
Handbook of Mathematical Functions, Chapters 13 and 15.

   Maxima has very limited knowledge of these functions.  They can be
returned from function `hgfred'.

 -- Function: %m [<k>,<u>] (<z>)
     Whittaker M function `M[k,u](z) =
     exp(-z/2)*z^(1/2+u)*M(1/2+u-k,1+2*u,z)'.  (A&S 13.1.32)


 -- Function: %w [<k>,<u>] (<z>)
     Whittaker W function.  (A&S 13.1.33)


 -- Function: %f [<p>,<q>] (<[a],[b],z>)
     The pFq(a1,a2,..ap;b1,b2,..bq;z) hypergeometric function, where
     `a' a list of length `p' and `b' a list of length `q'.


 -- Function: hypergeometric ([<a1>, ..., <ap>],[<b1>, ... ,<bq>], x)
     The hypergeometric function. Unlike Maxima's `%f' hypergeometric
     function, the function `hypergeometric' is a simplifying function;
     also, `hypergeometric' supports complex double and big floating
     point evaluation. For the Gauss hypergeometric function, that is p
     = 2 and q = 1, floating point evaluation outside the unit circle
     is supported, but in general, it is not supported.

     When the option variable `expand_hypergeometric' is true (default
     is false) and one of the arguments `a1' through `ap' is a negative
     integer (a polynomial case), `hypergeometric' returns an expanded
     polynomial.

     Examples:

          (%i1)  hypergeometric([],[],x);
          (%o1) %e^x

     Polynomial cases automatically expand when `expand_hypergeometric'
     is true:

          (%i2) hypergeometric([-3],[7],x);
          (%o2) hypergeometric([-3],[7],x)

          (%i3) hypergeometric([-3],[7],x), expand_hypergeometric : true;
          (%o3) -x^3/504+3*x^2/56-3*x/7+1

     Both double float and big float evaluation is supported:

          (%i4) hypergeometric([5.1],[7.1 + %i],0.42);
          (%o4)       1.346250786375334 - 0.0559061414208204 %i
          (%i5) hypergeometric([5,6],[8], 5.7 - %i);
          (%o5)     .007375824009774946 - .001049813688578674 %i
          (%i6) hypergeometric([5,6],[8], 5.7b0 - %i), fpprec : 30;
          (%o6) 7.37582400977494674506442010824b-3
                                    - 1.04981368857867315858055393376b-3 %i


File: maxima.info,  Node: Parabolic Cylinder Functions,  Next: Functions and Variables for Special Functions,  Prev: Hypergeometric Functions,  Up: Special Functions

15.9 Parabolic Cylinder Functions
=================================

The Parabolic Cylinder Functions are defined in Abramowitz and Stegun,
Handbook of Mathematical Functions, Chapter 19.

   Maxima has very limited knowledge of these functions.  They can be
returned from function `hgfred'.

 -- Function: parabolic_cylinder_d (<v>, <z>)
     The parabolic cylinder function `parabolic_cylinder_d(v,z)'. (A&S
     19.3.1)



File: maxima.info,  Node: Functions and Variables for Special Functions,  Prev: Parabolic Cylinder Functions,  Up: Special Functions

15.10 Functions and Variables for Special Functions
===================================================

 -- Function: specint (exp(- s*<t>) * <expr>, <t>)
     Compute the Laplace transform of <expr> with respect to the
     variable <t>.  The integrand <expr> may contain special functions.

     The following special functions are handled by `specint':
     incomplete gamma function, error functions (but not the error
     function `erfi', it is easy to transform `erfi' e.g. to the error
     function `erf'), exponential integrals, bessel functions
     (including products of bessel functions), hankel functions,
     hermite and the laguerre polynomials.

     Furthermore, `specint' can handle the hypergeometric function
     `%f[p,q]([],[],z)', the whittaker function of the first kind
     `%m[u,k](z)' and of the second kind `%w[u,k](z)'.

     The result may be in terms of special functions and can include
     unsimplified hypergeometric functions.

     When `laplace' fails to find a Laplace transform, `specint' is
     called.  Because `laplace' knows more general rules for Laplace
     transforms, it is preferable to use `laplace' and not `specint'.

     `demo(hypgeo)' displays several examples of Laplace transforms
     computed by `specint'.

     Examples:
          (%i1) assume (p > 0, a > 0)$
          (%i2) specint (t^(1/2) * exp(-a*t/4) * exp(-p*t), t);
                                     sqrt(%pi)
          (%o2)                     ------------
                                           a 3/2
                                    2 (p + -)
                                           4
          (%i3) specint (t^(1/2) * bessel_j(1, 2 * a^(1/2) * t^(1/2))
                        * exp(-p*t), t);
                                             - a/p
                                   sqrt(a) %e
          (%o3)                    ---------------
                                          2
                                         p

     Examples for exponential integrals:

          (%i4) assume(s>0,a>0,s-a>0)$
          (%i5) ratsimp(specint(%e^(a*t)
                                *(log(a)+expintegral_e1(a*t))*%e^(-s*t),t));
                                       log(s)
          (%o5)                        ------
                                       s - a
          (%i6) logarc:true$

          (%i7) gamma_expand:true$

          radcan(specint((cos(t)*expintegral_si(t)
                               -sin(t)*expintegral_ci(t))*%e^(-s*t),t));
                                       log(s)
          (%o8)                        ------
                                        2
                                       s  + 1
          ratsimp(specint((2*t*log(a)+2/a*sin(a*t)
                                -2*t*expintegral_ci(a*t))*%e^(-s*t),t));
                                         2    2
                                    log(s  + a )
          (%o9)                     ------------
                                          2
                                         s

     Results when using the expansion of `gamma_incomplete' and when
     changing the representation to `expintegral_e1':

          (%i10) assume(s>0)$
          (%i11) specint(1/sqrt(%pi*t)*unit_step(t-k)*%e^(-s*t),t);
                                                      1
                                      gamma_incomplete(-, k s)
                                                      2
          (%o11)                      ------------------------
                                         sqrt(%pi) sqrt(s)

          (%i12) gamma_expand:true$
          (%i13) specint(1/sqrt(%pi*t)*unit_step(t-k)*%e^(-s*t),t);
                                        erfc(sqrt(k) sqrt(s))
          (%o13)                        ---------------------
                                               sqrt(s)

          (%i14) expintrep:expintegral_e1$
          (%i15) ratsimp(specint(1/(t+a)^2*%e^(-s*t),t));
                                        a s
                                  a s %e    expintegral_e1(a s) - 1
          (%o15)                - ---------------------------------
                                                  a


 -- Function: hgfred (<a>, <b>, <t>)
     Simplify the generalized hypergeometric function in terms of other,
     simpler, forms.  <a> is a list of numerator parameters and <b> is
     a list of the denominator parameters.

     If `hgfred' cannot simplify the hypergeometric function, it returns
     an expression of the form `%f[p,q]([a], [b], x)' where <p> is the
     number of elements in <a>, and <q> is the number of elements in
     <b>.  This is the usual `pFq' generalized hypergeometric function.

          (%i1) assume(not(equal(z,0)));
          (%o1)                          [notequal(z, 0)]
          (%i2) hgfred([v+1/2],[2*v+1],2*%i*z);

                               v/2                               %i z
                              4    bessel_j(v, z) gamma(v + 1) %e
          (%o2)               ---------------------------------------
                                                 v
                                                z
          (%i3) hgfred([1,1],[2],z);

                                             log(1 - z)
          (%o3)                            - ----------
                                                 z
          (%i4) hgfred([a,a+1/2],[3/2],z^2);

                                         1 - 2 a          1 - 2 a
                                  (z + 1)        - (1 - z)
          (%o4)                   -------------------------------
                                           2 (1 - 2 a) z

     It can be beneficial to load orthopoly too as the following example
     shows.  Note that <L> is the generalized Laguerre polynomial.

          (%i5) load(orthopoly)$
          (%i6) hgfred([-2],[a],z);

                                              (a - 1)
                                           2 L       (z)
                                              2
          (%o6)                            -------------
                                             a (a + 1)
          (%i7) ev(%);

                                            2
                                           z        2 z
          (%o7)                         --------- - --- + 1
                                        a (a + 1)    a

 -- Function: lambert_w (<z>)
     The principal branch of Lambert's W function W(z), the solution of
     `z = W(z) * exp(W(z))'.  (DLMF 4.13)


 -- Function: generalized_lambert_w (<k>, <z>)
     The <k>-th branch of Lambert's W function W(z), the solution of `z
     = W(z) * exp(W(z))'. (DLMF 4.13)

     The principal branch, denoted Wp(z) in DLMF, is `lambert_w(z) =
     generalized_lambert_w(0,z)'.

     The other branch with real values, denoted Wm(z) in DLMF, is
     `generalized_lambert_w(-1,z)'.


 -- Function: nzeta (<z>)
     The Plasma Dispersion Function `nzeta(z) =
     %i*sqrt(%pi)*exp(-z^2)*(1-erf(-%i*z))'


 -- Function: nzetar (<z>)
     Returns `realpart(nzeta(z))'.


 -- Function: nzetai (<z>)
     Returns `imagpart(nzeta(z))'.



File: maxima.info,  Node: Elliptic Functions,  Next: Limits,  Prev: Special Functions,  Up: Top

16 Elliptic Functions
*********************

* Menu:

* Introduction to Elliptic Functions and Integrals::
* Functions and Variables for Elliptic Functions::
* Functions and Variables for Elliptic Integrals::


File: maxima.info,  Node: Introduction to Elliptic Functions and Integrals,  Next: Functions and Variables for Elliptic Functions,  Up: Top

16.1 Introduction to Elliptic Functions and Integrals
=====================================================

Maxima includes support for Jacobian elliptic functions and for
complete and incomplete elliptic integrals.  This includes symbolic
manipulation of these functions and numerical evaluation as well.
Definitions of these functions and many of their properties can by
found in Abramowitz and Stegun, Chapter 16-17.  As much as possible, we
use the definitions and relationships given there.

   In particular, all elliptic functions and integrals use the parameter
m instead of the modulus k or the modular angle \alpha.  This is one
area where we differ from Abramowitz and Stegun who use the modular
angle for the elliptic functions.  The following relationships are true:
m = k^2 and k = \sin(\alpha)

   The elliptic functions and integrals are primarily intended to
support symbolic computation.  Therefore, most of derivatives of the
functions and integrals are known.  However, if floating-point values
are given, a floating-point result is returned.

   Support for most of the other properties of elliptic functions and
integrals other than derivatives has not yet been written.

   Some examples of elliptic functions:
     (%i1) jacobi_sn (u, m);
     (%o1)                    jacobi_sn(u, m)
     (%i2) jacobi_sn (u, 1);
     (%o2)                        tanh(u)
     (%i3) jacobi_sn (u, 0);
     (%o3)                        sin(u)
     (%i4) diff (jacobi_sn (u, m), u);
     (%o4)            jacobi_cn(u, m) jacobi_dn(u, m)
     (%i5) diff (jacobi_sn (u, m), m);
     (%o5) jacobi_cn(u, m) jacobi_dn(u, m)

           elliptic_e(asin(jacobi_sn(u, m)), m)
      (u - ------------------------------------)/(2 m)
                          1 - m

                 2
        jacobi_cn (u, m) jacobi_sn(u, m)
      + --------------------------------
                   2 (1 - m)

   Some examples of elliptic integrals:
     (%i1) elliptic_f (phi, m);
     (%o1)                  elliptic_f(phi, m)
     (%i2) elliptic_f (phi, 0);
     (%o2)                          phi
     (%i3) elliptic_f (phi, 1);
                                    phi   %pi
     (%o3)                  log(tan(--- + ---))
                                     2     4
     (%i4) elliptic_e (phi, 1);
     (%o4)                       sin(phi)
     (%i5) elliptic_e (phi, 0);
     (%o5)                          phi
     (%i6) elliptic_kc (1/2);
                                          1
     (%o6)                    elliptic_kc(-)
                                          2
     (%i7) makegamma (%);
                                      2 1
                                 gamma (-)
                                        4
     (%o7)                      -----------
                                4 sqrt(%pi)
     (%i8) diff (elliptic_f (phi, m), phi);
                                     1
     (%o8)                 ---------------------
                                         2
                           sqrt(1 - m sin (phi))
     (%i9) diff (elliptic_f (phi, m), m);
            elliptic_e(phi, m) - (1 - m) elliptic_f(phi, m)
     (%o9) (-----------------------------------------------
                                   m

                                      cos(phi) sin(phi)
                                  - ---------------------)/(2 (1 - m))
                                                  2
                                    sqrt(1 - m sin (phi))

   Support for elliptic functions and integrals was written by Raymond
Toy.  It is placed under the terms of the General Public License (GPL)
that governs the distribution of Maxima.


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

16.2 Functions and Variables for Elliptic Functions
===================================================

 -- Function: jacobi_sn (<u>, <m>)
     The Jacobian elliptic function sn(u,m).


 -- Function: jacobi_cn (<u>, <m>)
     The Jacobian elliptic function cn(u,m).


 -- Function: jacobi_dn (<u>, <m>)
     The Jacobian elliptic function dn(u,m).


 -- Function: jacobi_ns (<u>, <m>)
     The Jacobian elliptic function ns(u,m) = 1/sn(u,m).


 -- Function: jacobi_sc (<u>, <m>)
     The Jacobian elliptic function sc(u,m) = sn(u,m)/cn(u,m).


 -- Function: jacobi_sd (<u>, <m>)
     The Jacobian elliptic function sd(u,m) = sn(u,m)/dn(u,m).


 -- Function: jacobi_nc (<u>, <m>)
     The Jacobian elliptic function nc(u,m) = 1/cn(u,m).


 -- Function: jacobi_cs (<u>, <m>)
     The Jacobian elliptic function cs(u,m) = cn(u,m)/sn(u,m).


 -- Function: jacobi_cd (<u>, <m>)
     The Jacobian elliptic function cd(u,m) = cn(u,m)/dn(u,m).


 -- Function: jacobi_nd (<u>, <m>)
     The Jacobian elliptic function nc(u,m) = 1/cn(u,m).


 -- Function: jacobi_ds (<u>, <m>)
     The Jacobian elliptic function ds(u,m) = dn(u,m)/sn(u,m).


 -- Function: jacobi_dc (<u>, <m>)
     The Jacobian elliptic function dc(u,m) = dn(u,m)/cn(u,m).


 -- Function: inverse_jacobi_sn (<u>, <m>)
     The inverse of the Jacobian elliptic function sn(u,m).


 -- Function: inverse_jacobi_cn (<u>, <m>)
     The inverse of the Jacobian elliptic function cn(u,m).


 -- Function: inverse_jacobi_dn (<u>, <m>)
     The inverse of the Jacobian elliptic function dn(u,m).


 -- Function: inverse_jacobi_ns (<u>, <m>)
     The inverse of the Jacobian elliptic function ns(u,m).


 -- Function: inverse_jacobi_sc (<u>, <m>)
     The inverse of the Jacobian elliptic function sc(u,m).


 -- Function: inverse_jacobi_sd (<u>, <m>)
     The inverse of the Jacobian elliptic function sd(u,m).


 -- Function: inverse_jacobi_nc (<u>, <m>)
     The inverse of the Jacobian elliptic function nc(u,m).


 -- Function: inverse_jacobi_cs (<u>, <m>)
     The inverse of the Jacobian elliptic function cs(u,m).


 -- Function: inverse_jacobi_cd (<u>, <m>)
     The inverse of the Jacobian elliptic function cd(u,m).


 -- Function: inverse_jacobi_nd (<u>, <m>)
     The inverse of the Jacobian elliptic function nc(u,m).


 -- Function: inverse_jacobi_ds (<u>, <m>)
     The inverse of the Jacobian elliptic function ds(u,m).


 -- Function: inverse_jacobi_dc (<u>, <m>)
     The inverse of the Jacobian elliptic function dc(u,m).



File: maxima.info,  Node: Functions and Variables for Elliptic Integrals,  Prev: Functions and Variables for Elliptic Functions,  Up: Top

16.3 Functions and Variables for Elliptic Integrals
===================================================

 -- Function: elliptic_f (<phi>, <m>)
     The incomplete elliptic integral of the first kind, defined as

     integrate(1/sqrt(1 - m*sin(x)^2), x, 0, phi)

     See also *note elliptic_e:: and *note elliptic_kc::.


 -- Function: elliptic_e (<phi>, <m>)
     The incomplete elliptic integral of the second kind, defined as

     elliptic_e(phi, m) = integrate(sqrt(1 - m*sin(x)^2), x, 0, phi)

     See also *note elliptic_e:: and *note elliptic_ec::.


 -- Function: elliptic_eu (<u>, <m>)
     The incomplete elliptic integral of the second kind, defined as

     integrate(dn(v,m)^2,v,0,u) = integrate(sqrt(1-m*t^2)/sqrt(1-t^2),
     t, 0, tau)

     where tau = sn(u,m).

     This is related to elliptic_e by

     elliptic_eu(u, m) = elliptic_e(asin(sn(u,m)),m)

     See also *note elliptic_e::.


 -- Function: elliptic_pi (<n>, <phi>, <m>)
     The incomplete elliptic integral of the third kind, defined as

     integrate(1/(1-n*sin(x)^2)/sqrt(1 - m*sin(x)^2), x, 0, phi)

     Only the derivative with respect to phi is known by Maxima.


 -- Function: elliptic_kc (<m>)
     The complete elliptic integral of the first kind, defined as

     integrate(1/sqrt(1 - m*sin(x)^2), x, 0, %pi/2)

     For certain values of m, the value of the integral is known in
     terms of Gamma functions.  Use `makegamma' to evaluate them.


 -- Function: elliptic_ec (<m>)
     The complete elliptic integral of the second kind, defined as

     integrate(sqrt(1 - m*sin(x)^2), x, 0, %pi/2)

     For certain values of m, the value of the integral is known in
     terms of Gamma functions.  Use `makegamma' to evaluate them.



File: maxima.info,  Node: Limits,  Next: Differentiation,  Prev: Elliptic Functions,  Up: Top

17 Limits
*********

* Menu:

* Functions and Variables for Limits::


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

17.1 Functions and Variables for Limits
=======================================

 -- Option variable: lhospitallim
     Default value: 4

     `lhospitallim' is the maximum number of times L'Hospital's rule is
     used in `limit'.  This prevents infinite looping in cases like
     `limit (cot(x)/csc(x), x, 0)'.


 -- Function: limit (<expr>, <x>, <val>, <dir>)
 -- Function: limit (<expr>, <x>, <val>)
 -- Function: limit (<expr>)
     Computes the limit of <expr> as the real variable <x> approaches
     the value <val> from the direction <dir>.  <dir> may have the value
     `plus' for a limit from above, `minus' for a limit from below, or
     may be omitted (implying a two-sided limit is to be computed).

     `limit' uses the following special symbols: `inf' (positive
     infinity) and `minf' (negative infinity).  On output it may also
     use `und' (undefined), `ind' (indefinite but bounded) and
     `infinity' (complex infinity).

     `infinity' (complex infinity) is returned when the limit of the
     absolute value of the expression is positive infinity, but the
     limit of the expression itself is not positive infinity or
     negative infinity.  This includes cases where the limit of the
     complex argument is a constant, as in `limit(log(x), x, minf)',
     cases where the complex argument oscillates, as in `limit((-2)^x,
     x, inf)', and cases where the complex argument is different for
     either side of a two-sided limit, as in `limit(1/x, x, 0)' and
     `limit(log(x), x, 0)'.

     `lhospitallim' is the maximum number of times L'Hospital's rule is
     used in `limit'.  This prevents infinite looping in cases like
     `limit (cot(x)/csc(x), x, 0)'.

     `tlimswitch' when true will allow the `limit' command to use
     Taylor series expansion when necessary.

     `limsubst' prevents `limit' from attempting substitutions on
     unknown forms.  This is to avoid bugs like `limit (f(n)/f(n+1), n,
     inf)' giving 1.  Setting `limsubst' to `true' will allow such
     substitutions.

     `limit' with one argument is often called upon to simplify constant
     expressions, for example, `limit (inf-1)'.

     `example (limit)' displays some examples.

     For the method see Wang, P., "Evaluation of Definite Integrals by
     Symbolic Manipulation", Ph.D. thesis, MAC TR-92, October 1971.


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

     prevents `limit' from attempting substitutions on unknown forms.
     This is to avoid bugs like `limit (f(n)/f(n+1), n, inf)' giving 1.
     Setting `limsubst' to `true' will allow such substitutions.


 -- Function: tlimit (<expr>, <x>, <val>, <dir>)
 -- Function: tlimit (<expr>, <x>, <val>)
 -- Function: tlimit (<expr>)
     Take the limit of the Taylor series expansion of `expr' in `x' at
     `val' from direction `dir'.


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

     When `tlimswitch' is `true', the `limit' command will use a Taylor
     series expansion if the limit of the input expression cannot be
     computed directly.  This allows evaluation of limits such as
     `limit(x/(x-1)-1/log(x),x,1,plus)'.  When `tlimswitch' is `false'
     and the limit of input expression cannot be computed directly,
     `limit' will return an unevaluated limit expression.



File: maxima.info,  Node: Differentiation,  Next: Integration,  Prev: Limits,  Up: Top

18 Differentiation
******************

* Menu:

* Functions and Variables for Differentiation::


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

18.1 Functions and Variables for Differentiation
================================================

 -- Function: antid (<expr>, <x>, <u(x)>)
     Returns a two-element list, such that an antiderivative of <expr>
     with respect to <x> can be constructed from the list.  The
     expression <expr> may contain an unknown function <u> and its
     derivatives.

     Let <L>, a list of two elements, be the return value of `antid'.
     Then `<L>[1] + 'integrate (<L>[2], <x>)' is an antiderivative of
     <expr> with respect to <x>.

     When `antid' succeeds entirely, the second element of the return
     value is zero.  Otherwise, the second element is nonzero, and the
     first element is nonzero or zero.  If `antid' cannot make any
     progress, the first element is zero and the second nonzero.

     `load ("antid")' loads this function.  The `antid' package also
     defines the functions `nonzeroandfreeof' and `linear'.

     `antid' is related to `antidiff' as follows.  Let <L>, a list of
     two elements, be the return value of `antid'.  Then the return
     value of `antidiff' is equal to `<L>[1] + 'integrate (<L>[2],
     <x>)' where <x> is the variable of integration.

     Examples:

          (%i1) load ("antid")$
          (%i2) expr: exp (z(x)) * diff (z(x), x) * y(x);
                                      z(x)  d
          (%o2)                y(x) %e     (-- (z(x)))
                                            dx
          (%i3) a1: antid (expr, x, z(x));
                                 z(x)      z(x)  d
          (%o3)          [y(x) %e    , - %e     (-- (y(x)))]
                                                 dx
          (%i4) a2: antidiff (expr, x, z(x));
                                      /
                               z(x)   [   z(x)  d
          (%o4)         y(x) %e     - I %e     (-- (y(x))) dx
                                      ]         dx
                                      /
          (%i5) a2 - (first (a1) + 'integrate (second (a1), x));
          (%o5)                           0
          (%i6) antid (expr, x, y(x));
                                       z(x)  d
          (%o6)             [0, y(x) %e     (-- (z(x)))]
                                             dx
          (%i7) antidiff (expr, x, y(x));
                            /
                            [        z(x)  d
          (%o7)             I y(x) %e     (-- (z(x))) dx
                            ]              dx
                            /


 -- Function: antidiff (<expr>, <x>, <u>(<x>))
     Returns an antiderivative of <expr> with respect to <x>.  The
     expression <expr> may contain an unknown function <u> and its
     derivatives.

     When `antidiff' succeeds entirely, the resulting expression is
     free of integral signs (that is, free of the `integrate' noun).
     Otherwise, `antidiff' returns an expression which is partly or
     entirely within an integral sign.  If `antidiff' cannot make any
     progress, the return value is entirely within an integral sign.

     `load ("antid")' loads this function.  The `antid' package also
     defines the functions `nonzeroandfreeof' and `linear'.

     `antidiff' is related to `antid' as follows.  Let <L>, a list of
     two elements, be the return value of `antid'.  Then the return
     value of `antidiff' is equal to `<L>[1] + 'integrate (<L>[2],
     <x>)' where <x> is the variable of integration.

     Examples:

          (%i1) load ("antid")$
          (%i2) expr: exp (z(x)) * diff (z(x), x) * y(x);
                                      z(x)  d
          (%o2)                y(x) %e     (-- (z(x)))
                                            dx
          (%i3) a1: antid (expr, x, z(x));
                                 z(x)      z(x)  d
          (%o3)          [y(x) %e    , - %e     (-- (y(x)))]
                                                 dx
          (%i4) a2: antidiff (expr, x, z(x));
                                      /
                               z(x)   [   z(x)  d
          (%o4)         y(x) %e     - I %e     (-- (y(x))) dx
                                      ]         dx
                                      /
          (%i5) a2 - (first (a1) + 'integrate (second (a1), x));
          (%o5)                           0
          (%i6) antid (expr, x, y(x));
                                       z(x)  d
          (%o6)             [0, y(x) %e     (-- (z(x)))]
                                             dx
          (%i7) antidiff (expr, x, y(x));
                            /
                            [        z(x)  d
          (%o7)             I y(x) %e     (-- (z(x))) dx
                            ]              dx
                            /


 -- Function: at (<expr>, [<eqn_1>, ..., <eqn_n>])
 -- Function: at (<expr>, <eqn>)
     Evaluates the expression <expr> with the variables assuming the
     values as specified for them in the list of equations `[<eqn_1>,
     ..., <eqn_n>]' or the single equation <eqn>.

     If a subexpression depends on any of the variables for which a
     value is specified but there is no `atvalue' specified and it
     can't be otherwise evaluated, then a noun form of the `at' is
     returned which displays in a two-dimensional form.

     `at' carries out multiple substitutions in parallel.

     See also `atvalue'.  For other functions which carry out
     substitutions, see also `subst' and `ev'.

     Examples:

          (%i1) atvalue (f(x,y), [x = 0, y = 1], a^2);
                                          2
          (%o1)                          a
          (%i2) atvalue ('diff (f(x,y), x), x = 0, 1 + y);
          (%o2)                        @2 + 1
          (%i3) printprops (all, atvalue);
                                          !
                            d             !
                           --- (f(@1, @2))!       = @2 + 1
                           d@1            !
                                          !@1 = 0

                                               2
                                    f(0, 1) = a

          (%o3)                         done
          (%i4) diff (4*f(x, y)^2 - u(x, y)^2, x);
                            d                          d
          (%o4)  8 f(x, y) (-- (f(x, y))) - 2 u(x, y) (-- (u(x, y)))
                            dx                         dx
          (%i5) at (%, [x = 0, y = 1]);
                                                   !
                        2              d           !
          (%o5)     16 a  - 2 u(0, 1) (-- (u(x, y))!            )
                                       dx          !
                                                   !x = 0, y = 1


 -- Property: atomgrad
     `atomgrad' is the atomic gradient property of an expression.  This
     property is assigned by `gradef'.


 -- Function: atvalue (<expr>, [<x_1> = <a_1>, ..., <x_m> = <a_m>], <c>)
 -- Function: atvalue (<expr>, <x_1> = <a_1>, <c>)
     Assigns the value <c> to <expr> at the point `<x> = <a>'.
     Typically boundary values are established by this mechanism.

     <expr> is a function evaluation, `<f>(<x_1>, ..., <x_m>)', or a
     derivative, `diff (<f>(<x_1>, ..., <x_m>), <x_1>, <n_1>, ...,
     <x_n>, <n_m>)' in which the function arguments explicitly appear.
     <n_i> is the order of differentiation with respect to <x_i>.

     The point at which the atvalue is established is given by the list
     of equations `[<x_1> = <a_1>, ..., <x_m> = <a_m>]'.  If there is a
     single variable <x_1>, the sole equation may be given without
     enclosing it in a list.

     `printprops ([<f_1>, <f_2>, ...], atvalue)' displays the atvalues
     of the functions `<f_1>, <f_2>, ...' as specified by calls to
     `atvalue'.  `printprops (<f>, atvalue)' displays the atvalues of
     one function <f>.  `printprops (all, atvalue)' displays the
     atvalues of all functions for which atvalues are defined.

     The symbols `@1', `@2', ... represent the variables <x_1>, <x_2>,
     ... when atvalues are displayed.

     `atvalue' evaluates its arguments.  `atvalue' returns <c>, the
     atvalue.

     Examples:

          (%i1) atvalue (f(x,y), [x = 0, y = 1], a^2);
                                          2
          (%o1)                          a
          (%i2) atvalue ('diff (f(x,y), x), x = 0, 1 + y);
          (%o2)                        @2 + 1
          (%i3) printprops (all, atvalue);
                                          !
                            d             !
                           --- (f(@1, @2))!       = @2 + 1
                           d@1            !
                                          !@1 = 0

                                               2
                                    f(0, 1) = a

          (%o3)                         done
          (%i4) diff (4*f(x,y)^2 - u(x,y)^2, x);
                            d                          d
          (%o4)  8 f(x, y) (-- (f(x, y))) - 2 u(x, y) (-- (u(x, y)))
                            dx                         dx
          (%i5) at (%, [x = 0, y = 1]);
                                                   !
                        2              d           !
          (%o5)     16 a  - 2 u(0, 1) (-- (u(x, y))!            )
                                       dx          !
                                                   !x = 0, y = 1


 -- Function: cartan
     The exterior calculus of differential forms is a basic tool of
     differential geometry developed by Elie Cartan and has important
     applications in the theory of partial differential equations.  The
     `cartan' package implements the functions `ext_diff' and
     `lie_diff', along with the operators `~' (wedge product) and `|'
     (contraction of a form with a vector.)  Type `demo (tensor)' to
     see a brief description of these commands along with examples.

     `cartan' was implemented by F.B. Estabrook and H.D. Wahlquist.


 -- Function: del (<x>)
     `del (<x>)' represents the differential of the variable x.

     `diff' returns an expression containing `del' if an independent
     variable is not specified.  In this case, the return value is the
     so-called "total differential".

     Examples:

          (%i1) diff (log (x));
                                       del(x)
          (%o1)                        ------
                                         x
          (%i2) diff (exp (x*y));
                               x y              x y
          (%o2)            x %e    del(y) + y %e    del(x)
          (%i3) diff (x*y*z);
          (%o3)         x y del(z) + x z del(y) + y z del(x)


 -- Function: delta (<t>)
     The Dirac Delta function.

     Currently only `laplace' knows about the `delta' function.

     Example:

          (%i1) laplace (delta (t - a) * sin(b*t), t, s);
          Is  a  positive, negative, or zero?

          p;
                                             - a s
          (%o1)                   sin(a b) %e


 -- System variable: dependencies
 -- Function: dependencies (<f_1>, ..., <f_n>)
     The variable `dependencies' is the list of atoms which have
     functional dependencies, assigned by `depends', the function
     `dependencies', or `gradef'.  The `dependencies' list is
     cumulative: each call to `depends', `dependencies', or `gradef'
     appends additional items.  The default value of `dependencies' is
     `[]'.

     The function `dependencies(<f_1>, ..., <f_n>)' appends <f_1>, ...,
     <f_n>, to the `dependencies' list, where <f_1>, ..., <f_n> are
     expressions of the form `<f>(<x_1>, ..., <x_m>)', and <x_1>, ...,
     <x_m> are any number of arguments.

     `dependencies(<f>(<x_1>, ..., <x_m>))' is equivalent to
     `depends(<f>, [<x_1>, ..., <x_m>])'.

     See also `depends' and `gradef'.

          (%i1) dependencies;
          (%o1)                          []
          (%i2) depends (foo, [bar, baz]);
          (%o2)                    [foo(bar, baz)]
          (%i3) depends ([g, h], [a, b, c]);
          (%o3)               [g(a, b, c), h(a, b, c)]
          (%i4) dependencies;
          (%o4)        [foo(bar, baz), g(a, b, c), h(a, b, c)]
          (%i5) dependencies (quux (x, y), mumble (u));
          (%o5)                [quux(x, y), mumble(u)]
          (%i6) dependencies;
          (%o6) [foo(bar, baz), g(a, b, c), h(a, b, c), quux(x, y),
                                                                 mumble(u)]
          (%i7) remove (quux, dependency);
          (%o7)                         done
          (%i8) dependencies;
          (%o8)  [foo(bar, baz), g(a, b, c), h(a, b, c), mumble(u)]


 -- Function: depends (<f_1>, <x_1>, ..., <f_n>, <x_n>)
     Declares functional dependencies among variables for the purpose
     of computing derivatives.  In the absence of declared dependence,
     `diff (f, x)' yields zero.  If `depends (f, x)' is declared, `diff
     (f, x)' yields a symbolic derivative (that is, a `diff' noun).

     Each argument <f_1>, <x_1>, etc., can be the name of a variable or
     array, or a list of names.  Every element of <f_i> (perhaps just a
     single element) is declared to depend on every element of <x_i>
     (perhaps just a single element).  If some <f_i> is the name of an
     array or contains the name of an array, all elements of the array
     depend on <x_i>.

     `diff' recognizes indirect dependencies established by `depends'
     and applies the chain rule in these cases.

     `remove (<f>, dependency)' removes all dependencies declared for
     <f>.

     `depends' returns a list of the dependencies established.  The
     dependencies are appended to the global variable `dependencies'.
     `depends' evaluates its arguments.

     `diff' is the only Maxima command which recognizes dependencies
     established by `depends'.  Other functions (`integrate',
     `laplace', etc.)  only recognize dependencies explicitly
     represented by their arguments.  For example, `integrate' does not
     recognize the dependence of `f' on `x' unless explicitly
     represented as `integrate (f(x), x)'.

     `depends(<f>, [<x_1>, ..., <x_n>])' is equivalent to
     `dependencies(<f>(<x_1>, ..., <x_n>))'.

          (%i1) depends ([f, g], x);
          (%o1)                     [f(x), g(x)]
          (%i2) depends ([r, s], [u, v, w]);
          (%o2)               [r(u, v, w), s(u, v, w)]
          (%i3) depends (u, t);
          (%o3)                        [u(t)]
          (%i4) dependencies;
          (%o4)      [f(x), g(x), r(u, v, w), s(u, v, w), u(t)]
          (%i5) diff (r.s, u);
                                   dr           ds
          (%o5)                    -- . s + r . --
                                   du           du

          (%i6) diff (r.s, t);
                                dr du           ds du
          (%o6)                 -- -- . s + r . -- --
                                du dt           du dt

          (%i7) remove (r, dependency);
          (%o7)                         done
          (%i8) diff (r.s, t);
                                          ds du
          (%o8)                       r . -- --
                                          du dt


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

     When `derivabbrev' is `true', symbolic derivatives (that is,
     `diff' nouns) are displayed as subscripts.  Otherwise, derivatives
     are displayed in the Leibniz notation `dy/dx'.


 -- Function: derivdegree (<expr>, <y>, <x>)
     Returns the highest degree of the derivative of the dependent
     variable <y> with respect to the independent variable <x> occuring
     in <expr>.

     Example:

          (%i1) 'diff (y, x, 2) + 'diff (y, z, 3) + 'diff (y, x) * x^2;
                                   3     2
                                  d y   d y    2 dy
          (%o1)                   --- + --- + x  --
                                    3     2      dx
                                  dz    dx
          (%i2) derivdegree (%, y, x);
          (%o2)                           2


 -- Function: derivlist (<var_1>, ..., <var_k>)
     Causes only differentiations with respect to the indicated
     variables, within the `ev' command.


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

     When `derivsubst' is `true', a non-syntactic substitution such as
     `subst (x, 'diff (y, t), 'diff (y, t, 2))' yields `'diff (x, t)'.


 -- Function: diff (<expr>, <x_1>, <n_1>, ..., <x_m>, <n_m>)
 -- Function: diff (<expr>, <x>, <n>)
 -- Function: diff (<expr>, <x>)
 -- Function: diff (<expr>)
     Returns the derivative or differential of <expr> with respect to
     some or all variables in <expr>.

     `diff (<expr>, <x>, <n>)' returns the <n>'th derivative of <expr>
     with respect to <x>.

     `diff (<expr>, <x_1>, <n_1>, ..., <x_m>, <n_m>)' returns the mixed
     partial derivative of <expr> with respect to <x_1>, ..., <x_m>.
     It is equivalent to `diff (... (diff (<expr>, <x_m>, <n_m>) ...),
     <x_1>, <n_1>)'.

     `diff (<expr>, <x>)' returns the first derivative of <expr> with
     respect to the variable <x>.

     `diff (<expr>)' returns the total differential of <expr>, that is,
     the sum of the derivatives of <expr> with respect to each its
     variables times the differential `del' of each variable.  No
     further simplification of `del' is offered.

     The noun form of `diff' is required in some contexts, such as
     stating a differential equation.  In these cases, `diff' may be
     quoted (as `'diff') to yield the noun form instead of carrying out
     the differentiation.

     When `derivabbrev' is `true', derivatives are displayed as
     subscripts.  Otherwise, derivatives are displayed in the Leibniz
     notation, `dy/dx'.

     Examples:

          (%i1) diff (exp (f(x)), x, 2);
                               2
                        f(x)  d               f(x)  d         2
          (%o1)       %e     (--- (f(x))) + %e     (-- (f(x)))
                                2                   dx
                              dx
          (%i2) derivabbrev: true$
          (%i3) 'integrate (f(x, y), y, g(x), h(x));
                                   h(x)
                                  /
                                  [
          (%o3)                   I     f(x, y) dy
                                  ]
                                  /
                                   g(x)
          (%i4) diff (%, x);
                 h(x)
                /
                [
          (%o4) I     f(x, y)  dy + f(x, h(x)) h(x)  - f(x, g(x)) g(x)
                ]            x                     x                  x
                /
                 g(x)

     For the tensor package, the following modifications have been
     incorporated:

     (1) The derivatives of any indexed objects in <expr> will have the
     variables <x_i> appended as additional arguments.  Then all the
     derivative indices will be sorted.

     (2) The <x_i> may be integers from 1 up to the value of the
     variable `dimension' [default value: 4].  This will cause the
     differentiation to be carried out with respect to the <x_i>'th
     member of the list `coordinates' which should be set to a list of
     the names of the coordinates, e.g., `[x, y, z, t]'. If
     `coordinates' is bound to an atomic variable, then that variable
     subscripted by <x_i> will be used for the variable of
     differentiation.  This permits an array of coordinate names or
     subscripted names like `X[1]', `X[2]', ... to be used.  If
     `coordinates' has not been assigned a value, then the variables
     will be treated as in (1) above.


 -- Special symbol: diff
     When `diff' is present as an `evflag' in call to `ev', all
     differentiations indicated in `expr' are carried out.


 -- Function: dscalar (<f>)
     Applies the scalar d'Alembertian to the scalar function <f>.

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


 -- Function: express (<expr>)
     Expands differential operator nouns into expressions in terms of
     partial derivatives.  `express' recognizes the operators `grad',
     `div', `curl', `laplacian'.  `express' also expands the cross
     product `~'.

     Symbolic derivatives (that is, `diff' nouns) in the return value
     of express may be evaluated by including `diff' in the `ev'
     function call or command line.  In this context, `diff' acts as an
     `evfun'.

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

     Examples:

          (%i1) load ("vect")$
          (%i2) grad (x^2 + y^2 + z^2);
                                        2    2    2
          (%o2)                  grad (z  + y  + x )
          (%i3) express (%);
                 d    2    2    2   d    2    2    2   d    2    2    2
          (%o3) [-- (z  + y  + x ), -- (z  + y  + x ), -- (z  + y  + x )]
                 dx                 dy                 dz
          (%i4) ev (%, diff);
          (%o4)                    [2 x, 2 y, 2 z]
          (%i5) div ([x^2, y^2, z^2]);
                                        2   2   2
          (%o5)                   div [x , y , z ]
          (%i6) express (%);
                             d    2    d    2    d    2
          (%o6)              -- (z ) + -- (y ) + -- (x )
                             dz        dy        dx
          (%i7) ev (%, diff);
          (%o7)                    2 z + 2 y + 2 x
          (%i8) curl ([x^2, y^2, z^2]);
                                         2   2   2
          (%o8)                   curl [x , y , z ]
          (%i9) express (%);
                 d    2    d    2   d    2    d    2   d    2    d    2
          (%o9) [-- (z ) - -- (y ), -- (x ) - -- (z ), -- (y ) - -- (x )]
                 dy        dz       dz        dx       dx        dy
          (%i10) ev (%, diff);
          (%o10)                      [0, 0, 0]
          (%i11) laplacian (x^2 * y^2 * z^2);
                                            2  2  2
          (%o11)                laplacian (x  y  z )
          (%i12) express (%);
                   2                2                2
                  d     2  2  2    d     2  2  2    d     2  2  2
          (%o12)  --- (x  y  z ) + --- (x  y  z ) + --- (x  y  z )
                    2                2                2
                  dz               dy               dx
          (%i13) ev (%, diff);
                                2  2      2  2      2  2
          (%o13)             2 y  z  + 2 x  z  + 2 x  y
          (%i14) [a, b, c] ~ [x, y, z];
          (%o14)                [a, b, c] ~ [x, y, z]
          (%i15) express (%);
          (%o15)          [b z - c y, c x - a z, a y - b x]


 -- Function: gradef (<f>(<x_1>, ..., <x_n>), <g_1>, ..., <g_m>)
 -- Function: gradef (<a>, <x>, <expr>)
     Defines the partial derivatives (i.e., the components of the
     gradient) of the function <f> or variable <a>.

     `gradef (<f>(<x_1>, ..., <x_n>), <g_1>, ..., <g_m>)' defines
     `d<f>/d<x_i>' as <g_i>, where <g_i> is an expression; <g_i> may be
     a function call, but not the name of a function.  The number of
     partial derivatives <m> may be less than the number of arguments
     <n>, in which case derivatives are defined with respect to <x_1>
     through <x_m> only.

     `gradef (<a>, <x>, <expr>)' defines the derivative of variable <a>
     with respect to <x> as <expr>.  This also establishes the
     dependence of <a> on <x> (via `depends (<a>, <x>)').

     The first argument `<f>(<x_1>, ..., <x_n>)' or <a> is quoted, but
     the remaining arguments <g_1>, ..., <g_m> are evaluated.  `gradef'
     returns the function or variable for which the partial derivatives
     are defined.

     `gradef' can redefine the derivatives of Maxima's built-in
     functions.  For example, `gradef (sin(x), sqrt (1 - sin(x)^2))'
     redefines the derivative of `sin'.

     `gradef' cannot define partial derivatives for a subscripted
     function.

     `printprops ([<f_1>, ..., <f_n>], gradef)' displays the partial
     derivatives of the functions <f_1>, ..., <f_n>, as defined by
     `gradef'.

     `printprops ([<a_n>, ..., <a_n>], atomgrad)' displays the partial
     derivatives of the variables <a_n>, ..., <a_n>, as defined by
     `gradef'.

     `gradefs' is the list of the functions for which partial
     derivatives have been defined by `gradef'.  `gradefs' does not
     include any variables for which partial derivatives have been
     defined by `gradef'.

     Gradients are needed when, for example, a function is not known
     explicitly but its first derivatives are and it is desired to
     obtain higher order derivatives.


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

     `gradefs' is the list of the functions for which partial
     derivatives have been defined by `gradef'.  `gradefs' does not
     include any variables for which partial derivatives have been
     defined by `gradef'.


 -- Function: laplace (<expr>, <t>, <s>)
     Attempts to compute the Laplace transform of <expr> with respect
     to the variable <t> and transform parameter <s>.

     `laplace' recognizes in <expr> the functions `delta', `exp',
     `log', `sin', `cos', `sinh', `cosh', and `erf', as well as
     `derivative', `integrate', `sum', and `ilt'.  If laplace fails to
     find a transform the function `specint' is called.  `specint' can
     find the laplace transform for expressions with special functions
     like the bessel functions `bessel_j', `bessel_i', ...  and can
     handle the `unit_step' function.  See also `specint'.

     If `specint' cannot find a solution too, a noun `laplace' is
     returned.

     <expr> may also be a linear, constant coefficient differential
     equation in which case `atvalue' of the dependent variable is used.
     The required atvalue may be supplied either before or after the
     transform is computed.  Since the initial conditions must be
     specified at zero, if one has boundary conditions imposed
     elsewhere he can impose these on the general solution and
     eliminate the constants by solving the general solution for them
     and substituting their values back.

     `laplace' recognizes convolution integrals of the form `integrate
     (f(x) * g(t - x), x, 0, t)'; other kinds of convolutions are not
     recognized.

     Functional relations must be explicitly represented in <expr>;
     implicit relations, established by `depends', are not recognized.
     That is, if <f> depends on <x> and <y>, `f (x, y)' must appear in
     <expr>.

     See also `ilt', the inverse Laplace transform.

     Examples:

          (%i1) laplace (exp (2*t + a) * sin(t) * t, t, s);
                                      a
                                    %e  (2 s - 4)
          (%o1)                    ---------------
                                     2           2
                                   (s  - 4 s + 5)
          (%i2) laplace ('diff (f (x), x), x, s);
          (%o2)             s laplace(f(x), x, s) - f(0)
          (%i3) diff (diff (delta (t), t), t);
                                    2
                                   d
          (%o3)                    --- (delta(t))
                                     2
                                   dt
          (%i4) laplace (%, t, s);
                                      !
                         d            !         2
          (%o4)        - -- (delta(t))!      + s  - delta(0) s
                         dt           !
                                      !t = 0
          (%i5) assume(a>0)$
          (%i6) laplace(gamma_incomplete(a,t),t,s),gamma_expand:true;
                                                        - a - 1
                                   gamma(a)   gamma(a) s
          (%o6)                    -------- - -----------------
                                      s            1     a
                                                  (- + 1)
                                                   s
          (%i7) factor(laplace(gamma_incomplete(1/2,t),t,s));
                                                        s + 1
                                sqrt(%pi) (sqrt(s) sqrt(-----) - 1)
                                                          s
          (%o7)                 -----------------------------------
                                          3/2      s + 1
                                         s    sqrt(-----)
                                                     s
          (%i8) assume(exp(%pi*s)>1)$
          (%i9) laplace(sum((-1)^n*unit_step(t-n*%pi)*sin(t),n,0,inf),t,s),
                   simpsum;
                                   %i                         %i
                        ------------------------ - ------------------------
                                        - %pi s                    - %pi s
                        (s + %i) (1 - %e       )   (s - %i) (1 - %e       )
          (%o9)         ---------------------------------------------------
                                                 2
          (%i9) factor(%);
                                                %pi s
                                              %e
          (%o9)                   -------------------------------
                                                       %pi s
                                  (s - %i) (s + %i) (%e      - 1)



File: maxima.info,  Node: Integration,  Next: Equations,  Prev: Differentiation,  Up: Top

19 Integration
**************

* Menu:

* Introduction to Integration::
* Functions and Variables for Integration::
* Introduction to QUADPACK::
* Functions and Variables for QUADPACK::


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

19.1 Introduction to Integration
================================

Maxima has several routines for handling integration.  The `integrate'
function makes use of most of them.  There is also the `antid' package,
which handles an unspecified function (and its derivatives, of course).
For numerical uses, there is a set of adaptive integrators from
QUADPACK, named `quad_qag', `quad_qags', etc., which are described
under the heading `QUADPACK'.  Hypergeometric functions are being
worked on, see `specint' for details.  Generally speaking, Maxima only
handles integrals which are integrable in terms of the "elementary
functions" (rational functions, trigonometrics, logs, exponentials,
radicals, etc.) and a few extensions (error function, dilogarithm).  It
does not handle integrals in terms of unknown functions such as `g(x)'
and `h(x)'.


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

19.2 Functions and Variables for Integration
============================================

 -- Function: changevar (<expr>, <f(x,y)>, <y>, <x>)
     Makes the change of variable given by `<f(x,y)> = 0' in all
     integrals occurring in <expr> with integration with respect to <x>.
     The new variable is <y>.

          (%i1) assume(a > 0)$
          (%i2) 'integrate (%e**sqrt(a*y), y, 0, 4);
                                4
                               /
                               [    sqrt(a) sqrt(y)
          (%o2)                I  %e                dy
                               ]
                               /
                                0
          (%i3) changevar (%, y-z^2/a, z, y);
                                0
                               /
                               [                abs(z)
                             2 I            z %e       dz
                               ]
                               /
                                - 2 sqrt(a)
          (%o3)            - ----------------------------
                                          a

     An expression containing a noun form, such as the instances of
     `'integrate' above, may be evaluated by `ev' with the `nouns' flag.
     For example, the expression returned by `changevar' above may be
     evaluated by `ev (%o3, nouns)'.

     `changevar' may also be used to changes in the indices of a sum or
     product.  However, it must be realized that when a change is made
     in a sum or product, this change must be a shift, i.e., `i = j+
     ...', not a higher degree function.  E.g.,

          (%i4) sum (a[i]*x^(i-2), i, 0, inf);
                                   inf
                                   ====
                                   \         i - 2
          (%o4)                     >    a  x
                                   /      i
                                   ====
                                   i = 0
          (%i5) changevar (%, i-2-n, n, i);
                                  inf
                                  ====
                                  \               n
          (%o5)                    >      a      x
                                  /        n + 2
                                  ====
                                  n = - 2


 -- Function: dblint (<f>, <r>, <s>, <a>, <b>)
     A double-integral routine which was written in top-level Maxima
     and then translated and compiled to machine code.  Use `load
     (dblint)' to access this package.  It uses the Simpson's rule
     method in both the x and y directions to calculate

          /b /s(x)
          |  |
          |  |    f(x,y) dy dx
          |  |
          /a /r(x)

     The function <f> must be a translated or compiled function of two
     variables, and <r> and <s> must each be a translated or compiled
     function of one variable, while <a> and <b> must be floating point
     numbers.  The routine has two global variables which determine the
     number of divisions of the x and y intervals: `dblint_x' and
     `dblint_y', both of which are initially 10, and can be changed
     independently to other integer values (there are `2*dblint_x+1'
     points computed in the x direction, and `2*dblint_y+1' in the y
     direction).  The routine subdivides the X axis and then for each
     value of X it first computes `<r>(x)' and `<s>(x)'; then the Y axis
     between `<r>(x)' and `<s>(x)' is subdivided and the integral along
     the Y axis is performed using Simpson's rule; then the integral
     along the X axis is done using Simpson's rule with the function
     values being the Y-integrals.  This procedure may be numerically
     unstable for a great variety of reasons, but is reasonably fast:
     avoid using it on highly oscillatory functions and functions with
     singularities (poles or branch points in the region).  The Y
     integrals depend on how far apart `<r>(x)' and `<s>(x)' are, so if
     the distance `<s>(x) - <r>(x)' varies rapidly with X, there may be
     substantial errors arising from truncation with different
     step-sizes in the various Y integrals.  One can increase
     `dblint_x' and `dblint_y' in an effort to improve the coverage of
     the region, at the expense of computation time.  The function
     values are not saved, so if the function is very time-consuming,
     you will have to wait for re-computation if you change anything
     (sorry).  It is required that the functions <f>, <r>, and <s> be
     either translated or compiled prior to calling `dblint'.  This
     will result in orders of magnitude speed improvement over
     interpreted code in many cases!

     `demo (dblint)' executes a demonstration of `dblint' applied to an
     example problem.


 -- Function: defint (<expr>, <x>, <a>, <b>)
     Attempts to compute a definite integral.  `defint' is called by
     `integrate' when limits of integration are specified, i.e., when
     `integrate' is called as `integrate (<expr>, <x>, <a>, <b>)'.
     Thus from the user's point of view, it is sufficient to call
     `integrate'.

     `defint' returns a symbolic expression, either the computed
     integral or the noun form of the integral.  See `quad_qag' and
     related functions for numerical approximation of definite
     integrals.


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

     When `erfflag' is `false', prevents `risch' from introducing the
     `erf' function in the answer if there were none in the integrand to
     begin with.


 -- Function: ilt (<expr>, <s>, <t>)
     Computes the inverse Laplace transform of <expr> with respect to
     <s> and parameter <t>.  <expr> must be a ratio of polynomials
     whose denominator has only linear and quadratic factors.  By using
     the functions `laplace' and `ilt' together with the `solve' or
     `linsolve' functions the user can solve a single differential or
     convolution integral equation or a set of them.

          (%i1) 'integrate (sinh(a*x)*f(t-x), x, 0, t) + b*f(t) = t**2;
                        t
                       /
                       [                                    2
          (%o1)        I  f(t - x) sinh(a x) dx + b f(t) = t
                       ]
                       /
                        0
          (%i2) laplace (%, t, s);
                                         a laplace(f(t), t, s)   2
          (%o2)  b laplace(f(t), t, s) + --------------------- = --
                                                 2    2           3
                                                s  - a           s
          (%i3) linsolve ([%], ['laplace(f(t), t, s)]);
                                                  2      2
                                               2 s  - 2 a
          (%o3)     [laplace(f(t), t, s) = --------------------]
                                              5         2     3
                                           b s  + (a - a  b) s
          (%i4) ilt (rhs (first (%)), s, t);
          Is  a b (a b - 1)  positive, negative, or zero?

          pos;
                         sqrt(a b (a b - 1)) t
                  2 cosh(---------------------)       2
                                   b               a t
          (%o4) - ----------------------------- + -------
                        3  2      2               a b - 1
                       a  b  - 2 a  b + a

                                                                 2
                                                       + ------------------
                                                          3  2      2
                                                         a  b  - 2 a  b + a


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

     When `true', definite integration tries to find poles in the
     integrand in the interval of integration.  If there are, then the
     integral is evaluated appropriately as a principal value integral.
     If intanalysis is `false', this check is not performed and
     integration is done assuming there are no poles.

     See also `ldefint'.

     Examples:

     Maxima can solve the following integrals, when `intanalysis' is
     set to `false':

          (%i1) integrate(1/(sqrt(x)+1),x,0,1);
                                          1
                                         /
                                         [       1
          (%o1)                          I  ----------- dx
                                         ]  sqrt(x) + 1
                                         /
                                          0

          (%i2) integrate(1/(sqrt(x)+1),x,0,1),intanalysis:false;
          (%o2)                            2 - 2 log(2)

          (%i3) integrate(cos(a)/sqrt((tan(a))^2 +1),a,-%pi/2,%pi/2);
          The number 1 isn't in the domain of atanh
           -- an error. To debug this try: debugmode(true);

          (%i4) intanalysis:false$
          (%i5) integrate(cos(a)/sqrt((tan(a))^2+1),a,-%pi/2,%pi/2);
                                                %pi
          (%o5)                                 ---
                                                 2


 -- Function: integrate (<expr>, <x>)
 -- Function: integrate (<expr>, <x>, <a>, <b>)
     Attempts to symbolically compute the integral of <expr> with
     respect to <x>.  `integrate (<expr>, <x>)' is an indefinite
     integral, while `integrate (<expr>, <x>, <a>, <b>)' is a definite
     integral, with limits of integration <a> and <b>.  The limits
     should not contain <x>, although `integrate' does not enforce this
     restriction.  <a> need not be less than <b>.  If <b> is equal to
     <a>, `integrate' returns zero.

     See `quad_qag' and related functions for numerical approximation of
     definite integrals.  See `residue' for computation of residues
     (complex integration).  See `antid' for an alternative means of
     computing indefinite integrals.

     The integral (an expression free of `integrate') is returned if
     `integrate' succeeds.  Otherwise the return value is the noun form
     of the integral (the quoted operator `'integrate') or an
     expression containing one or more noun forms.  The noun form of
     `integrate' is displayed with an integral sign.

     In some circumstances it is useful to construct a noun form by
     hand, by quoting `integrate' with a single quote, e.g.,
     `'integrate (<expr>, <x>)'.  For example, the integral may depend
     on some parameters which are not yet computed.  The noun may be
     applied to its arguments by `ev (<i>, nouns)' where <i> is the
     noun form of interest.

     `integrate' handles definite integrals separately from indefinite,
     and employs a range of heuristics to handle each case.  Special
     cases of definite integrals include limits of integration equal to
     zero or infinity (`inf' or `minf'), trigonometric functions with
     limits of integration equal to zero and `%pi' or `2 %pi', rational
     functions, integrals related to the definitions of the `beta' and
     `psi' functions, and some logarithmic and trigonometric integrals.
     Processing rational functions may include computation of residues.
     If an applicable special case is not found, an attempt will be
     made to compute the indefinite integral and evaluate it at the
     limits of integration.  This may include taking a limit as a limit
     of integration goes to infinity or negative infinity; see also
     `ldefint'.

     Special cases of indefinite integrals include trigonometric
     functions, exponential and logarithmic functions, and rational
     functions.  `integrate' may also make use of a short table of
     elementary integrals.

     `integrate' may carry out a change of variable if the integrand
     has the form `f(g(x)) * diff(g(x), x)'.  `integrate' attempts to
     find a subexpression `g(x)' such that the derivative of `g(x)'
     divides the integrand.  This search may make use of derivatives
     defined by the `gradef' function.  See also `changevar' and
     `antid'.

     If none of the preceding heuristics find the indefinite integral,
     the Risch algorithm is executed.  The flag `risch' may be set as
     an `evflag', in a call to `ev' or on the command line, e.g., `ev
     (integrate (<expr>, <x>), risch)' or `integrate (<expr>, <x>),
     risch'.  If `risch' is present, `integrate' calls the `risch'
     function without attempting heuristics first.  See also `risch'.

     `integrate' works only with functional relations represented
     explicitly with the `f(x)' notation.  `integrate' does not respect
     implicit dependencies established by the `depends' function.

     `integrate' may need to know some property of a parameter in the
     integrand.  `integrate' will first consult the `assume' database,
     and, if the variable of interest is not there, `integrate' will
     ask the user.  Depending on the question, suitable responses are
     `yes;' or `no;', or `pos;', `zero;', or `neg;'.

     `integrate' is not, by default, declared to be linear.  See
     `declare' and `linear'.

     `integrate' attempts integration by parts only in a few special
     cases.

     Examples:

        * Elementary indefinite and definite integrals.

               (%i1) integrate (sin(x)^3, x);
                                          3
                                       cos (x)
               (%o1)                   ------- - cos(x)
                                          3
               (%i2) integrate (x/ sqrt (b^2 - x^2), x);
                                                2    2
               (%o2)                    - sqrt(b  - x )
               (%i3) integrate (cos(x)^2 * exp(x), x, 0, %pi);
                                              %pi
                                          3 %e      3
               (%o3)                      ------- - -
                                             5      5
               (%i4) integrate (x^2 * exp(-x^2), x, minf, inf);
                                           sqrt(%pi)
               (%o4)                       ---------
                                               2

        * Use of `assume' and interactive query.

               (%i1) assume (a > 1)$
               (%i2) integrate (x**a/(x+1)**(5/2), x, 0, inf);
                   2 a + 2
               Is  -------  an integer?
                      5

               no;
               Is  2 a - 3  positive, negative, or zero?

               neg;
                                                  3
               (%o2)                  beta(a + 1, - - a)
                                                  2

        * Change of variable.  There are two changes of variable in
          this example: one using a derivative established by `gradef',
          and one using the derivation `diff(r(x))' of an unspecified
          function `r(x)'.

               (%i3) gradef (q(x), sin(x**2));
               (%o3)                         q(x)
               (%i4) diff (log (q (r (x))), x);
                                     d               2
                                    (-- (r(x))) sin(r (x))
                                     dx
               (%o4)                ----------------------
                                           q(r(x))
               (%i5) integrate (%, x);
               (%o5)                     log(q(r(x)))

        * Return value contains the `'integrate' noun form.  In this
          example, Maxima can extract one factor of the denominator of
          a rational function, but cannot factor the remainder or
          otherwise find its integral.  `grind' shows the noun form
          `'integrate' in the result.  See also `integrate_use_rootsof'
          for more on integrals of rational functions.

               (%i1) expand ((x-4) * (x^3+2*x+1));
                                   4      3      2
               (%o1)              x  - 4 x  + 2 x  - 7 x - 4
               (%i2) integrate (1/%, x);
                                             /  2
                                             [ x  + 4 x + 18
                                             I ------------- dx
                                             ]  3
                                log(x - 4)   / x  + 2 x + 1
               (%o2)            ---------- - ------------------
                                    73               73
               (%i3) grind (%);
               log(x-4)/73-('integrate((x^2+4*x+18)/(x^3+2*x+1),x))/73$

        * Defining a function in terms of an integral.  The body of a
          function is not evaluated when the function is defined.  Thus
          the body of `f_1' in this example contains the noun form of
          `integrate'.  The quote-quote operator `''' causes the
          integral to be evaluated, and the result becomes the body of
          `f_2'.

               (%i1) f_1 (a) := integrate (x^3, x, 1, a);
                                                    3
               (%o1)           f_1(a) := integrate(x , x, 1, a)
               (%i2) ev (f_1 (7), nouns);
               (%o2)                          600
               (%i3) /* Note parentheses around integrate(...) here */
                     f_2 (a) := ''(integrate (x^3, x, 1, a));
                                                  4
                                                 a    1
               (%o3)                   f_2(a) := -- - -
                                                 4    4
               (%i4) f_2 (7);
               (%o4)                          600


 -- System variable: integration_constant
     Default value: `%c'

     When a constant of integration is introduced by indefinite
     integration of an equation, the name of the constant is
     constructed by concatenating `integration_constant' and
     `integration_constant_counter'.

     `integration_constant' may be assigned any symbol.

     Examples:

          (%i1) integrate (x^2 = 1, x);
                                     3
                                    x
          (%o1)                     -- = x + %c1
                                    3
          (%i2) integration_constant : 'k;
          (%o2)                           k
          (%i3) integrate (x^2 = 1, x);
                                      3
                                     x
          (%o3)                      -- = x + k2
                                     3


 -- System variable: integration_constant_counter
     Default value: 0

     When a constant of integration is introduced by indefinite
     integration of an equation, the name of the constant is
     constructed by concatenating `integration_constant' and
     `integration_constant_counter'.

     `integration_constant_counter' is incremented before constructing
     the next integration constant.

     Examples:

          (%i1) integrate (x^2 = 1, x);
                                     3
                                    x
          (%o1)                     -- = x + %c1
                                    3
          (%i2) integrate (x^2 = 1, x);
                                     3
                                    x
          (%o2)                     -- = x + %c2
                                    3
          (%i3) integrate (x^2 = 1, x);
                                     3
                                    x
          (%o3)                     -- = x + %c3
                                    3
          (%i4) reset (integration_constant_counter);
          (%o4)            [integration_constant_counter]
          (%i5) integrate (x^2 = 1, x);
                                     3
                                    x
          (%o5)                     -- = x + %c1
                                    3


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

     When `integrate_use_rootsof' is `true' and the denominator of a
     rational function cannot be factored, `integrate' returns the
     integral in a form which is a sum over the roots (not yet known)
     of the denominator.

     For example, with `integrate_use_rootsof' set to `false',
     `integrate' returns an unsolved integral of a rational function in
     noun form:

          (%i1) integrate_use_rootsof: false$
          (%i2) integrate (1/(1+x+x^5), x);
                  /  2
                  [ x  - 4 x + 5
                  I ------------ dx                            2 x + 1
                  ]  3    2                2            5 atan(-------)
                  / x  - x  + 1       log(x  + x + 1)          sqrt(3)
          (%o2)   ----------------- - --------------- + ---------------
                          7                 14             7 sqrt(3)

     Now we set the flag to be true and the unsolved part of the
     integral will be expressed as a summation over the roots of the
     denominator of the rational function:

          (%i3) integrate_use_rootsof: true$
          (%i4) integrate (1/(1+x+x^5), x);
                ====        2
                \       (%r4  - 4 %r4 + 5) log(x - %r4)
                 >      -------------------------------
                /                    2
                ====            3 %r4  - 2 %r4
                                3    2
                %r4 in rootsof(x  - x  + 1)
          (%o4) ----------------------------------------------------------
                         7

                                                                2 x + 1
                                            2            5 atan(-------)
                                       log(x  + x + 1)          sqrt(3)
                                     - --------------- + ---------------
                                             14             7 sqrt(3)

     Alternatively the user may compute the roots of the denominator
     separately, and then express the integrand in terms of these
     roots, e.g., `1/((x - a)*(x - b)*(x - c))' or `1/((x^2 - (a+b)*x +
     a*b)*(x - c))' if the denominator is a cubic polynomial.
     Sometimes this will help Maxima obtain a more useful result.


 -- Function: ldefint (<expr>, <x>, <a>, <b>)
     Attempts to compute the definite integral of <expr> by using
     `limit' to evaluate the indefinite integral of <expr> with respect
     to <x> at the upper limit <b> and at the lower limit <a>.  If it
     fails to compute the definite integral, `ldefint' returns an
     expression containing limits as noun forms.

     `ldefint' is not called from `integrate', so executing `ldefint
     (<expr>, <x>, <a>, <b>)' may yield a different result than
     `integrate (<expr>, <x>, <a>, <b>)'.  `ldefint' always uses the
     same method to evaluate the definite integral, while `integrate'
     may employ various heuristics and may recognize some special cases.


 -- Function: potential (<givengradient>)
     The calculation makes use of the global variable
     `potentialzeroloc[0]' which must be `nonlist' or of the form

          [indeterminatej=expressionj, indeterminatek=expressionk, ...]

     the former being equivalent to the nonlist expression for all
     right-hand sides in the latter.  The indicated right-hand sides
     are used as the lower limit of integration.  The success of the
     integrations may depend upon their values and order.
     `potentialzeroloc' is initially set to 0.

 -- Function: residue (<expr>, <z>, <z_0>)
     Computes the residue in the complex plane of the expression <expr>
     when the variable <z> assumes the value <z_0>.  The residue is the
     coefficient of `(<z> - <z_0>)^(-1)' in the Laurent series for
     <expr>.

          (%i1) residue (s/(s**2+a**2), s, a*%i);
                                          1
          (%o1)                           -
                                          2
          (%i2) residue (sin(a*x)/x**4, x, 0);
                                           3
                                          a
          (%o2)                         - --
                                          6


 -- Function: risch (<expr>, <x>)
     Integrates <expr> with respect to <x> using the transcendental
     case of the Risch algorithm.  (The algebraic case of the Risch
     algorithm has not been implemented.)  This currently handles the
     cases of nested exponentials and logarithms which the main part of
     `integrate' can't do.  `integrate' will automatically apply
     `risch' if given these cases.

     `erfflag', if `false', prevents `risch' from introducing the `erf'
     function in the answer if there were none in the integrand to begin
     with.

          (%i1) risch (x^2*erf(x), x);
                                                                  2
                       3                      2                - x
                  %pi x  erf(x) + (sqrt(%pi) x  + sqrt(%pi)) %e
          (%o1)   -------------------------------------------------
                                        3 %pi
          (%i2) diff(%, x), ratsimp;
                                       2
          (%o2)                       x  erf(x)


 -- Function: tldefint (<expr>, <x>, <a>, <b>)
     Equivalent to `ldefint' with `tlimswitch' set to `true'.



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

19.3 Introduction to QUADPACK
=============================

QUADPACK is a collection of functions for the numerical computation of
one-dimensional definite integrals.  It originated from a joint project
of R. Piessens (1), E. de Doncker (2), C. Ueberhuber (3), and D.
Kahaner (4).

   The QUADPACK library included in Maxima is an automatic translation
(via the program `f2cl') of the Fortran source code of QUADPACK as it
appears in the SLATEC Common Mathematical Library, Version 4.1 (5).
The SLATEC library is dated July 1993, but the QUADPACK functions were
written some years before.  There is another version of QUADPACK at
Netlib (6); it is not clear how that version differs from the SLATEC
version.

   The QUADPACK functions included in Maxima are all automatic, in the
sense that these functions attempt to compute a result to a specified
accuracy, requiring an unspecified number of function evaluations.
Maxima's Lisp translation of QUADPACK also includes some non-automatic
functions, but they are not exposed at the Maxima level.

   Further information about QUADPACK can be found in the QUADPACK book
(7).

19.3.1 Overview
---------------

`quad_qag'
     Integration of a general function over a finite interval.
     `quad_qag' implements a simple globally adaptive integrator using
     the strategy of Aind (Piessens, 1973).  The caller may choose
     among 6 pairs of Gauss-Kronrod quadrature formulae for the rule
     evaluation component.  The high-degree rules are suitable for
     strongly oscillating integrands.

`quad_qags'
     Integration of a general function over a finite interval.
     `quad_qags' implements globally adaptive interval subdivision with
     extrapolation (de Doncker, 1978) by the Epsilon algorithm (Wynn,
     1956).

`quad_qagi'
     Integration of a general function over an infinite or
     semi-infinite interval.  The interval is mapped onto a finite
     interval and then the same strategy as in `quad_qags' is applied.

`quad_qawo'
     Integration of cos(omega x) f(x) or sin(omega x) f(x) over a
     finite interval, where omega is a constant.  The rule evaluation
     component is based on the modified Clenshaw-Curtis technique.
     `quad_qawo' applies adaptive subdivision with extrapolation,
     similar to `quad_qags'.

`quad_qawf'
     Calculates a Fourier cosine or Fourier sine transform on a
     semi-infinite interval.  The same approach as in `quad_qawo' is
     applied on successive finite intervals, and convergence
     acceleration by means of the Epsilon algorithm (Wynn, 1956) is
     applied to the series of the integral contributions.

`quad_qaws'
     Integration of w(x) f(x) over a finite interval [a, b], where w is
     a function of the form (x - a)^alpha (b - x)^beta v(x) and v(x) is
     1 or log(x - a) or log(b - x) or log(x - a) log(b - x), and alpha
     > -1 and beta > -1.

     A globally adaptive subdivision strategy is applied, with modified
     Clenshaw-Curtis integration on the subintervals which contain a or
     b.

`quad_qawc'
     Computes the Cauchy principal value of f(x)/(x - c) over a finite
     interval (a, b) and specified c.  The strategy is globally
     adaptive, and modified Clenshaw-Curtis integration is used on the
     subranges which contain the point x = c.

`quad_qagp'
     Basically the same as `quad_qags' but points of singularity or
     discontinuity of the integrand must be supplied.  This makes it
     easier for the integrator to produce a good solution.

   ---------- Footnotes ----------

   (1) Applied Mathematics and Programming Division, K.U. Leuven

   (2) Applied Mathematics and Programming Division, K.U. Leuven

   (3) Institut fu"r Mathematik, T.U. Wien

   (4) National Bureau of Standards, Washington, D.C., U.S.A

   (5) `http://www.netlib.org/slatec'

   (6) `http://www.netlib.org/quadpack'

   (7) R. Piessens, E. de Doncker-Kapenga, C.W. Uberhuber, and D.K.
Kahaner.  QUADPACK: A Subroutine Package for Automatic Integration.
Berlin: Springer-Verlag, 1983, ISBN 0387125531.


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

19.4 Functions and Variables for QUADPACK
=========================================

 -- Function: quad_qag (<f(x)>, <x>, <a>, <b>, <key>, [<epsrel>,
          <epsabs>, <limit>])
 -- Function: quad_qag (<f>, <x>, <a>, <b>, <key>, [<epsrel>, <epsabs>,
          <limit>])
     Integration of a general function over a finite interval.
     `quad_qag' implements a simple globally adaptive integrator using
     the strategy of Aind (Piessens, 1973).  The caller may choose
     among 6 pairs of Gauss-Kronrod quadrature formulae for the rule
     evaluation component.  The high-degree rules are suitable for
     strongly oscillating integrands.

     `quad_qag' computes the integral

     integrate (f(x), x, a, b)

     The function to be integrated is <f(x)>, with dependent variable
     <x>, and the function is to be integrated between the limits <a>
     and <b>.  <key> is the integrator to be used and should be an
     integer between 1 and 6, inclusive.  The value of <key> selects
     the order of the Gauss-Kronrod integration rule.  High-order rules
     are suitable for strongly oscillating integrands.

     The integrand may be specified as the name of a Maxima or Lisp
     function or operator, a Maxima lambda expression, or a general
     Maxima expression.

     The numerical integration is done adaptively by subdividing the
     integration region into sub-intervals until the desired accuracy is
     achieved.

     The keyword arguments are optional and may be specified in any
     order.  They all take the form `key=val'.  The keyword arguments
     are:

    `epsrel'
          Desired relative error of approximation.  Default is 1d-8.

    `epsabs'
          Desired absolute error of approximation.  Default is 0.

    `limit'
          Size of internal work array.  <limit> is the maximum number
          of subintervals to use.  Default is 200.

     `quad_qag' returns a list of four elements:

        * an approximation to the integral,

        * the estimated absolute error of the approximation,

        * the number integrand evaluations,

        * an error code.

     The error code (fourth element of the return value) can have the
     values:

    `0'
          if no problems were encountered;

    `1'
          if too many sub-intervals were done;

    `2'
          if excessive roundoff error is detected;

    `3'
          if extremely bad integrand behavior occurs;

    `6'
          if the input is invalid.


     Examples:

          (%i1) quad_qag (x^(1/2)*log(1/x), x, 0, 1, 3, 'epsrel=5d-8);
          (%o1)    [.4444444444492108, 3.1700968502883E-9, 961, 0]
          (%i2) integrate (x^(1/2)*log(1/x), x, 0, 1);
                                          4
          (%o2)                           -
                                          9


 -- Function: quad_qags (<f(x)>, <x>, <a>, <b>, [<epsrel>, <epsabs>,
          <limit>])
 -- Function: quad_qags (<f>, <x>, <a>, <b>, [<epsrel>, <epsabs>,
          <limit>])
     Integration of a general function over a finite interval.
     `quad_qags' implements globally adaptive interval subdivision with
     extrapolation (de Doncker, 1978) by the Epsilon algorithm (Wynn,
     1956).

     `quad_qags' computes the integral

     integrate (f(x), x, a, b)

     The function to be integrated is <f(x)>, with dependent variable
     <x>, and the function is to be integrated between the limits <a>
     and <b>.

     The integrand may be specified as the name of a Maxima or Lisp
     function or operator, a Maxima lambda expression, or a general
     Maxima expression.

     The keyword arguments are optional and may be specified in any
     order.  They all take the form `key=val'.  The keyword arguments
     are:

    `epsrel'
          Desired relative error of approximation.  Default is 1d-8.

    `epsabs'
          Desired absolute error of approximation.  Default is 0.

    `limit'
          Size of internal work array.  <limit> is the maximum number
          of subintervals to use.  Default is 200.

     `quad_qags' returns a list of four elements:

        * an approximation to the integral,

        * the estimated absolute error of the approximation,

        * the number integrand evaluations,

        * an error code.

     The error code (fourth element of the return value) can have the
     values:

    `0'
          no problems were encountered;

    `1'
          too many sub-intervals were done;

    `2'
          excessive roundoff error is detected;

    `3'
          extremely bad integrand behavior occurs;

    `4'
          failed to converge

    `5'
          integral is probably divergent or slowly convergent

    `6'
          if the input is invalid.

     Examples:

          (%i1) quad_qags (x^(1/2)*log(1/x), x, 0, 1, 'epsrel=1d-10);
          (%o1)   [.4444444444444448, 1.11022302462516E-15, 315, 0]

     Note that `quad_qags' is more accurate and efficient than
     `quad_qag' for this integrand.


 -- Function: quad_qagi (<f(x)>, <x>, <a>, <b>, [<epsrel>, <epsabs>,
          <limit>])
 -- Function: quad_qagi (<f>, <x>, <a>, <b>, [<epsrel>, <epsabs>,
          <limit>])
     Integration of a general function over an infinite or
     semi-infinite interval.  The interval is mapped onto a finite
     interval and then the same strategy as in `quad_qags' is applied.

     `quad_qagi' evaluates one of the following integrals

     integrate (f(x), x, a, inf)

     integrate (f(x), x, minf, a)

     integrate (f(x), x, minf, inf)

     using the Quadpack QAGI routine.  The function to be integrated is
     <f(x)>, with dependent variable <x>, and the function is to be
     integrated over an infinite range.

     The integrand may be specified as the name of a Maxima or Lisp
     function or operator, a Maxima lambda expression, or a general
     Maxima expression.

     One of the limits of integration must be infinity.  If not, then
     `quad_qagi' will just return the noun form.

     The keyword arguments are optional and may be specified in any
     order.  They all take the form `key=val'.  The keyword arguments
     are:

    `epsrel'
          Desired relative error of approximation.  Default is 1d-8.

    `epsabs'
          Desired absolute error of approximation.  Default is 0.

    `limit'
          Size of internal work array.  <limit> is the maximum number
          of subintervals to use.  Default is 200.

     `quad_qagi' returns a list of four elements:

        * an approximation to the integral,

        * the estimated absolute error of the approximation,

        * the number integrand evaluations,

        * an error code.

     The error code (fourth element of the return value) can have the
     values:

    `0'
          no problems were encountered;

    `1'
          too many sub-intervals were done;

    `2'
          excessive roundoff error is detected;

    `3'
          extremely bad integrand behavior occurs;

    `4'
          failed to converge

    `5'
          integral is probably divergent or slowly convergent

    `6'
          if the input is invalid.


     Examples:

          (%i1) quad_qagi (x^2*exp(-4*x), x, 0, inf, 'epsrel=1d-8);
          (%o1)        [0.03125, 2.95916102995002E-11, 105, 0]
          (%i2) integrate (x^2*exp(-4*x), x, 0, inf);
                                         1
          (%o2)                          --
                                         32


 -- Function: quad_qawc (<f(x)>, <x>, <c>, <a>, <b>, [<epsrel>,
          <epsabs>, <limit>])
 -- Function: quad_qawc (<f>, <x>, <c>, <a>, <b>, [<epsrel>, <epsabs>,
          <limit>])
     Computes the Cauchy principal value of f(x)/(x - c) over a finite
     interval.  The strategy is globally adaptive, and modified
     Clenshaw-Curtis integration is used on the subranges which contain
     the point x = c.

     `quad_qawc' computes the Cauchy principal value of

     integrate (f(x)/(x - c), x, a, b)

     using the Quadpack QAWC routine.  The function to be integrated is
     `<f(x)>/(<x> - <c>)', with dependent variable <x>, and the
     function is to be integrated over the interval <a> to <b>.

     The integrand may be specified as the name of a Maxima or Lisp
     function or operator, a Maxima lambda expression, or a general
     Maxima expression.

     The keyword arguments are optional and may be specified in any
     order.  They all take the form `key=val'.  The keyword arguments
     are:

    `epsrel'
          Desired relative error of approximation.  Default is 1d-8.

    `epsabs'
          Desired absolute error of approximation.  Default is 0.

    `limit'
          Size of internal work array.  <limit> is the maximum number
          of subintervals to use.  Default is 200.

     `quad_qawc' returns a list of four elements:

        * an approximation to the integral,

        * the estimated absolute error of the approximation,

        * the number integrand evaluations,

        * an error code.

     The error code (fourth element of the return value) can have the
     values:

    `0'
          no problems were encountered;

    `1'
          too many sub-intervals were done;

    `2'
          excessive roundoff error is detected;

    `3'
          extremely bad integrand behavior occurs;

    `6'
          if the input is invalid.


     Examples:

          (%i1) quad_qawc (2^(-5)*((x-1)^2+4^(-5))^(-1), x, 2, 0, 5,
                           'epsrel=1d-7);
          (%o1)    [- 3.130120337415925, 1.306830140249558E-8, 495, 0]
          (%i2) integrate (2^(-alpha)*(((x-1)^2 + 4^(-alpha))*(x-2))^(-1),
                x, 0, 5);
          Principal Value
                                 alpha
                  alpha       9 4                 9
                 4      log(------------- + -------------)
                                alpha           alpha
                            64 4      + 4   64 4      + 4
          (%o2) (-----------------------------------------
                                  alpha
                               2 4      + 2

                 3 alpha                       3 alpha
                 -------                       -------
                    2            alpha/2          2          alpha/2
              2 4        atan(4 4       )   2 4        atan(4       )   alpha
            - --------------------------- - -------------------------)/2
                        alpha                        alpha
                     2 4      + 2                 2 4      + 2
          (%i3) ev (%, alpha=5, numer);
          (%o3)                    - 3.130120337415917


 -- Function: quad_qawf (<f(x)>, <x>, <a>, <omega>, <trig>, [<epsabs>,
          <limit>, <maxp1>, <limlst>])
 -- Function: quad_qawf (<f>, <x>, <a>, <omega>, <trig>, [<epsabs>,
          <limit>, <maxp1>, <limlst>])
     Calculates a Fourier cosine or Fourier sine transform on a
     semi-infinite interval using the Quadpack QAWF function.  The same
     approach as in `quad_qawo' is applied on successive finite
     intervals, and convergence acceleration by means of the Epsilon
     algorithm (Wynn, 1956) is applied to the series of the integral
     contributions.

     `quad_qawf' computes the integral

     integrate (f(x)*w(x), x, a, inf)

     The weight function w is selected by <trig>:

    `cos'
          w(x) = cos (omega x)

    `sin'
          w(x) = sin (omega x)

     The integrand may be specified as the name of a Maxima or Lisp
     function or operator, a Maxima lambda expression, or a general
     Maxima expression.

     The keyword arguments are optional and may be specified in any
     order.  They all take the form `key=val'.  The keyword arguments
     are:

    `epsabs'
          Desired absolute error of approximation.  Default is 1d-10.

    `limit'
          Size of internal work array.  (<limit> - <limlst>)/2 is the
          maximum number of subintervals to use.  Default is 200.

    `maxp1'
          Maximum number of Chebyshev moments.  Must be greater than 0.
          Default is 100.

    `limlst'
          Upper bound on the number of cycles.  Must be greater than or
          equal to 3.  Default is 10.

     `quad_qawf' returns a list of four elements:

        * an approximation to the integral,

        * the estimated absolute error of the approximation,

        * the number integrand evaluations,

        * an error code.

     The error code (fourth element of the return value) can have the
     values:

    `0'
          no problems were encountered;

    `1'
          too many sub-intervals were done;

    `2'
          excessive roundoff error is detected;

    `3'
          extremely bad integrand behavior occurs;

    `6'
          if the input is invalid.


     Examples:

          (%i1) quad_qawf (exp(-x^2), x, 0, 1, 'cos, 'epsabs=1d-9);
          (%o1)   [.6901942235215714, 2.84846300257552E-11, 215, 0]
          (%i2) integrate (exp(-x^2)*cos(x), x, 0, inf);
                                    - 1/4
                                  %e      sqrt(%pi)
          (%o2)                   -----------------
                                          2
          (%i3) ev (%, numer);
          (%o3)                   .6901942235215714


 -- Function: quad_qawo (<f(x)>, <x>, <a>, <b>, <omega>, <trig>,
          [<epsrel>, <epsabs>, <limit>, <maxp1>, <limlst>])
 -- Function: quad_qawo (<f>, <x>, <a>, <b>, <omega>, <trig>,
          [<epsrel>, <epsabs>, <limit>, <maxp1>, <limlst>])
     Integration of cos (omega x) f(x) or sin (omega x) f(x) over a
     finite interval, where omega is a constant.  The rule evaluation
     component is based on the modified Clenshaw-Curtis technique.
     `quad_qawo' applies adaptive subdivision with extrapolation,
     similar to `quad_qags'.

     `quad_qawo' computes the integral using the Quadpack QAWO routine:

     integrate (f(x)*w(x), x, a, b)

     The weight function w is selected by <trig>:

    `cos'
          w(x) = cos (omega x)

    `sin'
          w(x) = sin (omega x)

     The integrand may be specified as the name of a Maxima or Lisp
     function or operator, a Maxima lambda expression, or a general
     Maxima expression.

     The keyword arguments are optional and may be specified in any
     order.  They all take the form `key=val'.  The keyword arguments
     are:

    `epsrel'
          Desired relative error of approximation.  Default is 1d-8.

    `epsabs'
          Desired absolute error of approximation.  Default is 0.

    `limit'
          Size of internal work array.  <limit>/2 is the maximum number
          of subintervals to use.  Default is 200.

    `maxp1'
          Maximum number of Chebyshev moments.  Must be greater than 0.
          Default is 100.

    `limlst'
          Upper bound on the number of cycles.  Must be greater than or
          equal to 3.  Default is 10.

     `quad_qawo' returns a list of four elements:

        * an approximation to the integral,

        * the estimated absolute error of the approximation,

        * the number integrand evaluations,

        * an error code.

     The error code (fourth element of the return value) can have the
     values:

    `0'
          no problems were encountered;

    `1'
          too many sub-intervals were done;

    `2'
          excessive roundoff error is detected;

    `3'
          extremely bad integrand behavior occurs;

    `6'
          if the input is invalid.


     Examples:

          (%i1) quad_qawo (x^(-1/2)*exp(-2^(-2)*x), x, 1d-8, 20*2^2, 1, cos);
          (%o1)     [1.376043389877692, 4.72710759424899E-11, 765, 0]
          (%i2) rectform (integrate (x^(-1/2)*exp(-2^(-alpha)*x) * cos(x),
                x, 0, inf));
                             alpha/2 - 1/2            2 alpha
                  sqrt(%pi) 2              sqrt(sqrt(2        + 1) + 1)
          (%o2)   -----------------------------------------------------
                                         2 alpha
                                   sqrt(2        + 1)
          (%i3) ev (%, alpha=2, numer);
          (%o3)                     1.376043390090716


 -- Function: quad_qaws (<f(x)>, <x>, <a>, <b>, <alpha>, <beta>,
          <wfun>, [<epsrel>, <epsabs>, <limit>])
 -- Function: quad_qaws (<f>, <x>, <a>, <b>, <alpha>, <beta>, <wfun>,
          [<epsrel>, <epsabs>, <limit>])
     Integration of w(x) f(x) over a finite interval, where w(x) is a
     certain algebraic or logarithmic function.  A globally adaptive
     subdivision strategy is applied, with modified Clenshaw-Curtis
     integration on the subintervals which contain the endpoints of the
     interval of integration.

     `quad_qaws' computes the integral using the Quadpack QAWS routine:

     integrate (f(x)*w(x), x, a, b)

     The weight function w is selected by <wfun>:

    `1'
          w(x) = (x - a)^alpha (b - x)^beta

    `2'
          w(x) = (x - a)^alpha (b - x)^beta log(x - a)

    `3'
          w(x) = (x - a)^alpha (b - x)^beta log(b - x)

    `4'
          w(x) = (x - a)^alpha (b - x)^beta log(x - a) log(b - x)

     The integrand may be specified as the name of a Maxima or Lisp
     function or operator, a Maxima lambda expression, or a general
     Maxima expression.

     The keyword arguments are optional and may be specified in any
     order.  They all take the form `key=val'.  The keyword arguments
     are:

    `epsrel'
          Desired relative error of approximation.  Default is 1d-8.

    `epsabs'
          Desired absolute error of approximation.  Default is 0.

    `limit'
          Size of internal work array.  <limit>is the maximum number of
          subintervals to use.  Default is 200.

     `quad_qaws' returns a list of four elements:

        * an approximation to the integral,

        * the estimated absolute error of the approximation,

        * the number integrand evaluations,

        * an error code.

     The error code (fourth element of the return value) can have the
     values:

    `0'
          no problems were encountered;

    `1'
          too many sub-intervals were done;

    `2'
          excessive roundoff error is detected;

    `3'
          extremely bad integrand behavior occurs;

    `6'
          if the input is invalid.


     Examples:

          (%i1) quad_qaws (1/(x+1+2^(-4)), x, -1, 1, -0.5, -0.5, 1,
                           'epsabs=1d-9);
          (%o1)     [8.750097361672832, 1.24321522715422E-10, 170, 0]
          (%i2) integrate ((1-x*x)^(-1/2)/(x+1+2^(-alpha)), x, -1, 1);
                 alpha
          Is  4 2      - 1  positive, negative, or zero?

          pos;
                                    alpha         alpha
                             2 %pi 2      sqrt(2 2      + 1)
          (%o2)              -------------------------------
                                         alpha
                                      4 2      + 2
          (%i3) ev (%, alpha=4, numer);
          (%o3)                     8.750097361672829


 -- Function: quad_qagp (<f(x)>, <x>, <a>, <b>, <points>, [<epsrel>,
          <epsabs>, <limit>])
 -- Function: quad_qagp (<f>, <x>, <a>, <b>, <points>, [<epsrel>,
          <epsabs>, <limit>])
     Integration of a general function over a finite interval.
     `quad_qagp' implements globally adaptive interval subdivision with
     extrapolation (de Doncker, 1978) by the Epsilon algorithm (Wynn,
     1956).

     `quad_qagp' computes the integral

     integrate (f(x), x, a, b)

     The function to be integrated is <f(x)>, with dependent variable
     <x>, and the function is to be integrated between the limits <a>
     and <b>.

     The integrand may be specified as the name of a Maxima or Lisp
     function or operator, a Maxima lambda expression, or a general
     Maxima expression.

     To help the integrator, the user must supply a list of points where
     the integrand is singular or discontinous.

     The keyword arguments are optional and may be specified in any
     order.  They all take the form `key=val'.  The keyword arguments
     are:

    `epsrel'
          Desired relative error of approximation.  Default is 1d-8.

    `epsabs'
          Desired absolute error of approximation.  Default is 0.

    `limit'
          Size of internal work array.  <limit> is the maximum number
          of subintervals to use.  Default is 200.

     `quad_qagp' returns a list of four elements:

        * an approximation to the integral,

        * the estimated absolute error of the approximation,

        * the number integrand evaluations,

        * an error code.

     The error code (fourth element of the return value) can have the
     values:

    `0'
          no problems were encountered;

    `1'
          too many sub-intervals were done;

    `2'
          excessive roundoff error is detected;

    `3'
          extremely bad integrand behavior occurs;

    `4'
          failed to converge

    `5'
          integral is probably divergent or slowly convergent

    `6'
          if the input is invalid.

     Examples:

          (%i1) quad_qagp(x^3*log(abs((x^2-1)*(x^2-2))),x,0,3,[1,sqrt(2)]);
          (%o1)   [52.74074838347143, 2.6247632689546663e-7, 1029, 0]
          (%i2) quad_qags(x^3*log(abs((x^2-1)*(x^2-2))), x, 0, 3);
          (%o2)   [52.74074847951494, 4.088443219529836e-7, 1869, 0]

     The integrand has singularities at `1' and `sqrt(2)' so we supply
     these points to `quad_qagp'.  We also note that `quad_qagp' is
     more accurate and more efficient that `quad_qags'.


 -- Function: quad_control (<parameter>, [<value>])
     Control error handling for quadpack.  The parameter should be one
     of the following symbols:

    `current_error'
          The current error number

    `control'
          Controls if messages are printed or not.  If it is set to
          zero or less, messages are suppressed.

    `max_message'
          The maximum number of times any message is to be printed.

     If <value> is not given, then the current value of the <parameter>
     is returned.  If <value> is given, the value of <parameter> is set
     to the given value.



File: maxima.info,  Node: Equations,  Next: Differential Equations,  Prev: Integration,  Up: Top

20 Equations
************

* Menu:

* Functions and Variables for Equations::


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

20.1 Functions and Variables for Equations
==========================================

 -- System variable: %rnum_list
     Default value: `[]'

     `%rnum_list' is the list of variables introduced in solutions by
     `solve' and `algsys'.  `%r' variables are added to `%rnum_list' in
     the order they are created.  This is convenient for doing
     substitutions into the solution later on.  It's recommended to use
     this list rather than doing `concat ('%r, j)'.

          (%i1) solve ([x + y = 3], [x,y]);
          (%o1)              [[x = 3 - %r1, y = %r1]]
          (%i2) %rnum_list;
          (%o2)                       [%r1]
          (%i3) sol : solve ([x + 2*y + 3*z = 4], [x,y,z]);
          (%o3)   [[x = - 2 %r3 - 3 %r2 + 4, y = %r3, z = %r2]]
          (%i4) %rnum_list;
          (%o4)                     [%r2, %r3]
          (%i5) for i : 1 thru length (%rnum_list) do
                  sol : subst (t[i], %rnum_list[i], sol)$
          (%i6) sol;
          (%o6)     [[x = - 2 t  - 3 t  + 4, y = t , z = t ]]
                               2      1           2       1


 -- Option variable: algepsilon
     Default value: 10^8

     `algepsilon' is used by `algsys'.


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

     `algexact' affects the behavior of `algsys' as follows:

     If `algexact' is `true', `algsys' always calls `solve' and then
     uses `realroots' on `solve''s failures.

     If `algexact' is `false', `solve' is called only if the eliminant
     was not univariate, or if it was a quadratic or biquadratic.

     Thus `algexact: true' does not guarantee only exact solutions,
     just that `algsys' will first try as hard as it can to give exact
     solutions, and only yield approximations when all else fails.


 -- Function: algsys ([<expr_1>, ..., <expr_m>], [<x_1>, ..., <x_n>])
 -- Function: algsys ([<eqn_1>, ..., <eqn_m>], [<x_1>, ..., <x_n>])
     Solves the simultaneous polynomials <expr_1>, ..., <expr_m> or
     polynomial equations <eqn_1>, ..., <eqn_m> for the variables
     <x_1>, ..., <x_n>.  An expression <expr> is equivalent to an
     equation `<expr> = 0'.  There may be more equations than variables
     or vice versa.

     `algsys' returns a list of solutions, with each solution given as
     a list of equations stating values of the variables <x_1>, ...,
     <x_n> which satisfy the system of equations.  If `algsys' cannot
     find a solution, an empty list `[]' is returned.

     The symbols `%r1', `%r2', ..., are introduced as needed to
     represent arbitrary parameters in the solution; these variables
     are also appended to the list `%rnum_list'.

     The method is as follows:

       1. First the equations are factored and split into subsystems.

       2. For each subsystem <S_i>, an equation <E> and a variable <x>
          are selected.  The variable is chosen to have lowest nonzero
          degree.  Then the resultant of <E> and <E_j> with respect to
          <x> is computed for each of the remaining equations <E_j> in
          the subsystem <S_i>.  This yields a new subsystem <S_i'> in
          one fewer variables, as <x> has been eliminated.  The process
          now returns to (1).

       3. Eventually, a subsystem consisting of a single equation is
          obtained.  If the equation is multivariate and no
          approximations in the form of floating point numbers have
          been introduced, then `solve' is called to find an exact
          solution.

          In some cases, `solve' is not be able to find a solution, or
          if it does the solution may be a very large expression.

          If the equation is univariate and is either linear,
          quadratic, or biquadratic, then again `solve' is called if no
          approximations have been introduced.  If approximations have
          been introduced or the equation is not univariate and neither
          linear, quadratic, or biquadratic, then if the switch
          `realonly' is `true', the function `realroots' is called to
          find the real-valued solutions.  If `realonly' is `false',
          then `allroots' is called which looks for real and
          complex-valued solutions.

          If `algsys' produces a solution which has fewer significant
          digits than required, the user can change the value of
          `algepsilon' to a higher value.

          If `algexact' is set to `true', `solve' will always be called.

       4. Finally, the solutions obtained in step (3) are substituted
          into previous levels and the solution process returns to (1).

     When `algsys' encounters a multivariate equation which contains
     floating point approximations (usually due to its failing to find
     exact solutions at an earlier stage), then it does not attempt to
     apply exact methods to such equations and instead prints the
     message: "`algsys' cannot solve - system too complicated."

     Interactions with `radcan' can produce large or complicated
     expressions.  In that case, it may be possible to isolate parts of
     the result with `pickapart' or `reveal'.

     Occasionally, `radcan' may introduce an imaginary unit `%i' into a
     solution which is actually real-valued.

     Examples:

          (%i1) e1: 2*x*(1 - a1) - 2*(x - 1)*a2;
          (%o1)              2 (1 - a1) x - 2 a2 (x - 1)
          (%i2) e2: a2 - a1;
          (%o2)                        a2 - a1
          (%i3) e3: a1*(-y - x^2 + 1);
                                             2
          (%o3)                   a1 (- y - x  + 1)
          (%i4) e4: a2*(y - (x - 1)^2);
                                                 2
          (%o4)                   a2 (y - (x - 1) )
          (%i5) algsys ([e1, e2, e3, e4], [x, y, a1, a2]);
          (%o5) [[x = 0, y = %r1, a1 = 0, a2 = 0],

                                            [x = 1, y = 0, a1 = 1, a2 = 1]]
          (%i6) e1: x^2 - y^2;
                                        2    2
          (%o6)                        x  - y
          (%i7) e2: -1 - y + 2*y^2 - x + x^2;
                                   2        2
          (%o7)                 2 y  - y + x  - x - 1
          (%i8) algsys ([e1, e2], [x, y]);
                           1            1
          (%o8) [[x = - -------, y = -------],
                        sqrt(3)      sqrt(3)

                  1              1             1        1
          [x = -------, y = - -------], [x = - -, y = - -], [x = 1, y = 1]]
               sqrt(3)        sqrt(3)          3        3


 -- Function: allroots (<expr>)
 -- Function: allroots (<eqn>)
     Computes numerical approximations of the real and complex roots of
     the polynomial <expr> or polynomial equation <eqn> of one variable.

     The flag `polyfactor' when `true' causes `allroots' to factor the
     polynomial over the real numbers if the polynomial is real, or
     over the complex numbers, if the polynomial is complex.

     `allroots' may give inaccurate results in case of multiple roots.
     If the polynomial is real, `allroots (%i*<p>)' may yield more
     accurate approximations than `allroots (<p>)', as `allroots'
     invokes a different algorithm in that case.

     `allroots' rejects non-polynomials.  It requires that the numerator
     after `rat''ing should be a polynomial, and it requires that the
     denominator be at most a complex number.  As a result of this
     `allroots' will always return an equivalent (but factored)
     expression, if `polyfactor' is `true'.

     For complex polynomials an algorithm by Jenkins and Traub is used
     (Algorithm 419, Comm. ACM, vol. 15, (1972), p. 97).  For real
     polynomials the algorithm used is due to Jenkins (Algorithm 493,
     ACM TOMS, vol. 1, (1975), p.178).

     Examples:

          (%i1) eqn: (1 + 2*x)^3 = 13.5*(1 + x^5);
                                      3          5
          (%o1)              (2 x + 1)  = 13.5 (x  + 1)
          (%i2) soln: allroots (eqn);
          (%o2) [x = .8296749902129361, x = - 1.015755543828121,

          x = .9659625152196369 %i - .4069597231924075,

          x = - .9659625152196369 %i - .4069597231924075, x = 1.0]
          (%i3) for e in soln
                  do (e2: subst (e, eqn), disp (expand (lhs(e2) - rhs(e2))));
                                - 3.5527136788005E-15

                               - 5.32907051820075E-15

                   4.44089209850063E-15 %i - 4.88498130835069E-15

                  - 4.44089209850063E-15 %i - 4.88498130835069E-15

                                 3.5527136788005E-15

          (%o3)                         done
          (%i4) polyfactor: true$
          (%i5) allroots (eqn);
          (%o5) - 13.5 (x - 1.0) (x - .8296749902129361)

                                     2
           (x + 1.015755543828121) (x  + .8139194463848151 x

           + 1.098699797110288)


 -- Function: bfallroots (<expr>)
 -- Function: bfallroots (<eqn>)
     Computes numerical approximations of the real and complex roots of
     the polynomial <expr> or polynomial equation <eqn> of one variable.

     In all respects, `bfallroots' is identical to `allroots' except
     that `bfallroots' computes the roots using bigfloats.  See
     `allroots' for more information.


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

     When `backsubst' is `false', prevents back substitution in
     `linsolve' after the equations have been triangularized.  This may
     be helpful in very big problems where back substitution would cause
     the generation of extremely large expressions.

          (%i1) eq1 : x + y + z = 6$
          (%i2) eq2 : x - y + z = 2$
          (%i3) eq3 : x + y - z = 0$
          (%i4) backsubst : false$
          (%i5) linsolve ([eq1, eq2, eq3], [x,y,z]);
          (%o5)             [x = z - y, y = 2, z = 3]
          (%i6) backsubst : true$
          (%i7) linsolve ([eq1, eq2, eq3], [x,y,z]);
          (%o7)               [x = 1, y = 2, z = 3]


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

     When `breakup' is `true', `solve' expresses solutions of cubic and
     quartic equations in terms of common subexpressions, which are
     assigned to intermediate expression labels (`%t1', `%t2', etc.).
     Otherwise, common subexpressions are not identified.

     `breakup: true' has an effect only when `programmode' is `false'.

     Examples:

          (%i1) programmode: false$
          (%i2) breakup: true$
          (%i3) solve (x^3 + x^2 - 1);

                                  sqrt(23)    25 1/3
          (%t3)                  (--------- + --)
                                  6 sqrt(3)   54
          Solution:

                                                sqrt(3) %i   1
                                                ---------- - -
                          sqrt(3) %i   1            2        2   1
          (%t4)    x = (- ---------- - -) %t3 + -------------- - -
                              2        2            9 %t3        3

                                                sqrt(3) %i   1
                                              - ---------- - -
                        sqrt(3) %i   1              2        2   1
          (%t5)    x = (---------- - -) %t3 + ---------------- - -
                            2        2             9 %t3         3

                                             1     1
          (%t6)                  x = %t3 + ----- - -
                                           9 %t3   3
          (%o6)                    [%t4, %t5, %t6]
          (%i6) breakup: false$
          (%i7) solve (x^3 + x^2 - 1);
          Solution:

                       sqrt(3) %i   1
                       ---------- - -
                           2        2        sqrt(23)    25 1/3
          (%t7) x = --------------------- + (--------- + --)
                       sqrt(23)    25 1/3    6 sqrt(3)   54
                    9 (--------- + --)
                       6 sqrt(3)   54

                                                        sqrt(3) %i   1    1
                                                     (- ---------- - -) - -
                                                            2        2    3
                     sqrt(23)    25 1/3  sqrt(3) %i   1
          (%t8) x = (--------- + --)    (---------- - -)
                     6 sqrt(3)   54          2        2

                                                      sqrt(3) %i   1
                                                    - ---------- - -
                                                          2        2      1
                                                + --------------------- - -
                                                     sqrt(23)    25 1/3   3
                                                  9 (--------- + --)
                                                     6 sqrt(3)   54
                      sqrt(23)    25 1/3             1             1
          (%t9)  x = (--------- + --)    + --------------------- - -
                      6 sqrt(3)   54          sqrt(23)    25 1/3   3
                                           9 (--------- + --)
                                              6 sqrt(3)   54
          (%o9)                    [%t7, %t8, %t9]


 -- Function: dimension (<eqn>)
 -- Function: dimension (<eqn_1>, ..., <eqn_n>)
     `dimen' is a package for dimensional analysis.  `load ("dimen")'
     loads this package.  `demo ("dimen")' displays a short
     demonstration.


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

     If set to `false' within a `block' will inhibit the display of
     output generated by the solve functions called from within the
     `block'.  Termination of the `block' with a dollar sign, $, sets
     `dispflag' to `false'.


 -- Function: funcsolve (<eqn>, <g>(<t>))
     Returns `[<g>(<t>) = ...]'  or `[]', depending on whether or not
     there exists a rational function `<g>(<t>)' satisfying <eqn>,
     which must be a first order, linear polynomial in (for this case)
     `<g>(<t>)' and `<g>(<t>+1)'

          (%i1) eqn: (n + 1)*f(n) - (n + 3)*f(n + 1)/(n + 1) =
                (n - 1)/(n + 2);
                                      (n + 3) f(n + 1)   n - 1
          (%o1)        (n + 1) f(n) - ---------------- = -----
                                           n + 1         n + 2
          (%i2) funcsolve (eqn, f(n));

          Dependent equations eliminated:  (4 3)
                                             n
          (%o2)                f(n) = ---------------
                                      (n + 1) (n + 2)

     Warning: this is a very rudimentary implementation - many safety
     checks and obvious generalizations are missing.


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

     When `globalsolve' is `true', solved-for variables are assigned the
     solution values found by `linsolve', and by `solve' when solving
     two or more linear equations.

     When `globalsolve' is `false', solutions found by `linsolve' and
     by `solve' when solving two or more linear equations are expressed
     as equations, and the solved-for variables are not assigned.

     When solving anything other than two or more linear equations,
     `solve' ignores `globalsolve'.  Other functions which solve
     equations (e.g., `algsys') always ignore `globalsolve'.

     Examples:

          (%i1) globalsolve: true$
          (%i2) solve ([x + 3*y = 2, 2*x - y = 5], [x, y]);
          Solution

                                           17
          (%t2)                        x : --
                                           7

                                             1
          (%t3)                        y : - -
                                             7
          (%o3)                     [[%t2, %t3]]
          (%i3) x;
                                         17
          (%o3)                          --
                                         7
          (%i4) y;
                                           1
          (%o4)                          - -
                                           7
          (%i5) globalsolve: false$
          (%i6) kill (x, y)$
          (%i7) solve ([x + 3*y = 2, 2*x - y = 5], [x, y]);
          Solution

                                           17
          (%t7)                        x = --
                                           7

                                             1
          (%t8)                        y = - -
                                             7
          (%o8)                     [[%t7, %t8]]
          (%i8) x;
          (%o8)                           x
          (%i9) y;
          (%o9)                           y


 -- Function: ieqn (<ie>, <unk>, <tech>, <n>, <guess>)
     `inteqn' is a package for solving integral equations.  `load
     ("inteqn")' loads this package.

     <ie> is the integral equation; <unk> is the unknown function;
     <tech> is the technique to be tried from those given above (<tech>
     = `first' means: try the first technique which finds a solution;
     <tech> = `all' means: try all applicable techniques); <n> is the
     maximum number of terms to take for `taylor', `neumann',
     `firstkindseries', or `fredseries' (it is also the maximum depth
     of recursion for the differentiation method); <guess> is the
     initial guess for `neumann' or `firstkindseries'.

     Default values for the 2nd thru 5th parameters are:

     <unk>: `<p>(<x>)', where <p> is the first function encountered in
     an integrand which is unknown to Maxima and <x> is the variable
     which occurs as an argument to the first occurrence of <p> found
     outside of an integral in the case of `secondkind' equations, or
     is the only other variable besides the variable of integration in
     `firstkind' equations.  If the attempt to search for <x> fails,
     the user will be asked to supply the independent variable.

     tech: `first'

     n: 1

     guess: `none' which will cause `neumann' and `firstkindseries' to
     use `<f>(<x>)' as an initial guess.


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

     `ieqnprint' governs the behavior of the result returned by the
     `ieqn' command.  When `ieqnprint' is `false', the lists returned
     by the `ieqn' function are of the form

     [<solution>, <technique used>, <nterms>, <flag>]

     where <flag> is absent if the solution is exact.

     Otherwise, it is the word `approximate' or `incomplete'
     corresponding to an inexact or non-closed form solution,
     respectively.  If a series method was used, <nterms> gives the
     number of terms taken (which could be less than the n given to
     `ieqn' if an error prevented generation of further terms).


 -- Function: lhs (<expr>)
     Returns the left-hand side (that is, the first argument) of the
     expression <expr>, when the operator of <expr> is one of the
     relational operators `< <= = # equal notequal >= >', one of the
     assignment operators `:= ::= : ::', or a user-defined binary infix
     operator, as declared by `infix'.

     When <expr> is an atom or its operator is something other than the
     ones listed above, `lhs' returns <expr>.

     See also `rhs'.

     Examples:

          (%i1) e: aa + bb = cc;
          (%o1)                     bb + aa = cc
          (%i2) lhs (e);
          (%o2)                        bb + aa
          (%i3) rhs (e);
          (%o3)                          cc
          (%i4) [lhs (aa < bb), lhs (aa <= bb), lhs (aa >= bb),
                 lhs (aa > bb)];
          (%o4)                   [aa, aa, aa, aa]
          (%i5) [lhs (aa = bb), lhs (aa # bb), lhs (equal (aa, bb)),
                 lhs (notequal (aa, bb))];
          (%o5)                   [aa, aa, aa, aa]
          (%i6) e1: '(foo(x) := 2*x);
          (%o6)                     foo(x) := 2 x
          (%i7) e2: '(bar(y) ::= 3*y);
          (%o7)                    bar(y) ::= 3 y
          (%i8) e3: '(x : y);
          (%o8)                         x : y
          (%i9) e4: '(x :: y);
          (%o9)                        x :: y
          (%i10) [lhs (e1), lhs (e2), lhs (e3), lhs (e4)];
          (%o10)               [foo(x), bar(y), x, x]
          (%i11) infix ("][");
          (%o11)                         ][
          (%i12) lhs (aa ][ bb);
          (%o12)                         aa


 -- Function: linsolve ([<expr_1>, ..., <expr_m>], [<x_1>, ..., <x_n>])
     Solves the list of simultaneous linear equations for the list of
     variables.  The expressions must each be polynomials in the
     variables and may be equations.

     When `globalsolve' is `true', each solved-for variable is bound to
     its value in the solution of the equations.

     When `backsubst' is `false', `linsolve' does not carry out back
     substitution after the equations have been triangularized.  This
     may be necessary in very big problems where back substitution
     would cause the generation of extremely large expressions.

     When `linsolve_params' is `true', `linsolve' also generates the
     `%r' symbols used to represent arbitrary parameters described in
     the manual under `algsys'.  Otherwise, `linsolve' solves an
     under-determined system of equations with some variables expressed
     in terms of others.

     When `programmode' is `false', `linsolve' displays the solution
     with intermediate expression (`%t') labels, and returns the list
     of labels.

          (%i1) e1: x + z = y;
          (%o1)                       z + x = y
          (%i2) e2: 2*a*x - y = 2*a^2;
                                                 2
          (%o2)                   2 a x - y = 2 a
          (%i3) e3: y - 2*z = 2;
          (%o3)                      y - 2 z = 2
          (%i4) [globalsolve: false, programmode: true];
          (%o4)                     [false, true]
          (%i5) linsolve ([e1, e2, e3], [x, y, z]);
          (%o5)            [x = a + 1, y = 2 a, z = a - 1]
          (%i6) [globalsolve: false, programmode: false];
          (%o6)                    [false, false]
          (%i7) linsolve ([e1, e2, e3], [x, y, z]);
          Solution

          (%t7)                       z = a - 1

          (%t8)                        y = 2 a

          (%t9)                       x = a + 1
          (%o9)                    [%t7, %t8, %t9]
          (%i9) ''%;
          (%o9)            [z = a - 1, y = 2 a, x = a + 1]
          (%i10) [globalsolve: true, programmode: false];
          (%o10)                    [true, false]
          (%i11) linsolve ([e1, e2, e3], [x, y, z]);
          Solution

          (%t11)                      z : a - 1

          (%t12)                       y : 2 a

          (%t13)                      x : a + 1
          (%o13)                 [%t11, %t12, %t13]
          (%i13) ''%;
          (%o13)           [z : a - 1, y : 2 a, x : a + 1]
          (%i14) [x, y, z];
          (%o14)                 [a + 1, 2 a, a - 1]
          (%i15) [globalsolve: true, programmode: true];
          (%o15)                    [true, true]
          (%i16) linsolve ([e1, e2, e3], '[x, y, z]);
          (%o16)           [x : a + 1, y : 2 a, z : a - 1]
          (%i17) [x, y, z];
          (%o17)                 [a + 1, 2 a, a - 1]


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

     When `linsolvewarn' is `true', `linsolve' prints a message
     "Dependent equations eliminated".


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

     When `linsolve_params' is `true', `linsolve' also generates the
     `%r' symbols used to represent arbitrary parameters described in
     the manual under `algsys'.  Otherwise, `linsolve' solves an
     under-determined system of equations with some variables expressed
     in terms of others.


 -- System variable: multiplicities
     Default value: `not_set_yet'

     `multiplicities' is set to a list of the multiplicities of the
     individual solutions returned by `solve' or `realroots'.


 -- Function: nroots (<p>, <low>, <high>)
     Returns the number of real roots of the real univariate polynomial
     <p> in the half-open interval `(<low>, <high>]'.  The endpoints of
     the interval may be `minf' or `inf'.

     `nroots' uses the method of Sturm sequences.

          (%i1) p: x^10 - 2*x^4 + 1/2$
          (%i2) nroots (p, -6, 9.1);
          (%o2)                           4


 -- Function: nthroot (<p>, <n>)
     where <p> is a polynomial with integer coefficients and <n> is a
     positive integer returns `q', a polynomial over the integers, such
     that `q^n = p' or prints an error message indicating that <p> is
     not a perfect nth power.  This routine is much faster than
     `factor' or even `sqfr'.


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

     The option variable `polyfactor' when `true' causes `allroots' and
     `bfallroots' to factor the polynomial over the real numbers if the
     polynomial is real, or over the complex numbers, if the polynomial
     is complex.

     See `allroots' for an example.


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

     When `programmode' is `true', `solve', `realroots', `allroots',
     and `linsolve' return solutions as elements in a list.  (Except
     when `backsubst' is set to `false', in which case `programmode:
     false' is assumed.)

     When `programmode' is `false', `solve', etc. create intermediate
     expression labels `%t1', `t2', etc., and assign the solutions to
     them.


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

     When `realonly' is `true', `algsys' returns only those solutions
     which are free of `%i'.


 -- Function: realroots (<expr>, <bound>)
 -- Function: realroots (<eqn>, <bound>)
 -- Function: realroots (<expr>)
 -- Function: realroots (<eqn>)
     Computes rational approximations of the real roots of the
     polynomial <expr> or polynomial equation <eqn> of one variable, to
     within a tolerance of <bound>.  Coefficients of <expr> or <eqn>
     must be literal numbers; symbol constants such as `%pi' are
     rejected.

     `realroots' assigns the multiplicities of the roots it finds to
     the global variable `multiplicities'.

     `realroots' constructs a Sturm sequence to bracket each root, and
     then applies bisection to refine the approximations.  All
     coefficients are converted to rational equivalents before
     searching for roots, and computations are carried out by exact
     rational arithmetic.  Even if some coefficients are floating-point
     numbers, the results are rational (unless coerced to floats by the
     `float' or `numer' flags).

     When <bound> is less than 1, all integer roots are found exactly.
     When <bound> is unspecified, it is assumed equal to the global
     variable `rootsepsilon'.

     When the global variable `programmode' is `true', `realroots'
     returns a list of the form `[x = <x_1>, x = <x_2>, ...]'.  When
     `programmode' is `false', `realroots' creates intermediate
     expression labels `%t1', `%t2', ..., assigns the results to them,
     and returns the list of labels.

     Examples:

          (%i1) realroots (-1 - x + x^5, 5e-6);
                                         612003
          (%o1)                     [x = ------]
                                         524288
          (%i2) ev (%[1], float);
          (%o2)                 x = 1.167303085327148
          (%i3) ev (-1 - x + x^5, %);
          (%o3)                - 7.396496210176905E-6

          (%i1) realroots (expand ((1 - x)^5 * (2 - x)^3 * (3 - x)), 1e-20);
          (%o1)                 [x = 1, x = 2, x = 3]
          (%i2) multiplicities;
          (%o2)                       [5, 3, 1]


 -- Function: rhs (<expr>)
     Returns the right-hand side (that is, the second argument) of the
     expression <expr>, when the operator of <expr> is one of the
     relational operators `< <= = # equal notequal >= >', one of the
     assignment operators `:= ::= : ::', or a user-defined binary infix
     operator, as declared by `infix'.

     When <expr> is an atom or its operator is something other than the
     ones listed above, `rhs' returns 0.

     See also `lhs'.

     Examples:

          (%i1) e: aa + bb = cc;
          (%o1)                     bb + aa = cc
          (%i2) lhs (e);
          (%o2)                        bb + aa
          (%i3) rhs (e);
          (%o3)                          cc
          (%i4) [rhs (aa < bb), rhs (aa <= bb), rhs (aa >= bb),
                 rhs (aa > bb)];
          (%o4)                   [bb, bb, bb, bb]
          (%i5) [rhs (aa = bb), rhs (aa # bb), rhs (equal (aa, bb)),
                 rhs (notequal (aa, bb))];
          (%o5)                   [bb, bb, bb, bb]
          (%i6) e1: '(foo(x) := 2*x);
          (%o6)                     foo(x) := 2 x
          (%i7) e2: '(bar(y) ::= 3*y);
          (%o7)                    bar(y) ::= 3 y
          (%i8) e3: '(x : y);
          (%o8)                         x : y
          (%i9) e4: '(x :: y);
          (%o9)                        x :: y
          (%i10) [rhs (e1), rhs (e2), rhs (e3), rhs (e4)];
          (%o10)                  [2 x, 3 y, y, y]
          (%i11) infix ("][");
          (%o11)                         ][
          (%i12) rhs (aa ][ bb);
          (%o12)                         bb


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

     `rootsconmode' governs the behavior of the `rootscontract' command.
     See `rootscontract' for details.


 -- Function: rootscontract (<expr>)
     Converts products of roots into roots of products.  For example,
     `rootscontract (sqrt(x)*y^(3/2))' yields `sqrt(x*y^3)'.

     When `radexpand' is `true' and `domain' is `real', `rootscontract'
     converts `abs' into `sqrt', e.g., `rootscontract (abs(x)*sqrt(y))'
     yields `sqrt(x^2*y)'.

     There is an option `rootsconmode' affecting `rootscontract' as
     follows:

          Problem            Value of        Result of applying
                            rootsconmode        rootscontract

          x^(1/2)*y^(3/2)      false          (x*y^3)^(1/2)
          x^(1/2)*y^(1/4)      false          x^(1/2)*y^(1/4)
          x^(1/2)*y^(1/4)      true           (x*y^(1/2))^(1/2)
          x^(1/2)*y^(1/3)      true           x^(1/2)*y^(1/3)
          x^(1/2)*y^(1/4)      all            (x^2*y)^(1/4)
          x^(1/2)*y^(1/3)      all            (x^3*y^2)^(1/6)

     When `rootsconmode' is `false', `rootscontract' contracts only
     with respect to rational number exponents whose denominators are
     the same.  The key to the `rootsconmode: true' examples is simply
     that 2 divides into 4 but not into 3.  `rootsconmode: all'
     involves taking the least common multiple of the denominators of
     the exponents.

     `rootscontract' uses `ratsimp' in a manner similar to
     `logcontract'.

     Examples:

          (%i1) rootsconmode: false$
          (%i2) rootscontract (x^(1/2)*y^(3/2));
                                             3
          (%o2)                      sqrt(x y )
          (%i3) rootscontract (x^(1/2)*y^(1/4));
                                             1/4
          (%o3)                     sqrt(x) y
          (%i4) rootsconmode: true$
          (%i5) rootscontract (x^(1/2)*y^(1/4));
          (%o5)                    sqrt(x sqrt(y))
          (%i6) rootscontract (x^(1/2)*y^(1/3));
                                             1/3
          (%o6)                     sqrt(x) y
          (%i7) rootsconmode: all$
          (%i8) rootscontract (x^(1/2)*y^(1/4));
                                        2   1/4
          (%o8)                       (x  y)
          (%i9) rootscontract (x^(1/2)*y^(1/3));
                                       3  2 1/6
          (%o9)                      (x  y )
          (%i10) rootsconmode: false$
          (%i11) rootscontract (sqrt(sqrt(x) + sqrt(1 + x))
                              *sqrt(sqrt(1 + x) - sqrt(x)));
          (%o11)                          1
          (%i12) rootsconmode: true$
          (%i13) rootscontract (sqrt(5+sqrt(5)) - 5^(1/4)*sqrt(1+sqrt(5)));
          (%o13)                          0


 -- Option variable: rootsepsilon
     Default value: 1.0e-7

     `rootsepsilon' is the tolerance which establishes the confidence
     interval for the roots found by the `realroots' function.


 -- Function: solve (<expr>, <x>)
 -- Function: solve (<expr>)
 -- Function: solve ([<eqn_1>, ..., <eqn_n>], [<x_1>, ..., <x_n>])
     Solves the algebraic equation <expr> for the variable <x> and
     returns a list of solution equations in <x>.  If <expr> is not an
     equation, the equation `<expr> = 0' is assumed in its place.  <x>
     may be a function (e.g. `f(x)'), or other non-atomic expression
     except a sum or product.  <x> may be omitted if <expr> contains
     only one variable.  <expr> may be a rational expression, and may
     contain trigonometric functions, exponentials, etc.

     The following method is used:

     Let <E> be the expression and <X> be the variable.  If <E> is
     linear in <X> then it is trivially solved for <X>.  Otherwise if
     <E> is of the form `A*X^N + B' then the result is `(-B/A)^1/N)'
     times the `N''th roots of unity.

     If <E> is not linear in <X> then the gcd of the exponents of <X> in
     <E> (say <N>) is divided into the exponents and the multiplicity
     of the roots is multiplied by <N>.  Then `solve' is called again
     on the result.  If <E> factors then `solve' is called on each of
     the factors.  Finally `solve' will use the quadratic, cubic, or
     quartic formulas where necessary.

     In the case where <E> is a polynomial in some function of the
     variable to be solved for, say `F(X)', then it is first solved for
     `F(X)' (call the result <C>), then the equation `F(X)=C' can be
     solved for <X> provided the inverse of the function <F> is known.

     `breakup' if `false' will cause `solve' to express the solutions
     of cubic or quartic equations as single expressions rather than as
     made up of several common subexpressions which is the default.

     `multiplicities' - will be set to a list of the multiplicities of
     the individual solutions returned by `solve', `realroots', or
     `allroots'.  Try `apropos (solve)' for the switches which affect
     `solve'.  `describe' may then by used on the individual switch
     names if their purpose is not clear.

     `solve ([<eqn_1>, ..., <eqn_n>], [<x_1>, ..., <x_n>])' solves a
     system of simultaneous (linear or non-linear) polynomial equations
     by calling `linsolve' or `algsys' and returns a list of the
     solution lists in the variables.  In the case of `linsolve' this
     list would contain a single list of solutions.  It takes two lists
     as arguments.  The first list represents the equations to be
     solved; the second list is a list of the unknowns to be
     determined.  If the total number of variables in the equations is
     equal to the number of equations, the second argument-list may be
     omitted.

     When `programmode' is `false', `solve' displays solutions with
     intermediate expression (`%t') labels, and returns the list of
     labels.

     When `globalsolve' is `true' and the problem is to solve two or
     more linear equations, each solved-for variable is bound to its
     value in the solution of the equations.

     Examples:

          (%i1) solve (asin (cos (3*x))*(f(x) - 1), x);

          solve: using arc-trig functions to get a solution.
          Some solutions will be lost.
                                      %pi
          (%o1)                  [x = ---, f(x) = 1]
                                       6
          (%i2) ev (solve (5^f(x) = 125, f(x)), solveradcan);
                                          log(125)
          (%o2)                   [f(x) = --------]
                                           log(5)
          (%i3) [4*x^2 - y^2 = 12, x*y - x = 2];
                                2    2
          (%o3)             [4 x  - y  = 12, x y - x = 2]

          (%i4) solve (%, [x, y]);
          (%o4) [[x = 2, y = 2], [x = .5202594388652008 %i
           - .1331240357358706, y = .07678378523787788
           - 3.608003221870287 %i], [x = - .5202594388652008 %i
           - .1331240357358706, y = 3.608003221870287 %i
           + .07678378523787788], [x = - 1.733751846381093,
          y = - .1535675710019696]]

          (%i5) solve (1 + a*x + x^3, x);

                                                 3
                        sqrt(3) %i   1   sqrt(4 a  + 27)   1 1/3
          (%o5) [x = (- ---------- - -) (--------------- - -)
                            2        2      6 sqrt(3)      2

                  sqrt(3) %i   1
                 (---------- - -) a
                      2        2
           - --------------------------, x =
                        3
                sqrt(4 a  + 27)   1 1/3
             3 (--------------- - -)
                   6 sqrt(3)      2

                                    3
           sqrt(3) %i   1   sqrt(4 a  + 27)   1 1/3
          (---------- - -) (--------------- - -)
               2        2      6 sqrt(3)      2

                   sqrt(3) %i   1
                (- ---------- - -) a
                       2        2
           - --------------------------, x =
                        3
                sqrt(4 a  + 27)   1 1/3
             3 (--------------- - -)
                   6 sqrt(3)      2

                   3
           sqrt(4 a  + 27)   1 1/3               a
          (--------------- - -)    - --------------------------]
              6 sqrt(3)      2                  3
                                        sqrt(4 a  + 27)   1 1/3
                                     3 (--------------- - -)
                                           6 sqrt(3)      2
          (%i6) solve (x^3 - 1);
                       sqrt(3) %i - 1        sqrt(3) %i + 1
          (%o6)   [x = --------------, x = - --------------, x = 1]
                             2                     2
          (%i7) solve (x^6 - 1);
                     sqrt(3) %i + 1      sqrt(3) %i - 1
          (%o7) [x = --------------, x = --------------, x = - 1,
                           2                   2

                               sqrt(3) %i + 1        sqrt(3) %i - 1
                         x = - --------------, x = - --------------, x = 1]
                                     2                     2
          (%i8) ev (x^6 - 1, %[1]);
                                                6
                                (sqrt(3) %i + 1)
          (%o8)                 ----------------- - 1
                                       64
          (%i9) expand (%);
          (%o9)                           0
          (%i10) x^2 - 1;
                                        2
          (%o10)                       x  - 1
          (%i11) solve (%, x);
          (%o11)                  [x = - 1, x = 1]
          (%i12) ev (%th(2), %[1]);
          (%o12)                          0

     The symbols `%r' are used to denote arbitrary constants in a
     solution.

          (%i1) solve([x+y=1,2*x+2*y=2],[x,y]);

          solve: dependent equations eliminated: (2)
          (%o1)                      [[x = 1 - %r1, y = %r1]]

     See `algsys' and `%rnum_list' for more information.


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

     When `solvedecomposes' is `true', `solve' calls `polydecomp' if
     asked to solve polynomials.


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

     When `solveexplicit' is `true', inhibits `solve' from returning
     implicit solutions, that is, solutions of the form `F(x) = 0' where
     `F' is some function.


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

     When `solvefactors' is `false', `solve' does not try to factor the
     expression.  The `false' setting may be desired in some cases where
     factoring is not necessary.


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

     When `solvenullwarn' is `true', `solve' prints a warning message
     if called with either a null equation list or a null variable
     list.  For example, `solve ([], [])' would print two warning
     messages and return `[]'.


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

     When `solveradcan' is `true', `solve' calls `radcan' which makes
     `solve' slower but will allow certain problems containing
     exponentials and logarithms to be solved.


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

     When `solvetrigwarn' is `true', `solve' may print a message saying
     that it is using inverse trigonometric functions to solve the
     equation, and thereby losing solutions.



File: maxima.info,  Node: Differential Equations,  Next: Numerical,  Prev: Equations,  Up: Top

21 Differential Equations
*************************

* Menu:

* Introduction to Differential Equations::
* Functions and Variables for Differential Equations::


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

21.1 Introduction to Differential Equations
===========================================

This section describes the functions available in Maxima to obtain
analytic solutions for some specific types of first and second-order
equations. To obtain a numerical solution for a system of differential
equations, see the additional package `dynamics'. For graphical
representations in phase space, see the additional package `plotdf'.


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

21.2 Functions and Variables for Differential Equations
=======================================================

 -- Function: bc2 (<solution>, <xval1>, <yval1>, <xval2>, <yval2>)
     Solves a boundary value problem for a second order differential
     equation.  Here: <solution> is a general solution to the equation,
     as found by `ode2'; <xval1> specifies the value of the independent
     variable in a first point, in the form `<x> = <x1>', and <yval1>
     gives the value of the dependent variable in that point, in the
     form `<y> = <y1>'. The expressions <xval2> and <yval2> give the
     values for these variables at a second point, using the same form.

     See `ode2' for an example of its usage.


 -- Function: desolve (<eqn>, <x>)
 -- Function: desolve ([<eqn_1>, ..., <eqn_n>], [<x_1>, ..., <x_n>])
     The function `desolve' solves systems of linear ordinary
     differential equations using Laplace transform.  Here the <eqn>'s
     are differential equations in the dependent variables <x_1>, ...,
     <x_n>.  The functional dependence of <x_1>, ..., <x_n> on an
     independent variable, for instance <x>, must be explicitly
     indicated in the variables and its derivatives. For example, this
     would not be the correct way to define two equations:

          eqn_1: 'diff(f,x,2) = sin(x) + 'diff(g,x);
          eqn_2: 'diff(f,x) + x^2 - f = 2*'diff(g,x,2);

     The correct way would be:

          eqn_1: 'diff(f(x),x,2) = sin(x) + 'diff(g(x),x);
          eqn_2: 'diff(f(x),x) + x^2 - f(x) = 2*'diff(g(x),x,2);

     The call to the function `desolve' would then be
          desolve([eqn_1, eqn_2], [f(x),g(x)]);

     If initial conditions at `x=0' are known, they can be supplied
     before calling `desolve' by using `atvalue'.

          (%i1) 'diff(f(x),x)='diff(g(x),x)+sin(x);
                           d           d
          (%o1)            -- (f(x)) = -- (g(x)) + sin(x)
                           dx          dx
          (%i2) 'diff(g(x),x,2)='diff(f(x),x)-cos(x);
                            2
                           d            d
          (%o2)            --- (g(x)) = -- (f(x)) - cos(x)
                             2          dx
                           dx
          (%i3) atvalue('diff(g(x),x),x=0,a);
          (%o3)                           a
          (%i4) atvalue(f(x),x=0,1);
          (%o4)                           1
          (%i5) desolve([%o1,%o2],[f(x),g(x)]);
                            x
          (%o5) [f(x) = a %e  - a + 1, g(x) =

                                                          x
                                             cos(x) + a %e  - a + g(0) - 1]
          (%i6) [%o1,%o2],%o5,diff;
                       x       x      x                x
          (%o6)   [a %e  = a %e , a %e  - cos(x) = a %e  - cos(x)]

     If `desolve' cannot obtain a solution, it returns `false'.


 -- Function: ic1 (<solution>, <xval>, <yval>)
     Solves initial value problems for first order differential
     equations.  Here <solution> is a general solution to the equation,
     as found by `ode2', <xval> gives an initial value for the
     independent variable in the form `<x> = <x0>', and <yval> gives the
     initial value for the dependent variable in the form `<y> = <y0>'.

     See `ode2' for an example of its usage.


 -- Function: ic2 (<solution>, <xval>, <yval>, <dval>)
     Solves initial value problems for second-order differential
     equations.  Here <solution> is a general solution to the equation,
     as found by `ode2', <xval> gives the initial value for the
     independent variable in the form `<x> = <x0>', <yval> gives the
     initial value of the dependent variable in the form `<y> = <y0>',
     and <dval> gives the initial value for the first derivative of the
     dependent variable with respect to independent variable, in the
     form `diff(<y>,<x>) = <dy0>' (`diff' does not have to be quoted).

     See `ode2' for an example of its usage.


 -- Function: ode2 (<eqn>, <dvar>, <ivar>)
     The function `ode2' solves an ordinary differential equation (ODE)
     of first or second order. It takes three arguments: an ODE given by
     <eqn>, the dependent variable <dvar>, and the independent variable
     <ivar>. When successful, it returns either an explicit or implicit
     solution for the dependent variable. `%c' is used to represent the
     integration constant in the case of first-order equations, and
     `%k1' and `%k2' the constants for second-order equations. The
     dependence of the dependent variable on the independent variable
     does not have to be written explicitly, as in the case of
     `desolve', but the independent variable must always be given as the
     third argument.

     If `ode2' cannot obtain a solution for whatever reason, it returns
     `false', after perhaps printing out an error message. The methods
     implemented for first order equations in the order in which they
     are tested are: linear, separable, exact - perhaps requiring an
     integrating factor, homogeneous, Bernoulli's equation, and a
     generalized homogeneous method. The types of second-order
     equations which can be solved are: constant coefficients, exact,
     linear homogeneous with non-constant coefficients which can be
     transformed to constant coefficients, the Euler or
     equi-dimensional equation, equations solvable by the method of
     variation of parameters, and equations which are free of either the
     independent or of the dependent variable so that they can be
     reduced to two first order linear equations to be solved
     sequentially.

     In the course of solving ODE's, several variables are set purely
     for informational purposes: `method' denotes the method of solution
     used (e.g., `linear'), `intfactor' denotes any integrating factor
     used, `odeindex' denotes the index for Bernoulli's method or for
     the generalized homogeneous method, and `yp' denotes the
     particular solution for the variation of parameters technique.

     In order to solve initial value problems (IVP) functions `ic1' and
     `ic2' are available for first and second order equations, and to
     solve second-order boundary value problems (BVP) the function `bc2'
     can be used.

     Example:

          (%i1) x^2*'diff(y,x) + 3*y*x = sin(x)/x;
                                2 dy           sin(x)
          (%o1)                x  -- + 3 x y = ------
                                  dx             x
          (%i2) ode2(%,y,x);
                                       %c - cos(x)
          (%o2)                    y = -----------
                                            3
                                           x
          (%i3) ic1(%o2,x=%pi,y=0);
                                        cos(x) + 1
          (%o3)                   y = - ----------
                                             3
                                            x
          (%i4) 'diff(y,x,2) + y*'diff(y,x)^3 = 0;
                                   2
                                  d y      dy 3
          (%o4)                   --- + y (--)  = 0
                                    2      dx
                                  dx
          (%i5) ode2(%,y,x);
                                3
                               y  + 6 %k1 y
          (%o5)                ------------ = x + %k2
                                    6
          (%i6) ratsimp(ic2(%o5,x=0,y=0,'diff(y,x)=2));
                                       3
                                    2 y  - 3 y
          (%o6)                   - ---------- = x
                                        6
          (%i7) bc2(%o5,x=0,y=1,x=1,y=3);
                                   3
                                  y  - 10 y       3
          (%o7)                   --------- = x - -
                                      6           2



File: maxima.info,  Node: Numerical,  Next: Matrices and Linear Algebra,  Prev: Differential Equations,  Up: Top

22 Numerical
************

* Menu:

* Introduction to fast Fourier transform::
* Functions and Variables for fast Fourier transform::
* Functions for numerical solution of equations::
* Introduction to numerical solution of differential equations::
* Functions for numerical solution of differential equations::


File: maxima.info,  Node: Introduction to fast Fourier transform,  Next: Functions and Variables for fast Fourier transform,  Prev: Numerical,  Up: Numerical

22.1 Introduction to fast Fourier transform
===========================================

The `fft' package comprises functions for the numerical (not symbolic)
computation of the fast Fourier transform.


File: maxima.info,  Node: Functions and Variables for fast Fourier transform,  Next: Functions for numerical solution of equations,  Prev: Introduction to fast Fourier transform,  Up: Numerical

22.2 Functions and Variables for fast Fourier transform
=======================================================

 -- Function: polartorect (<r>, <t>)
     Translates complex values of the form `r %e^(%i t)' to the form `a
     + b %i', where <r> is the magnitude and <t> is the phase.  <r> and
     <t> are 1-dimensional arrays of the same size.  The array size
     need not be a power of 2.

     The original values of the input arrays are replaced by the real
     and imaginary parts, `a' and `b', on return.  The outputs are
     calculated as

          a = r cos(t)
          b = r sin(t)

     `polartorect' is the inverse function of `recttopolar'.

     `load(fft)' loads this function.  See also `fft'.


 -- Function: recttopolar (<a>, <b>)
     Translates complex values of the form `a + b %i' to the form `r
     %e^(%i t)', where <a> is the real part and <b> is the imaginary
     part.  <a> and <b> are 1-dimensional arrays of the same size.  The
     array size need not be a power of 2.

     The original values of the input arrays are replaced by the
     magnitude and angle, `r' and `t', on return.  The outputs are
     calculated as

          r = sqrt(a^2 + b^2)
          t = atan2(b, a)

     The computed angle is in the range `-%pi' to `%pi'.

     `recttopolar' is the inverse function of `polartorect'.

     `load(fft)' loads this function.  See also `fft'.


 -- Function: inverse_fft (<y>)
     Computes the inverse complex fast Fourier transform.  <y> is a
     list or array (named or unnamed) which contains the data to
     transform.  The number of elements must be a power of 2.  The
     elements must be literal numbers (integers, rationals, floats, or
     bigfloats) or symbolic constants, or expressions `a + b*%i' where
     `a' and `b' are literal numbers or symbolic constants.

     `inverse_fft' returns a new object of the same type as <y>, which
     is not modified.  Results are always computed as floats or
     expressions `a + b*%i' where `a' and `b' are floats.

     The inverse discrete Fourier transform is defined as follows.  Let
     `x' be the output of the inverse transform.  Then for `j' from 0
     through `n - 1',

          x[j] = sum(y[k] exp(-2 %i %pi j k / n), k, 0, n - 1)

     `load(fft)' loads this function.

     See also `fft' (forward transform), `recttopolar', and
     `polartorect'.

     Examples:

     Real data.

          (%i1) load (fft) $
          (%i2) fpprintprec : 4 $
          (%i3) L : [1, 2, 3, 4, -1, -2, -3, -4] $
          (%i4) L1 : inverse_fft (L);
          (%o4) [0.0, 14.49 %i - .8284, 0.0, 2.485 %i + 4.828, 0.0,
                                 4.828 - 2.485 %i, 0.0, - 14.49 %i - .8284]
          (%i5) L2 : fft (L1);
          (%o5) [1.0, 2.0 - 2.168L-19 %i, 3.0 - 7.525L-20 %i,
          4.0 - 4.256L-19 %i, - 1.0, 2.168L-19 %i - 2.0,
          7.525L-20 %i - 3.0, 4.256L-19 %i - 4.0]
          (%i6) lmax (abs (L2 - L));
          (%o6)                       3.545L-16

     Complex data.

          (%i1) load (fft) $
          (%i2) fpprintprec : 4 $
          (%i3) L : [1, 1 + %i, 1 - %i, -1, -1, 1 - %i, 1 + %i, 1] $
          (%i4) L1 : inverse_fft (L);
          (%o4) [4.0, 2.711L-19 %i + 4.0, 2.0 %i - 2.0,
          - 2.828 %i - 2.828, 0.0, 5.421L-20 %i + 4.0, - 2.0 %i - 2.0,
          2.828 %i + 2.828]
          (%i5) L2 : fft (L1);
          (%o5) [4.066E-20 %i + 1.0, 1.0 %i + 1.0, 1.0 - 1.0 %i,
          1.55L-19 %i - 1.0, - 4.066E-20 %i - 1.0, 1.0 - 1.0 %i,
          1.0 %i + 1.0, 1.0 - 7.368L-20 %i]
          (%i6) lmax (abs (L2 - L));
          (%o6)                       6.841L-17


 -- Function: fft (<x>)
     Computes the complex fast Fourier transform.  <x> is a list or
     array (named or unnamed) which contains the data to transform.
     The number of elements must be a power of 2.  The elements must be
     literal numbers (integers, rationals, floats, or bigfloats) or
     symbolic constants, or expressions `a + b*%i' where `a' and `b'
     are literal numbers or symbolic constants.

     `fft' returns a new object of the same type as <x>, which is not
     modified.  Results are always computed as floats or expressions `a
     + b*%i' where `a' and `b' are floats.

     The discrete Fourier transform is defined as follows.  Let `y' be
     the output of the transform.  Then for `k' from 0 through `n - 1',

          y[k] = (1/n) sum(x[j] exp(+2 %i %pi j k / n), j, 0, n - 1)

     When the data <x> are real, real coefficients `a' and `b' can be
     computed such that

          x[j] = sum(a[k]*cos(2*%pi*j*k/n)+b[k]*sin(2*%pi*j*k/n), k, 0, n/2)

     with

          a[0] = realpart (y[0])
          b[0] = 0

     and, for k from 1 through n/2 - 1,

          a[k] = realpart (y[k] + y[n - k])
          b[k] = imagpart (y[n - k] - y[k])

     and

          a[n/2] = realpart (y[n/2])
          b[n/2] = 0

     `load(fft)' loads this function.

     See also `inverse_fft' (inverse transform), `recttopolar', and
     `polartorect'.

     Examples:

     Real data.

          (%i1) load (fft) $
          (%i2) fpprintprec : 4 $
          (%i3) L : [1, 2, 3, 4, -1, -2, -3, -4] $
          (%i4) L1 : fft (L);
          (%o4) [0.0, - 1.811 %i - .1036, 0.0, .6036 - .3107 %i, 0.0,
                                   .3107 %i + .6036, 0.0, 1.811 %i - .1036]
          (%i5) L2 : inverse_fft (L1);
          (%o5) [1.0, 2.168L-19 %i + 2.0, 7.525L-20 %i + 3.0,
          4.256L-19 %i + 4.0, - 1.0, - 2.168L-19 %i - 2.0,
          - 7.525L-20 %i - 3.0, - 4.256L-19 %i - 4.0]
          (%i6) lmax (abs (L2 - L));
          (%o6)                       3.545L-16

     Complex data.

          (%i1) load (fft) $
          (%i2) fpprintprec : 4 $
          (%i3) L : [1, 1 + %i, 1 - %i, -1, -1, 1 - %i, 1 + %i, 1] $
          (%i4) L1 : fft (L);
          (%o4) [0.5, .3536 %i + .3536, - 0.25 %i - 0.25,
          0.5 - 6.776L-21 %i, 0.0, - .3536 %i - .3536, 0.25 %i - 0.25,
          0.5 - 3.388L-20 %i]
          (%i5) L2 : inverse_fft (L1);
          (%o5) [1.0 - 4.066E-20 %i, 1.0 %i + 1.0, 1.0 - 1.0 %i,
          - 1.008L-19 %i - 1.0, 4.066E-20 %i - 1.0, 1.0 - 1.0 %i,
          1.0 %i + 1.0, 1.947L-20 %i + 1.0]
          (%i6) lmax (abs (L2 - L));
          (%o6)                       6.83L-17

     Computation of sine and cosine coefficients.

          (%i1) load (fft) $
          (%i2) fpprintprec : 4 $
          (%i3) L : [1, 2, 3, 4, 5, 6, 7, 8] $
          (%i4) n : length (L) $
          (%i5) x : make_array (any, n) $
          (%i6) fillarray (x, L) $
          (%i7) y : fft (x) $
          (%i8) a : make_array (any, n/2 + 1) $
          (%i9) b : make_array (any, n/2 + 1) $
          (%i10) a[0] : realpart (y[0]) $
          (%i11) b[0] : 0 $
          (%i12) for k : 1 thru n/2 - 1 do
             (a[k] : realpart (y[k] + y[n - k]),
              b[k] : imagpart (y[n - k] - y[k]));
          (%o12)                        done
          (%i13) a[n/2] : y[n/2] $
          (%i14) b[n/2] : 0 $
          (%i15) listarray (a);
          (%o15)          [4.5, - 1.0, - 1.0, - 1.0, - 0.5]
          (%i16) listarray (b);
          (%o16)           [0, - 2.414, - 1.0, - .4142, 0]
          (%i17) f(j) := sum (a[k]*cos(2*%pi*j*k/n) + b[k]*sin(2*%pi*j*k/n),
                              k, 0, n/2) $
          (%i18) makelist (float (f (j)), j, 0, n - 1);
          (%o18)      [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]



File: maxima.info,  Node: Functions for numerical solution of equations,  Next: Introduction to numerical solution of differential equations,  Prev: Functions and Variables for fast Fourier transform,  Up: Numerical

22.3 Functions for numerical solution of equations
==================================================

 -- Function: horner (<expr>, <x>)
 -- Function: horner (<expr>)
     Returns a rearranged representation of <expr> as in Horner's rule,
     using <x> as the main variable if it is specified.  `x' may be
     omitted in which case the main variable of the canonical rational
     expression form of <expr> is used.

     `horner' sometimes improves stability if `expr' is to be
     numerically evaluated.  It is also useful if Maxima is used to
     generate programs to be run in Fortran.  See also `stringout'.

          (%i1) expr: 1e-155*x^2 - 5.5*x + 5.2e155;
                                     2
          (%o1)             1.e-155 x  - 5.5 x + 5.2e+155
          (%i2) expr2: horner (%, x), keepfloat: true;
          (%o2)         1.0 ((1.e-155 x - 5.5) x + 5.2e+155)
          (%i3) ev (expr, x=1e155);
          Maxima encountered a Lisp error:

           arithmetic error FLOATING-POINT-OVERFLOW signalled

          Automatically continuing.
          To enable the Lisp debugger set *debugger-hook* to nil.
          (%i4) ev (expr2, x=1e155);
          (%o4)                 7.00000000000001e+154


 -- Function: find_root (<expr>, <x>, <a>, <b>, [<abserr>, <relerr>])
 -- Function: find_root (<f>, <a>, <b>, [<abserr>, <relerr>])
 -- Function: bf_find_root (<expr>, <x>, <a>, <b>, [<abserr>, <relerr>])
 -- Function: bf_find_root (<f>, <a>, <b>, [<abserr>, <relerr>])
 -- Option variable: find_root_error
 -- Option variable: find_root_abs
 -- Option variable: find_root_rel
     Finds a root of the expression <expr> or the function <f> over the
     closed interval [<a>, <b>].  The expression <expr> may be an
     equation, in which case `find_root' seeks a root of `lhs(<expr>) -
     rhs(<expr>)'.

     Given that Maxima can evaluate <expr> or <f> over [<a>, <b>] and
     that <expr> or <f> is continuous, `find_root' is guaranteed to
     find the root, or one of the roots if there is more than one.

     `find_root' initially applies binary search.  If the function in
     question appears to be smooth enough, `find_root' applies linear
     interpolation instead.

     `bf_find_root' is a bigfloat version of `find_root'.  The function
     is computed using bigfloat arithmetic and a bigfloat result is
     returned.  Otherwise, `bf_find_root' is identical to `find_root',
     and the following description is equally applicable to
     `bf_find_root'.

     The accuracy of `find_root' is governed by `abserr' and `relerr',
     which are optional keyword arguments to `find_root'.  These
     keyword arguments take the form `key=val'.  The keyword arguments
     are

    `abserr'
          Desired absolute error of function value at root.  Default is
          `find_root_abs'.

    `relerr'
          Desired relative error of root.  Default is `find_root_rel'.

     `find_root' stops when the function in question evaluates to
     something less than or equal to `abserr', or if successive
     approximants <x_0>, <x_1> differ by no more than `relerr *
     max(abs(x_0), abs(x_1))'.  The default values of `find_root_abs'
     and `find_root_rel' are both zero.

     `find_root' expects the function in question to have a different
     sign at the endpoints of the search interval.  When the function
     evaluates to a number at both endpoints and these numbers have the
     same sign, the behavior of `find_root' is governed by
     `find_root_error'.  When `find_root_error' is `true', `find_root'
     prints an error message.  Otherwise `find_root' returns the value
     of `find_root_error'.  The default value of `find_root_error' is
     `true'.

     If <f> evaluates to something other than a number at any step in
     the search algorithm, `find_root' returns a partially-evaluated
     `find_root' expression.

     The order of <a> and <b> is ignored; the region in which a root is
     sought is [min(<a>, <b>), max(<a>, <b>)].

     Examples:

          (%i1) f(x) := sin(x) - x/2;
                                                  x
          (%o1)                  f(x) := sin(x) - -
                                                  2
          (%i2) find_root (sin(x) - x/2, x, 0.1, %pi);
          (%o2)                   1.895494267033981
          (%i3) find_root (sin(x) = x/2, x, 0.1, %pi);
          (%o3)                   1.895494267033981
          (%i4) find_root (f(x), x, 0.1, %pi);
          (%o4)                   1.895494267033981
          (%i5) find_root (f, 0.1, %pi);
          (%o5)                   1.895494267033981
          (%i6) find_root (exp(x) = y, x, 0, 100);
                                      x
          (%o6)           find_root(%e  = y, x, 0.0, 100.0)
          (%i7) find_root (exp(x) = y, x, 0, 100), y = 10;
          (%o7)                   2.302585092994046
          (%i8) log (10.0);
          (%o8)                   2.302585092994046
          (%i9) fpprec:32;
          (%o9)                           32
          (%i10) bf_find_root (exp(x) = y, x, 0, 100), y = 10;
          (%o10)                  2.3025850929940456840179914546844b0
          (%i11) log(10b0);
          (%o11)                  2.3025850929940456840179914546844b0


 -- Function: newton (<expr>, <x>, <x_0>, <eps>)
     Returns an approximate solution of `<expr> = 0' by Newton's method,
     considering <expr> to be a function of one variable, <x>.  The
     search begins with `<x> = <x_0>' and proceeds until `abs(<expr>) <
     <eps>' (with <expr> evaluated at the current value of <x>).

     `newton' allows undefined variables to appear in <expr>, so long
     as the termination test `abs(<expr>) < <eps>' evaluates to `true'
     or `false'.  Thus it is not necessary that <expr> evaluate to a
     number.

     `load(newton1)' loads this function.

     See also `realroots', `allroots', `find_root', and `mnewton'.

     Examples:

          (%i1) load (newton1);
          (%o1)  /maxima/share/numeric/newton1.mac
          (%i2) newton (cos (u), u, 1, 1/100);
          (%o2)                   1.570675277161251
          (%i3) ev (cos (u), u = %);
          (%o3)                 1.2104963335033529e-4
          (%i4) assume (a > 0);
          (%o4)                        [a > 0]
          (%i5) newton (x^2 - a^2, x, a/2, a^2/100);
          (%o5)                  1.00030487804878 a
          (%i6) ev (x^2 - a^2, x = %);
                                                     2
          (%o6)                6.098490481853958e-4 a



File: maxima.info,  Node: Introduction to numerical solution of differential equations,  Next: Functions for numerical solution of differential equations,  Prev: Functions for numerical solution of equations,  Up: Numerical

22.4 Introduction to numerical solution of differential equations
=================================================================

The Ordinary Differential Equations (ODE) solved by the functions in
this section should have the form,
            dy
            -- = F(x,y)
            dx
   which is a first-order ODE. Higher order differential equations of
order <n> must be written as a system of <n> first-order equations of
that kind. For instance, a second-order ODE should be written as a
system of two equations
            dx               dy
            -- = G(x,y,t)    -- = F(x,y,t)
            dt               dt

   The first argument in the functions will be a list with the
expressions on the right-side of the ODE's. The variables whose
derivatives are represented by those expressions should be given in a
second list. In the case above those variables are <x> and <y>. The
independent variable, <t> in the examples above, might be given in a
separated option. If the expressions given do not depend on that
independent variable, the system is called autonomous.


File: maxima.info,  Node: Functions for numerical solution of differential equations,  Prev: Introduction to numerical solution of differential equations,  Up: Numerical

22.5 Functions for numerical solution of differential equations
===============================================================

 -- Function: plotdf (<dydx>, ...options...)
 -- Function: plotdf (<dvdu>, `['<u>,<v>`]', ...options...)
 -- Function: plotdf (`['<dxdt>,<dydt>`]', ...options...)
 -- Function: plotdf (`['<dudt>,<dvdt>`]', `['<u>,<v>`]', ...options...)
     The function `plotdf' creates a two-dimensional plot of the
     direction field (also called slope field) for a first-order
     Ordinary Differential Equation (ODE) or a system of two autonomous
     first-order ODE's.

     Plotdf requires Xmaxima, even if its run from a Maxima session in
     a console, since the plot will be created by the Tk scripts in
     Xmaxima.  If Xmaxima is not installed plotdf will not work.

     <dydx>, <dxdt> and <dydt> are expressions that depend on <x> and
     <y>. <dvdu>, <dudt> and <dvdt> are expressions that depend on <u>
     and <v>. In addition to those two variables, the expressions can
     also depend on a set of parameters, with numerical values given
     with the `parameters' option (the option syntax is given below),
     or with a range of allowed values specified by a <sliders> option.

     Several other options can be given within the command, or selected
     in the menu. Integral curves can be obtained by clicking on the
     plot, or with the option `trajectory_at'. The direction of the
     integration can be controlled with the `direction' option, which
     can have values of _forward_, _backward_ or _both_. The number of
     integration steps is given by `nsteps'; at each integration step
     the time increment will be adjusted automatically to produce
     displacements much smaller than the size of the plot window. The
     numerical method used is 4th order Runge-Kutta with variable time
     steps.

     Plot window menu:

     The menu bar of the plot window has the following seven icons:

     An X. Can be used to close the plot window.

     A wrench and a screwdriver. Opens the configuration menu with
     several fields that show the ODE(s) in use and various other
     settings. If a pair of coordinates are entered in the field
     _Trajectory at_ and the <enter> key is pressed, a new integral
     curve will be shown, in addition to the ones already shown.

     Two arrows following a circle. Replots the direction field with the
     new settings defined in the configuration menu and replots only
     the last integral curve that was previously plotted.

     Hard disk drive with an arrow. Used to save a copy of the plot, in
     Postscript format, in the file specified in a field of the box
     that appears when that icon is clicked.

     Magnifying glass with a plus sign. Zooms in the plot.

     Magnifying glass with a minus sign. Zooms out the plot. The plot
     can be displaced by holding down the right mouse button while the
     mouse is moved.

     Icon of a plot. Opens another window with a plot of the two
     variables in terms of time, for the last integral curve that was
     plotted.

     Plot options:

     Options can also be given within the `plotdf' itself, each one
     being a list of two or more elements. The first element in each
     option is the name of the option, and the remainder is the value
     or values assigned to the option.

     The options which are recognized by `plotdf' are the following:

        * "nsteps" defines the number of steps that will be used for the
          independent variable, to compute an integral curve. The
          default value is 100.

        * "direction" defines the direction of the independent variable
          that will be followed to compute an integral curve. Possible
          values are `forward', to make the independent variable
          increase `nsteps' times, with increments `tstep', `backward',
          to make the independent variable decrease, or `both' that
          will lead to an integral curve that extends `nsteps' forward,
          and `nsteps' backward. The keywords `right' and `left' can be
          used as synonyms for `forward' and `backward'.  The default
          value is `both'.

        * "tinitial" defines the initial value of variable <t> used to
          compute integral curves. Since the differential equations are
          autonomous, that setting will only appear in the plot of the
          curves as functions of <t>.  The default value is 0.

        * "versus_t" is used to create a second plot window, with a
          plot of an integral curve, as two functions <x>, <y>, of the
          independent variable <t>. If `versus_t' is given any value
          different from 0, the second plot window will be displayed.
          The second plot window includes another menu, similar to the
          menu of the main plot window.  The default value is 0.

        * "trajectory_at" defines the coordinates <xinitial> and
          <yinitial> for the starting point of an integral curve.  The
          option is empty by default.

        * "parameters" defines a list of parameters, and their
          numerical values, used in the definition of the differential
          equations. The name and values of the parameters must be
          given in a string with a comma-separated sequence of pairs
          `name=value'.

        * "sliders" defines a list of parameters that will be changed
          interactively using slider buttons, and the range of
          variation of those parameters. The names and ranges of the
          parameters must be given in a string with a comma-separated
          sequence of elements `name=min:max'

        * "xfun" defines a string with semi-colon-separated sequence of
          functions of <x> to be displayed, on top of the direction
          field.  Those functions will be parsed by Tcl and not by
          Maxima.

        * "x" should be followed by two numbers, which will set up the
          minimum and maximum values shown on the horizontal axis. If
          the variable on the horizontal axis is not <x>, then this
          option should have the name of the variable on the horizontal
          axis.  The default horizontal range is from -10 to 10.

        * "y" should be followed by two numbers, which will set up the
          minimum and maximum values shown on the vertical axis. If the
          variable on the vertical axis is not <y>, then this option
          should have the name of the variable on the vertical axis.
          The default vertical range is from -10 to 10.

        * "xaxislabel" will be used to identify the horizontal axis.
          Its default value is the name of the first state variable.

        * "yaxislabel" will be used to identify the vertical axis. Its
          default value is the name of the second state variable.


     *Examples:*

        * To show the direction field of the differential equation y' =
          exp(-x) + y and the solution that goes through (2, -0.1):
               (%i1) plotdf(exp(-x)+y,[trajectory_at,2,-0.1])$

        * To obtain the direction field for the equation diff(y,x) = x
          - y^2 and the solution with initial condition y(-1) = 3, we
          can use the command:
               (%i1) plotdf(x-y^2,[xfun,"sqrt(x);-sqrt(x)"],
                        [trajectory_at,-1,3], [direction,forward],
                        [y,-5,5], [x,-4,16])$

          The graph also shows the function y = sqrt(x).

        * The following example shows the direction field of a harmonic
          oscillator, defined by the two equations dz/dt = v and dv/dt
          = -k*z/m, and the integral curve through (z,v) = (6,0), with
          a slider that will allow you to change the value of m
          interactively (k is fixed at 2):
               (%i1) plotdf([v,-k*z/m], [z,v], [parameters,"m=2,k=2"],
                          [sliders,"m=1:5"], [trajectory_at,6,0])$

        * To plot the direction field of the Duffing equation,
          m*x"+c*x'+k*x+b*x^3 = 0, we introduce the variable y=x' and
          use:
               (%i1) plotdf([y,-(k*x + c*y + b*x^3)/m],
                            [parameters,"k=-1,m=1.0,c=0,b=1"],
                            [sliders,"k=-2:2,m=-1:1"],[tstep,0.1])$

        * The direction field for a damped pendulum, including the
          solution for the given initial conditions, with a slider that
          can be used to change the value of the mass m, and with a
          plot of the two state variables as a function of time:

               (%i1) plotdf([w,-g*sin(a)/l - b*w/m/l], [a,w],
                       [parameters,"g=9.8,l=0.5,m=0.3,b=0.05"],
                       [trajectory_at,1.05,-9],[tstep,0.01],
                       [a,-10,2], [w,-14,14], [direction,forward],
                       [nsteps,300], [sliders,"m=0.1:1"], [versus_t,1])$



 -- Function: ploteq (<exp>, ...options...)
     Plots equipotential curves for <exp>, which should be an expression
     depending on two variables. The curves are obtained by integrating
     the differential equation that define the orthogonal trajectories
     to the solutions of the autonomous system obtained from the
     gradient of the expression given.  The plot can also show the
     integral curves for that gradient system (option fieldlines).

     This program also requires Xmaxima, even if its run from a Maxima
     session in a console, since the plot will be created by the Tk
     scripts in Xmaxima.  By default, the plot region will be empty
     until the user clicks in a point (or gives its coordinate with in
     the set-up menu or via the trajectory_at option).

     Most options accepted by plotdf can also be used for ploteq and
     the plot interface is the same that was described in plotdf.

     Example:

          (%i1) V: 900/((x+1)^2+y^2)^(1/2)-900/((x-1)^2+y^2)^(1/2)$
          (%i2) ploteq(V,[x,-2,2],[y,-2,2],[fieldlines,"blue"])$

     Clicking on a point will plot the equipotential curve that passes
     by that point (in red) and the orthogonal trajectory (in blue).


 -- Function: rk (<ODE>, <var>, <initial>, <domain>)
 -- Function: rk ([<ODE1>,...,<ODEm>], [<v1>,...,<vm>],
          [<init1>,...,<initm>], <domain>)
     The first form solves numerically one first-order ordinary
     differential equation, and the second form solves a system of m of
     those equations, using the 4th order Runge-Kutta method. <var>
     represents the dependent variable. <ODE> must be an expression
     that depends only on the independent and dependent variables and
     defines the derivative of the dependent variable with respect to
     the independent variable.

     The independent variable is specified with `domain', which must be
     a list of four elements as, for instance:
          [t, 0, 10, 0.1]
     the first element of the list identifies the independent variable,
     the second and third elements are the initial and final values for
     that variable, and the last element sets the increments that
     should be used within that interval.

     If <m> equations are going to be solved, there should be <m>
     dependent variables <v1>, <v2>, ..., <vm>. The initial values for
     those variables will be <init1>, <init2>, ..., <initm>.  There
     will still be just one independent variable defined by `domain',
     as in the previous case. <ODE1>, ..., <ODEm> are the expressions
     that define the derivatives of each dependent variable in terms of
     the independent variable. The only variables that may appear in
     those expressions are the independent variable and any of the
     dependent variables. It is important to give the derivatives
     <ODE1>, ..., <ODEm> in the list in exactly the same order used for
     the dependent variables; for instance, the third element in the
     list will be interpreted as the derivative of the third dependent
     variable.

     The program will try to integrate the equations from the initial
     value of the independent variable until its last value, using
     constant increments. If at some step one of the dependent
     variables takes an absolute value too large, the integration will
     be interrupted at that point. The result will be a list with as
     many elements as the number of iterations made. Each element in
     the results list is itself another list with <m>+1 elements: the
     value of the independent variable, followed by the values of the
     dependent variables corresponding to that point.

     To solve numerically the differential equation

                    dx/dt = t - x^2

     With initial value x(t=0) = 1, in the interval of t from 0 to 8
     and with increments of 0.1 for t, use:

          (%i1) results: rk(t-x^2,x,1,[t,0,8,0.1])$
          (%i2) plot2d ([discrete, results])$

     the results will be saved in the list `results' and the plot will
     show the solution obtained, with <t> on the horizontal axis and
     <x> on the vertical axis.

     To solve numerically the system:

                  dx/dt = 4-x^2-4*y^2     dy/dt = y^2-x^2+1

     for t between 0 and 4, and with values of -1.25 and 0.75 for x and
     y at t=0:

          (%i1) sol: rk([4-x^2-4*y^2,y^2-x^2+1],[x,y],[-1.25,0.75],[t,0,4,0.02])$
          (%i2) plot2d ([discrete,makelist([p[1],p[3]],p,sol)], [xlabel,"t"],[ylabel,"y"])$

     The plot will show the solution for variable <y> as a function of
     <t>.



File: maxima.info,  Node: Matrices and Linear Algebra,  Next: Affine,  Prev: Numerical,  Up: Top

23 Matrices and Linear Algebra
******************************

* Menu:

* Introduction to Matrices and Linear Algebra::
* Functions and Variables for Matrices and Linear Algebra::


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

23.1 Introduction to Matrices and Linear Algebra
================================================

* Menu:

* Dot::
* Vectors::
* eigen::


File: maxima.info,  Node: Dot,  Next: Vectors,  Prev: Introduction to Matrices and Linear Algebra,  Up: Introduction to Matrices and Linear Algebra

23.1.1 Dot
----------

The operator `.' represents noncommutative multiplication and scalar
product.  When the operands are 1-column or 1-row matrices `a' and `b',
the expression `a.b' is equivalent to `sum (a[i]*b[i], i, 1,
length(a))'.  If `a' and `b' are not complex, this is the scalar
product, also called the inner product or dot product, of `a' and `b'.
The scalar product is defined as `conjugate(a).b' when `a' and `b' are
complex; `innerproduct' in the `eigen' package provides the complex
scalar product.

   When the operands are more general matrices, the product is the
matrix product `a' and `b'.  The number of rows of `b' must equal the
number of columns of `a', and the result has number of rows equal to
the number of rows of `a' and number of columns equal to the number of
columns of `b'.

   To distinguish `.' as an arithmetic operator from the decimal point
in a floating point number, it may be necessary to leave spaces on
either side.  For example, `5.e3' is `5000.0' but `5 . e3' is `5' times
`e3'.

   There are several flags which govern the simplification of
expressions involving `.', namely `dot0nscsimp', `dot0simp',
`dot1simp', `dotassoc', `dotconstrules', `dotdistrib', `dotexptsimp',
`dotident', and `dotscrules'.


File: maxima.info,  Node: Vectors,  Next: eigen,  Prev: Dot,  Up: Introduction to Matrices and Linear Algebra

23.1.2 Vectors
--------------

`vect' is a package of functions for vector analysis.  `load ("vect")'
loads this package, and `demo ("vect")' displays a demonstration.

   The vector analysis package can combine and simplify symbolic
expressions including dot products and cross products, together with
the gradient, divergence, curl, and Laplacian operators.  The
distribution of these operators over sums or products is governed by
several flags, as are various other expansions, including expansion
into components in any specific orthogonal coordinate systems.  There
are also functions for deriving the scalar or vector potential of a
field.

   The `vect' package contains these functions: `vectorsimp',
`scalefactors', `express', `potential', and `vectorpotential'.

   By default the `vect' package does not declare the dot operator to
be a commutative operator.  To get a commutative dot operator `.', the
command `declare(".", commutative)' must be executed.


File: maxima.info,  Node: eigen,  Prev: Vectors,  Up: Introduction to Matrices and Linear Algebra

23.1.3 eigen
------------

The package `eigen' contains several functions devoted to the symbolic
computation of eigenvalues and eigenvectors.  Maxima loads the package
automatically if one of the functions `eigenvalues' or `eigenvectors'
is invoked.  The package may be loaded explicitly as `load ("eigen")'.

   `demo ("eigen")' displays a demonstration of the capabilities of
this package.  `batch ("eigen")' executes the same demonstration, but
without the user prompt between successive computations.

   The functions in the `eigen' package are:
`innerproduct', `unitvector', `columnvector', `gramschmidt',
`eigenvalues',
`eigenvectors', `uniteigenvectors', and `similaritytransform'.


File: maxima.info,  Node: Functions and Variables for Matrices and Linear Algebra,  Prev: Introduction to Matrices and Linear Algebra,  Up: Matrices and Linear Algebra

23.2 Functions and Variables for Matrices and Linear Algebra
============================================================

 -- Function: addcol (<M>, <list_1>, ..., <list_n>)
     Appends the column(s) given by the one or more lists (or matrices)
     onto the matrix <M>.


 -- Function: addrow (<M>, <list_1>, ..., <list_n>)
     Appends the row(s) given by the one or more lists (or matrices)
     onto the matrix <M>.


 -- Function: adjoint (<M>)
     Returns the adjoint of the matrix <M>.  The adjoint matrix is the
     transpose of the matrix of cofactors of <M>.


 -- Function: augcoefmatrix ([<eqn_1>, ..., <eqn_m>], [<x_1>, ...,
          <x_n>])
     Returns the augmented coefficient matrix for the variables <x_1>,
     ..., <x_n> of the system of linear equations <eqn_1>, ...,
     <eqn_m>.  This is the coefficient matrix with a column adjoined
     for the constant terms in each equation (i.e., those terms not
     dependent upon <x_1>, ..., <x_n>).

          (%i1) m: [2*x - (a - 1)*y = 5*b, c + b*y + a*x = 0]$
          (%i2) augcoefmatrix (m, [x, y]);
                                 [ 2  1 - a  - 5 b ]
          (%o2)                  [                 ]
                                 [ a    b      c   ]


 -- Function: cauchy_matrix ([<x_1>, <x_2>, ..., <x_m>], [<y_1>, <y_2>,
          ..., <y_n>])
 -- Function: cauchy_matrix ([<x_1>, <x_2>, ..., <x_n>])
     Returns a `n' by <m> Cauchy matrix with the elements <a[i,j]> =
     1/(<x_i>+<y_i>).  The second argument of `cauchy_matrix' is
     optional.  For this case the elements of the Cauchy matrix are
     <a[i,j]> = 1/(<x_i>+<x_j>).

     Remark: In the literature the Cauchy matrix can be found defined
     in two forms.  A second definition is <a[i,j]> = 1/(<x_i>-<y_i>).

     Examples:

          (%i1) cauchy_matrix([x1,x2],[y1,y2]);
                                [    1        1    ]
                                [ -------  ------- ]
                                [ y1 + x1  y2 + x1 ]
          (%o1)                 [                  ]
                                [    1        1    ]
                                [ -------  ------- ]
                                [ y1 + x2  y2 + x2 ]

          (%i2) cauchy_matrix([x1,x2]);
                                [   1         1    ]
                                [  ----    ------- ]
                                [  2 x1    x2 + x1 ]
          (%o2)                 [                  ]
                                [    1       1     ]
                                [ -------   ----   ]
                                [ x2 + x1   2 x2   ]


 -- Function: charpoly (<M>, <x>)
     Returns the characteristic polynomial for the matrix <M> with
     respect to variable <x>.  That is, `determinant (<M> - diagmatrix
     (length (<M>), <x>))'.

          (%i1) a: matrix ([3, 1], [2, 4]);
                                      [ 3  1 ]
          (%o1)                       [      ]
                                      [ 2  4 ]
          (%i2) expand (charpoly (a, lambda));
                                     2
          (%o2)                lambda  - 7 lambda + 10
          (%i3) (programmode: true, solve (%));
          (%o3)               [lambda = 5, lambda = 2]
          (%i4) matrix ([x1], [x2]);
                                       [ x1 ]
          (%o4)                        [    ]
                                       [ x2 ]
          (%i5) ev (a . % - lambda*%, %th(2)[1]);
                                    [ x2 - 2 x1 ]
          (%o5)                     [           ]
                                    [ 2 x1 - x2 ]
          (%i6) %[1, 1] = 0;
          (%o6)                     x2 - 2 x1 = 0
          (%i7) x2^2 + x1^2 = 1;
                                      2     2
          (%o7)                     x2  + x1  = 1
          (%i8) solve ([%th(2), %], [x1, x2]);
                            1               2
          (%o8) [[x1 = - -------, x2 = - -------],
                         sqrt(5)         sqrt(5)

                                                       1             2
                                              [x1 = -------, x2 = -------]]
                                                    sqrt(5)       sqrt(5)


 -- Function: coefmatrix ([<eqn_1>, ..., <eqn_m>], [<x_1>, ..., <x_n>])
     Returns the coefficient matrix for the variables <x_1>, ..., <x_n>
     of the system of linear equations <eqn_1>, ..., <eqn_m>.

          (%i1) coefmatrix([2*x-(a-1)*y+5*b = 0, b*y+a*x = 3], [x,y]);
                                           [ 2  1 - a ]
          (%o1)                            [          ]
                                           [ a    b   ]


 -- Function: col (<M>, <i>)
     Returns the <i>'th column of the matrix <M>.  The return value is
     a matrix.


 -- Function: columnvector (<L>)
 -- Function: covect (<L>)
     Returns a matrix of one column and `length (<L>)' rows, containing
     the elements of the list <L>.

     `covect' is a synonym for `columnvector'.

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

     This is useful if you want to use parts of the outputs of the
     functions in this package in matrix calculations.

     Example:

          (%i1) load ("eigen")$
          Warning - you are redefining the Macsyma function eigenvalues
          Warning - you are redefining the Macsyma function eigenvectors
          (%i2) columnvector ([aa, bb, cc, dd]);
                                       [ aa ]
                                       [    ]
                                       [ bb ]
          (%o2)                        [    ]
                                       [ cc ]
                                       [    ]
                                       [ dd ]


 -- Function: copymatrix (<M>)
     Returns a copy of the matrix <M>.  This is the only way to make a
     copy aside from copying <M> element by element.

     Note that an assignment of one matrix to another, as in `m2: m1',
     does not copy `m1'.  An assignment `m2 [i,j]: x' or `setelmx(x, i,
     j, m2)' also modifies `m1 [i,j]'.  Creating a copy with
     `copymatrix' and then using assignment creates a separate,
     modified copy.


 -- Function: determinant (<M>)
     Computes the determinant of <M> by a method similar to Gaussian
     elimination.

     The form of the result depends upon the setting of the switch
     `ratmx'.

     There is a special routine for computing sparse determinants which
     is called when the switches `ratmx' and `sparse' are both `true'.


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

     When `detout' is `true', the determinant of a matrix whose inverse
     is computed is factored out of the inverse.

     For this switch to have an effect `doallmxops' and `doscmxops'
     should be `false' (see their descriptions).  Alternatively this
     switch can be given to `ev' which causes the other two to be set
     correctly.

     Example:

          (%i1) m: matrix ([a, b], [c, d]);
                                      [ a  b ]
          (%o1)                       [      ]
                                      [ c  d ]
          (%i2) detout: true$
          (%i3) doallmxops: false$
          (%i4) doscmxops: false$
          (%i5) invert (m);
                                    [  d   - b ]
                                    [          ]
                                    [ - c   a  ]
          (%o5)                     ------------
                                     a d - b c


 -- Function: diagmatrix (<n>, <x>)
     Returns a diagonal matrix of size <n> by <n> with the diagonal
     elements all equal to <x>.  `diagmatrix (<n>, 1)' returns an
     identity matrix (same as `ident (<n>)').

     <n> must evaluate to an integer, otherwise `diagmatrix' complains
     with an error message.

     <x> can be any kind of expression, including another matrix.  If
     <x> is a matrix, it is not copied; all diagonal elements refer to
     the same instance, <x>.


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

     When `doallmxops' is `true', all operations relating to matrices
     are carried out.  When it is `false' then the setting of the
     individual `dot' switches govern which operations are performed.


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

     When `domxexpt' is `true', a matrix exponential, `exp (<M>)' where
     <M> is a matrix, is interpreted as a matrix with element `[i,j]'
     equal to `exp (m[i,j])'.  Otherwise `exp (<M>)' evaluates to `exp
     (<ev(M)>)'.

     `domxexpt' affects all expressions of the form `<base>^<power>'
     where <base> is an expression assumed scalar or constant, and
     <power> is a list or matrix.

     Example:

          (%i1) m: matrix ([1, %i], [a+b, %pi]);
                                   [   1    %i  ]
          (%o1)                    [            ]
                                   [ b + a  %pi ]
          (%i2) domxexpt: false$
          (%i3) (1 - c)^m;
                                       [   1    %i  ]
                                       [            ]
                                       [ b + a  %pi ]
          (%o3)                 (1 - c)
          (%i4) domxexpt: true$
          (%i5) (1 - c)^m;
                            [                      %i  ]
                            [    1 - c      (1 - c)    ]
          (%o5)             [                          ]
                            [        b + a         %pi ]
                            [ (1 - c)       (1 - c)    ]


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

     When `domxmxops' is `true', all matrix-matrix or matrix-list
     operations are carried out (but not scalar-matrix operations); if
     this switch is `false' such operations are not carried out.


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

     When `domxnctimes' is `true', non-commutative products of matrices
     are carried out.


 -- Option variable: dontfactor
     Default value: `[]'

     `dontfactor' may be set to a list of variables with respect to
     which factoring is not to occur.  (The list is initially empty.)
     Factoring also will not take place with respect to any variables
     which are less important, according the variable ordering assumed
     for canonical rational expression (CRE) form, than those on the
     `dontfactor' list.


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

     When `doscmxops' is `true', scalar-matrix operations are carried
     out.


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

     When `doscmxplus' is `true', scalar-matrix operations yield a
     matrix result.  This switch is not subsumed under `doallmxops'.


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

     When `dot0nscsimp' is `true', a non-commutative product of zero
     and a nonscalar term is simplified to a commutative product.


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

     When `dot0simp' is `true', a non-commutative product of zero and a
     scalar term is simplified to a commutative product.


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

     When `dot1simp' is `true', a non-commutative product of one and
     another term is simplified to a commutative product.


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

     When `dotassoc' is `true', an expression `(A.B).C' simplifies to
     `A.(B.C)'.


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

     When `dotconstrules' is `true', a non-commutative product of a
     constant and another term is simplified to a commutative product.
     Turning on this flag effectively turns on `dot0simp',
     `dot0nscsimp', and `dot1simp' as well.


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

     When `dotdistrib' is `true', an expression `A.(B + C)' simplifies
     to `A.B + A.C'.


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

     When `dotexptsimp' is `true', an expression `A.A' simplifies to
     `A^^2'.


 -- Option variable: dotident
     Default value: 1

     `dotident' is the value returned by `X^^0'.


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

     When `dotscrules' is `true', an expression `A.SC' or `SC.A'
     simplifies to `SC*A' and `A.(SC*B)' simplifies to `SC*(A.B)'.


 -- Function: echelon (<M>)
     Returns the echelon form of the matrix <M>, as produced by
     Gaussian elimination.  The echelon form is computed from <M> by
     elementary row operations such that the first non-zero element in
     each row in the resulting matrix is one and the column elements
     under the first one in each row are all zero.

     `triangularize' also carries out Gaussian elimination, but it does
     not normalize the leading non-zero element in each row.

     `lu_factor' and `cholesky' are other functions which yield
     triangularized matrices.

          (%i1) M: matrix ([3, 7, aa, bb], [-1, 8, 5, 2], [9, 2, 11, 4]);
                                 [  3   7  aa  bb ]
                                 [                ]
          (%o1)                  [ - 1  8  5   2  ]
                                 [                ]
                                 [  9   2  11  4  ]
          (%i2) echelon (M);
                            [ 1  - 8  - 5      - 2     ]
                            [                          ]
                            [         28       11      ]
                            [ 0   1   --       --      ]
          (%o2)             [         37       37      ]
                            [                          ]
                            [              37 bb - 119 ]
                            [ 0   0    1   ----------- ]
                            [              37 aa - 313 ]


 -- Function: eigenvalues (<M>)
 -- Function: eivals (<M>)
     Returns a list of two lists containing the eigenvalues of the
     matrix <M>.  The first sublist of the return value is the list of
     eigenvalues of the matrix, and the second sublist is the list of
     the multiplicities of the eigenvalues in the corresponding order.

     `eivals' is a synonym for `eigenvalues'.

     `eigenvalues' calls the function `solve' to find the roots of the
     characteristic polynomial of the matrix.  Sometimes `solve' may
     not be able to find the roots of the polynomial; in that case some
     other functions in this package (except `innerproduct',
     `unitvector', `columnvector' and `gramschmidt') will not work.

     In some cases the eigenvalues found by `solve' may be complicated
     expressions.  (This may happen when `solve' returns a
     not-so-obviously real expression for an eigenvalue which is known
     to be real.)  It may be possible to simplify the eigenvalues using
     some other functions.

     The package `eigen.mac' is loaded automatically when `eigenvalues'
     or `eigenvectors' is referenced.  If `eigen.mac' is not already
     loaded, `load ("eigen")' loads it.  After loading, all functions
     and variables in the package are available.


 -- Function: eigenvectors (<M>)
 -- Function: eivects (<M>)
     Computes eigenvectors of the matrix <M>.  The return value is a
     list of two elements.  The first is a list of the eigenvalues of
     <M> and a list of the multiplicities of the eigenvalues.  The
     second is a list of lists of eigenvectors.  There is one list of
     eigenvectors for each eigenvalue.  There may be one or more
     eigenvectors in each list.

     `eivects' is a synonym for `eigenvectors'.

     The package `eigen.mac' is loaded automatically when `eigenvalues'
     or `eigenvectors' is referenced.  If `eigen.mac' is not already
     loaded, `load ("eigen")' loads it.  After loading, all functions
     and variables in the package are available.

     The flags that affect this function are:

     `nondiagonalizable' is set to `true' or `false' depending on
     whether the matrix is nondiagonalizable or diagonalizable after
     `eigenvectors' returns.

     `hermitianmatrix' when `true', causes the degenerate eigenvectors
     of the Hermitian matrix to be orthogonalized using the
     Gram-Schmidt algorithm.

     `knowneigvals' when `true' causes the `eigen' package to assume
     the eigenvalues of the matrix are known to the user and stored
     under the global name `listeigvals'.  `listeigvals' should be set
     to a list similar to the output `eigenvalues'.

     The function `algsys' is used here to solve for the eigenvectors.
     Sometimes if the eigenvalues are messy, `algsys' may not be able
     to find a solution.  In some cases, it may be possible to simplify
     the eigenvalues by first finding them using `eigenvalues' command
     and then using other functions to reduce them to something
     simpler.  Following simplification, `eigenvectors' can be called
     again with the `knowneigvals' flag set to `true'.

     See also `eigenvalues'.

     Examples:

     A matrix which has just one eigenvector per eigenvalue.

          (%i1) M1 : matrix ([11, -1], [1, 7]);
                                     [ 11  - 1 ]
          (%o1)                      [         ]
                                     [ 1    7  ]
          (%i2) [vals, vecs] : eigenvectors (M1);
          (%o2) [[[9 - sqrt(3), sqrt(3) + 9], [1, 1]],
                                  [[[1, sqrt(3) + 2]], [[1, 2 - sqrt(3)]]]]
          (%i3) for i thru length (vals[1]) do disp (val[i] = vals[1][i],
            mult[i] = vals[2][i], vec[i] = vecs[i]);
                                 val  = 9 - sqrt(3)
                                    1

                                      mult  = 1
                                          1

                              vec  = [[1, sqrt(3) + 2]]
                                 1

                                 val  = sqrt(3) + 9
                                    2

                                      mult  = 1
                                          2

                              vec  = [[1, 2 - sqrt(3)]]
                                 2

          (%o3)                         done

     A matrix which has two eigenvectors for one eigenvalue (namely 2).

          (%i1) M1 : matrix ([0, 1, 0, 0], [0, 0, 0, 0], [0, 0, 2, 0],
                             [0, 0, 0, 2]);
                                   [ 0  1  0  0 ]
                                   [            ]
                                   [ 0  0  0  0 ]
          (%o1)                    [            ]
                                   [ 0  0  2  0 ]
                                   [            ]
                                   [ 0  0  0  2 ]
          (%i2) [vals, vecs] : eigenvectors (M1);
          (%o2) [[[0, 2], [2, 2]], [[[1, 0, 0, 0]],
                                             [[0, 0, 1, 0], [0, 0, 0, 1]]]]
          (%i3) for i thru length (vals[1]) do disp (val[i] = vals[1][i],
            mult[i] = vals[2][i], vec[i] = vecs[i]);
                                      val  = 0
                                         1

                                      mult  = 2
                                          1

                                vec  = [[1, 0, 0, 0]]
                                   1

                                      val  = 2
                                         2

                                      mult  = 2
                                          2

                         vec  = [[0, 0, 1, 0], [0, 0, 0, 1]]
                            2

          (%o3)                         done


 -- Function: ematrix (<m>, <n>, <x>, <i>, <j>)
     Returns an <m> by <n> matrix, all elements of which are zero
     except for the `[<i>, <j>]' element which is <x>.


 -- Function: entermatrix (<m>, <n>)
     Returns an <m> by <n> matrix, reading the elements interactively.

     If <n> is equal to <m>, Maxima prompts for the type of the matrix
     (diagonal, symmetric, antisymmetric, or general) and for each
     element.  Each response is terminated by a semicolon `;' or dollar
     sign `$'.

     If <n> is not equal to <m>, Maxima prompts for each element.

     The elements may be any expressions, which are evaluated.
     `entermatrix' evaluates its arguments.

          (%i1) n: 3$
          (%i2) m: entermatrix (n, n)$

          Is the matrix  1. Diagonal  2. Symmetric  3. Antisymmetric
          4. General
          Answer 1, 2, 3 or 4 :
          1$
          Row 1 Column 1:
          (a+b)^n$
          Row 2 Column 2:
          (a+b)^(n+1)$
          Row 3 Column 3:
          (a+b)^(n+2)$

          Matrix entered.
          (%i3) m;
                          [        3                     ]
                          [ (b + a)      0         0     ]
                          [                              ]
          (%o3)           [                  4           ]
                          [    0      (b + a)      0     ]
                          [                              ]
                          [                            5 ]
                          [    0         0      (b + a)  ]


 -- Function: genmatrix (<a>, <i_2>, <j_2>, <i_1>, <j_1>)
 -- Function: genmatrix (<a>, <i_2>, <j_2>, <i_1>)
 -- Function: genmatrix (<a>, <i_2>, <j_2>)
     Returns a matrix generated from <a>, taking element `<a>[<i_1>,
     <j_1>]' as the upper-left element and `<a>[<i_2>, <j_2>]' as the
     lower-right element of the matrix.  Here <a> is a declared array
     (created by `array' but not by `make_array') or an undeclared
     array, or an array function, or a lambda expression of two
     arguments.  (An array function is created like other functions
     with `:=' or `define', but arguments are enclosed in square
     brackets instead of parentheses.)

     If <j_1> is omitted, it is assumed equal to <i_1>.  If both <j_1>
     and <i_1> are omitted, both are assumed equal to 1.

     If a selected element `i,j' of the array is undefined, the matrix
     will contain a symbolic element `<a>[i,j]'.

     Examples:

          (%i1) h [i, j] := 1 / (i + j - 1);
                                              1
          (%o1)                  h     := ---------
                                  i, j    i + j - 1
          (%i2) genmatrix (h, 3, 3);
                                     [    1  1 ]
                                     [ 1  -  - ]
                                     [    2  3 ]
                                     [         ]
                                     [ 1  1  1 ]
          (%o2)                      [ -  -  - ]
                                     [ 2  3  4 ]
                                     [         ]
                                     [ 1  1  1 ]
                                     [ -  -  - ]
                                     [ 3  4  5 ]
          (%i3) array (a, fixnum, 2, 2);
          (%o3)                           a
          (%i4) a [1, 1] : %e;
          (%o4)                          %e
          (%i5) a [2, 2] : %pi;
          (%o5)                          %pi
          (%i6) genmatrix (a, 2, 2);
                                     [ %e   0  ]
          (%o6)                      [         ]
                                     [ 0   %pi ]
          (%i7) genmatrix (lambda ([i, j], j - i), 3, 3);
                                   [  0    1   2 ]
                                   [             ]
          (%o7)                    [ - 1   0   1 ]
                                   [             ]
                                   [ - 2  - 1  0 ]
          (%i8) genmatrix (B, 2, 2);
                                  [ B      B     ]
                                  [  1, 1   1, 2 ]
          (%o8)                   [              ]
                                  [ B      B     ]
                                  [  2, 1   2, 2 ]


 -- Function: gramschmidt (<x>)
 -- Function: gramschmidt (<x>, <F>)
     Carries out the Gram-Schmidt orthogonalization algorithm on <x>,
     which is either a matrix or a list of lists.  <x> is not modified
     by `gramschmidt'.  The inner product employed by `gramschmidt' is
     <F>, if present, otherwise the inner product is the function
     `innerproduct'.

     If <x> is a matrix, the algorithm is applied to the rows of <x>.
     If <x> is a list of lists, the algorithm is applied to the
     sublists, which must have equal numbers of elements.  In either
     case, the return value is a list of lists, the sublists of which
     are orthogonal and span the same space as <x>.  If the dimension
     of the span of <x> is less than the number of rows or sublists,
     some sublists of the return value are zero.

     `factor' is called at each stage of the algorithm to simplify
     intermediate results.  As a consequence, the return value may
     contain factored integers.

     `load(eigen)' loads this function.

     Example:

     Gram-Schmidt algorithm using default inner product function.

          (%i1) load (eigen)$
          (%i2) x: matrix ([1, 2, 3], [9, 18, 30], [12, 48, 60]);
                                   [ 1   2   3  ]
                                   [            ]
          (%o2)                    [ 9   18  30 ]
                                   [            ]
                                   [ 12  48  60 ]
          (%i3) y: gramschmidt (x);
                                 2      2            4     3
                                3      3   3 5      2  3  2  3
          (%o3)  [[1, 2, 3], [- ---, - --, ---], [- ----, ----, 0]]
                                2 7    7   2 7       5     5
          (%i4) map (innerproduct, [y[1], y[2], y[3]], [y[2], y[3], y[1]]);
          (%o4)                       [0, 0, 0]

     Gram-Schmidt algorithm using a specified inner product function.

          (%i1) load (eigen)$
          (%i2) ip (f, g) := integrate (f * g, u, a, b);
          (%o2)          ip(f, g) := integrate(f g, u, a, b)
          (%i3) y : gramschmidt([1, sin(u), cos(u)], ip), a= -%pi/2, b=%pi/2;
                                         %pi cos(u) - 2
          (%o3)              [1, sin(u), --------------]
                                              %pi
          (%i4) map (ip, [y[1], y[2], y[3]], [y[2], y[3], y[1]]),
                                                          a= -%pi/2, b=%pi/2;
          (%o4)                       [0, 0, 0]


 -- Function: ident (<n>)
     Returns an <n> by <n> identity matrix.


 -- Function: innerproduct (<x>, <y>)
 -- Function: inprod (<x>, <y>)
     Returns the inner product (also called the scalar product or dot
     product) of <x> and <y>, which are lists of equal length, or both
     1-column or 1-row matrices of equal length.  The return value is
     `conjugate (x) . y', where `.' is the noncommutative
     multiplication operator.

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

     `inprod' is a synonym for `innerproduct'.


 -- Function: invert (<M>)
     Returns the inverse of the matrix <M>.  The inverse is computed
     via the LU decomposition.

     When `ratmx' is `true', elements of <M> are converted to canonical
     rational expressions (CRE), and the elements of the return value
     are also CRE.

     When `ratmx' is `false', elements of <M> are not converted to a
     common representation.  In particular, float and bigfloat elements
     are not converted to rationals.

     When `detout' is `true', the determinant is factored out of the
     inverse.  The global flags `doallmxops' and `doscmxops' must be
     `false' to prevent the determinant from being absorbed into the
     inverse.  `xthru' can multiply the determinant into the inverse.

     `invert' does not apply any simplifications to the elements of the
     inverse apart from the default arithmetic simplifications.
     `ratsimp' and `expand' can apply additional simplifications.  In
     particular, when <M> has polynomial elements,
     `expand(invert(<M>))' might be preferable.

     `invert(<M>)' is equivalent to `<M>^^-1'.


 -- Function: list_matrix_entries (<M>)
     Returns a list containing the elements of the matrix <M>.

     Example:

          (%i1) list_matrix_entries(matrix([a,b],[c,d]));
          (%o1)                     [a, b, c, d]


 -- Option variable: lmxchar
     Default value: `['

     `lmxchar' is the character displayed as the left delimiter of a
     matrix.  See also `rmxchar'.

     Example:

          (%i1) lmxchar: "|"$
          (%i2) matrix ([a, b, c], [d, e, f], [g, h, i]);
                                     | a  b  c ]
                                     |         ]
          (%o2)                      | d  e  f ]
                                     |         ]
                                     | g  h  i ]


 -- Function: matrix (<row_1>, ..., <row_n>)
     Returns a rectangular matrix which has the rows <row_1>, ...,
     <row_n>.  Each row is a list of expressions.  All rows must be the
     same length.

     The operations `+' (addition), `-' (subtraction), `*'
     (multiplication), and `/' (division), are carried out element by
     element when the operands are two matrices, a scalar and a matrix,
     or a matrix and a scalar.  The operation `^' (exponentiation,
     equivalently `**') is carried out element by element if the
     operands are a scalar and a matrix or a matrix and a scalar, but
     not if the operands are two matrices.  All operations are normally
     carried out in full, including `.' (noncommutative multiplication).

     Matrix multiplication is represented by the noncommutative
     multiplication operator `.'.  The corresponding noncommutative
     exponentiation operator is `^^'.  For a matrix `<A>', `<A>.<A> =
     <A>^^2' and `<A>^^-1' is the inverse of <A>, if it exists.
     `<A>^^-1' is equivalent to `invert(<A>)'.

     There are switches for controlling simplification of expressions
     involving dot and matrix-list operations.  These are `doallmxops',
     `domxexpt', `domxmxops', `doscmxops', and `doscmxplus'.

     There are additional options which are related to matrices.  These
     are: `lmxchar', `rmxchar', `ratmx', `listarith', `detout',
     `scalarmatrix' and `sparse'.

     There are a number of functions which take matrices as arguments
     or yield matrices as return values.  See `eigenvalues',
     `eigenvectors', `determinant', `charpoly', `genmatrix', `addcol',
     `addrow', `copymatrix', `transpose', `echelon', and `rank'.

     Examples:

        * Construction of matrices from lists.

          (%i1) x: matrix ([17, 3], [-8, 11]);
                                     [ 17   3  ]
          (%o1)                      [         ]
                                     [ - 8  11 ]
          (%i2) y: matrix ([%pi, %e], [a, b]);
                                     [ %pi  %e ]
          (%o2)                      [         ]
                                     [  a   b  ]

        * Addition, element by element.

          (%i3) x + y;
                                [ %pi + 17  %e + 3 ]
          (%o3)                 [                  ]
                                [  a - 8    b + 11 ]

        * Subtraction, element by element.

          (%i4) x - y;
                                [ 17 - %pi  3 - %e ]
          (%o4)                 [                  ]
                                [ - a - 8   11 - b ]

        * Multiplication, element by element.

          (%i5) x * y;
                                  [ 17 %pi  3 %e ]
          (%o5)                   [              ]
                                  [ - 8 a   11 b ]

        * Division, element by element.

          (%i6) x / y;
                                  [ 17       - 1 ]
                                  [ ---  3 %e    ]
                                  [ %pi          ]
          (%o6)                   [              ]
                                  [   8    11    ]
                                  [ - -    --    ]
                                  [   a    b     ]

        * Matrix to a scalar exponent, element by element.

          (%i7) x ^ 3;
                                   [ 4913    27  ]
          (%o7)                    [             ]
                                   [ - 512  1331 ]

        * Scalar base to a matrix exponent, element by element.

          (%i8) exp(y);
                                   [   %pi    %e ]
                                   [ %e     %e   ]
          (%o8)                    [             ]
                                   [    a     b  ]
                                   [  %e    %e   ]

        * Matrix base to a matrix exponent.  This is not carried out
          element by element.

          (%i9) x ^ y;
                                          [ %pi  %e ]
                                          [         ]
                                          [  a   b  ]
                               [ 17   3  ]
          (%o9)                [         ]
                               [ - 8  11 ]

        * Noncommutative matrix multiplication.

          (%i10) x . y;
                            [ 3 a + 17 %pi  3 b + 17 %e ]
          (%o10)            [                           ]
                            [ 11 a - 8 %pi  11 b - 8 %e ]
          (%i11) y . x;
                          [ 17 %pi - 8 %e  3 %pi + 11 %e ]
          (%o11)          [                              ]
                          [  17 a - 8 b     11 b + 3 a   ]

        * Noncommutative matrix exponentiation.  A scalar base <b> to a
          matrix power <M> is carried out element by element and so
          `b^^m' is the same as `b^m'.

          (%i12) x ^^ 3;
                                  [  3833   1719 ]
          (%o12)                  [              ]
                                  [ - 4584  395  ]
          (%i13) %e ^^ y;
                                   [   %pi    %e ]
                                   [ %e     %e   ]
          (%o13)                   [             ]
                                   [    a     b  ]
                                   [  %e    %e   ]

        * A matrix raised to a -1 exponent with noncommutative
          exponentiation is the matrix inverse, if it exists.

          (%i14) x ^^ -1;
                                   [ 11      3  ]
                                   [ ---  - --- ]
                                   [ 211    211 ]
          (%o14)                   [            ]
                                   [  8    17   ]
                                   [ ---   ---  ]
                                   [ 211   211  ]
          (%i15) x . (x ^^ -1);
                                      [ 1  0 ]
          (%o15)                      [      ]
                                      [ 0  1 ]


 -- Function: matrixmap (<f>, <M>)
     Returns a matrix with element `i,j' equal to `<f>(<M>[i,j])'.

     See also `map', `fullmap', `fullmapl', and `apply'.


 -- Function: matrixp (<expr>)
     Returns `true' if <expr> is a matrix, otherwise `false'.


 -- Option variable: matrix_element_add
     Default value: `+'

     `matrix_element_add' is the operation invoked in place of addition
     in a matrix multiplication.  `matrix_element_add' can be assigned
     any n-ary operator (that is, a function which handles any number
     of arguments).  The assigned value may be the name of an operator
     enclosed in quote marks, the name of a function, or a lambda
     expression.

     See also `matrix_element_mult' and `matrix_element_transpose'.

     Example:

          (%i1) matrix_element_add: "*"$
          (%i2) matrix_element_mult: "^"$
          (%i3) aa: matrix ([a, b, c], [d, e, f]);
                                     [ a  b  c ]
          (%o3)                      [         ]
                                     [ d  e  f ]
          (%i4) bb: matrix ([u, v, w], [x, y, z]);
                                     [ u  v  w ]
          (%o4)                      [         ]
                                     [ x  y  z ]
          (%i5) aa . transpose (bb);
                               [  u  v  w   x  y  z ]
                               [ a  b  c   a  b  c  ]
          (%o5)                [                    ]
                               [  u  v  w   x  y  z ]
                               [ d  e  f   d  e  f  ]


 -- Option variable: matrix_element_mult
     Default value: `*'

     `matrix_element_mult' is the operation invoked in place of
     multiplication in a matrix multiplication.  `matrix_element_mult'
     can be assigned any binary operator.  The assigned value may be
     the name of an operator enclosed in quote marks, the name of a
     function, or a lambda expression.

     The dot operator `.' is a useful choice in some contexts.

     See also `matrix_element_add' and `matrix_element_transpose'.

     Example:

          (%i1) matrix_element_add: lambda ([[x]], sqrt (apply ("+", x)))$
          (%i2) matrix_element_mult: lambda ([x, y], (x - y)^2)$
          (%i3) [a, b, c] . [x, y, z];
                                    2          2          2
          (%o3)         sqrt((c - z)  + (b - y)  + (a - x) )
          (%i4) aa: matrix ([a, b, c], [d, e, f]);
                                     [ a  b  c ]
          (%o4)                      [         ]
                                     [ d  e  f ]
          (%i5) bb: matrix ([u, v, w], [x, y, z]);
                                     [ u  v  w ]
          (%o5)                      [         ]
                                     [ x  y  z ]
          (%i6) aa . transpose (bb);
                         [             2          2          2  ]
                         [ sqrt((c - w)  + (b - v)  + (a - u) ) ]
          (%o6)  Col 1 = [                                      ]
                         [             2          2          2  ]
                         [ sqrt((f - w)  + (e - v)  + (d - u) ) ]

                                   [             2          2          2  ]
                                   [ sqrt((c - z)  + (b - y)  + (a - x) ) ]
                           Col 2 = [                                      ]
                                   [             2          2          2  ]
                                   [ sqrt((f - z)  + (e - y)  + (d - x) ) ]


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

     `matrix_element_transpose' is the operation applied to each
     element of a matrix when it is transposed.  `matrix_element_mult'
     can be assigned any unary operator.  The assigned value may be the
     name of an operator enclosed in quote marks, the name of a
     function, or a lambda expression.

     When `matrix_element_transpose' equals `transpose', the
     `transpose' function is applied to every element.  When
     `matrix_element_transpose' equals `nonscalars', the `transpose'
     function is applied to every nonscalar element.  If some element
     is an atom, the `nonscalars' option applies `transpose' only if
     the atom is declared nonscalar, while the `transpose' option
     always applies `transpose'.

     The default value, `false', means no operation is applied.

     See also `matrix_element_add' and `matrix_element_mult'.

     Examples:

          (%i1) declare (a, nonscalar)$
          (%i2) transpose ([a, b]);
                                  [ transpose(a) ]
          (%o2)                   [              ]
                                  [      b       ]
          (%i3) matrix_element_transpose: nonscalars$
          (%i4) transpose ([a, b]);
                                  [ transpose(a) ]
          (%o4)                   [              ]
                                  [      b       ]
          (%i5) matrix_element_transpose: transpose$
          (%i6) transpose ([a, b]);
                                  [ transpose(a) ]
          (%o6)                   [              ]
                                  [ transpose(b) ]
          (%i7) matrix_element_transpose: lambda ([x], realpart(x)
                - %i*imagpart(x))$
          (%i8) m: matrix ([1 + 5*%i, 3 - 2*%i], [7*%i, 11]);
                               [ 5 %i + 1  3 - 2 %i ]
          (%o8)                [                    ]
                               [   7 %i       11    ]
          (%i9) transpose (m);
                                [ 1 - 5 %i  - 7 %i ]
          (%o9)                 [                  ]
                                [ 2 %i + 3    11   ]


 -- Function: mattrace (<M>)
     Returns the trace (that is, the sum of the elements on the main
     diagonal) of the square matrix <M>.

     `mattrace' is called by `ncharpoly', an alternative to Maxima's
     `charpoly'.

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


 -- Function: minor (<M>, <i>, <j>)
     Returns the <i>, <j> minor of the matrix <M>.  That is, <M> with
     row <i> and column <j> removed.


 -- Function: ncharpoly (<M>, <x>)
     Returns the characteristic polynomial of the matrix <M> with
     respect to <x>.  This is an alternative to Maxima's `charpoly'.

     `ncharpoly' works by computing traces of powers of the given
     matrix, which are known to be equal to sums of powers of the roots
     of the characteristic polynomial.  From these quantities the
     symmetric functions of the roots can be calculated, which are
     nothing more than the coefficients of the characteristic
     polynomial.  `charpoly' works by forming the determinant of `<x> *
     ident [n] - a'.  Thus `ncharpoly' wins, for example, in the case
     of large dense matrices filled with integers, since it avoids
     polynomial arithmetic altogether.

     `load ("nchrpl")' loads this file.


 -- Function: newdet (<M>)
     Computes the determinant of the matrix <M> by the
     Johnson-Gentleman tree minor algorithm.  `newdet' returns the
     result in CRE form.


 -- Function: permanent (<M>)
     Computes the permanent of the matrix <M> by the Johnson-Gentleman
     tree minor algorithm.  A permanent is like a determinant but with
     no sign changes.  `permanent' returns the result in CRE form.

     See also `newdet'.


 -- Function: rank (<M>)
     Computes the rank of the matrix <M>.  That is, the order of the
     largest non-singular subdeterminant of <M>.

     <rank> may return the wrong answer if it cannot determine that a
     matrix element that is equivalent to zero is indeed so.


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

     When `ratmx' is `false', determinant and matrix addition,
     subtraction, and multiplication are performed in the
     representation of the matrix elements and cause the result of
     matrix inversion to be left in general representation.

     When `ratmx' is `true', the 4 operations mentioned above are
     performed in CRE form and the result of matrix inverse is in CRE
     form.  Note that this may cause the elements to be expanded
     (depending on the setting of `ratfac') which might not always be
     desired.


 -- Function: row (<M>, <i>)
     Returns the <i>'th row of the matrix <M>.  The return value is a
     matrix.


 -- Option variable: rmxchar
     Default value: `]'

     `rmxchar' is the character drawn on the right-hand side of a
     matrix.

     See also `lmxchar'.


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

     When `scalarmatrixp' is `true', then whenever a 1 x 1 matrix is
     produced as a result of computing the dot product of matrices it
     is simplified to a scalar, namely the sole element of the matrix.

     When `scalarmatrixp' is `all', then all 1 x 1 matrices are
     simplified to scalars.

     When `scalarmatrixp' is `false', 1 x 1 matrices are not simplified
     to scalars.


 -- Function: scalefactors (<coordinatetransform>)
     Here the argument <coordinatetransform> evaluates to the form
     `[[expression1, expression2, ...], indeterminate1, indeterminat2,
     ...]', where the variables <indeterminate1>, <indeterminate2>,
     etc. are the curvilinear coordinate variables and where a set of
     rectangular Cartesian components is given in terms of the
     curvilinear coordinates by `[expression1, expression2, ...]'.
     `coordinates' is set to the vector `[indeterminate1,
     indeterminate2,...]', and `dimension' is set to the length of this
     vector.  SF[1], SF[2], ..., SF[DIMENSION] are set to the
     coordinate scale factors, and `sfprod' is set to the product of
     these scale factors.  Initially, `coordinates' is `[X, Y, Z]',
     `dimension' is 3, and SF[1]=SF[2]=SF[3]=SFPROD=1, corresponding to
     3-dimensional rectangular Cartesian coordinates.  To expand an
     expression into physical components in the current coordinate
     system, there is a function with usage of the form


 -- Function: setelmx (<x>, <i>, <j>, <M>)
     Assigns <x> to the (<i>, <j>)'th element of the matrix <M>, and
     returns the altered matrix.

     `<M> [<i>, <j>]: <x>' has the same effect, but returns <x> instead
     of <M>.


 -- Function: similaritytransform (<M>)
 -- Function: simtran (<M>)
     `similaritytransform' computes a similarity transform of the matrix
     `M'.  It returns a list which is the output of the
     `uniteigenvectors' command.  In addition if the flag
     `nondiagonalizable' is `false' two global matrices `leftmatrix'
     and `rightmatrix' are computed.  These matrices have the property
     that `leftmatrix . <M> . rightmatrix' is a diagonal matrix with
     the eigenvalues of <M> on the diagonal.  If `nondiagonalizable' is
     `true' the left and right matrices are not computed.

     If the flag `hermitianmatrix' is `true' then `leftmatrix' is the
     complex conjugate of the transpose of `rightmatrix'.  Otherwise
     `leftmatrix' is the inverse of `rightmatrix'.

     `rightmatrix' is the matrix the columns of which are the unit
     eigenvectors of <M>.  The other flags (see `eigenvalues' and
     `eigenvectors') have the same effects since `similaritytransform'
     calls the other functions in the package in order to be able to
     form `rightmatrix'.

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

     `simtran' is a synonym for `similaritytransform'.


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

     When `sparse' is `true', and if `ratmx' is `true', then
     `determinant' will use special routines for computing sparse
     determinants.


 -- Function: submatrix (<i_1>, ..., <i_m>, <M>, <j_1>, ..., <j_n>)
 -- Function: submatrix (<i_1>, ..., <i_m>, <M>)
 -- Function: submatrix (<M>, <j_1>, ..., <j_n>)
     Returns a new matrix composed of the matrix <M> with rows <i_1>,
     ..., <i_m> deleted, and columns <j_1>, ..., <j_n> deleted.


 -- Function: transpose (<M>)
     Returns the transpose of <M>.

     If <M> is a matrix, the return value is another matrix <N> such
     that `N[i,j] = M[j,i]'.

     If <M> is a list, the return value is a matrix <N> of `length (m)'
     rows and 1 column, such that `N[i,1] = M[i]'.

     Otherwise <M> is a symbol, and the return value is a noun
     expression `'transpose (<M>)'.


 -- Function: triangularize (<M>)
     Returns the upper triangular form of the matrix `M', as produced
     by Gaussian elimination.  The return value is the same as
     `echelon', except that the leading nonzero coefficient in each row
     is not normalized to 1.

     `lu_factor' and `cholesky' are other functions which yield
     triangularized matrices.

          (%i1) M: matrix ([3, 7, aa, bb], [-1, 8, 5, 2], [9, 2, 11, 4]);
                                 [  3   7  aa  bb ]
                                 [                ]
          (%o1)                  [ - 1  8  5   2  ]
                                 [                ]
                                 [  9   2  11  4  ]
          (%i2) triangularize (M);
                       [ - 1   8         5            2      ]
                       [                                     ]
          (%o2)        [  0   - 74     - 56         - 22     ]
                       [                                     ]
                       [  0    0    626 - 74 aa  238 - 74 bb ]


 -- Function: uniteigenvectors (<M>)
 -- Function: ueivects (<M>)
     Computes unit eigenvectors of the matrix <M>.  The return value is
     a list of lists, the first sublist of which is the output of the
     `eigenvalues' command, and the other sublists of which are the
     unit eigenvectors of the matrix corresponding to those eigenvalues
     respectively.

     The flags mentioned in the description of the `eigenvectors'
     command have the same effects in this one as well.

     When `knowneigvects' is `true', the `eigen' package assumes that
     the eigenvectors of the matrix are known to the user and are
     stored under the global name `listeigvects'.  `listeigvects' should
     be set to a list similar to the output of the `eigenvectors'
     command.

     If `knowneigvects' is set to `true' and the list of eigenvectors is
     given the setting of the flag `nondiagonalizable' may not be
     correct.  If that is the case please set it to the correct value.
     The author assumes that the user knows what he is doing and will
     not try to diagonalize a matrix the eigenvectors of which do not
     span the vector space of the appropriate dimension.

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

     `ueivects' is a synonym for `uniteigenvectors'.


 -- Function: unitvector (<x>)
 -- Function: uvect (<x>)
     Returns <x>/norm(<x>); this is a unit vector in the same direction
     as <x>.

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

     `uvect' is a synonym for `unitvector'.


 -- Function: vectorpotential (<givencurl>)
     Returns the vector potential of a given curl vector, in the
     current coordinate system.  `potentialzeroloc' has a similar role
     as for `potential', but the order of the left-hand sides of the
     equations must be a cyclic permutation of the coordinate variables.


 -- Function: vectorsimp (<expr>)
     Applies simplifications and expansions according to the following
     global flags:

     `expandall', `expanddot', `expanddotplus', `expandcross', `expandcrossplus',
     `expandcrosscross', `expandgrad', `expandgradplus', `expandgradprod',
     `expanddiv', `expanddivplus', `expanddivprod', `expandcurl', `expandcurlplus',
     `expandcurlcurl', `expandlaplacian', `expandlaplacianplus',
     and `expandlaplacianprod'.

     All these flags have default value `false'.  The `plus' suffix
     refers to employing additivity or distributivity.  The `prod'
     suffix refers to the expansion for an operand that is any kind of
     product.

    `expandcrosscross'
          Simplifies p ~ (q ~ r) to (p . r)*q - (p . q)*r.

    `expandcurlcurl'
          Simplifies curl curl p to grad div p + div grad p.

    `expandlaplaciantodivgrad'
          Simplifies laplacian p to div grad p.

    `expandcross'
          Enables `expandcrossplus' and `expandcrosscross'.

    `expandplus'
          Enables `expanddotplus', `expandcrossplus', `expandgradplus',
          `expanddivplus', `expandcurlplus', and `expandlaplacianplus'.

    `expandprod'
          Enables `expandgradprod', `expanddivprod', and
          `expandlaplacianprod'.

     These flags have all been declared `evflag'.


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

     When `vect_cross' is `true', it allows DIFF(X~Y,T) to work where ~
     is defined in SHARE;VECT (where VECT_CROSS is set to `true',
     anyway.)


 -- Function: zeromatrix (<m>, <n>)
     Returns an <m> by <n> matrix, all elements of which are zero.



File: maxima.info,  Node: Affine,  Next: itensor,  Prev: Matrices and Linear Algebra,  Up: Top

24 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

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

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

          grobner_basis ([3*x^2+1, y*x])$

          polysimp (y^2*x + x^3*9 + 2) ==> -3*x + 2

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


 -- 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: itensor,  Next: ctensor,  Prev: Affine,  Up: Top

25 itensor
**********

* Menu:

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


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

25.1 Introduction to itensor
============================

Maxima implements symbolic tensor manipulation of two distinct types:
component tensor manipulation (`ctensor' package) and indicial tensor
manipulation (`itensor' package).

   Nota bene: Please see the note on 'new tensor notation' below.

   Component tensor manipulation means that geometrical tensor objects
are represented as arrays or matrices. Tensor operations such as
contraction or covariant differentiation are carried out by actually
summing over repeated (dummy) indices with `do' statements.  That is,
one explicitly performs operations on the appropriate tensor components
stored in an array or matrix.

   Indicial tensor manipulation is implemented by representing tensors
as functions of their covariant, contravariant and derivative indices.
Tensor operations such as contraction or covariant differentiation are
performed by manipulating the indices themselves rather than the
components to which they correspond.

   These two approaches to the treatment of differential, algebraic and
analytic processes in the context of Riemannian geometry have various
advantages and disadvantages which reveal themselves only through the
particular nature and difficulty of the user's problem.  However, one
should keep in mind the following characteristics of the two
implementations:

   The representation of tensors and tensor operations explicitly in
terms of their components makes `ctensor' easy to use. Specification of
the metric and the computation of the induced tensors and invariants is
straightforward. Although all of Maxima's powerful simplification
capacity is at hand, a complex metric with intricate functional and
coordinate dependencies can easily lead to expressions whose size is
excessive and whose structure is hidden. In addition, many calculations
involve intermediate expressions which swell causing programs to
terminate before completion. Through experience, a user can avoid many
of these difficulties.

   Because of the special way in which tensors and tensor operations
are represented in terms of symbolic operations on their indices,
expressions which in the component representation would be unmanageable
can sometimes be greatly simplified by using the special routines for
symmetrical objects in `itensor'. In this way the structure of a large
expression may be more transparent. On the other hand, because of the
the special indicial representation in `itensor', in some cases the
user may find difficulty with the specification of the metric, function
definition, and the evaluation of differentiated "indexed" objects.

   The `itensor' package can carry out differentiation with respect to
an indexed variable, which allows one to use the package when dealing
with Lagrangian and Hamiltonian formalisms. As it is possible to
differentiate a field Lagrangian with respect to an (indexed) field
variable, one can use Maxima to derive the corresponding Euler-Lagrange
equations in indicial form. These equations can be translated into
component tensor (`ctensor') programs using the `ic_convert' function,
allowing us to solve the field equations in a particular coordinate
representation, or to recast the equations of motion in Hamiltonian
form. See `einhil.dem' and `bradic.dem' for two comprehensive examples.
The first, `einhil.dem', uses the Einstein-Hilbert action to derive the
Einstein field tensor in the homogeneous and isotropic case (Friedmann
equations) and the spherically symmetric, static case (Schwarzschild
solution.) The second, `bradic.dem', demonstrates how to compute the
Friedmann equations from the action of Brans-Dicke gravity theory, and
also derives the Hamiltonian associated with the theory's scalar field.

25.1.1 New tensor notation
--------------------------

Earlier versions of the `itensor' package in Maxima used a notation
that sometimes led to incorrect index ordering. Consider the following,
for instance:

     (%i2) imetric(g);
     (%o2)                                done
     (%i3) ishow(g([],[j,k])*g([],[i,l])*a([i,j],[]))$
                                      i l  j k
     (%t3)                           g    g    a
                                                i j
     (%i4) ishow(contract(%))$
                                           k l
     (%t4)                                a

   This result is incorrect unless `a' happens to be a symmetric tensor.
The reason why this happens is that although `itensor' correctly
maintains the order within the set of covariant and contravariant
indices, once an index is raised or lowered, its position relative to
the other set of indices is lost.

   To avoid this problem, a new notation has been developed that
remains fully compatible with the existing notation and can be used
interchangeably. In this notation, contravariant indices are inserted
in the appropriate positions in the covariant index list, but with a
minus sign prepended.  Functions like `contract' and `ishow' are now
aware of this new index notation and can process tensors appropriately.

   In this new notation, the previous example yields a correct result:

     (%i5) ishow(g([-j,-k],[])*g([-i,-l],[])*a([i,j],[]))$
                                      i l       j k
     (%t5)                           g    a    g
                                           i j
     (%i6) ishow(contract(%))$
                                           l k
     (%t6)                                a

   Presently, the only code that makes use of this notation is the
`lc2kdt' function. Through this notation, it achieves consistent
results as it applies the metric tensor to resolve Levi-Civita symbols
without resorting to numeric indices.

   Since this code is brand new, it probably contains bugs. While it
has been tested to make sure that it doesn't break anything using the
"old" tensor notation, there is a considerable chance that "new"
tensors will fail to interoperate with certain functions or features.
These bugs will be fixed as they are encountered... until then, caveat
emptor!

25.1.2 Indicial tensor manipulation
-----------------------------------

The indicial tensor manipulation package may be loaded by
`load(itensor)'. Demos are also available: try `demo(tensor)'.

   In `itensor' a tensor is represented as an "indexed object" .  This
is a function of 3 groups of indices which represent the covariant,
contravariant and derivative indices.  The covariant indices are
specified by a list as the first argument to the indexed object, and
the contravariant indices by a list as the second argument. If the
indexed object lacks either of these groups of indices then the empty
list `[]' is given as the corresponding argument.  Thus, `g([a,b],[c])'
represents an indexed object called `g' which has two covariant indices
`(a,b)', one contravariant index (`c') and no derivative indices.

   The derivative indices, if they are present, are appended as
additional arguments to the symbolic function representing the tensor.
They can be explicitly specified by the user or be created in the
process of differentiation with respect to some coordinate variable.
Since ordinary differentiation is commutative, the derivative indices
are sorted alphanumerically, unless `iframe_flag' is set to `true',
indicating that a frame metric is being used. This canonical ordering
makes it possible for Maxima to recognize that, for example,
`t([a],[b],i,j)' is the same as `t([a],[b],j,i)'.  Differentiation of
an indexed object with respect to some coordinate whose index does not
appear as an argument to the indexed object would normally yield zero.
This is because Maxima would not know that the tensor represented by
the indexed object might depend implicitly on the corresponding
coordinate.  By modifying the existing Maxima function `diff' in
`itensor', Maxima now assumes that all indexed objects depend on any
variable of differentiation unless otherwise stated.  This makes it
possible for the summation convention to be extended to derivative
indices. It should be noted that `itensor' does not possess the
capabilities of raising derivative indices, and so they are always
treated as covariant.

   The following functions are available in the tensor package for
manipulating indexed objects.  At present, with respect to the
simplification routines, it is assumed that indexed objects do not by
default possess symmetry properties. This can be overridden by setting
the variable `allsym[false]' to `true', which will result in treating
all indexed objects completely symmetric in their lists of covariant
indices and symmetric in their lists of contravariant indices.

   The `itensor' package generally treats tensors as opaque objects.
Tensorial equations are manipulated based on algebraic rules,
specifically symmetry and contraction rules. In addition, the `itensor'
package understands covariant differentiation, curvature, and torsion.
Calculations can be performed relative to a metric of moving frame,
depending on the setting of the `iframe_flag' variable.

   A sample session below demonstrates how to load the `itensor'
package, specify the name of the metric, and perform some simple
calculations.

     (%i1) load(itensor);
     (%o1)      /share/tensor/itensor.lisp
     (%i2) imetric(g);
     (%o2)                                done
     (%i3) components(g([i,j],[]),p([i,j],[])*e([],[]))$
     (%i4) ishow(g([k,l],[]))$
     (%t4)                               e p
                                            k l
     (%i5) ishow(diff(v([i],[]),t))$
     (%t5)                                  0
     (%i6) depends(v,t);
     (%o6)                               [v(t)]
     (%i7) ishow(diff(v([i],[]),t))$
                                         d
     (%t7)                               -- (v )
                                         dt   i
     (%i8) ishow(idiff(v([i],[]),j))$
     (%t8)                                v
                                           i,j
     (%i9) ishow(extdiff(v([i],[]),j))$
     (%t9)                             v    - v
                                        j,i    i,j
                                       -----------
                                            2
     (%i10) ishow(liediff(v,w([i],[])))$
                                    %3          %3
     (%t10)                        v   w     + v   w
                                        i,%3    ,i  %3
     (%i11) ishow(covdiff(v([i],[]),j))$
                                                   %4
     (%t11)                        v    - v   ichr2
                                    i,j    %4      i j
     (%i12) ishow(ev(%,ichr2))$
                     %4 %5
     (%t12) v    - (g      v   (e p       + e   p     - e p       - e    p
             i,j            %4     j %5,i    ,i  j %5      i j,%5    ,%5  i j

                                              + e p       + e   p    ))/2
                                                   i %5,j    ,j  i %5
     (%i13) iframe_flag:true;
     (%o13)                               true
     (%i14) ishow(covdiff(v([i],[]),j))$
                                                  %6
     (%t14)                        v    - v   icc2
                                    i,j    %6     i j
     (%i15) ishow(ev(%,icc2))$
                                                  %6
     (%t15)                        v    - v   ifc2
                                    i,j    %6     i j
     (%i16) ishow(radcan(ev(%,ifc2,ifc1)))$
                  %6 %7                    %6 %7
     (%t16) - (ifg      v   ifb       + ifg      v   ifb       - 2 v
                         %6    j %7 i             %6    i j %7      i,j

                                                  %6 %7
                                             - ifg      v   ifb      )/2
                                                         %6    %7 i j
     (%i17) ishow(canform(s([i,j],[])-s([j,i])))$
     (%t17)                            s    - s
                                        i j    j i
     (%i18) decsym(s,2,0,[sym(all)],[]);
     (%o18)                               done
     (%i19) ishow(canform(s([i,j],[])-s([j,i])))$
     (%t19)                                 0
     (%i20) ishow(canform(a([i,j],[])+a([j,i])))$
     (%t20)                            a    + a
                                        j i    i j
     (%i21) decsym(a,2,0,[anti(all)],[]);
     (%o21)                               done
     (%i22) ishow(canform(a([i,j],[])+a([j,i])))$
     (%t22)                                 0


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

25.2 Functions and Variables for itensor
========================================

25.2.1 Managing indexed objects
-------------------------------

 -- Function: dispcon (<tensor_1>, <tensor_2>, ...)
 -- Function: dispcon (all)
     Displays the contraction properties of its arguments as were given
     to `defcon'.  `dispcon (all)' displays all the contraction
     properties which were defined.


 -- Function: entertensor (<name>)
     is a function which, by prompting, allows one to create an indexed
     object called <name> with any number of tensorial and derivative
     indices. Either a single index or a list of indices (which may be
     null) is acceptable input (see the example under `covdiff').


 -- Function: changename (<old>, <new>, <expr>)
     will change the name of all indexed objects called <old> to <new>
     in <expr>. <old> may be either a symbol or a list of the form
     `[<name>, <m>, <n>]' in which case only those indexed objects
     called <name> with <m> covariant and <n> contravariant indices
     will be renamed to <new>.


 -- Function: listoftens
     Lists all tensors in a tensorial expression, complete with their
     indices. E.g.,


          (%i6) ishow(a([i,j],[k])*b([u],[],v)+c([x,y],[])*d([],[])*e)$
                                                   k
          (%t6)                        d e c    + a    b
                                            x y    i j  u,v
          (%i7) ishow(listoftens(%))$
                                         k
          (%t7)                        [a   , b   , c   , d]
                                         i j   u,v   x y


 -- Function: ishow (<expr>)
     displays <expr> with the indexed objects in it shown having their
     covariant indices as subscripts and contravariant indices as
     superscripts. The derivative indices are displayed as subscripts,
     separated from the covariant indices by a comma (see the examples
     throughout this document).


 -- Function: indices (<expr>)
     Returns a list of two elements.  The first is a list of the free
     indices in <expr> (those that occur only once). The second is the
     list of the dummy indices in <expr> (those that occur exactly
     twice) as the following example demonstrates.


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) ishow(a([i,j],[k,l],m,n)*b([k,o],[j,m,p],q,r))$
                                          k l      j m p
          (%t2)                          a        b
                                          i j,m n  k o,q r
          (%i3) indices(%);
          (%o3)                 [[l, p, i, n, o, q, r], [k, j, m]]

     A tensor product containing the same index more than twice is
     syntactically illegal. `indices' attempts to deal with these
     expressions in a reasonable manner; however, when it is called to
     operate upon such an illegal expression, its behavior should be
     considered undefined.


 -- Function: rename (<expr>)
 -- Function: rename (<expr>, <count>)
     Returns an expression equivalent to <expr> but with the dummy
     indices in each term chosen from the set `[%1, %2,...]', if the
     optional second argument is omitted. Otherwise, the dummy indices
     are indexed beginning at the value of <count>.  Each dummy index
     in a product will be different. For a sum, `rename' will operate
     upon each term in the sum resetting the counter with each term. In
     this way `rename' can serve as a tensorial simplifier. In
     addition, the indices will be sorted alphanumerically (if `allsym'
     is `true') with respect to covariant or contravariant indices
     depending upon the value of `flipflag'.  If `flipflag' is `false'
     then the indices will be renamed according to the order of the
     contravariant indices. If `flipflag' is `true' the renaming will
     occur according to the order of the covariant indices. It often
     happens that the combined effect of the two renamings will reduce
     an expression more than either one by itself.


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) allsym:true;
          (%o2)                                true
          (%i3) g([],[%4,%5])*g([],[%6,%7])*ichr2([%1,%4],[%3])*
          ichr2([%2,%3],[u])*ichr2([%5,%6],[%1])*ichr2([%7,r],[%2])-
          g([],[%4,%5])*g([],[%6,%7])*ichr2([%1,%2],[u])*
          ichr2([%3,%5],[%1])*ichr2([%4,%6],[%3])*ichr2([%7,r],[%2]),noeval$
          (%i4) expr:ishow(%)$
                 %4 %5  %6 %7      %3         u          %1         %2
          (%t4) g      g      ichr2      ichr2      ichr2      ichr2
                                   %1 %4      %2 %3      %5 %6      %7 r

                  %4 %5  %6 %7      u          %1         %3         %2
               - g      g      ichr2      ichr2      ichr2      ichr2
                                    %1 %2      %3 %5      %4 %6      %7 r
          (%i5) flipflag:true;
          (%o5)                                true
          (%i6) ishow(rename(expr))$
                 %2 %5  %6 %7      %4         u          %1         %3
          (%t6) g      g      ichr2      ichr2      ichr2      ichr2
                                   %1 %2      %3 %4      %5 %6      %7 r

                  %4 %5  %6 %7      u          %1         %3         %2
               - g      g      ichr2      ichr2      ichr2      ichr2
                                    %1 %2      %3 %4      %5 %6      %7 r
          (%i7) flipflag:false;
          (%o7)                                false
          (%i8) rename(%th(2));
          (%o8)                                  0
          (%i9) ishow(rename(expr))$
                 %1 %2  %3 %4      %5         %6         %7        u
          (%t9) g      g      ichr2      ichr2      ichr2     ichr2
                                   %1 %6      %2 %3      %4 r      %5 %7

                  %1 %2  %3 %4      %6         %5         %7        u
               - g      g      ichr2      ichr2      ichr2     ichr2
                                    %1 %3      %2 %6      %4 r      %5 %7


 -- Function: show (<expr>)
     Displays `expr' with the indexed objects in it shown having
     covariant indices as subscripts, contravariant indices as
     superscripts.  The derivative indices are displayed as subscripts,
     separated from the covariant indices by a comma.


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

     If `false' then the indices will be renamed according to the order
     of the contravariant indices, otherwise according to the order of
     the covariant indices.

     If `flipflag' is `false' then `rename' forms a list of the
     contravariant indices as they are encountered from left to right
     (if `true' then of the covariant indices). The first dummy index
     in the list is renamed to `%1', the next to `%2', etc.  Then
     sorting occurs after the `rename'-ing (see the example under
     `rename').


 -- Function: defcon (<tensor_1>)
 -- Function: defcon (<tensor_1>, <tensor_2>, <tensor_3>)
     gives <tensor_1> the property that the contraction of a product of
     <tensor_1> and <tensor_2> results in <tensor_3> with the
     appropriate indices.  If only one argument, <tensor_1>, is given,
     then the contraction of the product of <tensor_1> with any indexed
     object having the appropriate indices (say `my_tensor') will yield
     an indexed object with that name, i.e. `my_tensor', and with a new
     set of indices reflecting the contractions performed.      For
     example, if `imetric:g', then `defcon(g)' will implement the
     raising and lowering of indices through contraction with the metric
     tensor.      More than one `defcon' can be given for the same
     indexed object; the latest one given which applies in a particular
     contraction will be used.  `contractions' is a list of those
     indexed objects which have been given contraction properties with
     `defcon'.


 -- Function: remcon (<tensor_1>, ..., <tensor_n>)
 -- Function: remcon (all)
     removes all the contraction properties from the (<tensor_1>, ...,
     <tensor_n>). `remcon(all)' removes all contraction properties from
     all indexed objects.


 -- Function: contract (<expr>)
     Carries out the tensorial contractions in <expr> which may be any
     combination of sums and products. This function uses the
     information given to the `defcon' function. For best results,
     `expr' should be fully expanded. `ratexpand' is the fastest way to
     expand products and powers of sums if there are no variables in
     the denominators of the terms. The `gcd' switch should be `false'
     if GCD cancellations are unnecessary.


 -- Function: indexed_tensor (<tensor>)
     Must be executed before assigning components to a <tensor> for
     which a built in value already exists as with `ichr1', `ichr2',
     `icurvature'. See the example under `icurvature'.


 -- Function: components (<tensor>, <expr>)
     permits one to assign an indicial value to an expression <expr>
     giving the values of the components of <tensor>. These are
     automatically substituted for the tensor whenever it occurs with
     all of its indices. The tensor must be of the form `t([...],[...])'
     where either list may be empty. <expr> can be any indexed
     expression involving other objects with the same free indices as
     <tensor>. When used to assign values to the metric tensor wherein
     the components contain dummy indices one must be careful to define
     these indices to avoid the generation of multiple dummy indices.
     Removal of this assignment is given to the function `remcomps'.

     It is important to keep in mind that `components' cares only about
     the valence of a tensor, not about any particular index ordering.
     Thus assigning components to, say, `x([i,-j],[])', `x([-j,i],[])',
     or `x([i],[j])' all produce the same result, namely components
     being assigned to a tensor named `x' with valence `(1,1)'.

     Components can be assigned to an indexed expression in four ways,
     two of which involve the use of the `components' command:

     1) As an indexed expression. For instance:

          (%i2) components(g([],[i,j]),e([],[i])*p([],[j]))$
          (%i3) ishow(g([],[i,j]))$
                                                i  j
          (%t3)                                e  p

     2) As a matrix:


          (%i5) lg:-ident(4)$lg[1,1]:1$lg;
                                      [ 1   0    0    0  ]
                                      [                  ]
                                      [ 0  - 1   0    0  ]
          (%o5)                       [                  ]
                                      [ 0   0   - 1   0  ]
                                      [                  ]
                                      [ 0   0    0   - 1 ]
          (%i6) components(g([i,j],[]),lg);
          (%o6)                                done
          (%i7) ishow(g([i,j],[]))$
          (%t7)                                g
                                                i j
          (%i8) g([1,1],[]);
          (%o8)                                  1
          (%i9) g([4,4],[]);
          (%o9)                                 - 1

     3) As a function. You can use a Maxima function to specify the
     components of a tensor based on its indices. For instance, the
     following code assigns `kdelta' to `h' if `h' has the same number
     of covariant and contravariant indices and no derivative indices,
     and `g' otherwise:


          (%i4) h(l1,l2,[l3]):=if length(l1)=length(l2) and length(l3)=0
            then kdelta(l1,l2) else apply(g,append([l1,l2], l3))$
          (%i5) ishow(h([i],[j]))$
                                                    j
          (%t5)                               kdelta
                                                    i
          (%i6) ishow(h([i,j],[k],l))$
                                               k
          (%t6)                               g
                                               i j,l

     4) Using Maxima's pattern matching capabilities, specifically the
     `defrule' and `applyb1' commands:


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) matchdeclare(l1,listp);
          (%o2)                                done
          (%i3) defrule(r1,m(l1,[]),(i1:idummy(),
                g([l1[1],l1[2]],[])*q([i1],[])*e([],[i1])))$

          (%i4) defrule(r2,m([],l1),(i1:idummy(),
                w([],[l1[1],l1[2]])*e([i1],[])*q([],[i1])))$

          (%i5) ishow(m([i,n],[])*m([],[i,m]))$
                                              i m
          (%t5)                              m    m
                                                   i n
          (%i6) ishow(rename(applyb1(%,r1,r2)))$
                                     %1  %2  %3 m
          (%t6)                     e   q   w     q   e   g
                                                   %1  %2  %3 n


 -- Function: remcomps (<tensor>)
     Unbinds all values from <tensor> which were assigned with the
     `components' function.


 -- Function: showcomps (<tensor>)
     Shows component assignments of a tensor, as made using the
     `components' command. This function can be particularly useful
     when a matrix is assigned to an indicial tensor using
     `components', as demonstrated by the following example:


          (%i1) load(ctensor);
          (%o1)       /share/tensor/ctensor.mac
          (%i2) load(itensor);
          (%o2)      /share/tensor/itensor.lisp
          (%i3) lg:matrix([sqrt(r/(r-2*m)),0,0,0],[0,r,0,0],
                          [0,0,sin(theta)*r,0],[0,0,0,sqrt((r-2*m)/r)]);
                         [         r                                     ]
                         [ sqrt(-------)  0       0              0       ]
                         [      r - 2 m                                  ]
                         [                                               ]
                         [       0        r       0              0       ]
          (%o3)          [                                               ]
                         [       0        0  r sin(theta)        0       ]
                         [                                               ]
                         [                                      r - 2 m  ]
                         [       0        0       0        sqrt(-------) ]
                         [                                         r     ]
          (%i4) components(g([i,j],[]),lg);
          (%o4)                                done
          (%i5) showcomps(g([i,j],[]));
                            [         r                                     ]
                            [ sqrt(-------)  0       0              0       ]
                            [      r - 2 m                                  ]
                            [                                               ]
                            [       0        r       0              0       ]
          (%t5)      g    = [                                               ]
                      i j   [       0        0  r sin(theta)        0       ]
                            [                                               ]
                            [                                      r - 2 m  ]
                            [       0        0       0        sqrt(-------) ]
                            [                                         r     ]
          (%o5)                                false

     The `showcomps' command can also display components of a tensor of
     rank higher than 2.


 -- Function: idummy ()
     Increments `icounter' and returns as its value an index of the form
     `%n' where n is a positive integer.  This guarantees that dummy
     indices which are needed in forming expressions will not conflict
     with indices already in use (see the example under `indices').


 -- Option variable: idummyx
     Default value: `%'

     Is the prefix for dummy indices (see the example under `indices').


 -- Option variable: icounter
     Default value: `1'

     Determines the numerical suffix to be used in generating the next
     dummy index in the tensor package.  The prefix is determined by
     the option `idummy' (default: `%').


 -- Function: kdelta (<L1>, <L2>)
     is the generalized Kronecker delta function defined in the
     `itensor' package with <L1> the list of covariant indices and <L2>
     the list of contravariant indices.  `kdelta([i],[j])' returns the
     ordinary Kronecker delta.  The command `ev(<expr>,kdelta)' causes
     the evaluation of an expression containing `kdelta([],[])' to the
     dimension of the manifold.

     In what amounts to an abuse of this notation, `itensor' also allows
     `kdelta' to have 2 covariant and no contravariant, or 2
     contravariant and no covariant indices, in effect providing a
     co(ntra)variant "unit matrix" capability. This is strictly
     considered a programming aid and not meant to imply that
     `kdelta([i,j],[])' is a valid tensorial object.


 -- Function: kdels (<L1>, <L2>)
     Symmetrized Kronecker delta, used in some calculations. For
     instance:


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) kdelta([1,2],[2,1]);
          (%o2)                                 - 1
          (%i3) kdels([1,2],[2,1]);
          (%o3)                                  1
          (%i4) ishow(kdelta([a,b],[c,d]))$
                                       c       d         d       c
          (%t4)                  kdelta  kdelta  - kdelta  kdelta
                                       a       b         a       b
          (%i4) ishow(kdels([a,b],[c,d]))$
                                       c       d         d       c
          (%t4)                  kdelta  kdelta  + kdelta  kdelta
                                       a       b         a       b


 -- Function: levi_civita (<L>)
     is the permutation (or Levi-Civita) tensor which yields 1 if the
     list <L> consists of an even permutation of integers, -1 if it
     consists of an odd permutation, and 0 if some indices in <L> are
     repeated.


 -- Function: lc2kdt (<expr>)
     Simplifies expressions containing the Levi-Civita symbol,
     converting these to Kronecker-delta expressions when possible. The
     main difference between this function and simply evaluating the
     Levi-Civita symbol is that direct evaluation often results in
     Kronecker expressions containing numerical indices. This is often
     undesirable as it prevents further simplification.  The `lc2kdt'
     function avoids this problem, yielding expressions that are more
     easily simplified with `rename' or `contract'.


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) expr:ishow('levi_civita([],[i,j])
                           *'levi_civita([k,l],[])*a([j],[k]))$
                                            i j  k
          (%t2)                  levi_civita    a  levi_civita
                                                 j            k l
          (%i3) ishow(ev(expr,levi_civita))$
                                            i j  k       1 2
          (%t3)                       kdelta    a  kdelta
                                            1 2  j       k l
          (%i4) ishow(ev(%,kdelta))$
                       i       j         j       i   k
          (%t4) (kdelta  kdelta  - kdelta  kdelta ) a
                       1       2         1       2   j

                                         1       2         2       1
                                  (kdelta  kdelta  - kdelta  kdelta )
                                         k       l         k       l
          (%i5) ishow(lc2kdt(expr))$
                               k       i       j    k       j       i
          (%t5)               a  kdelta  kdelta  - a  kdelta  kdelta
                               j       k       l    j       k       l
          (%i6) ishow(contract(expand(%)))$
                                           i           i
          (%t6)                           a  - a kdelta
                                           l           l

     The `lc2kdt' function sometimes makes use of the metric tensor.
     If the metric tensor was not defined previously with `imetric',
     this results in an error.


          (%i7) expr:ishow('levi_civita([],[i,j])
                           *'levi_civita([],[k,l])*a([j,k],[]))$
                                           i j            k l
          (%t7)                 levi_civita    levi_civita    a
                                                               j k
          (%i8) ishow(lc2kdt(expr))$
          Maxima encountered a Lisp error:

           Error in $IMETRIC [or a callee]:
           $IMETRIC [or a callee] requires less than two arguments.

          Automatically continuing.
          To reenable the Lisp debugger set *debugger-hook* to nil.
          (%i9) imetric(g);
          (%o9)                                done
          (%i10) ishow(lc2kdt(expr))$
                   %3 i       k   %4 j       l     %3 i       l   %4 j
          (%t10) (g     kdelta   g     kdelta   - g     kdelta   g
                              %3             %4               %3
                        k
                  kdelta  ) a
                        %4   j k
          (%i11) ishow(contract(expand(%)))$
                                            l i    l i  j
          (%t11)                           a    - g    a
                                                        j


 -- Function: lc_l
     Simplification rule used for expressions containing the
     unevaluated Levi-Civita symbol (`levi_civita'). Along with `lc_u',
     it can be used to simplify many expressions more efficiently than
     the evaluation of `levi_civita'.  For example:


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) el1:ishow('levi_civita([i,j,k],[])*a([],[i])*a([],[j]))$
                                       i  j
          (%t2)                       a  a  levi_civita
                                                       i j k
          (%i3) el2:ishow('levi_civita([],[i,j,k])*a([i])*a([j]))$
                                                 i j k
          (%t3)                       levi_civita      a  a
                                                        i  j
          (%i4) canform(contract(expand(applyb1(el1,lc_l,lc_u))));
          (%t4)                                  0
          (%i5) canform(contract(expand(applyb1(el2,lc_l,lc_u))));
          (%t5)                                  0


 -- Function: lc_u
     Simplification rule used for expressions containing the
     unevaluated Levi-Civita symbol (`levi_civita'). Along with `lc_u',
     it can be used to simplify many expressions more efficiently than
     the evaluation of `levi_civita'.  For details, see `lc_l'.


 -- Function: canten (<expr>)
     Simplifies <expr> by renaming (see `rename') and permuting dummy
     indices. `rename' is restricted to sums of tensor products in
     which no derivatives are present. As such it is limited and should
     only be used if `canform' is not capable of carrying out the
     required simplification.

     The `canten' function returns a mathematically correct result only
     if its argument is an expression that is fully symmetric in its
     indices.  For this reason, `canten' returns an error if `allsym'
     is not set to `true'.


 -- Function: concan (<expr>)
     Similar to `canten' but also performs index contraction.


25.2.2 Tensor symmetries
------------------------

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

     If `true' then all indexed objects are assumed symmetric in all of
     their covariant and contravariant indices. If `false' then no
     symmetries of any kind are assumed in these indices. Derivative
     indices are always taken to be symmetric unless `iframe_flag' is
     set to `true'.


 -- Function: decsym (<tensor>, <m>, <n>, [<cov_1>, <cov_2>, ...],
          [<contr_1>, <contr_2>, ...])
     Declares symmetry properties for <tensor> of <m> covariant and <n>
     contravariant indices. The <cov_i> and <contr_i> are
     pseudofunctions expressing symmetry relations among the covariant
     and contravariant indices respectively.  These are of the form
     `symoper(<index_1>, <index_2>,...)' where `symoper' is one of
     `sym', `anti' or `cyc' and the <index_i> are integers indicating
     the position of the index in the <tensor>.  This will declare
     <tensor> to be symmetric, antisymmetric or cyclic respectively in
     the <index_i>. `symoper(all)' is also an allowable form which
     indicates all indices obey the symmetry condition. For example,
     given an object `b' with 5 covariant indices,
     `decsym(b,5,3,[sym(1,2),anti(3,4)],[cyc(all)])' declares `b'
     symmetric in its first and second and antisymmetric in its third
     and fourth covariant indices, and cyclic in all of its
     contravariant indices.  Either list of symmetry declarations may
     be null.  The function which performs the simplifications is
     `canform' as the example below illustrates.


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) expr:contract( expand( a([i1, j1, k1], [])
                     *kdels([i, j, k], [i1, j1, k1])))$
          (%i3) ishow(expr)$
          (%t3)         a      + a      + a      + a      + a      + a
                         k j i    k i j    j k i    j i k    i k j    i j k
          (%i4) decsym(a,3,0,[sym(all)],[]);
          (%o4)                                done
          (%i5) ishow(canform(expr))$
          (%t5)                              6 a
                                                i j k
          (%i6) remsym(a,3,0);
          (%o6)                                done
          (%i7) decsym(a,3,0,[anti(all)],[]);
          (%o7)                                done
          (%i8) ishow(canform(expr))$
          (%t8)                                  0
          (%i9) remsym(a,3,0);
          (%o9)                                done
          (%i10) decsym(a,3,0,[cyc(all)],[]);
          (%o10)                               done
          (%i11) ishow(canform(expr))$
          (%t11)                        3 a      + 3 a
                                           i k j      i j k
          (%i12) dispsym(a,3,0);
          (%o12)                     [[cyc, [[1, 2, 3]], []]]


 -- Function: remsym (<tensor>, <m>, <n>)
     Removes all symmetry properties from <tensor> which has <m>
     covariant indices and <n> contravariant indices.


 -- Function: canform (<expr>)
 -- Function: canform (<expr>, <rename>)
     Simplifies <expr> by renaming dummy indices and reordering all
     indices as dictated by symmetry conditions imposed on them. If
     `allsym' is `true' then all indices are assumed symmetric,
     otherwise symmetry information provided by `decsym' declarations
     will be used. The dummy indices are renamed in the same manner as
     in the `rename' function. When `canform' is applied to a large
     expression the calculation may take a considerable amount of time.
     This time can be shortened by calling `rename' on the expression
     first.  Also see the example under `decsym'. Note: `canform' may
     not be able to reduce an expression completely to its simplest
     form although it will always return a mathematically correct
     result.

     The optional second parameter <rename>, if set to `false',
     suppresses renaming.


25.2.3 Indicial tensor calculus
-------------------------------

 -- Function: diff (<expr>, <v_1>, [<n_1>, [<v_2>, <n_2>] ...])
     is the usual Maxima differentiation function which has been
     expanded in its abilities for `itensor'. It takes the derivative
     of <expr> with respect to <v_1> <n_1> times, with respect to <v_2>
     <n_2> times, etc. For the tensor package, the function has been
     modified so that the <v_i> may be integers from 1 up to the value
     of the variable `dim'.  This will cause the differentiation to be
     carried out with respect to the <v_i>th member of the list
     `vect_coords'.  If `vect_coords' is bound to an atomic variable,
     then that variable subscripted by <v_i> will be used for the
     variable of differentiation.  This permits an array of coordinate
     names or subscripted names like `x[1]', `x[2]', ...  to be used.

     A further extension adds the ability to `diff' to compute
     derivatives with respect to an indexed variable. In particular,
     the tensor package knows how to differentiate expressions
     containing combinations of the metric tensor and its derivatives
     with respect to the metric tensor and its first and second
     derivatives. This capability is particularly useful when
     considering Lagrangian formulations of a gravitational theory,
     allowing one to derive the Einstein tensor and field equations
     from the action principle.


 -- Function: idiff (<expr>, <v_1>, [<n_1>, [<v_2>, <n_2>] ...])
     Indicial differentiation. Unlike `diff', which differentiates with
     respect to an independent variable, `idiff)' can be used to
     differentiate with respect to a coordinate. For an indexed object,
     this amounts to appending the <v_i> as derivative indices.
     Subsequently, derivative indices will be sorted, unless
     `iframe_flag' is set to `true'.

     `idiff' can also differentiate the determinant of the metric
     tensor. Thus, if `imetric' has been bound to `G' then
     `idiff(determinant(g),k)' will return `2 * determinant(g) *
     ichr2([%i,k],[%i])' where the dummy index `%i' is chosen
     appropriately.


 -- Function: liediff (<v>, <ten>)
     Computes the Lie-derivative of the tensorial expression <ten> with
     respect to the vector field <v>. <ten> should be any indexed
     tensor expression; <v> should be the name (without indices) of a
     vector field. For example:


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) ishow(liediff(v,a([i,j],[])*b([],[k],l)))$
                 k    %2            %2          %2
          (%t2) b   (v   a       + v   a     + v   a    )
                 ,l       i j,%2    ,j  i %2    ,i  %2 j

                                    %1  k        %1  k      %1  k
                                + (v   b      - b   v    + v   b   ) a
                                        ,%1 l    ,l  ,%1    ,l  ,%1   i j


 -- Function: rediff (<ten>)
     Evaluates all occurrences of the `idiff' command in the tensorial
     expression <ten>.


 -- Function: undiff (<expr>)
     Returns an expression equivalent to <expr> but with all derivatives
     of indexed objects replaced by the noun form of the `idiff'
     function. Its arguments would yield that indexed object if the
     differentiation were carried out.  This is useful when it is
     desired to replace a differentiated indexed object with some
     function definition resulting in <expr> and then carry out the
     differentiation by saying `ev(<expr>, idiff)'.


 -- Function: evundiff (<expr>)
     Equivalent to the execution of `undiff', followed by `ev' and
     `rediff'.

     The point of this operation is to easily evalute expressions that
     cannot be directly evaluated in derivative form. For instance, the
     following causes an error:

          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) icurvature([i,j,k],[l],m);
          Maxima encountered a Lisp error:

           Error in $ICURVATURE [or a callee]:
           $ICURVATURE [or a callee] requires less than three arguments.

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

     However, if `icurvature' is entered in noun form, it can be
     evaluated using `evundiff':

          (%i3) ishow('icurvature([i,j,k],[l],m))$
                                                   l
          (%t3)                          icurvature
                                                   i j k,m
          (%i4) ishow(evundiff(%))$
                       l              l         %1           l           %1
          (%t4) - ichr2        - ichr2     ichr2      - ichr2       ichr2
                       i k,j m        %1 j      i k,m        %1 j,m      i k

                       l              l         %1           l           %1
                + ichr2        + ichr2     ichr2      + ichr2       ichr2
                       i j,k m        %1 k      i j,m        %1 k,m      i j

     Note: In earlier versions of Maxima, derivative forms of the
     Christoffel-symbols also could not be evaluated. This has been
     fixed now, so `evundiff' is no longer necessary for expressions
     like this:

          (%i5) imetric(g);
          (%o5)                                done
          (%i6) ishow(ichr2([i,j],[k],l))$
                 k %3
                g     (g         - g         + g        )
                        j %3,i l    i j,%3 l    i %3,j l
          (%t6) -----------------------------------------
                                    2

                                   k %3
                                  g     (g       - g       + g      )
                                   ,l     j %3,i    i j,%3    i %3,j
                                + -----------------------------------
                                                   2


 -- Function: flush (<expr>, <tensor_1>, <tensor_2>, ...)
     Set to zero, in <expr>, all occurrences of the <tensor_i> that
     have no derivative indices.


 -- Function: flushd (<expr>, <tensor_1>, <tensor_2>, ...)
     Set to zero, in <expr>, all occurrences of the <tensor_i> that
     have derivative indices.


 -- Function: flushnd (<expr>, <tensor>, <n>)
     Set to zero, in <expr>, all occurrences of the differentiated
     object <tensor> that have <n> or more derivative indices as the
     following example demonstrates.

          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) ishow(a([i],[J,r],k,r)+a([i],[j,r,s],k,r,s))$
                                          J r      j r s
          (%t2)                          a      + a
                                          i,k r    i,k r s
          (%i3) ishow(flushnd(%,a,3))$
                                               J r
          (%t3)                               a
                                               i,k r


 -- Function: coord (<tensor_1>, <tensor_2>, ...)
     Gives <tensor_i> the coordinate differentiation property that the
     derivative of contravariant vector whose name is one of the
     <tensor_i> yields a Kronecker delta. For example, if `coord(x)' has
     been done then `idiff(x([],[i]),j)' gives `kdelta([i],[j])'.
     `coord' is a list of all indexed objects having this property.


 -- Function: remcoord (<tensor_1>, <tensor_2>, ...)
 -- Function: remcoord (all)
     Removes the coordinate differentiation property from the `tensor_i'
     that was established by the function `coord'.  `remcoord(all)'
     removes this property from all indexed objects.


 -- Function: makebox (<expr>)
     Display <expr> in the same manner as `show'; however, any tensor
     d'Alembertian occurring in <expr> will be indicated using the
     symbol `[]'.  For example, `[]p([m],[n])' represents
     `g([],[i,j])*p([m],[n],i,j)'.


 -- Function: conmetderiv (<expr>, <tensor>)
     Simplifies expressions containing ordinary derivatives of both
     covariant and contravariant forms of the metric tensor (the
     current restriction).  For example, `conmetderiv' can relate the
     derivative of the contravariant metric tensor with the Christoffel
     symbols as seen from the following:


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) ishow(g([],[a,b],c))$
                                                a b
          (%t2)                                g
                                                ,c
          (%i3) ishow(conmetderiv(%,g))$
                                   %1 b      a       %1 a      b
          (%t3)                 - g     ichr2     - g     ichr2
                                             %1 c              %1 c


 -- Function: simpmetderiv (<expr>)
 -- Function: simpmetderiv (<expr>[, <stop>])
     Simplifies expressions containing products of the derivatives of
     the metric tensor. Specifically, `simpmetderiv' recognizes two
     identities:


             ab        ab           ab                 a
            g   g   + g   g     = (g   g  )   = (kdelta )   = 0
             ,d  bc        bc,d         bc ,d          c ,d

     hence


             ab          ab
            g   g   = - g   g
             ,d  bc          bc,d

     and


            ab          ab
           g   g     = g   g
            ,j  ab,i    ,i  ab,j

     which follows from the symmetries of the Christoffel symbols.

     The `simpmetderiv' function takes one optional parameter which,
     when present, causes the function to stop after the first
     successful substitution in a product expression. The
     `simpmetderiv' function also makes use of the global variable
     <flipflag> which determines how to apply a "canonical" ordering to
     the product indices.

     Put together, these capabilities can be used to achieve powerful
     simplifications that are difficult or impossible to accomplish
     otherwise.  This is demonstrated through the following example
     that explicitly uses the partial simplification features of
     `simpmetderiv' to obtain a contractible expression:


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) imetric(g);
          (%o2)                                done
          (%i3) ishow(g([],[a,b])*g([],[b,c])*g([a,b],[],d)*g([b,c],[],e))$
                                       a b  b c
          (%t3)                       g    g    g      g
                                                 a b,d  b c,e
          (%i4) ishow(canform(%))$

          errexp1 has improper indices
           -- an error.  Quitting.  To debug this try debugmode(true);
          (%i5) ishow(simpmetderiv(%))$
                                       a b  b c
          (%t5)                       g    g    g      g
                                                 a b,d  b c,e
          (%i6) flipflag:not flipflag;
          (%o6)                                true
          (%i7) ishow(simpmetderiv(%th(2)))$
                                         a b  b c
          (%t7)                         g    g    g    g
                                         ,d   ,e   a b  b c
          (%i8) flipflag:not flipflag;
          (%o8)                                false
          (%i9) ishow(simpmetderiv(%th(2),stop))$
                                         a b  b c
          (%t9)                       - g    g    g      g
                                              ,e   a b,d  b c
          (%i10) ishow(contract(%))$
                                              b c
          (%t10)                           - g    g
                                              ,e   c b,d

     See also `weyl.dem' for an example that uses `simpmetderiv' and
     `conmetderiv' together to simplify contractions of the Weyl tensor.


 -- Function: flush1deriv (<expr>, <tensor>)
     Set to zero, in `expr', all occurrences of `tensor' that have
     exactly one derivative index.


25.2.4 Tensors in curved spaces
-------------------------------

 -- Function: imetric (<g>)
 -- System variable: imetric
     Specifies the metric by assigning the variable `imetric:<g>' in
     addition, the contraction properties of the metric <g> are set up
     by executing the commands `defcon(<g>), defcon(<g>, <g>, kdelta)'.
     The variable `imetric' (unbound by default), is bound to the
     metric, assigned by the `imetric(<g>)' command.


 -- Function: idim (<n>)
     Sets the dimensions of the metric. Also initializes the
     antisymmetry properties of the Levi-Civita symbols for the given
     dimension.


 -- Function: ichr1 ([<i>, <j>, <k>])
     Yields the Christoffel symbol of the first kind via the definition
                 (g      + g      - g     )/2 .
                   ik,j     jk,i     ij,k
     To evaluate the Christoffel symbols for a particular metric, the
     variable `imetric' must be assigned a name as in the example under
     `chr2'.


 -- Function: ichr2 ([<i>, <j>], [<k>])
     Yields the Christoffel symbol of the second kind defined by the
     relation
                                 ks
             ichr2([i,j],[k]) = g    (g      + g      - g     )/2
                                       is,j     js,i     ij,s


 -- Function: icurvature ([<i>, <j>, <k>], [<h>])
     Yields the Riemann curvature tensor in terms of the Christoffel
     symbols of the second kind (`ichr2').  The following notation is
     used:
                      h             h            h         %1         h
            icurvature     = - ichr2      - ichr2     ichr2    + ichr2
                      i j k         i k,j        %1 j      i k        i j,k
                                      h          %1
                               + ichr2      ichr2
                                      %1 k       i j


 -- Function: covdiff (<expr>, <v_1>, <v_2>, ...)
     Yields the covariant derivative of <expr> with respect to the
     variables <v_i> in terms of the Christoffel symbols of the second
     kind (`ichr2').  In order to evaluate these, one should use
     `ev(<expr>,ichr2)'.


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) entertensor()$
          Enter tensor name: a;
          Enter a list of the covariant indices: [i,j];
          Enter a list of the contravariant indices: [k];
          Enter a list of the derivative indices: [];
                                                k
          (%t2)                                a
                                                i j
          (%i3) ishow(covdiff(%,s))$
                       k         %1     k         %1     k
          (%t3)     - a     ichr2    - a     ichr2    + a
                       i %1      j s    %1 j      i s    i j,s

                       k     %1
                + ichr2     a
                       %1 s  i j
          (%i4) imetric:g;
          (%o4)                                  g
          (%i5) ishow(ev(%th(2),ichr2))$
                   %1 %4  k
                  g      a     (g       - g       + g      )
                          i %1   s %4,j    j s,%4    j %4,s
          (%t5) - ------------------------------------------
                                      2
              %1 %3  k
             g      a     (g       - g       + g      )
                     %1 j   s %3,i    i s,%3    i %3,s
           - ------------------------------------------
                                 2
              k %2  %1
             g     a    (g        - g        + g       )
                    i j   s %2,%1    %1 s,%2    %1 %2,s     k
           + ------------------------------------------- + a
                                  2                         i j,s
          (%i6)


 -- Function: lorentz_gauge (<expr>)
     Imposes the Lorentz condition by substituting 0 for all indexed
     objects in <expr> that have a derivative index identical to a
     contravariant index.


 -- Function: igeodesic_coords (<expr>, <name>)
     Causes undifferentiated Christoffel symbols and first derivatives
     of the metric tensor vanish in <expr>. The <name> in the
     `igeodesic_coords' function refers to the metric <name> (if it
     appears in <expr>) while the connection coefficients must be
     called with the names `ichr1' and/or `ichr2'. The following example
     demonstrates the verification of the cyclic identity satisfied by
     the Riemann curvature tensor using the `igeodesic_coords' function.


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) ishow(icurvature([r,s,t],[u]))$
                       u            u         %1         u
          (%t2) - ichr2      - ichr2     ichr2    + ichr2
                       r t,s        %1 s      r t        r s,t

                                                        u         %1
                                                 + ichr2     ichr2
                                                        %1 t      r s
          (%i3) ishow(igeodesic_coords(%,ichr2))$
                                           u            u
          (%t3)                       ichr2      - ichr2
                                           r s,t        r t,s
          (%i4) ishow(igeodesic_coords(icurvature([r,s,t],[u]),ichr2)+
                      igeodesic_coords(icurvature([s,t,r],[u]),ichr2)+
                      igeodesic_coords(icurvature([t,r,s],[u]),ichr2))$
                       u            u            u            u
          (%t4) - ichr2      + ichr2      + ichr2      - ichr2
                       t s,r        t r,s        s t,r        s r,t

                                                       u            u
                                                - ichr2      + ichr2
                                                       r t,s        r s,t
          (%i5) canform(%);
          (%o5)                                  0


25.2.5 Moving frames
--------------------

Maxima now has the ability to perform calculations using moving frames.
These can be orthonormal frames (tetrads, vielbeins) or an arbitrary
frame.

   To use frames, you must first set `iframe_flag' to `true'. This
causes the Christoffel-symbols, `ichr1' and `ichr2', to be replaced by
the more general frame connection coefficients `icc1' and `icc2' in
calculations. Speficially, the behavior of `covdiff' and `icurvature'
is changed.

   The frame is defined by two tensors: the inverse frame field (`ifri',
the dual basis tetrad), and the frame metric `ifg'. The frame metric is
the identity matrix for orthonormal frames, or the Lorentz metric for
orthonormal frames in Minkowski spacetime. The inverse frame field
defines the frame base (unit vectors).  Contraction properties are
defined for the frame field and the frame metric.

   When `iframe_flag' is true, many `itensor' expressions use the frame
metric `ifg' instead of the metric defined by `imetric' for raising and
lowerind indices.

   IMPORTANT: Setting the variable `iframe_flag' to `true' does NOT
undefine the contraction properties of a metric defined by a call to
`defcon' or `imetric'. If a frame field is used, it is best to define
the metric by assigning its name to the variable `imetric' and NOT
invoke the `imetric' function.

   Maxima uses these two tensors to define the frame coefficients
(`ifc1' and `ifc2') which form part of the connection coefficients
(`icc1' and `icc2'), as the following example demonstrates:


     (%i1) load(itensor);
     (%o1)      /share/tensor/itensor.lisp
     (%i2) iframe_flag:true;
     (%o2)                                true
     (%i3) ishow(covdiff(v([],[i]),j))$
                                    i        i     %1
     (%t3)                         v   + icc2     v
                                    ,j       %1 j
     (%i4) ishow(ev(%,icc2))$
                                    %1     i       i
     (%t4)                         v   ifc2     + v
                                           %1 j    ,j
     (%i5) ishow(ev(%,ifc2))$
                               %1    i %2                i
     (%t5)                    v   ifg     ifc1        + v
                                              %1 j %2    ,j
     (%i6) ishow(ev(%,ifc1))$
                 %1    i %2
                v   ifg     (ifb        - ifb        + ifb       )
                                j %2 %1      %2 %1 j      %1 j %2     i
     (%t6)      -------------------------------------------------- + v
                                        2                             ,j
     (%i7) ishow(ifb([a,b,c]))$
                                                        %3    %4
     (%t7)               (ifri        - ifri       ) ifr   ifr
                              a %3,%4       a %4,%3     b     c

   An alternate method is used to compute the frame bracket (`ifb') if
the `iframe_bracket_form' flag is set to `false':


     (%i8) block([iframe_bracket_form:false],ishow(ifb([a,b,c])))$
                                     %6    %5        %5      %6
     (%t8)              ifri     (ifr   ifr     - ifr     ifr  )
                            a %5     b     c,%6      b,%6    c

 -- Function: iframes ()
     Since in this version of Maxima, contraction identities for `ifr'
     and `ifri' are always defined, as is the frame bracket (`ifb'),
     this function does nothing.


 -- Variable: ifb
     The frame bracket. The contribution of the frame metric to the
     connection coefficients is expressed using the frame bracket:


                    - ifb      + ifb      + ifb
                         c a b      b c a      a b c
          ifc1    = --------------------------------
              abc                  2

     The frame bracket itself is defined in terms of the frame field
     and frame metric. Two alternate methods of computation are used
     depending on the value of `frame_bracket_form'. If true (the
     default) or if the `itorsion_flag' is `true':


                    d      e                                      f
          ifb =  ifr    ifr   (ifri      - ifri      - ifri    itr   )
             abc    b      c       a d,e       a e,d       a f    d e

     Otherwise:


                       e      d        d      e
          ifb    = (ifr    ifr    - ifr    ifr   ) ifri
             abc       b      c,e      b,e    c        a d


 -- Variable: icc1
     Connection coefficients of the first kind. In `itensor', defined as


          icc1    = ichr1    - ikt1    - inmc1
              abc        abc       abc        abc

     In this expression, if `iframe_flag' is true, the
     Christoffel-symbol `ichr1' is replaced with the frame connection
     coefficient `ifc1'.  If `itorsion_flag' is `false', `ikt1' will be
     omitted. It is also omitted if a frame base is used, as the
     torsion is already calculated as part of the frame bracket.
     Lastly, of `inonmet_flag' is `false', `inmc1' will not be present.


 -- Variable: icc2
     Connection coefficients of the second kind. In `itensor', defined
     as


              c         c        c         c
          icc2   = ichr2   - ikt2   - inmc2
              ab        ab       ab        ab

     In this expression, if `iframe_flag' is true, the
     Christoffel-symbol `ichr2' is replaced with the frame connection
     coefficient `ifc2'.  If `itorsion_flag' is `false', `ikt2' will be
     omitted. It is also omitted if a frame base is used, as the
     torsion is already calculated as part of the frame bracket.
     Lastly, of `inonmet_flag' is `false', `inmc2' will not be present.


 -- Variable: ifc1
     Frame coefficient of the first kind (also known as Ricci-rotation
     coefficients.) This tensor represents the contribution of the
     frame metric to the connection coefficient of the first kind.
     Defined as:


                    - ifb      + ifb      + ifb
                         c a b      b c a      a b c
          ifc1    = --------------------------------
              abc                   2


 -- Variable: ifc2
     Frame coefficient of the second kind. This tensor represents the
     contribution of the frame metric to the connection coefficient of
     the second kind. Defined as a permutation of the frame bracket
     (`ifb') with the appropriate indices raised and lowered as
     necessary:


              c       cd
          ifc2   = ifg   ifc1
              ab             abd


 -- Variable: ifr
     The frame field. Contracts with the inverse frame field (`ifri') to
     form the frame metric (`ifg').


 -- Variable: ifri
     The inverse frame field. Specifies the frame base (dual basis
     vectors). Along with the frame metric, it forms the basis of all
     calculations based on frames.


 -- Variable: ifg
     The frame metric. Defaults to `kdelta', but can be changed using
     `components'.


 -- Variable: ifgi
     The inverse frame metric. Contracts with the frame metric (`ifg')
     to `kdelta'.


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

     Specifies how the frame bracket (`ifb') is computed.


25.2.6 Torsion and nonmetricity
-------------------------------

Maxima can now take into account torsion and nonmetricity. When the flag
`itorsion_flag' is set to `true', the contribution of torsion is added
to the connection coefficients. Similarly, when the flag `inonmet_flag'
is true, nonmetricity components are included.

 -- Variable: inm
     The nonmetricity vector. Conformal nonmetricity is defined through
     the covariant derivative of the metric tensor. Normally zero, the
     metric tensor's covariant derivative will evaluate to the
     following when `inonmet_flag' is set to `true':


          g     =- g  inm
           ij;k     ij   k


 -- Variable: inmc1
     Covariant permutation of the nonmetricity vector components.
     Defined as


                     g   inm  - inm  g   - g   inm
                      ab    c      a  bc    ac    b
          inmc1    = ------------------------------
               abc                 2

     (Substitute `ifg' in place of `g' if a frame metric is used.)


 -- Variable: inmc2
     Contravariant permutation of the nonmetricity vector components.
     Used in the connection coefficients if `inonmet_flag' is `true'.
     Defined as:


                                c         c         cd
                    -inm  kdelta  - kdelta  inm  + g   inm  g
               c        a       b         a    b          d  ab
          inmc2   = -------------------------------------------
               ab                        2

     (Substitute `ifg' in place of `g' if a frame metric is used.)


 -- Variable: ikt1
     Covariant permutation of the torsion tensor (also known as
     contorsion).  Defined as:


                            d           d       d
                    -g   itr  - g    itr   - itr   g
                      ad    cb    bd    ca      ab  cd
          ikt1    = ----------------------------------
              abc                   2

     (Substitute `ifg' in place of `g' if a frame metric is used.)


 -- Variable: ikt2
     Contravariant permutation of the torsion tensor (also known as
     contorsion).  Defined as:


              c     cd
          ikt2   = g   ikt1
              ab           abd

     (Substitute `ifg' in place of `g' if a frame metric is used.)


 -- Variable: itr
     The torsion tensor. For a metric with torsion, repeated covariant
     differentiation on a scalar function will not commute, as
     demonstrated by the following example:


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) imetric:g;
          (%o2)                                  g
          (%i3) covdiff( covdiff( f( [], []), i), j)
                                - covdiff( covdiff( f( [], []), j), i)$
          (%i4) ishow(%)$
                                             %4              %2
          (%t4)                    f    ichr2    - f    ichr2
                                    ,%4      j i    ,%2      i j
          (%i5) canform(%);
          (%o5)                                  0
          (%i6) itorsion_flag:true;
          (%o6)                                true
          (%i7) covdiff( covdiff( f( [], []), i), j)
                                - covdiff( covdiff( f( [], []), j), i)$
          (%i8) ishow(%)$
                                     %8             %6
          (%t8)             f    icc2    - f    icc2    - f     + f
                             ,%8     j i    ,%6     i j    ,j i    ,i j
          (%i9) ishow(canform(%))$
                                             %1             %1
          (%t9)                     f    icc2    - f    icc2
                                     ,%1     j i    ,%1     i j
          (%i10) ishow(canform(ev(%,icc2)))$
                                             %1             %1
          (%t10)                    f    ikt2    - f    ikt2
                                     ,%1     i j    ,%1     j i
          (%i11) ishow(canform(ev(%,ikt2)))$
                                %2 %1                    %2 %1
          (%t11)          f    g      ikt1       - f    g      ikt1
                           ,%2            i j %1    ,%2            j i %1
          (%i12) ishow(factor(canform(rename(expand(ev(%,ikt1))))))$
                                     %3 %2            %1       %1
                               f    g      g      (itr    - itr   )
                                ,%3         %2 %1     j i      i j
          (%t12)               ------------------------------------
                                                2
          (%i13) decsym(itr,2,1,[anti(all)],[]);
          (%o13)                               done
          (%i14) defcon(g,g,kdelta);
          (%o14)                               done
          (%i15) subst(g,nounify(g),%th(3))$
          (%i16) ishow(canform(contract(%)))$
                                                     %1
          (%t16)                           - f    itr
                                              ,%1    i j


25.2.7 Exterior algebra
-----------------------

The `itensor' package can perform operations on totally antisymmetric
covariant tensor fields. A totally antisymmetric tensor field of rank
(0,L) corresponds with a differential L-form. On these objects, a
multiplication operation known as the exterior product, or wedge
product, is defined.

   Unfortunately, not all authors agree on the definition of the wedge
product. Some authors prefer a definition that corresponds with the
notion of antisymmetrization: in these works, the wedge product of two
vector fields, for instance, would be defined as

                 a a  - a a
                  i j    j i
      a  /\ a  = -----------
       i     j        2

   More generally, the product of a p-form and a q-form would be
defined as

                            1     k1..kp l1..lq
     A       /\ B       = ------ D              A       B
      i1..ip     j1..jq   (p+q)!  i1..ip j1..jq  k1..kp  l1..lq

   where `D' stands for the Kronecker-delta.

   Other authors, however, prefer a "geometric" definition that
corresponds with the notion of the volume element:

     a  /\ a  = a a  - a a
      i     j    i j    j i

   and, in the general case

                            1    k1..kp l1..lq
     A       /\ B       = ----- D              A       B
      i1..ip     j1..jq   p! q!  i1..ip j1..jq  k1..kp  l1..lq

   Since `itensor' is a tensor algebra package, the first of these two
definitions appears to be the more natural one. Many applications,
however, utilize the second definition. To resolve this dilemma, a flag
has been implemented that controls the behavior of the wedge product: if
`igeowedge_flag' is `false' (the default), the first, "tensorial"
definition is used, otherwise the second, "geometric" definition will
be applied.

 -- Operator: ~
     The wedge product operator is denoted by the tilde `~'. This is a
     binary operator. Its arguments should be expressions involving
     scalars, covariant tensors of rank one, or covariant tensors of
     rank `l' that have been declared antisymmetric in all covariant
     indices.

     The behavior of the wedge product operator is controlled by the
     `igeowedge_flag' flag, as in the following example:

          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) ishow(a([i])~b([j]))$
                                           a  b  - b  a
                                            i  j    i  j
          (%t2)                            -------------
                                                 2
          (%i3) decsym(a,2,0,[anti(all)],[]);
          (%o3)                                done
          (%i4) ishow(a([i,j])~b([k]))$
                                    a    b  + b  a    - a    b
                                     i j  k    i  j k    i k  j
          (%t4)                     ---------------------------
                                                 3
          (%i5) igeowedge_flag:true;
          (%o5)                                true
          (%i6) ishow(a([i])~b([j]))$
          (%t6)                            a  b  - b  a
                                            i  j    i  j
          (%i7) ishow(a([i,j])~b([k]))$
          (%t7)                     a    b  + b  a    - a    b
                                     i j  k    i  j k    i k  j


 -- Operator: |
     The vertical bar `|' denotes the "contraction with a vector" binary
     operation. When a totally antisymmetric covariant tensor is
     contracted with a contravariant vector, the result is the same
     regardless which index was used for the contraction. Thus, it is
     possible to define the contraction operation in an index-free
     manner.

     In the `itensor' package, contraction with a vector is always
     carried out with respect to the first index in the literal sorting
     order. This ensures better simplification of expressions involving
     the `|' operator. For instance:

          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) decsym(a,2,0,[anti(all)],[]);
          (%o2)                                done
          (%i3) ishow(a([i,j],[])|v)$
                                              %1
          (%t3)                              v   a
                                                  %1 j
          (%i4) ishow(a([j,i],[])|v)$
                                               %1
          (%t4)                             - v   a
                                                   %1 j

     Note that it is essential that the tensors used with the `|'
     operator be declared totally antisymmetric in their covariant
     indices. Otherwise, the results will be incorrect.


 -- Function: extdiff (<expr>, <i>)
     Computes the exterior derivative of <expr> with respect to the
     index <i>. The exterior derivative is formally defined as the wedge
     product of the partial derivative operator and a differential
     form. As such, this operation is also controlled by the setting of
     `igeowedge_flag'.  For instance:

          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) ishow(extdiff(v([i]),j))$
                                            v    - v
                                             j,i    i,j
          (%t2)                             -----------
                                                 2
          (%i3) decsym(a,2,0,[anti(all)],[]);
          (%o3)                                done
          (%i4) ishow(extdiff(a([i,j]),k))$
                                     a      - a      + a
                                      j k,i    i k,j    i j,k
          (%t4)                      ------------------------
                                                3
          (%i5) igeowedge_flag:true;
          (%o5)                                true
          (%i6) ishow(extdiff(v([i]),j))$
          (%t6)                             v    - v
                                             j,i    i,j
          (%i7) ishow(extdiff(a([i,j]),k))$
          (%t7)                    - (a      - a      + a     )
                                       k j,i    k i,j    j i,k


 -- Function: hodge (<expr>)
     Compute the Hodge-dual of <expr>. For instance:


          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) imetric(g);
          (%o2)                            done
          (%i3) idim(4);
          (%o3)                            done
          (%i4) icounter:100;
          (%o4)                             100
          (%i5) decsym(A,3,0,[anti(all)],[])$

          (%i6) ishow(A([i,j,k],[]))$
          (%t6)                           A
                                           i j k
          (%i7) ishow(canform(hodge(%)))$
                                    %1 %2 %3 %4
                         levi_civita            g        A
                                                 %1 %102  %2 %3 %4
          (%t7)          -----------------------------------------
                                             6
          (%i8) ishow(canform(hodge(%)))$
                           %1 %2 %3 %8            %4 %5 %6 %7
          (%t8) levi_civita            levi_civita            g
                                                               %1 %106
                                       g        g        g      A         /6
                                        %2 %107  %3 %108  %4 %8  %5 %6 %7
          (%i9) lc2kdt(%)$

          (%i10) %,kdelta$

          (%i11) ishow(canform(contract(expand(%))))$
          (%t11)                     - A
                                        %106 %107 %108


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

     Controls the behavior of the wedge product and exterior
     derivative. When set to `false' (the default), the notion of
     differential forms will correspond with that of a totally
     antisymmetric covariant tensor field.  When set to `true',
     differential forms will agree with the notion of the volume
     element.


25.2.8 Exporting TeX expressions
--------------------------------

The `itensor' package provides limited support for exporting tensor
expressions to TeX. Since `itensor' expressions appear as function
calls, the regular Maxima `tex' command will not produce the expected
output. You can try instead the `tentex' command, which attempts to
translate tensor expressions into appropriately indexed TeX objects.

 -- Function: tentex (<expr>)
     To use the `tentex' function, you must first load `tentex', as in
     the following example:

          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) load(tentex);
          (%o2)       /share/tensor/tentex.lisp
          (%i3) idummyx:m;
          (%o3)                                  m
          (%i4) ishow(icurvature([j,k,l],[i]))$
                      m1       i           m1       i           i
          (%t4)  ichr2    ichr2     - ichr2    ichr2     - ichr2
                      j k      m1 l        j l      m1 k        j l,k

                                                                i
                                                         + ichr2
                                                                j k,l
          (%i5) tentex(%)$
          $$\Gamma_{j\,k}^{m_1}\,\Gamma_{l\,m_1}^{i}-\Gamma_{j\,l}^{m_1}\,
           \Gamma_{k\,m_1}^{i}-\Gamma_{j\,l,k}^{i}+\Gamma_{j\,k,l}^{i}$$

     Note the use of the `idummyx' assignment, to avoid the appearance
     of the percent sign in the TeX expression, which may lead to
     compile errors.

     NB: This version of the `tentex' function is somewhat experimental.


25.2.9 Interfacing with ctensor
-------------------------------

The `itensor' package has the ability to generate Maxima code that can
then be executed in the context of the `ctensor' package. The function
that performs this task is `ic_convert'.

 -- Function: ic_convert (<eqn>)
     Converts the `itensor' equation <eqn> to a `ctensor' assignment
     statement.  Implied sums over dummy indices are made explicit
     while indexed objects are transformed into arrays (the array
     subscripts are in the order of covariant followed by contravariant
     indices of the indexed objects). The derivative of an indexed
     object will be replaced by the noun form of `diff' taken with
     respect to `ct_coords' subscripted by the derivative index. The
     Christoffel symbols `ichr1' and `ichr2' will be translated to
     `lcs' and `mcs', respectively and if `metricconvert' is `true'
     then all occurrences of the metric with two covariant
     (contravariant) indices will be renamed to `lg' (`ug'). In
     addition, `do' loops will be introduced summing over all free
     indices so that the transformed assignment statement can be
     evaluated by just doing `ev'. The following examples demonstrate
     the features of this function.

          (%i1) load(itensor);
          (%o1)      /share/tensor/itensor.lisp
          (%i2) eqn:ishow(t([i,j],[k])=f([],[])*g([l,m],[])*a([],[m],j)
                *b([i],[l,k]))$
                                       k        m   l k
          (%t2)                       t    = f a   b    g
                                       i j      ,j  i    l m
          (%i3) ic_convert(eqn);
          (%o3) for i thru dim do (for j thru dim do (
                 for k thru dim do
                  t        : f sum(sum(diff(a , ct_coords ) b
                   i, j, k                   m           j   i, l, k

           g    , l, 1, dim), m, 1, dim)))
            l, m
          (%i4) imetric(g);
          (%o4)                                done
          (%i5) metricconvert:true;
          (%o5)                                true
          (%i6) ic_convert(eqn);
          (%o6) for i thru dim do (for j thru dim do (
                 for k thru dim do
                  t        : f sum(sum(diff(a , ct_coords ) b
                   i, j, k                   m           j   i, l, k

           lg    , l, 1, dim), m, 1, dim)))
             l, m


25.2.10 Reserved words
----------------------

The following Maxima words are used by the `itensor' package internally
and should not be redefined:

       Keyword    Comments
       ------------------------------------------
       indices2() Internal version of indices()
       conti      Lists contravariant indices
       covi       Lists covariant indices of a indexed object
       deri       Lists derivative indices of an indexed object
       name       Returns the name of an indexed object
       concan
       irpmon
       lc0
       _lc2kdt0
       _lcprod
       _extlc


File: maxima.info,  Node: ctensor,  Next: atensor,  Prev: itensor,  Up: Top

26 ctensor
**********

* Menu:

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


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

26.1 Introduction to ctensor
============================

`ctensor' is a component tensor manipulation package.  To use the
`ctensor' package, type `load(ctensor)'.  To begin an interactive
session with `ctensor', type `csetup()'.  You are first asked to
specify the dimension of the manifold. If the dimension is 2, 3 or 4
then the list of coordinates defaults to `[x,y]', `[x,y,z]' or
`[x,y,z,t]' respectively.  These names may be changed by assigning a
new list of coordinates to the variable `ct_coords' (described below)
and the user is queried about this. Care must be taken to avoid the
coordinate names conflicting with other object definitions.

   Next, the user enters the metric either directly or from a file by
specifying its ordinal position.  The metric is stored in the matrix
`lg'. Finally, the metric inverse is computed and stored in the matrix
`ug'. One has the option of carrying out all calculations in a power
series.

   A sample protocol is begun below for the static, spherically
symmetric metric (standard coordinates) which will be applied to the
problem of deriving Einstein's vacuum equations (which lead to the
Schwarzschild solution) as an example. Many of the functions in
`ctensor' will be displayed for the standard metric as examples.

     (%i1) load(ctensor);
     (%o1)      /share/tensor/ctensor.mac
     (%i2) csetup();
     Enter the dimension of the coordinate system:
     4;
     Do you wish to change the coordinate names?
     n;
     Do you want to
     1. Enter a new metric?

     2. Enter a metric from a file?

     3. Approximate a metric with a Taylor series?
     1;

     Is the matrix  1. Diagonal  2. Symmetric  3. Antisymmetric  4. General
     Answer 1, 2, 3 or 4
     1;
     Row 1 Column 1:
     a;
     Row 2 Column 2:
     x^2;
     Row 3 Column 3:
     x^2*sin(y)^2;
     Row 4 Column 4:
     -d;

     Matrix entered.
     Enter functional dependencies with the DEPENDS function or 'N' if none
     depends([a,d],x);
     Do you wish to see the metric?
     y;
                               [ a  0       0        0  ]
                               [                        ]
                               [     2                  ]
                               [ 0  x       0        0  ]
                               [                        ]
                               [         2    2         ]
                               [ 0  0   x  sin (y)   0  ]
                               [                        ]
                               [ 0  0       0       - d ]
     (%o2)                                done
     (%i3) christof(mcs);
                                                 a
                                                  x
     (%t3)                          mcs        = ---
                                       1, 1, 1   2 a

                                                  1
     (%t4)                           mcs        = -
                                        1, 2, 2   x

                                                  1
     (%t5)                           mcs        = -
                                        1, 3, 3   x

                                                 d
                                                  x
     (%t6)                          mcs        = ---
                                       1, 4, 4   2 d

                                                   x
     (%t7)                          mcs        = - -
                                       2, 2, 1     a

                                                cos(y)
     (%t8)                         mcs        = ------
                                      2, 3, 3   sin(y)

                                                    2
                                               x sin (y)
     (%t9)                      mcs        = - ---------
                                   3, 3, 1         a

     (%t10)                   mcs        = - cos(y) sin(y)
                                 3, 3, 2

                                                 d
                                                  x
     (%t11)                         mcs        = ---
                                       4, 4, 1   2 a
     (%o11)                               done

