Warning, /afterburner/README.md is written in an unsupported language. File is not indexed.
0001 # afterburner
0002
0003 EIC MC afterburner. Software package to provide framework independent
0004 well validated crossing angle and beam effects C++ library and HepMC file converter (abconv)
0005 for Electron Ion Collider.
0006
0007 **Physics simulated:**
0008 - Crossing angle
0009 - Beam effects (divergence, crabbing kick, etc.)
0010 - Vertex spread (position, time)
0011
0012
0013 **Software:**
0014 - Standalone framework independent code
0015 - Clean C++ API to embed in analysis scripts and/or frameworks
0016 - Convenient Command Line Interface (CLI) HepMC2/3 and `root.hepmc` converter, that adds crossing_angle_hor and beam effects
0017 - Configurable beam parameters interface (yaml files)
0018
0019
0020 ## Installation
0021
0022 The converter and benchmark require libyaml-cpp. Those are available in package managers for the most of systems:
0023
0024 ```bash
0025 apt install libyaml-cpp-dev # Debian/Ubuntu/Mint
0026 yum install yaml-cpp-devel # RHEL/CentOS/Fedora
0027 ```
0028
0029
0030 ```bash
0031 git clone https://eicweb.phy.anl.gov/monte_carlo/afterburner.git
0032 mkdir -p afterburner/build
0033 cd afterburner/build
0034
0035 # setup cmake (c++ code lives in cpp directory)
0036 cmake ../cpp
0037
0038 # to build all
0039 cmake --build ../cpp --target all
0040
0041 # to install
0042 cmake --build ../cpp --target install -- -j 8
0043 ```
0044
0045 **Preinstalled versions** are available in [ATHENA containers](https://doc.athena-eic.org/en/latest/overview/containers.html).
0046
0047
0048 ## CLI command
0049
0050 ### Examples:
0051
0052 ```bash
0053 # Process my whole file, add crossing angle, beam effects, do validation plots
0054 abconv my.hepmc
0055
0056 # Same, but limit the number of events to 1000 and set the output name as 'test'
0057 abconv my.hepmc -o test -l 1000
0058
0059 # Just convert hepmc3 to hepmc2 don't use afterburner, don't create plots
0060 abconv my.hepmc -f hepmc2 --ab-off --plot-off
0061
0062 # Just convert hepmc3 to hepmc.root don't use afterburner, don't create plots
0063 abconv my.hepmc -f treeroot --ab-off --plot-off
0064 ```
0065 Note: In the final example above, you want the `treeroot` option. The `root` option creates a (rather strange) flat file.
0066
0067 How exactly the afterburner works illustrated by `abconv my.hepmc` command.
0068
0069
0070 ### Afterburner algorithm
0071
0072 1. AB opens the input file, gets beam particles and extract beam energy settings (from the first event).
0073 See **beam energy settings** for the details below.
0074
0075 2. AB awaits that there is no crossing angle between beam particles. To check this
0076 AB calculates a crossing angle between the beam particles. If the crossing angle is not zero
0077 and `--exit-ca` flag is set - AB exits; without the flag a warning is issued.
0078
0079 3. AB processes events applying crossing angle and beam effects for each event.
0080 `-s,--ev-start`, `-e,--ev-end`, `-l,--limit` flags limit the number of events to process
0081
0082 4. By defaults AB also creates *.hist.root file that contains validation histograms
0083 `--plot-off` flag can switch off histograms creation
0084
0085
0086 P.S. Is one needs just HepMC3->HepMC2 converter one can use `--ab-off` flag to disable
0087 afterburner during conversion. This way **abconv** could be use as different HepMC formats
0088 converter.
0089
0090
0091 ### Beam energy settings
0092
0093 - The input file events must have two beam particles (marked by status code 4)
0094 - Beam particle energies should correspond to one of EIC beam energy setups:
0095 - ep \[GeV\]: 275x18, 275x10, 100x10, 100x5, 41x5
0096 - eAu \[GeV\]: 110x18, 110x10, 110x5, 41x5
0097 - One can [the exact beam parameters](https://eicweb.phy.anl.gov/monte_carlo/afterburner/-/blob/main/cpp/afterburner/EicConfigurator.cc)
0098 that correspond to EIC CDR tables 3.3, 3.4, 3.5
0099 - Using `-p/--preset` flag one can select a profile:
0100 - 0: IP6 High Divergence (higher luminosity) - default,
0101 - 1: IP6 High Acceptance
0102 - 2: IP6 eAu
0103 - 3: IP8 High Divergence (higher luminosity) - default,
0104 - 4: IP8 High Acceptance
0105 - 5: IP8 eAu
0106 - Crossing angle is given in horizontal and vertical components
0107 - [Afterburner configuration](https://eicweb.phy.anl.gov/monte_carlo/afterburner/-/blob/main/cpp/afterburner/AfterburnerConfig.hh)
0108
0109 > (!) For now IP8 is a copy of IP6 parameters with 35 mrad crossing angle. It will be populated with IP8 own parameters as
0110 > soon as they are officially published.
0111
0112 ### Input file requirements
0113
0114 - The CLI command can accept any file, that HepMC3 library can open:
0115 HepMC3 ascii, HepMC2 ascii, HepMC3 ROOT, HepEvt etc.
0116 - The input file events must have two beam particles (marked by status code 4)
0117 - Input file should not have crossing angle and beam effects that AB simulates.
0118 **By default, it is not possible to apply just crossing angle or just beam effects.**
0119 **But!** in the upcoming version one can provide beam parameters through yaml config files,
0120 where one would be able to switch off crossing angle, beam effects, etc.
0121
0122
0123 ### All options:
0124
0125 | Flag | Description |
0126 |----------------------|-------------------------------------------|
0127 | -h,--help | Print this help message and exit|
0128 | -v,--version | Shows package version number |
0129 | -o,--output TEXT | Base name for Output files ((!) no extension)|
0130 | -p,--preset TEXT | Beams configuration 0: IP6 High divergence\[default\], 1: IP6 High acceptance, 2: IP6 eAu|
0131 | -i,--in-format TEXT | Input format: auto \[default\], hepmc2, hepmc3, hpe, lhef, gz, treeroot, root|
0132 | -f,--out-format TEXT | Output format: hepmc3 \[default\], hepmc2, dot, none (no events file is saved)|
0133 | -s,--ev-start INT | Start event index (all previous are skipped)|
0134 | -e,--ev-end INT | End event index (end processing after this event)|
0135 | -l,--limit UINT | Limit number of events to process. (Shutdown after this number of parsed events)|
0136 | --ab-off | No afterburner is applied|
0137 | --plot-off | Don't produce validation plots|
0138 | --exit-ca | Check existing crossing angle and exit if CA>1mrad (1) |
0139
0140
0141 > (1) How `--exit-ca` works exactly: when afterburner processes the first event it checks if
0142 > it has 2 beam particles (fails with non zero code if not) and then calculates their crossing angle
0143 > with the `--exit-ca` is set and crossing angle absolute value is > 1mrad program ends with 0 code.
0144 > This method is very coarse as if in a source file the crossing angle is 0 but all beam effects do exist,
0145 > beam effects will be applied twice
0146
0147 -p,--preset flag, values \[0,1,2,3,4,5\] set config and auto determine energy from source file:
0148
0149 - "0": IP6, High divergence, auto read energy [default],
0150 - "1": IP6, High acceptance, auto read energy
0151 - "2": IP6, eAu, auto read energy
0152 - "3": IP8, High divergence, auto read energy [default],
0153 - "4": IP8, High acceptance, auto read energy
0154 - "5": IP8, eAu, auto read energy
0155
0156 The other options sets energy settings manually, not checking the source file:
0157
0158 <table>
0159 <tr><td>ip6_hidiv_41x5</td><td>ip6_hidiv_100x5</td><td>ip6_hidiv_100x10</td><td>ip6_hidiv_275x10</td><td>ip6_hidiv_275x18</td></tr>
0160 <tr><td>ip6_hiacc_41x5</td><td>ip6_hiacc_100x5</td><td>ip6_hiacc_100x10</td><td>ip6_hiacc_275x10</td><td>ip6_hiacc_275x18</td></tr>
0161 <tr><td>ip6_eau_41x5 </td><td>ip6_eau_110x5 </td><td>ip6_eau_110x10 </td><td>ip6_eau_110x18 </td><td>-</td></tr>
0162 <tr><td>ip8_hidiv_41x5</td><td>ip8_hidiv_100x5</td><td>ip8_hidiv_100x10</td><td>ip8_hidiv_275x10</td><td>ip8_hidiv_275x18</td></tr>
0163 <tr><td>ip8_hiacc_41x5</td><td>ip8_hiacc_100x5</td><td>ip8_hiacc_100x10</td><td>ip8_hiacc_275x10</td><td>ip8_hiacc_275x18</td></tr>
0164 <tr><td>ip8_eau_41x5 </td><td>ip8_eau_110x5 </td><td>ip8_eau_110x10 </td><td>ip8_eau_110x18 </td><td>-</td></tr>
0165 </table>
0166
0167 Example of manual configuration setting:
0168
0169 ```bash
0170 abconv -p ip6_hidiv_100x5 source_file.hepmc
0171 ```
0172
0173 > (!) For now IP8 is a copy of IP6 parameters with 35 mrad crossing angle. It will be populated with IP8 own parameters as
0174 > soon as they are officially published.
0175 >
0176
0177 ## Validation
0178
0179 The validation is performed by comparison of the resulting particle distributions with
0180 [Pythia8 beam effects](https://github.com/bspage912/eicSimuBeamEffects) simulation.
0181 The later was also validated with Fun4All afterburner implementation.
0182
0183
0184 To apply benchmarks. Head-on data (no crossing angle nor effects) is located:
0185
0186 ```
0187 https://eics3.sdcc.bnl.gov:9000/minio/eictest/ATHENA/WG/BeamEffects/
0188 ```
0189
0190 The validation plots are generated and can be viewed in [python/comparison.ipynb](python/comparison.ipynb)
0191
0192 Essential plots from the latest validation run:
0193
0194 > The discrepancy in low Eta has been explained by a slight phase space difference
0195 > in generated headon and full beam effects files on Pythia8 side.
0196 > TL;DR; [It is Fine](https://cdn.vox-cdn.com/thumbor/qQPUPBlaiVYrsXg5QM1QQYVgH34=/0x0:900x500/1400x1400/filters:focal(378x178:522x322):format(jpeg)/cdn.vox-cdn.com/uploads/chorus_image/image/49493993/this-is-fine.0.jpg)
0197
0198 <table>
0199 <thead>
0200 <tr>
0201 <th>41x5 GeV</th>
0202 <th>100x10 GeV</th>
0203 <th>275x18 GeV</th>
0204 </tr>
0205 </thead>
0206 <tr>
0207 <td><img src="python/pics/41x5_eta_comparison.png" alt="Eta comparison"/></td>
0208 <td><img src="python/pics/100x10_eta_comparison.png" alt="Eta comparison"/></td>
0209 <td><img src='python/pics/275x18_eta_comparison.png' alt="Eta comparison"/></td>
0210 </tr>
0211 <tr>
0212 <td><img src="python/pics/41x5_phi_comparison.png" alt="Phi comparison"/></td>
0213 <td><img src="python/pics/100x10_phi_comparison.png" alt="Phi comparison"/></td>
0214 <td><img src='python/pics/275x18_phi_comparison.png' alt="Phi comparison"/></td>
0215 </tr>
0216 <tr>
0217 <td><img src="python/pics/41x5_atan2_pxpz_hadron.png" alt="atan2_pxpz hadron comparison"/></td>
0218 <td><img src="python/pics/100x10_atan2_pxpz_hadron.png" alt="atan2_pxpz hadron comparison"/></td>
0219 <td><img src='python/pics/275x18_atan2_pxpz_hadron.png' alt="atan2_pxpz hadron comparison"/></td>
0220 </tr>
0221 <tr>
0222 <td><img src="python/pics/41x5_atan2_pypz_hadron.png" alt="atan2_pypz hadron comparison"/></td>
0223 <td><img src="python/pics/100x10_atan2_pypz_hadron.png" alt="atan2_pypz hadron comparison"/></td>
0224 <td><img src='python/pics/275x18_atan2_pypz_hadron.png' alt="atan2_pypz hadron comparison"/></td>
0225 </tr>
0226 <tr>
0227 <td><img src="python/pics/41x5_atan2_pxpz_lepton.png" alt="atan2_pxpz lepton comparison"/></td>
0228 <td><img src="python/pics/100x10_atan2_pxpz_lepton.png" alt="atan2_pxpz lepton comparison"/></td>
0229 <td><img src='python/pics/275x18_atan2_pxpz_lepton.png' alt="atan2_pxpz lepton comparison"/></td>
0230 </tr>
0231 <tr>
0232 <td><img src="python/pics/41x5_atan2_pypz_lepton.png" alt="atan2_pypz lepton comparison"/></td>
0233 <td><img src="python/pics/100x10_atan2_pypz_lepton.png" alt="atan2_pypz lepton comparison"/></td>
0234 <td><img src='python/pics/275x18_atan2_pypz_lepton.png' alt="atan2_pypz lepton comparison"/></td>
0235 </tr>
0236 <tr>
0237 <td><img src="python/pics/41x5_vtx_x_comparison.png" alt="Vertex X comparison"/></td>
0238 <td><img src="python/pics/100x10_vtx_x_comparison.png" alt="Vertex X comparison"/></td>
0239 <td><img src='python/pics/275x18_vtx_x_comparison.png' alt="Vertex X comparison"/></td>
0240 </tr>
0241 <tr>
0242 <td><img src="python/pics/41x5_vtx_z_comparison.png" alt="Vertex Z comparison"/></td>
0243 <td><img src="python/pics/100x10_vtx_z_comparison.png" alt="Vertex Z comparison"/></td>
0244 <td><img src='python/pics/275x18_vtx_z_comparison.png' alt="Vertex Z comparison"/></td>
0245 </tr>
0246 <tr>
0247 <td><img src="python/pics/41x5_vtx_t_comparison.png" alt="Vertex T comparison"/></td>
0248 <td><img src="python/pics/100x10_vtx_t_comparison.png" alt="Vertex T comparison"/></td>
0249 <td><img src='python/pics/275x18_vtx_t_comparison.png' alt="Vertex T comparison"/></td>
0250 </tr>
0251 </table>
0252
0253 ## References
0254
0255 - [Accelerator and beam conditions critical for physics and detector simulations for the Electron-Ion Collider](https://github.com/eic/documents/blob/master/reports/general/Note-Simulations-BeamEffects.pdf)
0256 - [Pythia8 beam effects](https://github.com/bspage912/eicSimuBeamEffects/blob/headonTestJin/Pythia8/PythiaBeamShape.cxx)
0257 - [Fun4All code](https://github.com/sPHENIX-Collaboration/coresoftware/pull/1251)
