Newer
Older
EIC MC afterburner.
## Installation
The converter and benchmark require libyaml-cpp. Those are available in package managers for the most of systems:
```bash
apt install libyaml-cpp-dev # Debian/Ubuntu/Mint
yum install yaml-cpp-devel # RHEL/CentOS/Fedora
```
```bash
git clone https://eicweb.phy.anl.gov/monte_carlo/afterburner.git
mkdir -p afterburner/build
cd afterburner/build
# setup cmake (c++ code lives in cpp directory)
cmake ../cpp
# to build all
cmake --build ../cpp --target all
# to install
cmake --build ../cpp --target install -- -j 8
```
**Preinstalled versions** are available in [ATHENA containers](https://doc.athena-eic.org/en/latest/overview/containers.html).
## CLI command
### Examples:
```bash
# Process my whole file, add crossing angle, beam effects, do validation plots
abconv my.hepmc
# Same, but limit the number of events to 1000 and set the output name as 'test'
abconv my.hepmc -o test -l 1000
# Just convert hepmc3 to hepmc2 don't use afterburner, don't create plots
abconv my.hepmc -f hepmc2 --ab-off --plot-off
```
How exactly the afterburner works illustrated by `abconv my.hepmc` command.
- AB opens *my.hepmc* file, gets beam particles and extract beam energy settings
- The settings should correspond to one of EIC beam energy setups:
- ep \[GeV\]: 275x18, 275x10, 100x10, 100x5, 41x5
- eAu \[GeV\]: 110x18, 110x10, 110x5, 41x5
- (!) Thus the input file must have two beam particles (marked by status code 4)
- One can [see available settings](https://eicweb.phy.anl.gov/monte_carlo/afterburner/-/blob/main/cpp/afterburner/EicConfigurator.cc)
that correspond to EIC CDR tables 3.3, 3.4, 3.5
- Using `-c/--config` flag one can select a profile:
- 0: High Divergence (default),
- 1: High Acceptance
- 2: eAu
- AB awaits that there is no crossing angle between beam particles. To check this
AB calculates a crossing angle between beams of the first event. If the crossing angle is not zero
and `--exit-ca` flag is set - AB exits; without the flag a warning is issued.
- AB processes events applying crossing angle and beam effects for each event.
- `-s,--ev-start`, `-e,--ev-end`, `-l,--limit` - limits the number of events to process
- By defaults AB also creates *.hist.root file that contains validation histograms
- `--plot-off` flag can switch off histograms creation
### Options:
| Flag | Description |
|----------------------|-------------------------------------------|
| -h,--help | Print this help message and exit|
| -o,--output TEXT | Base name for Output files ((!) no extension)|
| -c,--config TEXT | Beams configuration 0: High divergence\[default\], 1: High acceptance, 2: eAu|
| -i,--in-format TEXT | Input format: auto \[default\], hepmc2, hepmc3, hpe, lhef, gz, treeroot, root|
| -f,--out-format TEXT | Output format: hepmc3 \[default\], hepmc2, dot, none (no events file is saved)|
| -s,--ev-start INT | Start event index (all previous are skipped)|
| -e,--ev-end INT | End event index (end processing after this event)|
| -l,--limit UINT | Limit number of events to process. (Shutdown after this number of parsed events)|
| --ab-off | No afterburner is applied|
| --plot-off | Don't produce validation plots|
|--exit-ca | Check existing crossing angle and exit if CA>1mrad (1) |
> (1) How `--exit-ca` works exactly: when afterburner processes the first event it checks if
> it has 2 beam particles (fails with non zero code if not) and then calculates their crossing angle
> with the `--exit-ca` is set and crossing angle absolute value is > 1mrad program ends with 0 code.
> This method is very coarse as if in a source file the crossing angle is 0 but all beam effects do exist,
> beam effects will be applied twice
To apply benchmarks. Head-on data (no crossing angle nor effects) is located:
```
https://dtn01.sdcc.bnl.gov:9000/minio/eictest/ATHENA/WG/BeamEffects/
```
Pythia8 generated data with crossing angle and full effects is located:
```
https://dtn01.sdcc.bnl.gov:9000/minio/eictest/ATHENA/EVGEN/DIS/NC/
```
The validation plots are generated and can be viewed in [python/comparison.ipynb](python/comparison.ipynb)
> The discrepancy in low Eta has been explained by a slight phase space difference
> in generated headon and full beam effects files on Pythia8 side.
> 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)
<thead>
<tr>
<th>41x5 GeV</th>
<th>100x10 GeV</th>
<th>275x18 GeV</th>
</tr>
</thead>
<td><img src="python/pics/41x5_eta_comparison.png" alt="Eta comparison"/></td>
<td><img src="python/pics/100x10_eta_comparison.png" alt="Eta comparison"/></td>
<td><img src='python/pics/275x18_eta_comparison.png' alt="Eta comparison"/></td>
<td><img src="python/pics/41x5_phi_comparison.png" alt="Phi comparison"/></td>
<td><img src="python/pics/100x10_phi_comparison.png" alt="Phi comparison"/></td>
<td><img src='python/pics/275x18_phi_comparison.png' alt="Phi comparison"/></td>
<td><img src="python/pics/41x5_vtx_x_comparison.png" alt="Vertex X comparison"/></td>
<td><img src="python/pics/100x10_vtx_x_comparison.png" alt="Vertex X comparison"/></td>
<td><img src='python/pics/275x18_vtx_x_comparison.png' alt="Vertex X comparison"/></td>
</tr>
<tr>
<td><img src="python/pics/ 41x50_vtx_z_comparison.png" alt="Vertex Z comparison"/></td>
<td><img src="python/pics/100x10_vtx_z_comparison.png" alt="Vertex Z comparison"/></td>
<td><img src='python/pics/275x18_vtx_z_comparison.png' alt="Vertex Z comparison"/></td>
</tr>
<tr>
<td><img src="python/pics/41x5_vtx_t_comparison.png" alt="Vertex T comparison"/></td>
<td><img src="python/pics/100x10_vtx_t_comparison.png" alt="Vertex T comparison"/></td>
<td><img src='python/pics/275x18_vtx_t_comparison.png' alt="Vertex T comparison"/></td>
## References
- [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)
- [Pythia8 beam effects](https://github.com/bspage912/eicSimuBeamEffects/blob/headonTestJin/Pythia8/PythiaBeamShape.cxx)
- [Fun4All code](https://github.com/sPHENIX-Collaboration/coresoftware/pull/1251)