Installation

The recommended and fastest way of running remage is through pre-built software containers. Alternatively, the project can be built from source.

Pre-built container images

Stable releases are regularly made available on Docker Hub. To obtain and run the latest just do:

$ docker run legendexp/remage:latest --help # just prints a help message

If you prefer Apptainer, you can easily generate an image locally:

$ apptainer build remage_latest.sif docker://legendexp/remage:latest
$ apptainer run remage_latest.sif --help

More information is available in Software containers. If containers do not work for you, see the next section to learn how to build and install from source or from conda-forge.

Pre-built packages on conda-forge

Stable releases are made available on conda-forge for Linux and macOS systems. To install the latest version use:

$ conda install conda-forge::remage

Note

The conda-forge provided binaries does not support the ROOT output format, but fully supports LH5/HDF5.

Building from source

In preparation for the actual build, users are required to obtain some dependencies.

Required dependencies

  • CMake 3.14 or higher

  • Geant4 11.2.2 or higher

  • Python3 interpreter

Optional dependencies

  • Geant4 support for:

    • HDF5 object persistency (also needed for LH5)

    • Multithreading

    • GDML geometry description

  • ROOT 6.06 or higher

  • BxDecay0 1.0.10 or higher

  • HDF5 C++ support for LH5 object persistency

Note

Pre-built Docker container images with all necessary dependencies are available on Docker Hub (see Software containers).

Building

The build system is based on CMake.

Important

It is important that you use a unique install prefix for remage. Do not use a location that is controlled by your linux package manager (i.e. /usr). The default value of /usr/local is also dangerous if you install other software into that prefix. Failing to do so might create conflicts with other python packages or might even render your system unusable.

$ git clone https://github.com/legend-exp/remage
$ cd remage
$ mkdir build && cd build
$ cmake -DCMAKE_INSTALL_PREFIX=<unique prefix> ..
$ make install

Tip

When encountering any unexpected issues the first step should always be to remove the build folder and compile from scratch. The second step should be to additionally also remove the install folder and any traces of remage to try the installation on a fresh system.

Setting up Jupyter

To set up a remage-aware Jupyter kernel, you only have to provide the correct kernel.json file to your Jupyter installation.

$ mkdir -p ~/.local/share/jupyter/kernels/remage
$ touch ~/.local/share/jupyter/kernels/remage/kernel.json

Note

If Jupyter is installed inside a virtual environment (or in VSCode your default Python interpreter is inside a virtual environment) then you probably need to add the kernel.json to the share folder of that Jupyter installation instead.

If you have installed remage from a pre-built binary using Apptainer, your kernel file should look something like this (remember to replace /path/to/remage_latest.sif with your actual path):

{
  "argv": [
    "sh",
    "-c",
    "apptainer exec -B $XDG_RUNTIME_DIR:$XDG_RUNTIME_DIR /path/to/remage_latest.sif python -m ipykernel_launcher -f {connection_file}"
  ],
  "display_name": "remage container",
  "language": "python",
  "metadata": {
    "debugger": true
  }
}

Now after refreshing JupyterLab/VSCode you should be able to find the “remage container” kernel in your notebooks!

Warning

Interactive visualization, like the pyg4ometry or Geant4 visualizer, might not work as expected in a notebook.