LEGEND Julia Software Stack Tutorial

This tutorial demonstrates the LEGEND Julia software stack: It shows how to simulate an inverted-coaxial HPGe detector, how to generate detector waveforms based on Geant4 MC results, how to reconstruct an energy spectrum from the simulated pulses and how to perform an auto-calibration of the resulting spectrum.

Note: This is a work in progress, more functionality will be added over time. The LEGEND-related software packages used are still under very active development, so types and functions may change without notice. This tutorial will be updated regularly and adapted to API changes.

Required Software

The tutorial is offered in the form of a Jupyter notebook (also as a plain Julia script). So for full functionality, you need both Julia and a way to run Jupyter notebooks.

Using the LEGEND software container image

The easiest way to ensure that all required software is available is to use the LEGEND base software container (see the link for instructions).

When using the container image, you can skip the complete installation section below.

Installing Julia and optionally Jupyter or nteract

Installing Julia

Julia is easy to install:

• Download Julia.

• Extract the archive resp. run the installer.

• You may want to add the Julia "bin" directory to your $PATH"

We recommend using Julia v1.7 or later to run this tutorial.

Optional: Installing Jupyter

If you have a working Jupyter installation, it should detect the Jupyter Julia kernel that will be installed when you instantiate the LEGEND Julia environment (see below).

You can also start Jupyter via Julia: This can either use existing installations of Jupyter and pyplot, or install both internally by creating an internal Conda installation within $HOME/.julia/conda. On Linux, Julia will by default to use the Jupyter installation associated with the jupyter executable on your $PATH. On OS-X and Windows, both IJulia will by default always create a Julia-internal Conda installation (see above). To change this behavior, set the environment variable $JUPYTER. For details, see the IJulia.jldocumentation.

If you use Python packages from Julia (e.g. via PyPlot.jl, UpROOT.jl or directly via PyCall.jl), the same default behavior occurs (the system's Python3 is used on Linux, a Julia-internal Conda environment on OS-X and Windows). To change this, set the $PYTHON environment variable. For details, see the PyCall.jl and PyPlot.jl documentation.

If you want to use a standalone Jupyter/Python installation with Julia, we recommend to install Anaconda.

Optional: Installing nteract

On local systems, you can also install and use the nteract deskop applicaton to run Jupyter notebooks (instead of using a Jupyter server). nteract should detect the Jupyter Julia kernel that will be installed when you instantiate the LEGEND Julia environment (see below).

Environment variables

You may want/need to set the following environment variables:

• $PATH: Include the Julia bin-directory in your binary search path, see above. If you intend to use Jupyter, you will probably want to include the directory containing the jupyter binary to your PATH as well.

• $JULIA_NUM_THREADS: Number of threads to use for Julia multi-threading

• $JULIA_DEPOT_PATH and JULIA_PKG_DEVDIR: If you want Julia to install packages in another location than $HOME/.julia.

See the Julia manual for a description of other Julia-specific environment variables.

Setting up the tutorial and installing the required Julia packages

Download this tutorial via Git and change into the "legend-julia-tutorial" directory:

git clone https://github.com/legend-exp/legend-julia-tutorial.git
cd legend-julia-tutorial

Julia has a very powerful package management system that allows for using different versions of packages for different projects, layered package environments, etc. Run the shell command

julia --project=. -e 'using Pkg; pkg"instantiate; precompile"'

to instantiate the Julia project environment defined by the files "Project.toml" and "Manifest.toml" in the "legend-julia-tutorial" directory.

Optional: To make this environment available generally, independent of your current directory, create a directory "$HOME/user/.julia/environments/legend" and copy both "Project.toml" and "Manifest.toml" into that directory. Afterwards, you'll be able to activate the "legend" environment via activate --shared legend on the Julia package management console (which you can enter by pressing ] in Julia).

Optional: Of course you may also istall the required packages (listed in "Project.toml") into your default julia environment (located in "$HOME/user/.julia/environments/v1.4"), the packages in the default environment are always available in Julia.

The file "legend-julia-software-tutorial.jl" is Julia script with embedded Markdown text sections. The script "make.jl" uses the Julia package Literate.jl to convert this script into a Jupyter notebook "legend-julia-software-tutorial.ipynb" with code and text cells.

Do do so, run

julia --project=. make.jl

You may of course also run the script "legend-julia-software-tutorial.jl" directly. However, plots will constantly be replaced by the next plot and no output will be saved. The Julia script is more useful as a starting point for advanced users who want to start developing their own scripts.

Running the tutorial

The tutorial is offered in several variants (see above).

Note: To activate Julia's multi-threading support, set the environment variable JULIA_NUM_THREADS before starting Julia or Jupyter.

Using the Jupyter tutorial notebook

The Jupyter notebook version of the tutorial is probably the best starting point for most users.

Running Julia in Jupyter requires the IJulia Jupyter Julia kernel. If you do not have added IJulia in your default environment (we recommend that you do), you can add IJulia to the "legend-julia-tutorial" project using

julia --project=. -e 'using Pkg; Pkg.add("IJulia")'

If you do have IJulia in your default environment then don't add it to "legend-julia-tutorial" as well.

If you do not have a Jupyter installation on your $PATH, you may want to start Jupyter via Julia or (on a desktop system) use nteract.

If you do have a Jupyter installation on your $PATH (preferred), you can just usually start a Jupyter notebook server using

jupyter notebook

When using a Jupyter installation on your local system, your web browser will usually be started automatically and be pointed to the Jupyter notebook server instance. However, when using a software container or starting jupyter on a remote system with SSH port forwarding (and in some other cases), Jupyter will complain that it can't start the web browser. In these cases, run

jupyter notebook --no-browser

Jupyter will print the URL to point your web browser too, this URL should include an authorization token (unless you configured Jupyter for password-based access).

Depending on where and how you run Jupyter - especially if you run in a Docker container - you may need to specify a non-standard port number and/or IP address to bind to, or allow Jupyter to run in a root user account. In such cases, additional options will be required, e.g.:

jupyter notebook --no-browser --ip 0.0.0.0 --port 8888 --allow-root

On the Jupyter web page, open the notebook "legend-julia-software-tutorial.ipynb", and on the notebook page, choose "Run all cells" from the menu at the top of the page.

Building a custom Julia LEGEND system image

The LEGEND Julia packages and their dependencies constitute a large code base, using them the first time in a new Julia session takes a while (each time). To reduce this startup latency (due to package loading and code-generation time), you can build a custom Julia system image that includes almost all of the packages used in the LEGEND Julia tutorial via PackageCompiler.jl.

If you do not have added PackageCompiler to your default environment (we recommend that you do), you can add PackageCompiler to the "legend-julia-tutorial" project using

julia --project=. -e 'using Pkg; Pkg.add("PackageCompiler")'

To build the custom Julia LEGEND system image, run

julia --project=. build_sysimage.jl

Afterwards, you can use

julia --project="/path/to/this/legend-julia-tutorial" --sysimage="/path/to/legend-julia-tutorial/JuliaSysimage.so"

to run Julia with the custom system image. Note: The file name of the system image file is OS-dependent: on Linux it is "JuliaSysimage.so", on OS-X it is "JuliaSysimage.dylib", and on Windows it is "JuliaSysimage.dll".

Also note that using a custom Julia system image freezes all included packages and all their transitive dependencies to the package version used when generating the image. While the custom system image is used, none of these Julia packages can be updated. The system image will also only work for your current Julia version.

If you activate the "legend-julia-tutorial" project/environment in the Julia plugin for Visual Studio Code, you may want to enable the "julia.useCustomSysimage" option to use the custom system image automatically.

Learning (more about) Julia

If you're interesting in learning Julia, or just learning more about Julia, the Julia website provides many links to introductory videos and written tutorials, e.g. "Intro to Julia", "A Deep Introduction to Julia for Data Science and Scientific Computing" and "The Fast Track to Julia 1.0"

The in-depth article Why Numba and Cython are not substitutes for Julia explains how Julia addresses several fundamental challenges inherent to scientific computing.