remage

Simulation framework for low background physics experiments

Monte Carlo simulations are an essential tool for data modeling and experimental design in low-background physics. They typically demand a considerable effort, with each collaboration developing and maintaining its own complex Geant4 application. remage is an open-source framework designed to standardize these simulations and significantly reduce this effort.

Its design separates the experimental geometry, built with dedicated Python tools, from the compiled application. It provides a physics list and event generators tuned to radiogenic and cosmogenic backgrounds, output tailored to the most common detector types, and robust validation backed by modern software development practices. The software is distributed ready to use and scales efficiently with the computing resources that demanding simulations require. remage has been primarily developed for the LEGEND experiment, but is applicable to a wide variety of others.

Get started with our documentation pages!

Quick start

Give it a try, with pixi:

Main features

• Low entry barrier: Most simulations can be executed directly using the remage executable and a macro file, eliminating the need to write or compile C++ code.
• Ready-to-use distribution: conda-forge packages and pre-compiled container images on Docker Hub
• Geometry decoupled from the application: it is supplied as a GDML file, conveniently generated from Python with legend-pygeom-tools
• Support for modern Geant4, including:
  • Multithreading, complemented by a custom multi-process mode for consistent speedups on large machines
  • Multiple output file formats (ROOT, HDF5...)
• LEGEND HDF5 (LH5) primary output format, with wide support in multiple languages (e.g. Julia, Python)
• Physics list tuned for low-background applications, with production cuts and step limits suited to high-precision modeling of HPGe detectors
• Fast third-party cosmic muon generator (through EcoMug)
• Support for external generators, by reading in the files they produce:
  • cosmic muons generated with MUSUN
  • neutron capture gamma cascades computed with MAURINA
• Third-party double-beta decay generator (through bxdecay0)
• Advanced vertex confinement on physical volumes, geometrical solids, surfaces and intersections
• Event vertices and kinematics can also be read from HDF5 files, so that generators can be written in any language (e.g. with revertex)
• Sensible output schemes for HPGe and optical detectors
• Data reduction and speedup mechanisms: step clustering, output filtering and conditional tracking (track staging and suspension)
• Continuously updated validation suite, including end-to-end comparisons with experimental data, run automatically for every change to remage or Geant4
• Automatically generated documentation of all remage macro commands