Skip to content

Running Simulations in MAIA

Info

This guide is current as of August 2025, and was written for version 2.9.7 of the software.

The most recent tutorial makes use of the 3 TeV detector geometry. The same set of instructions can be used to run simulations over the 10 TeV detectors, MAIA and MUSIC, although these detector geometries haven't been fully integrated into the official software releases yet; for the time being this short guide is intended to quickly document how to set up and run simulations over the MAIA detector.

These instructions may not be quite as polished as the tutorial; improvements are welcome!

Setup

The latest MAIA samples are being produced using the latest version of the software, which is now only being built as a container. For running locally, you can pull the container from Github here:

docker pull ghcr.io/muoncollidersoft/mucoll-sim-alma9:v2.9.7

(Or pull mucoll-sim-ubuntu24 instead to get a Ubuntu-based image).

For running on the OSG, or another cluster, you can instead pull from cvmfs using apptainer. The rest of these instructions will assume you're running on the OSG with access to the shared data directory, which is mounted into the container in the command below:

apptainer run -B /ospool/uc-shared/project/futurecolliders/data/:/data /cvmfs/unpacked.cern.ch/ghcr.io/muoncollidersoft/mucoll-sim-alma9\:v2.9.7

Once inside the container (via either method), you can set up the environment by running:

setup_mucoll

You'll then need to check out several separate git repositories, described below:

Dependencies: Calorimeter Coning

You'll need to check out and compile one additional processor for the reconstruction framework that is used for coning in the calorimeter; you can find that here (for the time being). To check it out and compile it, you can run the following commands:

git clone https://github.com/madbaron/MyBIBUtils
cd MyBIBUtils
mkdir build; cd build
cmake ..
make

This will produce a new library file in the build directory, which Marlin needs to be told about. You'll need to do this each time you log back in and set up up the container (or create a setup script to do it for you, following the instructions described in the CERN 2023 version of the tutorial).

export MARLIN_DLL=`readlink -e lib/libMyBIBUtils.so`:${MARLIN_DLL}

Dependencies: Detector Geometry

The MAIA geometry files are now included upstream in k4geo. For the time being however, you can still pull them from the standalone repository below:

git clone https://github.com/madbaron/detector-simulation -b KITP_10TeV

Dependencies: Steering Macros

Updated Python steering scripts for simulation and digitization/reconstruction can be found here:

git clone https://github.com/madbaron/SteeringMacros

(These scripts will ultimately be integrated into the mucoll-benchmarks package; help merging them in would be welcome!)

Dependencies: ACTS Material Maps

These may be available inside the container itself. To make sure you have the latest version of the various material maps, however, you can also check out the repository containing our ACTSTracking processor:

git clone https://github.com/MuonColliderSoft/ACTSTracking

Since we are just pulling data files from this repository, there's no need to compile it.

Running Simulation

To run simulation, you can use the following macro.

For testing purposes, you can run simulation using the single particle guns that were generated for studying MAIA detector performance, they can be found in this directory: /ospool/uc-shared/project/futurecolliders/data/fmeloni/ParticleGuns. In the setup above, we mounted this path into the container under /data, so you can (for example) try running sim over /data/fmeloni/ParticleGuns/muonGun_pT_0_50/muonGun_pT_0_50_gen.slcio to get muon gun events between 0 and 50 GeV.

You can run simulation using the following command; update paths to your checkout of SteeringMacros and the MAIA detector geometry accordingly:

ddsim --inputFile /data/fmeloni/ParticleGuns/muonGun_pT_0_50/muonGun_pT_0_50_gen.slcio \
      --steeringFile /path/to/SteeringMacros/Sim/sim_steer_GEN_CONDOR.py \
      --outputFile output_sim.slcio \
      --compactFile /path/to/detector-simulation/geometries/MAIA_v0/MAIA_v0.xml

Running Digitization and Reconstruction

There is now a single Python file for running both digitization and reconstruction in one step; you can find that file here.

Script Updates

You'll need to update a number of paths in this file to point at your copies of the MAIA detector geometry, ACTS material maps, and calorimeter thresholds (included in the MyBIBUtils checkout above). In general, paths beginning with /code/ need changing. The following series of diffs may not be exhaustive; for each of the examples below, replace /path/to with the actual path to where you cloned the various repositories above.

  • The detector geometry file is specified here; change this to your path to the detector-simulation repository:
-    "DD4hepXMLFile": ["/code/detector-simulation/geometries/MAIA_v0/MAIA_v0.xml"],
+    "DD4hepXMLFile": ["/path/to/detector-simulation/geometries/MAIA_v0/MAIA_v0.xml"],
  • The following passes geometry information to ACTS; note that MAIA_v0.root appears to live in ACTSTracking and so you'll want to update the path accordingly:
-    "TGeoFile": ["/code/detector-simulation/geometries/MAIA_v0/MAIA_v0.root"],
+    "TGeoFile": ["/path/to/ACTSTracking/data/MAIA_v0.root"],

-    "MatFile": ["/code/detector-simulation/geometries/MAIA_v0/MAIA_v0_material.json"],
+    "MatFile": ["/path/to/ACTSTracking/data/MAIA_v0_material.json"],
  • The calorimeter threshold files also need updating:
-    "ThresholdsFilePath": ["/code/CaloSelector/ECAL_Thresholds_10TeV.root"],
+    "ThresholdsFilePath": ["/path/to/MyBIBUtils/data/ECAL_Thresholds_10TeV.root"],

-    "ThresholdsFilePath": ["/code/CaloSelector/ECAL_Thresholds_10TeV.root"],
+    "ThresholdsFilePath": ["/path/to//git/MyBIBUtils/data/ECAL_Thresholds_10TeV.root"],
  • And you'll also need to update the location of the PandoraSettings file:
-    "PandoraSettingsXmlFile": ["/code/SteeringMacros/PandoraSettings/PandoraSettingsDefault.xml"],
+    "PandoraSettingsXmlFile": ["/path/to/SteeringMacros/PandoraSettings/PandoraSettingsDefault.xml"],

To use this script directly, you may also need to change the following paths that specify the location of input files:

read.Files = ["/dataMuC/sim/"+the_args.TypeEvent+"/"+the_args.TypeEvent+"_sim_"+the_args.InFileName+".slcio"]

and output files:

    "FileName": ["lctuple_"+the_args.TypeEvent+"_actsseededckf_"+the_args.InFileName],

and:

        "LCIOOutputFile": ["/dataMuC/reco/"+the_args.TypeEvent+"/"+the_args.TypeEvent+"_reco_"+the_args.InFileName+".slcio"],

and here:

        "LCIOOutputFile": ["/dataMuC/recoBIB/"+the_args.TypeEvent+"/"+the_args.TypeEvent+"_reco_"+the_args.InFileName+".slcio"],

to point at a path that exists on the OSG (or on whatever other system you are running). In the future, we'll aim to provide an updated steering macro where these changes are less necessary. (You can of course modify the script to enable many of these arguments to be set on the command line as well).

Running

Once you've updated the steering macro, it should be very simple to run:

k4run /path/to/SteeringMacros/k4Reco/steer_reco.py

This should give you a LCIO file containing events reconstructed with the latest version of the MAIA detector!