====== Using polymake with jupyter ======
===== Prerequisites =====
To use polymake with jupyter it is necessary to have jupyter installed. jupyter is provided via the package manager in many linux distributions.
  - Ubuntu: ''sudo apt-get install python3-notebook jupyter jupyter-core''
  - Fedora: ''sudo dnf install python3-jupyter-core''

Furthermore you need an **installed** version of polymake. This means that you need to run
<code>
ninja -C build/Opt install
</code>
if working with the polymake source. Then please use the polymake binary from the folder you installed polymake in.

If you use a version of polymake installed via your package manager, make sure you have the ''polymake-config'' binary. Try running
<code>
polymake-config --version
</code>
in a terminal. For example for Ubuntu it is not enough to have the ''polymake'' package installed, you will also need ''libpolymake-dev''.

===== Setup =====
polymake comes with a convenience script to start jupyter with a polymake kernel. You can call it in the following way:
<code>
polymake --script jupyter
</code>
The script will then ask you whether you want to install a polymake kernel with jupyter, if none is available. Furthermore it will provide you with the url to access jupyter in your browser. It will also prompt you whether it should open the browser for you. The full output may look similar to
<code>
This function installs the jupyter-polymake kernel
and the python libpolymake interface JuPyMake for the
current user (into ~/.local).
You need to have a running version of the jupyter
notebook for python3 installed.

Are you sure you want to continue with the installation? [y/N] 
y
Installation complete.
Do you want to start a jupyter notebook now? [y/N]
y
[I 12:35:04.597 NotebookApp] Serving notebooks from local directory: /home/lars/repos/cellularSheaves/demo
[I 12:35:04.598 NotebookApp] The Jupyter Notebook is running at:
[I 12:35:04.598 NotebookApp] http://localhost:8888/?token=603b26582273404c145c39657d4262f87e9656913a4e323f
[I 12:35:04.598 NotebookApp]  or http://127.0.0.1:8888/?token=603b26582273404c145c39657d4262f87e9656913a4e323f
[I 12:35:04.598 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 12:35:04.653 NotebookApp] 
    
    To access the notebook, open this file in a browser:
        file:///home/lars/.local/share/jupyter/runtime/nbserver-3961845-open.html
    Or copy and paste one of these URLs:
        http://localhost:8888/?token=603b26582273404c145c39657d4262f87e9656913a4e323f
     or http://127.0.0.1:8888/?token=603b26582273404c145c39657d4262f87e9656913a4e323f
</code>
Afterwards you will see debug output from jupyter in terminal. You can access jupyter by copying the url from the output into your browser. In many instances it will just automatically open in the browser. Not that you can only access files in the folder that you started jupyter in and its subfolders, but not above.

Sometimes an old jupyter kernel might be broken, then it is necessary to force the polymake command to install a new kernel, in the following way:
<code>
polymake --script jupyter --force
</code>

===== Usage =====
The usage of the jupyter interface is independent of polymake, so we point you to the [[https://jupyter.org/|jupyter documentation]].

In the code blocks you may use polymake just like in the polymake shell.


===== Troubleshooting =====
If the polymake kernel does not start for you, look at the output of jupyter in the terminal and search for any error messages.

If you experience issues it makes sense to try a different browser.

==== JuPyMake.PolymakeError: polymake::Main - /usr/lib/polymake/shared is not a symlink ====
This error sometimes appears with polymake installed by the package manager. It can be fixed by manually setting the symlink
<code>
cd /usr/lib/polymake
sudo ln -s ../../share/polymake shared
</code>


==== polymake configuration ====
The default configuration used by the jupyter kernel is the one in ''$HOME/.polymake''. If you need to reconfigure a rules file, it is easiest to reconfigure it outside of jupyter. Note that the configuration is only saved to ''$HOME/.polymake'' once polymake gets closed using ''exit;''.

Advance users can use a different configuration folder in the following way:
<code>
alias jupymake="env POLYMAKE_USER_DIR=$HOME/.polymake-jupyter jupyter notebook --notebook-dir=$HOME/jupyter-notebooks"
</code>

==== polymake kernel does not start ====
If the polymake kernel will not start, but used to start, then please force the installation of a new kernel at startup, with
<code>
polymake --script jupyter --force
</code>

==== Switching applications ====
If you change the polymake application in your code, then put the command for this in a separate code block in your jupyter notebook.