Build and develop Mu2e offline software using muse, git workflows, and multi-repository coordination. Use when working with Offline, Production, or mu2e-trig-config repositories, running muse commands, or managing git branches.
Mu2e is a high-energy physics experiment at Fermilab searching for muon-to-electron conversion. This document describes the offline software ecosystem (simulation, reconstruction, and analysis), which is distinct from the online DAQ system.
The offline software comprises ~1 million lines of C++ code across ~60 repositories maintained by ~100 collaborators. This instruction file covers the core coordinated repositories used for offline work.
These three repos are tightly coordinated and typically checked out together:
Offline - Core simulation, reconstruction, and analysis framework
https://github.com/Mu2e/OfflineProduction - Configuration and scripts for production workflows
https://github.com/Mu2e/Productionmu2e-trig-config (mtc) - Trigger configuration and generation
generateMenuFromJSON.pyhttps://github.com/Mu2e/mu2e-trig-configRelationship: Production and mtc provide configuration/scripts that control executables built in Offline. You typically cannot do meaningful work in Offline without the other two.
The DAQ/online system is independently maintained:
otsdaq-* reposartdaq-* reposOffline depends on standard HEP software and custom collaboration tools:
Standard HEP packages:
geant4 - Detector simulationroot - Data analysis frameworkgsl - GNU Scientific Libraryboost, clhep - Standard C++ librariesxerces-c, sqlite, postgresql - Data handlingArt framework (Fermilab's event processing framework):
art - Core frameworkcanvas - Data product handlingmessagefacility - Loggingfhicl-cpp - Configuration systemcetlib, cetlib-except - UtilitiesCollaboration-developed:
kinkal - Kalman filter track fittingbtrk - Track reconstructionartdaq-core-mu2e - Raw data format definitionsAll dependencies are managed via:
Muse is Mu2e's build orchestration system. It wraps SCons and manages multi-repo builds.
Note on architecture: Mu2e is in a transition period (Phase 2):
This explains why you see both CMakeLists.txt and SConscript files in the code.
→ For complete Muse documentation, see muse-reference.md
build/ subdirectory (out-of-source)# Initial setup (always required first)
mu2einit
# See available published builds (does not create links)
muse list
# Link to a backing build (before muse setup)
muse backing HEAD # Latest CI build
muse backing Offline v13_00_11 # Specific release
# Setup environment (run once per shell session)
muse setup # From workDir
muse setup /path/to/workDir # From anywhere
muse setup -q debug # Debug build
muse setup -q prof # Production build (default)
# Build (after muse setup)
muse build -j 20 --mu2eCompactPrint # Parallel build with compact output
# Check status
muse status # Show current setup and builds
# Create grid tarball
muse tarball # For job submission
Full local build (all three repos):
cd /path/to/workDir
git clone https://github.com/Mu2e/Offline
git clone https://github.com/Mu2e/Production
git clone https://github.com/Mu2e/mu2e-trig-config
muse setup
muse build -j 20 --mu2eCompactPrint
Build with backing (recommended for development):
cd /path/to/workDir
muse backing HEAD # Link to latest CI build
git clone [email protected]:<username>/MyAnalysisRepo
muse setup
muse build -j 20 --mu2eCompactPrint
Build with backing build:
cd /path/to/workDir
muse backing HEAD
muse setup
muse build -j 20
Return to existing build:**
cd /path/to/workDir
muse setup # Re-establishes environment
# Now ready to build or run
mu2ebuild02 for builds, not gpvm nodes (use -j 20)muse setup is run, environment persists for that shell sessionSmack is the next-generation build system using Spack + CMake:
Smack quickstart (Phase 3 preview):
export MYSS=myproject
export MYENV=prof
mu2einit
smack local $MYSS/$MYENV
cd $MYSS
source ./setup-env.sh
spack env activate $MYENV
spack add Offline@main +g4
spack develop Offline@main
spack add production@main
spack develop production@main
spack add mu2e-trig-config@main
spack develop mu2e-trig-config@main
spack concretize -f
spack install
→ For complete Smack/Spack documentation, see smack-reference.md
After building:
# Run art executable
mu2e -c Production/Validation/ceSimReco.fcl -n 100
# Generate trigger menu from JSON
python mu2e-trig-config/python/generateMenuFromJSON.py \
-mf mu2e-trig-config/data/physMenu.json \
-o gen -evtMode all
Branches have semantic meaning in Mu2e workflows:
main - Development head, continuous integrationRun1* - Production branches for Run 1 data taking (e.g., Run1B)Current setup in this workspace:
Run1Bhead (likely detached HEAD or branch alias)headDevelopers often use aliases for convenience:
# Standard build alias
alias build='muse build -j 20 --mu2eCompactPrint'
# Standard initialization
alias mu2einit='source /cvmfs/mu2e.opensciencegrid.org/setupmu2e-art.sh'
workDir/
├── Offline/ # Source code
├── Production/ # Source code
├── mu2e-trig-config/ # Source code
└── build/ # ALL build output (can be symlink to other disk)
└── <stub>/ # e.g., al9-prof-e29-p090
├── Offline/
│ └── lib/ # Compiled libraries
├── Production/
└── mu2e-trig-config/
Build output directory is named by: <OS>-<profile>-<compiler>-<envset>
Prepare tarball for grid jobs:
cd workDir
muse setup
muse tarball
# Tarball path will be printed
# Use with mu2eprodsys: --code=/path/to/Code.tar.bz2
Pre-built releases and dependencies:
/cvmfs/mu2e.opensciencegrid.org/Musings//cvmfs/mu2e-development.opensciencegrid.org/museCIBuild//cvmfs/mu2e.opensciencegrid.org/DataFiles//cvmfs/mu2e.opensciencegrid.org/DataFiles/Muse/Always available via CVMFS (network-mounted filesystem).
Build fails with memory issues:
-j 20Wrong environment/dependencies:
muse status for current setupmu2einit was runMuse can't find repos:
.muse file in root (already present in Big Three)muse status to see recognized reposBuild doesn't see changes:
muse setup was run)muse statusmuse build -c && muse build -j 20When helping with Mu2e offline work:
mu2einit has been run before any muse commandsmuse setupbuild if available, or muse build -j 20 --mu2eCompactPrintWhen you execute commands:
muse status to understand current setupgit status or git branchLast updated: 2026-02-07
Maintained by: Offline software coordinators
Questions: Post in #help-bug or #offlineSoftware on Mu2e Slack