This package provides a so-called kernel for the Jupyter interactive document system. This kernel is implemented in GAP.
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 ZeroMQInterface manual. 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".
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.
The communication between the Jupyter frontend and GAP happens through ZeroMQ streams as documented here, 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.
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.
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 Exec (Reference: Exec) will print output in the terminal, rather than the Jupyter notebook it is currently executing in. Some objects are also not JupyterRenderable (3.1-3), and as such are not working in the current version of JupyterKernel. The function LogTo (Reference: LogTo) does also currently not work in the current version of JupyterKernel. The variables last, last2 and last3 (see Reference: Main Loop) are also unsupported in the current version. If you happen to notice problems of this kind, feel free to report them on the issue tracker. or suggest a solution via a pull-request.
For bug reports, feature requests and suggestions, please use our issue tracker.
generated by GAPDoc2HTML