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).
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.)
So maxima uses a colon [ : ] to assign values to variable names. (This resembles 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 what follows it.)
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,
Unlike variable assignments, functions are defined with the peculiar := operator. For example,
F(x) := 2*x;
F(x) := 2 x
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
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.
If you want to save the Fortran-formatted output, you should use something like
with_stdout("ftn.out",fortran( . . . ));
stringout ("filename_in_quotes", input);
The input statements saved in this file can be read back in with the maxima operation
You may find it helpful to include explanatory comments in the file. Comments in maxima are anything between /* and /*, just as in C.
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.
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:
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.
Actually, this peculiar notation (which omits the normal line terminator) is shorthand for the describe command. That is,
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.
describe ("tex", inexact);
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
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.
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.,
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
But to run the demo in /usr/share/maxima/5.34.1/share/contrib/format/format.demo , you have to say either
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).
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.
Copyright © 2011 – 2012, 2018, 2020 Andrew T. Young
GF pictures page
main mirage page
GF home page
or the website overview page