Process MCEG
============

- How to run MCEG files throught the Software
- What are the requirements and limitations for the MCEG
- How to convert files to the right format
- How to apply beam effects and crossing angle

MCEG Overview
-------------

.. figure:: ../_images/mceg_hepmc_stack.png
   :alt: Hepmc in software stack
   :width: 800

Athena full simulation and reconstruction stack accepts only HepMC2 and HepMC3 as an input format. 
The reason for that is that support for many formats on simulation/reconstruction level 
leads to increasing number of bugs witch are difficult to mitigate with testing because of the combinatorics. 
It is much easier in terms of testing, robustness and reprodusobility to have a reliable chain that works with one
(universal) format and have well tested standalone satelite conventers, that allow to work with different 
MCEG software (see the next picture). 


.. figure:: ../_images/mceg_hepmc_full_stack.png
   :alt: Hepmc conversion in the software stack
   :width: 800

- **Converters** allow to convert other formats to HepMC
- **Afterburner** applies crossing angle and beam effects

.. _convert_mceg:

Convert MCEG
------------

Currently there are 2 packages that allow to convert different MCEG to HepMC

- `EicSmear <https://github.com/eic/eic-smear>`__ - and old (means well tested) and reliable package 
   that allows to convert various (and especially old) MCEG to HepMC format. 
   `Instruction how to convert to HepMC <https://github.com/eic/eic-smear#creation-of-hepmc-output>`__
   It is recommended to use EicSmear especially for BNL RootTree files.
- `mcconv <https://eicweb.phy.anl.gov/monte_carlo/mcconv>`__ - new and less reliable, but kind of easier 
   to use for users and also has convenient python API. mcconv correctly works with GEMC LUND (Clas12) format.


Example converting CLAS12 file to HepMC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: bash

    # install mcconv
    pip3 install --upgrade mcconv

    # if there is a sertificate problems
    python3 -m pip install --trusted-host pypi.python.org --trusted-host files.pythonhosted.org --trusted-host pypi.org --user -U mcconv

    # Add home bin directory to the PATH environment variable
    export PATH=~/.local/bin:$PATH

    # convert lund gemc
    mcconv input.txt -i lund_gemc -b 10x100 -v

    # File from example
    mcconv /work/eic/mc/meson_MC/OUTPUTS/0mrad_IR0/nov_2021/pi_n_10.0on100.0_x0.0010-1.0000_q1.0-100.0_lund.dat -v -p 1000



Crossing angle and beam effects
-------------------------------

In order to apply crossing and beam effects to existing HepMC files `EIC Afterbur <https://eicweb.phy.anl.gov/monte_carlo/afterburner>`__
is to be used. The package provides framework independent well validated crossing angle and beam effects C++ library and HepMC file converter (abconv)
for Electron Ion Collider.


**Physics simulated:**

- Crossing angle
- Beam effects (divergence, crabbing kick, etc.)
- Vertex spread (position, time)

Please follow the `instruction of how to use the afterburner <https://eicweb.phy.anl.gov/monte_carlo/afterburner>`__. 


Using converters and afterburner
--------------------------------

Both converters and aferburner are parts of the container. And could be used from JLab and BNL farm.
Follow singularity chapter.