GAP (JupyterKernel) - Chapter 1: Introduction

Goto Chapter: Top 1 2 3 4 Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

1 Introduction
1.1 GAP Jupyter Kernel
1.2 Installation
1.3 How it works
1.3-1 Kernel Startup
1.3-2 Kernel operation
1.4 Code Highlighting and Indentation
1.5 Known Limitations and Caveats
1.6 Feedback

### 1 Introduction

#### 1.1 GAP Jupyter Kernel

This package provides a so-called kernel for the Jupyter interactive document system. This kernel is implemented in GAP.

#### 1.2 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 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".

#### 1.3 How it works

##### 1.3-1 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.

##### 1.3-2 Kernel operation

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.

#### 1.4 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.

#### 1.5 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 `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.

#### 1.6 Feedback

For bug reports, feature requests and suggestions, please use our issue tracker.

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 Ind

generated by GAPDoc2HTML