Skip to content

Tutorial

Jump to bottom
jdkio edited this page Jun 16, 2026 · 22 revisions

Tutorial: First dune-tms Run

Last revised: 2026-06-15

This tutorial walks through a first successful dune-tms run: build the code, choose an input file, run detector simulation + reconstruction, and inspect the output.

For installation details, see Software Installation and Dependencies. For the detector-simulation model, see TMS Simulation. For the code architecture, see dune-tms Primer.

Goal

By the end of this tutorial, you should be able to:

  1. build dune-tms on the DUNE GPVMs
  2. run ConvertToTMSTree.exe on an edep-sim file
  3. confirm that an output ROOT file was produced
  4. identify the main output trees
  5. know where to go next for validation, plotting, or code changes

Recommended environment

The recommended environment is a DUNE GPVM.

kinit [email protected]
ssh dunegpvmXX.fnal.gov

GPVMs should be used for interactive development, small tests, and debugging. They should not be used for sustained large-scale production. Large production requests should go through the ND production team.

Get and build the code

Clone and build in your DUNE app area:

cd /exp/dune/app/users/${USER}
git clone [email protected]:DUNE/dune-tms.git
cd dune-tms
source setup_FNAL.sh
make

If SSH cloning is not set up, HTTPS should also work:

git clone https://github.com/DUNE/dune-tms.git

For GitHub SSH setup, use GitHub's official documentation: Adding a new SSH key to your GitHub account.

Alternative: SL7 container

Some workflows may need the older SL7 environment. Enter the SL7 container with:

/cvmfs/oasis.opensciencegrid.org/mis/apptainer/current/bin/apptainer shell \
  --shell=/bin/bash \
  -B /cvmfs,/exp,/nashome,/pnfs/dune,/opt,/run/user,/etc/hostname,/etc/hosts,/etc/krb5.conf \
  --ipc --pid \
  /cvmfs/singularity.opensciencegrid.org/fermilab/fnal-dev-sl7:latest

Then set up and build with:

cd /exp/dune/app/users/${USER}/dune-tms
. setup.sh
make

If you already built in a different environment, run make clean before rebuilding inside SL7.

Choose an input file

ConvertToTMSTree.exe runs on edep-sim ROOT files.

For local dune-tms development, the most useful inputs are usually spill-like edep-sim files from official production. These already group events into spill-like units and are useful for testing detector-simulation, time-slicing, reconstruction, and output changes.

For example, MicroProdN4p1 spill-like files are under:

/pnfs/dune/persistent/physicsgroups/dunendsim/abooth/nd-production/MicroProdN4p1/run-spill-build/MicroProdN4p1_NDComplex_FHC.spill.full/

See Datasets for more sample locations and for the distinction between:

  • individual edep-sim event files
  • spill-like edep-sim files
  • existing TMS reconstruction output

For a first test, pick one small edep-sim ROOT file from a spill-like directory.

Run detector simulation and reconstruction

The executable is:

ConvertToTMSTree.exe input_edep_file.root output_tmsreco_file.root

Example pattern:

ConvertToTMSTree.exe \
  /path/to/input_edep_file.root \
  /path/to/output_tmsreco_file.root

If you omit the output filename, ConvertToTMSTree.exe writes an output file next to the input using the input filename with _output.root appended before the final extension.

For example:

ConvertToTMSTree.exe input.root

writes:

input_output.root

Limit the number of events for testing

For quick tests, it is often useful to process only a small number of events. The maximum number of events is controlled in:

config/TMS_Default_Config.toml

Look for:

[Applications]
MaximumNEvents = -1

Set MaximumNEvents to a small positive number for a quick smoke test, for example:

MaximumNEvents = 10

Set it back to -1 to process all entries.

Time slicing

The time slicer is controlled in:

config/TMS_Default_Config.toml

Look for:

[Recon.Time]
RunTimeSlicer = true

For modern spill-like production inputs, running with the time slicer on is usually the relevant default. Be aware that:

  • Reco_Tree, Truth_Info, and Line_Candidates are filled for reconstructed events/time slices
  • Truth_Spill is spill-level

This distinction matters when computing efficiencies or matching reconstructed tracks back to truth.

Inspect the output file

After the run finishes, check that the output file exists:

ls -lh output_tmsreco_file.root

Then inspect the ROOT trees. For example:

root -l output_tmsreco_file.root

Inside ROOT:

.ls
Reco_Tree->Print()
Truth_Info->Print()
Truth_Spill->Print()

The main trees are:

Tree Purpose
Reco_Tree reconstructed 3D TMS tracks
Truth_Spill authoritative spill-level particle and vertex truth
Truth_Info reco-to-truth matching summaries and slice-level truth information
Line_Candidates lower-level Hough lines, clusters, and reco debugging information
Metadata version and geometry provenance

For details, see Output File Contents.

Minimal sanity checks

A first successful run should usually have:

  • a non-empty output ROOT file
  • a Metadata tree
  • entries in Truth_Spill
  • entries in Reco_Tree / Truth_Info / Line_Candidates, depending on reconstruction and time slicing

Simple ROOT checks:

Reco_Tree->GetEntries()
Truth_Info->GetEntries()
Truth_Spill->GetEntries()
Metadata->Scan()

If Reco_Tree has no entries, check whether the input file has TMS activity, whether the reconstruction thresholds are appropriate, and whether MaximumNEvents was set too low.

Understanding the output

For reconstructed-track analysis, start with:

For particle and vertex truth, use:

For reco-to-truth matching, use:

Important matching convention:

  • RecoTrackPrimaryParticle* describes the true particle contributing the most visible energy to a reconstructed track
  • RecoTrackSecondaryParticle* describes the true particle contributing the second-highest visible energy
  • equivalent summaries are not saved for third-and-later truth contributors
  • for the full particle record, use the particle index plus Truth_Spill

Drawing event displays

Event-display scripts live under scripts/. The exact script names and options may change, so check the current script help before running:

python3 scripts/Reco/draw_spill_3D_projections.py --help

A typical pattern is:

python3 scripts/Reco/draw_spill_3D_projections.py \
  --input_filename output_tmsreco_file.root \
  --outdir event_display_output

See Plotting events / event display for more details.

Common next steps

I want to change detector simulation

Start with:

I want to change reconstruction

Start with:

I want to add output branches

Start with:

When adding branches, update the relevant wiki page:

I want to validate a change

Start with:

Getting help

For questions, ask in the DUNE Slack channel:

#nd_muon_spectrometer

When asking for help, include:

  • which GPVM/container environment you used
  • the branch or commit you built
  • the input file path
  • the command you ran
  • the error message or unexpected output
  • whether you changed any config values

Clone this wiki locally