Learning MAXIMA


Many UNIX utilities are described as “little languages”; but maxima is a BIG language, comparable to FORTRAN or C; a still better analogue is the more complex PostScript language, with its hundreds of operators.  (maxima is a computer language for doing algebra, trigonometry, calculus, solving equations, and performing other common mathematical procedures on real and complex scalar variables, vectors and matrices, rather than just 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.

I've found that maxima has a steep learning curve. There are some tutorials available, but a little extra help would be useful.

A good place to start is with Antonio Cangiano's 10-minute tutorial and Richard Rand's slightly longer Introduction to Maxima.

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.

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.


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 store numerical values in variables.

So maxima uses a colon [ : ] to assign values to variable names. (This is similar to C's use of a colon to assign labels to places in a program; in both cases, the name before the colon is associated with something.)

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. (Note that this 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; and some statements are used to set flags that modify the way the program operates, and merely return the string "done". If you don't want to see the result of a statement, you can suppress the 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 the 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

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.

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 the program tries to represent integral and summation signs with ASCII-art versions of and Σ, the output is fairly ugly.

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. (Tell maxima just
? tex
— ending the line with just a ⟨CR⟩, not a semicolon — for details; see the Help section below.)

Fortran output

Similarly, there are fortran and f90 commands that produce output in the form of FORTRAN statements.) Unfortunately, maxima sends this useful output to the 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( . . . ));

Input-format output

All these forms are different  from the 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 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.

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 only 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:

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

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

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

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,


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, mostmaxima 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.

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 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

There are two other commands to bring up documentation. Most, but not all, commands have a file of examples available, which can be brought up 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.

Some topics also have interactive demonstrations. These are in files with extensions like .dem or .demo , either in subdirectories under  /usr/share/maxima/5.34.1/share/  or in  /usr/share/maxima/5.34.1/demo/  itself.  You have to specify the path (as a string in double-quotes) to the demo file from  /usr/share/maxima/5.34.1/* .  [Note that the "5.34.1" here is the current number of the installed version of maxima.]

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.34.1/share");
which lets your default shell execute the ls.

The handful of *.dem files in /usr/share/maxima/5.34.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.34.1/demo/array.dem .

But to run the demo in /usr/share/maxima/5.34.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.


Copyright © 2011 – 2012, 2018 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