Configuring Jupyter kernels

Legate supports single-node execution of programs using Jupyter Notebooks. Please use the instructions given below to set up IPython kernels that will be used in the notebooks.

Setup

IPython Kernel

Todo

[BD] We might want to give an example of a simple launch with one GPU, and later an example with multi GPU.

Inputs that are passed to the Legate launcher will now be passed to the notebook through IPython kernels. By default, LEGATE_SM_GPU kernel will be available and set to use one GPU.

Todo

[BD] Is it still correct with the new auto config feature in 24.11?

For each set of inputs to legate, a new kernel will have to be created using legate-jupyter and then selected from the drop-down menu for “Select Kernel” from your notebook.

Use the following to list all the installed kernels. By default, LEGATE_SM_GPU should be available.

jupyter kernelspec list

Todo

[BD] we might want to give a GPU example first.

To create a new kernel that corresponds to a particular set of inputs to legate, say, to run on 2 CPUs with 10GB of memory and 10% of memory reserved for eager allocations, run the following:

legate-jupyter --name "legate_cpus_2" --cpus 2 --sysmem 10000 --eager-alloc-percentage 10

jupyter kernelspec list

This should create a new kernel named legate_cpus_2. The installed kernel can then be selected from the notebook to run on two CPUs.

Todo

[BD] we might want to give the example command of selecting a kernel.

You can also see input arguments that were passed to Legate by the kernel by using magic commands from a cell in the notebook (including the % character), like below:

%load_ext legate.info
%legate_info

A sample output from a custom kernel is given below:

Kernel 'legate_cpus_2' configured for 1 node(s)

Cores:
CPUs to use per rank : 2
GPUs to use per rank : 0
OpenMP groups to use per rank : 0
Threads per OpenMP group : 4
Utility processors per rank : 2

Memory:
DRAM memory per rank (in MBs) : 10000
DRAM memory per NUMA domain per rank (in MBs) : 0
Framebuffer memory per GPU (in MBs) : 4000
Zero-copy memory per rank (in MBs) : 32
Registered CPU-side pinned memory per rank (in MBs) : 0

Running on a remote server

If you intend to run the notebook on a remote server or a laptop, you will have to create a tunnel from your localhost to the remote server. Substitute remote-server-hostname with the hostname of the remote server you plan to use,

ssh -4 -t -L 8888:localhost:8002 username@remote-server-hostname ssh -t -L 8002:localhost:8888 remote-server-hostname

and then run on your local machine:

jupyter notebook --port=8888 --no-browser

This should give a URL where the Jupyter server is running and will look like this:

http://localhost:8888/tree?token=<token-id>

Where <token-id> will be different each time you launch jupyter. Launch the URL from your browser and choose the Legate_SM_GPU kernel. This ensures that the underlying computations can be run using the resources specified in the Legate_SM_GPU kernel.

For more information on how this works with the runtime, we refer the readers to respective sections in Legion and Legate documentation.

Running Jupyter Notebooks

You are now set up to run the notebooks using Jupyter with your configured options. Check out the notebooks in the examples section.

Todo

[BD] Does the example come with conda install? If not, we might want to give instructions of how to get the examples.