<p>This package provides a so-called <em>kernel</em> for the <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> interactive document system. This kernel is implemented in <strong class="pkg">GAP</strong>.</p>
<p>This package requires <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> to be installed on your system, which on most Python installations can be achieved by issuing the following command.</p>
<p>Further instructions can be found at <span class="URL"><a href="https://jupyter.org/install">https://jupyter.org/install</a></span>. This package requires the <strong class="pkg">GAP</strong> packages <strong class="pkg">IO</strong>, <strong class="pkg">uuid</strong>, <strong class="pkg">ZeroMQInterface</strong>, <strong class="pkg">crypting</strong>, and <strong class="pkg">json</strong>, all of which are distributed with <strong class="pkg">GAP</strong>, and some of which require compilation. To compile <strong class="pkg">ZeroMQInterface</strong> you need to install <span class="URL"><a href="https://zeromq.org">ZeroMQ</a></span>, for details please refer to the <span class="URL"><a href="https://gap-packages.github.io/ZeroMQInterface/doc/chap0.html">ZeroMQInterface manual</a></span>. <strong class="pkg">JupyterKernel</strong> itself does not contain any kernel code that needs to be compiled. It is necessary to register <strong class="pkg">JupyterKernel</strong> with your <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> installation. Registering the GAP jupyter kernel system-wide works as follows:</p>
<p>If <strong class="pkg">GAP</strong> is not in your PATH, then you have to set the environment variable <code class="code">JUPYTER_GAP_EXECUTABLE</code> to point to your GAP executable for <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> to be able to execute <strong class="pkg">GAP</strong>, and the script <code class="code">jupyter-kernel-gap</code> that is distributed with this package in the directory <code class="code">bin/</code> needs to be in your path. To start <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> run:</p>
<p>Then <strong class="pkg">JupyterKernel</strong> should show up in your <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> installation as "GAP 4".</p>
<p>This section gives a short explanation how the process of executing <strong class="pkg">GAP</strong> as a kernel by <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> works to help with debugging issues. <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> registers kernels using json files in various directories. You can list which kernel specifications are installed by executing the following command</p>
<div class="example"><pre>
> jupyter kernelspec list
Available kernels:
python2 /usr/local/lib/python2.7/site-packages/ipykernel/resources
gap-4 /usr/local/share/jupyter/kernels/gap-4
</pre></div>
<p>If there is no line containing the <code class="code">gap-4</code> kernel, something went wrong with <code class="code">setup.py</code>. You can try to manually install the file <code class="code">kernel.json</code> which is in the <code class="code">etc</code> directory of the <strong class="pkg">JupyterKernel</strong> 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 <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> and <strong class="pkg">GAP</strong>, and which commands you tried to execute. What happens when <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> wants to start a <strong class="pkg">GAP</strong> kernel is that it tries to execute the smallscript <code class="code">jupyter-kernel-gap</code> (which is distributed with the <strong class="pkg">JupyterKernel</strong> package), which in turn executes <strong class="pkg">GAP</strong>, loading the package and then running the kernel. This script currently has to be in your <code class="code">PATH</code> environment variable, too.</p>
<p>The communication between the <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> frontend and <strong class="pkg">GAP</strong> happens through ZeroMQ streams as documented <span class="URL"><a href="https://jupyter-client.readthedocs.io/en/latest/messaging.html">here</a></span>, encoded as <code class="code">JSON</code> dicts. After entering code into a cell and instructing <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> to execute that code, the jupyter frontend sends the code to the <strong class="pkg">GAP</strong> session where it is executed by using the <strong class="pkg">GAP</strong> function <code class="code">READ_ALL_COMMANDS</code>, resulting values of the execution are rendered using <code class="code">ViewString</code> and sent back to the <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> frontend. In principle, rich rendering of content, as exemplified in the function <code class="code">JUPYTER_DotSplash</code> is possible. Tab-completion is handled by the <strong class="pkg">GAP</strong> function <code class="code">JUPYTER_completion</code>, and inspection is handled by <code class="code">JUPYTER_Inspect</code>. Changing these functions, one can change the behaviour of Tab-completion and inspection to improve user experience.</p>
<h4>1.4 <span class="Heading">Code Highlighting and Indentation</span></h4>
<p><strong class="pkg">JupyterKernel</strong> provides a <strong class="pkg">GAP</strong> mode with code highlighting and indentation. This mode is installed as a notebook extension and registers 'text/x-gap' as a MIME type.</p>
<h4>1.5 <span class="Heading">Known Limitations and Caveats</span></h4>
<p>Currently the support of the <strong class="pkg">GAP</strong> system for alternative frontends is a work in progress. In particular, certain outputs that are printed by <strong class="pkg">GAP</strong> cannot be captured by the <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> frontend and will not show up. At current, the output of the function <code class="func">Exec</code> (<a href="../../../doc/ref/chap11_mj.html#X81402C91833986FC"><span class="RefLink">Reference: Exec</span></a>) will print output in the terminal, rather than the <span class="URL"><a href="https://jupyter.org">Jupyter</a></span> notebook it is currently executing in. Some objects are also not <code class="func">JupyterRenderable</code> (<a href="chap3.html#X7D00BEBE827BDDC4"><span class="RefLink">3.1-3</span></a>), and as such are not working in the current version of <strong class="pkg">JupyterKernel</strong>. The function <code class="func">LogTo</code> (<a href="../../../doc/ref/chap9_mj.html#X79813A6686894960"><span class="RefLink">Reference: LogTo</span></a>) does also currently not work in the current version of <strong class="pkg">JupyterKernel</strong>. The variables <code class="code">last</code>, <code class="code">last2</code> and <code class="code">last3</code> (see <a href="../../../doc/ref/chap6_mj.html#X81667F568237B232"><span class="RefLink">Reference: Main Loop</span></a>) are also unsupported in the current version. If you happen to notice problems of this kind, feel free to report them on the <span class="URL"><a href="https://github.com/gap-packages/JupyterKernel/issues">issue tracker</a></span>. or suggest a solution via a pull-request.</p>
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
