Introduction
GAP Jupyter Kernel This package provides a so-called kernel for the https://jupyter.org interactive document system. This kernel is implemented in &GAP;.
Installation This package requires &Jupyter; to be installed on your system, which on most Python installations can be achieved by issuing the following command. > pip install --user notebook Further instructions can be found at https://jupyter.org/install. This package requires the &GAP; packages &IO;, &uuid;, &ZeroMQInterface;, &crypting;, and &json;, all of which are distributed with &GAP;, and some of which require compilation. To compile &ZeroMQInterface; you need to install &ZeroMQ;, for details please refer to the https://gap-packages.github.io/ZeroMQInterface/doc/chap0.html. &JupyterKernel; itself does not contain any kernel code that needs to be compiled. It is necessary to register &JupyterKernel; with your &Jupyter; installation. Registering the GAP jupyter kernel system-wide works as follows: > pip install . or registering for your user only > pip install . --user If &GAP; is not in your PATH, then you have to set the environment variable JUPYTER_GAP_EXECUTABLE to point to your GAP executable for &Jupyter; to be able to execute &GAP;, and the script jupyter-kernel-gap that is distributed with this package in the directory bin/ needs to be in your path. To start &Jupyter; run: > jupyter notebook Then &JupyterKernel; should show up in your &Jupyter; installation as "GAP 4".
How it works Kernel Startup This section gives a short explanation how the process of executing &GAP; as a kernel by &Jupyter; works to help with debugging issues. &Jupyter; registers kernels using json files in various directories. You can list which kernel specifications are installed by executing the following command > jupyter kernelspec list Available kernels: python2 /usr/local/lib/python2.7/site-packages/ipykernel/resources gap-4 /usr/local/share/jupyter/kernels/gap-4 If there is no line containing the gap-4 kernel, something went wrong with setup.py. You can try to manually install the file kernel.json which is in the etc directory of the &JupyterKernel; package by copying it. Better yet, you should report this issue on the issue tracker giving wich operating system you are using, your version of &Jupyter; and &GAP;, and which commands you tried to execute. What happens when &Jupyter; wants to start a &GAP; kernel is that it tries to execute the small script jupyter-kernel-gap (which is distributed with the &JupyterKernel; package), which in turn executes &GAP;, loading the package and then running the kernel. This script currently has to be in your PATH environment variable, too. Kernel operation The communication between the &Jupyter; frontend and &GAP; happens through ZeroMQ streams as documented http://jupyter-client.readthedocs.io/en/latest/messaging.html, encoded as JSON dicts. After entering code into a cell and instructing &Jupyter; to execute that code, the jupyter frontend sends the code to the &GAP; session where it is executed by using the &GAP; function READ_ALL_COMMANDS, resulting values of the execution are rendered using ViewString and sent back to the &Jupyter; frontend. In principle, rich rendering of content, as exemplified in the function JUPYTER_DotSplash is possible. Tab-completion is handled by the &GAP; function JUPYTER_completion, and inspection is handled by JUPYTER_Inspect. Changing these functions, one can change the behaviour of Tab-completion and inspection to improve user experience.
Code Highlighting and Indentation &JupyterKernel; provides a &GAP; mode with code highlighting and indentation. This mode is installed as a notebook extension and registers 'text/x-gap' as a MIME type.
Known Limitations and Caveats Currently the support of the &GAP; system for alternative frontends is a work in progress. In particular, certain outputs that are printed by &GAP; cannot be captured by the &Jupyter; frontend and will not show up. At current, the output of the function will print output in the terminal, rather than the &Jupyter; notebook it is currently executing in. Some objects are also not , and as such are not working in the current version of &JupyterKernel;. The function does also currently not work in the current version of &JupyterKernel;. The variables last, last2 and last3 (see ) are also unsupported in the current version. If you happen to notice problems of this kind, feel free to report them on the https://github.com/gap-packages/JupyterKernel/issues. or suggest a solution via a pull-request.
Feedback For bug reports, feature requests and suggestions, please use our https://github.com/gap-packages/JupyterKernel/issues.