| blob | 782980b0a6de401e09c870abdfb68145e65a28d4 |
1 @menu
2 * Lisp and Maxima::
3 * Garbage Collection::
4 * Introduction to Program Flow::
5 * Functions and Variables for Program Flow::
6 @end menu
8 @c -----------------------------------------------------------------------------
9 @node Lisp and Maxima, Garbage Collection, Program Flow, Program Flow
10 @section Lisp and Maxima
11 @c -----------------------------------------------------------------------------
13 Maxima is written in Lisp, and it is easy to access Lisp functions and variables
14 from Maxima and vice versa. Lisp and Maxima symbols are distinguished by a
15 naming convention. A Lisp symbol which begins with a dollar sign @code{$}
16 corresponds to a Maxima symbol without the dollar sign.
18 @c NEED TO MENTION THIS OR IS IT JUST CLUTTERING ??
19 @c This includes special Maxima variables such as @code{%} and input and output
20 @c labels, which appear as @code{$%}, @code{$%i1}, @code{$%o1}, etc., in Lisp.
22 A Maxima symbol which begins with a question mark @code{?} corresponds to a Lisp
23 symbol without the question mark. For example, the Maxima symbol @code{foo}
24 corresponds to the Lisp symbol @code{$FOO}, while the Maxima symbol @code{?foo}
25 corresponds to the Lisp symbol @code{FOO}. Note that @code{?foo} is written
26 without a space between @code{?} and @code{foo}; otherwise it might be mistaken
27 for @code{describe ("foo")}.
29 Hyphen @code{-}, asterisk @code{*}, or other special characters in Lisp symbols
30 must be escaped by backslash @code{\} where they appear in Maxima code. For
31 example, the Lisp identifier @code{*foo-bar*} is written @code{?\*foo\-bar\*}
32 in Maxima.
34 Lisp code may be executed from within a Maxima session. A single line of Lisp
35 (containing one or more forms) may be executed by the special command
36 @code{:lisp}. For example,
38 @example
39 (%i1) :lisp (foo $x $y)
40 @end example
42 @noindent
43 calls the Lisp function @code{foo} with Maxima variables @code{x} and @code{y}
44 as arguments. The @code{:lisp} construct can appear at the interactive prompt
45 or in a file processed by @mref{batch} or @mrefcomma{demo} but not in a file
46 processed by @mrefcomma{load} @mrefcomma{batchload}@w{}
47 @mrefcomma{translate_file} or @mrefdot{compile_file}
49 The function @mref{to_lisp} opens an interactive Lisp session.
50 Entering @code{(to-maxima)} closes the Lisp session and returns to Maxima.
51 @c I DON'T EVEN WANT TO MENTION USING CTRL-C TO OPEN A LISP SESSION.
52 @c (1) IT TAKES EXTRA SET UP TO GET STARTED NAMELY :lisp (setq *debugger-hook* nil)
53 @c (2) IT GETS SCREWED UP EASILY -- TYPE SOMETHING WRONG AND YOU CAN'T GET BACK TO MAXIMA
54 @c (3) IT DOESN'T OFFER FUNCTIONALITY NOT PRESENT IN THE to_lisp() SESSION
56 Lisp functions and variables which are to be visible in Maxima as functions and
57 variables with ordinary names (no special punctuation) must have Lisp names
58 beginning with the dollar sign @code{$}.
60 Maxima is case-sensitive, distinguishing between lowercase and uppercase letters
61 in identifiers. There are some rules governing the translation of names between
62 Lisp and Maxima.
64 @enumerate
65 @item
66 A Lisp identifier not enclosed in vertical bars corresponds to a Maxima
67 identifier in lowercase. Whether the Lisp identifier is uppercase, lowercase,
68 or mixed case, is ignored. E.g., Lisp @code{$foo}, @code{$FOO}, and @code{$Foo}
69 all correspond to Maxima @code{foo}. But this is because @code{$foo},
70 @code{$FOO} and @code{$Foo} are converted by the Lisp reader by default to the
71 Lisp symbol @code{$FOO}.
72 @item
73 A Lisp identifier which is all uppercase or all lowercase and enclosed in
74 vertical bars corresponds to a Maxima identifier with case reversed. That is,
75 uppercase is changed to lowercase and lowercase to uppercase. E.g., Lisp
76 @code{|$FOO|} and @code{|$foo|} correspond to Maxima @code{foo} and @code{FOO},
77 respectively.
78 @item
79 A Lisp identifier which is mixed uppercase and lowercase and enclosed in
80 vertical bars corresponds to a Maxima identifier with the same case. E.g.,
81 Lisp @code{|$Foo|} corresponds to Maxima @code{Foo}.
82 @end enumerate
84 The @code{#$} Lisp macro allows the use of Maxima expressions in Lisp code.
85 @code{#$@var{expr}$} expands to a Lisp expression equivalent to the Maxima
86 expression @var{expr}.
88 @example
89 (msetq $foo #$[x, y]$)
90 @end example
92 @noindent
93 This has the same effect as entering
95 @example
96 (%i1) foo: [x, y];
97 @end example
99 @noindent
100 The Lisp function @code{displa} prints an expression in Maxima format.
102 @example
103 (%i1) :lisp #$[x, y, z]$
104 ((MLIST SIMP) $X $Y $Z)
105 (%i1) :lisp (displa '((MLIST SIMP) $X $Y $Z))
106 [x, y, z]
107 NIL
108 @end example
110 Functions defined in Maxima are not ordinary Lisp functions. The Lisp function
111 @code{mfuncall} calls a Maxima function. For example:
113 @example
114 (%i1) foo(x,y) := x*y$
115 (%i2) :lisp (mfuncall '$foo 'a 'b)
116 ((MTIMES SIMP) A B)
117 @end example
119 Some Lisp functions are shadowed in the Maxima package, namely the following.
121 @verbatim
122 complement continue //
123 float functionp array
124 exp listen signum
125 atan asin acos
126 asinh acosh atanh
127 tanh cosh sinh
128 tan break gcd
129 @end verbatim
131 @opencatbox
132 @category{Programming}
133 @closecatbox
135 @c -----------------------------------------------------------------------------
136 @node Garbage Collection, Introduction to Program Flow, Lisp and Maxima, Program Flow
137 @section Garbage Collection
138 @c -----------------------------------------------------------------------------
140 Symbolic computation tends to create a good deal of garbage (temporary or
141 intermediate results that are eventually not used), and effective handling of
142 this can be crucial to successful completion of some programs.
144 @c HOW MUCH OF THE FOLLOWING STILL HOLDS ??
145 @c WHAT ABOUT GC IN GCL ON MS WINDOWS ??
146 @c SHOULD WE SAY SOMETHING ABOUT GC FOR OTHER LISPS ??
147 Under GCL, on UNIX systems where the mprotect system call is available
148 (including SUN OS 4.0 and some variants of BSD) a stratified garbage collection
149 is available. This limits the collection to pages which have been recently
150 written to. See the GCL documentation under ALLOCATE and GBC. At the Lisp
151 level doing (setq si::*notify-gbc* t) will help you determine which areas might
152 need more space.
154 For other Lisps that run Maxima, we refer the reader to the documentation for
155 that Lisp on how to control GC.
157 @c -----------------------------------------------------------------------------
158 @node Introduction to Program Flow, Functions and Variables for Program Flow, Garbage Collection, Program Flow
159 @section Introduction to Program Flow
160 @c -----------------------------------------------------------------------------
162 Maxima provides a @code{do} loop for iteration, as well as more primitive
163 constructs such as @code{go}.
165 @c end concepts Program Flow
167 @c -----------------------------------------------------------------------------
168 @node Functions and Variables for Program Flow, , Introduction to Program Flow, Program Flow
169 @section Functions and Variables for Program Flow
170 @c -----------------------------------------------------------------------------
172 @c -----------------------------------------------------------------------------
173 @anchor{backtrace}
174 @deffn {Function} backtrace @
175 @fname{backtrace} () @
176 @fname{backtrace} (@var{n})
178 Prints the call stack, that is, the list of functions which
179 called the currently active function.
181 @code{backtrace()} prints the entire call stack.
183 @code{backtrace (@var{n})} prints the @var{n} most recent
184 functions, including the currently active function.
186 @c IS THIS STATMENT REALLY NEEDED ??
187 @c (WHY WOULD ANYONE BELIEVE backtrace CANNOT BE CALLED OUTSIDE A DEBUGGING CONTEXT??)
188 @code{backtrace} can be called from a script, a function, or the interactive
189 prompt (not only in a debugging context).
191 Examples:
193 @itemize @bullet
194 @item
195 @code{backtrace()} prints the entire call stack.
197 @example
198 (%i1) h(x) := g(x/7)$
199 (%i2) g(x) := f(x-11)$
200 (%i3) f(x) := e(x^2)$
201 (%i4) e(x) := (backtrace(), 2*x + 13)$
202 (%i5) h(10);
203 #0: e(x=4489/49)
204 #1: f(x=-67/7)
205 #2: g(x=10/7)
206 #3: h(x=10)
207 9615
208 (%o5) ----
209 49
210 @end example
211 @end itemize
213 @itemize @bullet
214 @item
215 @code{backtrace (@var{n})} prints the @var{n} most recent
216 functions, including the currently active function.
218 @example
219 (%i1) h(x) := (backtrace(1), g(x/7))$
220 (%i2) g(x) := (backtrace(1), f(x-11))$
221 (%i3) f(x) := (backtrace(1), e(x^2))$
222 (%i4) e(x) := (backtrace(1), 2*x + 13)$
223 (%i5) h(10);
224 #0: h(x=10)
225 #0: g(x=10/7)
226 #0: f(x=-67/7)
227 #0: e(x=4489/49)
228 9615
229 (%o5) ----
230 49
231 @end example
232 @end itemize
234 @opencatbox
235 @category{Debugging}
236 @closecatbox
237 @end deffn
239 @c -----------------------------------------------------------------------------
240 @anchor{do}
241 @deffn {Special operator} do
242 @deffnx {Special operator} in
244 The @code{do} statement is used for performing iteration. Due to its
245 great generality the @code{do} statement will be described in two parts.
246 First the usual form will be given which is analogous to that used in
247 several other programming languages (Fortran, Algol, PL/I, etc.); then
248 the other features will be mentioned.
250 There are three variants of this form that differ only in their
251 terminating conditions. They are:
253 @itemize @bullet
254 @item
255 @code{for @var{variable}: @var{initial_value} step @var{increment}
256 thru @var{limit} do @var{body}}
257 @item
258 @code{for @var{variable}: @var{initial_value} step @var{increment}
259 while @var{condition} do @var{body}}
260 @item
261 @code{for @var{variable}: @var{initial_value} step @var{increment}
262 unless @var{condition} do @var{body}}
263 @end itemize
265 @c UGH. DO WE REALLY NEED TO MENTION THIS??
266 (Alternatively, the @code{step} may be given after the termination condition
267 or limit.)
269 @var{initial_value}, @var{increment}, @var{limit}, and @var{body} can be any
270 expressions. If the increment is 1 then "@code{step 1}" may be omitted.
272 The execution of the @code{do} statement proceeds by first assigning
273 the @var{initial_value} to the @var{variable} (henceforth called the
274 control-variable). Then: (1) If the control-variable has exceeded the
275 limit of a @code{thru} specification, or if the condition of the
276 @code{unless} is @code{true}, or if the condition of the @code{while}
277 is @code{false} then the @code{do} terminates. (2) The @var{body} is
278 evaluated. (3) The increment is added to the control-variable. The
279 process from (1) to (3) is performed repeatedly until the termination
280 condition is satisfied. One may also give several termination
281 conditions in which case the @code{do} terminates when any of them is
282 satisfied.
284 In general the @code{thru} test is satisfied when the control-variable
285 is greater than the @var{limit} if the @var{increment} was
286 non-negative, or when the control-variable is less than the
287 @var{limit} if the @var{increment} was negative. The
288 @var{increment} and @var{limit} may be non-numeric expressions as
289 long as this inequality can be determined. However, unless the
290 @var{increment} is syntactically negative (e.g. is a negative number)
291 at the time the @code{do} statement is input, Maxima assumes it will
292 be positive when the @code{do} is executed. If it is not positive,
293 then the @code{do} may not terminate properly.
295 Note that the @var{limit}, @var{increment}, and termination condition are
296 evaluated each time through the loop. Thus if any of these involve
297 much computation, and yield a result that does not change during all
298 the executions of the @var{body}, then it is more efficient to set a
299 variable to their value prior to the @code{do} and use this variable in the
300 @code{do} form.
302 The value normally returned by a @code{do} statement is the atom
303 @code{done}. However, the function @code{return} may be used inside
304 the @var{body} to exit the @code{do} prematurely and give it any
305 desired value. Note however that a @code{return} within a @code{do}
306 that occurs in a @code{block} will exit only the @code{do} and not the
307 @code{block}. Note also that the @code{go} function may not be used
308 to exit from a @code{do} into a surrounding @code{block}.
310 The control-variable is always local to the @code{do} and thus any
311 variable may be used without affecting the value of a variable with
312 the same name outside of the @code{do}. The control-variable is unbound
313 after the @code{do} terminates.
315 @example
316 (%i1) for a:-3 thru 26 step 7 do display(a)$
317 a = - 3
319 a = 4
321 a = 11
323 a = 18
325 a = 25
326 @end example
328 @example
329 (%i1) s: 0$
330 (%i2) for i: 1 while i <= 10 do s: s+i;
331 (%o2) done
332 (%i3) s;
333 (%o3) 55
334 @end example
336 Note that the condition @code{while i <= 10}
337 is equivalent to @code{unless i > 10} and also @code{thru 10}.
339 @example
340 (%i1) series: 1$
341 (%i2) term: exp (sin (x))$
342 (%i3) for p: 1 unless p > 7 do
343 (term: diff (term, x)/p,
344 series: series + subst (x=0, term)*x^p)$
345 (%i4) series;
346 7 6 5 4 2
347 x x x x x
348 (%o4) -- - --- - -- - -- + -- + x + 1
349 90 240 15 8 2
350 @end example
352 which gives 8 terms of the Taylor series for @code{e^sin(x)}.
354 @example
355 (%i1) poly: 0$
356 (%i2) for i: 1 thru 5 do
357 for j: i step -1 thru 1 do
358 poly: poly + i*x^j$
359 (%i3) poly;
360 5 4 3 2
361 (%o3) 5 x + 9 x + 12 x + 14 x + 15 x
362 (%i4) guess: -3.0$
363 (%i5) for i: 1 thru 10 do
364 (guess: subst (guess, x, 0.5*(x + 10/x)),
365 if abs (guess^2 - 10) < 0.00005 then return (guess));
366 (%o5) - 3.162280701754386
367 @end example
369 This example computes the negative square root of 10 using the
370 Newton- Raphson iteration a maximum of 10 times. Had the convergence
371 criterion not been met the value returned would have been @code{done}.
373 Instead of always adding a quantity to the control-variable one
374 may sometimes wish to change it in some other way for each iteration.
375 In this case one may use @code{next @var{expression}} instead of
376 @code{step @var{increment}}. This will cause the control-variable to be set to
377 the result of evaluating @var{expression} each time through the loop.
379 @example
380 (%i6) for count: 2 next 3*count thru 20 do display (count)$
381 count = 2
383 count = 6
385 count = 18
386 @end example
388 @c UGH. DO WE REALLY NEED TO MENTION THIS??
389 As an alternative to @code{for @var{variable}: @var{value} ...do...}
390 the syntax @code{for @var{variable} from @var{value} ...do...} may be
391 used. This permits the @code{from @var{value}} to be placed after the
392 @code{step} or @code{next} value or after the termination condition.
393 If @code{from @var{value}} is omitted then 1 is used as the initial
394 value.
396 Sometimes one may be interested in performing an iteration where
397 the control-variable is never actually used. It is thus permissible
398 to give only the termination conditions omitting the initialization
399 and updating information as in the following example to compute the
400 square-root of 5 using a poor initial guess.
402 @example
403 (%i1) x: 1000$
404 (%i2) thru 20 do x: 0.5*(x + 5.0/x)$
405 (%i3) x;
406 (%o3) 2.23606797749979
407 (%i4) sqrt(5), numer;
408 (%o4) 2.23606797749979
409 @end example
411 If it is desired one may even omit the termination conditions entirely
412 and just give @code{do @var{body}} which will continue to evaluate the
413 @var{body} indefinitely. In this case the function @code{return}
414 should be used to terminate execution of the @code{do}.
416 @example
417 (%i1) newton (f, x):= ([y, df, dfx], df: diff (f ('x), 'x),
418 do (y: ev(df), x: x - f(x)/y,
419 if abs (f (x)) < 5e-6 then return (x)))$
420 (%i2) sqr (x) := x^2 - 5.0$
421 (%i3) newton (sqr, 1000);
422 (%o3) 2.236068027062195
423 @end example
425 @c DUNNO IF WE NEED THIS LEVEL OF DETAIL; THIS ARTICLE IS GETTING PRETTY LONG
426 (Note that @code{return}, when executed, causes the current value of @code{x} to
427 be returned as the value of the @code{do}. The @code{block} is exited and this
428 value of the @code{do} is returned as the value of the @code{block} because the
429 @code{do} is the last statement in the block.)
431 One other form of the @code{do} is available in Maxima. The syntax is:
433 @example
434 for @var{variable} in @var{list} @var{end_tests} do @var{body}
435 @end example
437 The elements of @var{list} are any expressions which will successively
438 be assigned to the @code{variable} on each iteration of the
439 @var{body}. The optional termination tests @var{end_tests} can be
440 used to terminate execution of the @code{do}; otherwise it will
441 terminate when the @var{list} is exhausted or when a @code{return} is
442 executed in the @var{body}. (In fact, @code{list} may be any
443 non-atomic expression, and successive parts are taken.)
445 @example
446 (%i1) for f in [log, rho, atan] do ldisp(f(1))$
447 (%t1) 0
448 (%t2) rho(1)
449 %pi
450 (%t3) ---
451 4
452 (%i4) ev(%t3,numer);
453 (%o4) 0.78539816
454 @end example
456 @opencatbox
457 @category{Programming}
458 @closecatbox
459 @end deffn
461 @c -----------------------------------------------------------------------------
462 @anchor{errcatch}
463 @deffn {Function} errcatch (@var{expr_1}, @dots{}, @var{expr_n})
465 Evaluates @var{expr_1}, @dots{}, @var{expr_n} one by one and
466 returns @code{[@var{expr_n}]} (a list) if no error occurs. If an
467 error occurs in the evaluation of any argument, @code{errcatch}
468 prevents the error from propagating and
469 returns the empty list @code{[]} without evaluating any more arguments.
471 @code{errcatch}
472 is useful in @code{batch} files where one suspects an error might occur which
473 would terminate the @code{batch} if the error weren't caught.
475 @opencatbox
476 @category{Programming}
477 @closecatbox
478 @end deffn
480 @c -----------------------------------------------------------------------------
481 @anchor{error}
482 @deffn {Function} error (@var{expr_1}, @dots{}, @var{expr_n})
483 @deffnx {System variable} error
485 Evaluates and prints @var{expr_1}, @dots{}, @var{expr_n},
486 and then causes an error return to top level Maxima
487 or to the nearest enclosing @code{errcatch}.
489 The variable @code{error} is set to a list describing the error.
490 The first element of @code{error} is a format string, which merges all the
491 strings among the arguments @var{expr_1}, @dots{}, @var{expr_n},
492 and the remaining elements are the values of any non-string arguments.
494 @code{errormsg()} formats and prints @code{error}.
495 This is effectively reprinting the most recent error message.
497 @opencatbox
498 @category{Programming}
499 @closecatbox
500 @end deffn
502 @c -----------------------------------------------------------------------------
503 @anchor{error_size}
504 @defvr {Option variable} error_size
505 Default value: 10
507 @code{error_size} modifies error messages according to the size of expressions
508 which appear in them. If the size of an expression (as determined by the Lisp
509 function @code{ERROR-SIZE}) is greater than @code{error_size}, the expression is
510 replaced in the message by a symbol, and the symbol is assigned the expression.
511 The symbols are taken from the list @code{error_syms}.
513 Otherwise, the expression is smaller than @code{error_size}, and the expression
514 is displayed in the message.
516 See also @code{error} and @code{error_syms}.
518 Example:
519 @c OUTPUT GENERATED BY THE FOLLOWING
520 @c U: (C^D^E + B + A)/(cos(X-1) + 1)$
521 @c error_size: 20$
522 @c error ("Example expression is", U);
523 @c errexp1;
524 @c error_size: 30$
525 @c error ("Example expression is", U);
527 The size of @code{U}, as determined by @code{ERROR-SIZE}, is 24.
529 @example
530 (%i1) U: (C^D^E + B + A)/(cos(X-1) + 1)$
532 (%i2) error_size: 20$
534 (%i3) error ("Example expression is", U);
536 Example expression is errexp1
537 -- an error. Quitting. To debug this try debugmode(true);
538 (%i4) errexp1;
539 E
540 D
541 C + B + A
542 (%o4) --------------
543 cos(X - 1) + 1
544 (%i5) error_size: 30$
546 (%i6) error ("Example expression is", U);
548 E
549 D
550 C + B + A
551 Example expression is --------------
552 cos(X - 1) + 1
553 -- an error. Quitting. To debug this try debugmode(true);
554 @end example
556 @opencatbox
557 @category{Debugging} @category{Display flags and variables}
558 @closecatbox
559 @end defvr
561 @c -----------------------------------------------------------------------------
562 @anchor{error_syms}
563 @defvr {Option variable} error_syms
564 Default value: @code{[errexp1, errexp2, errexp3]}
566 In error messages, expressions larger than @code{error_size} are replaced by
567 symbols, and the symbols are set to the expressions. The symbols are taken from
568 the list @code{error_syms}. The first too-large expression is replaced by
569 @code{error_syms[1]}, the second by @code{error_syms[2]}, and so on.
571 If there are more too-large expressions than there are elements of
572 @code{error_syms}, symbols are constructed automatically, with the @var{n}-th
573 symbol equivalent to @code{concat ('errexp, @var{n})}.
575 See also @code{error} and @code{error_size}.
577 @opencatbox
578 @category{Debugging} @category{Display flags and variables}
579 @closecatbox
580 @end defvr
582 @c -----------------------------------------------------------------------------
583 @anchor{errormsg}
584 @deffn {Function} errormsg ()
586 Reprints the most recent error message.
587 The variable @code{error} holds the message,
588 and @code{errormsg} formats and prints it.
590 @opencatbox
591 @category{Programming}
592 @closecatbox
593 @end deffn
595 @c -----------------------------------------------------------------------------
596 @anchor{option_errormsg}
597 @defvr {Option variable} errormsg
598 Default value: @code{true}
600 When @code{false} the output of error messages is suppressed.
602 The option variable @code{errormsg} can not be set in a block to a local
603 value. The global value of @code{errormsg} is always present.
605 @c ===beg===
606 @c errormsg;
607 @c sin(a,b);
608 @c errormsg:false;
609 @c sin(a,b);
610 @c ===end===
611 @example
612 (%i1) errormsg;
613 (%o1) true
614 (%i2) sin(a,b);
615 Wrong number of arguments to sin
616 -- an error. To debug this try: debugmode(true);
617 (%i3) errormsg:false;
618 (%o3) false
619 (%i4) sin(a,b);
621 -- an error. To debug this try: debugmode(true);
622 @end example
624 The option variable @code{errormsg} can not be set in a block to a local value.
626 @c ===beg===
627 @c f(bool):=block([errormsg:bool], print ("value of errormsg is",errormsg))$
628 @c errormsg:true;
629 @c f(false);
630 @c errormsg:false;
631 @c f(true);
632 @c ===end===
633 @example
634 (%i1) f(bool):=block([errormsg:bool],
635 print ("value of errormsg is",errormsg))$
636 (%i2) errormsg:true;
637 (%o2) true
638 (%i3) f(false);
639 value of errormsg is true
640 (%o3) true
641 (%i4) errormsg:false;
642 (%o4) false
643 (%i5) f(true);
644 value of errormsg is false
645 (%o5) false
646 @end example
648 @opencatbox
649 @category{Programming}
650 @closecatbox
651 @end defvr
653 @c REPHRASE
654 @c AT LEAST SHOULD LIST VARIANTS HERE
656 @c -----------------------------------------------------------------------------
657 @anchor{for}
658 @deffn {Special operator} for
660 Used in iterations. See @code{do} for a description of
661 Maxima's iteration facilities.
663 @opencatbox
664 @category{Programming}
665 @closecatbox
666 @end deffn
668 @c -----------------------------------------------------------------------------
669 @anchor{go}
670 @deffn {Function} go (@var{tag})
672 is used within a @code{block} to transfer control to the statement
673 of the block which is tagged with the argument to @code{go}. To tag a
674 statement, precede it by an atomic argument as another statement in
675 the @code{block}. For example:
677 @example
678 block ([x], x:1, loop, x+1, ..., go(loop), ...)
679 @end example
681 The argument to @code{go} must be the name of a tag appearing in the same
682 @code{block}. One cannot use @code{go} to transfer to tag in a @code{block}
683 other than the one containing the @code{go}.
685 @opencatbox
686 @category{Programming}
687 @closecatbox
688 @end deffn
690 @c NEEDS CLARIFICATION, EXPANSION, EXAMPLES
691 @c THIS ITEM IS IMPORTANT
693 @c -----------------------------------------------------------------------------
694 @anchor{if}
695 @deffn {Special operator} if
697 Represents conditional evaluation. Various forms of @code{if} expressions are
698 recognized.
700 @code{if @var{cond_1} then @var{expr_1} else @var{expr_0}}
701 eva@-lu@-ates to @var{expr_1} if @var{cond_1} evaluates to @code{true},
702 otherwise the expression evaluates to @var{expr_0}.
704 The command @code{if @var{cond_1} then @var{expr_1} elseif @var{cond_2} then
705 @var{expr_2} elseif ... else @var{expr_0}} evaluates to @var{expr_k} if
706 @var{cond_k} is @code{true} and all preceding conditions are @code{false}. If
707 none of the conditions are @code{true}, the expression evaluates to
708 @code{expr_0}.
710 A trailing @code{else false} is assumed if @code{else} is missing. That is,
711 the command @code{if @var{cond_1} then @var{expr_1}} is equivalent to
712 @code{if @var{cond_1} then @var{expr_1} else false}, and the command
713 @code{if @var{cond_1} then @var{expr_1} elseif ... elseif @var{cond_n} then
714 @var{expr_n}} is equivalent to @code{if @var{cond_1} then @var{expr_1} elseif
715 ... elseif @var{cond_n} then @var{expr_n} else false}.
717 The alternatives @var{expr_0}, @dots{}, @var{expr_n} may be any Maxima
718 expressions, including nested @code{if} expressions. The alternatives are
719 neither simplified nor evaluated unless the corresponding condition is
720 @code{true}.
722 The conditions @var{cond_1}, @dots{}, @var{cond_n} are expressions which
723 potentially or actually evaluate to @code{true} or @code{false}.
724 When a condition does not actually evaluate to @code{true} or @code{false},
725 the behavior of @code{if} is governed by the global flag @code{prederror}.
726 When @code{prederror} is @code{true}, it is an error if any evaluated condition
727 does not evaluate to @code{true} or @code{false}. Otherwise, conditions which
728 do not evaluate to @code{true} or @code{false} are accepted, and the result is
729 a conditional expression.
731 Among other elements, conditions may comprise relational and logical operators
732 as follows.
734 @c - SEEMS LIKE THIS TABLE WANTS TO BE IN A DISCUSSION OF PREDICATE FUNCTIONS; PRESENT LOCATION IS OK I GUESS
735 @c - REFORMAT THIS TABLE USING TEXINFO MARKUP (MAYBE)
736 @example
737 Operation Symbol Type
739 less than < relational infix
740 less than <=
741 or equal to relational infix
742 equality (syntactic) = relational infix
743 negation of = # relational infix
744 equality (value) equal relational function
745 negation of equal notequal relational function
746 greater than >=
747 or equal to relational infix
748 greater than > relational infix
749 and and logical infix
750 or or logical infix
751 not not logical prefix
752 @end example
754 @opencatbox
755 @category{Programming} @category{Predicate functions}
756 @closecatbox
757 @end deffn
759 @c NEEDS CLARIFICATION
760 @c THIS ITEM IS IMPORTANT
762 @c -----------------------------------------------------------------------------
763 @anchor{map}
764 @deffn {Function} map (@var{f}, @var{expr_1}, @dots{}, @var{expr_n})
766 Returns an expression whose leading operator is the same as that of the
767 expressions @var{expr_1}, @dots{}, @var{expr_n} but whose subparts are the
768 results of applying @var{f} to the corresponding subparts of the expressions.
769 @var{f} is either the name of a function of @math{n} arguments or is a
770 @code{lambda} form of @math{n} arguments.
772 @code{maperror} - if @code{false} will cause all of the mapping
773 functions to (1) stop when they finish going down the shortest
774 @var{expr_i} if not all of the @var{expr_i} are of the same length and
775 (2) apply @var{f} to [@var{expr_1}, @var{expr_2}, @dots{}] if the
776 @var{expr_i} are not all the same type of object. If @code{maperror}
777 is @code{true} then an error message will be given in the above two
778 instances.
780 One of the uses of this function is to @code{map} a function (e.g.
781 @code{partfrac}) onto each term of a very large expression where it ordinarily
782 wouldn't be possible to use the function on the entire expression due to an
783 exhaustion of list storage space in the course of the computation.
785 @c IN THESE EXAMPLES, SPELL OUT WHAT IS THE MAIN OPERATOR
786 @c AND SHOW HOW THE RESULT FOLLOWS FROM THE DESCRIPTION STATED IN THE FIRST PARAGRAPH
787 @example
788 (%i1) map(f,x+a*y+b*z);
789 (%o1) f(b z) + f(a y) + f(x)
790 (%i2) map(lambda([u],partfrac(u,x)),x+1/(x^3+4*x^2+5*x+2));
791 1 1 1
792 (%o2) ----- - ----- + -------- + x
793 x + 2 x + 1 2
794 (x + 1)
795 (%i3) map(ratsimp, x/(x^2+x)+(y^2+y)/y);
796 1
797 (%o3) y + ----- + 1
798 x + 1
799 (%i4) map("=",[a,b],[-0.5,3]);
800 (%o4) [a = - 0.5, b = 3]
803 @end example
805 @opencatbox
806 @category{Function application}
807 @closecatbox
808 @end deffn
810 @c -----------------------------------------------------------------------------
811 @anchor{mapatom}
812 @deffn {Function} mapatom (@var{expr})
814 Returns @code{true} if and only if @var{expr} is treated by the mapping
815 routines as an atom. "Mapatoms" are atoms, numbers
816 (including rational numbers), and subscripted variables.
817 @c WHAT ARE "THE MAPPING ROUTINES", AND WHY DO THEY HAVE A SPECIALIZED NOTION OF ATOMS ??
819 @opencatbox
820 @category{Predicate functions}
821 @closecatbox
822 @end deffn
824 @c NEEDS CLARIFICATION
826 @c -----------------------------------------------------------------------------
827 @anchor{maperror}
828 @defvr {Option variable} maperror
829 Default value: @code{true}
831 When @code{maperror} is @code{false}, causes all of the mapping functions,
832 for example
834 @example
835 map (@var{f}, @var{expr_1}, @var{expr_2}, ...)
836 @end example
838 to (1) stop when they finish going down the shortest @var{expr_i} if
839 not all of the @var{expr_i} are of the same length and (2) apply
840 @var{f} to [@var{expr_1}, @var{expr_2}, @dots{}] if the @var{expr_i} are
841 not all the same type of object.
843 If @code{maperror} is @code{true} then an error message
844 is displayed in the above two instances.
846 @opencatbox
847 @category{Function application}
848 @closecatbox
849 @end defvr
851 @c -----------------------------------------------------------------------------
852 @anchor{mapprint}
853 @defvr {Option variable} mapprint
854 Default value: @code{true}
856 When @code{mapprint} is @code{true}, various information messages from
857 @code{map}, @code{mapl}, and @code{fullmap} are produced in certain
858 situations. These include situations where @code{map} would use
859 @code{apply}, or @code{map} is truncating on the shortest list.
861 If @code{mapprint} is @code{false}, these messages are suppressed.
863 @opencatbox
864 @category{Function application}
865 @closecatbox
866 @end defvr
868 @c NEEDS CLARIFICATION
870 @c -----------------------------------------------------------------------------
871 @anchor{maplist}
872 @deffn {Function} maplist (@var{f}, @var{expr_1}, @dots{}, @var{expr_n})
874 Returns a list of the applications of @var{f} to the parts of the expressions
875 @var{expr_1}, @dots{}, @var{expr_n}. @var{f} is the name of a function, or a
876 lambda expression.
878 @code{maplist} differs from @code{map(@var{f}, @var{expr_1}, ..., @var{expr_n})}
879 which returns an expression with the same main operator as @var{expr_i} has
880 (except for simplifications and the case where @code{map} does an @code{apply}).
882 @opencatbox
883 @category{Function application}
884 @closecatbox
885 @end deffn
887 @c NEEDS CLARIFICATION
889 @c -----------------------------------------------------------------------------
890 @anchor{prederror}
891 @defvr {Option variable} prederror
892 Default value: @code{false}
894 When @code{prederror} is @code{true}, an error message is displayed whenever the
895 predicate of an @code{if} statement or an @code{is} function fails to evaluate
896 to either @code{true} or @code{false}.
898 If @code{false}, @code{unknown} is returned
899 instead in this case. The @code{prederror: false} mode is not supported in
900 translated code;
901 however, @code{maybe} is supported in translated code.
903 See also @code{is} and @code{maybe}.
905 @opencatbox
906 @category{Programming} @category{Predicate functions}
907 @closecatbox
909 @end defvr
911 @deffn {Function} return (@var{value})
912 May be used to exit explicitly from a block, bringing
913 its argument. See @code{block} for more information.
915 @opencatbox
916 @category{Programming}
917 @closecatbox
918 @end deffn
920 @c NEEDS CLARIFICATION
921 @deffn {Function} scanmap @
922 @fname{scanmap} (@var{f}, @var{expr}) @
923 @fname{scanmap} (@var{f}, @var{expr}, bottomup)
925 Recursively applies @var{f} to @var{expr}, in a top
926 down manner. This is most useful when complete factorization is
927 desired, for example:
929 @example
930 (%i1) exp:(a^2+2*a+1)*y + x^2$
931 (%i2) scanmap(factor,exp);
932 2 2
933 (%o2) (a + 1) y + x
934 @end example
936 Note the way in which @code{scanmap} applies the given function
937 @code{factor} to the constituent subexpressions of @var{expr}; if
938 another form of @var{expr} is presented to @code{scanmap} then the
939 result may be different. Thus, @code{%o2} is not recovered when
940 @code{scanmap} is applied to the expanded form of @code{exp}:
942 @example
943 (%i3) scanmap(factor,expand(exp));
944 2 2
945 (%o3) a y + 2 a y + y + x
946 @end example
948 Here is another example of the way in which @code{scanmap} recursively
949 applies a given function to all subexpressions, including exponents:
951 @example
952 (%i4) expr : u*v^(a*x+b) + c$
953 (%i5) scanmap('f, expr);
954 f(f(f(a) f(x)) + f(b))
955 (%o5) f(f(f(u) f(f(v) )) + f(c))
956 @end example
958 @code{scanmap (@var{f}, @var{expr}, bottomup)} applies @var{f} to @var{expr} in a
959 bottom-up manner. E.g., for undefined @code{f},
961 @example
962 scanmap(f,a*x+b) ->
963 f(a*x+b) -> f(f(a*x)+f(b)) -> f(f(f(a)*f(x))+f(b))
964 scanmap(f,a*x+b,bottomup) -> f(a)*f(x)+f(b)
965 -> f(f(a)*f(x))+f(b) ->
966 f(f(f(a)*f(x))+f(b))
967 @end example
969 In this case, you get the same answer both
970 ways.
972 @opencatbox
973 @category{Function application}
974 @closecatbox
975 @end deffn
977 @c -----------------------------------------------------------------------------
978 @anchor{throw}
979 @deffn {Function} throw (@var{expr})
981 Evaluates @var{expr} and throws the value back to the most recent
982 @code{catch}. @code{throw} is used with @code{catch} as a nonlocal return
983 mechanism.
985 @opencatbox
986 @category{Programming}
987 @closecatbox
988 @end deffn
990 @c NEED MORE HERE !!
991 @c AT LEAST SHOULD LIST ACCEPTABLE VARIANTS
993 @c -----------------------------------------------------------------------------
994 @anchor{while}
995 @anchor{unless}
996 @deffn {Special operator} while
997 @deffnx {Special operator} unless
998 See @code{do}.
1000 @opencatbox
1001 @category{Programming}
1002 @closecatbox
1003 @end deffn
1005 @c -----------------------------------------------------------------------------
1006 @anchor{outermap}
1007 @deffn {Function} outermap (@var{f}, @var{a_1}, @dots{}, @var{a_n})
1009 Applies the function @var{f} to each one of the elements of the outer product
1010 @var{a_1} cross @var{a_2} @dots{} cross @var{a_n}.
1012 @var{f} is the name of a function of @math{n} arguments or a lambda expression
1013 of @math{n} arguments. Each argument @var{a_k} may be a list or nested list,
1014 or a matrix, or any other kind of expression.
1016 The @code{outermap} return value is a nested structure. Let @var{x} be the
1017 return value. Then @var{x} has the same structure as the first list, nested
1018 list, or matrix argument, @code{@var{x}[i_1]...[i_m]} has the same structure as
1019 the second list, nested list, or matrix argument,
1020 @code{@var{x}[i_1]...[i_m][j_1]...[j_n]} has the same structure as the third
1021 list, nested list, or matrix argument, and so on, where @var{m}, @var{n},
1022 @dots{} are the numbers of indices required to access the elements of each
1023 argument (one for a list, two for a matrix, one or more for a nested list).
1024 Arguments which are not lists or matrices have no effect on the structure of
1025 the return value.
1027 Note that the effect of @code{outermap} is different from that of applying
1028 @var{f} to each one of the elements of the outer product returned by
1029 @code{cartesian_product}. @code{outermap} preserves the structure of the
1030 arguments in the return value, while @code{cartesian_product} does not.
1032 @code{outermap} evaluates its arguments.
1034 See also @code{map}, @code{maplist}, and @code{apply}.
1035 @c CROSS REF OTHER FUNCTIONS HERE ??
1037 Examples:
1039 Elementary examples of @code{outermap}.
1040 To show the argument combinations more clearly, @code{F} is left undefined.
1042 @c ===beg===
1043 @c outermap (F, [a, b, c], [1, 2, 3]);
1044 @c outermap (F, matrix ([a, b], [c, d]), matrix ([1, 2], [3, 4]));
1045 @c outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
1046 @c outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
1047 @c outermap ("+", [a, b, c], [1, 2, 3]);
1048 @c ===end===
1049 @example
1050 (%i1) outermap(F, [a, b, c], [1, 2, 3]);
1051 (%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)],
1052 [F(c, 1), F(c, 2), F(c, 3)]]
1053 (%i2) outermap(F, matrix([a, b],[c, d]), matrix([1, 2],[3, 4]));
1054 [ [ F(a, 1) F(a, 2) ] [ F(b, 1) F(b, 2) ] ]
1055 [ [ ] [ ] ]
1056 [ [ F(a, 3) F(a, 4) ] [ F(b, 3) F(b, 4) ] ]
1057 (%o2) [ ]
1058 [ [ F(c, 1) F(c, 2) ] [ F(d, 1) F(d, 2) ] ]
1059 [ [ ] [ ] ]
1060 [ [ F(c, 3) F(c, 4) ] [ F(d, 3) F(d, 4) ] ]
1061 (%i3) outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
1062 [ F(a, x, 1) F(a, x, 2) ] [ F(b, x, 1) F(b, x, 2) ]
1063 (%o3) [[ ], [ ]]
1064 [ F(a, x, 3) F(a, x, 4) ] [ F(b, x, 3) F(b, x, 4) ]
1065 (%i4) outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
1066 [ [ F(a, 1, x) ] [ F(a, 2, x) ] ]
1067 (%o4) [[ [ ] [ ] ],
1068 [ [ F(a, 1, y) ] [ F(a, 2, y) ] ]
1069 [ [ F(b, 1, x) ] [ F(b, 2, x) ] ]
1070 [ [ ] [ ] ]]
1071 [ [ F(b, 1, y) ] [ F(b, 2, y) ] ]
1072 (%i5) outermap ("+", [a, b, c], [1, 2, 3]);
1073 (%o5) [[a + 1, a + 2, a + 3], [b + 1, b + 2, b + 3],
1074 [c + 1, c + 2, c + 3]]
1075 @end example
1077 A closer examination of the @code{outermap} return value. The first, second,
1078 and third arguments are a matrix, a list, and a matrix, respectively.
1079 The return value is a matrix.
1080 Each element of that matrix is a list,
1081 and each element of each list is a matrix.
1083 @c ===beg===
1084 @c arg_1 : matrix ([a, b], [c, d]);
1085 @c arg_2 : [11, 22];
1086 @c arg_3 : matrix ([xx, yy]);
1087 @c xx_0 : outermap (lambda ([x, y, z], x / y + z), arg_1,
1088 @c arg_2, arg_3);
1089 @c xx_1 : xx_0 [1][1];
1090 @c xx_2 : xx_0 [1][1] [1];
1091 @c xx_3 : xx_0 [1][1] [1] [1][1];
1092 @c [op (arg_1), op (arg_2), op (arg_3)];
1093 @c [op (xx_0), op (xx_1), op (xx_2)];
1094 @c ===end===
1095 @example
1096 (%i1) arg_1 : matrix ([a, b], [c, d]);
1097 [ a b ]
1098 (%o1) [ ]
1099 [ c d ]
1100 (%i2) arg_2 : [11, 22];
1101 (%o2) [11, 22]
1102 (%i3) arg_3 : matrix ([xx, yy]);
1103 (%o3) [ xx yy ]
1104 (%i4) xx_0 : outermap(lambda([x, y, z], x / y + z), arg_1,
1105 arg_2, arg_3);
1106 [ [ a a ] [ a a ] ]
1107 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1108 [ [ 11 11 ] [ 22 22 ] ]
1109 (%o4) Col 1 = [ ]
1110 [ [ c c ] [ c c ] ]
1111 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1112 [ [ 11 11 ] [ 22 22 ] ]
1113 @group
1114 [ [ b b ] [ b b ] ]
1115 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1116 [ [ 11 11 ] [ 22 22 ] ]
1117 Col 2 = [ ]
1118 [ [ d d ] [ d d ] ]
1119 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1120 [ [ 11 11 ] [ 22 22 ] ]
1121 @end group
1122 (%i5) xx_1 : xx_0 [1][1];
1123 [ a a ] [ a a ]
1124 (%o5) [[ xx + -- yy + -- ], [ xx + -- yy + -- ]]
1125 [ 11 11 ] [ 22 22 ]
1126 (%i6) xx_2 : xx_0 [1][1] [1];
1127 [ a a ]
1128 (%o6) [ xx + -- yy + -- ]
1129 [ 11 11 ]
1130 (%i7) xx_3 : xx_0 [1][1] [1] [1][1];
1131 a
1132 (%o7) xx + --
1133 11
1134 (%i8) [op (arg_1), op (arg_2), op (arg_3)];
1135 (%o8) [matrix, [, matrix]
1136 (%i9) [op (xx_0), op (xx_1), op (xx_2)];
1137 (%o9) [matrix, [, matrix]
1138 @end example
1140 @code{outermap} preserves the structure of the arguments in the return value,
1141 while @code{cartesian_product} does not.
1143 @c ===beg===
1144 @c outermap (F, [a, b, c], [1, 2, 3]);
1145 @c setify (flatten (%));
1146 @c map (lambda ([L], apply (F, L)),
1147 @c cartesian_product ({a, b, c}, {1, 2, 3}));
1148 @c is (equal (%, %th (2)));
1149 @c ===end===
1150 @example
1151 (%i1) outermap (F, [a, b, c], [1, 2, 3]);
1152 (%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)],
1153 [F(c, 1), F(c, 2), F(c, 3)]]
1154 (%i2) setify (flatten (%));
1155 (%o2) @{F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3),
1156 F(c, 1), F(c, 2), F(c, 3)@}
1157 (%i3) map(lambda([L], apply(F, L)),
1158 cartesian_product(@{a, b, c@}, @{1, 2, 3@}));
1159 (%o3) @{F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3),
1160 F(c, 1), F(c, 2), F(c, 3)@}
1161 (%i4) is (equal (%, %th (2)));
1162 (%o4) true
1163 @end example
1165 @opencatbox
1166 @category{Function application}
1167 @closecatbox
1168 @end deffn