| blob | 4ef6a2f9ab2ec7ab2af43982740855cd01553627 |
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 a fairly complete programming language. But since it is written in
14 Lisp, it additionally can provide easy access to Lisp functions and variables
15 from Maxima and vice versa. Lisp and Maxima symbols are distinguished by a
16 naming convention. A Lisp symbol which begins with a dollar sign @code{$}
17 corresponds to a Maxima symbol without the dollar sign.
19 @c NEED TO MENTION THIS OR IS IT JUST CLUTTERING ??
20 @c This includes special Maxima variables such as @code{%} and input and output
21 @c labels, which appear as @code{$%}, @code{$%i1}, @code{$%o1}, etc., in Lisp.
23 A Maxima symbol which begins with a question mark @code{?} corresponds to a Lisp
24 symbol without the question mark. For example, the Maxima symbol @code{foo}
25 corresponds to the Lisp symbol @code{$FOO}, while the Maxima symbol @code{?foo}
26 corresponds to the Lisp symbol @code{FOO}. Note that @code{?foo} is written
27 without a space between @code{?} and @code{foo}; otherwise it might be mistaken
28 for @code{describe ("foo")}.
30 Hyphen @code{-}, asterisk @code{*}, or other special characters in Lisp symbols
31 must be escaped by backslash @code{\} where they appear in Maxima code. For
32 example, the Lisp identifier @code{*foo-bar*} is written @code{?\*foo\-bar\*}
33 in Maxima.
35 Lisp code may be executed from within a Maxima session. A single line of Lisp
36 (containing one or more forms) may be executed by the special command
37 @code{:lisp}. For example,
39 @example
40 (%i1) :lisp (foo $x $y)
41 @end example
43 @noindent
44 calls the Lisp function @code{foo} with Maxima variables @code{x} and @code{y}
45 as arguments. The @code{:lisp} construct can appear at the interactive prompt
46 or in a file processed by @mref{batch} or @mrefcomma{demo} but not in a file
47 processed by @mrefcomma{load} @mrefcomma{batchload}@w{}
48 @mrefcomma{translate_file} or @mrefdot{compile_file}
50 The function @mref{to_lisp} opens an interactive Lisp session.
51 Entering @code{(to-maxima)} closes the Lisp session and returns to Maxima.
52 @c I DON'T EVEN WANT TO MENTION USING CTRL-C TO OPEN A LISP SESSION.
53 @c (1) IT TAKES EXTRA SET UP TO GET STARTED NAMELY :lisp (setq *debugger-hook* nil)
54 @c (2) IT GETS SCREWED UP EASILY -- TYPE SOMETHING WRONG AND YOU CAN'T GET BACK TO MAXIMA
55 @c (3) IT DOESN'T OFFER FUNCTIONALITY NOT PRESENT IN THE to_lisp() SESSION
57 Lisp functions and variables which are to be visible in Maxima as functions and
58 variables with ordinary names (no special punctuation) must have Lisp names
59 beginning with the dollar sign @code{$}.
61 Maxima is case-sensitive, distinguishing between lowercase and uppercase letters
62 in identifiers. There are some rules governing the translation of names between
63 Lisp and Maxima.
65 @enumerate
66 @item
67 A Lisp identifier not enclosed in vertical bars corresponds to a Maxima
68 identifier in lowercase. Whether the Lisp identifier is uppercase, lowercase,
69 or mixed case, is ignored. E.g., Lisp @code{$foo}, @code{$FOO}, and @code{$Foo}
70 all correspond to Maxima @code{foo}. But this is because @code{$foo},
71 @code{$FOO} and @code{$Foo} are converted by the Lisp reader by default to the
72 Lisp symbol @code{$FOO}.
73 @item
74 A Lisp identifier which is all uppercase or all lowercase and enclosed in
75 vertical bars corresponds to a Maxima identifier with case reversed. That is,
76 uppercase is changed to lowercase and lowercase to uppercase. E.g., Lisp
77 @code{|$FOO|} and @code{|$foo|} correspond to Maxima @code{foo} and @code{FOO},
78 respectively.
79 @item
80 A Lisp identifier which is mixed uppercase and lowercase and enclosed in
81 vertical bars corresponds to a Maxima identifier with the same case. E.g.,
82 Lisp @code{|$Foo|} corresponds to Maxima @code{Foo}.
83 @end enumerate
85 The @code{#$} Lisp macro allows the use of Maxima expressions in Lisp code.
86 @code{#$@var{expr}$} expands to a Lisp expression equivalent to the Maxima
87 expression @var{expr}.
89 @example
90 (msetq $foo #$[x, y]$)
91 @end example
93 @noindent
94 This has the same effect as entering
96 @example
97 (%i1) foo: [x, y];
98 @end example
100 @noindent
101 The Lisp function @code{displa} prints an expression in Maxima format.
103 @example
104 (%i1) :lisp #$[x, y, z]$
105 ((MLIST SIMP) $X $Y $Z)
106 (%i1) :lisp (displa '((MLIST SIMP) $X $Y $Z))
107 [x, y, z]
108 NIL
109 @end example
111 Functions defined in Maxima are not ordinary Lisp functions. The Lisp function
112 @code{mfuncall} calls a Maxima function. For example:
114 @example
115 (%i1) foo(x,y) := x*y$
116 (%i2) :lisp (mfuncall '$foo 'a 'b)
117 ((MTIMES SIMP) A B)
118 @end example
120 Some Lisp functions are shadowed in the Maxima package, namely the following.
122 @verbatim
123 complement continue //
124 float functionp array
125 exp listen signum
126 atan asin acos
127 asinh acosh atanh
128 tanh cosh sinh
129 tan break gcd
130 @end verbatim
132 @opencatbox{Categories:}
133 @category{Programming}
134 @closecatbox
136 @c -----------------------------------------------------------------------------
137 @node Garbage Collection, Introduction to Program Flow, Lisp and Maxima, Program Flow
138 @section Garbage Collection
139 @c -----------------------------------------------------------------------------
141 One of the advantages of using lisp is that it uses ``Garbage Collection''. In other
142 words it automatically takes care of freeing memory occupied for example of
143 intermediate results that were used during symbolic computation.
145 Garbage Collection avoids many errors frequently found in C programs (memory
146 being freed too early, multiple times or not at all).
148 @c -----------------------------------------------------------------------------
150 @anchor{garbage_collect}
151 @deffn {Function} garbage_collect ()
153 Tries to manually trigger the lisp's garbage collection. This rarely is necessary
154 as the lisp will employ an excellent algorithm for determining when to start
155 garbage collection.
157 If maxima knows how to do manually trigger the garbage collection for the
158 current lisp @code{garbage_collect} returns @code{true}, else @code{false}.
160 @opencatbox{Categories:}
161 @category{Programming}
162 @closecatbox
163 @end deffn
165 @c -----------------------------------------------------------------------------
166 @node Introduction to Program Flow, Functions and Variables for Program Flow, Garbage Collection, Program Flow
167 @section Introduction to Program Flow
168 @c -----------------------------------------------------------------------------
170 Maxima provides a @code{do} loop for iteration, as well as more primitive
171 constructs such as @code{go}.
173 @c end concepts Program Flow
175 @c -----------------------------------------------------------------------------
176 @node Functions and Variables for Program Flow, , Introduction to Program Flow, Program Flow
177 @section Functions and Variables for Program Flow
178 @c -----------------------------------------------------------------------------
180 @c -----------------------------------------------------------------------------
181 @anchor{backtrace}
182 @deffn {Function} backtrace @
183 @fname{backtrace} () @
184 @fname{backtrace} (@var{n})
186 Prints the call stack, that is, the list of functions which
187 called the currently active function.
189 @code{backtrace ()} prints the entire call stack.
191 @code{backtrace (@var{n})} prints the @var{n} most recent
192 functions, including the currently active function.
194 @c IS THIS STATEMENT REALLY NEEDED ??
195 @c (WHY WOULD ANYONE BELIEVE backtrace CANNOT BE CALLED OUTSIDE A DEBUGGING CONTEXT??)
196 @code{backtrace} can be called from a script, a function, or the interactive
197 prompt (not only in a debugging context).
199 Examples:
201 @itemize @bullet
202 @item
203 @code{backtrace ()} prints the entire call stack.
205 @example
206 (%i1) h(x) := g(x/7)$
207 (%i2) g(x) := f(x-11)$
208 (%i3) f(x) := e(x^2)$
209 (%i4) e(x) := (backtrace(), 2*x + 13)$
210 (%i5) h(10);
211 #0: e(x=4489/49)
212 #1: f(x=-67/7)
213 #2: g(x=10/7)
214 #3: h(x=10)
215 9615
216 (%o5) ----
217 49
218 @end example
219 @end itemize
221 @itemize @bullet
222 @item
223 @code{backtrace (@var{n})} prints the @var{n} most recent
224 functions, including the currently active function.
226 @example
227 (%i1) h(x) := (backtrace(1), g(x/7))$
228 (%i2) g(x) := (backtrace(1), f(x-11))$
229 (%i3) f(x) := (backtrace(1), e(x^2))$
230 (%i4) e(x) := (backtrace(1), 2*x + 13)$
231 (%i5) h(10);
232 #0: h(x=10)
233 #0: g(x=10/7)
234 #0: f(x=-67/7)
235 #0: e(x=4489/49)
236 9615
237 (%o5) ----
238 49
239 @end example
240 @end itemize
242 @opencatbox{Categories:}
243 @category{Debugging}
244 @closecatbox
245 @end deffn
247 @c -----------------------------------------------------------------------------
248 @anchor{do}
249 @anchor{while}
250 @anchor{unless}
251 @anchor{for}
252 @anchor{from}
253 @anchor{thru}
254 @anchor{step}
255 @anchor{next}
256 @anchor{in}
257 @deffn {Special operator} do
258 @deffnx {Special operator} while
259 @deffnx {Special operator} unless
260 @deffnx {Special operator} for
261 @deffnx {Special operator} from
262 @deffnx {Special operator} thru
263 @deffnx {Special operator} step
264 @deffnx {Special operator} next
265 @deffnx {Special operator} in
267 The @code{do} statement is used for performing iteration. The general
268 form of the @code{do} statements maxima supports is:
270 @itemize @bullet
271 @item
272 @code{for @var{variable}: @var{initial_value} step @var{increment}
273 thru @var{limit} do @var{body}}
274 @item
275 @code{for @var{variable}: @var{initial_value} step @var{increment}
276 while @var{condition} do @var{body}}
277 @item
278 @code{for @var{variable}: @var{initial_value} step @var{increment}
279 unless @var{condition} do @var{body}}
280 @item
281 @code{for @var{variable} in @var{list} do @var{body}}
282 @end itemize
284 If the loop is expected to generate a list as output the command
285 @mref{makelist} may be the appropriate command to use instead,
286 @xref{Performance considerations for Lists}.
288 @var{initial_value}, @var{increment}, @var{limit}, and @var{body} can be any
289 expression. @var{list} is a list. If the increment is 1 then "@code{step 1}"
290 may be omitted; As always, if @code{body} needs to contain more than one command
291 these commands can be specified as a comma-separated list surrounded
292 by parenthesis or as a @mrefdot{block}
293 Due to its great generality the @code{do} statement will be described in two parts.
294 The first form of the @code{do} statement (which is shown in the first three
295 items above) is analogous to that used in
296 several other programming languages (Fortran, Algol, PL/I, etc.); then
297 the other features will be mentioned.
299 The execution of the @code{do} statement proceeds by first assigning
300 the @var{initial_value} to the @var{variable} (henceforth called the
301 control-variable). Then: (1) If the control-variable has exceeded the
302 limit of a @code{thru} specification, or if the condition of the
303 @code{unless} is @code{true}, or if the condition of the @code{while}
304 is @code{false} then the @code{do} terminates. (2) The @var{body} is
305 evaluated. (3) The increment is added to the control-variable. The
306 process from (1) to (3) is performed repeatedly until the termination
307 condition is satisfied. One may also give several termination
308 conditions in which case the @code{do} terminates when any of them is
309 satisfied.
311 In general the @code{thru} test is satisfied when the control-variable
312 is greater than the @var{limit} if the @var{increment} was
313 non-negative, or when the control-variable is less than the
314 @var{limit} if the @var{increment} was negative. The
315 @var{increment} and @var{limit} may be non-numeric expressions as
316 long as this inequality can be determined. However, unless the
317 @var{increment} is syntactically negative (e.g. is a negative number)
318 at the time the @code{do} statement is input, Maxima assumes it will
319 be positive when the @code{do} is executed. If it is not positive,
320 then the @code{do} may not terminate properly.
322 Note that the @var{limit}, @var{increment}, and termination condition are
323 evaluated each time through the loop. Thus if any of these involve
324 much computation, and yield a result that does not change during all
325 the executions of the @var{body}, then it is more efficient to set a
326 variable to their value prior to the @code{do} and use this variable in the
327 @code{do} form.
329 The value normally returned by a @code{do} statement is the atom
330 @code{done}. However, the function @code{return} may be used inside
331 the @var{body} to exit the @code{do} prematurely and give it any
332 desired value. Note however that a @code{return} within a @code{do}
333 that occurs in a @code{block} will exit only the @code{do} and not the
334 @code{block}. Note also that the @code{go} function may not be used
335 to exit from a @code{do} into a surrounding @code{block}.
337 The control-variable is always local to the @code{do} and thus any
338 variable may be used without affecting the value of a variable with
339 the same name outside of the @code{do}. The control-variable is unbound
340 after the @code{do} terminates.
342 @example
343 (%i1) for a:-3 thru 26 step 7 do display(a)$
344 a = - 3
346 a = 4
348 a = 11
350 a = 18
352 a = 25
353 @end example
355 @c ===beg===
356 @c s: 0$
357 @c for i: 1 while i <= 10 do s: s+i;
358 @c s;
359 @c ===end===
360 @example
361 (%i1) s: 0$
362 (%i2) for i: 1 while i <= 10 do s: s+i;
363 (%o2) done
364 (%i3) s;
365 (%o3) 55
366 @end example
368 Note that the condition @code{while i <= 10}
369 is equivalent to @code{unless i > 10} and also @code{thru 10}.
371 @c ===beg===
372 @c series: 1$
373 @c term: exp (sin (x))$
374 @c for p: 1 unless p > 7 do
375 @c (term: diff (term, x)/p,
376 @c series: series + subst (x=0, term)*x^p)$
377 @c series;
378 @c ===end===
379 @example
380 (%i1) series: 1$
381 (%i2) term: exp (sin (x))$
382 (%i3) for p: 1 unless p > 7 do
383 (term: diff (term, x)/p,
384 series: series + subst (x=0, term)*x^p)$
385 (%i4) series;
386 7 6 5 4 2
387 x x x x x
388 (%o4) -- - --- - -- - -- + -- + x + 1
389 90 240 15 8 2
390 @end example
392 which gives 8 terms of the Taylor series for @code{e^sin(x)}.
394 @c ===beg===
395 @c poly: 0$
396 @c for i: 1 thru 5 do
397 @c for j: i step -1 thru 1 do
398 @c poly: poly + i*x^j$
399 @c poly;
400 @c guess: -3.0$
401 @c for i: 1 thru 10 do
402 @c (guess: subst (guess, x, 0.5*(x + 10/x)),
403 @c if abs (guess^2 - 10) < 0.00005 then return (guess));
404 @c ===end===
405 @example
406 (%i1) poly: 0$
407 (%i2) for i: 1 thru 5 do
408 for j: i step -1 thru 1 do
409 poly: poly + i*x^j$
410 (%i3) poly;
411 5 4 3 2
412 (%o3) 5 x + 9 x + 12 x + 14 x + 15 x
413 (%i4) guess: -3.0$
414 (%i5) for i: 1 thru 10 do
415 (guess: subst (guess, x, 0.5*(x + 10/x)),
416 if abs (guess^2 - 10) < 0.00005 then return (guess));
417 (%o5) - 3.162280701754386
418 @end example
420 This example computes the negative square root of 10 using the
421 Newton- Raphson iteration a maximum of 10 times. Had the convergence
422 criterion not been met the value returned would have been @code{done}.
424 Instead of always adding a quantity to the control-variable one
425 may sometimes wish to change it in some other way for each iteration.
426 In this case one may use @code{next @var{expression}} instead of
427 @code{step @var{increment}}. This will cause the control-variable to be set to
428 the result of evaluating @var{expression} each time through the loop.
430 @example
431 (%i6) for count: 2 next 3*count thru 20 do display (count)$
432 count = 2
434 count = 6
436 count = 18
437 @end example
439 @c UGH. DO WE REALLY NEED TO MENTION THIS??
440 As an alternative to @code{for @var{variable}: @var{value} ...do...}
441 the syntax @code{for @var{variable} from @var{value} ...do...} may be
442 used. This permits the @code{from @var{value}} to be placed after the
443 @code{step} or @code{next} value or after the termination condition.
444 If @code{from @var{value}} is omitted then 1 is used as the initial
445 value.
447 Sometimes one may be interested in performing an iteration where
448 the control-variable is never actually used. It is thus permissible
449 to give only the termination conditions omitting the initialization
450 and updating information as in the following example to compute the
451 square-root of 5 using a poor initial guess.
453 @c ===beg===
454 @c x: 1000$
455 @c thru 20 do x: 0.5*(x + 5.0/x)$
456 @c x;
457 @c sqrt(5), numer;
458 @c ===end===
459 @example
460 (%i1) x: 1000$
461 (%i2) thru 20 do x: 0.5*(x + 5.0/x)$
462 (%i3) x;
463 (%o3) 2.23606797749979
464 (%i4) sqrt(5), numer;
465 (%o4) 2.23606797749979
466 @end example
468 If it is desired one may even omit the termination conditions entirely
469 and just give @code{do @var{body}} which will continue to evaluate the
470 @var{body} indefinitely. In this case the function @code{return}
471 should be used to terminate execution of the @code{do}.
473 @c ===beg===
474 @c newton (f, x):= ([y, df, dfx], df: diff (f ('x), 'x),
475 @c do (y: ev(df), x: x - f(x)/y,
476 @c if abs (f (x)) < 5e-6 then return (x)))$
477 @c sqr (x) := x^2 - 5.0$
478 @c newton (sqr, 1000);
479 @c ===end===
480 @example
481 (%i1) newton (f, x):= ([y, df, dfx], df: diff (f ('x), 'x),
482 do (y: ev(df), x: x - f(x)/y,
483 if abs (f (x)) < 5e-6 then return (x)))$
484 (%i2) sqr (x) := x^2 - 5.0$
485 (%i3) newton (sqr, 1000);
486 (%o3) 2.236068027062195
487 @end example
489 @c DUNNO IF WE NEED THIS LEVEL OF DETAIL; THIS ARTICLE IS GETTING PRETTY LONG
490 (Note that @code{return}, when executed, causes the current value of @code{x} to
491 be returned as the value of the @code{do}. The @code{block} is exited and this
492 value of the @code{do} is returned as the value of the @code{block} because the
493 @code{do} is the last statement in the block.)
495 One other form of the @code{do} is available in Maxima. The syntax is:
497 @example
498 for @var{variable} in @var{list} @var{end_tests} do @var{body}
499 @end example
501 The elements of @var{list} are any expressions which will successively
502 be assigned to the @code{variable} on each iteration of the
503 @var{body}. The optional termination tests @var{end_tests} can be
504 used to terminate execution of the @code{do}; otherwise it will
505 terminate when the @var{list} is exhausted or when a @code{return} is
506 executed in the @var{body}. (In fact, @code{list} may be any
507 non-atomic expression, and successive parts are taken.)
509 @example
510 (%i1) for f in [log, rho, atan] do ldisp(f(1))$
511 (%t1) 0
512 (%t2) rho(1)
513 %pi
514 (%t3) ---
515 4
516 (%i4) ev(%t3,numer);
517 (%o4) 0.78539816
518 @end example
520 @opencatbox{Categories:}
521 @category{Programming}
522 @closecatbox
523 @end deffn
525 @c -----------------------------------------------------------------------------
526 @anchor{errcatch}
527 @deffn {Function} errcatch (@var{expr_1}, @dots{}, @var{expr_n})
529 Evaluates @var{expr_1}, @dots{}, @var{expr_n} one by one and
530 returns @code{[@var{expr_n}]} (a list) if no error occurs. If an
531 error occurs in the evaluation of any argument, @code{errcatch}
532 prevents the error from propagating and
533 returns the empty list @code{[]} without evaluating any more arguments.
535 @code{errcatch}
536 is useful in @code{batch} files where one suspects an error might occur which
537 would terminate the @code{batch} if the error weren't caught.
539 See also @mrefdot{errormsg}
541 @opencatbox{Categories:}
542 @category{Programming}
543 @closecatbox
544 @end deffn
546 @c -----------------------------------------------------------------------------
547 @anchor{error}
548 @deffn {Function} error (@var{expr_1}, @dots{}, @var{expr_n})
549 @deffnx {System variable} error
551 Evaluates and prints @var{expr_1}, @dots{}, @var{expr_n},
552 and then causes an error return to top level Maxima
553 or to the nearest enclosing @code{errcatch}.
555 The variable @code{error} is set to a list describing the error.
556 The first element of @code{error} is a format string, which merges all the
557 strings among the arguments @var{expr_1}, @dots{}, @var{expr_n},
558 and the remaining elements are the values of any non-string arguments.
560 @code{errormsg()} formats and prints @code{error}.
561 This is effectively reprinting the most recent error message.
563 @opencatbox{Categories:}
564 @category{Programming}
565 @closecatbox
566 @end deffn
568 @c -----------------------------------------------------------------------------
569 @anchor{warning}
570 @deffn {Function} warning (@var{expr_1}, @dots{}, @var{expr_n})
572 Evaluates and prints @var{expr_1}, @dots{}, @var{expr_n},
573 as a warning message that is formatted in a standard way so a maxima front-end
574 may be able to recognize the warning and to format it accordingly.
576 The function @code{warning} always returns false.
578 @opencatbox{Categories:}
579 @category{Programming}
580 @closecatbox
581 @end deffn
583 @c -----------------------------------------------------------------------------
584 @anchor{error_size}
585 @defvr {Option variable} error_size
586 Default value: 60
588 @code{error_size} modifies error messages according to the size of expressions
589 which appear in them. If the size of an expression (as determined by the Lisp
590 function @code{ERROR-SIZE}) is greater than @code{error_size}, the expression is
591 replaced in the message by a symbol, and the symbol is assigned the expression.
592 The symbols are taken from the list @mref{error_syms}.
594 Otherwise, the expression is smaller than @code{error_size}, and the expression
595 is displayed in the message.
597 See also @mref{error} and @mrefdot{error_syms}
599 Example:
600 @c OUTPUT GENERATED BY THE FOLLOWING
601 @c U: (C^D^E + B + A)/(cos(X-1) + 1)$
602 @c error_size: 20$
603 @c error ("Example expression is", U);
604 @c errexp1;
605 @c error_size: 30$
606 @c error ("Example expression is", U);
608 The size of @code{U}, as determined by @code{ERROR-SIZE}, is 24.
610 @example
611 (%i1) U: (C^D^E + B + A)/(cos(X-1) + 1)$
613 (%i2) error_size: 20$
615 (%i3) error ("Example expression is", U);
617 Example expression is errexp1
618 -- an error. Quitting. To debug this try debugmode(true);
619 (%i4) errexp1;
620 E
621 D
622 C + B + A
623 (%o4) --------------
624 cos(X - 1) + 1
625 (%i5) error_size: 30$
627 (%i6) error ("Example expression is", U);
629 E
630 D
631 C + B + A
632 Example expression is --------------
633 cos(X - 1) + 1
634 -- an error. Quitting. To debug this try debugmode(true);
635 @end example
637 @opencatbox{Categories:}
638 @category{Debugging}
639 @category{Display flags and variables}
640 @closecatbox
641 @end defvr
643 @c -----------------------------------------------------------------------------
644 @anchor{error_syms}
645 @defvr {Option variable} error_syms
646 Default value: @code{[errexp1, errexp2, errexp3]}
648 In error messages, expressions larger than @mref{error_size} are replaced by
649 symbols, and the symbols are set to the expressions. The symbols are taken from
650 the list @code{error_syms}. The first too-large expression is replaced by
651 @code{error_syms[1]}, the second by @code{error_syms[2]}, and so on.
653 If there are more too-large expressions than there are elements of
654 @code{error_syms}, symbols are constructed automatically, with the @var{n}-th
655 symbol equivalent to @code{concat ('errexp, @var{n})}.
657 See also @mref{error} and @mrefdot{error_size}
659 @opencatbox{Categories:}
660 @category{Debugging}
661 @category{Display flags and variables}
662 @closecatbox
663 @end defvr
665 @c -----------------------------------------------------------------------------
666 @anchor{errormsg_fn}
667 @deffn {Function} errormsg ()
669 Reprints the most recent error message.
670 The variable @code{error} holds the message,
671 and @mref{errormsg} formats and prints it.
673 @opencatbox{Categories:}
674 @category{Programming}
675 @closecatbox
676 @end deffn
678 @c -----------------------------------------------------------------------------
679 @anchor{errormsg}
680 @defvr {Option variable} errormsg
681 Default value: @code{true}
683 When @code{false} the output of error messages is suppressed.
685 The option variable @code{errormsg} can not be set in a block to a local
686 value. The global value of @code{errormsg} is always present.
688 @c ===beg===
689 @c errormsg;
690 @c sin(a,b);
691 @c errormsg: false;
692 @c sin(a,b);
693 @c ===end===
694 @example
695 @group
696 (%i1) errormsg;
697 (%o1) true
698 @end group
699 @group
700 (%i2) sin(a,b);
701 sin: wrong number of arguments.
702 -- an error. To debug this try: debugmode(true);
703 @end group
704 @group
705 (%i3) errormsg: false;
706 (%o3) false
707 @end group
708 @group
709 (%i4) sin(a,b);
710 -- an error. To debug this try: debugmode(true);
711 @end group
712 @end example
714 The option variable @code{errormsg} can not be set in a block to a local value.
716 @c ===beg===
717 @c f(bool):=block([errormsg:bool],
718 @c print ("value of errormsg is",errormsg))$
719 @c errormsg:true;
720 @c f(false);
721 @c errormsg:false;
722 @c f(true);
723 @c ===end===
724 @example
725 (%i1) f(bool):=block([errormsg:bool],
726 print ("value of errormsg is",errormsg))$
727 @group
728 (%i2) errormsg:true;
729 (%o2) true
730 @end group
731 @group
732 (%i3) f(false);
733 value of errormsg is true
734 (%o3) true
735 @end group
736 @group
737 (%i4) errormsg:false;
738 (%o4) false
739 @end group
740 @group
741 (%i5) f(true);
742 value of errormsg is false
743 (%o5) false
744 @end group
745 @end example
747 @opencatbox{Categories:}
748 @category{Programming}
749 @closecatbox
750 @end defvr
752 @c -----------------------------------------------------------------------------
753 @anchor{go}
754 @deffn {Function} go (@var{tag})
756 is used within a @mref{block} to transfer control to the statement
757 of the block which is tagged with the argument to @code{go}. To tag a
758 statement, precede it by an atomic argument as another statement in
759 the @code{block}. For example:
761 @example
762 block ([x], x:1, loop, x+1, ..., go(loop), ...)
763 @end example
765 The argument to @code{go} must be the name of a tag appearing in the same
766 @code{block}. One cannot use @code{go} to transfer to tag in a @code{block}
767 other than the one containing the @code{go}.
769 @opencatbox{Categories:}
770 @category{Programming}
771 @closecatbox
772 @end deffn
774 @c NEEDS CLARIFICATION, EXPANSION, EXAMPLES
775 @c THIS ITEM IS IMPORTANT
777 @c -----------------------------------------------------------------------------
778 @anchor{if}
779 @deffn {Special operator} if
781 Represents conditional evaluation. Various forms of @code{if} expressions are
782 recognized.
784 @code{if @var{cond_1} then @var{expr_1} else @var{expr_0}}
785 eva@-lu@-ates to @var{expr_1} if @var{cond_1} evaluates to @code{true},
786 otherwise the expression evaluates to @var{expr_0}.
788 The command @code{if @var{cond_1} then @var{expr_1} elseif @var{cond_2} then
789 @var{expr_2} elseif ... else @var{expr_0}} evaluates to @var{expr_k} if
790 @var{cond_k} is @code{true} and all preceding conditions are @code{false}. If
791 none of the conditions are @code{true}, the expression evaluates to
792 @code{expr_0}.
794 A trailing @code{else false} is assumed if @code{else} is missing. That is,
795 the command @code{if @var{cond_1} then @var{expr_1}} is equivalent to
796 @code{if @var{cond_1} then @var{expr_1} else false}, and the command
797 @code{if @var{cond_1} then @var{expr_1} elseif ... elseif @var{cond_n} then
798 @var{expr_n}} is equivalent to @code{if @var{cond_1} then @var{expr_1} elseif
799 ... elseif @var{cond_n} then @var{expr_n} else false}.
801 The alternatives @var{expr_0}, @dots{}, @var{expr_n} may be any Maxima
802 expressions, including nested @code{if} expressions. The alternatives are
803 neither simplified nor evaluated unless the corresponding condition is
804 @code{true}.
806 The conditions @var{cond_1}, @dots{}, @var{cond_n} are expressions which
807 potentially or actually evaluate to @code{true} or @code{false}.
808 When a condition does not actually evaluate to @code{true} or @code{false},
809 the behavior of @code{if} is governed by the global flag @code{prederror}.
810 When @code{prederror} is @code{true}, it is an error if any evaluated condition
811 does not evaluate to @code{true} or @code{false}. Otherwise, conditions which
812 do not evaluate to @code{true} or @code{false} are accepted, and the result is
813 a conditional expression.
815 Among other elements, conditions may comprise relational and logical operators
816 as follows.
818 @c - SEEMS LIKE THIS TABLE WANTS TO BE IN A DISCUSSION OF PREDICATE FUNCTIONS; PRESENT LOCATION IS OK I GUESS
819 @c I (rtoy) would prefer to use the headitem prototype text since it's
820 @c easier to reason about, but currently the html output just seems to
821 @c ignore that and automatically makes the column width fit the widest
822 @c entry. We use @columnfractions to fix that, but it's hard to know
823 @c a priori how wide to make each column.
824 @indentedblock
825 @c @multitable {greater than or equal to 333} {notequal 333} {relational function}
826 @multitable @columnfractions .3 .2 .3
827 @headitem Operation @tab Symbol @tab Type
828 @item less than @tab @code{<} @tab relational infix
829 @item less than or equal to @tab @code{<=} @tab relational infix
830 @item equality (syntactic) @tab @code{=} @tab relational infix
831 @item equality (value) @tab @code{equal} @tab relational function
832 @item negation of equal @tab @code{notequal} @tab relational function
833 @item greater than or equal to @tab @code{>=} @tab relational infix
834 @item greater than @tab @code{>} @tab relational infix
835 @item and @tab @code{and} @tab logical infix
836 @item or @tab @code{or} @tab logical infix
837 @item not @tab @code{not} @tab logical infix
838 @end multitable
839 @end indentedblock
841 @opencatbox{Categories:}
842 @category{Programming}
843 @category{Predicate functions}
844 @closecatbox
845 @end deffn
847 @c NEEDS CLARIFICATION
848 @c THIS ITEM IS IMPORTANT
850 @c -----------------------------------------------------------------------------
851 @anchor{map}
852 @deffn {Function} map (@var{f}, @var{expr_1}, @dots{}, @var{expr_n})
854 Returns an expression whose leading operator is the same as that of the
855 expressions @var{expr_1}, @dots{}, @var{expr_n} but whose subparts are the
856 results of applying @var{f} to the corresponding subparts of the expressions.
857 @var{f} is either the name of a function of @math{n} arguments or is a
858 @code{lambda} form of @math{n} arguments.
860 @mref{maperror} - if @code{false} will cause all of the mapping
861 functions to (1) stop when they finish going down the shortest
862 @var{expr_i} if not all of the @var{expr_i} are of the same length and
863 (2) apply @var{f} to [@var{expr_1}, @var{expr_2}, @dots{}] if the
864 @var{expr_i} are not all the same type of object. If @code{maperror}
865 is @code{true} then an error message will be given in the above two
866 instances.
868 One of the uses of this function is to @code{map} a function (e.g.
869 @mref{partfrac}) onto each term of a very large expression where it ordinarily
870 wouldn't be possible to use the function on the entire expression due to an
871 exhaustion of list storage space in the course of the computation.
873 See also @mrefcomma{scanmap} @mrefcomma{maplist} @mrefcomma{outermap} @mref{matrixmap} and @mrefdot{apply}
875 @c IN THESE EXAMPLES, SPELL OUT WHAT IS THE MAIN OPERATOR
876 @c AND SHOW HOW THE RESULT FOLLOWS FROM THE DESCRIPTION STATED IN THE FIRST PARAGRAPH
878 @c ===beg===
879 @c map(f,x+a*y+b*z);
880 @c map(lambda([u],partfrac(u,x)),x+1/(x^3+4*x^2+5*x+2));
881 @c map(ratsimp, x/(x^2+x)+(y^2+y)/y);
882 @c map("=",[a,b],[-0.5,3]);
883 @c ===end===
884 @example
885 (%i1) map(f,x+a*y+b*z);
886 (%o1) f(b z) + f(a y) + f(x)
887 (%i2) map(lambda([u],partfrac(u,x)),x+1/(x^3+4*x^2+5*x+2));
888 1 1 1
889 (%o2) ----- - ----- + -------- + x
890 x + 2 x + 1 2
891 (x + 1)
892 (%i3) map(ratsimp, x/(x^2+x)+(y^2+y)/y);
893 1
894 (%o3) y + ----- + 1
895 x + 1
896 (%i4) map("=",[a,b],[-0.5,3]);
897 (%o4) [a = - 0.5, b = 3]
900 @end example
902 @opencatbox{Categories:}
903 @category{Function application}
904 @closecatbox
905 @end deffn
907 @c -----------------------------------------------------------------------------
908 @anchor{mapatom}
909 @deffn {Function} mapatom (@var{expr})
911 Returns @code{true} if and only if @var{expr} is treated by the mapping
912 routines as an atom. "Mapatoms" are atoms, numbers
913 (including rational numbers), subscripted variables and structure
914 references.
915 @c WHAT ARE "THE MAPPING ROUTINES", AND WHY DO THEY HAVE A SPECIALIZED NOTION OF ATOMS ??
917 @opencatbox{Categories:}
918 @category{Predicate functions}
919 @closecatbox
920 @end deffn
922 @c NEEDS CLARIFICATION
924 @c -----------------------------------------------------------------------------
925 @anchor{maperror}
926 @defvr {Option variable} maperror
927 Default value: @code{true}
929 When @code{maperror} is @code{false}, causes all of the mapping functions,
930 for example
932 @example
933 map (@var{f}, @var{expr_1}, @var{expr_2}, ...)
934 @end example
936 to (1) stop when they finish going down the shortest @var{expr_i} if
937 not all of the @var{expr_i} are of the same length and (2) apply
938 @var{f} to [@var{expr_1}, @var{expr_2}, @dots{}] if the @var{expr_i} are
939 not all the same type of object.
941 If @code{maperror} is @code{true} then an error message
942 is displayed in the above two instances.
944 @opencatbox{Categories:}
945 @category{Function application}
946 @closecatbox
947 @end defvr
949 @c -----------------------------------------------------------------------------
950 @anchor{mapprint}
951 @defvr {Option variable} mapprint
952 Default value: @code{true}
954 When @code{mapprint} is @code{true}, various information messages from
955 @mref{map}, @mref{maplist}, and @mref{fullmap} are produced in certain
956 situations. These include situations where @code{map} would use
957 @mref{apply}, or @code{map} is truncating on the shortest list.
959 If @mref{mapprint} is @code{false}, these messages are suppressed.
961 @opencatbox{Categories:}
962 @category{Function application}
963 @closecatbox
964 @end defvr
966 @c NEEDS CLARIFICATION
968 @c -----------------------------------------------------------------------------
969 @anchor{maplist}
970 @deffn {Function} maplist (@var{f}, @var{expr_1}, @dots{}, @var{expr_n})
972 Returns a list of the applications of @var{f} to the parts of the expressions
973 @var{expr_1}, @dots{}, @var{expr_n}. @var{f} is the name of a function, or a
974 lambda expression.
976 @code{maplist} differs from @code{map(@var{f}, @var{expr_1}, ..., @var{expr_n})}
977 which returns an expression with the same main operator as @var{expr_i} has
978 (except for simplifications and the case where @mref{map} does an @mref{apply}).
980 @opencatbox{Categories:}
981 @category{Function application}
982 @closecatbox
983 @end deffn
985 @c NEEDS CLARIFICATION
987 @c -----------------------------------------------------------------------------
988 @anchor{prederror}
989 @defvr {Option variable} prederror
990 Default value: @code{false}
992 When @code{prederror} is @code{true}, an error message is displayed whenever the
993 predicate of an @code{if} statement or an @mref{is} function fails to evaluate
994 to either @code{true} or @code{false}.
996 If @code{false}, @code{unknown} is returned
997 instead in this case. The @code{prederror: false} mode is not supported in
998 translated code;
999 however, @code{maybe} is supported in translated code.
1001 See also @mref{is} and @mrefdot{maybe}
1003 @opencatbox{Categories:}
1004 @category{Programming}
1005 @category{Predicate functions}
1006 @closecatbox
1008 @end defvr
1010 @anchor{return}
1011 @deffn {Function} return (@var{value})
1012 May be used to exit explicitly from the current @mrefcomma{block} @mrefcomma{while}
1013 @mref{for} or @mref{do} loop bringing its argument. It therefore can be compared
1014 with the @code{return} statement found in other programming languages but it yields
1015 one difference: In maxima only returns from the current block, not from the entire
1016 function it was called in. In this aspect it more closely resembles the @code{break}
1017 statement from C.
1019 @c ===beg===
1020 @c for i:1 thru 10 do o:i;
1021 @c for i:1 thru 10 do if i=3 then return(i);
1022 @c for i:1 thru 10 do
1023 @c (
1024 @c block([i],
1025 @c i:3,
1026 @c return(i)
1027 @c ),
1028 @c return(8)
1029 @c );
1030 @c block([i],
1031 @c i:4,
1032 @c block([o],
1033 @c o:5,
1034 @c return(o)
1035 @c ),
1036 @c return(i),
1037 @c return(10)
1038 @c );
1039 @c ===end===
1040 @example
1041 @group
1042 (%i1) for i:1 thru 10 do o:i;
1043 (%o1) done
1044 @end group
1045 @group
1046 (%i2) for i:1 thru 10 do if i=3 then return(i);
1047 (%o2) 3
1048 @end group
1049 @group
1050 (%i3) for i:1 thru 10 do
1051 (
1052 block([i],
1053 i:3,
1054 return(i)
1055 ),
1056 return(8)
1057 );
1058 (%o3) 8
1059 @end group
1060 (%i4) block([i],
1061 i:4,
1062 block([o],
1063 o:5,
1064 return(o)
1065 ),
1066 return(i),
1067 return(10)
1068 );
1069 (%o4) 4
1070 @end example
1073 See also @mrefcomma{for} @mrefcomma{while} @mref{do} and @mref{block}.
1075 @opencatbox{Categories:}
1076 @category{Programming}
1077 @closecatbox
1078 @end deffn
1080 @c NEEDS CLARIFICATION
1081 @anchor{scanmap}
1082 @deffn {Function} scanmap @
1083 @fname{scanmap} (@var{f}, @var{expr}) @
1084 @fname{scanmap} (@var{f}, @var{expr}, bottomup)
1086 Recursively applies @var{f} to @var{expr}, in a top
1087 down manner. This is most useful when complete factorization is
1088 desired, for example:
1090 @example
1091 (%i1) exp:(a^2+2*a+1)*y + x^2$
1092 (%i2) scanmap(factor,exp);
1093 2 2
1094 (%o2) (a + 1) y + x
1095 @end example
1097 Note the way in which @code{scanmap} applies the given function
1098 @code{factor} to the constituent subexpressions of @var{expr}; if
1099 another form of @var{expr} is presented to @code{scanmap} then the
1100 result may be different. Thus, @code{%o2} is not recovered when
1101 @code{scanmap} is applied to the expanded form of @code{exp}:
1103 @example
1104 (%i3) scanmap(factor,expand(exp));
1105 2 2
1106 (%o3) a y + 2 a y + y + x
1107 @end example
1109 Here is another example of the way in which @code{scanmap} recursively
1110 applies a given function to all subexpressions, including exponents:
1112 @example
1113 (%i4) expr : u*v^(a*x+b) + c$
1114 (%i5) scanmap('f, expr);
1115 f(f(f(a) f(x)) + f(b))
1116 (%o5) f(f(f(u) f(f(v) )) + f(c))
1117 @end example
1119 @code{scanmap (@var{f}, @var{expr}, bottomup)} applies @var{f} to @var{expr} in a
1120 bottom-up manner. E.g., for undefined @code{f},
1122 @example
1123 scanmap(f,a*x+b) ->
1124 f(a*x+b) -> f(f(a*x)+f(b)) -> f(f(f(a)*f(x))+f(b))
1125 scanmap(f,a*x+b,bottomup) -> f(a)*f(x)+f(b)
1126 -> f(f(a)*f(x))+f(b) ->
1127 f(f(f(a)*f(x))+f(b))
1128 @end example
1130 In this case, you get the same answer both
1131 ways.
1133 @opencatbox{Categories:}
1134 @category{Function application}
1135 @closecatbox
1136 @end deffn
1138 @c -----------------------------------------------------------------------------
1139 @anchor{throw}
1140 @deffn {Function} throw (@var{expr})
1142 Evaluates @var{expr} and throws the value back to the most recent
1143 @mref{catch}. @code{throw} is used with @code{catch} as a nonlocal return
1144 mechanism.
1146 @opencatbox{Categories:}
1147 @category{Programming}
1148 @closecatbox
1149 @end deffn
1151 @c -----------------------------------------------------------------------------
1152 @anchor{outermap}
1153 @deffn {Function} outermap (@var{f}, @var{a_1}, @dots{}, @var{a_n})
1155 Applies the function @var{f} to each one of the elements of the outer product
1156 @var{a_1} cross @var{a_2} @dots{} cross @var{a_n}.
1158 @var{f} is the name of a function of @math{n} arguments or a lambda expression
1159 of @math{n} arguments. Each argument @var{a_k} may be a list or nested list,
1160 or a matrix, or any other kind of expression.
1162 The @code{outermap} return value is a nested structure. Let @var{x} be the
1163 return value. Then @var{x} has the same structure as the first list, nested
1164 list, or matrix argument, @code{@var{x}[i_1]...[i_m]} has the same structure as
1165 the second list, nested list, or matrix argument,
1166 @code{@var{x}[i_1]...[i_m][j_1]...[j_n]} has the same structure as the third
1167 list, nested list, or matrix argument, and so on, where @var{m}, @var{n},
1168 @dots{} are the numbers of indices required to access the elements of each
1169 argument (one for a list, two for a matrix, one or more for a nested list).
1170 Arguments which are not lists or matrices have no effect on the structure of
1171 the return value.
1173 Note that the effect of @code{outermap} is different from that of applying
1174 @var{f} to each one of the elements of the outer product returned by
1175 @mref{cartesian_product}. @code{outermap} preserves the structure of the
1176 arguments in the return value, while @code{cartesian_product} does not.
1178 @code{outermap} evaluates its arguments.
1180 See also @mrefcomma{map} @mrefcomma{maplist} and @mrefdot{apply}
1181 @c CROSS REF OTHER FUNCTIONS HERE ??
1183 Examples:
1185 Elementary examples of @code{outermap}.
1186 To show the argument combinations more clearly, @code{F} is left undefined.
1188 @c ===beg===
1189 @c outermap (F, [a, b, c], [1, 2, 3]);
1190 @c outermap (F, matrix ([a, b], [c, d]), matrix ([1, 2], [3, 4]));
1191 @c outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
1192 @c outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
1193 @c outermap ("+", [a, b, c], [1, 2, 3]);
1194 @c ===end===
1195 @example
1196 @group
1197 (%i1) outermap (F, [a, b, c], [1, 2, 3]);
1198 (%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)],
1199 [F(c, 1), F(c, 2), F(c, 3)]]
1200 @end group
1201 @group
1202 (%i2) outermap (F, matrix ([a, b], [c, d]), matrix ([1, 2], [3, 4]));
1203 [ [ F(a, 1) F(a, 2) ] [ F(b, 1) F(b, 2) ] ]
1204 [ [ ] [ ] ]
1205 [ [ F(a, 3) F(a, 4) ] [ F(b, 3) F(b, 4) ] ]
1206 (%o2) [ ]
1207 [ [ F(c, 1) F(c, 2) ] [ F(d, 1) F(d, 2) ] ]
1208 [ [ ] [ ] ]
1209 [ [ F(c, 3) F(c, 4) ] [ F(d, 3) F(d, 4) ] ]
1210 @end group
1211 @group
1212 (%i3) outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
1213 [ F(a, x, 1) F(a, x, 2) ] [ F(b, x, 1) F(b, x, 2) ]
1214 (%o3) [[ ], [ ]]
1215 [ F(a, x, 3) F(a, x, 4) ] [ F(b, x, 3) F(b, x, 4) ]
1216 @end group
1217 @group
1218 (%i4) outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
1219 [ [ F(a, 1, x) ] [ F(a, 2, x) ] ]
1220 (%o4) [[ [ ] [ ] ],
1221 [ [ F(a, 1, y) ] [ F(a, 2, y) ] ]
1222 [ [ F(b, 1, x) ] [ F(b, 2, x) ] ]
1223 [ [ ] [ ] ]]
1224 [ [ F(b, 1, y) ] [ F(b, 2, y) ] ]
1225 @end group
1226 @group
1227 (%i5) outermap ("+", [a, b, c], [1, 2, 3]);
1228 (%o5) [[a + 1, a + 2, a + 3], [b + 1, b + 2, b + 3],
1229 [c + 1, c + 2, c + 3]]
1230 @end group
1231 @end example
1233 A closer examination of the @code{outermap} return value. The first, second,
1234 and third arguments are a matrix, a list, and a matrix, respectively.
1235 The return value is a matrix.
1236 Each element of that matrix is a list,
1237 and each element of each list is a matrix.
1239 @c ===beg===
1240 @c arg_1 : matrix ([a, b], [c, d]);
1241 @c arg_2 : [11, 22];
1242 @c arg_3 : matrix ([xx, yy]);
1243 @c xx_0 : outermap (lambda ([x, y, z], x / y + z), arg_1,
1244 @c arg_2, arg_3);
1245 @c xx_1 : xx_0 [1][1];
1246 @c xx_2 : xx_0 [1][1] [1];
1247 @c xx_3 : xx_0 [1][1] [1] [1][1];
1248 @c [op (arg_1), op (arg_2), op (arg_3)];
1249 @c [op (xx_0), op (xx_1), op (xx_2)];
1250 @c ===end===
1251 @example
1252 @group
1253 (%i1) arg_1 : matrix ([a, b], [c, d]);
1254 [ a b ]
1255 (%o1) [ ]
1256 [ c d ]
1257 @end group
1258 @group
1259 (%i2) arg_2 : [11, 22];
1260 (%o2) [11, 22]
1261 @end group
1262 @group
1263 (%i3) arg_3 : matrix ([xx, yy]);
1264 (%o3) [ xx yy ]
1265 @end group
1266 (%i4) xx_0 : outermap (lambda ([x, y, z], x / y + z), arg_1,
1267 arg_2, arg_3);
1268 [ [ a a ] [ a a ] ]
1269 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1270 [ [ 11 11 ] [ 22 22 ] ]
1271 (%o4) Col 1 = [ ]
1272 [ [ c c ] [ c c ] ]
1273 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1274 [ [ 11 11 ] [ 22 22 ] ]
1275 [ [ b b ] [ b b ] ]
1276 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1277 [ [ 11 11 ] [ 22 22 ] ]
1278 Col 2 = [ ]
1279 [ [ d d ] [ d d ] ]
1280 [ [[ xx + -- yy + -- ], [ xx + -- yy + -- ]] ]
1281 [ [ 11 11 ] [ 22 22 ] ]
1282 @group
1283 (%i5) xx_1 : xx_0 [1][1];
1284 [ a a ] [ a a ]
1285 (%o5) [[ xx + -- yy + -- ], [ xx + -- yy + -- ]]
1286 [ 11 11 ] [ 22 22 ]
1287 @end group
1288 @group
1289 (%i6) xx_2 : xx_0 [1][1] [1];
1290 [ a a ]
1291 (%o6) [ xx + -- yy + -- ]
1292 [ 11 11 ]
1293 @end group
1294 @group
1295 (%i7) xx_3 : xx_0 [1][1] [1] [1][1];
1296 a
1297 (%o7) xx + --
1298 11
1299 @end group
1300 @group
1301 (%i8) [op (arg_1), op (arg_2), op (arg_3)];
1302 (%o8) [matrix, [, matrix]
1303 @end group
1304 @group
1305 (%i9) [op (xx_0), op (xx_1), op (xx_2)];
1306 (%o9) [matrix, [, matrix]
1307 @end group
1308 @end example
1310 @code{outermap} preserves the structure of the arguments in the return value,
1311 while @code{cartesian_product} does not.
1313 @c ===beg===
1314 @c outermap (F, [a, b, c], [1, 2, 3]);
1315 @c setify (flatten (%));
1316 @c map (lambda ([L], apply (F, L)),
1317 @c cartesian_product ({a, b, c}, {1, 2, 3}));
1318 @c is (equal (%, %th (2)));
1319 @c ===end===
1320 @example
1321 @group
1322 (%i1) outermap (F, [a, b, c], [1, 2, 3]);
1323 (%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)],
1324 [F(c, 1), F(c, 2), F(c, 3)]]
1325 @end group
1326 @group
1327 (%i2) setify (flatten (%));
1328 (%o2) @{F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3),
1329 F(c, 1), F(c, 2), F(c, 3)@}
1330 @end group
1331 @group
1332 (%i3) map (lambda ([L], apply (F, L)),
1333 cartesian_product (@{a, b, c@}, @{1, 2, 3@}));
1334 (%o3) @{F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3),
1335 F(c, 1), F(c, 2), F(c, 3)@}
1336 @end group
1337 @group
1338 (%i4) is (equal (%, %th (2)));
1339 (%o4) true
1340 @end group
1341 @end example
1343 @opencatbox{Categories:}
1344 @category{Function application}
1345 @closecatbox
1346 @end deffn