Installation

Pre-built binaries

The recommended and fastest way of running remage is through pre-built software containers. 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

If containers do not work for you, see the next section to learn how to build and install from source.

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.

Note

Apptainer images can be easily generated with, e.g.:

 $ apptainer build remage-base_latest.sif docker://legendexp/remage-base:latest

For more details, have a look at the documentation.

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

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.