A Maxima kernel for Jupyter, based on CL-Jupyter (Common Lisp kernel)
Switch branches/tags
Nothing to show
Clone or download

Readme.md

Maxima-Jupyter

An enhanced interactive environment for the computer algebra system Maxima, based on CL-Jupyter, a Jupyter kernel for Common Lisp, by Frederic Peschanski. Thanks, Frederic!

Requirements

To try Maxima-Jupyter you need :

  • a Maxima executable

    • built with a Common Lisp implementation which has native threads

      • Clozure CL works for sure; SBCL should work (incompletely tested)

      • Other implementations which support the Bordeaux Threads package might work. The Bordeaux Threads project description says "Supports all major Common Lisp implementations: SBCL, CCL, Lispworks, Allegro, ABCL, ECL, Clisp." Aside from SBCL and CCL (i.e. Clozure CL) which are known to work, the others in that list are untested with maxima-jupyter.

      • Note specifically that GCL is not supported by Bordeaux Threads, and therefore cannot work with maxima-jupyter.

    • You might or might not need to build Maxima. (A) If you have available a Maxima binary package compiled with a compatible Lisp implementation (i.e. SBCL, Clozure CL, Lispworks, etc. as enumerated above), then you do not need to build Maxima. (B) Otherwise, you must install a compatible Lisp implementation and compile Maxima yourself.

  • Quicklisp

    • When you load Maxima-Jupyter into Maxima for the first time, Quicklisp will download some dependencies automatically. Good luck.
  • Python 3.2 or above

  • Jupyter, or IPython 3.x

  • If the build aborts because the file zmq.h is missing, you may need to install the development files for the high-level C binding for ZeroMQ. On debian-based systems, you can satisfy this requirement by installing the package libczmq-dev.

Quick Install

I installed Jupyter via:

 python3 -m pip install jupyter

There are two kernel installation techniques. The first is to create a saved image as detailed in make-maxima-jupyter-recipe.txt. Once this image has been created then the installation script can be used with:

python3 ./install-maxima-jupyter.py --exec=path/to/maxima-jupyter

Adding the option --user will install a user kernel instead of a system kernel.

The second installation method will run the kernel from an interactive Maxima session. The advantange to this technique is that the normal initialization behavior of Maxima, such as loading maxima-init.mac from the current directory will be preserved. After the files in src have been copied to an appropriate location such as /usr/share/maxima-jupyter for a system installation or ~/maxima-jupyter for a user installation then the installation script called:

python3 ./install-maxima-jupyter.py --root=/path/to/maxima-jupyter-src

The option --maxima may also be used to specify the location of the Maxima executable. Please note that in order for this method to work quicklisp needs be loaded by default in every Maxima session. See quicklisp documentation for details.

Installation on Arch/Manjaro

The package for Arch Linux is maxima-jupyter-git. Building and installing (including dependencies) can be accomplished with:

yaourt -Sy maxima-jupyter-git

Alternatively use makepkg:

curl -L -O https://aur.archlinux.org/cgit/aur.git/snapshot/maxima-jupyter-git.tar.gz
tar -xvf maxima-jupyter-git.tar.gz
cd maxima-jupyter-git
makepkg -Csri

Please consult the Arch Wiki for more information regarding installing packages from the AUR.

Code Highlighting Installation

Highlighting Maxima code is handled by CodeMirror in the notebook and Pygments in HTML export.

The CodeMirror mode for Maxima is maxima.js. To install it, find the CodeMirror mode installation directory, create a directory named maxima there, copy maxima.js to the maxima directory, and update codemirror/mode/meta.js as shown in codemirror-mode-meta-patch. Yes, this is pretty painful, sorry about that.

The Pygments lexer for Maxima is maxima_lexer.py. To install it, find the Pygments installation directory, copy maxima_lexer.py to that directory, and update lexers/_mapping.py as shown in pygments-mapping-patch. Yes, this is pretty painful too.

Running Maxima-Jupyter

Console mode

jupyter console --kernel=maxima

When you enter stuff to be evaluated, you must include the usual trailing semicolon or dollar sign:

In [1]: 2*21;
Out[1]: 42

In [2]:

Notebook mode

jupyter notebook

Notebook Examples

Note that the Github notebook renderer is currently (August 2015) broken (bug report); it renders all math formulas in a tiny font.


Have fun and keep me posted. Feel free to send pull requests, comments, etc.

Robert Dodier robert.dodier@gmail.com robert-dodier @ github