This is the C++ source code for the musrSim simulation software which is intended to be a general tool to design and simulate µSR spectrometer with very high accuracy. To compile and run musrSim, the user must have a recent Geant4 (tested with v11.0.3 and v11.2.0) and Root installed (tested with v6-22-06 and v6-30-02, but the version should not be critical).

The code is specifically tuned to simulate muon spin spectrometers.
The code is maintained by the Laboratory for Muon Spin Spectroscopy at PSI.

Supported platforms

Linux and any other decent OS that can run Root and GEANT4.

Installation

Compile and install Geant4, we recommend the use of the following cmake flags

cmake -DCMAKE_INSTALL_PREFIX=/path/to/G4installation /path/to/G4source -DGEANT4_USE_QT=ON -DGEANT4_INSTALL_DATA=ON -DGEANT4_USE_OPENGL_X11=ON

We also recommend that you use view3dscene as a VRML viewer.

Following the installation of Gean4, set the correct environment variables. This can be done easily by editing /path/to/G4installation/bin/geant4.sh to uncomment the lines defining Geant4 data location:

export G4NEUTRONHPDATA=$GEANT4_DATA_DIR/G4NDL4.7
export G4LEDATA=$GEANT4_DATA_DIR/G4EMLOW8.5
export G4LEVELGAMMADATA=$GEANT4_DATA_DIR/PhotonEvaporation5.7
export G4RADIOACTIVEDATA=$GEANT4_DATA_DIR/RadioactiveDecay5.6
export G4PARTICLEXSDATA=$GEANT4_DATA_DIR/G4PARTICLEXS4.0
export G4PIIDATA=$GEANT4_DATA_DIR/G4PII1.3
export G4REALSURFACEDATA=$GEANT4_DATA_DIR/RealSurface2.2
export G4SAIDXSDATA=$GEANT4_DATA_DIR/G4SAIDDATA2.0
export G4ABLADATA=$GEANT4_DATA_DIR/G4ABLA3.3
export G4INCLDATA=$GEANT4_DATA_DIR/G4INCL1.2
export G4ENSDFSTATEDATA=$GEANT4_DATA_DIR/G4ENSDFSTATE2.3

Then run the following to setup the correct variables

. /path/to/G4installation/bin/geant4.sh

You will probably need to do that everytime you want to run the simulation or add the line above to your .bashrc.

Clone the musrSim repository

git clone https://bitbucket.org/muonspin/musrsim.git

then (see below for RedHat or other old systems)

cd musrsim
mkdir build
cd build
cmake ../
make -j8
make install

This will install the musrSim binary in /usr/local/bin, but it can be moved to any other directory in your PATH.

Running the tests

Tests are built by default. After configuring and building, run them with:

ctest --test-dir build --output-on-failure

Set -DBUILD_TESTING=OFF during CMake configuration to omit the test executables.

The regression suite currently covers steering-file parsing, process and volume ID mappings, the muonium charge-state yield model over its documented energy range, and the unpolarized muonium decay spectrum, isotropy, and energy conservation. Tests carrying the physics label can be run separately with:

ctest --test-dir build --output-on-failure -L physics

To compare a modified build with an older build using identical event seeds and the LEM run-4000 setup, build the musrRootOutputCompare target and run:

tests/compare_lem_versions.sh /path/to/baseline/musrSim /path/to/candidate/musrSim 500

The harness writes both simulations to temporary directories and compares the logical ROOT contents exactly. Set MUSRSIM_ROOT_COMPARATOR when the comparator is not available under tests/ beside the candidate executable.

Running the simulations

Prepare a file, finlename.mac, with your beamline and spectrometer design following the instruction in the musrSim manual. Create a folder data and then run the simulation

musrSim filename.mac

RedHat and old systems

For compilation on RedHat systems:

Make sure that the gcc-toolset-13 package is installed
Use the follwoing compilation command: scl enable gcc-toolset-13 'make -j8'
Use CMakeLists_rhel8.txt: cp CMakeLists_rhel8.txt CMakeLists.txt
If you have Root 6.30 use FindROOT_6.30.cmake: cp FindROOT_6.30.cmake FindROOT.cmake

Contact

Thomas Prokscha thomas.prokscha@psi.ch

Zaher Salman zaher.salman@psi.ch

README.md

musrSim simulation

Contents