Start using Xeus-Cling

Requirements¶

• Linux OS (tested on Ubuntu 20.04).
• Linux build essentials (e.g. sudo apt-get installbuild-essential on Ubuntu).
• realpath (e.g. sudo apt-get install realpath on Ubuntu).
• CMake 3.12 or higher.
• CUDA CUDA >= 8.0 and <= 10.2 if you need CUDA kernels (-g option).
• Docker if you want to build/run the Docker images/containers.

Build the entire software stack¶

To build and install the entire software stack for running Jupyter with Xeus-Cling kernel from the source, you can use make-xeus-cling-jupyter.sh bash script:

$ git clone git@github.com:arminms/xeus-cling-jupyter.git
$ cd xeus-cling-jupyter
$ ./make-xeus-cling-jupyter.sh --help

Usage: ./make-xeus-cling-jupyter.sh [OPTION]... [DIRECTORY(=~/xeus-cling(-env))]

Build and install xeus-cling 0.15.3 from source in DIRECTORY, optionally with a python virtual environment or as a Docker image.
Needs CMake 3.12+ and 'realpath' to work (e.g. 'sudo apt-get install realpath').

  -b  FOLDER    build directory (default: ./build)
  -c            clean the build directory after installation
  -d            build xeus-cling-jupyter Docker image (requires Docker)
  -g            install xeus-cling CUDA-enabled kernels for NVIDIA GPUs
  -k            install kernels to the current user's kernel registry
  -n  N         number of threads to build cling (default: 2)
  -h            show this help message
  -r            resume the build from the last step
  -s            skip creating python virtual environment
  -x            install extra libraries (xproperty, xwidgets, xtensor)

For instance, to build and install in a virtual environment named xeus-cling-env in your home directory (~) with extra libraries (-x) using 4 concurrent threads, you can use the following command:

./make-xeus-cling-jupyter.sh -xn 4 ~/xeus-cling-env

Building Docker images¶

To build the image using Docker simply run the script with the -d option:

./make-xeus-cling-jupyter.sh -d

Or -gd for CUDA support:

./make-xeus-cling-jupyter.sh -gd

Launching pre-built container images¶

Docker¶

Use the following command to launch the pre-built container image:

docker run -p 8888:8888 -it --rm asobhani/xeus-cling-jupyter

Or this one with CUDA support:

docker run --gpus=all -p 8888:8888 -it --rm asobhani/xeus-cling-jupyter:latest-cuda

You can also use the above container images as the starting point for your custom-made docker image (e.g. FROM asobhani/xeus-cling-jupyter:latest).

Apptainer¶

If you’re working on an HPC cluster, you can use Apptainer instead:

apptainer run docker://asobhani/xeus-cling-jupyter:latest

Or this one with CUDA support:

apptainer --nv run docker://asobhani/xeus-cling-jupyter:latest-cuda