FastGArSim

A Geant4-based simulation, reconstruction and analysis framework for a high-pressure gaseous argon detector, targeting neutrino interaction studies.

The detector is a cylindrical high-pressure gaseous argon TPC in a magnetic field, surrounded by an electromagnetic calorimeter with separate barrel and endcap regions and a muon identification system. Geometry, physics models and event generation are all configurable at run time through macro commands.

Modules

Stage	Package	Produces
1. Detector simulation	detector_simulation/	Events and Geometry trees, optionally convert to flat ntuples with EventToNtupleConverter
2. Reconstruction	reconstruction/	RecoTree
3. Analysis	analysis/	Whatever your macro writes

The classes written to and read from these files are defined once, in common/include/, so that all three packages agree on them.

Repository structure

FastGArSim/
├── CMakeLists.txt              # Top-level build, selects the sub-packages
├── setup_fnal.sh               # Environment setup for the FNAL machines
├── cmake/                      # Shared CMake settings, helpers and templates
├── common/                     # Data types shared by every package
│   └── include/
│       ├── SimDataTypes.hh     # Simulation output types
│       └── DigiDataTypes.hh    # Digitization types
├── detector_simulation/        # Geant4 simulation
│   ├── src/, include/          # Sources and headers
│   ├── macros/                 # Run and configuration macros
│   ├── utils/                  # Ntuple converter, geometry viewer
│   └── jobs/                   # Grid job submission tools
├── reconstruction/             # Modular reconstruction framework
│   ├── src/, include/          # Modules and framework
│   ├── macros/                 # Module configuration macros
│   └── utils/                  # Macros for reco output
└── analysis/                   # Compiled analysis framework
    ├── src/, include/          # Event readers, event loop, plotting, and utils
    └── macros/                 # Analyses built on the framework

Requirements

• ROOT 6
• Geant4 11 (10.7 or later works), for the simulation only
• CMake >= 3.16
• A C++17 compiler

The reconstruction and analysis packages need only ROOT, so they build on a machine without Geant4.

Building

Everything, in one go:

mkdir build && cd build
cmake ..
make -j4

Selecting what to build

List the sub-packages you want. Names are sim, reco, analysis and all:

cmake -DCOMPONENTS="reco,analysis" ..   # skip the Geant4 simulation
cmake -DCOMPONENTS="sim" ..             # simulation only

Or switch them off one at a time:

cmake -DBUILD_SIMULATION=OFF ..

Option	Default	Effect
COMPONENTS	(empty)	Comma-separated list of sub-packages; overrides the BUILD_* options
BUILD_SIMULATION	ON	Build GArSimulation
BUILD_RECONSTRUCTION	ON	Build GArReconstruction
BUILD_ANALYSIS	ON	Build libGArAnalysis
WITH_GEANT4_UIVIS	ON	Build the simulation with the Geant4 UI and visualisation drivers
CMAKE_BUILD_TYPE	RelWithDebInfo	Standard CMake build types

Each sub-package also still configures on its own, from its own directory — useful when working on one of them:

cd analysis && mkdir build && cd build && cmake .. && make -j4

common/ is pulled in automatically either way, so a standalone build gets the same data type dictionaries as the full one.

Build layout

The sub-packages keep their own subdirectory of the build tree, so the layout is the same whether you built everything or just one package:

build/
├── setup.sh                    # Environment for this build (generated)
├── rootlogon.C                 # Same, for ROOT sessions (generated)
├── common/                     # libSimDataDict, libDigiDataDict + .pcm/.rootmap
├── detector_simulation/        # GArSimulation, macros/, EventToNtupleConverter.C
├── reconstruction/             # GArReconstruction, libRecoDataDict, macros/
└── analysis/                   # libGArAnalysis, macros/

Setting up the environment

CMake writes a setup.sh into the build directory describing what was built. Source it to use the build from any directory — it puts the executables on PATH, the shared libraries on the dynamic loader path and the headers on ROOT_INCLUDE_PATH:

source build/setup.sh
GArSimulation -m macros/gun.mac

It also writes a rootlogon.C, which ROOT runs automatically when started from the build directory, loading the dictionaries and libGArAnalysis. To get it in any directory, run root -l "$FASTGARSIM_ROOTLOGON", or point Rint.Logon in your ~/.rootrc at it.

Command line tools

The macros that are batch tools are also built as executables, installed into bin and put on PATH by setup.sh. They take the macro's arguments positionally, so there is no ROOT invocation to quote and no environment to set up:

EventToNtupleConverter simulation.root ntuple.root
TruncatedDEDX 'gun_*.root' dedx.root 0.1 5.
ECalDigiAnalysis reco.root

The tools are discovered, not listed. Each package scans one directory and builds an executable per macro it finds, named after the macro with the .C dropped:

Directory scanned	Tools currently built
detector_simulation/utils/	EventToNtupleConverter, GeoVis
reconstruction/utils/	ECalDigiAnalysis, RecoExample, TPCRecoAnalysis
analysis/macros/	ExampleAnalysis, TruncatedDEDX

Dropping a new macro into one of those directories is all it takes to get a tool for it — no CMake edits. The macro's entry function has to share its file name, which is the convention ROOT already requires for .x Macro.C.

Each tool takes -h/--help, which reports the argument count it accepts and the description taken from the macro's own header comment. Optional arguments default to whatever the macro declares, and anything that draws runs in batch mode and writes its canvases to file (set FASTGARSIM_NO_BATCH to override).

A macro that only makes sense interactively, or that cannot be compiled, is named in the EXCLUDE list of its package's fastgarsim_add_macro_apps() call.

On the FNAL machines

setup_fnal.sh sets up the UPS products (CMake, Geant4, ROOT) from CVMFS and then the build on top of them. Source it, don't run it:

source setup_fnal.sh

If there is no build yet it says so and tells you how to make one; source it again afterwards. A build directory other than <source>/build can be given as an argument, and the product versions can be overridden beforehand:

export FASTGARSIM_ROOT_VERSION=v6_28_12
source setup_fnal.sh /path/to/build

Credentials for reading files from dCache are not set up — run setup_fnal_security afterwards when you need them. See the analysis README for what that involves.

Quick start

The whole chain, from a build of everything:

source build/setup.sh

# 1. Simulate. macros/nu.mac reads GENIE events, macros/gun.mac fires a particle gun
GArSimulation -m macros/gun.mac

# 2. Convert the object-based output to a flat ntuple
EventToNtupleConverter output.root ntuple.root

# 3. Reconstruct (optional; reads the simulation output, not the ntuple)
GArReconstruction -i output.root -m macros/ecal_digi.mac -o ecal_reco.root
GArReconstruction -i output.root -m macros/tpc_reco.mac  -o tpc_reco.root

# 4. Analyse
ExampleAnalysis ntuple.root example_out.root

Run the simulation with -v instead of -m for the interactive viewer; that is what creates the Geant4 visualisation manager.

GArSimulation finds its run macros through FASTGARSIM_MACRO_PATH (exported by setup.sh) and through its own location, so it can be started from any directory. Macros still resolve against the working directory first, so a local macros/ overrides the built-in one.

Where to go next

Document	Covers
detector_simulation/README.md	Detector geometry, physics and generator commands, the output format, the ntuple branches
detector_simulation/jobs/README.md	Grid production: tarballs, job submission, the configuration script
reconstruction/README.md	Reconstruction modules and their parameters, output branches, writing a new module
analysis/README.md	Writing an analysis, input specifications, reading from dCache, the shipped macros

Citation

See CITATION.cff.

Authors

• Francisco Martinez Lopez — frmart@iu.edu
• Jude Martin — j.martin24@imperial.ac.uk