LCIO - Users manual
Contents
1. LCIO Event data entities Tracker Hit MC Particle Tracker Hit FENTEndpont const nt getPosition const double BITCreatedinSimulation const int getCovMatrin const FloatVec amp BITEackscatter const int tere L t float BiTvertexis NotEndpointOfParent const int CR getTime float BITDecayedinTracker const int PS BITDecayedinCalorimeter const int GE LEE Le GE LCObiect BiTLettDetector const int Geer erter Lora int BITStopped const int GetdEd float HgetTime noat HEET L getTime float hate deet TaT HgetEnergy float getMCParticle const MC Particle Een an ne getParents const MCParticleVec amp Kei di getRawDataWord int Gas getDaughters const MCParticleVec amp fegettType int H get Number OfParents int LOST getDG float HgetParent MCParticle get Phi float HgetPDG int FLORENT getOmega float cetGenerator Status int Leben LC Obiect getZ0 float Keess eg i getTo LCObiect getTanLambda float Ee een DEE zeen Ke vertexlsNotEndpointOfParent boot D e irons ba isDecayedintracker boot re SimCalorimeter Fn OR getChi2 float isDecayedinCalorimeter bool b getCeliD0 int Here a Big hasLeftDetector booi getCeliD10 int Raw Calorimeter Hit Dee een getdEdx2. we created the event so we need to delete it delete evt A The last line is of course only relevant for C 3 8 3 LCIO Memory management in C The philosophy of memory management in LCIO is If you created the object using new you are responsible for deleting it when it is no longer needed 16 In order to make this easier the LCEvent will delete everything that has been attached to the event If you are only reading LCIO will create the objects and thus delete them when reading the next object of the same type thus no need for deleting on your side If you are reading and adding sth to the event it is LCIO that deletes the event as it created it and thus also everything attached to it again no need for deleting on your side As a rule of thumb Use delete evt runhdr at the end of every event run loop where you created the event runHeader and don t use delete in all other cases Of course if you use your own implementation of the EVENT interface you are also responsible for the memory management 3 9 The Fortran Interface The Fortran API of LCIO is based on a set of wrapper functions to the C implementation using cfrotran h to create the correct Fortran name The main idea is that we use integers in Fortran to represent pointers to objects on the C side There will be one wrapper function for every class method of the implementation classes namespaces IMPL and IO plus two additi
3. lercpcreate lcrcpdelete prcp lcrcpsettype prep itype lcrcpsetmomentum prep xmomv lcrcpsetenergy prcp energy lcrcpsetcovmatrix prcp covmxv lercpsetmass prep xmass lcrcpsetcharge prcp charge lcrcpsetreferencepoint prcp refpointv lcrcpsetgoodnessofpid prcp goodns lcrcpaddparticleid prep pid lcrcpaddparticle prcp pparticle weigth lcrcpaddcluster prcp pclus weigth lcrcpaddtrack prep ptrack weigth lercpid prep lcrcpgettype prcp lercpisprimary prep lprim lcrcpgetmomentum prcp xmomv lcrcpgetenergy prcp lctrkgetcovmatrix prcp covmxv lcrcpgetmass prcp lcrcpgetcharge prcp lercpgetreferencepoint prcp refpointv lcrcpgetgoodnessofpid prcp lcrcpgetparticleids prep lcercpgetparticles prcp lcrcpgetclusters prcp lcrcpgettracks prcp type logical lcpidcreate lcpiddelete ppid lcpidsettype ppid idtype lcpidsetpdg ppid ipdg lcpidsetlikelihood ppid xlogl lcpidsetalgorithmtype ppid itype lcpidaddparameter ppid param lcpidid ppid lcpidgettype ppid lcpidgetpdg ppid lcpidgetlikelihood ppid lcpidgetalgorithmtype ppid lcpidgetparameters ppid paramv nparam lemcpcreate lcmcpdelete pmcp lcmcpaddparent pmcp pmcpp lcmcpsetpdg pmcp ipdg lcmcpsetgeneratorstatus pmcp istatus lcemcpsetsimulatorstatus pmcp istatus lemcpsetvertex pmcp dvtxv lcmcpsete
4. float HisStanped booi legetEneray oat Le Fett Zi getdEdxError float HsetCreatedinSimulation void getPosition const float Raw Calorimeter HIC haies v cetRadius OfinnermostHit float setBackscatter void J getNMCParticles int Gold int Mt corel to getSubdetector HitNNumbers const Intvec amp setVertexlsNotEndpoint OfParentt void getEnergy Conte float RENE Leet const TrackVec setDecayedinTracker void i getAmplitude int RK setDecayedinCalorimeter void battere tee eg getTimeStamp int get Tracker Hits const Tracker HitVec amp setHasLeftDetector void getParticleCont MCParticle setStopnedt void getVertex const double getEndpoint const double getMomentum const float getMass float Easter getCharge float Chuster ReconstructedParticle getNumber OfDaughters int Lettre int getDaughter MCParticie fegetenergy float FesonstructedParticie getPosition const float toetType int qetPositionError const FloatVec amp Pt Boal e is getlTheta float getMomentum const float TO Obiect Kefir A0 L tfreo float RTE Generic Obiect HgetDirectionError const Fioatvec amp 9etCovMatrix const FoatVec 8 getNint int HgetShape const Floater amp HgetMass float Eer et getPartieiDs const ParticlelDVec amp HgetCharge oat g Kater Lotte const Cl
5. id getCellID getTime getCharge getQuality getNRawDataWords getRawDataWord class TrackerHit create delete status status status status status icellid dposv i fpv i pathl fdedx fedep ftime pmcp 5 pschit status status status status status status id icellid0 icellidi energy status number pmcp CG energy time ipdg pehit status status status status status status status status id icellidO icellidi energy status time itype prawhit pthit status status status status status status id icellid time charge iquality nraw iword ptrhit status lcsthsettime pthit ftime lcsthsetmcparticle pthit pmcp lcsthsetmomentum pthit fpv lcsthsetmomentumxyz pthit px py pz lcsthsetpathlength pthit pathl lesthgetcellid pthit lcsthgetposition pthit i i 1 2 3 lcsthgetmomentum pthit i i 1 2 3 lcsthgetpathlength pthit lesthgetdedx pthit lcsthgetedep pthit lcsthgettime pthit lesthgetmcparticle pthit leschcreate lcschdelete pschit lcschsetcellidO pschit icellidO lcschsetcellidi pschit icellidi lcschsetenergy pschit energy lcschsetposition pschit posv lcschaddmcparticlecontribution pschit pmcp energy time ipdg lccahid pschit lcschgetcellidO pschit leschgetcellidi pschit lcschgetenergy
6. LCFactory getInstance gt createLCReader or in Java LCReader lcReader LCFactory getInstance createLCReader The factory pattern is used to hide the concrete implementation of the data format see 3 6 from user code Now opening and closing a file is as simple as 1lcReader gt open my_data slcio here we can read sth from the file 1lcReader gt close As described in the section on exceptions 3 1 1 you could enclose the above code or parts of it in a try catch block e g try 1lcReader gt open my_data slcio UL vas 1lcReader gt close 12 catch I0Exception amp eil cout lt lt Unable to read and analyze the LCIO file lt lt e what lt lt endl if you want to do anything else in your application after what would have been done in failed Here is the corresponding Java code 1lcReader open my_data slcio do sth 1lcReader close It is obviously straightforward to get the Java version of the code from the C one so we only give example code in C from now on 3 7 2 Reading from the file There are two different ways of reading data from an LCIO file One is via readNext Something methods where Something is either the next RunHeader or the next Event This way the user has control over what is being read from the file On the other hand you can only read one type of records at a time as you don t know the exact
7. gt getQuality ki getRawHits gt class Track create gt delete gt setTypeBit gt setOmega gt setTanLambda gt setPhi gt setDO gt setZO ki setCovMatrix gt setReferencePoint gt setChi2 ki setNdf gt setdEdx gt setdEdxError gt setRadiusOfInnermostHit gt addTrack s addHit gt subdetectorHitNumbers gt id gt getType ki getOmega gt getTanLambda gt getPhi gt getDO ki Set 20 gt getCovMatrix gt getReferencePoint ki getChi2 gt getNdf gt getdEdx ki getdEdxError gt getRadiusOf InnermostHit gt subdetectorHitNumbers gt getTracks ki getTrackerHits ki class Cluster create gt delete gt setTypeBit gt setEnergy gt setPosition gt setPositionError gt setITheta gt setIPhi gt setDirectionError gt setShape Ge addParticleID gt addCluster gt addHit gt setsubdetectorEnergies gt id gt getType gt getEnergy ki Set Position gt status status status status status status status status status id status status dedx edep edeperr time itype iquality prawhv ptrk status status status status status status status status status status status status status status status status status id itype omega tanlam phi do z0 status status chi2 ndf dedx dedxerr radius status ptrackv ptrhitv pclu status status status status status status status status status status
8. in the first part of Appendix B under utility e the function name ends on the full lowercased name of the class method e g LCEventImp1 getRunNumber becomes lcevtgetrunnumber e the constructor and destructor of the class end on create and delete respectively eg lcevt delete e All constants defined in Event LCIO are defined as constants in Fortran with the same name prepended by LCIO_ e g the type name for MCParticles defined in C in LCIO MCPARTICLE is defined in a character constant in Fortran named LCIO MCPARTICLE see the Fortran include file lciof77apiext inc Additional methods to handle string int and float vectors from Fortran are provided for the user extension classes LCIntVec LCFloat Vec LCStringVec lcivcgetlength lcivegetintat 17 C class f77 acronym CalorimeterHitImpl cah ClusterImpl clu LCCollectionVec col LCEventImpl evt LCGenericObjectImpl gob MCParticlelmpl mcp LCObject Vector obv ParticleIDImpl pid ReconstructedParticleImpl rcp LCReader rdr LCRelationImpl rel LCRunHeaderImpl rhd LCRelationNavigator rnv SimCalorimeterHitImpl sch Sim TrackerHitImpl sth TPCHitImpl tph TrackerHitImpl trh TrackImpl trk LCWriter wrt LCVec STL vector 22 Table 2 Three letter acronyms for f77 wrapper functions Icfvcgetlength Icfvcgetfloatat Icsvcgetlength lcesvcgetstringat and for the stl
9. ptrk lctrkgetdedx ptrk lctrkgetdedxerror ptrk lctrkgetradiusofinnermosthit ptrk lctrkgetsubdetectorhitnumbers ptrk intv nintv letrkgettracks ptrk letrkgettrackerhits ptrk lcclucreate lccludelete pclu lcclusettypebit pclu ibit ival lcclusetenergy pclu energy lcclusetposition pclu posv lcclusetpositionerror pclu poserrv lec lec usetitheta pclu theta usetiphi pclu phi lcclusetdirectionerror pclu direrrv lcclusetshape pclu pshapev lcc uaddparticleid pclu ppid lccluaddcluster pclu pcluadd lccluaddhit pclu pcalhit weight lec usetsubdetectorenergies pclu energiesv nenergies not in C API lccluid pclu lcclugettype pclu Lee ugetenergy pclu lcclugetposition pclu posv 28 getPositionError ki getITheta gt getIPhi gt getDirectionError ki getShape gt getParticleIDs ki getClusters ki getCalorimeterHits gt getSubdetectorEnergies gt getHitContributions gt status theta phi status pshapev ppidvec pcluget pcalhv pfloatv status class ReconstructedParticle create gt delete gt setType gt setMomentum gt setEnergy gt gt setCovMatrix setMass 2 gt setCharge gt setReferencePoint gt setGoodnessOfPID gt addParticleID gt addParticle gt addCluster gt addTrack gt id ki getType ki isPrimary gt getMomentum gt getEnergy gt getCovMatrix
10. status getFloatVector gt status getStringVector gt status hepevt21cio pevent LCIntVec LCFloatVec LCStringVec lcintvectorcreate intv nint lcfloatvectorcreate floatv nfloat lcstringvectorcreate stringsv nstrings len stringsv 1 lcgetintvector pvec intv nintv legetfloatvector pvec floatv nfloatv lcgetstringvector pvec stringv nstringv len stringv 1 for the stl vector class int float string pointer IntVectorCreate gt IntVectorDelete gt FloatVectorCreate gt FloatVectorDelete gt StringVectorCreate gt StringVectorDelete ki PointerVectorCreate gt PointerVectorDelete gt getIntVector gt getFloatVector ki getStringVector gt get PointerVector ki pveci status Duech Status pvecs status pvecp status status status status status intvectorcreate intv nintv intvectordelete pveci floatvectorcreate floatv nfloatv floatvectordelete pvecf stringvectorcreate stringsv nstrings len stringsv 1 stringvectordelete pvecs pointervectorcreate pointerv npointerv pointervectordelete pvecp getintvector pveci intv nintv getfloatvector pvecf floatv nfloatv getstringvector pvecs stringv nstringv len stringv 1 getpointervector pvecp pointerv npointerv 31 References 1 LCIO A persistency framework for linear collider simulation studies By Frank Gaede DESY Ties Behnke DES
11. status status status id itype energy status lctrhsetposition ptrhit dposv lctrhsetcovmatrix ptrhit covmxv lctrhsetdedx ptrhit dedx lctrhsetedep ptrhit edep lctrhsetedeperr ptrhit error lctrhsettime ptrhit time lctrhsettype ptrhit itype lctrhsetquality ptrhit iquality lctrhaddrawhit ptrhit prawh lctrhid ptrhit lctrhgetposition ptrhit dposv lctrhsetcovmatrix ptrhit covmxv lctrhgetdedx ptrhit lctrhgetedep ptrhit lctrhgetedeperr ptrhit lctrhgettime ptrhit lctrhgettype ptrhit lctrhgetquality ptrhit lctrhgetrawhits ptrhit lctrkcreate lctrkdelete ptrk lctrksettypebit ptrk ibit ival lctrksetomega ptrk omega lctrksettanlambda ptrk tanlambda lctrksetphi ptrk phi lctrksetd0 ptrk dO lctrksetz0 ptrk z0 lctrksetcovmatrix ptrk covmxv lctrksetreferencepoint ptrk refpointv lctrksetchi2 ptrk chi2 lctrksetndf ptrk ndf lctrksetdedx ptrk dedx lctrksetdedxerror ptrk dedxerr lctrksetradiusofinnermosthit ptrk radius lctrkaddtrack ptrk ptrack lctrkaddhit ptrk phit lctrksetsubdetectorhitnumbers ptrk intv nintv mot in C API lctrkid ptrk lctrkgettype ptrk lctrkgetomega ptrk letrkgettanlambda ptrk lctrkgetphi ptrk lctrkgetd0 ptrk lctrkgetz0 ptrk lctrkgetcovmatrix ptrk covmxv lctrkgetreferencepoint ptrk refpointv lctrkgetchi2 ptrk lctrkgetndf
12. i 1 lccolgetflag pcol lecolistransient pcol number lcrelcreate0 lcrelcreate pobjectfrom pobjectto weight lcreldelete prel lcrelsetfrom prel pobjectfrom lcrelsetto prel pobjectto lcrelsetweight prel weight lcrelid prel lcrelgetfrom prel lcrelgetto prel lcrelgetweight prel lcobvgetlength pobjv pobjv pfrom pto lcobvgetobject pobjv i i 1 nelem lcobvgetobjectid pobjv i i 1 nelem lcobvgetweight pobjv i i 1 nelem lcrnvcreate fromname toname lcrnvcreatefromcollection pcol lcrnvdelete lcrnvgaddrelation prel pobjectfrom pobjectto weight lcrnvgremoverelation prel pobjectfrom pobjectto lcrnvcreatecollection prel lcrnvgetfromtype prnv getRelatedFromWeights gt pweightv class LCGenericObject create gt pgob create dimensions gt pgob delete gt status setIntVal gt status setFloatVal gt status setDoubleVal gt status id gt id getNInt gt nint getNFloat gt nfloat getNDouble gt ndouble getIntVal gt ival getFloatVal gt fval getDoubleVal gt dval isFixedSize gt bool getTypeName gt name getDataDescription gt string class SimTrackerHit create gt pthit delete gt status setCellID gt status setPosition gt status setdEdx gt status setEDep gt status lcrnvgettotype prnv lcrnvgetrelatedtoobjects prnv pobj lcrnvgetrelatedfr
13. string gt getParameters const LC Parameters amp parameters LC Parameters amp D LCIO Event data model LCCollection BTTransient const int LCCollection get Number OfElements int getTypeName const std string getElement t LC Object get Flag int tisTransient bool addElement void removeElementAt void setFlag void getParameters const LC Parameters amp parameters LC Parameters amp LCParameters LCObiect LCObiect id clone LC Obiect CIE uster en Figure 1 Overview of the event data model defined by LCIO The boxes correspond to classes and the arrows denote relationships between these The main class in LCIO is LCEvent that serves as a container of named collections LCCollection of data objects LCObject AU data that are related to one event is stored in such collections A few example classes are shown see 2 for details on the data entities The LCRunHeader is used to store run related information The class LCParameters can be used to attach keyed parameters of type int float string to either LCRunHeader LCEvent or LC Collection in order to store so called meta data e g the encoding of certain bits in some type word or the order of some parameters in a given array
14. tracking of particle stopped because particle left the world volume e hasLeft Detector True if tracking of particle left the world volume e isStopped True if particle lost all kinetic energy inside world volume and did not decay For the MCParticle only parent relationships are stored When reading the data back from the file the daughter relationships are reconstructed from the parents This is to ensure consistency Care has to be taken when analyzing the particle tree Because a particle can have more than one parent the particle list in fact does not consist of a set of trees one for each mother particle but forms a directed acyclic graph Thus the user has to avoid double counting in his code Of course this only matters at the parton level as real particles have exactly one or no parent 3 2 2 SimCalorimeterHit Generic class for calorimeter hits from a simulation program Typically every calorimeter subdetector will create a collection of this type SimCalorimeterHits have a float energy amplitude and an int cellid and optionally a 3d hit cell position In order to study clustering and reconstruction algorithms there are links to the MCParticles that contributed to the hit There are two different levels of detail foreseen check set the flag LCIO CHBIT_STEP e LCIO CHBIT_STEP 0 normal mode one MCParticle contribution for every MCParticle that contributed to the hit i e there will be only one MCParticle contributi
15. 0fElements gt nelem lcsvcgetlength pstv getElementAt gt colname lcsvcgetstringat pstv i i 1 nelem 25 stl vector Interface stl vector Interface stl vector Interface stl vector Interface class LCCollection create gt pcol delete gt status addElement gt status removeElementAt gt status setFlag gt status setTransient gt status getTypeName gt name getNumber0fElements gt number getElementAt gt pobject getFlag gt iflag isTransient gt bool class LCRelation LCObject create defaults gt prel create gt prel delete gt status setFrom gt status setTo gt status setWeight gt status id gt id getFrom gt pfrom getTo gt pto getWeight gt weight getLength gt nelem getObject gt id getObjectID gt id getWeight gt weight class LCRelationNavigator create gt prnv create from col gt prnv delete gt status addRelation gt status removeRelation gt status createLCCollection gt pcol getFromType gt namefr getToType gt nameto getRelatedToObjects gt pobjvto getRelatedFrom0bjects gt pobjvfr getRelatedToWeights gt pweightv lccolcreate colname 1ccoldelete pcol lccoladdelement pcol pobject lccolremoveelementat pcol i lccolsetflag pcol iflag lccolsettransient pcol bool bool true false lccolgettypename pcol lccolgetnumberofelements pcol lccolgetelementat pcol i
16. LCGenericObject getTypeName and LCGenericObject getDataDescription from const std string amp to const std string to make the implementation easier UTIL LCFixedObject template Added convenience template UTIL LCFixedObject for user defined subclasses of LCGeneri cObjects with fixed size See src cpp src EXAMPLE CalibrationConstant h for example on how to use it Definition of LCEvent get TimeStamp The 64bit event timestamp is defined to be ns since 1 1 1970 00 00 00 UTC Changed C API to use long long 64 bit UTIL LCTime C Helper class to convert between time stamps and calendar time Multiple I O streams in C Support for multiple instances of LCReader and LCWriter objects files added LCIODEBUG flag in C Added LCIODEBUG environment variable to control compilation Changes from v1 0 to v1 3 Tracks Cluster and ReconstructedParticles added These are the main classes for reconstruction output RawCalorimeterHit added A calorimeter hit class for testbeam data that reflects real data more closely than Calorime terHit LCRelation added Can be used to map arbitrary weighted n to m relationships with n m gt 1 LCGenericObject added Support for user defined objects that have an arbitrary number of attributes of type int float and double Added time information to CalorimterHit An optional time word has been added to CalorimeterHit Transient flag added to LCCollection LCCollections can now
17. LCIO Users manual v02 04 F Gaede DESY IT H Vogt DESY Zeuthen Contents 1 INTRODUCTION 2 1 Getting LCIO BEEN 3 Using LCIO 3 1 Java and C APIj 3 2 Data model DK EE 3 5 TrackerPulse oe Re ae 3 7 How to read LCIO files 3 8 How to write LCIO files 4 Real world examples 4 1 Icioframe C Root 12 aida JAVA AIDA 4 3 Iciohbook Fortran Hbook 4 4 pythia Fortran Pythia A ChangeLog A 1 Changes from v1 3 to v1 4 A 2 Changes from v1 0 to v1 3 February 6 2014 B Summary of Fortran API Functions 1 INTRODUCTION Note Some of the latest developments in LCIO are not yet described in this manual However it is still a good starting point if you are new to LCIO as it explains the basic concepts to quite some detail For some of the newer developments and the current versions please refer to the API documentation at http lcio desy de and the discussions in the LCIO forum at http forum linearcollider org LCIO is a persistency framework that defines a data model for the linear collider physics community It is intended to be used in both simulation studies and analysis frameworks Its light weight and portability makes it also suitable for use in detector R amp D applications It provides a C and a Java implementation with a common interface API A Fortran interface to the C implementation is provided as well This manua
18. Y amp SLAC Norman Graf Tony Johnson SLAC SLAC PUB 9992 CHEP 2003 TUKT001 Jun 2003 5pp Talk given at 2003 Conference for Computing in High Energy and Nuclear Physics CHEP 03 La Jolla California 24 28 Mar 2003 e Print Archive physics 0306114 LC Note LC TOOL 2003 053 2 LCIO Homepage 3 SIO documentation http www sldnt slac stanford edu nld new Docs FileFormats sio pd 4 AID Homepage http java freehep org aid index html El Sax Di El Gi en SR B Le og a ttp java sun com j2se javadoc 6 doxygen Homepage ttp www stack nl dimitri doxygen EI a er jam TG ka D ttp root cern ch 8 Pythia Homepage ttp www thep lu se torbjorn Pythia html Er 9 cernlib Homepage http cernlib web cern ch cernlib 10 AIDA Homepage http aida freehep org 11 JAS3 Homepage ttp jas freehep org jas3 index html CMake Homepage http www cmake org 12 32
19. _counter stdhepjob bin lt anajob_F simjob_F recjob_F 2 4 Checking the In http maven apache org download html and then type will create the following libraries and executables Java library and executables C lcio library C sio library C examples and tools f77 examples stallation To check whether the C installation was successful run the simjob program simjob simjob slcio This creates a simple LCIO file that you can read with anajob simjob slcio The same for the Java Linux version runSimJob sh simjob sclio runAnalysisJob sh simjob sclio or for the Java Windows Cygwin version runSimJob bat simjob sclio runAnalysisJob bat simjob slcio In case CMake has been used to build LCIO it is possible to run a small chain of tests by calling make tests amp amp make test 2 5 Building the documentation A few targets are defined to build the documentation see below that is also available from the LCIO homepage 2 see 3 1 If you are using CMake see all documentation can be built and installed by setting the cmake option INSTALL_DOC to ON as follows cmake DINSTALL_DOC ON make install In order to build individual documentation components the following targets may be used make doc lt build all documentation doc_cpp doc_java doc_manual make doc_cpp lt C API documentation needs em doxygen cite ref_doxygen make doc_java lt Java API docum
20. _pointer lcgetparameters class_name class_pointer method_name key_name vector_pointer The vector pointer is given to lcsetparameters and obtained from lcgetparameters and the vector content may be set or obtained by the stl vector wrapper fuctions Methods of the extended Fortran API can be used to create the vectors for the user extension classes LCIntVec LCFloatVec LCStringVec Icintvectorcreate Icfloatvectorcreate Icstringvectorcreate and to fetch the content of a vector Icgetintvector Icgetfloatvector Icgetstringvector to create delete the stl vectors having int float string and pointer datamembers e g needed for the setShape method in the ClusterImpl Class intvectorcreate intvectordelete floatvectorcreate floatvectordelete stringvectorcreate stringvectordelete pointervectorcreate pointervectordelete and to fetch the content of a vector getintvector getfloatvector getstringvector getpointervector The parameters of the functions above are explained in the the second part of Appendix The extended Fortran API to LCIO 3 9 4 Reading and writing LCIO files Examples for reading and writing LCIO files can be found in src f77 simjob F recjob F anajob F To build these examples do gmake C src f77 These examples correspond to that provided in LCIO src cpp src EXAMPLE for C The complete interface is dec
21. act paramter of the track the in the r z plane e tanLambda Lambda is the dip angle of the track in the r z plane at the reference point By default LCIO tracks have the point of closest approach PCA as the reference point But any other point can be chosen at will check isReferencePointPCA A full covariance matrix is stored with every track as the lower triangel matrix of the parameters in the given order Track points back to the hits that have been used in the fit If the hits are not available there is a vector of subdetector hit numbers check set the collection parameter TrackSubdetectorNames to decode the indices Also Tracks can point to other Tracks typically track segments from other subdetectors that have been combined to the track at hand Tracks have a type word where the lower 15 bits can be used to decode the type of the track by the user e g define a bit per subdetector Check Set the collection variables TrackTypeBitNames and TrackTypeBitIndices 10 3 5 4 ReconstructedParticle ReconstructedParticle is the class to be used for every object that is reconstructed ReconstructedPar ticle can be a single particle e g a track with a pion PID or a compound object like a jet made from many particles ReconstructedParticle has lists of Tracks Clusters and ReconstructedParticles that have been combined to form this particle The particle type is encoded in a type word check set the collection parameters ReconstructedParti
22. be flagged as transient for use in applications that have LCEvent as the underlying transient data model 23 Default flag added to LCCollection LCCollections can now be flagged as default lists There should be only one default LCCollection for every type New package UTIL for C A new namespace UTIL has been added to the C version It holds convenient classes and methods that facilitate the handling ov LCIO data Support of CLHEP HepLorentzvector for C For C there is a template LCFour Vector that can be used to create CLHEP HepLorentzvectors from MCParticles and ReconstructedParticles A Java equivalent will added in the next release Added chain reader to LCReader Added a new method LCReader open vector fileNames that allows to specify a list of files that will be read sequentially Made API more consistent A number of methods have been added and or modified to make the API more consistent Some methods that have a new name or calling signature have been marked as deprecated Usdage of those methods will generate a warning please switch to the new methods StdHep Reader Added support for reading binary StdHep files and create an LCCollection of MCParticles See UTIL LCStdHepRdr and EXAMPLES stdhepjob cc 24 B Summary of Fortran API Functions The basic Fortran API to LCIO Remarks The return value of the functions and the meaning of arguments are either pointers denoted by a name beginning with the lette
23. bit pointer tag per hit 3 2 5 CalorimeterHit The CalorimeterHit should be used for final reference to the calorimeter hits i e after calibration clustering etc It has a float energy and optional time word Clusters will have links to objects of type CalorimeterHit 3 2 6 TPCHit Deprecated Please use the new classes for raw tracker data TrackerRawData TrackerData and TrackerPulse 3 3 TrackerRawData Generic class for raw tracker data One or optionally two LCIO TRAWBIT ID1 1 cell ids can be used to decode the readout channel Specific subdetectors will use different encodings e g a silicon vertex detector might use cell DO and cellID1 to encode the module number row and column of the hit An arbitrary number of ADC values can be stored in the hit This can be either a complete spectrum waveform as for a TPC like detector or just one or two consecutive ADC readout values 3 4 TrackerData Same as the TrackerRawData except that the data has been corrected calibrated In particular the calibrated ADC values are stored as floating point charge values with arbitrary i e subdetector specific units 3 5 TrackerPulse Tracker pulse that is typically created from TrackerData by some sort of feature extraction e g for a TPC like detector the pulse will contain the integrated charge of the spectrum and the corresponding time 3 5 1 TrackerHit The TrackerHit serves as a generic hit type that can be used for pattern recogni
24. cleTypeNames and ReconstructedParticleTypeValues ReconstructedParticles have a 4 momentum and for convenience a redundant mass field In general users will want to fill these consistently Typically kinematics is calculated from the most likely PID assigned to this particle ReconstructedParticle also points nack to CLusters and Tracks that have been used to create the particle Users have to make sure that they don t double count when looping over lists of Recon structedParticles LCIO might provide a convenient method to help looping over lists in a future release Reconstruction programs are expected to provide one reasonable list of ReconstructedParticles in the event that serves as a starting point for physics analysis The corresponding LCCollection should be flagged as default and has to fulfill the following requirements e unambigous elements in the list can be combined to compound particles like K but no particle can be used in more than one compound Additional particle hypotheses are supposed to be stored in another list e complete the list should be reasonably complete i e everything seen in the event should have been taken into account to create that list 3 5 5 LCGenericObject Users are free to store additional data in LCIO files that cannot be expressed in terms of the classes that are provided with LCIO To do so it is easiest to implement the interface LCGenericObject in a user defined concrete class In order to writ
25. cription gt status lcrhdsetdescription pheader descrstring addActiveSubdetector gt status lcrhdaddactivesubdetector pheader sdname getRunNumber gt irun lcrhgetrunnumber pheader getDetectorName gt detname lcrhdgetdetectorname pheader getDescription gt string lcrhdgetdescription pheader getActiveSubdetectors by getActiveSubdetectors gt psdvec lcrhdgetactivesubdetectors pheader getNumber0fElements gt pelen lcsvcgetlength psdvec getElementAt gt sdname lcsvcgetstringat psdvec i i 1 nelem class LCEvent create gt pevent lcevtcreate delete gt status lcevtdelete pevent setRunNumber gt status lcevtsetrunnumber pevent irun setEventNumber gt status lcevtseteventnumber pevent ievt setDetectorName gt status lcevtsetdetectorname pevent detname setTimeStamp gt status lcevtsettimestamp pevent ilong addCollection gt status lcevtaddcollection pevent pcol colname removeCollection gt status lcevtremovecollection pevent colname getRunNumber gt irun lcevtgetrunnumber pevent getEventNumber gt ievt lcevtgeteventnumber pevent getDetectorName gt detname lcevtgetdetectorname pevent getTimeStamp gt ilong lcevtgettimestamp pevent getCollection gt peol lcevtgetcollection pevent colname getCollectionNames by getCollectionNames gt pstv lcevtgetcollectionnames pevent getNumber
26. ding on the use case you will need mostly classes from one or two namespaces e g if you need to read data from an existing LCIO file you only need the classes in EVENT If you want to write data with LCIO you have to instantiate the implementation classes provided in IMPL or implement the interface from EVENT 3 1 1 Exceptions Both the Java and C versions of LCIO make use of the exception mechanism Exceptions are implemented differently in Java and Cl For LCIO we adopted a scheme of using exceptions that hides these differences as much as possible All Exceptions except IOException in Java inherit from RunTimeException i e are unchecked exceptions Thus the compiler will in general not complain about missing catch blocks or throw declarations The same holds true for the C compiler anyhow 1The Java Exception mechanism is more powerful in that it offers compile time check of correct try catch blocks or throw clauses and the notion of unchecked and checked exceptions In the API you will find throw clauses declarations at certain methods These are meant as a hint to the user of what could go wrong in the method at hand do not try to catch all exceptions with a dedicated try catch block around every function call Most exceptions will be due to programming errors and will cause an abort of the program when not caught by the user which is usually what you want There are exceptions to this rule however In particular the DataNo
27. e data simply create instances of this class and add them to an LCCollection that in turn is added to the LCEvent When reading back this information users are free to instantiate objects of the user class type via copy constructor or simply access the information through the LCGenericObject interface For C a template for LCGenericObjects with fixed size LCFixedObject lt int nint int nfloat int ndouble gt is provided in the UTIL namespace Users have to provide minimal code by inheriting from this class 3 5 6 LCIntVec LCFloatVec and LCStringVec Simple user extension data can be stored in LCCollections of vectors of type of float int and string The LCIntVec can also be used to store indices of objects in another collection thus building subcol lections For example one can have a lepton finder that returns lepton candidates as a list of indices that point into the LCCollection of type Track that was given to finder 3 5 7 LCRelation As described above some LCIO classes have built in links relations to other classes e g tracks point back to hits LCIO intentionally does not define such links to point back from reconstructed objects to Monte Carlo truth information in order to allow a clean development of tools that could run on real data Using the LCRelation one is still able to make such relations for simulation data In general LCRe lation can be used to store a weighted many to many relationship between objects of two arb
28. em int nelem float nelem string nelem pointer intvectorgetlength pintvec intvectorgetelement pintvec i i 1 nelem floatvectorgetlength pfloatvec floatvectorgetelement pfloatvec i i 1 nelem stringvectorgetlength pstrvec stringvectorgetelement pstrvec i i 1 nelem pointervectorgetlength ppointervec pointervectorgetelement ppointervec i i 1 nelem 30 The extended Fortran API to LCIO Remarks The return value of the functions and the meaning of arguments are either EE reals else pointers denoted by a name beginning with the letter p character strings denoted by name or string integers denoted by status or a variable name starting with i orn double precision variables denoted by a name starting with d arrays denoted by a name ending with v If arguments of the type array of character strings are used the last argument has to be the length of a character string in the array Integers starting with n are also used to give the length of an array input output argument for get functions input dimension of the array output number of values stored for class LCReader lcrdropenchain gt for class LCRunHeader writeRunHeader gt readNextRunHeader gt for class LCEvent setEventHeader gt getEventHeader gt dumpEvent ki dumpEventDetailed ki for class SimTrackerHit addSimTrackerHit getSimTrackerHit gt gt status lcrdrope
29. ementation event that LCIO provides These are also used in the following examples The principle steps involved are create an instance of the implementation class set the attributes and then call the corresponding write method of the LC Writer interface For example writing the run header is done with LCRunHeaderImpl runHdr new LCRunHeaderImpl runHdr gt setRunNumber rn runHdr gt setDetectorName HCALPPT lcWrt gt writeRunHeader runHdr delete runHdr see below in LCIO Memory management in C The event works in the same way except that we now also need collections the necessary steps are create the event set the event attributes create a collection with type name add objects to the collection and finally add the collection to the event with a unique name LCEventImp1 evt new LCEventImpl create the event evt gt setRunNumber rn evt gt setEventNumber i set the event attributes LCCollectionVec calVec new LCCollectionVec LCIO SIMCALORIMETERHIT create a collection for the type SimCalorimeterHit for int j 0 j lt NHITS j SimCalorimeterHitImpl hit new SimCalorimeterHitImpl hit gt setEnergy 3 1415 bee calVec gt push_back hit add hit objects to the collection D E A ee evt gt addCollection calVec HCalPPTHits add the collection with a name lcWrt gt writeEvent evt write the event to the file _ IMPORTANT
30. entation make doc_refman lt Reference manual make doc_usrman lt User manual If you are not using CMake keep on reading the rest of this section on how to build the documentation with ant You can create the documentation of the Java API with javadoc 5 ant doc and then open the file LCIO doc api index html with your Browser And the current version of this manual is created with ant doc manual as LCI0 doc manual pdf and LC1I0O doc manual ps provided you have latex in your PATH 3 Using LCIO This section gives an introduction on how to use LCIO We describe the user interface the data model and provide some code examples For most of the section we focus on Java and C as these are the main languages supported by LCIO Thanks to the AID 4 tool Java and C hava an API which is generated from a common source and thus very similar The Fortran interface implemented as a wrapper to the C implementation is described in 3 1 Java and C API Detailed documentation of the API is provided both for Java and C on the LCIO homepage 2 generated directly from documentation in the source code using javadoc and doxygen respectively If you are experienced in either Java or C you will probably find most of what you need to use LCIO in the corresponding version of the API documentation However reading the detailed description of the data entities in is probably usefull A few words on the design of LCIO might be hel
31. er common outinfo writer 21 kk some code if wanted Zitt write event status lcwrtwriteevent writer pevent end The 4 subroutines processrunheader modifyrunheader processevent and modifyevent must be provided if the wrapper function lerdreventprocessor is used They are called via the LCRun Listener LCEventListener classes As an expample the code in LCIO src f77 recjob F may be looked at The function lcdumprunheader pheader is part of the extended interface described in 3 9 3 4 Real world examples All the examples described above show how to use LCIO with Java C and Fortran They are build with LCIO and provided as binaries in LCIO bin We also provide some examples that show how to use LCIO with some common physiscs simulation and analysis packages such as Pythia Root and AIDA JAS in LCIO examples javalcpp f771 As these examples depend on external tools and libraries they are not build by default with LCIO Please check the corresponding README files for instructions on how to build these examples 4 1 lcioframe C Root Defines mini framework where you can specify analysis modules at runtime The example modules create a root 7 file with some histograms You can use the provided main program with your own analysis modules and tools 4 2 aida JAVA AIDA This Java example creates an AIDA file from an LCIO file with some histograms and an Ntuple You can use any AIDA compliant analysis to
32. er hit assigned to it and the particle is flagged as a backscatter Thus direct tracker hits for a particular particle can be distinguished from those not actually produced by that particle The generatorStatus and simulatorStatus attributes define the creation and destruction status of the particle where the generatorStatus is defined by the generator program and the simulatorStatus is combined from the following boolean flags e isCreatedInSimulation True if Simulator created particle False if Generator created particle e isBackscatter True if particle created by Simulator as a result of interaction or decay in non tracking region By convention such particles are not saved However if this particle creates a tracker hit the LC Event LCEvent getRunNumber int getEventNumber int getDetector Name const std string amp getTimeStamp long getCollectionMames const std vector lt std string gt getCollection LCCollection addCollection void removeCollection void getParameters const LC Parameters amp parameters LC Parameters amp getRelationMames const std vector lt std string gt getRelation LCRelation acddRelation void removeRelation void LCRunHeader getDetectorName const std string amp getDescription const std string amp getActive Subdetectors const std vector lt std
33. es and types of an unknown LCIO file e casts as LCIO uses untyped collections we have to down cast from LCObject to the corre sponding type i e we need to know the type of the data This is analogous to the Collection interface in Java As C does not provide a common base class we had to introduce LCObject as a common base for event data in LCIO 3 8 How to write LCIO files Some examples for writing data with LCIO can be found in src cpp src EXAMPLE simjob cc recjob cc src java hep 1cio example SimJob java RecJob java 3 8 1 File handling Before you can write to an LCIO file you have to create an instance of LCWriter using LCFactory LCWriter lcWriter LCFactory getInstance gt createLCWriter or in Java LCWriter lcWriter LCFactory getInstance createLCWriter Opening and closing the file is the same as described for the LCReader e g in Java lcWriter open my_data slcio write sth to the file lcWriter close 15 3 8 2 Writing to the file The LCWriter interface only uses the interfaces in EVENT hep lcio event So all classes implementing these interfaces can be written with LCIO This could in principle be used for existing classes in already existing applications eventhough copying the data into instances of the LCIO implementation classes is more convenient If you design a new application in either Java or C you should use the implementation classes IMPL hep lcio impl
34. formation is stored in LCRun Header Run headers events and collections have an instance of LCParameters that allows to attach arbitrary named parameters of types int float or string to either of these objects This mechanism is foreseen to allow storage of meta data e g the name of the algorithm that has been used to create a certain collection The LCCollection has a type word that is used as a flag word where certain bits are used by LCIO to denote some well defined feature of the objects in the collection Typically these flag bit positions are defined as global constants in the class LCIO The following gives a detailed description of the data entities that are defined in LCIO An overview of these classes is shown in figure 3 2 1 MCParticle There will be exactly one collection with name MCParticle in every event that holds the Monte Carlo truth particles as generated by the generator or as added by the simulation program decay in flight Particles that are created during simulation will be added to the existing list of MCParticles Adding particles with their correct lineage ceases when a particle decays or interacts in a non tracking region Otherwise the number of MCParticles explodes in calorimeter shower development All energy depositions are assigned to the initial particle that decayed or interacted in a non tracking region The exception is a particle producing a hit in a tracker This particle is recorded with the track
35. gt getMass gt getCharge gt getReferencePoint ki getGoodnessOfPID gt getParticleIDs SC getParticles ki getClusters gt getTracks ki class ParticleID create gt delete gt setType gt setPDG gt setLikelihood gt setAlgorithmType gt addParameter gt id gt getType gt getPDG ki getLikelihood ki getAlgorithmType a getParameters ki class MCParticle create gt delete y addParent gt setPDG gt setGeneratorStatus gt setSimulatorStatus ki setVertex gt setEndpoint Ce setMomentum 2 gt setMass gt setCharge gt getNumber0OfParents gt getParent gt getNumberOfDaughters gt getDaughter ki Set PDG ex prep status status status status status status status status status status status status status id itype lprim status energy status xmass charge status goodns pids ppartv pclusv ptrkv ppid status status status status status status id idtype ipdg xlogl itype status pmcp status status status status status status status status status status number pmcpp number pmcpd ipdg lcclugetpositionerror pclu poserrv lcclugetitheta pclu theta lcclugetiphi pclu phi lcclugetdirectionerror pclu direrr lcclugetshape pclu leclugetparticleids pclu leclugetclusters pclu lcclugetcalorimeterhits pclu lcclugetsubdetectorenergies pclu lcclugethitcontributions pclu energiesv nenergies not in C API
36. he C version 2 3 1 Building LCIO with CMake If you want to use CMake for building LCIO you need at least CMake version 2 6 If you want to build LCIO using CMake make sure that the cmake command is in your path e g export PATH Path_to_CMake bin PATH Then issue the following commands mkdir build cd build cmake make install lt create an out of source directory for the build check build options change options with cmake DOPTION ON OFF e g to also build the Java version use cmake DINSTALL_JAR ON optionally use ccmake and configure interactively CMake options may also be specified in a separate file and read with the C option please check the CMake 12 documentation for more details ILCSoft cmake is ac It contains the list in this example the path to the ROOT pac cmake C afs desy de DBUILD_ROOTDICT onfiguration file generated for each ilcsoft reference installation of paths from all tools within the installation BUILD_ROOTDICT option from LCIO is activated which requires the kage This path is read from the ILCSoft cmake configuration file project ilcsoft sw i386_gcc41_s15 v01 11 ILCSoft cmake ON 2 3 2 Building LCIO with Maven Download and install Maven mvn clean install Both ways of building LCIO lib lcio jar lt liblcio so lt libsio so lt bin lt anajob copyfix dumpevent readcalibration recjob simjob lcio_event
37. itrary but fixed type LCRelations are stored as any other data entity in an LCCollection For user con venience a LCRelationNavigator is provided in UTIL hep Icio util that allows to quickly navigate the relationships The type of the from and to object are stored in the collection parameters RelationFromType and RelationToType 11 3 6 Data format As a first concrete data format for LCIO we chose to use SIO Serial Input Output 3 SIO has been developed at SLAC and has been used successfully in the hep lcd framework It is a serial data format that is based on XDR and thus machine independent While being a sequential format it still offers some OO features in particular it allows to store and retrieve references and pointers within one record In addition SIO includes on the fly data compression using zlib LCIO files that use SIO i e all current ones have the extension slcio A detailed description of the data layout in the SIO files is given in LCIO doc lcio xml 3 7 How to read LCIO files There are a number of examples in the src directory some examples for reading and accessing data can be found in src cpp src EXAMPLE anajob cc dumpevent cc recjob cc readcalibration cc src cpp src IMPL LCTOOLS cc src java hep 1cio example AnalysisJob java RecJob java LCTools java 3 7 1 File handling Before you can read from an LCIO file you have to create an instance of LCReader using LCFactory LCReader lcReader
38. l is intended for application developers that want to incorporate LCIO in their programs This includes e g simulation developers as well as physicists that want to read LCIO files for their analysis It focuses on the practical aspects of using LCIO A more general discussion can be found in I and other documents listed on the LCIO homepage 2 2 Installation 2 1 Getting LCIO If LCIO is not yet installed at your site you can get a recent copy from the SVN repository as follows bash svn co svn svn freehep org lcio tags v01 60 lcio v01 60 checkout release v01 60 svn co svn svn freehep org lcio trunk lcio trunk checkout trunk 2 2 Requirements In order to build LCIO you need to have a Java VM version 1 4 or higher installed on your platform This is true even if you only want to install the C version as the API files are generated from an abstract description for Java and C using the AID Hi tool The build scripts used in LCIO also require that gcc and gmake make are installed The C version of LCIO is developed and tested under Linux SL4 and SL5 32 and 64bit and also builds under Windows Cygwin or MacOSX As the ansi compiler flag is used it should be fairly easy to port it to other platforms with an ANSI compliant C compiler 2 3 Building LCIO There are two build tools that can be used to build LCIO maven and CMake 12 CMake 12 has been introduced in version v01 11 to facilitate cross plattform support for t
39. lared in the include file LCIO src f77 lciof77api inc A simple example for reading an LCIO file with Fortran is 19 include lciof77api inc include lciof77apiext inc 11 PTRTYPE reader event runhdr integer status irun ievent reader lcrdrcreate status if status eq LCIO_ERROR then goto 99 endif do event lcrdrreadnextevent reader if event eq 0 goto 11 status lcdumpevent event enddo continue lcrdropen reader simjob slcio The function 1cdumpevent event is part of the extended interface described in 3 9 3 Note that all functions that operate on existing objects have as a first argument the integer pointer to this particluar object All functions that do not return a pointer to an object do return a status word instead that can be compared to LCIO_ERROR LCIO_SUCCESS An example how to write a LCIO file from Fortran is writer lcwrtcreate status lcwrtopen writer filename LCIO_WRITE_NEW do iev 1 nev event lcevtcreate status lcevtsetrunnumber event irun status lcevtseteventnumber event iev schcol lccolcreate LCIO_SIMCALORIMETERHIT do k 1 nhit hit lcschcreate status lcschsetcellidO hit 1234 status lcschsetenergy hit energy status lccoladdelement schcol hit enddo status lcwrtwriteevent writer event need to delete the event as we created status lcevtdelete event 20 it enddo status lce
40. nchain preader filenamesv nfiles len filenamesv 1 status pheader status status status status status status for class SimCalorimeterHit lcwriterunheader pwriter irun detname descrname sdnamev nsdn len sdnamev 1 lcreadnextrunheader preader irun detname descrname sdnamev nsdn len sdnamev 1 lcseteventheader pevent irun ievt itim detname lcgeteventheader pevent irun ievt itim detname lcdumpevent pevent lcdumpeventdetailed pevent lcaddsimtrackerhit pcolhitt icellid dposv fdedx ftime pmcp lcgetsimtrackerhit pcolhitt i icellid dposv fdedx ftime pmcp lcaddsimcalohit pcolhitc icellidO icellidi energy posv lcschaddmcparticlecontribution phit pmcp energy time ipdg lcgetsimcalohit pcolhitc i icellidO icellidi energy posv legetsimcalohitmccont phit i pmcp energy time ipdg from basic 77 API lcgetmcparticledata pmcp ipdg igstat isstat dvtxv momv mass charge ndaughters to COMMON HEPEVT lcio2hepevt pevent addSimCaloHit gt phit 8 addSimCaloHitMCont gt status getSimCaloHit gt phit getSimCaloHitMCont gt status for class MCParticle getMCParticleData gt status for class HEPEVT Fortran interface toHepEvt gt status fromHepEvt gt status for the user extension classes createIntVector gt pvec createFloatVector gt pvec createStringVector gt pvec getIntVector gt
41. ndpoint pmcp dvtxv lcmcpsetmomentum pmcp momv lcmcpsetmass pmcp mass lcmcpsetcharge pmcp charge lcmcpgetnumberofparents pmcp lcmcpgetparent pmcp i lcmcpgetnumberofdaughters pmcp lemcpgetdaughter pmcp i i 1 lcmcpgetpdg pmcp number 29 getGeneratorStatus ki getSimulatorStatus ki getVertex gt getEndpoint ki getMomentum gt getEnergy ki getMass ki getCharge gt utility istatg istats status status status denergy dmass charge lcmcpgetgeneratorstatus pmcp lcmcpgetsimulatorstatus pmcp lcmcpgetvertex pmcp dvtxv lcemcpgetendpoint pmcp dvtxv lcmcpgetmomentum pmcp dmomv lcmcpgetenergy pmcp lcmcpgetmass pmcp lcmcpgetcharge pmcp LCIntVec LCFloatVec LCStrVec classes getLengthofIntVector gt getIntAt gt getLengthofFloatVector gt getFloatAt gt getLengthofStringVector gt getStringAt gt nelem int nelem float nelem string lcivcgetlength pintvec lcivegetintat pintvec i i 1 nelem lcfvcgetlength pfloatvec lefvcgetfloatat pfloatvec i i 1 nelem lcsvcgetlength pstrvec lcsvcgetstringat pstrvec i i 1 nelem stl vector class int float string pointer IntVectorGetLength gt IntVectorGetElement gt FloatVectorGetLength gt FloatVectorGetElement gt StringVectorGetLength gt StringVectorGetElement gt PointerVectorGetLength gt PointerVectorGetElement gt nel
42. number of events for each run A simple event loop looks like this LCEvent evt while evt lcReader gt readNextEvent 0 LCTOOLS dumpEvent evt nEvents For small applications and data files this is a reasonable way of analyzing data The other way of reading LCIO data files is via a Listener or Observer pattern In this approach you have to write your own analysis module s which implements the LCRunListener and LCEventListener interface and register those with the LCReader When reading the data stream the corresponding registered modules are called depending on the type of the current record By writing modules for distinct tasks e g vertex track reconstruction track finding clustering algorithms etc this already defines an application framework for reconstruction with the LCEvent as underlying data structure For example you can define one analysis module as run and event listener class for processing run and event records class MyAnalysis public LCRunListener public LCEventListener public MyAnalysis MyAnalysis void processEvent LCEvent evt void processRunHeader LCRunHeader run void modifyEvent LCEvent evt not needed void modifyRunHeader LCRunHeader run not needed L 13 Here the processEvent RunHeader methods are used as they provide read only access to the data The only modification of the data allowed in read only mode is
43. ols for viewing the histograms e g JAS3 I 4 3 Iciohbook Fortran Hbook A Fortran example that creates an Hbook 9 file from an LCIO file with some histograms to be analyzed with PAW 5 4 4 pythia Fortran Pythia An ASCII file of generator output can be produced by the script pythiahepevt sh This script runs a Pythia 8 job using the Pythia routine PYHEPC to fill the hepevt common block and a modified version of LCWRITE to create the ASCII file is included in the script To run this script one has to provide cernlib 9 2002 or later The script has to be modified if necessary to provide a valid path to the cernlib libraries The program PYSIMJOB pysimjob F reads the ASCII file fills the hepevt common block and writes a LCIO file which is read again in a second pass to fill the hepevt common block 22 Appendix A A ChangeLog Changes from v1 3 to v1 4 There have been a number of changes in LCIO wrt to the last public release v01 03 A 2 LCGenericObjects in Java Support for user defined objects that have an arbitrary number of attributes of type int float and double now also in Java Support for subset collections Added flag isSubset to LCCollection that allows to have collections that are subsets of existing collections in the event In case the collection is not transient only references pointers are written to the output file Small API change in LCGenericObject C Changed the return value of
44. omobjects prnv pobj lcrnvgetrelatedtoweights prnv pobj lcrnvgetrelatedfromweights prnv pobj lcgobcreate lcgobcreatefixed nint nfloat ndouble 1cgobdelete pgob lcgobsetintval pgob i ival lcgobsetfloatval pgob i fval lcgobsetdoubleval pgob i dval lcgobid pgob legobgetnint pgob lcgobgetnfloat pgob lcgobgetdoubleval pgob lcgobgetintval pgob i i 1 nint lcgobgetfloatval pgob i i 1 nfloat lcgobsetdoubleval pgob i i 1 ndouble lcgobisfixedsize pgob lcgobgettypename pgob lcgobgetdatadescription pgob lesthcreate lcsthdelete pthit lcsthsetcellid pthit icellid lcsthsetposition pthit dposv lcsthsetdedx pthit fdedx lcsthsetedep pthit fedep 26 setTime setMCParticle setMomentum setMomentumXYZ setPathLength getCel1ID getPosition getMomentum getPathLength getdEdx getEDep getTime getMCParticle class SimCalorimeterHit create delete setCellIDO setCellID1 setEnergy setPosition addMCParticleContr id getCe11IDO getCellID1i getEnergy getPosition getNMCParticles getParticleCont getEnergyCont getTimeCont getPDGCont class CalorimeterHit create delete setCellIDO setCellID1 setEnergy setPosition setTime setType setRawHit id getCellIDO getCellID1i getEnergy getPosition getTime getType getRawHit class TPCHit create delete setCellID setTime setCharge setQuality setRawData
45. on except for cells where showers from two particles overlap e LCIO CHBIT STEP 1 detailed mode one contribution for every simulator step that con tributed to the hit Every contribution has the energy time and PDG of the shower particle that caused the energy deposit This mode will result in a lot of entries per calorimeter hit and is intended for detailed studies only In general the position of calorimeter hits will be decoded from the cellid to save disk space For user convenience it is however possible to store the three dimensional position of the cell with every hit Check set the collection flag bit LCIO CHBIT LONG 1 Also for cases where it is impossible or inconvenient to decode the cellid in one word SimCalorimeterHit can have an optional second cellid LCIO CHBIT_ID1 1 3 2 3 SimTrackerHit This is the generic class for storing simulated hits from tracking subdetectors It records the space point energy and time of the hit as well as a link to the MCParticle that caused it 3 2 4 RawCalorimeterHit This class is intended to be used for real calorimeter data e g from test beam calorimeters It stores a cellid amplitude and optionally LCIO RCHBIT_TIME 1 a time word all as int values as this is what is read out from the DAQ system Also a second cellid can be utilized if needed LCIO RCHBIT ID1 1 To save disk space when storing raw data only set the colelction flag bit LCIO RCHBIT_NO_PTR 1 suppressing an additional 32
46. onal methods to create and delete the object respectively All functions that operate on objects i e all functions except for the creation functions constructors need as a first argument the integer pointer to the particluar object By using a unique naming convention the documentation of the C version of the API can be utilized for the Fortran API as well Moreover example code written in C can be translated into Fortran basically line by line as far as LCIO is concerned of course language specific control structures will have to be different So even if you are only intereseted in using LCIO from Fortran it is probably a good idea to read the above sections on Java and C as well to get some insight into the general structure of LCIO 3 9 1 Note The handling of pointers in Fortran must be done carefully One has to ensure that pointers are always used in the right context Pointers of objects given back to C can not be checked by the language to be applicable In most cases of wrong pointer usage the execution of the executable will result ina segmentation violation 3 9 2 Naming convention The following naming convention is used for the fortran wrapper functions to the C implementation of LCIO e all function names start with Ic e lc is followed by a three letter acronym that uniquley identifies the corresponding C class e g evt for LCEvent See table 2 for a complete listing for the classes LCVec STL vector see
47. pful to browse the documentation LCIO is organized in a hierarchical package structure where the packages combine classes with a well defined purpose as shown in table 1 So a good starting point to browse the API documentation is the package namespace C Namespace Java package Purpose EVENT hep lcio event The base interfaces of all data classes in LCIO To be used for reading existing data IO hep lcio io The base interfaces for io of data IMPL hep lcio implementation event The default implementations of the base interfaces that are defined in EVENT Needed for writing new data or extending existing data e g during reconstruction UTIL hep lcio util Holds convenient and support classes and methods for the LCIO objects Icio n a The namespace lcio combines EVENT IO UTIL and IMPL for user conve nience include Icio h Namespaces packages below are shown for completeness only don t use in your code IOIMPL hep lcio implementation io Extensions to the default implementa tions needed for IO With the exception of LCFactory all other classes are for in ternal use only SIO hep lcio implementation sio The persistency implementation using SIO Users should not use any of the classes defined here explicitly but through their base interfaces defined in IO DATA hep lcio data Removed in v1 3 Table 1 Overview of the packages namespaces used in LCIO overview Depen
48. pschit lcschgetposition pschit posv lcschgetnmcparticles pschit lcschgetparticlecont pschit i i 1 leschgetenergycont pschit i i 1 lcschgettimecont pschit i Gi 1 lcschgetpdgcont pschit i is1 number number number number lccahcreate lccahdelete pchit lccahsetcellidO pchit icellidO lccahsetcellidi pchit icellidi lccahsetenergy pchit energy lccahsetposition pchit posv lccahsettime pchit time lccahsettype pchit itype lccahsetrawhit pchit praw lccahid pchit lccahgetcellidO pchit lccahgetcellidi pchit lccahgetenergy pchit lccahgetposition pchit posv lccahgettime pchit lccahgettype pchit lccahsetrawhit pchit lctphcreate lctphdelete pthit lctphsetcellid pthit icellid lctphsettime pthit time lctphsetcharge pthit charge lctphsetquality pthit iquality lctphsetrawdata pthit irawv nraw lctphid pthit lctphgetcellid pthit lctphgettime pthit lctphgcharge pthit lctphgetquality pthit lctphgetnrawdatawords pthit lctphgetrawdataword pthit i i 1 nraw lctrhcreate lctrhdelete ptrhit 27 setPosition gt setCovMatrix 2 gt setdEdx gt setEDep gt setEDepError gt setTime gt setType gt setQuality mz addRawHit gt id ki Set Position gt getCovMatrix gt getdEdx gt getEDep gt getEDepError gt getTime ki getType
49. r p character strings denoted by name or string logicals denoted by bool integers denoted by status or a variable name starting with i or n long integers INTEGER 8 denoted by ilong double precision variables name starting with d reals else arrays are denoted by a name ending with v EE EE class LCReader create gt preader lcrdrcreate delete gt status lcrdrdelete preader open gt status lcrdropen preader filename close gt status lcrdrclose preader readStream gt status lcrdrreadstream preader nmax readNextRunHeader gt pheader lcreadnextrunheader preader iaccessmode readNextEvent gt pevent lcrdrreadnextevent preader iaccessmode readEvent gt pevent lcrdrreadevent preader irun ievt RunEventProcessor includes registerLCEventListener registerLCRunListener gt status lcrdreventprocessor filename class LCWriter create gt pwriter lcwrtcreate delete gt status lcwrtdelete pwriter open gt status lcwrtopen pwriter filename imode close gt status lcwrtclose pwriter writeRunHeader gt status lcwrtwriterunheader pwriter pheader writeEvent gt status lcwrtwriteevent pwriter pevent class LCRunHeader create gt pheader lcrhdcreate delete gt status lcrhddelete pheader setRunNumber gt status lcrhdsetrunnumber pheader setDetectorName gt status lcrhdsetdetectorname pheader detname setDes
50. ss the data in the LCIO data structures Mostly this is straightforward e g printing run data is as easy as LCRunHeader runHdr cout lt lt Run lt lt runHdr gt getRunNumber ee lt lt runHdr gt getDetectorName Es 3 lt lt runHdr gt getDescription lt lt endl In order to access the information stored in the event you need to know the collection names that hold the relevant data as well as the type of the objects e g to access the TPC hits one could write code like the following 14 LCCollection col evt gt getCollection TPCHits int nHits col gt getNumber0fElements for int i 0 i lt nHits i TPCHit hit dynamic_cast lt TPCHit gt col gt getElementAt i cout lt lt hit lt lt i lt lt charge lt lt hit gt getCharge lt lt time lt lt hit gt getTime lt lt endl J A few comments are in order e collection name LCIO stores collections under user defined names In order to retrieve the collection from the data you need to know this name Usually the person that created a data file will also have provided some documentation on the content and on collection names NB The underlying implementation of the LCIO data format is self documenting i e infor mation on collection names and types is included in the files This is used in the anajob and dumpevent example programs run either of those to print collection nam
51. tAvailableException will be thrown by methods accessing event data that are not available e g if you are trying to get a named collection from the event that is not available In this case it depends on your application whether you want to continue or not if the computation is vital for the rest of the program you ll probably want to abort if the code just produces some check plots for a particular subdetector you might as well carry on with other 7modules In case an exception is thrown at run time that is not caught the program will abort and you will get some printout as to what caused the exception in Java this is done by the VM in C we print the type of the exception with some information on the problem usually the class and function name Note to C programmers We included std exception in all throw clauses in C This way we ensure a behavior similar to Java i e despite a throw clause basically all exceptions can be thrown by the function as all STL Exceptions as well as all LCIO Exceptions inherit from the base std exception So the user can decide to catch run time exceptions for parts of the code in order to prevent an abort of the program 3 2 Data model Figure i shows the event data model of LCIO The most important class is LCEvent it serves as a container for all data that are related to one event It holds an arbitrary number of named collections class LCCollection of data objects class LCObject Run related in
52. the addition of new collections to the event as this doesn t alter existing information This will probably suffice for most analysis and reconstruction applications So unless you need to do any of the following e remove collections from the event e change elements in the collections i e fix bugs e add data to existing collections e g background hits you should use the read only mode in the processRunHeader Event methods which is also default for the readNextEvent RunHeader methods In an analysis job one could for example create histograms for every run in processRunHeader LCRunHeader run and then fill the histograms in processEvent LCEvent evt The corresponding simplified but complete main program will then look something like this in C include lcio h include I0 LCReader h include MyAnalysis h using namespace lcio int main int argc char argv LCReader lcReader LCFactory getInstance gt createLCReader lcReader gt open argv i MyAnalysis myAnalysis lcReader gt registerLCRunListener amp myAnalysis 1lcReader gt registerLCEventListener amp myAnalysis lcReader gt readStream read the whole stream lcReader gt close return 0 A more elaborated example C that defines a mini framework where you can specify analysis modules at runtime can be found in HU 3 7 3 Accessing the data Check the API documentation and the examples on how to acce
53. tion It allready has a space point position and error matrix computed from the raw data TrackerHits point back to the raw data hits that they have been created from 3 5 2 Cluster Clusters are made from sets of CalorimeterHits that they point back to Clusters can also be combined from other Clusters allowing a tree like structure e g one could build clusters with a geometrical algorithm and then combine some of these clusters to particles applying some track match criterieon Due to the imaging capabilities of the LC calorimeters clusters have an intrinsic direction denoted ITheta IPhi For fast Monte Carlo or in case where the hits are droped from the files DST Clusters can have vector of subdetector energies Check set the collection variable ClusterSubdetectorNames for the decoding of the indices in the vector And similarly check set the collection variable Clus terShapeParameters for the indices in the shape parameter vector Clusters have a type word where the lower 15 bits can be used to decode the type of the cluster by the user e g define a bit per subdetector Check Set the collection variables ClusterTypeBitNames and ClusterTypeBitIndices 3 5 3 Track For LCIO we use the following parameters for Track e do Impact paramter of the track in the r phi plane e phi Phi of the track at the reference point e omega The signed curvature of the track in 1 mm the sign is that of the particle s charge e z0 Imp
54. uster vec getReferencePoint const float Asil At getCalorimeter Hits const Calorimeter Hitvec amp gstParticie Ds const ParticlelbVecd sgetFioatVak float getHitContributions const FloatVec amp getParticleID Used ParticleID Kater L etptsieclafre get const Besich getParticles const ReconstructedParticleVec amp Kee l getClusters const ClusterVec amp getTypeName const std string amp Ds E Geesen HacdParticle void HaddCluster void addTrack void Figure 2 Overview of the data entities defined by LCIO namespace EVENT All classes are subclasses of LCObject The shown dependencies correspond to links between objects e g for a given reconstructed particle you can get the tracks and clusters that have been used to create the particle There is no direct link from real data objects to Monte Carlo objects instead LC Relation is to be used for that particle is added to the MCParticle list with this flag set and the parent set to the particle that initially decayed or interacted in a non tracking region e vertexIsNotEndpointOfParent True if particle created as a result of a continuous process where the parent particle continues i e hard ionization Bremsstrahlung elastic interactions etc e isDecayedInTracker True if the particle decayed or interacted non continuous interaction particle terminated in a tracking region e isDecayedInCalorimeter True if
55. vector class intvectorgetlength intvectorgetelement floatvectorgetlength floatvectorgetelement stringvectorgetlength stringvectorgetelement For strings the Fortran CHARACTER declaration has to be large enough otherwise the original string is truncated A Summary of all functions in the basic Fortran API is given in the first part of Appendix B i 3 9 3 Extension of the Base Fortran API An additional set of Fortran functions is provided for user convenience These are higher level func tions that usually allow to access several attributes of data objects with one function call These functions are declared in LCIO src f77 lciof7Tapiext inc and are summarized in the second part of Appendix B Most Fortran programs for simulation use the hepevt common block Conversion functions from the LCIO MCParticle collection to the hepevt common block and vice versa are also provided in the extended interface See the example in 4 4 The wrapper functions for the LCParametersImpl class are provided in the extension of the base Fortran API This class is related to the classes LCRunHeaderImpl LCEventImpl and LCCollectionVec and has the methods setInt Values setFloat Values setString Values getIntKeys getFloatKeys getStringt Keys getInt Values getFloat Values and getStringValues 18 The set get methods are performed by the wrapper fuctions lcsetparameters class_name class_pointer method_name key_name vector
56. vtaddcollection event schcol MyCalHits status lcwrtclose writer Note that as in the C case we have to delete the event if we created it as described in 3 8 3 3 9 5 Using a C RunEventProcessor class for LCIO files processing in Fortran A RunEventProcessor class is added to the Fortran API To use it a wrapper function lcrdrevent processor is provided which has to be called as include lciof77api inc kkk kkk kkk kkk kkk KKK integer lcrdreventprocessor status character 30 filenamesin 3 character 30 filenameout PTRTYPE writer pv common outinfo writer filenamesin 1 simjob_f1 slcio filenamesin 2 simjob_f2 slcio filenamesin 3 simjob_f3 slcio filenameout recjob_f slcio create writer open output file writer lcwrtcreate status lcwrtopen writer filenameout LCIO_WRITE_NEW create a stringvector of input file names pv lcstringvectorcreate filenamesin 3 len filenamesin 1 create reader open input file chain start event loop status lcrdreventprocessor pv subroutine processrunheader pheader PTRTYPE pheader some code if wanted e g status lcdumprunheader pheader end subroutine modifyrunheader pheader PTRTYPE pheader some code if wanted end subroutine processevent pevent PTRTYPE pevent some code if wanted end subroutine modifyevent pevent include lciof77api inc PTRTYPE pevent PTRTYPE writ
Download Pdf Manuals
Related Search