Learning the MAXIMA Computer Algebra System

Introduction

For years, I struggled to learn to use maxima, the open-source computer algebra system. Its user interface is very different from that of most other software, and is heavily influenced by the conventions of LISP (the odd language that acts as its interpreter). Like LaTeX or PostScript, it has hundreds of commands; so there's a lot of stuff to learn.

Here's my attempt to write a guide for beginners — and some reminders for occasional users, like myself. If you find it too elementary, I also have a slightly higher-level guide to learning maxima.

Debian and most other Linux distributions have a command-line version of maxima, usually in a package with that name. If you're as un-coordinated as I am, you'll prefer this to the GUI versions like xmaxima (for the X Window System) or wxmaxima. Plain command-line maxima itself is complicated enough without having to use a mouse and navigate a nest of menus as well, so this guide will deal with just the bare-bones CLI version.

If you have never used maxima, just read on; I'll start with the most basic ideas.

If you only need a refresher on a particular topic, here are links to some important sections:

Basic Conventions

Think of maxima as a expert system that knows a lot of rules about mathematical operations. Unfortunately, you have to interact with its rather clumsy and rigid user interface. Proceed slowly and carefully, as maxima is intolerant of typos. You will have to be very specific in telling it what to do.

Interactive use

The usual interaction is to feed maxima statements to process, one at a time. When maxima has processed a statement, it will either show you the result, or prompt for another statement.

When maxima is ready for input, it presents a prompt like this: 

	(%i1)

The "%i" in the prompt tells you it's ready for input. The number that follows is part of a label that maxima assigns to your input. (These labels can be used in later input statements.) Here the label is "%i1".

Often, input statements to maxima are long, complicated expressions that need two or more lines. That means that a simple carriage return, <CR>, is not enough to mark the end of a statement. So maxima requires a special statement terminator:

Statement terminators

There are two common statement terminators: 
	;	/* <semicolon><CR>     prints output */

	$	/* <dollar sign><CR>   prints no output */

If you forget to type the statement terminator, and just hit <CR>, maxima will move the cursor down to the next line and wait patiently for more input. It ignores superfluous whitespace, so go ahead and type the terminator before pressing <CR> again.

If a statement prints output, that will be shown after a label like 

	(%o1)

where the "o" means "output" — and, again, these labels can be used in later input statements. For example: 

	(%i1) x;
	(%o1)                                  x
	(%i2) y$

	(%i3) %o1+%o2;
	(%o3)                                y + x
	(%i4)
Notice that the result  %o2  was actually computed; it just wasn't printed.

Interactive style

The little snippet above shows how a session proceeds: there is an alternating sequence of input from the user, and output from maxima. The small sample above shows how to create two variables, x and y, and then represents their sum. To do anything useful will require many more such input-output pairs.
A useful notation
Consequently, you'll need to perform a series of operations to manipulate variables, expressions, and equations into the final result you want. At each step, you need to see the current state of this process; so it's convenient to have a shorthand label for "the last output from maxima". There's a standard symbol for that: "%".

You'll also want to name some particular intermediate quantities, and assign values to them. I'll get to assignments later, below.

Names
Although all maxima operations are defined by lower-case names, you can use upper-case letters in names, which helps avoid conflict with the many pre-defined special words. All names are case-sensitive, so X and x are names for different variables.

Getting out of  maxima

The right way
Just as everything in *ix is a file, and everything in Lisp is in parentheses, everything in macsyma seems to use a function of some kind; and that includes quitting the program. So the universally approved way to quit is to enter 
	quit();
Here, the parentheses are required because quit is a function  with zero arguments. And of course the semicolon is needed to terminate the statement.
The WRONG way
Because maxima is closely tied to Lisp, it's easy to get it confused with a wrong keystroke; then you'll find yourself dealing with the Lisp interface. This often happens to beginners who are trying to get out of maxima. Typically, you get an error message like 
	Maxima encountered a Lisp error:
followed by 
	To enable the Lisp debugger set *debugger-hook* to nil.
NO. Don't do that! The way to get back on track is to type just 
	:q<CR>
which will get you a normal maxima input prompt.

Similarly, if you do something wrong and find yourself looking at a prompt that says 

	MAXIMA>>>
(often with another ">" every time you hit <CR>), the way to get back to normal input is to enter just "<colon>q": 
	:q<CR>
Once you have the regular "%i" type of prompt, you can tell it 
	quit();
and you're back to your shell prompt.

Basic Operations

Starting  maxima

Now that you know how to get out of  maxima, it should be safe for you to start it. In any text terminal that displays a shell prompt, just type 
	maxima<CR>
and you should see its startup message, followed by a (%i1) prompt for input.

If the shell can't find maxima, it probably hasn't been installed. Is it in one of the directories in the list printed by an 

	echo $PATH<CR>
command? If not, you need to install it (as root).

Text: Comments and Annotations

In addition to mathematical constructs, maxima supports strings of text characters. While there are many functions for operating on strings, these are not of immediate interest. However, comments in input and annotations in output are very basic.

Comments

Comments in input are essential to explain what is supposed to be going on. As in C, a comment is any text between "/*" and "*/ — for example, 
	/* This is a comment */
The input parser ignores everything in a comment, including its delimiters, and replaces the whole thing with whitespace. So comments can appear anywhere in maxima input, except in the middle of a name.

Annotations

Similarly, it's useful to annotate output with text. There are several ways to do this, but the commonest uses "print". The function print() evaluates and displays its arguments, some of which can be strings of text, which are enclosed in double-quotes. E.g.: 
	print ("The result of the last calculation was",%);

Numerical operations

Integers

At the lowest level, you can treat maxima as a glorified calculator. For example: 
	(%i1) 4+5;
	(%o1)                                  9
	(%i2) 4*5;
	(%o2)                                 20
	(%i3) 2^3;
	(%o3)                                  8
	(%i4) 2**3;
	(%o4)                                  8
Notice that the regular exponentiation operator is ^, as in C; but the ** used in Fortran is also accepted.

Besides the usual operations on integers, maxima has rational numbers, such as 

	(%i5) 4/5;
	                                       4
	(%o5)                                  -
	                                       5
that can be converted to floating-point values: 
	(%i6) %,numer;
	(%o6)                                 0.8
	(%i7)
That "(%i6)" input illustrates two more features of maxima: first, the use of "%" in an input line to mean the previous output value; and second, the addition of a comma and the condition "numer" to force decimal evaluation of any expression.

Also, notice the re-setting of the fraction in (%o5) above. That's an example of what maxima calls "two-dimensional" output. It works well for fractions, but gets messy for complicated expressions with lots of exponents and subscripts, which is why many people prefer maxima's flavors with graphical interfaces (xmaxima and wxmaxima).

Floating-point numbers

There are two kinds of floating-point numbers: ordinary double-precision numbers with 15 or 16 decimal digits, and arbitrary-precision "big floats". Because maxima's user interface is so clumsy, it's easier to use the arbitrary-precision calculator bc if all you need is some high-precision arithmetic.

Assignments

Most numerical tools use the equality sign (=) to assign values to variables. But maxima deals with things like simultaneous equations, or differential equations, where the equality sign is used to write the equations. So, to avoid the ambiguity caused by overloading the "=" sign, maxima uses a colon (:) to assign values to variables: 
	(%i13) x:5;
	(%o13)                                 5
	(%i14) print("The value of x is",x);
	The value of x is 5 
	(%o14)                                 5
Notice that the "print" function has two arguments here: a text string (enclosed in double-quotes); and the variable x (which is evaluated before being printed). [ In general, it can have any number of arguments. ]

Interactive help

You'd think that a big, complicated program like maxima would have a "help" command, but it doesn't. However, there is some help available. The simplest kind is to inquire about some operator or operation; that can be done by typing 
	? cmd<CR>
at an input prompt. Notice that there is no statement terminator; you just enter the question mark, a space, and the name of the command.

Unfortunately, this prints the section of the reference manual for maxima that describes the command; but the manual is written in LISP jargon, which is a more advanced topic. Please read the references mentioned in my other page about maxima.

Actually, it turns out that this odd syntax with a question mark is just an alias for the maxima function describe(). And there is a complication: the question mark must be the first character on the line.

A more useful form of on-line help is available through the example() function, which offers examples of the use of several topics. The problem here is that not every operation in maxima has a text file showing examples. Fortunately, the command example() (with no arguments) provides a list of all the topics for which example files exist.

There's also an apropos() function that's about as useless as the one available at a shell prompt, and for the same reason: you have to know the exact name of what you're looking for, in order to use it.

Beyond the basics

The information above lets you flounder around a little in maxima, but doesn't tell you how to use it for its main purpose: mathematical manipulations. To get anything useful done, you need to look at some tutorials, and understand a little more about how maxima actually works. A slightly more advanced guide to these next steps is here.

 

Copyright © 2020, 2022 Andrew T. Young

Back to the . . .
main LaTeX page

or the alphabetic index page

or the GF home page

or the website overview page