MCEG chapter

docs/howto/mceg.rst

+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
+------------
+
+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.
+
+
+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. 

docs/index.rst

@@ -29,6 +29,7 @@ ATHENA Software
    :maxdepth: 1
    :caption: HOWTOs:
    
+   howto/mceg
    howto/run_fast_simulation
    howto/full_simulation
    howto/use_singularity