Skip to content

FAQ

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

FAQ

Last revised: 2026-06-15

General

How do I report an issue or ask for help?

For questions, start in the DUNE Slack channel:

  • #nd_muon_spectrometer

For code-specific issues, the code channel may also be useful:

  • #nd_muon_spectrometer_code

You can also create an issue on the DUNE/dune-tms issue tracker.

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

Where should my code go?

Most code lives in src/. The main executable is app/ConvertToTMSTree.cpp.

Useful places to start:

Task Start here
Detector simulation/readout changes src/TMS_Event.cpp, src/TMS_Readout_Manager.cpp, config/TMS_Readout_Default_Config.toml
Reconstruction changes src/TMS_Reco.cpp, src/TMS_Track.cpp, config/TMS_Default_Config.toml
Output branch changes src/TMS_TreeWriter.cpp, src/TMS_TreeWriter.h
Analysis/validation scripts scripts/
Geometry changes DUNE/dunendggd, not usually dune-tms

For a broader map of the code, see dune-tms Primer.

What is the procedure for committing/updating code?

Typical workflow:

  1. Create a branch for your changes.
  2. Make the smallest coherent change you can.
  3. Build and run a small validation test.
  4. Update relevant documentation if output branches, configs, or workflows changed.
  5. Open a pull request against the appropriate branch.
  6. Explain what changed, why, and how you tested it.

Before requesting review, check Validating Changes.

Who runs production?

Large-scale production should be handled through the ND production workflow/team, not ad hoc GPVM jobs.

For production sample documentation, use:

Use GPVMs for small tests, debugging, and development.

Setup and running

How do I install or build dune-tms?

Start with Software Installation and Dependencies.

The recommended path is the DUNE GPVM setup:

source setup_FNAL.sh
make

An SL7 container workflow and local/developer build notes are also documented there.

How do I run dune-tms on an edep-sim file?

Use:

ConvertToTMSTree.exe input_edep_file.root output_tmsreco_file.root

For a guided first run, see Tutorial.

Where are useful input files?

See Datasets.

For local development, spill-like edep-sim files are usually the most useful inputs because they can be processed locally through dune-tms after code/config changes.

What output trees should I use?

See Output File Contents.

Short version:

Use case Tree
Reconstructed tracks Reco_Tree
Full particle/vertex truth Truth_Spill
Reco-to-truth matching summaries Truth_Info
Hough lines / clusters / reco debugging Line_Candidates
Geometry/version provenance Metadata

How do I match a reconstructed track to truth?

Use Truth_Info to find the top truth contributors to each reconstructed track:

  • RecoTrackPrimaryParticle*: true particle contributing the most visible energy to the reco track
  • RecoTrackSecondaryParticle*: true particle contributing the second-highest visible energy

No equivalent per-track summaries are saved for third-and-later truth contributors.

For the full particle record, use the particle index branches with Truth_Spill:

  • RecoTrackPrimaryParticleIndex
  • RecoTrackSecondaryParticleIndex

What is the difference between Truth_Info and Truth_Spill?

Truth_Spill is the authoritative spill-level particle and vertex truth table.

Truth_Info is filled with reconstructed events/time slices and is mainly for reco-to-truth matching summaries, slice-level truth summaries, and hit-level debugging.

A useful mental model:

  • Truth_Spill: "What true particles and vertices were in the spill?"
  • Truth_Info: "Which true particles contributed to this reconstructed track/slice?"

Geometry and fiducial volumes

How can I visualize geometry?

Use the online DUNE geometry visualizer.

Also see:

Where are the TMS/LAr fiducial volumes defined?

The reconstruction config contains fiducial-volume settings:

TMS geometry constants are in:

For output-file provenance, check the Metadata tree, which stores geometry tag/branch/commit and fiducial bounds.

Coding and analysis

Should I write scripts in Python or C++?

Either is fine for small studies. Python is often faster to write and easier for interactive exploration.

For large files or event loops, C++/ROOT may be much faster. If a Python loop is too slow, consider either:

  • reading fewer branches
  • using vectorized/uproot-style workflows, if appropriate
  • rewriting the hot loop in C++

My Python ROOT branch reading is confusing. What should I check?

First check the branch definitions in:

Then check the output-tree pages:

Many branches are fixed-size C-style arrays, for example [nTracks][200][4] or [nTrueParticles][4]. In PyROOT or uproot, these may not behave like ordinary Python lists unless you explicitly convert or slice them carefully.

I changed the code. How do I know I did not break anything?

Start with Validating Changes.

Useful checks include:

  • build succeeds cleanly
  • small ConvertToTMSTree.exe test runs to completion
  • output file contains expected trees
  • Metadata matches the expected geometry/version
  • key validation plots or reconstruction-efficiency checks look reasonable

Also see:

Clone this wiki locally