Warning, /EICrecon/src/services/io/podio/README.md is written in an unsupported language. File is not indexed.
0001
0002 ## podio JEventSource Overview
0003
0004 This is the podio/edm4hep/edm4eic JANA plugin. This plugin is automatically
0005 used by _eicrecon_ to read/write podio files. It may also be used with any
0006 jana executable (including the generic _jana_ executable that comes with
0007 JANA.) To use it with eicrecon to read in a podio file, you don't need to
0008 do anything other than provide a podio file(s) on the command line:
0009
0010 ~~~
0011 eicrecon infile.root [infile2.root [infile3.root ...]]
0012 ~~~
0013
0014 To write to an output file, set the _podio:output_file_ configuration
0015 parameter to the name of the output file.
0016
0017 ~~~
0018 eicrecon infile.root -Ppodio:output_file=outfile.root
0019 ~~~
0020 _n.b. if you set the output file name to "1" it will use the name "podio_output.root"_
0021
0022 ### Finding available collections
0023 For _eicrecon_, there are direct command line options to list all available
0024 object types/names which includes those in the input file. The podio plugin
0025 itself also provides a mechanism to list only what is in the podio file.
0026 To see a list of collections and their types contained in a file do this:
0027
0028 ~~~
0029 eicrecon -Ppodio:print_type_table=1 infile.root
0030 ...
0031 Available Collections
0032
0033 Collection Name Data Type
0034 ----------------------------------- -----------------------------------
0035 MCParticles vector<edm4hep::MCParticleData>
0036 EventHeader vector<edm4hep::EventHeaderData>
0037 DIRCBarHits vector<edm4hep::SimTrackerHitData>
0038 EcalEndcapNHits vector<edm4hep::SimCalorimeterHitData>
0039 EcalEndcapNHitsContributions vector<edm4hep::CaloHitContributionData>
0040 EcalEndcapPHits vector<edm4hep::SimCalorimeterHitData>
0041 EcalEndcapPHitsContributions vector<edm4hep::CaloHitContributionData>
0042 VertexBarrelHits vector<edm4hep::SimTrackerHitData>
0043 DRICHHits vector<edm4hep::SimTrackerHitData>
0044 TrackerBarrelHits vector<edm4hep::SimTrackerHitData>
0045 TrackerEndcapHits1 vector<edm4hep::SimTrackerHitData>
0046 TrackerEndcapHits2 vector<edm4hep::SimTrackerHitData>
0047 MPGDTrackerBarrelHits1 vector<edm4hep::SimTrackerHitData>
0048 TrackerEndcapHits3 vector<edm4hep::SimTrackerHitData>
0049 TrackerEndcapHits4 vector<edm4hep::SimTrackerHitData>
0050 MPGDTrackerBarrelHits2 vector<edm4hep::SimTrackerHitData>
0051 TrackerEndcapHits5 vector<edm4hep::SimTrackerHitData>
0052 TrackerEndcapHits6 vector<edm4hep::SimTrackerHitData>
0053 GEMTrackerEndcapHits1 vector<edm4hep::SimTrackerHitData>
0054 GEMTrackerEndcapHits2 vector<edm4hep::SimTrackerHitData>
0055 GEMTrackerEndcapHits3 vector<edm4hep::SimTrackerHitData>
0056 MRICHHits vector<edm4hep::SimTrackerHitData>
0057 TOFBarrelHits vector<edm4hep::SimTrackerHitData>
0058 EcalBarrelHits vector<edm4hep::SimCalorimeterHitData>
0059 EcalBarrelHitsContributions vector<edm4hep::CaloHitContributionData>
0060 HcalBarrelHits vector<edm4hep::SimCalorimeterHitData>
0061 HcalBarrelHitsContributions vector<edm4hep::CaloHitContributionData>
0062 HcalEndcapPHits vector<edm4hep::SimCalorimeterHitData>
0063 HcalEndcapPHitsContributions vector<edm4hep::CaloHitContributionData>
0064 HcalEndcapNHits vector<edm4hep::SimCalorimeterHitData>
0065 HcalEndcapNHitsContributions vector<edm4hep::CaloHitContributionData>
0066 B0PreshowerHits vector<edm4hep::SimTrackerHitData>
0067 B0TrackerHits vector<edm4hep::SimTrackerHitData>
0068 ZDCEcalHits vector<edm4hep::SimCalorimeterHitData>
0069 ZDCEcalHitsContributions vector<edm4hep::CaloHitContributionData>
0070 ForwardOffMTrackerHits1 vector<edm4hep::SimTrackerHitData>
0071 ForwardOffMTrackerHits2 vector<edm4hep::SimTrackerHitData>
0072 ForwardOffMTrackerHits3 vector<edm4hep::SimTrackerHitData>
0073 ForwardOffMTrackerHits4 vector<edm4hep::SimTrackerHitData>
0074 ZDCHcalHits vector<edm4hep::SimCalorimeterHitData>
0075 ZDCHcalHitsContributions vector<edm4hep::CaloHitContributionData>
0076 ForwardRomanPotHits1 vector<edm4hep::SimTrackerHitData>
0077 ForwardRomanPotHits2 vector<edm4hep::SimTrackerHitData>
0078 TaggerTracker1Hits vector<edm4hep::SimTrackerHitData>
0079 TaggerCalorimeter1Hits vector<edm4hep::SimCalorimeterHitData>
0080 TaggerCalorimeter1HitsContributions vector<edm4hep::CaloHitContributionData>
0081 TaggerTracker2Hits vector<edm4hep::SimTrackerHitData>
0082 TaggerCalorimeter2Hits vector<edm4hep::SimCalorimeterHitData>
0083 TaggerCalorimeter2HitsContributions vector<edm4hep::CaloHitContributionData>
0084 ...
0085 ~~~
0086
0087 ### Include/exclude collection lists for reading and writing
0088 You may speed up how fast events are read in if you are only interested in certain collections
0089 by configuring the include and exclude lists. For example if you are only interested in the
0090 _MCParticles_ collection then do this:
0091 ~~~
0092 eicrecon -Ppodio:input_include_collections=MCParticles infile.root
0093 ~~~
0094
0095 You may also specify multiple collections using a comma separated list:
0096 ~~~
0097 eicrecon -Ppodio:input_include_collections=MCParticles,EcalEndcapNHits infile.root
0098 ~~~
0099
0100 Specify a list of collections to exclude like this:
0101 ~~~
0102 eicrecon -Ppodio:input_exclude_collections=MCParticles,EcalEndcapNHits infile.root
0103 ~~~
0104
0105 You may specify both an include list and an exclude list.
0106
0107
0108 Similar to the input, you may also specify which collections to write out using the
0109 _podio:output_include_collections_ and _podio:output_exclude_collections_ configuration
0110 parameters.
0111
0112 ### Testing
0113 There may be certain instances where you would like to test an infinite stream of events, but
0114 have a limited number of events in your root file. The _podio:run_forever_ flag will cause
0115 the file to be repeatedly cycled over. For example:
0116 ~~~
0117 eicrecon -Ppodio:run_forever=1 infile.root
0118 ~~~
0119 Note that with this option set, only the first file will be read repeatedly. Any additional
0120 files given on the command line will be ignored.
0121
0122 ### Extra copy
0123 One my specify that an additional copy of the output root file be made at the very
0124 end of processing. The second file will have the same name as the first, but the
0125 directory for this second copy may be specified like this:
0126 ~~~
0127 eicrecon -Ppodio:output_file=myfile1.root -Ppodio:output_file_copy_dir=/path/to/copydir infile.root
0128 ~~~
0129 The above will result in a file _myfile1.root_ in the local directory and another copy
0130 at _/path/to/copydir/myfile1.root_ .
0131
0132 ### Merging in background events
0133 One may specify a background event file that will have 1 or more events read and
0134 merged into the primary event as it is read in. This is controlled by the
0135 _podio:background_filename_ and _podio:num_background_events_ configuration
0136 parameters.
0137
0138 Example: The command below will read in the primary (signal) events from _inputfile.root_
0139 and for each signal event, it will add objects from 3 events from the file _background.root_
0140 file.
0141 ~~~
0142 eicrecon inputfile.root -Ppodio:background_filename=background.root -Ppodio:num_background_events=3
0143 ~~~
0144
0145 *NOTES:*
0146
0147 * The objects from the background events file will not be written to the output file (if
0148 specified). Only objects from the primary input file and reconstructed values will be.
0149 (This may change in the near future.)
0150 * The background events will be recycled as needed so that the number of events in the
0151 background file may be smaller than the number of events in the primary input file.
0152 * This is implemented by opening _num_background_events_ instances of the background
0153 events file. This not terribly efficient and will work fine up to about
0154 _num_background_events_ <= 10. For values much larger than that, you
0155
0156 ### Technical notes
0157
0158
0159 * This uses a code generator to generate some routines that can take a class name
0160 in the form of a string and then call a templated function which can then use
0161 that class. This is only possible for the limited number of data types defined
0162 in the edm4hep data model. The code generation is done based on filenames it
0163 finds matching the pattern _${EDM4HEP_ROOT}/include/edm4hep/*Collection.h_ . Thus,
0164 if the model is updated, this will need to be recompiled, but it should automatically
0165 find the classes defined in the updated model.
