File: maxima_41.html

package info (click to toggle)
maxima 5.10.0-6
links: PTS
area: main
in suites: etch, etch-m68k
size: 44,268 kB
ctags: 17,987
sloc: lisp: 152,894; fortran: 14,667; perl: 14,204; tcl: 10,103; sh: 3,376; makefile: 2,202; ansic: 471; awk: 7
file content (876 lines) | stat: -rw-r--r-- 37,275 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on September, 20 2006 by texi2html 1.76 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
            Karl Berry  <karl@freefriends.org>
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
            and many others.
Maintained by: Many creative people <dev@texi2html.cvshome.org>
Send bugs and suggestions to <users@texi2html.cvshome.org>

-->
<head>
<title>Maxima Manual: 41. Program Flow</title>

<meta name="description" content="Maxima Manual: 41. Program Flow">
<meta name="keywords" content="Maxima Manual: 41. Program Flow">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.76">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
body
{
    color: black;
    background: white; 
    margin-left: 8%;
    margin-right: 13%;
}

h1
{
    margin-left: +8%;
    font-size: 150%;
    font-family: sans-serif
}

h2
{
    font-size: 125%;
    font-family: sans-serif
}

h3
{
    font-size: 100%;
    font-family: sans-serif
}

h2,h3,h4,h5,h6 { margin-left: +4%; }

div.textbox
{
    border: solid;
    border-width: thin;
    /* width: 100%; */
    padding-top: 1em;
    padding-bottom: 1em;
    padding-left: 2em;
    padding-right: 2em
}

div.titlebox
{
    border: none;
    padding-top: 1em;
    padding-bottom: 1em;
    padding-left: 2em;
    padding-right: 2em;
    background: rgb(200,255,255);
    font-family: sans-serif
}

div.synopsisbox
{
    border: none;
    padding-top: 1em;
    padding-bottom: 1em;
    padding-left: 2em;
    padding-right: 2em;
     background: rgb(255,220,255);
    /*background: rgb(200,255,255); */
    /* font-family: fixed */
}

pre.example
{
    border: none;
    padding-top: 1em;
    padding-bottom: 1em;
    padding-left: 1em;
    padding-right: 1em;
    background: rgb(247,242,180); /* kind of sandy */
    /* background: rgb(200,255,255); */ /* sky blue */
    font-family: "Lucida Console", monospace
}

div.spacerbox
{
    border: none;
    padding-top: 2em;
    padding-bottom: 2em
}

div.image
{
    margin: 0;
    padding: 1em;
    text-align: center;
}
-->
</style>

<link rel="icon" href="http://maxima.sourceforge.net/favicon.ico"/>
</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">

<a name="Program-Flow"></a>
<a name="SEC162"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="maxima_40.html#SEC161" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC163" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima_40.html#SEC155" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_42.html#SEC165" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h1 class="chapter"> 41. Program Flow </h1>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#SEC163">41.1 Introduction to Program Flow</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">  
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC164">41.2 Definitions for Program Flow</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">  
</td></tr>
</table>

<hr size="6">
<a name="Introduction-to-Program-Flow"></a>
<a name="SEC163"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC162" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC164" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC162" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_42.html#SEC165" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 41.1 Introduction to Program Flow </h2>

<p>Maxima provides a <code>do</code> loop for iteration, as well as more primitive
constructs such as <code>go</code>.
</p>
<hr size="6">
<a name="Definitions-for-Program-Flow"></a>
<a name="SEC164"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC163" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="maxima_42.html#SEC165" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC162" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_42.html#SEC165" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 41.2 Definitions for Program Flow </h2>

<dl>
<dt><u>Function:</u> <b>backtrace</b><i> ()</i>
<a name="IDX1346"></a>
</dt>
<dt><u>Function:</u> <b>backtrace</b><i> (<var>n</var>)</i>
<a name="IDX1347"></a>
</dt>
<dd><p>Prints the call stack, that is, the list of functions which
called the currently active function.
</p>
<p><code>backtrace()</code> prints the entire call stack.
</p>
<p><code>backtrace (<var>n</var>)</code> prints the <var>n</var> most recent 
functions, including the currently active function.
</p>
<p><code>backtrace</code> can be called from a script, a function, or the interactive prompt
(not only in a debugging context).
</p>
<p>Examples:
</p>
<ul>
<li>
<code>backtrace()</code> prints the entire call stack.

<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) h(x) := g(x/7)$
(%i2) g(x) := f(x-11)$
(%i3) f(x) := e(x^2)$
(%i4) e(x) := (backtrace(), 2*x + 13)$
(%i5) h(10);
#0: e(x=4489/49)
#1: f(x=-67/7)
#2: g(x=10/7)
#3: h(x=10)
                              9615
(%o5)                         ----
                               49
</pre></td></tr></table></li></ul>

<ul>
<li>
<code>backtrace (<var>n</var>)</code> prints the <var>n</var> most recent 
functions, including the currently active function.

<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) h(x) := (backtrace(1), g(x/7))$
(%i2) g(x) := (backtrace(1), f(x-11))$
(%i3) f(x) := (backtrace(1), e(x^2))$
(%i4) e(x) := (backtrace(1), 2*x + 13)$
(%i5) h(10);
#0: h(x=10)
#0: g(x=10/7)
#0: f(x=-67/7)
#0: e(x=4489/49)
                              9615
(%o5)                         ----
                               49
</pre></td></tr></table></li></ul>

</dd></dl>

<dl>
<dt><u>Special operator:</u> <b>do</b>
<a name="IDX1348"></a>
</dt>
<dd><p>The <code>do</code> statement is used for performing iteration.  Due to its
great generality the <code>do</code> statement will be described in two parts.
First the usual form will be given which is analogous to that used in
several other programming languages (Fortran, Algol, PL/I, etc.); then
the other features will be mentioned.
</p>
<p>There are three variants of this form that differ only in their
terminating conditions.  They are:
</p>
<ul>
<li>
<code>for <var>variable</var>: <var>initial_value</var> step <var>increment</var>
      thru <var>limit</var> do <var>body</var></code>
</li><li>
<code>for <var>variable</var>: <var>initial_value</var> step <var>increment</var>
      while <var>condition</var> do <var>body</var></code>
</li><li>
<code>for <var>variable</var>: <var>initial_value</var> step <var>increment</var>
      unless <var>condition</var> do <var>body</var></code>
</li></ul>

<p>(Alternatively, the <code>step</code> may be given after the termination condition
or limit.)
</p>
<p><var>initial_value</var>, <var>increment</var>, <var>limit</var>, and <var>body</var> can be any
expressions.  If the increment is 1 then &quot;<code>step 1</code>&quot; may be omitted.
</p>
<p>The execution of the <code>do</code> statement proceeds by first assigning the
initial_value to the variable (henceforth called the
control-variable). Then: (1) If the control-variable has exceeded the
limit of a <code>thru</code> specification, or if the condition of the <code>unless</code> is
<code>true</code>, or if the condition of the <code>while</code> is <code>false</code> then the <code>do</code>
terminates. (2) The body is evaluated.  (3) The increment is added to
the control-variable.  The process from (1) to (3) is performed
repeatedly until the termination condition is satisfied.  One may also
give several termination conditions in which case the <code>do</code> terminates
when any of them is satisfied.
</p>
<p>In general the <code>thru</code> test is satisfied when the control-variable is
greater than the limit if the increment was non-negative, or when the
control-variable is less than the limit if the increment was negative.
The increment and limit may be non-numeric expressions as long as this
inequality can be determined.  However, unless the increment is
syntactically negative (e.g. is a negative number) at the time the <code>do</code>
statement is input, Maxima assumes it will be positive when the <code>do</code> is
executed.  If it is not positive, then the <code>do</code> may not terminate
properly.
</p>
<p>Note that the limit, increment, and termination condition are
evaluated each time through the loop.  Thus if any of these involve
much computation, and yield a result that does not change during all
the executions of the body, then it is more efficient to set a
variable to their value prior to the <code>do</code> and use this variable in the
<code>do</code> form.
</p>
<p>The value normally returned by a <code>do</code> statement is the atom <code>done</code>.
However, the function
<code>return</code> may be used inside the body to exit the <code>do</code> prematurely and give
it any desired value.
Note however that a <code>return</code> within a <code>do</code> that
occurs in a <code>block</code> will exit only the <code>do</code> and not the <code>block</code>.  Note also
that the <code>go</code> function may not be used to exit from a <code>do</code> into a
surrounding <code>block</code>.
</p>
<p>The control-variable is always local to the <code>do</code> and thus any
variable may be used without affecting the value of a variable with
the same name outside of the <code>do</code>.  The control-variable is unbound
after the <code>do</code> terminates.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) for a:-3 thru 26 step 7 do display(a)$
                             a = - 3

                              a = 4

                             a = 11

                             a = 18

                             a = 25
</pre></td></tr></table>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) s: 0$
(%i2) for i: 1 while i &lt;= 10 do s: s+i;
(%o2)                         done
(%i3) s;
(%o3)                          55
</pre></td></tr></table>
<p>Note that the condition <code>while i &lt;= 10</code>
is equivalent to <code>unless i &gt; 10</code> and also <code>thru 10</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) series: 1$
(%i2) term: exp (sin (x))$
(%i3) for p: 1 unless p &gt; 7 do
          (term: diff (term, x)/p, 
           series: series + subst (x=0, term)*x^p)$
(%i4) series;
                  7    6     5    4    2
                 x    x     x    x    x
(%o4)            -- - --- - -- - -- + -- + x + 1
                 90   240   15   8    2
</pre></td></tr></table>
<p>which gives 8 terms of the Taylor series for <code>e^sin(x)</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) poly: 0$
(%i2) for i: 1 thru 5 do
          for j: i step -1 thru 1 do
              poly: poly + i*x^j$
(%i3) poly;
                  5      4       3       2
(%o3)          5 x  + 9 x  + 12 x  + 14 x  + 15 x
(%i4) guess: -3.0$
(%i5) for i: 1 thru 10 do
          (guess: subst (guess, x, 0.5*(x + 10/x)),
           if abs (guess^2 - 10) &lt; 0.00005 then return (guess));
(%o5)                  - 3.162280701754386
</pre></td></tr></table>
<p>This example computes the negative square root of 10 using the
Newton- Raphson iteration a maximum of 10 times.  Had the convergence
criterion not been met the value returned would have been <code>done</code>.
</p>
<p>Instead of always adding a quantity to the control-variable one
may sometimes wish to change it in some other way for each iteration.
In this case one may use <code>next <var>expression</var></code> instead of <code>step <var>increment</var></code>.
This will cause the control-variable to be set to the
result of evaluating expression each time through the loop.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i6) for count: 2 next 3*count thru 20 do display (count)$
                            count = 2

                            count = 6

                           count = 18
</pre></td></tr></table>
<p>As an alternative to <code>for <var>variable</var>: <var>value</var> ...do...</code> the syntax
<code>for <var>variable</var> from <var>value</var> ...do...</code>  may be used.  This permits the
<code>from <var>value</var></code> to be placed after the step or next value or after the
termination condition.  If <code>from <var>value</var></code> is omitted then 1 is used as
the initial value.
</p>
<p>Sometimes one may be interested in performing an iteration where
the control-variable is never actually used.  It is thus permissible
to give only the termination conditions omitting the initialization
and updating information as in the following example to compute the
square-root of 5 using a poor initial guess.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) x: 1000$
(%i2) thru 20 do x: 0.5*(x + 5.0/x)$
(%i3) x;
(%o3)                   2.23606797749979
(%i4) sqrt(5), numer;
(%o4)                   2.23606797749979
</pre></td></tr></table>
<p>If it is desired one may even omit the termination conditions
entirely and just give <code>do <var>body</var></code> which will continue to evaluate the
body indefinitely.  In this case the function <code>return</code> should be used to
terminate execution of the <code>do</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) newton (f, x):= ([y, df, dfx], df: diff (f ('x), 'x),
          do (y: ev(df), x: x - f(x)/y, 
              if abs (f (x)) &lt; 5e-6 then return (x)))$
(%i2) sqr (x) := x^2 - 5.0$
(%i3) newton (sqr, 1000);
(%o3)                   2.236068027062195
</pre></td></tr></table>
<p>(Note that <code>return</code>, when executed, causes the current value of
<code>x</code> to be returned as the value of the <code>do</code>.  The <code>block</code> is exited and
this value of the <code>do</code> is returned as the value of the <code>block</code> because the
<code>do</code> is the last statement in the block.)
</p>
<p>One other form of the <code>do</code> is available in Maxima.  The syntax is:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">for <var>variable</var> in <var>list</var> <var>end_tests</var> do <var>body</var>
</pre></td></tr></table>
<p>The elements of <var>list</var> are any expressions which will
successively be assigned to the variable on each iteration of the
body.  The optional termination tests <var>end_tests</var> can be used to terminate execution of
the <code>do</code>; otherwise it will terminate when the list is exhausted or when
a <code>return</code> is executed in the body.  (In fact, list may be any
non-atomic expression, and successive parts are taken.)
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1)  for f in [log, rho, atan] do ldisp(f(1))$
(%t1)                                  0
(%t2)                                rho(1)
                                     %pi
(%t3)                                 ---
                                      4
(%i4) ev(%t3,numer);
(%o4)                             0.78539816
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>errcatch</b><i> (<var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1349"></a>
</dt>
<dd><p>Evaluates <var>expr_1</var>, ..., <var>expr_n</var> one by one and
returns <code>[<var>expr_n</var>]</code> (a list) if no error occurs.  If an
error occurs in the evaluation of any argument, <code>errcatch</code> 
prevents the error from propagating and
returns the empty list <code>[]</code> without evaluating any more arguments.
</p>
<p><code>errcatch</code>
is useful in <code>batch</code> files where one suspects an error might occur which
would terminate the <code>batch</code> if the error weren't caught.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>error</b><i> (<var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1350"></a>
</dt>
<dt><u>System variable:</u> <b>error</b>
<a name="IDX1351"></a>
</dt>
<dd><p>Evaluates and prints <var>expr_1</var>, ..., <var>expr_n</var>,
and then causes an error return to top level Maxima
or to the nearest enclosing <code>errcatch</code>.
</p>
<p>The variable <code>error</code> is set to a list describing the error.
The first element of <code>error</code> is a format string,
which merges all the strings among the arguments <var>expr_1</var>, ..., <var>expr_n</var>,
and the remaining elements are the values of any non-string arguments.
</p>
<p><code>errormsg()</code> formats and prints <code>error</code>.
This is effectively reprinting the most recent error message.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>errormsg</b><i> ()</i>
<a name="IDX1352"></a>
</dt>
<dd><p>Reprints the most recent error message.
The variable <code>error</code> holds the message,
and <code>errormsg</code> formats and prints it.
</p>
</dd></dl>

<dl>
<dt><u>Special operator:</u> <b>for</b>
<a name="IDX1353"></a>
</dt>
<dd><p>Used in iterations. See <code>do</code> for a description of
Maxima's iteration facilities.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>go</b><i> (<var>tag</var>)</i>
<a name="IDX1354"></a>
</dt>
<dd><p>is used within a <code>block</code> to transfer control to the statement
of the block which is tagged with the argument to <code>go</code>.  To tag a
statement, precede it by an atomic argument as another statement in
the <code>block</code>.  For example:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">block ([x], x:1, loop, x+1, ..., go(loop), ...)
</pre></td></tr></table>
<p>The argument to <code>go</code> must be the name of a tag appearing in the same
<code>block</code>.  One cannot use <code>go</code> to transfer to tag in a <code>block</code> other than the
one containing the <code>go</code>.
</p>
</dd></dl>

<dl>
<dt><u>Special operator:</u> <b>if</b>
<a name="IDX1355"></a>
</dt>
<dd><p>The <code>if</code> statement is used for conditional execution.  The syntax
is:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">if &lt;condition&gt; then &lt;expr_1&gt; else &lt;expr_2&gt;
</pre></td></tr></table>
<p>The result of an <code>if</code> statement is <var>expr_1</var> if condition is <code>true</code> and
<var>expr_2</var> otherwise.  <var>expr_1</var> and <var>expr_2</var> are any
Maxima expressions (including nested <code>if</code> statements), and <var>condition</var> is
an expression which evaluates to <code>true</code> or <code>false</code> and is composed of
relational and logical operators which are as follows:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">Operation            Symbol      Type
 
less than            &lt;           relational infix
less than            &lt;=
  or equal to                    relational infix
equality (syntactic) =           relational infix
negation of =        #           relational infix
equality (value)     equal       relational function
negation of equal    notequal    relational function
greater than         &gt;=
  or equal to                    relational infix
greater than         &gt;           relational infix
and                  and         logical infix
or                   or          logical infix
not                  not         logical prefix
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>map</b><i> (<var>f</var>, <var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1356"></a>
</dt>
<dd><p>Returns an expression whose leading operator
is the same as that of the expressions
<var>expr_1</var>, ..., <var>expr_n</var> but whose subparts are the results of
applying <var>f</var> to the corresponding subparts of the expressions.  <var>f</var> is either
the name of a function of <em>n</em> arguments
or is a <code>lambda</code> form of <em>n</em> arguments.
</p>
<p><code>maperror</code> - if <code>false</code> will cause all of the mapping functions to
(1) stop when they finish going down the shortest expi if not all of
the expi are of the same length and (2) apply fn to [exp1, exp2,...]
if the expi are not all the same type of object. If <code>maperror</code> is <code>true</code>
then an error message will be given in the above two instances.
</p>
<p>One of the uses of this function is to <code>map</code> a function (e.g. <code>partfrac</code>)
onto each term of a very large expression where it ordinarily wouldn't
be possible to use the function on the entire expression due to an
exhaustion of list storage space in the course of the computation.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) map(f,x+a*y+b*z);
(%o1)                        f(b z) + f(a y) + f(x)
(%i2) map(lambda([u],partfrac(u,x)),x+1/(x^3+4*x^2+5*x+2));
                           1       1        1
(%o2)                     ----- - ----- + -------- + x
                         x + 2   x + 1          2
                                         (x + 1)
(%i3) map(ratsimp, x/(x^2+x)+(y^2+y)/y);
                                      1
(%o3)                            y + ----- + 1
                                    x + 1
(%i4) map(&quot;=&quot;,[a,b],[-0.5,3]);
(%o4)                          [a = - 0.5, b = 3]


</pre></td></tr></table></dd></dl>

<dl>
<dt><u>Function:</u> <b>mapatom</b><i> (<var>expr</var>)</i>
<a name="IDX1357"></a>
</dt>
<dd><p>Returns <code>true</code> if and only if <var>expr</var> is treated by the mapping
routines as an atom.  &quot;Mapatoms&quot; are atoms, numbers
(including rational numbers), and subscripted variables.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>maperror</b>
<a name="IDX1358"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>When <code>maperror</code> is <code>false</code>, causes all of the mapping functions, for example
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">map (f, expr_1, expr_2, ...))
</pre></td></tr></table>
<p>to (1) stop when they finish
going down the shortest expi if not all of the expi are of the same
length and (2) apply <code>f</code> to <code>[expr_1, expr_2, ...]</code> if the <code>expr_i</code> are not all
the same type of object.
</p>
<p>If <code>maperror</code> is <code>true</code> then an error message
is displayed in the above two instances.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>maplist</b><i> (<var>f</var>, <var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1359"></a>
</dt>
<dd><p>Returns a list of the applications of <var>f</var>
to the parts of the expressions <var>expr_1</var>, ..., <var>expr_n</var>.
<var>f</var> is the name of a function, or a lambda expression.
</p>
<p><code>maplist</code> differs from <code>map (<var>f</var>, <var>expr_1</var>, ..., <var>expr_n</var>)</code>
which returns an expression with the same main operator as <var>expr_i</var> has
(except for simplifications and the case where <code>map</code> does an <code>apply</code>).
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>prederror</b>
<a name="IDX1360"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>When <code>prederror</code> is <code>true</code>, an error message is displayed
whenever the predicate of an <code>if</code> statement or an <code>is</code> function fails to
evaluate to either <code>true</code> or <code>false</code>.
</p>
<p>If <code>false</code>, <code>unknown</code> is returned
instead in this case.  The <code>prederror: false</code> mode is not supported in
translated code;
however, <code>maybe</code> is supported in translated code.
</p>
<p>See also <code>is</code> and <code>maybe</code>.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>return</b><i> (value)</i>
<a name="IDX1361"></a>
</dt>
<dd><p>May be used to exit explicitly from a block, bringing
its argument.  See <code>block</code> for more information.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>scanmap</b><i> (<var>f</var>, <var>expr</var>)</i>
<a name="IDX1362"></a>
</dt>
<dt><u>Function:</u> <b>scanmap</b><i> (<var>f</var>, <var>expr</var>, bottomup)</i>
<a name="IDX1363"></a>
</dt>
<dd><p>Recursively applies <var>f</var> to <var>expr</var>, in a top
down manner.  This is most useful when complete factorization is
desired, for example:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) exp:(a^2+2*a+1)*y + x^2$
(%i2) scanmap(factor,exp);
                                    2      2
(%o2)                         (a + 1)  y + x
</pre></td></tr></table>
<p>Note the way in which <code>scanmap</code> applies the given function <code>factor</code> to the
constituent subexpressions of <var>expr</var>; if another form of <var>expr</var> is presented
to <code>scanmap</code> then the result may be different.  Thus, <code>%o2</code> is not
recovered when <code>scanmap</code> is applied to the expanded form of exp:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i3) scanmap(factor,expand(exp));
                           2                  2
(%o3)                      a  y + 2 a y + y + x
</pre></td></tr></table>
<p>Here is another example of the way in which <code>scanmap</code> recursively
applies a given function to all subexpressions, including exponents:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i4) expr : u*v^(a*x+b) + c$
(%i5) scanmap('f, expr);
                    f(f(f(a) f(x)) + f(b))
(%o5) f(f(f(u) f(f(v)                      )) + f(c))
</pre></td></tr></table>
<p><code>scanmap (<var>f</var>, <var>expr</var>, bottomup)</code> applies <var>f</var> to <var>expr</var> in a
bottom-up manner.  E.g., for undefined <code>f</code>,
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">scanmap(f,a*x+b) -&gt;
   f(a*x+b) -&gt; f(f(a*x)+f(b)) -&gt; f(f(f(a)*f(x))+f(b))
scanmap(f,a*x+b,bottomup) -&gt; f(a)*f(x)+f(b)
    -&gt; f(f(a)*f(x))+f(b) -&gt;
     f(f(f(a)*f(x))+f(b))
</pre></td></tr></table>
<p>In this case, you get the same answer both
ways.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>throw</b><i> (<var>expr</var>)</i>
<a name="IDX1364"></a>
</dt>
<dd><p>Evaluates <var>expr</var> and throws the value back to the most recent
<code>catch</code>.  <code>throw</code> is used with <code>catch</code> as a nonlocal return
mechanism.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>outermap</b><i> (<var>f</var>, <var>a_1</var>, ..., <var>a_n</var>)</i>
<a name="IDX1365"></a>
</dt>
<dd><p>Applies the function <var>f</var> to each one of the elements of the outer product
<var>a_1</var> cross <var>a_2</var> ... cross <var>a_n</var>.
</p>
<p><var>f</var> is the name of a function of <em>n</em> arguments
or a lambda expression of <em>n</em> arguments.
Each argument <var>a_k</var> may be a list or nested list, or a matrix, or any other kind of expression.
</p>
<p>The <code>outermap</code> return value is a nested structure.
Let <var>x</var> be the return value.
Then <var>x</var> has the same structure as the first list, nested list, or matrix argument,
<code><var>x</var>[i_1]...[i_m]</code> has the same structure as the second list, nested list, or matrix argument,
<code><var>x</var>[i_1]...[i_m][j_1]...[j_n]</code> has the same structure as the third list, nested list, or matrix argument,
and so on,
where <var>m</var>, <var>n</var>, ... are the numbers of indices required to access the
elements of each argument (one for a list, two for a matrix, one or more for a nested list).
Arguments which are not lists or matrices have no effect on the structure of the return value.
</p>
<p>Note that the effect of <code>outermap</code> is different from that of applying <var>f</var>
to each one of the elements of the outer product returned by <code>cartesian_product</code>.
<code>outermap</code> preserves the structure of the arguments in the return value,
while <code>cartesian_product</code> does not.
</p>
<p><code>outermap</code> evaluates its arguments.
</p>
<p>See also <code>map</code>, <code>maplist</code>, and <code>apply</code>.
</p>
<p>Examples:
</p>
<p>Elementary examples of <code>outermap</code>.
To show the argument combinations more clearly, <code>F</code> is left undefined.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) outermap (F, [a, b, c], [1, 2, 3]);
(%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)], 
                                     [F(c, 1), F(c, 2), F(c, 3)]]
(%i2) outermap (F, matrix ([a, b], [c, d]), matrix ([1, 2], [3, 4]));
         [ [ F(a, 1)  F(a, 2) ]  [ F(b, 1)  F(b, 2) ] ]
         [ [                  ]  [                  ] ]
         [ [ F(a, 3)  F(a, 4) ]  [ F(b, 3)  F(b, 4) ] ]
(%o2)    [                                            ]
         [ [ F(c, 1)  F(c, 2) ]  [ F(d, 1)  F(d, 2) ] ]
         [ [                  ]  [                  ] ]
         [ [ F(c, 3)  F(c, 4) ]  [ F(d, 3)  F(d, 4) ] ]
(%i3) outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
       [ F(a, x, 1)  F(a, x, 2) ]  [ F(b, x, 1)  F(b, x, 2) ]
(%o3) [[                        ], [                        ]]
       [ F(a, x, 3)  F(a, x, 4) ]  [ F(b, x, 3)  F(b, x, 4) ]
(%i4) outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
       [ [ F(a, 1, x) ]  [ F(a, 2, x) ] ]
(%o4) [[ [            ]  [            ] ], 
       [ [ F(a, 1, y) ]  [ F(a, 2, y) ] ]
                              [ [ F(b, 1, x) ]  [ F(b, 2, x) ] ]
                              [ [            ]  [            ] ]]
                              [ [ F(b, 1, y) ]  [ F(b, 2, y) ] ]
(%i5) outermap (&quot;+&quot;, [a, b, c], [1, 2, 3]);
(%o5) [[a + 1, a + 2, a + 3], [b + 1, b + 2, b + 3], 
                                           [c + 1, c + 2, c + 3]]
</pre></td></tr></table>
<p>A closer examination of the <code>outermap</code> return value.
The first, second, and third arguments are a matrix, a list, and a matrix, respectively.
The return value is a matrix.
Each element of that matrix is a list,
and each element of each list is a matrix.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) arg_1 :  matrix ([a, b], [c, d]);
                            [ a  b ]
(%o1)                       [      ]
                            [ c  d ]
(%i2) arg_2 : [11, 22];
(%o2)                       [11, 22]
(%i3) arg_3 : matrix ([xx, yy]);
(%o3)                      [ xx  yy ]
(%i4) xx_0 : outermap (lambda ([x, y, z], x / y + z), arg_1, arg_2, arg_3);
               [  [      a        a  ]  [      a        a  ]  ]
               [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
               [  [      11       11 ]  [      22       22 ]  ]
(%o4)  Col 1 = [                                              ]
               [  [      c        c  ]  [      c        c  ]  ]
               [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
               [  [      11       11 ]  [      22       22 ]  ]
                 [  [      b        b  ]  [      b        b  ]  ]
                 [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
                 [  [      11       11 ]  [      22       22 ]  ]
         Col 2 = [                                              ]
                 [  [      d        d  ]  [      d        d  ]  ]
                 [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
                 [  [      11       11 ]  [      22       22 ]  ]
(%i5) xx_1 : xx_0 [1][1];
           [      a        a  ]  [      a        a  ]
(%o5)     [[ xx + --  yy + -- ], [ xx + --  yy + -- ]]
           [      11       11 ]  [      22       22 ]
(%i6) xx_2 : xx_0 [1][1] [1];
                      [      a        a  ]
(%o6)                 [ xx + --  yy + -- ]
                      [      11       11 ]
(%i7) xx_3 : xx_0 [1][1] [1] [1][1];
                                  a
(%o7)                        xx + --
                                  11
(%i8) [op (arg_1), op (arg_2), op (arg_3)];
(%o8)                  [matrix, [, matrix]
(%i9) [op (xx_0), op (xx_1), op (xx_2)];
(%o9)                  [matrix, [, matrix]
</pre></td></tr></table>
<p><code>outermap</code> preserves the structure of the arguments in the return value,
while <code>cartesian_product</code> does not.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) outermap (F, [a, b, c], [1, 2, 3]);
(%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)], 
                                     [F(c, 1), F(c, 2), F(c, 3)]]
(%i2) setify (flatten (%));
(%o2) {F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3), 
                                       F(c, 1), F(c, 2), F(c, 3)}
(%i3) map (lambda ([L], apply (F, L)), cartesian_product ({a, b, c}, {1, 2, 3}));
(%o3) {F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3), 
                                       F(c, 1), F(c, 2), F(c, 3)}
(%i4) is (equal (%, %th (2)));
(%o4)                         true
</pre></td></tr></table>
</dd></dl>

<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC162" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="maxima_42.html#SEC165" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
 <font size="-1">
  This document was generated by <em>Robert Dodier</em> on <em>September, 20 2006</em> using <a href="http://texi2html.cvshome.org/"><em>texi2html 1.76</em></a>.
 </font>
 <br>

</p>
</body>
</html>