Imaxima

Imaxima is a package for displaying the output from the computer algebra system Maxima as images typeset by TeX.

This manual documents imaxima version branch_5_47_base_350_gc29330126. You can download the latest version of imaxima from the Maxima website.

Since version 1.0b, imaxima and imath supports inline graphs.

Send suggestions and bug reports to or the Maxima bug tracker.

Table of Contents


1 Installation

Install imaxima by unpacking the tarball and doing the usual incantation

./configure
make
make install

and put

(autoload 'imaxima "imaxima" "Image support for Maxima." t)

in your .emacs file.

If you use Interactive Math minor mode, put

(autoload 'imath-mode "imath" "Interactive Math minor mode." t)

in your .emacs file.

To do line breaking imaxima requires the LaTeX package breqn. This package is currently distributed from its CTAN webpage as breqn.tds.zip.

The files in breqn must be installed in a place where TeX can find them. In a typical LaTeX installation you should put the *.sty and *.sym files in

/usr/share/texmf/tex/latex/breqn/

and the documentation files in

/usr/share/texmf/doc/latex/breqn/.  

The files can also be installed in a number of other places—consult your TeX documentation for details.

Now run texhash after installing the files. You can use the command kpsewhich to verify that TeX is able to find the files, e.g.

kpsewhich breqn.sty

To get the best image quality a fairly recent version of Ghostscript is recommended. See Miscellaneous, for options suitable for using older versions of Ghostscript or not using Ghostscript at all

1.1 Manual installation

If you cannot use make, the manual steps required for installation are

  • Byte compile imaxima.el and imath.el.
  • Place the files imaxima.el, imaxima.elc, imath.el, imath.elc, imaxima-autoconf-variables.el and imaxima.lisp in Emacs’ load-path (see Lisp Libraries in The Emacs manual).
  • Install the TeX files in the way explained above.

2 Usage

To start using imaxima just type M-x imaxima. The imaxima directory needs to be on Emacs’ load-path.

Function: imaxima

Starts a Maxima session in an Emacs buffer.

You can turn image generation off by evaluating

display2d:true

in Maxima. Output from Maxima is then shown with the usual ASCII graphics. To turn images on again, evaluate

display2d:imaxima

If there is an error in a LaTeX expression you can press Mouse-2 (or RET) on the error message to view the error log and Mouse-3 (or M-RET) to view the LaTeX source file.

User Option: imaxima-use-maxima-mode-flag

Set to non-nil to use the Maxima mode from maxima.el.

By default imaxima.el uses a very simple mode which doesn’t provide any custom menus, font-locking or key-bindings. You can, however, combine imaxima.el with the Emacs mode from the Maxima distribution to get these features.

Function: imaxima-latex

Converts the Maxima buffer to a LaTeX document and opens it in LaTeX mode. imaxima-latex-buffer-name Note: This command does not work in XEmacs.

Function: imaxima-to-html

Converts the Maxima buffer to a HTML document named session.html and opens it in HTML mode. All the PNG files generated by imaxima for each output from Maxima are gathered in a folder named session-images and referenced from session.html. Note: This command does not work in XEmacs.

Function: imaxima-clean-up

Delete temporary files created by imaxima and kill the Ghostscript process if it is running. Normally imaxima does this automatically when you quit Maxima. This command is just a convenience if this doesn’t happen.

Function: imaxima-version

Display the package name and the version number of the imaxima imath package in the mini buffer. You should make sure the version information when you want to make bug reports.

Function: reinit-imaxima

Initialize the imaxima program. Sometimes you may encounter situations where imaxima does not repond to your input. This is caused by the inconsistency between Emacs Lisp and Maxima. Such situations can be resolved by using this command. After calling this command from the Emacs mini buffer, you should type simple Maxima expression such as 1+2; to ensure that the imaxima does respond to you now.

Function: imaxima-print-buffer

Run LaTeX on the current buffer and show output. See See imaxima-print-tex-command for how LaTeX is run.


3 Inline Graphs

Since version 1.0b, imaxima and imath supports the inline graph display feature. That is, if a special graph command (such as wxplot2d, wxplot3d) is used in the maxima session, the graph generated by the command is inserted in the maxima session buffer, instead of displaying in another window.

Before using this feature, you should make sure plot2d works with Gnuplot by trying:

(%i1) plot2d(x^2,[x,-5,5],[plot_format,gnuplot]);

If this works fine, then quite likely wxplot2d works, too.

Following commands can be used in a maxima session to draw graphs to be displayed inline: wxplot2d, wxplot3d, wxdraw2d, wxdraw3d, wximplicit_plot, and wxcontour_plot. New in version 1.0d, the graphics commands wxdraw, wxjulia and wxmandelbroit also provide inline images.

The syntax and capabilities of the wx-prefixed versions of the commands and their arguments are the same as the ones of the corresponding original commands. Hence, wxplot2d draws a graph inline in the imaxima buffer, while plot2d displays the same graph in a different window created by Gnuplot.

The wx-prefixed versions of the commands set up arguments so that Gnuplot is used to draw the graph and writes the graph in extended postscript format into a temporary file. Conseqently, use of plot options such as plot_format, gnuplot_script_file, gnuplot_term, ps_file or their draw counterparts will result in unspecified behaviour.

The wxdraw family of commands automatically load the draw package since they call draw internally. Similarly, wxjulia and wxmandelbroit automatically load the dynamics package.


3.1 Keybindings

Images in the imaxima buffer have a special keymap (see (emacs)keymaps). By hovering the mouse over the image, one can display the list of ‘hot keys’ and a short description of each action pressing a key triggers. To activate the keymap, point must be on the image.

  1. l : Copy the LaTeX source to generate the image under point into the register stored in imaxima-latex-src-register (default: l). see imaxima-get-latex-src.
  2. g : Have Gnuplot replot the graph/image under point in a separate window spawned by Gnuplot. see imaxima-gnuplot-replot.
  3. s : Forcibly restart the Gnuplot process. This can be useful if an error occurs during plotting. Some plot examples may only work if Gnuplot is restarted. see imaxima-gnuplot-restart.

3.2 Commands and Options

Command: imaxima-get-latex-src

When point is over an image, this copies the LaTeX source used by imaxima to generate the image into the register named by imaxima-latex-src-register.

Command: imaxima-gnuplot-replot

When point is over an image created by Gnuplot, this command will re-execute the Gnuplot script that created the image and display it in a separate window spawned by Gnuplot. Asks for the Gnuplot terminal to use. see imaxima-gnuplot-replot-term.

Command: imaxima-gnuplot-restart

Forcibly kill the Gnuplot process and buffer, if necessary, and then start a new Gnuplot process.

User Option: imaxima-gnuplot-buffer

The name of the buffer in which imaxima runs its Gnuplot process. Default: *imaxima-gnuplot*.

User Option: imaxima-gnuplot-command

The name of the Gnuplot executable that imaxima runs. Default: gnuplot.

User Option: imaxima-gnuplot-args

Optional arguments sent to the Gnuplot executable by imaxima. Default: "".

User Option: imaxima-latex-src-register

One can copy the LaTeX source used to generate an image into a register by placing point over the image and typing this key. Default: l.

User Option: imaxima-gnuplot-replot-term

The name of the Gnuplot terminal used to display an inline plot in an external, Gnuplot-spawned window. see imaxima-gnuplot-replot.


4 Options

All options can be changed in the Emacs customize interface, use M-x customize-group RET imaxima RET.


4.1 Appearance

User Option: imaxima-pt-size

The type size used in LaTeX. This can be ‘9’, ‘10’, ‘11’ or ‘12’ pt.

User Option: imaxima-fnt-size

Default size of font. Options include ‘small’, ‘normalsize’, ‘large’, ‘Large’, ‘LARGE’, ‘huge’ or ‘Huge’ (in non decreasing order).

User Option: imaxima-scale-factor

Scale all images by this factor. The default is ‘1.0’.

Note: The options imaxima-pt-size, imaxima-fnt-size and imaxima-scale-factor are highly non-orthogonal.

User Option: imaxima-equation-color

Color used for equations.

User Option: imaxima-label-color

Color used for output labels (red by default).

User Option: imaxima-bg-color

Background color used in the imaxima buffer. nil if you don’t want to change the default color.

User Option: imaxima-fg-color

Foreground color used in the imaxima buffer. nil if you don’t want to change the default color.

User Option: imaxima-latex-preamble

(See options imaxima-latex-document-class, imaxima-latex-use-packages, imaxima-latex-document-dimensions, imaxima-latex-macros and imaxima-latex-macros-linear.) LaTeX expression inserted at the start of the document preamble when TeX’ing equations. This can be used to change, say, the document font. E.g.

\usepackage{concrete}
\usepackage{euler}

will use Herman Zapf’s Euler math fonts and the accompanying Concrete roman fonts. These are probably better suited as screen fonts than the default Computer Modern, which works best at high resolutions.

User Option: imaxima-latex-error-face

Face used for LaTeX errors. This option is ignored when using maxima.el.

User Option: imaxima-latex-document-class

An elisp list (FORMAT-STRING [ARGS]) that provides a valid list of inputs to format. FORMAT-STRING should generate the LaTeX document class used to generate all LaTeX documents; ARGS is evaluated. Used by imaxima-latex.

User Option: imaxima-latex-use-packages

A string that contains all usepackage declarations needed. This is inserted into the LaTeX document after imaxima-latex-preamble.

User Option: imaxima-latex-macros-format-file

Macros used by imaxima-dump-tex to generate the format file.

User Option: imaxima-latex-macros, imaxima-latex-macros-linear

A string that defines imaxima-specific macros to format fractions in regular and linear fashion.

User Option: imaxima-latex-document-dimensions

A string the contains the document dimensions for imaxima-latex.

User Option: imaxima-create-image-options

An association list of options that are used by the imaxima function imaxima-create-image. For example, if one is using a dark background in emacs, it may be preferable to set this option to (:ascent center), thereby removing the default mask option.


4.2 Line Breaking

Imaxima usually does a decent job of breaking lines that are too wide to fit in the buffer (thanks to the breqn LaTeX package). However, this doesn’t work so well for very long fractions, superscripts and subscripts. Imaxima has two ways of dealing with this:

  • Scaling.
  • Rewriting the equation in a “linear” form which can be split over several lines.

The following options control how this is done.

User Option: imaxima-max-scale

Maximum amount of scaling allowed to fit wide equations in the buffer. The default is 0.85, which allows images to be scaled down to 85% of the original size. nil disables scaling and t allows unlimited scaling.

User Option: imaxima-linearize-flag

Non-nil allows fractions, superscripts, subscripts and square roots to be linearized to fit in the buffer. That is


         b                           a + b         _______
        a              a            -------       V a + b 
                        b            c + d

are written as

                                                          ?
    expt(a,b)   subscript(a,b)   (a + b)/(c + d)   (a + b)

4.3 Miscellaneous

If the required files are in your path, you shouldn’t normally need to change these options.

User Option: imaxima-latex-buffer-name

The default name of the buffer created by imaxima-latex. The default value is *imaxima-latex*.

User Option: imaxima-image-type

Image type used in the buffer. PNG, JPEG, TIFF and PostScript are supported. In my opinion PNG gives the best results, but if your Emacs wasn’t compiled with PNG support you could try one of the others. PostScript doesn’t require Ghostscript to be installed. XEmacs can not display PostScript images, so this type does not work in XEmacs.

User Option: imaxima-gs-program

Ghostscript executable

User Option: imaxima-gs-options

Options passed to gs when converting EPS to other image formats. Older versions of Ghostscript don’t support anti-aliasing. In that case you might have to remove the options -dTextAlphaBits=4 and -dGraphicsAlphaBits=4.

User Option: imaxima-cp-program

The default ‘copy’ program.

User Option: imaxima-dvips-program

Dvips executable.

User Option: imaxima-dvips-options

Command line options passed to dvips when converting EPS files to DVI.

User Option: imaxima-tmp-dir

Directory used for temporary files created by imaxima. /tmp by default.

User Option: imaxima-lisp-file

The Lisp file used to initialize Maxima.

User Option: imaxima-tex-program

TeX executable.

User Option: imaxima-initex-option

Option passed to TeX to start it in the “initial” form capable of dumping format files.

User Option: imaxima-maxima-program

Maxima executable.

User Option: imaxima-maxima-options

Command line arguments passed to Maxima. If you have Maxima versions compiled with different Lisps, you can use this to select which one to use. E.g. --lisp=cmucl will choose the version compiled with CMUCL.

User Option: imaxima-startup-hook

Hook run when starting imaxima.

User Option: imaxima-exit-hook

Hook run when exiting imaxima.

User Option: imaxima-html-dir

When imaxima-to-html function is called, the function determines the directory into which the session.html file and the session-images directory are created. The default value is “~”.

User Option: imaxima-print-tex-file

Name of the LaTeX file name to be created by imaxima-print-buffer. Do not include ".tex" suffix. This file will be stored in the directory imaxima-tmp-dir.

User Option: imaxima-print-tex-command

Command to run LaTeX on the file created by imaxima-print-buffer. In the string ’%s’ is replaced by the name of the tex file. e.g. "pdflatex %s; xpdf %s"


5 Imath minor mode

The imath minor mode provides a small set of functions to aid insert math formulas into plain text.

A math formula is written using a Maxima form whose syntax is {maxima a formula maxima} where a formula is a string which can be accepted as Maxima command input. C-c [ inserts a template for a maxima form.

The other way to write a math formula is to use LaTeX form whose syntax is {latex a formula latex} where a formula is a valid LaTeX commands. C-c ] inserts a template for a latex form.

Example maxima and latex forms are:

{maxima integrate(f(x),x) maxima}
{maxima sum(a[n],n,0,i) maxima}
{latex  \\int {f\\left(x\\right)}{\\;dx} latex}
{latex  \\sum_{n=0}^{i}{a_{n}} latex}

Assuming the cursor position is right after a form or in the middle, C-c ! transforms the form into the formula image using the Imaxima functionality.

If the resulting image is not what you want, you may want to edit the formula again. To do this, place the cursor right after the image and C-c &. Then the image is removed and original form appears at the position.

When saving the buffer into a file, images are discarded. However, maxima forms and their corresponding latex forms are kept there in the text. If the text is loaded again into Emacs and imath minor mode is enabled, you can type C-c $ to restore all the images for the forms in the buffer.

\C-c[   Compose Maxima form
\C-c]   Compose Latex form
\C-c!   Transform a form to an image
\C-c$   Transform all forms to images
\C-c&   Remove the image to restore the original form text

You can export the imath mode buffer contents into HTML using a command named imath-to-html. This command can be invoked by M-x imath-to-html. Then a buffer is created, visiting a file whose name is the same as the original imath text file, only exception being .html as the file extension. Upon saving, the file is placed in the same directory as the original file. Also a directory is created whose name is the same as the imath text file, but removing the extension and add -images. Images for formulas are copied in this directory.


6 Index

Jump to:   B   C   E   G   I   J   P   R  
Index Entry  Section

B
breqn: Installation

C
CMUCL: Miscellaneous
concrete: Appearance

E
euler: Appearance

G
ghostscript: Miscellaneous

I
imaxima: Usage
imaxima-bg-color: Appearance
imaxima-clean-up: Usage
imaxima-cp-program: Miscellaneous
imaxima-create-image-options: Appearance
imaxima-dvips-options: Miscellaneous
imaxima-dvips-program: Miscellaneous
imaxima-equation-color: Appearance
imaxima-exit-hook: Miscellaneous
imaxima-fg-color: Appearance
imaxima-fnt-size: Appearance
imaxima-get-latex-src: Commands and Options
imaxima-gnuplot-args: Commands and Options
imaxima-gnuplot-buffer: Commands and Options
imaxima-gnuplot-command: Commands and Options
imaxima-gnuplot-replot: Commands and Options
imaxima-gnuplot-replot-term: Commands and Options
imaxima-gnuplot-restart: Commands and Options
imaxima-gs-options: Miscellaneous
imaxima-gs-program: Miscellaneous
imaxima-html-dir: Miscellaneous
imaxima-image-type: Miscellaneous
imaxima-initex-option: Miscellaneous
imaxima-label-color: Appearance
imaxima-latex: Usage
imaxima-latex-buffer-name: Miscellaneous
imaxima-latex-document-class: Appearance
imaxima-latex-document-dimensions: Appearance
imaxima-latex-error-face: Appearance
imaxima-latex-macros,: Appearance
imaxima-latex-macros-format-file: Appearance
imaxima-latex-preamble: Appearance
imaxima-latex-src-register: Commands and Options
imaxima-latex-use-packages: Appearance
imaxima-linearize-flag: Line Breaking
imaxima-lisp-file: Miscellaneous
imaxima-max-scale: Line Breaking
imaxima-maxima-options: Miscellaneous
imaxima-maxima-program: Miscellaneous
imaxima-print-buffer: Usage
imaxima-print-tex-command: Miscellaneous
imaxima-print-tex-file: Miscellaneous
imaxima-pt-size: Appearance
imaxima-scale-factor: Appearance
imaxima-startup-hook: Miscellaneous
imaxima-tex-program: Miscellaneous
imaxima-tmp-dir: Miscellaneous
imaxima-to-html: Usage
imaxima-use-maxima-mode-flag: Usage
imaxima-version: Usage

J
jpeg: Miscellaneous

P
png: Miscellaneous

R
reinit-imaxima: Usage