Learning MAXIMA

Introduction

Many UNIX utilities are described as “little languages”; but maxima is a BIG language, comparable to modern versions of FORTRAN or C ; still better analogues are the more complex PostScript and LaTeX languages, with their hundreds of operators.  (maxima is an environment for doing symbolic algebra, trigonometry, calculus, solving equations, and performing other common mathematical procedures on real and complex scalar variables, vectors and matrices, as well as numerical or logical operations on numbers and strings.)

Partly because of its wide scope, and partly because maxima is older than UNIX and almost as old as FORTRAN , it's large, complicated, and full of fossils from the days of punched cards — when computers had very limited character sets, and awkward work-arounds had to be used to make up for a paucity of operators and symbols. That makes it a bit clumsy to use, and difficult to pick up. On the other hand, its long history means it's mature software, and relatively reliable. There is a pretty good overview of it on Wikipedia, at https://en.wikipedia.org/wiki/Maxima_(software). The current version of maxima is available at https://maxima.sourceforge.io/.

I've found that maxima has a steep learning curve. There are some tutorials available, but a little extra help would be useful. There is considerable documentation available at http://maxima.sourceforge.net/documentation.html.

A good place to start is with Antonio Cangiano's 10-minute tutorial and Richard Rand's longer Introduction to Maxima , which is available on your own system if you have installed Debian's maxima-doc package. (It will be in the file /usr/share/doc/maxima-doc/html/intromax.html.)

After looking at these very simple examples, it's useful to move on to slightly more advanced guides, like Robert Dodier's 20-page Minimal Maxima , and Edwin L. Woollett's free book Maxima by Example . But the novice may find even these guides difficult to follow without a little preliminary explanation — which is what you see below. (If this is too complicated for you, I have an even simpler version.)

Once you are past this introductory level, I suggest a look at Roland Salz's very clear (but incomplete) Maxima Workbook  (https://roland-salz.de/Maxima_Workbook.pdf), which brings much systematic order to the disorganized entries in the Manual.

Basic Ideas

Usually, maxima is used interactively; you can think of it as a symbolic-algebra shell. Statements are executed as they are encountered. As with a shell, scripts or “batch” files can be prepared for maxima too.

Input format

When maxima is used interactively, it presents numbered prompts (in parentheses) to ask for input. The input statements are denoted by %i followed by sequential integers: the first prompt is (%i1), the second is (%i2), and so on. These statement numbers can be used later on to refer to the corresponding lines of input.

Assignments

Assignment statements set up name-value pairs. Because maxima deals with complete equations as well as isolated algebraic expressions, it reserves the = operator for defining equations. That means that variables and functions have to be defined another way — unlike numerical languages like Fortran and C, where = is used to associate values with variable names.

So maxima uses a colon [:] to assign values to variable names. (This resembles the use of a colon in C and modern Fortran to assign labels to places in a program; in these cases, the name before the colon is associated with what follows it.)

Statement terminators

In some computer languages, such as Fortran and many scripting languages, the end of a line indicates the end of a statement. This isn't practical in maxima, where statements can be very long and require many lines. So maxima normally uses the semi-colon [ ; ] as a statement delimiter. (This also allows you to put several short statements on a single line of input.) For example, entering 
a:1; b:2;
at an input prompt assigns the numerical value 1 to the variable a, and the value 2 to b.

Normally, maxima executes the requested action and shows the result immediately afterward. In this example, the values 1 and 2 will be printed as the next two output lines.

However, you may not care to see the output from statements that produce lengthy intermediate results. Also, some statements that set flags to modify the way the program operates just return the string "done". If you don't want to see the result of a statement, you can suppress its printed output by ending the statement with a dollar sign [ $ ] instead of a semicolon. So, for example, 

c:3$ d:4$
produces no output — it just assigns 3 to the variable c, and 4 to d, and you get a new input prompt.

Function definitions

Unlike variable assignments, functions are defined with the peculiar  :=  operator. For example, 

F(x) := 2*x;
defines a function F(x). Here, the normal output is 
F(x) := 2 x
— i.e., the whole input line, but without  the semicolon terminator — and without  the asterisk that specifies multiplication.

Output Formats

This brings us to one of many confusing features in maxima: The forms of expressions in output lines are different  from the way they are input.

Default output format

The default output format is an attempt to represent normal mathematical notation. So, as we just saw, multiplication is implied by concatenation — though with a space inserted, so that identifiers (names) don't run together: the input  2*x  became  2 x  in the output.

Similarly, exponents get shifted up to the next line in output, so that x-squared is input as x^2 (or as x**2 — the Fortran convention), but looks like 

  2
x
in the usual output. This style is based on the nearest approximation to conventional notation that's possible on a lineprinter, which was the usual output device on mainframes when maxima was developed. (It's often described as “two-dimensional”.)

This isn't too bad, though raising exponents (and lowering subscripts) by a whole line instead of a half line makes them a little hard to read. But when maxima tries to represent integral and summation signs with ASCII-art versions of ∫ and Σ, the output is fairly ugly.

More readable output

Two different approaches to nicer formatting are (1) to use a GUI front-end, such as the wxMaxima interface, or (2) to produce output in a form that some elegant formatter like LaTeX can use. The former is preferable for interactive use; the latter is suitable for publication and hard-copy generally, as well as batch interaction at the computer terminal.
GUI output
The wxMaxima interface is well discussed in Chapter 1 of Edwin L. Woollett's book Maxima by Example  and need not be discussed further here. It's pretty readable, and is handy for occasional interactive use — especially by beginners.
TeX output
To get output suitable for use in TeX and LaTeX, use the tex command. (For details, just tell maxima 
? tex
— ending the line with just a <CR>, not a semicolon — see the Help section below.)

Fortran output

Similarly, there are fortran and f90 commands that produce output in the style of FORTRAN 77 or Fortran 90 statements. Unfortunately, maxima sends this useful output to its standard output, rather than to the usual '%o#' line, so it isn't easily saved in a file, even though it appears on your screen; the conventional %o output from the fortran operator is just “done”.

If you want to save the Fortran-formatted output, you should use something like 

with_stdout("ftn.out",fortran( . . . ));
which will save the Fortran-style output in a file named ftn.out.

Input-format output

All these output forms are different  from maxima's normal input format. But sometimes, you want to save commands in maxima's input format, so they can be read back in (e.g., in a “batch” file). The stringout command does that: 
stringout ("filename_in_quotes", input);
Note that the name  of a file is always a string , which must be enclosed in double-quotes. [ Unfortunately, the manual never tells you this, but consistently refers to the filename argument as  <filename>  — which would lead a novice reader to assume that the file name should be enclosed in angle brackets instead. ]

The input statements saved in this file can be read back in with the maxima operation 

batch ("filename_in_quotes");
You may find it helpful to include explanatory comments in the batch file. Comments in maxima are anything between /* and /*, just as in C.

Built-in Help

A few lines above, I mentioned that you could get detailed information on the tex command by typing a question mark, a space, and the name of the command. This is one of several different kinds of documentation that are available in maxima.

The help that's always available in maxima is the Manual, which comes in several forms. When you install the maxima package , you automatically get the info version, because maxima itself can display sections of that. But info files are not very nicely formatted; it's easier to read the Manual in HTML form — but that requires a browser. To get the Manual in HTML format, you have to install the maxima-doc package; then you'll find that help documentation in /usr/share/doc/maxima-doc/html/maxima.html. A variety of documentation, including a PDF version of the Manual, is at http://maxima.sourceforge.net/documentation.html.

But before you can read the help, you have to understand the jargon it's written in. So a short detour to explain the jargon is required.

Maxima and LISP jargon

LISP jargon

The problem is that maxima is built on top of a LISP engine. ( LISP was a fad in the early days of Artificial Intelligence; the name is an acronym for “LISt Processing”.) When maxima was first written at MIT, the only people using it were the AI people there; they were familiar with LISP, so they used its terminology when they wrote the original documentation.

Unfortunately, they also made their symbolic-algebra program very tightly coupled with LISP: the program accepts LISP statements as well as maxima statements. This is like the mixture of machine-language instructions and FORTRAN statements that were accepted in the short-lived experiment called FORTRAN III, which was generally thought to have been a Bad Thing. Yet the LISP features persist in maxima to the present day.

This might have made sense in the early days of maxima, when it had modest capabilities and was used mainly by LISP programmers. But today, LISP is of interest mainly to advanced developers who are adding esoteric new features to maxima. Nevertheless, the documentation is still full of LISP jargon. So even beginners are expected to understand things like “atoms” and “nouns” and “verbs” and “predicates”; — not to mention “lists” — and the help files continue to refer to these things.

So here's a short glossary:

  atom
In maxima, atoms are names  (of variables or procedures), numbers  (integer or floating-point), and strings  (enclosed in double-quotes: " ).

  list
An ordered set of objects (represented in maxima as a comma-separated list of items in square brackets: [a, b, c] is a list.)

  noun
Just a literal, symbolic name; as opposed to:
  verb
the execution  of a procedure, or the value  of a variable, invoked by using its name. (See the discussion of evaluation below.)

  predicate
In LISP, a predicate is a function that tests a condition. By convention, names of LISP predicates conventionally end in the letter p. You'll notice a lot of these in maxima. They return Boolean values (i.e., true or false).
These concepts are explained lucidly in more detail, with examples, in the first few pages of Robert Dodier's 20-page Minimal Maxima , and in still more detail in section 6, “Expressions”, of the Manual.

Evaluation

The other piece of jargon needed to read the Manual has to do with the term “evaluation”. You'll frequently find the phrase “This function evaluates its arguments” in the Manual. Fortunately, there's an excellent explanation of Evaluation  in Section 3 (pp. 6–9) of Minimal Maxima , so I don't need to discuss it further here.

Actually, most  maxima functions evaluate their arguments; but a few do not. And sometimes it's necessary to change the default behavior, and either inhibit evaluation when it normally would occur, or force evaluation when it wouldn't. You can control this behavior by using the operator ' (called “single-quote” in the Manual, though it's actually the apostrophe on your keyboard).

Prefixing an operator with one  single-quote mark suppresses evaluation, so that the operator's name is propagated, but the operation is deferred until some later evaluation. The jargon usage is something like: “If op is an operator, 'op is the noun form of the operator.”

On the other hand, prefixing the symbol name with two  single-quotes forces  evaluation, even when evaluation would not normally occur. In jargon:  “''op is the verb form of the operator.” (Don't confuse the pair of single-quotes [''] with a single double-quote ["].)

Using single-quote marks to postpone or to force immediate evaluation is often called “quoting” in the documentation. You can think of a single-quote as protecting the name that follows it from evaluation in maxima, much as the single-quote protects arguments from expansion by the shell in a UNIX command-line.

OK. Now that you can read the Manual and make some sense of it, let's get back to finding the right documentation.

Which kind of help?

Although the whole Manual is available in a separate window when you use either xmaxima or wxMaxima, you generally don't want to have to wade through it all; on my system, the PDF version is 954 pages long. Sometimes it's useful to keep a window open with the Manual in it, so you can consult the Index and dig up information. But most of the time, you just need a little advice on a particular topic. And that's available at maxima's input line.

Specific commands

If you just want to know the syntax for a particular command, just type a question mark, a space, the name of the command, and hit <CR> — just as in the tex example above. This brings up the manual entry for that command. (Notice that there must be a space after the question-mark.)

Actually, this peculiar notation (which omits the normal line terminator) is shorthand for the describe command. That is, 

? tex
is exactly equivalent to 
describe (tex);
as long as you're using maxima interactively. Actually, the full syntax is even longer, because the argument to describe should really be a string: 
describe ("tex");
— so you can see why the short form is preferable.

The problem here is that you have to know the name  of a maxima function or variable before you can look it up with either describe or ? . But, if you're a beginner, you don't know all those hundreds of names.

[ There's also a major inconvenience: the descriptions of many functions run to hundreds of lines, most of which scroll off the top of your screen. And there's no pager available to manage this display; you just have to tediously scroll back to read the first parts. It helps a little to invoke maxima in a console with enough lines to fill your screen. ]

Non-specific commands

There are two ways around this problem. One is to invoke the inexact  form of describe: 
describe ("tex", inexact);
which — fortunately — can be abbreviated as 
?? tex
This brings up a list of possible matches, containing all documented items that have the search string anywhere  (including in the middle of words) in their titles.
Caution: using ? or ?? to invoke  describe  works only  if the question-mark is the first  character on the input line.

The other way to conduct a fishing expedition is to use apropos, which is about as useful as the UNIX system command of the same name. Although the Manual claims that apropos works nearly the same way as describe, I find that apropos only finds keywords that begin  with the search string — which must not be enclosed in double-quotes. So 

apropos (integ);
brings up a list that includes integer and integrate, among other things.

Show and tell

Example
There are two more commands to bring up documentation. Most, but not all, commands have a file of examples available, which can be displayed with the example function. For example, 
example (diff);
displays many examples of the use of the diff (differentiation) function. Again, no quotes are needed around the argument.

If the word you ask about isn't the name of an example file, at least the command will provide a list of all the available topics. Then you can look for something plausible to try.

Demo
Some topics also have interactive demonstrations. These are in files with extensions like .dem or .demo , either in subdirectories under  /usr/share/maxima/5.38.1/share/  or in  /usr/share/maxima/5.38.1/demo/  itself.  You have to specify the path (as a string in double-quotes) to the demo file from  /usr/share/maxima/5.38.1/* .  [ Note that the "5.38.1" here is the current number of the installed version of maxima. (As of 2022, the version numbers are in the 40s, rather than the 38 on my machine.) ]

If the demo command can't find the file, it gives a list of directories  to search for what you want. You can then browse those directories to find files with a *.dem suffix, either by using the ls command in a separate window, or by using the system command from inside maxima — e.g., 

system("ls /usr/share/maxima/5.38.1/share");
which lets your default shell execute the ls.

The handful of *.dem files in /usr/share/maxima/5.38.1/demo/ can be used merely by giving the filename without the suffix; so 

demo ("array");
suffices to run the demo in /usr/share/maxima/5.38.1/demo/array.dem .

But to run the demo in /usr/share/maxima/5.38.1/share/contrib/format/format.demo , you have to say either 

demo ("contrib/format/format.demo");
or at least 
demo ("format/format.demo");
— being sure to include the suffix.
Remember:  demo requires  double-quoted strings;  example  does not.

Other pitfalls

Arithmetic

Because maxima can do arbitrary-precision arithmetic, one might be tempted to use it for extensive numerical computations. But because of maxima's awkward syntax, the arbitrary-precision calculator bc is usually a better choice.

Furthermore, there are several “option variables” whose settings determine the number of digits of precision, the default conversions between floating-point values and rational expressions, conversions between machine floats and “bigfloats” (i.e., higher-precision values), and so on. Unless you know what you are doing, you may get misleading numerical output; generally, a complicated system with lots of adjustments is usually out of adjustment.

In particular, the default value of fpprec (the number of digits printed in output lines) is 16, to match the precision of ordinary double-precision floating-point hardware. To print 40 digits when that precision is needed, you have to set 

	fpprec: 40;
(remembering to use the colon for the assignment, instead of an equal sign).

Re-formatted output

Remember that maxima has several kinds of things that other computer languages lack, like lists. These can be represented in tex output format, but what happens to them in Fortran output?

The closest Fortran object to a list is an array; so maxima translates lists into Fortran's array notation. This can be perplexing when you first try to put a Padé approximant into an arithmetic Fortran statement, because the output of the pade function is a list. If you assign its result to a variable, whose name will be printed out before an equal sign by the fortran function, you may be puzzled to see it appear in the Fortran output with “(1)” appended. That's because maxima has converted the one-item list produced by its pade function into a Fortran array just one element long.

To get the particular approximant you want out of its list and into a simple variable, you can use the first function in maxima. This will remove those inconspicuous square brackets from maxima's output, and save the result in a single Fortran variable, instead of in a one-element array. [In addition to first, there are functions named second through tenth, as well as rest and last.]

 

Copyright © 2011, 2012, 2018, 2020, 2022 Andrew T. Young

Back to the . . .
GF reading page

or the GF pictures page

or the main mirage page

or the GF home page

or the website overview page