View source for DEEPGen event generator


= Deep Exclusive Electro- and Photo-production Generator =

This event generator is intended to study some exclusive processes at kinematics of JLab current and future experiments. 
The current version (5.0) supports deep exclusive photo- and electro- production of lepton pairs and photons. 
These reactions involve Deeply Virtual Compton Scattering (DVCS), Timelike Compton Scattering (TCS) and Double Deeply Virtual Compton Scattering (DDVCS).

It also support the following "low virtuality" reactions: Virtual Compton Scattering (VCS), exclusive π° electroproduction, exclusive π+N production

For more details and history, look at the "old" webpage of the event generator (03/2015-12/2018) [[DDVCS and TCS event generator]]

= Content of the generator =

== Principle ==

The framework of this event generator has been primarly developed to perform systematic studies and simulations for exclusive reactions. Its goal is to provide numerous of weights (among other information) for each events in order to study physics impact of a potential reaction measurement. Spin options allow for predicting spin asymmetries, target options allow for studying the target impact in the relative flux (real and quasi-real) in case of photoproduction reactions. 

The event generator itself provides phase-space distributions as a function of invariants (Xbj, Q²...) and angular variables. It is possible to generate unweighted events for any kinematic range in the fix target mode. The weighted mode kinematics has been optimized for 4π acceptance experiments in the JLab@12 GeV area. Close enough kinematics can be generated (model approximations) with minor modifications. 

== Event weighting (physics mode) ==

In the event weighted mode, each event is weighted by a n-differential cross section (see normalization section), to allow to generate physics distributions and get expected counting rates for a specific experiment. Weights are saved in grids, processed independently, and N-dimensionnal linear interpolations allow for % level precision results in comparison to the original model. This method allow for any model to be plug into the generator and for fast event generation compared to direct calculations for each event. 

Each event is weighted by several results: 

W_tot_unpol corresponds to the total differential cross section for a given reaction, including all diagrams for interfering processes,

W_BH, W_TCS... correspond to cross sections if only one of the processes where giving this final state,

W_tot_pol_beam, W_tot_pol_target, W_tot_pol... are weights for polarized beam and/or target cross sections, including spin dilution factors, 

BSA, TSA, BTSA are approximated spin asymmetries for given kinematics, 

cross_tot_unpol... are the differential cross section for photoproduction reactions (TCS...) in case they were actually generated from a lepton beam (and the photon is bremsstrahlung in the target or quasi-real). In case of real photoproduction, W_xxx = cross_xxx.


Case of DIS and elastic scattering: calculation from analytic cross sections

== Reactions ==

Present version support the following reactions:

(version 5.0, June 27, 2019)

1) γ N → e+ e- N (N = proton or neutron) = TCS + BH

Options: unpolarized γ and N, circularly or linearly polarized γ, and/or longitudinally or transverselly polarized proton or neutron

option "tcs" = generate events and calculate cross sections, option "ps_eephoto_fix" generates phase-space. Select photon beam. 

1') e N → γ*(Q²≈0) N → e+ e- N (e') (N = proton or neutron) = TCS + BH from quasi-real beam + bremsstrahlung in the target

option "tcs" = generate events and calculate cross sections, option "ps_eephoto_fix" generates phase-space. Select electron beam.

unpolarized, circularly or linearly polarized photon, longitudinaly or transversely polarized target, off proton or neutron

2) e P → γ*(large Q²) P → e' μ+ μ- P = DDVCS + BH

option "ddvcs" = generate events and calculate cross sections, option "ps_eeel_fix" generates phase-space.

unpolarized or linearly polarized electron, off proton

3) e N → γ*(large Q²) N → e' N' γ = DVCS + BH

option "dvcs" = generate events and calculate cross sections, option "ps_vcs_fix" generates phase-space. off proton or neutron

4) e P → γ*(low Q²) P → e' P' γ = VCS + BH

option "vcs" = generate events and calculate cross sections, option "ps_vcs_fix" generates phase-space (same than for DVCS, just change the Q² value). 

off proton, unpolarized only

5) e P → e' P' π° (low Q²)

option "pi0", option "ps_pi_fix" for phase-space

7) e P → e' N π+ (low Q²)

option "pi+", option "ps_pin_fix" for phase-space

30) DIS

option "dis", unpolarized only, off proton

31) elastic scattering as a function of Q²

option "elastic", unpolarized only, off proton

32) elastic as a function of dΩ(e')

option "elasticlab", unpolarized only, off proton

== Models ==

Cross sections for DVCS+BH, TCS+BH, DDVCS+BH are calculated from VGG model GPDs [Refs. 1-4].

Form Factors are from [] for proton and [] for neutron.

Cross sections for VCS+BH from B. Pasquini MAID 2007

Cross sections for π° and π+ are from MAID2003

== Radiative corrections ==

Based on Mo & Tsai. Calculating bremsstrahlung in the target and internal real corrections as "equivalent radiator". Use virtual photon flux correction factor to rescale the energy to the electron beam after corrections.

In case of TCS, the photon beam is coming from bremsstrahlung and/or quasi-real photons. In that case, outgoing electron can radiate photons, with approximation the interaction happen at half of the target lenght.

For heavy target and high energy beam, possibility to radiate a cascade of photons in the target.

Virtual corrections applied only to VCS process. This part is still in progress.

= How to run =

== Generate events == 

Go to the directory where you copied the generator binary files, then:

1) ./set.csh

2) modify parameters in (process).input file

3) ./DEEPGen (process) (index) (seed)

- just do: ./DEEPGen to see the available options

- (process) = dvcs, tcs, ddvcs, ps_eeel_fix, ps_eephoto_fix, ps_vcs_fix (...) see input options
- (index) = run number index of the output file
- (seed) = random seed, only needed in batch mode

== Process options ==

1. tcs = generation of TCS+BH 5 or 6-fold (un)polarized differential cross section for p and n, weights in dt.dQ'2.dφ.dθ

2. ddvcs = generation of DDVCS+BH 7-fold unpolarized differential proton cross section, weights in dxbj.dt.dQ2.dQ'2.dφL.dφCM.dθCM

3. dvcs = generation of DVCS+BH 4- or 5-fold (un)polarized differential proton cross section for p and n weights in dxbj.dt.dQ2.dφL

4. vcs = generation of VCS+BH 4-fold unpolarized cross section off p, weights in dxbjdtdQ²dφL

5. pi0 = generation of exclusive π° unpolarized cross section off p, weights in dxbjdtdQ²dφL (integrated over π° decay angles)

5. pi+ = generation of exclusive π+ unpolarized cross section off p, weights in dxbjdtdQ²dφL

11. ps_ee_photo_fix = phase space generation for dilepton pair photoproduction (real photon) in fix target experiment

12. ps_eeel_fix = phase space generation for dilepton pair electroproduction in fix target experiment

13. ps_vcs_fix = phase space generation for gamma electroproduction in fix target experiment

15. ps_pi_fix = phase space generation for π° electroproduction in fix target experiment

17. ps_pin_fix = phase space generation for π+ electroproduction in fix target experiment


30. dis = generation of unpolarized cross section for DIS as a function of dxbdQ²

31. elastic = generation of unpolarized cross section for elastic scattering as a function of dQ²

32. elasticlab = generation of unpolarized cross section for elastic scattering as a function of dΩ(e')



21., 22., 23. = collider mode (in progress)

== Normalization == 

For each generated file, save the "TrueEventNumber" of the last generated event. 
It is the number of event which ideally where thrown in a N-D hypercube, if there where no 
kinematic cuts from correlations affecting the distributions.

The weights (W_tot_unpol...) are polarized or unpolarized cross sections. They have to be multiplied by the luminosity and the dimension of the phase space to get the number of counts in a specific experiment. Beam energy is generated flat for TCS from a photon beam and is fixed for DVCS and DDVCS. To get the proper energy distribution for TCS, rescale the flat distribution by a bremsstrahlung or any other profile normalized function.  

For asymmetries (BSA...): no normalization needed, just divide by the number of events in the bin to get an average.

== Phase space factor == 

Definition ΔA = A(max) - A(min) from user input file 

* TCS (electron or photon) 

event weights: dσ/(dt dQ'² dθ dφ)

phase space factor: luminosity*Δ(t)*Δ(Q'²)*Δ(θ)*Δ(φ) / Σ(TrueEventNumber of last event of each files)

NB: compared to past versions, sin(θ) factor to convert cross section in dcos(θ) → dθ is already included in the weights

* DVCS and VCS: 

event weights: dσ/(dt dQ² dxbj d_φ)

phase space factor: luminosity*Δ(t)*Δ(Q²)*Δ(Xbj)*Δ(φ_L) / Σ(TrueEventNumber of last event of each files)

* DDVCS: 

event weights: dσ/(dxbj dt dQ² dQ'² dθ dφ dφ_L)

phase space factor: luminosity*Δ(t)*Δ(Q²)*Δ(Xbj)*Δ(Q'²)*Δ(θ)*Δ(φ)*Δ(φ_L) / Σ(TrueEventNumber of last event of each files)

NB: compared to past versions, sin(θ) factor to convert cross section in dcos(θ) → dθ is already included in the weights

Multiplying the number of event in a specific bin while doing the analysis is giving the generated number of counts in this bin. If an acceptance factor is applied, the number obtained correspond to the predicted number of events for the given experiment.

== Units ==

DVCS+BH and VCS+BH weights are expressed in nb.GeV-4rad-1

TCS+BH weights are expressed in pb.GeV-4.rad-2

DDVCS+BH weights are expressed in pb.GeV-6.rad-3

VCS+BH weights are expressed in pb.GeV-4

exclusive π° or π+N weights are expressed in nb.GeV-4

Default unit for all momenta, invariant mass... is GeV (GeV/c...) and default unit for angle is radians.

Phase space factors for the different reactions are in (reaction cross-section unit)^-1.

= Files: input, output... = 

== Input ==

=== TCS mode ===

The example below generated 5000 TCS+BH events for a circularly polarized real photon beam, issued from a radiator with an initial 100% polarized electron at 11.5 GeV. The target is 40 cm LH2 longitudinally polarized (100%). Events will be printed in ROOT and HEP files.
Modify just the numeric values on lines with no *

 * Electron beam=1 (equivalent photon approximation) or photon beam=0
 * beamtype=
 0
 * Energy range of the photon (maximal range: 5 < Egamma < 11.5 GeV or less than electron energy)
 * Emin=
 5
 * Emax=
 11.4
 * In case of initial electron beam, energy of the incoming electron
 * In case of a fix energy photon beam, electron energy before radiator (used to calculate the polarization)
 * Eelectron=
 11.5
 * In case of initial electron beam, or collimated real photon (not only along z-axis), polar angle limit of the photon (real and/or quasi- real). -> recommended to let it at 0
 * Default = 0 for real photon. If set at 0, the beam is along axis without any dispersion.
 * If set at 0 for quasi-real beam, no cut is applied. Average angles without cut: 5e-5 rad for bremsstrahlung, 1e-2 rad for quasi-real.
 * thetag_max (degree)
 0
 * Number of events to generate
 * NTotEvents =
 5000
 
 * Outgoing particle to study: 1=electron, 2=muon
 * Warning: mass correction is included only for kinematic variables, not in cross sections
 * outlepton=
 1
 * Target lenght in cm and target atoms {A,N} or choose an element instead of A (for LH2 target, set (1,1) or (1001,1)) -> relevant only if use of quasi-real photon beam
 * target type and code = LH2: 1001; He: 1002; LiH: 1003; Carbon: 1006; NH3: 1007;  dry air: 1011; Al: 1013; Fe: 1016; Pb: 1082; lead-glas:  1083.
 * or with atoms, use numbers H (1), He (2), Be (4), N-H3 (7) , Au (79).
 * targetlenght= (cm)
 40
 * Atarget=
 1001
 *Ztarget=
 1
 * TCS on Proton (1) or TCS on Neutron (2)
 * protonorneutron=
 1
 * Beam polarization: degree of linear e- or circular gamma polarization in lab frame (<1)
 * If electron beam, will calculate P_circ as a function of the photon energy
 * If circularly polarized photon beam from bremstrahlung: calculated as a function of energy
 * If linearly polarized photon: set average polarization (energy dependence of P is not included)
 * polbeamdeg (0.8)
 1
 * Real photon polarization type: set 0 if no polarizer used (circular polarization rate is calculated as a fonction of energy transfered to the photon, or it is fixed to beam polarization in case of fix photon energy)
 * set 0 if a linearly polarized electron beam is used or a circularly polarized photon beam (default option)
 * if a linear polarizer is used for photons: 1 = along x-axis, 2=along y-axis, 3=45^0
 * beampolartype (0)
 0
 * Target nucleon polarization, incoherent scattering on proton
 * 0=unpolarized, +1 or +2 = transverse (perp to beam: 1 = x-axis, 2 = y-axis), +3 = longitudinal (same orientation as beam)
 * targetpoldir=
 3
 * degree of target polarization in lab frame(between -1 and +1)
 * poltargetdeg=
 1 
 * limits in -t (maximal range: 0.04 < -t < 2.02 GeV2)
 * mt_min=
 0.04
 * mt_max=
 2.02
 * limits in Q'2 (maximal range: 3.8 < Q'2 < 9.2 GeV2)
 * Qp2min=
 3.8
 * Qp2max=
 9.2
 * outgoing lepton angle in CM frame (maximal range= 30 < th < 150 degree)
 * theta_min
 30
 * theta_max
 130
 * In case of electron beam, maximal Q2 allowed (max=0.3 GeV2)
 * Q2max
 0.3
 * Print in ROOT only: 0, ROOT+HEP: 1, HEP only: 2
 1

=== DVCS mode, similar for VCS ===

 * Energy of the incoming electron (v4 supports only 11 GeV)
 * Eelectron=
 11
 * Number of events to generate
 * NTotEvents =
 5000
 * Target lenght in cm and target atoms {A,N} or choose an element instead of A (for LH2 target, set (1,1) or (1001,1)) -> relevant only if  use of quasi-real photon beam
 * target type and code = LH2: 1001; He: 1002; LiH: 1003; Carbon: 1006; NH3: 1007;  dry air: 1011; Al: 1013; Fe: 1016; Pb: 1082; lead-glas:  1083
 * or with atoms, use numbers H (1), He (2), Be (4), N-H3 (7) , Au (79).
 * targetlenght=
 40
 * Atarget=
 1
 *Ztarget=
 1
 * DVCS on Proton (1) or Neutron (2)
 * protonorneutron=
 2
 * Beam polarization: degree of linear e- or circular gamma polarization in lab frame(<1)
 * polbeamdeg
 1
 * Target polarization.incoherent scattering on proton
 * 0=unpolarized, +1 or +2 = transverse (perp to beam: 1 = x-axis, 2 = y-axis), +3 = longitudinal (same orientation as beam)
 * degree of polarization in lab frame(between -1 and +1)
 * targetpoldir=
 1
 * poltargetdeg= (0.7)
 1
 * limits in -t (maximal range: 0.05 < -t < 2.05 GeV2)
 * mt_min=
 0.05
 * mt_max=
 2.05
 * limits in xbj (maximal range: 0.05 < xbj < 0.5 )
 * xbj_min=
 0.1
 * xbj_max=
 0.5
 * limits in Q2 (maximal range:  0.7 < Q2 < 5.7 GeV2)
 * Q2min=
 0.9
 * Q2max=
 4.5
 * limits in y (not mandatory, for running efficiency 0 to 1)
 * ymin
 0
 * ymax
 1
 * Print in ROOT only: 0, ROOT+HEP: 1, HEP only: 2
 1

=== DDVCS mode ===

 * Energy of the incoming electron
 * Eelectron=?
 11
 * Number of events to generate
 * NTotEvents =?
 5000
 * Outgoing particle to study: 1=electron, 2=muon
 * Warning: only decay into muons
 * outlepton=?
 2
 * Target lenght in cm and target  atoms {A,N}
 * NH3 target: set A=1003 (not yet implemented!!! don't change A and Z please, only target lenght)
 * targetlenght=?
 15
 * Atarget=?
 1
 *Ztarget=?
 1
 * DDVCS on Proton (1)                        
 * protonorneutron= (only proton)
 1
 * Beam polarization: degree of linear e- or circular gamma polarization in lab frame(<1)
 * polbeamdeg
 1 
 * limits in -t (maximal range: 0.04 < -t < 0.84 GeV2)
 * mt_min=?
 0.04
 * mt_max=?
 0.84
 * limits in xbj (maximal range: 0.1 < xbj < 0.3)
 * xbj_min=?
 0.1
 * xbj_max=?
 0.3
 * limits in Q2 (maximal range: 0.9 < Q2 < 4.5 GeV2)
 * Q2min=?
 0.9
 * Q2max=?
 4.5
 * limits in Q'2 (maximal range: 1.7 < Q'2 < 5.3 GeV2)
 * Qp2min=?
 1.7
 * Qp2max=?
 5.3
 * out lepton "minus" angle in CM frame (maximal range= 30 < th < 150 degree)
 * theta_min=?
 30
 * theta_max=?
 150
 * Print in ROOT only: 0, ROOT+HEP: 1, HEP only: 2
 0

== Output ==

Name:
DEEPGen_(xxx).root = root file
DEEPGen_hep_(xxx).root = HEP file (text)
DEEPGen_kin_(xxx).root = relevant information to read associated to the HEP file (text)

Generic output root files contain 2 Trees: 

"SIM_Tree" contain all generated events important information such as 4-vectors for incoming and outgoing particles, kinematic invariants, event weights, event number, polarization information. We detail below the content for each supported process. Note that depending polarization option and event weighting options (phase space or full generation), 
some of the Tree Branch may not be present.

"Dump_Tree" contain additional information such as 4-vectors in different reference frames, initial options... Only the first 50 events are printed.

HEP files (see standard HEP format). 
Associated files can be related by the line numbers.

=== TCS mode ===

Content of SIM_Tree: 

General: 

 ALV_minus_lab   = 4-vector or outgoing lepton in lab frame (all 4-vector "ALV_xxx" are arrays containing: E, px, py, pz)
 ALV_plus_lab    = outgoing anti-lepton in lab frame
 ALV_gamma_in    = incoming photon in lab frame
 ALV_Recoil_lab  = recoil proton in lab frame

 Egamma          = energy of incoming photon
 Qp2             = final photon virtuality
 tt              = t Mandelstam
 ttmin           = minimal t allowed at this kinematic
 Phi_CMV         = azimuthal angle of decay leptons plane versus reaction plane
 Theta_CMV       = polar angle of decay electron versus reaction plane and virtual photon direction
 phi_beam        = azimuthal angle of electron and incoming photon versus x-axis in case of quasi real beam, or arbitrary rotation of the reaction plane in case of real photoproduction
 CosThetagg      = angle between the 2 photons in the gamma-target CM frame

 FlagSing        = if =1, this event is in the near-singularity region and has to be rejected for proper reconstruction (cut in θ, φ)
 thetamin_nocut  = minimal θ above the near-singularity region for this given E, t, Q'²
 EventNumber     = event number
 TrueEventNumber = actual number of events generated in hyper cubical space (for normalization)

Only if events are weighted:

 target_spindir  = spin orientation of target (+1 or -1)
 beam_spindir    = spin orientation of beam (+1 or -1)
 polbeamdeg      = beam polarization transfer times initial electron polarization rate (dilution factor)
 poltargetdeg    = dilution factor of target polarization

 W_tot_unpol     = actual total unpolarized cross section with flux factor for quasi real beam
 W_BH            = B-H "only" unpolarized cross section with flux factor for quasi real beam
 W_TCS           = TCS "only" unpolarized cross section with flux factor for quasi real beam
 W_tot_pol       = beam + target actual polarized cross section (quasi real beam + flux / dilution factors)
 W_tot_pol_beam  = beam only polarized cross section (quasi real photon + flux / dilution factor)
 W_tot_pol_target = target polarized cross section (quasi real photon + flux  / dilution factor)
 BSA             = approximate single beam spin asymmetry at this kinematic (no dilution)
 TSA             = approximate single target spin asymmetry (no dilution)
 BTSA            = approximate double beam and target spin asymmetry (no dilution)

Only in case of incoming electron (quasi-real photoproduction):

 ALV_el_in       = incoming electron in lab frame (case of quasi-real beam only)
 ALV_el_out      = scattered beam electron in lab frame (case of quasi-real beam only)
 Q2              = incoming photon virtuality in case of quasi real beam
 theta_gamma     = polar angle of incoming photon in case of quasi real beam
 theta_beam      = scattered electron polar angle in case of quasi real beam
 yy              = electron beam energy loss
 epsilon         = transverse flux
 VirtualFlag     = if 0 the incoming photon is real (real beam or bremsstrahlung in target), if 1 the incoming photon is quasi real
 Flux_qr         = quasi real equivalent flux
 Flux_bmr        = bremsstrahlung in the target equivalent flux

 cross_tot_unpol = unpolarized cross section for real photon beam
 cross_BH        = Bethe-Heitler "only" unpolarized cross section for real photon beam
 cross_TCS       = TCS "only" unpolarized cross section for real photon beam
 cross_tot_pol   = beam + target polarized cross section (real photon / dilution factors)
 cross_tot_pol_beam = beam only polarized cross section (real photon / dilution factor)
 cross_tot_pol_target = target polarized cross section (real photon / dilution factor)

Only in case of linearly polarized photon: 

 Psi_s           = angle between reaction plane and spin direction of linearly polarized incoming photon (option linear polarization only)
 cross_BH_x      = polarized differential cross section for BH if the beam spin is oriented "in plane" for the given kinematic
 cross_BH_y      = polarized differential cross section for BH if the beam spin is oriented "tangent to plane" for the given kinematic

Only in case of transversely polarized target:

 phi_s           = target spin azimuthal angle versus x+z plane in lab frame
 theta_s         = target spin polar angle versus z-axis in lab frame

=== DVCS or VCS mode ===

 ALV_minus_lab   = 4-vector or outgoing lepton in lab frame (all 4-vector "ALV_xxx" are arrays containing: E, px, py, pz)
 ALV_plus_lab    = outgoing anti-lepton in lab frame
 ALV_gamma_in    = incoming virtual photon in lab frame
 ALV_Recoil_lab  = recoil proton in lab frame
 ALV_gamma_out_lab = outgoing real photon in lab frame
 ALV_el_in       = electron beam incoming in lab frame

 Q2              = incoming photon virtuality in case of quasi real beam
 theta_beam      = scattered electron polar angle in case of quasi real beam
 phi_beam        = azimuthal angle of electron and incoming photon versus x-axis
 yy              = electron beam energy loss
 Xbj             = Bjorken variable
 tt              = t Mandelstam
 ttmin           = minimal t allowed at this kinematic
 Phi_LH          = angle between leptonic (beam, scattered) and reaction plane
 CosThetagg      = angle between the 2 photons in the gamma-target CM frame
 epsilon         = transverse flux

 EventNumber     = event number
 TrueEventNumber = actual number of events generated in hyper cubical space (for normalization)

Only if events are weighted:

 target_spindir  = spin orientation of target (+1 or -1)
 beam_spindir    = spin orientation of beam (+1 or -1)
 polbeamdeg      = beam polarization transfer times initial electron polarization rate (dilution factor)
 poltargetdeg    = dilution factor of target polarization

 W_tot_unpol     = actual total unpolarized cross section
 W_BH            = B-H "only" unpolarized cross section
 BSA             = approximate single beam spin asymmetry at this kinematic (no dilution)
 TSA             = approximate single target spin asymmetry (no dilution)
 BTSA            = approximate double beam and target spin asymmetry (no dilution)

Specific to DVCS:

 W_DVCS           = DVCS "only" unpolarized cross section

Specific to VCS

 W_VCS_born      = VCS "only" unpolarized cross section, contains only the 2 born diagrams for photon emitted by the proton
 W_VCS_nb        = VCS "only" unpolarized cross section, contains only the higher order terms/diagrams (non Born)

Only if transversely polarized target:

 phi_s           = target spin orientation relative to the reaction plane (photons)

=== DDVCS mode ===

Content of SIM_Tree: 

General: 

 ALV_minus_lab   = 4-vector or outgoing lepton in lab frame (all 4-vector "ALV_xxx" are arrays containing: E, px, py, pz)
 ALV_plus_lab    = outgoing anti-lepton in lab frame
 ALV_gamma_in    = incoming photon in lab frame
 ALV_Recoil_lab  = recoil proton in lab frame
 ALV_el_in       = incoming electron in lab frame (case of quasi-real beam only)
 ALV_el_out      = scattered beam electron in lab frame (case of quasi-real beam only)

 Q2              = incoming photon virtuality in case of quasi real beam
 theta_beam      = scattered electron polar angle in case of quasi real beam
 phi_beam        = azimuthal angle of electron and incoming photon versus x-axis
 yy              = electron beam energy loss
 Xbj             = Bjorken variable
 Qp2             = final photon virtuality
 tt              = t Mandelstam
 ttmin           = minimal t allowed at this kinematic
 Phi_LH          = angle between leptonic (beam, scattered) and reaction plane
 Phi_CMV         = azimuthal angle of decay leptons plane versus reaction plane
 Theta_CMV       = polar angle of decay electron versus reaction plane and virtual photon direction
 CosThetagg      = angle between the 2 photons in the gamma-target CM frame
 epsilon         = transverse flux

 EventNumber     = event number
 TrueEventNumber = actual number of events generated in hyper cubical space (for normalization)

Only if events are weighted:

 polbeamdeg      = beam polarization transfer times initial electron polarization rate (dilution factor)
 beam_spindir    = spin orientation of beam (+1 or -1)
 W_tot_unpol     = actual total unpolarized cross section  
 W_BH            = B-H "only" unpolarized cross section 
 W_DDVCS           = DDVCS "only" unpolarized cross section  
 BSA             = approximate single beam spin asymmetry at this kinematic (no dilution)

=== Dump Tree  ===

Tree for versions >= 5.0

contains only one entry. run index, total number of events, phase space, input options from user's file, configuration, target and polarization options...

Tree for versions <= 4.21

This tree is filled only for the first 50 events of the run, and for the last one. 
Use it for checks and for general information.

N.B.: depending which process is generated, some information may be irrelevant or the values are not filled.

 indexrun        = run index, i.e. number of the file given as an input when running the code
 param_initfile  = printout of input parameters as given in the user input file, in the same order (array)
 EventNumber     = event number
 TrueEventNumber = number of events actually generated at this step (for normalization purpose)
 phase_space     = phase space factor according to the user input file

 ALV_minus_lab   = 4-vector or outgoing lepton- in lab frame (all 4-vector "ALV_xxx" are arrays containing: E, px, py, pz)
 ALV_plus_lab    = outgoing lepton+ in lab frame
 ALV_gamma_in    = incoming photon in lab frame
 ALV_el_in       = incoming electron in lab frame (case of quasi-real beam if tcs, or ddvcs)
 ALV_Recoil_lab  = recoil proton in lab frame
 ALV_el_out      = scattered beam electron in lab frame (case of quasi-real beam if tcs, or ddvcs)
 ALV_gamma_out_lab = outgoing (real) photon in lab frame
 ALV_minus_CMV   = lepton- in virtual photon center of mass frame
 ALV_plus_CMV    = lepton+ in virtual photon center of mass frame
 ALV_minus_CMeP  = lepton- in photon-proton center of mass frame
 ALV_plus_CMeP   = lepton+ in photon-proton center of mass frame
 ALV_gamma_CMeP  = incoming photon in photon-proton center of mass frame
 ALV_Recoil_CMeP = recoil proton in photon-proton center of mass frame
 ALV_Virtual_CMeP = final virtual photon in photon-proton center of mass frame
 ALV_Virtual     = final virtual photon in lab frame
 ALV_Target_CMeP = incoming proton in photon-proton center of mass frame

 Q2              = incoming photon virtuality in case of tcs quasi real beam or ddvcs
 theta_beam      = scattered electron polar angle in case of tcs quasi real beam or ddvcs
 phi_beam        = azimuthal angle of scattered electron and photon plane in case of tcs quasi real beam or ddvcs
 yy              = beam electron energy loss
 Xbj             = valid for ddvcs
 Qp2             = final photon virtuality
 tt              = t Mandelstam
 ttmin           = minimal t at this kinematic
 Phi_CMV         = azimuthal angle of decay lepton plane versus reaction plane
 Phi_LH          = azimuthal angle of scattered electron plane versus virtual photon (reaction) plane for ddvcs
 Theta_CMV       = polar angle of decay lepton minus versus virtual photon orientation

== Get output files == 

Depending options, the event output is a ROOT and/or HEP file. 
We advice to generate Root files in order to save as much information as possible in a more efficient way.
If a specific input format is needed to plug the files to Geant (or other) simulation framework, 
the generated events can then be easily printed through a loop in any format needed, with any weighting option.

Versions >5.0

also provides text file readable with simc. additional weights require specific simc version (contact me). 

Log file, version >5.0

important information about the job: total number of events, phase space, index... needed for the normalization. Required to run with simc, modified version

= Public version =

== Binaries ==

version 5.0 = June 2019

/work/halla/solid/mboer/public/Generator_publicversion/version_5_0

The generator binary files are available to users of the JLab ifarm. Copy the whole directory to a place on your home directory. 
For test purpose, also see examples that were generated with specific options.

version 4 = December 2018

- Binaries for the generator are in:
/work/halla/solid/mboer/public/Generator_publicversion/version4

- Example files (root file + used input file) are in:
/work/halla/solid/mboer/public/Generator_publicversion/examples/version4
look at directories for the different processes.

== Special versions ==

Version for hall C BH/Jpsi studies, 
with extension to 0.04 < -t < 6.04 GeV², 3.8 < Q'² < 10.6 GeV². Limit beam energy: 8.5 < E < 11 GeV. 
This version only contain BH+TCS running mode. See Readme file in the directory. Has option to run directly through simc provided that input file take hall c lab axis as reference rather than hms/shms frames.

Latest version:
 
/work/halla/solid/mboer/public/Generator_publicversion/version4.21

NB: upgraded to 4.21 on 02/19/2019: 

version 4.21 has both proton and neutron cross sections and has been checked

version 4.20 is providing neutron rates only and should not been used. 

old: /work/halla/solid/mboer/public/Generator_publicversion/version4.20

== Old versions and history of the generator ==

The "old" webpage of the event generator (2015-2018), for versions 1.0 to 3.1, is available [[DDVCS and TCS event generator]]

= Contact =

For all questions such as how to use the generator, new versions and example files, please contact
Marie Boër, mboer@jlab.org

= References = 

[1] M. Vanderhaeghen, P.A.M. Guichon and M. Guidal, "Deeply virtual electroproduction of photons and mesons on the nucleon: Leading order amplitudes and power corrections", Phys. Rev. D 60 (1999) 094017.

[2] M. Guidal, VGG code, (private communication).

[3] M. Guidal and M.Vanderhaeghen, "Double deeply virtual Compton scattering off the nucleon" Phys. Rev. Lett. 90 (2003).

[4] M. Boër, M. Guidal and M. Vanderhaeghen, "Timelike Compton scattering off the proton and generalized parton distributions" Eur. Phys. J. A 51 (2015) no.8, 103.