{"id":22879497,"url":"https://github.com/robert-dodier/maxima-jupyter","last_synced_at":"2025-04-12T23:38:54.674Z","repository":{"id":2404991,"uuid":"41317187","full_name":"robert-dodier/maxima-jupyter","owner":"robert-dodier","description":"A Maxima kernel for Jupyter, based on CL-Jupyter (Common Lisp kernel)","archived":false,"fork":false,"pushed_at":"2025-01-02T21:03:23.000Z","size":4788,"stargazers_count":193,"open_issues_count":20,"forks_count":31,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-12T23:38:51.158Z","etag":null,"topics":["jupyter","maxima","maxima-cas"],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robert-dodier.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-24T17:28:44.000Z","updated_at":"2025-03-28T19:05:05.000Z","dependencies_parsed_at":"2023-01-11T16:09:59.222Z","dependency_job_id":"54b7804c-db36-4faf-b9da-02cbe1888918","html_url":"https://github.com/robert-dodier/maxima-jupyter","commit_stats":{"total_commits":349,"total_committers":15,"mean_commits":"23.266666666666666","dds":0.5386819484240688,"last_synced_commit":"8d851fd69e7bfd0e3d41cbafcff2991e02346988"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robert-dodier%2Fmaxima-jupyter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robert-dodier%2Fmaxima-jupyter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robert-dodier%2Fmaxima-jupyter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robert-dodier%2Fmaxima-jupyter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robert-dodier","download_url":"https://codeload.github.com/robert-dodier/maxima-jupyter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647255,"owners_count":21139081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jupyter","maxima","maxima-cas"],"created_at":"2024-12-13T16:47:43.129Z","updated_at":"2025-04-12T23:38:54.655Z","avatar_url":"https://github.com/robert-dodier.png","language":"Common Lisp","funding_links":[],"categories":["Interfaces to other package managers"],"sub_categories":["Third-party APIs"],"readme":"# Maxima-Jupyter\r\n\r\n[![Binder][mybinder-badge]][mybinder]\r\n\r\nAn enhanced interactive environment for the computer algebra system Maxima,\r\nbased on CL-Jupyter, a Jupyter kernel for Common Lisp, by Frederic Peschanski.\r\nThanks, Frederic! These days Maxima-Jupyter depends heavily on Common-Lisp-Jupyter,\r\nby Tarn Burton. Thanks, Tarn!\r\n\r\nThis file describes the installation and usage of Maxima-Jupyter on a local\r\nmachine, but you can try out Maxima-Jupyter without installing anything by\r\nclicking on the Binder badge above.\r\n\r\n## Examples\r\n\r\n- [MaximaJupyterExample.ipynb][] \u0026mdash; General usage of Maxima from within\r\n  JupyterLab.\r\n\r\n- [MaximaJupyterTalk.ipynb][] \u0026mdash; My notes for a talk given to the Portland\r\n  Python User Group.\r\n\r\n- [Plots.ipynb][] \u0026mdash; Usage of plotting facilities from within JupyterLab.\r\n\r\nThese examples make use of [nbviewer][].\r\nYou can submit a link to your own notebook to tell nbviewer to render it.\r\n\r\n## Installation\r\n\r\nMaxima-Jupyter may be installed on a machine using a local installation, a\r\n[repo2docker][] installation, or via a Docker image.\r\n\r\n## Local Installation\r\n\r\n### Requirements\r\n\r\nTo try Maxima-Jupyter you need :\r\n\r\n - a Maxima executable\r\n\r\n   - built with a Common Lisp implementation which has native threads\r\n\r\n     - SBCL works for sure\r\n\r\n     - Clozure CL works for sure\r\n\r\n     - Other implementations which support the Bordeaux Threads package\r\n       might work. The [Bordeaux Threads project description][] says\r\n       \"Supports all major Common Lisp implementations: SBCL, CCL, Lispworks, \r\n       Allegro, ABCL, ECL, Clisp.\" Aside from SBCL and CCL (i.e. Clozure CL) \r\n       which are known to work, the others in that list are untested with \r\n       maxima-jupyter.\r\n\r\n     - Note also that ECL might theoretically work, since it is supported\r\n       by Bordeaux Threads. However, nobody (neither Maxima-Jupyter \r\n       developers nor users) has been able to get ECL to work,\r\n       therefore you should assume **ECL does not work** with Maxima-Jupyter.\r\n       SBCL and Clozure CL are known to work, try those instead.\r\n\r\n     - Note specifically that GCL is not supported by Bordeaux Threads,\r\n       and therefore **GCL cannot work** with maxima-jupyter.\r\n\r\n   - You might or might not need to build Maxima. (A) If you have available\r\n     a Maxima binary package compiled with a compatible Lisp implementation\r\n     (i.e. SBCL, Clozure CL, Lispworks, etc. as enumerated above)\r\n     **and** ASDF is available to the Lisp runtime when Maxima is executed\r\n     (more on this immediately below), then you do not need to build Maxima.\r\n     (B) Otherwise, you must install a compatible Lisp implementation\r\n     and compile Maxima yourself.\r\n\r\n   - NOTE about how to determine if ASDF is available to the Lisp runtime.\r\n     Execute Maxima, and then, at the Maxima input prompt, enter\r\n     `:lisp (require :asdf)`\r\n     If that returns T or NIL without an error message, then ASDF is\r\n     available. If that causes an error about \"don't know how to require\r\n     ASDF\" or something like that, then ASDF is not available.\r\n\r\n - [Quicklisp][]\r\n\r\n   - When you load Maxima-Jupyter into Maxima for the first time,\r\n     Quicklisp will download some dependencies automatically.\r\n     Good luck.\r\n\r\n - Python 3.2 or above\r\n\r\n - [JupyterLab][]\r\n\r\n - If the build aborts because the file `zmq.h` is missing, you may need to\r\n   install the development files for the high-level C binding for ZeroMQ.\r\n   On debian-based systems, you can satisfy this requirement by installing\r\n   the package `libczmq-dev`.\r\n\r\n### Installing Maxima-Jupyter\r\n\r\n#### Installing Maxima-Jupyter on MS Windows\r\n\r\nHere is one recipe for pulling everything together for MS Windows.\r\nThere are other ways to achieve the same end;\r\nthis is one way which is known to work.\r\n\r\n1. Install Maxima and Gnuplot.\r\n\r\n   My advice is to install Maxima from an executable installer, which also includes Gnuplot.\r\n   Obtain an installer from the [Maxima project download page for Windows][].\r\n\r\n1. Update `Path` to include the folders which contain `maxima.bat` and `gnuplot.exe`.\r\n\r\n   To edit the environment variable `Path`,\r\n   click the \"Start\" button and enter \"environment variables\" in the search box,\r\n   then select \"System Properties\" from the search results.\r\n   Click \"Environment Variables\" in the \"System Properties\" popup window.\r\n   Then select \"Path\" in the list of variables, and click \"Edit...\".\r\n\r\n   I added the following folders to `Path`, in this order:\r\n   ```\r\n   C:\\maxima-5.47.0\\gnuplot\\bin\r\n   C:\\maxima-5.47.0\\bin\r\n   ```\r\n\r\n1. Install `conda`, a package manager for Python.\r\n\r\n   My advice is to install Miniconda, which includes a minimal set of components.\r\n   Follow the instructions on the [Miniconda installation page][].\r\n\r\n1. Install GCC, ZeroMQ, and Jupyter via `conda`.\r\n\r\n   In a command window (`cmd.exe`), execute the following commands:\r\n\r\n   ```\r\n   \u003e conda install --channel conda-forge m2w64-gcc\r\n   \u003e conda install --channel conda-forge m2w64-zeromq\r\n   \u003e conda install --channel conda-forge jupyterlab jupyter_console\r\n   ```\r\n\r\n1. Update `Path` to include the `conda` folders.\r\n\r\n   I added the following folders to `Path`, in this order:\r\n   ```\r\n   C:\\ProgramData\\miniconda3\\Library\\mingw-w64\\bin\r\n   C:\\ProgramData\\miniconda3\\Library\\bin\r\n   C:\\ProgramData\\miniconda3\\Scripts\r\n   C:\\ProgramData\\miniconda3\r\n   ```\r\n\r\n1. Install Quicklisp.\r\n\r\n   Download the [Quicklisp installer][]\r\n   and then execute `(load \"quicklisp.lisp\")` in a Lisp interpreter.\r\n   The simplest way to arrange that is to execute `maxima.bat`\r\n   and then, in your Maxima session, execute\r\n   ```\r\n   (%i1) :lisp (load \"quicklisp.lisp\")\r\n   ```\r\n\r\n1. Obtain Maxima-Jupyter source code.\r\n\r\n   To obtain the Maxima-Jupyter source code,\r\n   navigate to the [Maxima-Jupyter project page][]\r\n   and click the down arrow on the button labeled \"Code\",\r\n   and select \"Download ZIP\".\r\n\r\n   Extract the contents of the zip archive into a suitable folder.\r\n\r\n1. Install Maxima-Jupyter.\r\n\r\n   Assuming that the folder which now contains Maxima-Jupyter is named `path\\to\\maxima-jupyter`,\r\n   open a command window (`cmd.exe`) and execute `maxima.bat`,\r\n\r\n   ```\r\n   \u003e cd path\\to\\maxima-jupyter\r\n   \u003e maxima.bat\r\n   ```\r\n   and then execute the following commands in the Maxima session,\r\n   ```\r\n   (%i1) load (\"load-maxima-jupyter.lisp\");\r\n   (%i2) jupyter_install_image ();\r\n   ```\r\n   which creates an image (binary executable) containing Maxima-Jupyter in addition to Maxima itself.\r\n\r\n1. Launch Jupyter.\r\n\r\n   In a command window (`cmd.exe`), execute the following commands.\r\n   Here `path\\to\\a\\writeable\\folder` is any folder in which you can create files.\r\n\r\n   ```\r\n   \u003e cd path\\to\\a\\writeable\\folder\r\n   \u003e jupyter lab\r\n   ```\r\n\r\n   Jupyter will open a tab in a web browser (MS Edge when I tried it),\r\n   showing icons for any installed kernels (language-specific plugins),\r\n   which should now include Maxima.\r\n\r\n#### Installing Maxima-Jupyter on Unix-like systems\r\n\r\nOn Unix-like systems, Jupyter is installed via `pip` (Python package installer).\r\nIf you plan on using JupyterLab (which provides the notebook interface) then you\r\nmust install with the `--user` option.\r\n\r\n```\r\npython3 -m pip --user install jupyterlab jupyter-console\r\n```\r\n\r\nOnce Jupyter is installed, you can install Maxima-Jupyter.\r\n\r\nYou can install Maxima-Jupyter from the source files of this repository\r\non both Unix-like systems and MS Windows.\r\n\r\nIf you are using Arch Linux, you can install Maxima-Jupyter via the AUR.\r\n\r\n##### Method 1. Source Based Installation\r\n\r\nTo install Maxima-Jupyter from the current source files,\r\nfirst download the source files and then start a shell in the source directory.\r\nThen start Maxima and load the initialization script.\r\n\r\n```sh\r\n$ maxima\r\nMaxima 5.43.0 http://maxima.sourceforge.net\r\nusing Lisp SBCL 1.5.5\r\nDistributed under the GNU Public License. See the file COPYING.\r\nDedicated to the memory of William Schelter.\r\nThe function bug_report() provides bug reporting information.\r\n(%i1) load(\"load-maxima-jupyter.lisp\");\r\n```\r\n\r\nThen install Maxima-Jupyter using *one* of the kernel types.\r\n\r\n1. User-specific installation, with kernel loaded by Quicklisp: `jupyter_install();`\r\n2. User-specific installation, with kernel saved in binary image: `jupyter_install_image();`\r\n3. System-wide installation, with kernel loaded by Quicklisp: `jupyter_system_install(true, \"pkg/\");`\r\n\r\nAfter selecting the kernel type, exit Maxima.\r\nFor the system-wide installation, copy the files in `pkg` to the system root, i.e. \r\n`sudo cp -r pkg/* /` on Linux.\r\n\r\n##### Method 2. Installing Maxima-Jupyter on Arch/Manjaro Linux\r\n\r\nThe package for Arch Linux is [maxima-jupyter-git][]. Building and installing\r\n(including dependencies) can be accomplished with:\r\n\r\n```sh\r\nyaourt -Sy maxima-jupyter-git\r\n```\r\n\r\nAlternatively use ``makepkg``:\r\n\r\n```sh\r\ncurl -L -O https://aur.archlinux.org/cgit/aur.git/snapshot/maxima-jupyter-git.tar.gz\r\ntar -xvf maxima-jupyter-git.tar.gz\r\ncd maxima-jupyter-git\r\nmakepkg -Csri\r\n```\r\n\r\nPlease consult the [Arch Wiki][] for more information regarding installing\r\npackages from the AUR.\r\n\r\n### Code Highlighting Installation\r\n\r\nHighlighting Maxima code is handled by [CodeMirror][] in the notebook\r\nand [Pygments][] in HTML export.\r\n\r\nA [CodeMirror mode for Maxima][] has been published on [npmjs.com][].\r\nIt is not clear how that needs to be installed in order for Maxima-Jupyter to make use of it;\r\nstay tuned for further info.\r\n\r\nA Maxima lexer for Pygments has been submitted and accepted by the Pygments project,\r\nand it will be bundled with the next release of Pygments (2.11).\r\nIn the meantime, we are lacking highlighting in HTML export.\r\n\r\n### Running Maxima-Jupyter\r\n\r\nMaxima-Jupyter may be run from a local installation in console mode by the following.\r\n\r\n```sh\r\njupyter-console --kernel=maxima\r\n```\r\n\r\nNotebook mode is initiated by the following.\r\n\r\n```sh\r\njupyter-lab\r\n```\r\n\r\nWhen you enter stuff to be evaluated, you must include the usual trailing\r\nsemicolon or dollar sign:\r\n\r\n```\r\nIn [1]: 2*21;\r\nOut[1]: 42\r\n\r\nIn [2]:\r\n```\r\n\r\n## repo2docker Usage\r\n\r\nMaxima-Jupyter may be run as a Docker image managed by repo2docker which will\r\nfetch the current code from GitHub and handle all the details of running the\r\nJupyterLab server.\r\n\r\nFirst you need to install repo2docker (`sudo` may be required)\r\n\r\n```sh\r\npip install jupyter-repo2docker\r\n```\r\n\r\nOnce repo2docker is installed then the following will build and start the\r\nserver. Directions on accessing the server will be displayed once the image\r\nis built.\r\n\r\n```sh\r\njupyter-repo2docker --user-id=1000 --user-name=mj https://github.com/robert-dodier/maxima-jupyter\r\n```\r\n\r\n## Docker Image\r\n\r\nA Docker image of Maxima-Jupyter may be built using the following command\r\n(`sudo` may be required). This image is based on the docker image\r\n`archlinux/base`.\r\n\r\n```sh\r\ndocker build --tag=maxima-jupyter .\r\n```\r\nIf you'd like to build with a different user than the default (`mj`), you may\r\noverride it with the following:\r\n\r\n```sh\r\ndocker build --build-arg NB_USER=alice --tag=maxima-jupyter .\r\n```\r\n\r\nAfter the image is built the container may be run with:\r\n\r\n```sh\r\ndocker run -it maxima-jupyter\r\n```\r\n\r\nThe `Dockerfile` makes use of the `ENTRYPOINT` command; the default behaviour\r\nexecutes the `jupyter` binary with the arguments `console --kernel=maxima`. \r\n\r\nIf you'd like to run using Juypter's notebook web server, you may do the\r\nfollowing to override the default use of `console`:\r\n\r\n```sh\r\ndocker run -it \\\r\n    -v `pwd`/notebooks:/home/USER/maxima-jupyter/examples \\\r\n    -p 8888:8888 \\\r\n    maxima-jupyter \\\r\n    notebook --ip=0.0.0.0 --port=8888\r\n```\r\n\r\nwhere the last line is the set of arguments to `jupyter` that cause it to run\r\nin the notebook server mode.\r\n\r\nTo run the Bash shell on the container, just override the entry point:\r\n\r\n```sh\r\ndocker run -it --entrypoint=bash maxima-jupyter\r\n``` \r\n\r\nIf you cannot build the Docker image, you may use a \r\n[pre-built one](https://hub.docker.com/r/calyau/maxima-jupyter)\r\nby subsituting the Docker image name `maxima-jupyter` in the above `docker`\r\ncommands with `calyau/maxima-jupyter`. Note that the default user on the\r\n`calyau` image is not `mj`, but is rather `oubiwann`.\r\n\r\nAdditional examples of notebooks created using this mode have been created\r\nhere (taken from the Maxima tutorial):\r\n[https://github.com/calyau/maxima-tutorial-notebooks](https://github.com/calyau/maxima-tutorial-notebooks).\r\n\r\n----\r\n\r\nHave fun! If you run into problems, please open a ticket on the issue tracker for this project.\r\n\r\n\u003c!--refs--\u003e\r\n\r\n[Arch Wiki]: https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages\r\n[Bordeaux Threads project description]: https://common-lisp.net/project/bordeaux-threads/\r\n[CodeMirror]: https://codemirror.net \r\n[npmjs.com]: https://www.npmjs.com\r\n[CodeMirror mode for Maxima]: https://www.npmjs.com/package/codemirror-mode-maxima\r\n[Pygments]: https://pygments.org\r\n[JupyterLab]: https://jupyter.org/install.html\r\n[Maxima project download page for Windows]: https://sourceforge.net/projects/maxima/files/Maxima-Windows/\r\n[Miniconda installation page]: https://docs.anaconda.com/miniconda/install/\r\n[Quicklisp installer]: https://beta.quicklisp.org/quicklisp.lisp\r\n[Maxima-Jupyter project page]: https://github.com/robert-dodier/maxima-jupyter\r\n[maxima-jupyter-git]: https://aur.archlinux.org/packages/maxima-jupyter-git/\r\n[MaximaJupyterExample.ipynb]: http://nbviewer.jupyter.org/github/robert-dodier/maxima-jupyter/blob/master/examples/MaximaJupyterExample.ipynb\r\n[MaximaJupyterTalk.ipynb]: http://nbviewer.jupyter.org/github/robert-dodier/maxima-jupyter/blob/master/examples/MaximaJupyterTalk.ipynb\r\n[mybinder-badge]: https://mybinder.org/badge_logo.svg\r\n[mybinder]: https://mybinder.org/v2/gh/robert-dodier/maxima-jupyter/master?urlpath=lab\r\n[nbviewer]: http://nbviewer.jupyter.org\r\n[Plots.ipynb]: http://nbviewer.jupyter.org/github/robert-dodier/maxima-jupyter/blob/master/examples/Plots.ipynb\r\n[Quicklisp]: http://www.quicklisp.org\r\n[repo2docker]: https://repo2docker.readthedocs.io/en/latest/\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobert-dodier%2Fmaxima-jupyter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobert-dodier%2Fmaxima-jupyter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobert-dodier%2Fmaxima-jupyter/lists"}