Installation

The recommended and fastest way of running remage is through the pre-built packages on conda-forge; alternatively through our pre-built software container images. Alternatively, the project can be built from source.

Pre-built packages on conda-forge

Stable releases are made available on conda-forge for Linux and macOS systems. To install the latest version of remage into your environment, use pixi or conda:

$ pixi add remage
# or
$ conda install conda-forge::remage

Note

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

  • Make sure that you don’t have the anacoda channels enabled in your conda environment, otherwise incompatibilities can arise with the conda-forge repo (see upstream docs). You can directly create an environment with only the conda-forge channel enabled:

    $ conda create -n remage-env --channel conda-forge --override-channels python=3.13
$ conda activate remage-env
$ conda config --env --add channels conda-forge
$ conda config --env --remove channels defaults
$ conda config --env --set channel_priority strict
$ conda install remage

  • To install remage on an arm64 Mac, you need to perform special set-up steps at environment creation time:

    $ CONDA_SUBDIR=osx-64 conda create [...]
$ conda activate remage-env
$ conda config --env --set subdir osx-64
$ # ... continue with the additional steps above

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.

Building from source

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

Required dependencies

  • CMake 3.28 or higher

  • Geant4 11.2.2 or higher, recommended 11.3

  • 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 with a container

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.