Overview
This is a tutorial on the simulation and reconstruction software for the Muon Collider, which is based on CLIC's ILCSoft. It has been setup to run on the Snowmass machine login.snowmass21.io.
Tutorial Agenda: https://indico.fnal.gov/event/45187/
Monte Carlo samples
The Monte Carlo samples used in this tutorial are stored in the directory:
/collab/project/snowmass21/data/muonc/
Signal samples
The available μ−μ+ hard-scattering processes are:
- μ−μ+ → Hνν̄ → bb̄νν̄ at √s = 1.5 TeV, generated with PYTHIA8;
- μ−μ+ → HHνν̄ → bb̄bb̄νν̄ at √s = 3 TeV, generated with WIZARD;
- μ−μ+ → bb̄bb̄νν̄ at √s = 3 TeV, generated with WIZARD.
Beam-induced background sample
The Beam-Induced Background (BIB) at 1.5 TeV for one bunch-crossing has been generated by N. Mokhov with MARS15.
This has been simulated using this software with the last available detector geometry developed for the Muon Collider (CLIC_o3_v14_mod4)
All the BIB has been split in 16 files which contain a total of 2993 pseudo-events; this is an artificial subdivision used to speed up the simulation.
Simulation and reconstruction code
The Muon Collider simulation and reconstruction code is available in a singularity container on CERN's cvmfs:
/cvmfs/unpacked.cern.ch/registry.hub.docker.com/infnpd/mucoll-ilc-framework:1.0-centos8
N.B.: A docker container is also available at this link.
Steering files and ROOT macros
All the configuration files and ROOT macros used in this tutorial are available in the github repository:
https://github.com/MuonColliderSoft/MuC-Tutorial.git
Tutorial setup
1 - Log into the login.snowmass.io machine:
ssh -XY <account name>@login.snowmass21.io
2 - Access the singularity container:
singularity run --bind `echo $HOME` --bind /collab/project/snowmass21/data/muonc:/data /cvmfs/unpacked.cern.ch/registry.hub.docker.com/infnpd/mucoll-ilc-framework:1.0-centos8
The "bind" option is used to to mount the $HOME directory and the /data directory with the Monte Carlo samples.
N.B.: The source code is saved in the /opt/ilcsoft/v02-01-pre/ directory.
3 - Check that the Muon Collider software is properly set up. If everything is OK, you should see the following outputs with no error messages:
4 - Check out the configuration files and the ROOT macros:
git clone https://github.com/MuonColliderSoft/MuC-Tutorial.git
cd MuC-Tutorial && git checkout v2.0
1 - Running the simulation and reconstruction
Simulation step
The simulation program is part of the DD4Hep package, which uses as main components the ROOT geometry package, which is used for construction and visualization of geometry, and the Geant4 simulation toolkit, which can be interfaced via DD4hep to perform detector simulation in complex detector designs.
In the MuC-Tutorial/tutorial/1-mumuHHbbbb/ directory you can find two examples of the configuration files used by the simulation command: ddsim
To go to the directory use the command line:
cd ~/MuC-Tutorial/tutorial/1-mumuHHbbbb/
All the options can be passed as arguments to the command line, but probably the easiest way is to set everything in the steering file and then invoke for example:
ddsim --steeringFile sim_steer_Hbb.py > sim.out 2>&1
Looking in the configuration file you can see for example:
SIM.compactFile = "/opt/ilcsoft/v02-01-pre/detector-simulation/geometries/CLIC_o3_v14_mod4/CLIC_o3_v14.xml" ← geometry definition
SIM.inputFiles = ["/data/samples/HH/mumu2H2bb750.stdhep"] ← Input file
SIM.outputFile = "mumu_H_bb.slcio" ← Output file
SIM.numberOfEvents = 10 ← Number of events
Use the output of the command ddsim -h to see all the other parameters that you can set.
Digitization/reconstruction step
This second step is done using the command: Marlin: Modular Analysis and Reconstruction for the LINear Collider. As described in the main github page of the program: the idea is that every computing task is implemented as a processor (module) that analyses data in an LCEvent and creates additional output collections that are added to the event. The framework allows to define the processors (and their order) that are executed at runtime in a simple steering file. Via the steering file you can also define named parameters (string, float, int - single and arrays) for every processor as well as for the global scope. By using the framework users don't have to write any code that deals with the IO they simply write processors with defined callbacks, i.e. init(), processRunHeader(), processEvent(), end().
You can have a list of all the available processors with all their parameters using the follow command. Note that the file processor.txt can be see as an example steering file for the Marlin program:
Marlin -x > processor.txt
We can now use the output of the previous step to reconstruct the simulated events.
In the same directory MuC-Tutorial/tutorial/1-mumuHHbbbb/ run the reconstruction:
Marlin reco_steer_Hbb.xml > reco.out 2>&1
This command produces two output files: Output_REC.slcio with all the collections produced (you can specify which collections need to be saved in the file) and histograms.root which contains some diagnostics plots and trees.
Giving a quick look at the steering file you can see that it is an xml file enclosed in the <marlin> ... </marlin> tag. Then there are three main sections:
1) execute section (ordered list of processors to be executed):
<execute>
<processor name="MyAIDAProcessor"/>
<processor name="MyTestProcessor"/>
<processor name="MyLCIOOutputProcessor"/>
</execute>
2) global section (global settings):
<global>
<parameter name="LCIOInputFiles"> input.slcio </parameter>
<parameter name="MaxRecordNumber" value="1000" />
</global>
3) processor section (processor configuration, there is one section for each processors of the "execute" list):
<processor name="MyLCIOOutputProcessor" type="LCIOOutputProcessor">
<parameter name="LCIOOutputFile" type="string"> Output_DST.slcio </parameter>
<parameter name="DropCollectionTypes" type="StringVec">
SimCalorimeterHit
SimTrackerHit
</parameter>
<parameter name="LCIOWriteMode" type="string" value="WRITE_NEW"/>
<parameter name="SplitFileSizekB" type="int">1048576 </parameter>
<parameter name="Verbosity" type="string">WARNING </parameter>
</processor>
To produce final ntuples for the analysis:
Marlin lctuple_steer.xml > ntuples.out 2>&1
The final root file with ntuples is: JetHistograms.root
For exercise, 1000 events of double Higgs production are already simulated and reconstructed, and you can run a simple macro invariant_mass.C for the events analysis:
In order to run the macro:
root -l
.L invariant_mass.C
invariant_mass()
The argument is used to chose the plot you want to see:
- 0: number of reconstructed jets
- 1: pseudorapidity of jets in the event
- 2: transverse momentum of jets in the event
- 3: phi of jets in the event
- 4: energy of jets in the event
- 5: invariant mass of jet pair associated to Higgs with highest pT
- 6: invariant mass of jet pair associated to Higgs with lowest pT
As example:
root -l
.L invariant_mass.C
invariant_mass(5)
the plot of the invariant mass of jet pair associated to Higgs with highest pT is shown
Some useful tools
The default output format of the reconstruction package is an LCIO (Linear Collider I/O) file. You can inspect these files using these commands:
1) To print the list of saved collection and their sizes use:
anajob Output_REC.slcio
2) To see the details of all the collection of the first event:
dumpevent Output_REC.slcio 1 > event1.txt
If you are interest only in the number of events saved use:
lcio_event_counter Output_REC.slcio
You can also merge or split an LCIO files:
Singularity> lcio_merge_files -h
usage: lcio_merge_files <output-file> <input-file1> [[input-file2],...]
Singularity> lcio_split_file -h
usage: lcio_splitfile infilename outfilename sizeInBytes
You can also write a ROOT tuple for a more standard analysis. For this purpose you can use the LCTuple processor: it creates a ROOT TTree with a column wise ntuple from LCIO collections. You can see an example of use in the MuC-Tutorial/config/reco/lctuple_steer.xml file.
Marlin MuC-Tutorial/config/reco/lctuple_steer.xml > lctuple.out
This command produces the ROOT file: lctuple_example.root
Event display
To display events use the package CEDViewer:
ced2go -d /opt/ilcsoft/muonc/detector-simulation/geometries/MuColl_v1/MuColl_v1.xml Output_REC.slcio
2 - A look at the beam-induced background (BIB)
To get acquainted with the beam-induced background (BIB) two ROOT files have been prepared and are available in /data/ntuples/BIB (within the singularity container):
- mcParts_ntuple_BIB.root contains a TTree with the BIB Monte Carlo particles (MCpartTuple);
- allHits_ntuple_BIB.root contains TTrees with the reconstructed hits of the tracker, the ECAL and HCAL calorimeters, and the muon detercors (TrackerHitsTuple, CaloHitsTuple, MuonHitsTuple).
The macros to run over the TTrees and fill some significant histograms are in the directory:
cd ~/MuC-Tutorial/tutorial/2-BIB
Instructions are in the readme.txt file, available locally or at
https://github.com/MuonColliderSoft/MuC-Tutorial/blob/master/tutorial/2-BIB/readme.txt
3 - Overlaying the BIB to signals
To overlay background events from an additional set of LCIO files you can use the Overlay processor. You can list all files of the BIB and then decide which quota (i.e. the number of artificial pseudo events) to use. You can also decide a priori a set of time cuts to apply to each detector. Remember that signal and BIB are overlaid in the digitization step so the signal and BIB samples must be generated and simulated prior to overlaying.
You can check the example in the tutorial/3-mu_BIB directory. In this exercise you are going to learn how to check the reconstruction differences with and without the BIB.
The chosen signal is an event with 1000 prompt muons, with uniform pt between 0 and 10 GeV. The signal has been already simulated for you, now you are going to reconstruct it.
First going in the right directory:
cd ~/MuC-Tutorial/tutorial/3-mu_BIB/
To reconstruct the signal without the BIB digit:
Marlin reco_sig_only_steer.xml > log_sig_only.log
It will produce an histograms_sig_only.root output.
To reconstruct the signal overlayed with the BIB (10/2993 of the BIB bunch crossing is used as example):
Marlin reco_sig_and_BIB_steer.xml > log_sig_and_BIB.log
It will produce an histograms_sig_and_BIB.root output.
Now we are going to compare the fitted track parameters in the two cases.
A root file with a full signal+BIB reconstruction, a signal only reconstruction and a macro for the analysis has been prepared for you.
In order to run the macro:
root -l.L compare_sig_and_BIB.Ccompare_sig_and_BIB()
You can play with the cuts on the maximum chi2 (first argument) and on the number of hits (second argument) to clean your track sample. The third argument is used to chose the plot you want to see:
- 0. chi2/ndof
- 1: number of hits
- 2: track pt
- 3: D0
- 4: Z0
- 5: Omega
root -l.L compare_sig_and_BIB.Ccompare_sig_and_BIB(5,6,3)
In this way a maximum chi2/ndof of 5 and a minimum number of 6 hits is required, and the D0 comparison is shown.
You can also measure the track pT resolution as a function of PT with the track_pt_resolution.C macro. You should simply type:
root -l.L track_pt_resolution.Ctrack_pt_resolution()
In this way you can compare the track pt resolution with and without the BIB.
Advanced topics
Modifying an existing processor
If you want to modify an existing processor you can follow these simple steps:
- clone the repository of the processor in your working directory. Look into the following repositories:
- modify it
- compile it following these steps:
- create a BUILD directory separated from the sources
mkdir BUILD; cd BUILD
- create the make files:
cmake -C $ILCSOFT/ILCSoft.cmake -DBOOST_INCLUDEDIR=/usr/include/boost173 -DBOOST_LIBRARYDIR=/usr/lib64/boost173 ../
- compile it as usual (this create a library under the
libdirectory)make
- create a BUILD directory separated from the sources
- modify the MARLIN_DLL variable: you have to remove the old library path and add the new ones (this variable can not store duplicate libraries)
Creating a new processor
A script has been prepared to easily create a new processor, for details see here.
As first step copy the script in your working directory:
cp /opt/ilcsoft/v02-01-pre/Marlin/v01-17/examples/copy_new_Processor.sh .
Fix the "basic_folder" path in the script at line 9 (check the right Marlin version) and also another bug:
sed -i 's/v01-12/v01-17/g' copy_new_Processor.sh
sed -i 's|inform=.*|inform="export MARLIN_DLL=\${MARLIN_DLL}:${DIR}/lib/lib${PROJECTNAME}Processor.so"|g' copy_new_Processor.sh
Run the script with the name of the new processor. Usage: ./copy_new_Processor.sh [old_processor new_processor]. As you can see this script does a copy of an exist processor, so you have to use the given basic example.
First you need to export a variable with the name of the processor and then call the script as in this example. Note that the final name of the processor should be: ${PROJECTNAME}Processor
export PROJECTNAME=FirstExample
./copy_new_Processor.sh /opt/ilcsoft/v02-01-pre/Marlin/v01-17/examples/mymarlin ${PROJECTNAME}Processor
This script creates a directory (in the example FirstExampleProcessor) with the code for a very basic processor. It also modifies your .bashrc file adding the new setting for the MARLIN_DLL variable, but as reported if you use another shell, you should set it by yourself!
source ~/.bashrc
At this point you have a new running processor. You can modify the sources in the FirstExampleProcessor/src directory and then recompile it just giving make and make install from the FirstExampleProcessor/build directory.
To test it first verify that the library has been recognized, so look for the name of the processor in the output of the command:
Marlin -x > xml/mysteer.xml
You should find at the begin of the file mysteer.xml a line starting with <!-- Loading shared library : end ending with the path of the new installed library (in the previous example you should find libFirstExampleProcessor.so).
In this file you find also the basic configuration of the processor:
<processor name="MyFirstExampleProcessor" type="FirstExampleProcessor">
<!--FirstExampleProcessor does whatever it does ...-->
<!--Name of the MCParticle collection-->
<parameter name="CollectionName" type="string" lcioInType="MCParticle">MCParticle </parameter>
<!--verbosity level of this processor ("DEBUG0-4,MESSAGE0-4,WARNING0-4,ERROR0-4,SILENT")-->
<!--parameter name="Verbosity" type="string">DEBUG </parameter-->
</processor>
Add you processor to the execute section at the beginning of the file:
<execute>
<!--processor name="MyEventSelector"/-->
<!--if condition="MyEventSelector"-->
<processor name="MyAIDAProcessor"/>
<processor name="MyTestProcessor"/>
<processor name="MyFirstExampleProcessor"/>
<processor name="MyLCIOOutputProcessor"/>
<!--/if-->
</execute>
And set a valid input file for the global parameter LCIOInputFiles
If you exec Marlin xml/mysteer.xml in the output you should see lines like this one:
[ DEBUG "MyFirstExampleProcessor"] processing event: 0 in run: 0
Docker container
All the software is distributed through a docker container. Images for the Muon Collider software are available at DockerHub
For further details about the Docker setup please refer to the guide
To exec it after download you can for example the following command:
docker
run -ti --rm --env DISPLAY=${DISPLAY} --env USER=${USER} --env
HOME=/home/${USER} --user=$(id -u $USER):$(id -g $USER) -v <your
working directory>:/home/${USER} -v /cvmfs:/cvmfs -w /home/${USER} -v ${HOME}/.Xauthority:/home/${USER}/.Xauthority --net=host --entrypoint /bin/bash infnpd/mucoll-ilc-framework:1.0-centos8
First we define some environment variables used to export the graphical interface: --env DISPLAY=${DISPLAY} --env USER=${USER} --env HOME=/home/${USER}
We define also the local user as the user logged in the container (otherwise you login as root): --user=$(id -u $USER):$(id -g $USER)
We mount some local directories inside the container: -v <your working directory>:/home/${USER} -v /cvmfs:/cvmfs
With the next option we define the working directory inside the container: -w /home/${USER}
The last two options tell the container to share the host’s networking namespace: -v ${HOME}/.Xauthority:/home/${USER}/.Xauthority --net=host
Then you need to source the environment setting:
source /opt/ilcsoft/v02-01-pre/init_ilcsoft.sh