DEPRECATED (prototype)
Instead:
Release: https://github.com/fricas/jfricas
PyPI: https://pypi.org/project/jfricas/
Docs: https://jfricas.readthedocs.io/en/latest/
This Jupyter kernel for FriCAS is (hopefully) the final one of a series of attempts to provide a stable and easy maintainable application. The concept is rather simple, compared to the former kernels based on CL/ZeroMQ or pexpect:
|------------------| |---------------| | webSPAD (WS) |<---|kernel.json|--->|requests (Py) | | Hunchentoot (HT) | |fricaskernel.py| | FriCAS (BOOT) | |Jupyter/IPython|<--->|Browser | | Common Lisp (CL) | |Python3 | |Notebook | |------------------| |---------------| |QtConsole|
Hunchentoot is a (well-known) webserver for Common Lisp while webSPAD
is a program (also in CL) providing the interface between FriCAS and
Hunchentoot. In other words, FriCAS acts like a webserver responding to GET and
POST requests. On the Python side these GET and POST requests are handled by the
requests library inside the wrapper kernel fricaskernel.py. To put it
in a nutshell, our new kernel essentially comprises three files which we have
to install:
Kernel spec: kernel.json Wrapper Kernel: fricaskernel.py Web service: webspad.lisp
The whole trick is to put these files into the right places.
INSTALLATION INSTRUCTIONS
- Prerequisites
- Installation using pip3
- Manual installation
- Virtual environments
- Running the notebook
- Attaching a console
- Hyperdoc, Graphics, X11
- Uninstall
Appendix
The full documentation is in jfricas_docs.
The only supported OS at the moment is GNU/Linux - Debian/Ubuntu.
For some other OS a docker image will be provided (soon).
We require a version of FriCAS which was compiled with a Common Lisp that supports multithreading and Hunchentoot. We recommend SBCL 1.4.5 or later.
Since Python 2.7 will not be maintained past 2020, we will concentrate on Python3 (https://pythonclock.org/) only. We recommend Python 3.6 or later. For instance:
$ sudo apt update $ sudo apt install python3.6
Pip3 is also required (recommended version 9.0.1 or later):
$ sudo apt install python3-pip
In order to load Common Lisp programs we require ASDF (v3.3 or later):
$ sudo apt install cl-asdf
The Hunchentoot webserver (v1.2.35 or later) will be installed by:
$ sudo apt install cl-hunchentoot
It is hardly worth to mention, a web-browser is required as well. We strongly recommend the latest Firefox.
Regardless of whether you will use a virtual environment venv, this method should work as follows (assuming the prerequisites are satisfied):
Install Jupyter and jfricas from PyPI by
$ pip3 install jupyter $ pip3 install jfricas $ python3 -m jfricas.install_kernel
The requests library and the kernel.json file will be installed
automatically by jfricas.
$ pip3 install jupyter $ git clone https://github.com/fricas/jfricas.git $ cd jfricas $ pip3 install . $ python3 -m jfricas.install_kernel
or, install directly from the git repository branch:
$ pip3 install jupyter $ pip3 install -e git+https://github.com/fricas/jfricas.git@master#egg=jfricas $ python3 -m jfricas.install_kernel
We recall that on Debian/Ubuntu pip3 will install packages locally, that is
the default is --user. Thus, the method which we are going to describe here
is to install into $HOME/.local/... folders.
First, we have to install jupyter and requests:
$ pip3 install jupyter $ pip3 install requests
Second, you will have to get the Git repository (assuming 'git' is installed):
$ git clone https://github.com/fricas/jfricas.git
Then cd to it:
$ cd ./jfricas
and perform the following bash commands:
$ jupyter kernelspec install ./jfricas/kspec --name='jfricas' --user $ jupyter kernelspec list ### you should see 'jfricas' now. # Search for the Python3 user site $ PYUSRSITE=$(python3 -m site --user-site) # Copy kernel and webspad $ mkdir -p -v $PYUSRSITE/jfricas $ cp -v ./jfricas/fricaskernel.py $PYUSRSITE/jfricas $ cp -v ./jfricas/webspad.lisp $PYUSRSITE/jfricas
That is all.
The above commands (except the jupyter installation) are more or less
the content of the install.sh file in the root directory of the Git
repository (./install.sh from within the Git repo).
The venv module provides support for creating lightweight virtual environments with their own site directories, optionally isolated from system site directories. Each virtual environment has its own Python binary (which matches the version of the binary that was used to create this environment) and can have its own independent set of installed Python packages in its site directories.
The pip3 install supports venv:
Example: sudo apt-get install python3-venv cd /tmp python3 -m venv jfenv source jfenv/bin/activate which pip3 /tmp/jfenv/bin/pip3 pip3 install ...
To start the notebook, type (anywhere):
$ jupyter notebook
A browser window should open where you can choose NEW->FriCAS, then
after a while (first time some Lisp programs will be compiled, do not
worry) you may enter for instance: )version, followed by Shift-RETURN.
To leave the notebook you can enter (save it before!)
)quit
as usual, or choose (preferred)
Close and Halt
from the menu. After that (one or the other) the TAB can be closed.
To quit completely (leaving jupyter), press the Quit button on the
main Jupyter window.
During a notebook session, a console can be attached to the running kernel by the command
$ jupyter qtconsole --existing
Of course, instead of a notebook at all, one may use consoles with the kernel:
$ jupyter qtconsole --kernel=jfricas (or 'console' for the ordinary one, instead of 'qtconsole').
The QT console also requires:
PyQt4 >= 4.7, PyQt5, PySide >= 1.0.3 or PySide2.
Note that this is not the same as the usual start console in FriCAS,
because all traffic will go through the kernel. If you want to have a
real console in parallel to Jupyter, you can configure this in the kernel
sources (attaching xterm or a gnome-terminal).
For details we refer to the section kernel configuration in the main
documentation jfricas_docs.
The X11 programs hyperdoc and graphics (draw) will work as usual, however,
the hyperdoc pop-up window has been disabled by default (-noht). It is
possible to operate the web service without X at all. For details we refer
to the section kernel configuration in the main documentation jfricas_docs.
Depending on which method you have installed the kernel it can be completely removed easily either by
$ pip3 uninstall jfricas $ jupyter kernelspec remove jfricas
or by using the bash script uninstall.sh:
$ ./uninstall.sh
The commands may also be performed by hand:
# Remove kernel jupyter kernelspec remove jfricas jupyter kernelspec list # Search for Python user site PYUSRSITE=$(python3 -m site --user-site) # Remove kernel and webspad rm -v $PYUSRSITE/jfricas/fricaskernel.py rm -v $PYUSRSITE/jfricas/webspad.lisp rmdir -v --ignore-fail-on-non-empty $PYUSRSITE/jfricas
The following sequence of commands show how to check the presence and (if) the versions of the required programs:
echo ")version" | fricas -nosman
Value = "FriCAS 1.3.5 compiled at Sun Feb 3 18:21:59 UTC 2019"
echo ")lisp (lisp-implementation-type)" | fricas -nosman
Value = "SBCL", required: SBCL
echo ")lisp (lisp-implementation-version)" | fricas -nosman
Value = "1.4.5.debian", required: >= 1.2.6
python3 --version
Python 3.6.8, required: >= 3.3,
pip3 --version
pip 9.0.1 from /usr/lib/python3/dist-packages (python 3.6))
pip3 show requests
Name: requests
Version: 2.22.0
Summary: Python HTTP for Humans.
Home-page: http://python-requests.org
Install: pip3 install requests
pip3 freeze (should show something like ...
ipykernel==4.8.2
ipython==6.4.0
ipython-genutils==0.2.0
ipywidgets==7.2.1
jsonschema==2.6.0
jupyter==1.0.0
jupyter-client==5.2.3
jupyter-console==5.2.0
jupyter-core==4.4.0
...
otherwise install jupyter with:
pip3 install jupyter
jupyter --version
4.4.0
apt list cl-asdf
cl-asdf/bionic,bionic,now 2:3.3.1-1 all [installed,automatic]
apt list cl-hunchentoot
cl-hunchentoot/bionic,bionic,now 1.2.35-1 all [installed]
cat /etc/os-release
NAME="Ubuntu"
VERSION="18.04.2 LTS (Bionic Beaver)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 18.04.2 LTS"
VERSION_ID="18.04"
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
VERSION_CODENAME=bionic
UBUNTU_CODENAME=bionic
| App / Versions, OS | Min. ver. | Tested | OS/inst |
|---|---|---|---|
| FriCAS | 1.3.2 | 1.3.5 | Deb/Ub (make) |
| Python3 | 3.5 | 3.6 | Deb/Ub (apt) |
| Pip3 | 9.0 | 9.0.1 | apt |
| Jupyter | 4.4 | 4.4 | pip3 |
| Requests | 2.22.0 | 2.22.0 | pip3 |
| cl-asdf | 3.3 | 3.3.1 | Deb/Ub (apt) |
| cl-hunchentoot | 1.2.35 | 1.2.35 | Deb/Ub (apt) |
If jupyter is already in use and
$ jupyter kernelspec list
shows ifricas as available kernel, then you have to remove it by
$ jupyter kernelspec remove ifricas
because it has been registered with the same kernel name: FriCAS. Alternatively you may edit kernel.json of jfricas to use another name instead.
*) ifricas was the name of the old LISP based kernel.
Do not use )quit in consoles if you do not want to terminate the kernel.
Use <menu>/Quit instead (this will close the terminal window only).
| Authors: | Ralf Hemmecke, Kurt Pagani (and sundry other good-natured folks) |
|---|---|
| Version: | 0.2.17 of 2019/09/17 |