PHysiscs Analyses Software Tools (PHAST)

Installation and use.

Tutorial for AMBER software. 11.05.2021

… the framework for data analysis on the level of mDST

("mini Data Summary Trees").

PHAST is:

● environment for physics analysis code development

● software for access to:

● reconstructed events information

● detectors properties

● tool for:

● mDST processing and filtering

● Visualization

● PHAST also provides output data stream at the stage of eventreconstruction (mDST output in CORAL)

(PHAST web page https://cern.ch/ges/phast)

PHAST is ...

On any computer with C++ compiler and ROOT (http://root.cern.ch)package.

It was tested on:

● multiple Linux platforms with

● gcc compiler versions from 2.95 to 10.1.0

● ROOT versions from 3.00.6 to 6.22.0

● MacOS (10.10 with clang-700.0.72 compiler and ROOT v.6.10)

Where PHAST could be installed

mDST content

mDST is a ROOT file. It contains:

Event dependent information (tree of objects of class PaEvent):

Tracks

Vertices

Calorimeter clusters

Hits (stored “on request”)

Raw information (so called DAQ digits. Stored “onrequest”)

For MC mDST:

MC tracks MC vertices and MC hits

Event independent information (object of class PaSetup):

Tracking detectors geometry

Calorimeters geometry

RICH geometry

Magnetic field maps

Material maps

How-To Install(on lxplus.cern.ch using “bash”)

1) . /cvmfs/sft.cern.ch/lcg/views/LCG_99/x86_64-centos7-gcc10-dbg/setup.sh

(one of available “standard” environments for definition of ROOT and g++)

2) take tar-file from http://cern.ch/ges/phast/releases/ or

git clone https://uid@gitlab.cern.ch/compass/phast.git

(uid is your CERN user ID)

3) cd phast

4) ln -s Makefile.lxplus_centos7 Makefile

5) touch NO_FORTRAN (to switch off CERNLIB and Fortran code unless you really need it)

6) make

7) ./phast

(Just for test. If everything was OK it should prints PHAST options help)

How-To inspect mDST content(using Event Display)

Let’s take an example of AMBER MC mDST (Thanks to Catarina Quintans):

● go to https://cernbox.cern.ch/index.php/s/5zwEWf6vuhtTyg1 (pwd: ‘amber’)

● download mdst_amber_preliminary_run002.root file

● run PHAST:

./phast -g mdst_amber_preliminary_run002.root

Please note: Phast has to be compiled with activatedgraphics code:

● touch WITH_GRAPH

● make clean

● make

Context menus

Right mouse click on background invoke context menu withfirst section which extends standard ROOT menu.

Currently this menu has following items: Zoom,ZoomBack, ZoomReset, Locate, LocateOpGL,Move, Ruler, FixedCoord, FixedCoordReset

Almost all drawn objects are “inspectable”: If to point to “inspectable” object cursor is changing. In this

case right mouse click shows context menu, specific forthis object.

Menu item with name xxxInfo will print information aboutxxx object in the terminal (where ./phast was started)

Currently xxx is: Track, Hit,Vertex, CaloClus, Detector,MCTrack, MCHit, MCVertex

ROOT GL viewer of GDML geometry, stored in mDST

How-To inspect mDST content(using “dump”)

./phast -d mdst_amber_preliminary_run002.root | less

will “dump” content of this mDST events (a lot):

######################################## Event 1 ########################################

======> Run # 284943 Spill # 1 Event-in-Spill # 1 Trigger(s): < 3 > +++++++++++++++++++++++------ MC Trigger simulation information: (N elements = 1) 0x0 +++++++++++++++++++++++------ MC Vertex # 0 -------- [primary] X/Y/Z = -1.7506 -0.0977025 -234.698 Mother track -1 Beam track 0 N daughter MCtracks 15 #s : 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 ------ MC Vertex # 1 -------- X/Y/Z = -1.62625 -0.377332 -217.998 Mother track 8 N daughter MCtracks 12 #s : 15 16 17 18 19 20 21 22 23 24 25 26 ------ MC Vertex # 2 -------- X/Y/Z = -1.62626 -0.377335 -217.998 Mother track 23 N daughter MCtracks 1 #s : 27 ……………………… etc.

------ MC Track # 0 --------<Pion- > [ beam ] : -182.814 [GeV] : 11 MChits : 1 MChits ignored (10 det. hits) Mother vertex # 0 Daughter vertices : 44 Associated reco. track(s): 0 Hitmap: 3b73 0 0 0 0 0 0 0 0 0 11 associated original MC hits: 0 1 2 3 4 5 6 7 8 9 26 11 all associated MC hits: 0 1 2 3 4 5 6 7 8 9 26 ------ MC Track # 1 --------<Muon + > [ mu' ] : +4.60816 [GeV] : 10 MChits : 7 MChits ignored (3 det. hits) Mother vertex # 0 Daughter vertices : 35 Hitmap: 2110000 0 0 0 0 0 0 0 0 0 10 associated original MC hits: 10 11 12 27 48 88 108 129 160 185 10 all associated MC hits: 10 11 12 27 48 88 108 129 160 185

……………………… etc.

How-To inspect mDST content(cont’d)

……………………… etc.

------ MC Track # 81 --------<Electron> : -0.000358128 [GeV] : 0 MChits : 0 MChits ignored (0 det. hits) Mother vertex # 44 +++++++++++++++++++++++------ Particle # 0 -------- (-) [beam] has reference to: Track # 0 Vertex # : 0 ------ Particle # 1 --------<Muon - > has reference to: Track # 1 Vertex # : 0 Calo. Clust. # : 0 1 +++++++++++++++++++++++*----- Vertex # 0 -------- [primary] [CORAL's best] Chi2 = 1.11058 Z = -219.108 +- 46.97 [cm] X = -1.752 +- 0.06039 [cm] Y = -0.1072 +- 0.05864 [cm] Incoming particle : 0 Outgoing particles: 1 ( mu' ID not performed ) +++++++++++++++++++++++------ Track # 0 -------- N hits = 10 N TPar = 2 Part. # 0 Z first = -448.1 Z last = -448.1 Z min = -748.4 Z max = -448.1 chi2tot = 7.423 X/X0 = 0.1124 meanTime = -0.4453 +- 0.1897 NDF = 5 Mom. = -190 GeV Field Integ. = -0 T*m SM1 f.i. / Total f.i. = 100 %) ref. to MC = 0 Expected hits: 3bf3 0 0 0 0 0 0 0 0 0 0 0 0 chi2tot = 57.66 X/X0 = 100.5 meanTime = 0.1648 +- 1.269 NDF = 68 Mom. = -71.73 GeV Field Integ. = -5.24 T*m SM1 f.i. / Total f.i. = 1.811 %) ref. to MC = 2 RICH : 0 0 0 0 0 0 0 0 0 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 Expected hits: 0 0 3c03c00 c0000000 fe0007fb e3f0000 80100387 6978e1ff eb4bd 0 0 0 0 Found hits: 0 0 3c03c00 c0000000 fe0007fa e3f0000 80100387 6968e1fb ea4bd 0 0 0 0 270 271 273 274 277 278 279 280 281 282 283 285 286 288 289 290 291 294 296 297 300 301 303 304 305 307 308 310 312 315 316 317318 +++++++++++++++++++++++------ Calo. Clus. # 0 --------EC02P1__[ 1]: Size = 2, E = 7.31, X,Y,Z = 70.9, -12.1, 3317.2 Uncorrected: E = 7.309 X = 70.86 Y = -12.06 Time =0.01119 Particle(s): 1 ------ Calo. Clus. # 1 --------HC02P1__[ 3]: Size = 1, E = 1.71, X,Y,Z = 80.4, -12.1, 3540.3 Time = 0.01163 Particle(s): 1 +++++++++++++++++++++++------ MC Hit # 0 -------- MC track # 0 X = -1.51 Y = 0.06 Z = -748.37 in FI01X1__ Px = -0.08 Py = -0.06 Pz = 183.06 T = 8.561e-08 (ns) ELoss = 0.2366 [KeV]------ MC Hit # 1 -------- MC track # 0 X = -1.51 Y = 0.06 Z = -746.77 in FI01Y1__ Px = -0.08 Py = -0.06 Pz = 183.06 T = 1.823e-07 (ns) ELoss = 7.0720 [KeV]------ MC Hit # 2 -------- MC track # 0 X = -1.54 Y = 0.04 Z = -675.00 in FI04X1__ Px = -0.08 Py = -0.06 Pz = 183.06 T = 4.507e-06 (ns) ELoss = 10.9231 [KeV]

……………………… etc. z

How-To do analysis

● User’s code for data analysis has to be embedded into so called“UserEvent” function. This function will be called by Phast in the loopover events.

● It is a function void UserEventXXX(PaEvent& e) (where XXXis unique integer) which has to be put into ./user/ directory as afile with any name and extension .cc

● make command automatically compiles all code in ./user/

● Which UserEvent function(s) has to be called by Phast is controlled by-uXXX command line option (could be more than one) E.g.

● ./phast -u1234 -u5678 mDST.root will callUserEvent1234(PaEvent&) andUserEvent5678(PaEvent&)functions for every event, stored in‘mDST.root’ file

● In the ./user/ directory there are number of examples, which couldbe used as starting point for your code development.

How-To do analysis(example)

● ./phast -u20 mdst_amber_preliminary_run002.root

● This will call event-by-event function UserEvent20 defined in the file ./user/u20_MC_pulls.cc

● At the end of job file hist.root will be created. It is the file withhistograms / root-tries booked and filled in UserEvent functions.

● Histograms could be viewed by standard ROOT browser:

● root hist.root

● root [1] new Tbrowser

● go to ROOT files

● go to hist.root file

● go to UserEvent20 directory

How-To do analysis(example)

● Histograms created in UserEvent20 could be plotted by script:

root hist.root ./rootscripts/pulls.C

● As a result, “pulls” ( ) for reconstructed MC tracks andvertices will be plotted

P pull=P true−Preco

σreco

How-To do events filtration(UserEvent example)

#include "PaEvent.h"

void UserEvent12345(PaEvent& e){

// At least one primary vertex was reconstructed int iv = e.iBestPrimaryVertex(); if(iv == -1) return; // no primary vertex // N secondary tracks == 2 const PaVertex& v = e.vVertex(iv); if(v.NOutParticles() != 2) return;

// Total charge of tracks in the primary vertex == 0 int Qsum = 0; for(int i = 0; i < v.NOutParticles(); i++){// loop over particles int ip = v.iOutParticle(i); const PaParticle& p = e.vParticle(ip); if(p.Q() == -777) return; // charge is not known Qsum += p.Q(); } if(Qsum != 0) return;

e.TagToSave(); // <=== tag this event to be saved on output };

Documentation on classes (PaEvent, PaVertex, PaParticle etc.) is here:http://cern.ch/ges/phast/doxygen-html/annotated.html

How-To do events filtration./phast -u12345 -o uDST.root mdst_amber_preliminary_run002.root

=============================

____ __ __ /\ _`\ /\ \ /\ \__ \ \ \L\ \ \ \___ __ ____\ \ ,_\ \ \ ,__/\ \ _ `\ /'__`\ /',__\\ \ \/ \ \ \/ \ \ \ \ \/\ \L\.\_/\__, `\\ \ \_ \ \_\ \ \_\ \_\ \__/.\_\/\____/ \ \__\ \/_/ \/_/\/_/\/__/\/_/\/___/ \/__/

Input file(s) : # 1 mdst_amber_preliminary_run002.rootHistograms : hist.rootOutput file : uDST.rootUser routine(s): 'UserEvent 12345' will be called

==============================================================

1 'mdst_amber_preliminary_run002.root'... file contains 14997 events from 1 run(s) processing ...................................................

==============================================================

Number successfully opened input files : 1 (out of 1)Number of events in opened input files : 14997Number of processed events : 14997Number of events saved to output : 6414Number of processed spills : 1Data volume had been read : 588145 Kb (40158 bytes per processed event)Data volume had been written: 238401 Kb (38060 bytes per written event)

[Run] : Nevents[284943] : 14997;

CPU time (utime+stime) = 3.27932 [ms] per event

========= End of Job ========

How-To Install CORAL for MC data processing(only if you want to produce mDST yourself)

1) mv .bashrc bashrc.bck (to start from original bash environment)

2) bash (start new shell)

3) git clone https://uid@gitlab.cern.ch/compass/coral.git (uid is your CERN user ID)

4) cd coral

5) . /cvmfs/compass-mc.cern.ch/sw/tgeant/TGEANT_2021-04-09_gcc6.3/environment.sh

6) export CERN=/cvmfs/sft.cern.ch/lcg/external/cernlib/2006a

7) export CERN_LEVEL=x86_64-slc6-gcc47-opt

8) ./configure --disable-ZEBRA --enable-shared

9) source ./setup.sh

10) make -j8

here compilation of CORAL libraries starts. If it ends without errors then one has to link libraries withPHAST:

How-To link CORAL and PHAST

To be able to produce mDSTs, CORAL libraries has to be linked with PHAST. To do this:

11) Install PHAST:

1) git clone https://uid@gitlab.cern.ch/compass/phast.git or take tar-file

2) cd phast

3) ln -s Makefile.lxplus_centos7 Makefile

4) make -j8

12) cd coral

13) make -j8

14) ./coral.exe trafdic.tg.2018.opt

15) trafdic.tg.2018.opt file is an example of options file to run CORAL+PHAST

with DY MC data for COMPASS 2018 setup.

About mDST related options see README in this ./coral/ directory of PHAST

PHAST graphics in CORAL

For CORAL linked with PHAST1 Event Display could beactivated by following line, added to CORAL option file:

PHAST EvDis

In this case, such information as all hits, all track smoothingparameters etc. are available for visualization

1 CORAL has to be compiled in “shared libraries” mode ( ./configure --enable-shared )

Any questions are welcome.Send them to ...

amber-software@cern.ch or directly to me: ges@cern.ch

Thanks for your attention