# Executables {#Executables} ## `mu3eSim` ### Simulation environment The simulation program expects the following directories to be present in the directory where it is executed (can be simlinks): - `data` - the directory for the simulation output, should have enough free disk space ### Configuration files The simulation program will at startup always read the `./sim.json` configuration file. These files have to be present and have to contain all the required entries (the json format is mostly self-documenting, possible options are listed and units used are stated at the beginning of the file). `detector.conf` specifies the detector geometry and `digi.conf` both the simulation input (beam rate, branching fractions...) and the digitisation behaviour of the detector (thresholds, noise...). After reading the files, their content is stored in the output root file (similarly for configuration files added later in the processing chain) and is available during analysis or for checking of files. ### Interactive mode Starting the simulation with no command line arguments (i.e. just mu3eSim ), will start an interactive Geant session (provided Geant4 and Qt are properly talking to each other). Here you can study the geometry by switching on and off parts of the detector for visualization or actually simulate using the command /run/beamOn Nev where `Nev` is the number of events to be simulated. For other options (e.g. overlap search), check out the Geant4 documentation. If you just want a quick view of the detector, there is a faster version which does not load and configure physics processes but just the geomtry, which is started with mu3eVis ### Batch mode If the Mu3eSim program is started with a macro (`.mac`) file as an argument, the simulation will enter batch mode and process the commands in the macro file: mu3eSim r1.mac where the macro file usually looks like this # /run/verbose 0 /event/verbose 0 # /mu3e/run/setRunNumber 1 /run/beamOn 2116 The first two commands reduce the verbosity of Geant4, making the text output managable. The third command will set the run number (and thus the random seed) and the last command starts the simulation and simulates 2116 frames. Note that the first hundred frames are used for loading the target with muons and are not written to file. Also the sorting process (see below) consumes 16 frames, thus you have to simulate 116 frames more than you actually need. Mu3eSort -------- The simulation includes digitisation deadtimes and buffering in the pixel chips; hits will thus not necessarily show up in their frame of origin. The Mu3eSort program emulates the front end FPGAs and sorts the hits back into their appropriate frames. The sorting currently happens over a depth of 16 frames. The sorting program takes two arguments, an in- and an outputfile: mu3eSort in.root out.root And all of it in a batch script ------------------------------- For automated simulation in batch mode, the follwing script can be used: #!/bin/sh mkdir data echo '/mu3e/run/setRunNumber ' $1 > run.mac echo '/run/beamOn ' $2 >> run.mac run=`printf %06i $1` infile=`echo 'data/mu3e_run_'$run'.root'` outfile=`echo 'data/mu3e_sorted_'$run'.root'` ./mu3eSim run.mac ./mu3eSort $infile $outfile rm $infile Here we assume that we are in a clean working directory containing the `mu3eSim` and `mu3eSort` executables. The first argument is the run number and the second argument the number of frames to simulate. Mu3eTrirec ---------- The reconstruction based on hit triplets written and maintained bz Alex Kozlinskyi. The full set of options is returned by the help command mu3eTrirec --help The typical call would be mu3eTrirec in.root --output out.root If you want to look at the reconstructed events in the event display, do mu3eTrirec in.root --output out.root -d ### Reconstruction configuartion files The reconstruction is controlled with the `trirec.conf` configuration file, which should be present in the execution directory. Mu3eAnaVertexfit ---------------- The vertex fit executable tries to fit all triplets of two positive and one negative track in a frame to a common vertex and produces an output file suitable for a first analysis. Call with mu3eAnaVertexfit in.root out.root If you would like to combine several input files, just list them one after another mu3eAnaVertexfit in1.root in2.root ... inN.root out.root Mu3eAnaSignalnorm ----------------- If we simulate signal decays, the muons are generated in front of the vacuum window and fly to the target in order to get a realistic stopping distribution. Unfortunately, some muons will also get lost. As we normalize to the number of muons stopped on target, this number has to be extracted after the simulation run. To this end, run `mu3eAnaSignalnorm` on the output of `mu3eSort`: mu3eAnaSignalnorm sorted_data.root The output has a line `XXX good ID frames out of YYY`; `XXX` is the signal normalization you want to use. This number is also written to a `signalnorm.txt` file for use in batch processing. Mu3eAnaWeightsum ---------------- If weighted events are used, it is often desirable to know the sum of weights in a file/a series of files. For this take files after the vertex fit and run mu3eAnaWeightsum in1.root in2.root in3.root ... Mu3eAnaSignalana ---------------- Signal analysis programm determining resolutions and efficiencies. Run on the output of the vertex fit. mu3eAnaSignalana vertex_fit_output.root outputdirectory text nsignal Like most of the analysis programms, `mu3eAnaSignalana` requires a directory `results` in which the output is stored in a subdirectory given as a command line option `outputdirectory`. `text` is a text written into the plots for easy identification, typically something like `"phase I"`. `nsignal` is the number to normalize efficiencies to, typically obtained with `mu3eAnaSignalnorm`. The output direcotory will contain an `outputdirectory.ps` file with all the plots, an `outputdirectory.root` file storing the histograms and a `plots` subdirectory with individual `.png` and `.pdf` files of all the plots. Multiple input files can be processed by listing them in the beginning of the argument chain: mu3eAnaSignalana in1.root in2.root in3.root outputdirectory text nsignal Mu3eAnaBhabhafit ---------------- This program works analogously to `mu3eAnaVertexfit` but attempts to fit just one positive and one negative tarck in order to find Bhabha scattering events. Call with mu3eAnaVertexfit in.root out.root Mu3eAnaOccupancy ---------------- The `mu3eAnaOccupancy` program generates occupancy plots from simulation files: mu3eAnaOccupancy inputfile1.root ... inputfileN.root outputdirectory any number of input files is chained and the plots in various formats are placed in the output directory, similarly to `mu3eAnaSignalana`. Mu3eMakeFieldMap ---------------- Produce a field map using the current settings in `detector.json`. Only makes sense for solenoid fields with fixed number of windings. mu3eMakeFieldMap type file where `type` is 0 for an RZ map and 1 for a 3D map and file is the field map file. Now that we have field maps from the magnet manufacturer, this is partially obsolete. Mu3eConvertFieldMap ------------------- Convert a field map from the format provided by Danfysik/Sig Martin to the mu3e binary field map format. mu3eConvertFieldMap infile outfile