ihaskell-notebook

A Community Jupyter Docker Stacks image. Provides the Jupyter IHaskell kernel in a Docker image which composes well with other Jupyter Docker Stacks. Docker images are published on the Github container registry.

docker run the latest image right now with the following shell command, then open http://localhost:8888 to try out the Jupyter notebook. Your current working directory on your host computer will be mounted at Home / pwd in JupyterLab.

docker run --rm -p 8888:8888 -v $PWD:/home/jovyan/pwd --name ihaskell_notebook ghcr.io/ihaskell/ihaskell-notebook:master jupyter lab --ServerApp.token=''

Or with podman:

podman run --privileged --userns=keep-id --rm -p 8888:8888 -v $PWD:/home/jovyan/pwd --name ihaskell_notebook ghcr.io/ihaskell/ihaskell-notebook:master jupyter lab --ServerApp.token=''

Image structure

This image includes:

• JupyterLab 3
• IHaskell Jupyter kernel
• jupyterlab-ihaskell JupyterLab extension for Haskell syntax highlighting in notebooks
• Haskell libraries for instances of IHaskell.Display
  • ihaskell-aeson for Aeson JSON display
  • ihaskell-blaze for Blaze HTML display
  • ihaskell-gnuplot for gnuplot graphing utility
  • ihaskell-juicypixels for JuicyPixels image display
  • ihaskell-plot for plots diagrams-based plotting library
  • ihaskell-graphviz for Graphviz graph visualization
  • ihaskell-diagrams for diagrams language for creating vector graphics
  • ihaskell-charts for Chart rendering 2D charts
  • ihaskell-hatex for HaTeX LaTeX
  • ihaskell-widgets for Widgets interactive user-interface controls
  • DougBurke/ihaskell-hvega for Vega/Vega-Lite rendering, natively supported by JupyterLab
• Haskell Stack package manager, with Glasgow Haskell Compiler.

The image is configured with the common features of Jupyter Docker Stacks.

To ensure that this image composes well with any authentication and storage configuration (for example SystemUserSpawner) or notebook directory structure, we try to avoid installing anything in the Docker image in /home/jovyan.

This image is made with JupyterLab in mind, but it works well for classic notebooks.

Example notebooks are collected together in the container at /home/jovyan/ihaskell_examples.

IHaskell.Display

Some libraries for instances of IHaskell.Display are pre-installed in the JupyterLab container.

The installed libraries mostly come from mostly from IHaskell/ihaskell-display, and are installed if they appeared to be working at the time the JupyterLab Docker image was built. You can try to install the other IHaskell/ihaskell-display libraries, and they will be built from the /opt/IHaskell source in the container.

stack build ihaskell-magic

See the Stack global project /opt/stack/global-project/stack.yaml for information about the /opt/IHaskell source in the container.

You can see which libraries are installed by running ghc-pkg:

stack exec ghc-pkg -- list | grep ihaskell
    ihaskell-0.9.1.0
    ihaskell-aeson-0.3.0.1
    ihaskell-blaze-0.3.0.1
    ihaskell-gnuplot-0.1.0.1
    ihaskell-hvega-0.2.0.0
    ihaskell-juicypixels-1.1.0.1
    ...

Stack global project

The ihaskell executable, the ihaskell library, the ghc-parser library, and the ipython-kernel library are built and installed at the level of the Stack global project in /opt/stack/global-project/stack.yaml. This design choice was discussed in IHaskell issue #715.

This means that the ihaskell environment is available for all users in any directory mounted in the Docker container, so you can save and run .ipynb notebook files in any directory, which is one of the main advantage of this IHaskell Docker image. The present working directory (PWD) of a Jupyter notebook is the always the directory in which the notebook is saved.

The Stack global project resolver is determined by the IHaskell project resolver, and all included Haskell libraries are built using that Stack resolver.

Installing Haskell packages

You can install packages with stack build. For example, if you encounter a notebook error for a missing hmatrix package,

<interactive>:1:1: error:
   Could not find module ‘Numeric.LinearAlgebra’
   Use -v to see a list of the files searched for.

then you can install the missing hmatrix package from the terminal in your container:

stack build hmatrix

Or, in a notebook, you can use the GHCi-style shell commands:

:!stack build hmatrix

And then ⭮ restart your IHaskell kernel.

You can use this technique to create a list of package dependencies at the top of a notebook:

:!stack build hmatrix
import Numeric.LinearAlgebra
ident 3

(3><3)
 [ 1.0, 0.0, 0.0
 , 0.0, 1.0, 0.0
 , 0.0, 0.0, 1.0 ]

Installing Haskell packages caveats

1. You can only install packages from the Stackage snapshot from the Stack global project /opt/stack/global-project/stack.yaml resolver.
2. The first time you run the notebook the packages will be installed, but then the kernel will not load them. You must ⭮ restart the kernel to load the newly-installed packages.

Local project modules

You can add supporting modules of .hs files in the same directory where your .ipynb notebook file is stored.

If you create a file MyModule.hs with the contents

module MyModule where
support x = x + x

Then you can use the support function in your .ipynb notebook like this

:load MyModule
import MyModule (support)

System GHC

The GHC version specified by the IHaskell Stack resolver is also installed in the container at the system level, that is, on the executable PATH.

Building and running the Dockerfile locally

make build
make up

Open http://localhost:8888/

Composition with Docker Stacks

Rebase the IHaskell Dockerfile on top of another Jupyter Docker Stack image, for example the scipy-notebook:

docker build --build-arg BASE_CONTAINER=jupyter/scipy-notebook --rm --force-rm -t ihaskell_scipy_notebook:latest .

References, Links, Credits

IHaskell on Hackage

IHaskell on Stackage

IHaskell Wiki with Exemplary IHaskell Notebooks

Learn You a Haskell for Great Good, Jupyter adaptation

When Is Haskell More Useful Than R Or Python In Data Science? by Tikhon Jelvis

datahaskell.org

tweag/jupyterWith Jupyter Nix build