File Map - A short description of the files in HELAC-Onia :

   ====================================
   * input - Input Files              *
   ====================================

	* user.inp: - user's input parameters.
	* process.inp: - process information.
        * default.inp: - default input parameters.
	* seed.input: - seed for Monte Carlo.
	* ho_configuration.txt: - HELAC-Onia configuration file.
	* decay_default.inp: - default decay processes (none).
	* decay_user.inp: - user specified decay processes.

   ====================================
   * src - Matrix Elements Generation *
   ====================================

	* Helac_Global.f90: - declaration of global variables.
	* Helac_Func_1.f90: - helper functions and subroutines.
	* alfas_functions.f90: - MCFM running of alphas.
	* Projectors.f90: - definitions of Clebsch-Gordan coefficients.
	* Constants.f90: - subroutines for reading input parameters.
	* SM_FeynRule_Helac.f90: - Feynman rules of Standard Model.
	* Feynman_Helac.f90: - reconstruction Feynman diagrams.
	* Helac_wavef.f90: - definition of wavefunctions.
	* Helac_pan2.f90: - definition of vertices to be used in Helac_pan1.f90.
	* Helac_pan1.f90: - offshell currents generation via recursive relation.
	* Helac_master.f90: - main file of helicity amplitudes generation. 
	  	** Subroutine Helac_init is designed to generate topologies of Feynman diagrams andto calculate color matrix. 
	  	** Subroutine Helac_master_f will be called via every phase space point to compute the helicity amplitudes.


   ====================================
   * src - Phase Space & Events       *
   ====================================

	* PHEGAS:
	  ** Phegas.f90: - modified PHEGAS in Fortran90 to deal with Quarkonium.
	  ** Phegas_Choice.f90: - helper functions in PHEGAS.
	* VEGAS:
          ** MC_VEGAS.f90: - VEGAS in Fortran90.
	  ** Func_PSI.f90: - helper functions for phase space integration.
	  ** Colliders_PSI1.f90: - phase space integration with VEGAS (only 2 > n (n>=1) at hadron colliders are supported).
	  ** Colliders_PSI2.f90: - phase space integration with VEGAS (only 2 > n (n>=2) at electron positron colliders are supported).
	* MINT:
	  ** mint-integrator.f90: - MINT in Fortran90. 
        * Helac_ranmar.f90: - RANMAR (random number generation) in Fortran90.
	* MC_PARNI_Weight.f90: - PARNI in Fortran90.
	* MC_RAMBO.f90: - RAMBO in Fortran90.
	* MC_Helac_GRID.f90: - grid file.
	* Helac_unwei.f90: - subroutines for dealing with unweighted events.
	* ADAPT.f90: - adaption for optimization.
	* Phegas_Durham.f90: - Durham in Fortran90  to generate massless phase space points.
	* MC_Func.f90: - helper functions and subroutines in Monte Carlointegrations.
	* Kinetic_Func.f90: - functions and subroutines for kinematical variables.
	* Cuts_Module.f90: - imposing kinematical cuts on each phase space points.
	* KT_Clustering.f90: - KT clustering and reweight factor for MLM matching.
        * internal F90 PDF files:
	  ** CTEQ6PDF.f90: - CTEQ6 PDF file in Fortran90 .
	  ** Structf_PDFs.f90: - a file for calling PDFs.
	* LHAPDF files:
	  ** Structf_LHAPDFs.f90 : - a file for calling PDFs from LHAPDF (set "lhapdf=/path/to/lhapdf-config" in input/ho_configuration.txt).
	* setscale.f90: - renormalization and factorization scales definitions.
	* setscale_default.f90: - the default setscale.f90 file.
	* Helac_histo.f90: - histogram drawing file.
	* SinglePro.f90: - main file for phase space integration and events generation (events are generated only when using PHEGAS or VEGAS).
	* Summation_Pro.f90: - summation mode file (not supported).
	* unweight_lhe.f90: - a file to write out Les Houches Events files.
	* FO_plot.f90: - a file for fixed-order plots (no need of unweighted events).
	* Main_Test.f90: - Fortran main program.

   =====================================
   * pdf - Internal PDFs               *   
   =====================================

        * pdf_list.txt: - A summary of internal PDFs in HELAC-Onia
	* make_opts,makefile_pdf: - files of makefile the pdf. A library libpdf.a will be generated in lib directory
	* opendata.f: - Fortran77 file for opening PDF data
	* Partonx5.f: - Standalone Fortran77 Partonx function 
	* CTEQ files:
	  ** cteq3.f: - CTEQ3
	  ** Ctq4Fn.f: - CTEQ4
	  ** Ctq5Par.f,Ctq5Pdf.f: - CTEQ5
	  ** Ctq6Pdf.f: - CTEQ6
	  ** data files are in cteq directory
	* MRST files:
	  ** mrs98.f,mrs98ht.f,mrs98lo.f: - MRS98
	  ** mrs99.f: - MRS99
	  ** mrst2001.f: - MRST2001
	  ** jeppe02.f: - internal file for MRS
        * GS09dPDF files (gsdpdf):
	  ** dpdfgrids: the grids for GS09dPDF.
	  ** gsalps.f: the running of alpha_S with GS09dPDF.
	  ** gsdpdf.f: the calling of GS09dPDF.
	  ** makefile_gsdpdf: the corresponding makefile.

   =====================================
   * shower - shower files             *
   =====================================

	* QEDPS: e-e+ ISR photon shower 
	* HERWIG6: files for using HERWIG6
	* HERWIGPP: files for using HERWIG++
	* PYTHIA6: files for using PYTHIA6
	* PYTHIA8: files for using PYTHIA8.1
	* interface: interface files
	  ** QEDPS_interface.f90: - interface file to QEDPS

   =====================================
   * decay - decay with spin corr.     *
   =====================================

        * DecayInfo.f90: read the decay information from input file.
	* HOVll.f90: generator via spin corr.
	* Decay_interface.f90: decay interface and cutoffs for decay part.
	* stdhep.inc: common block for decay.
	* decay_list.txt: a summary of the available decay processes.

   =====================================
   * cernlib - CERNLib functions       *
   =====================================

        * minuit: minuit source files

   =====================================
   * analysis - analysis files         *
   =====================================

	* hbook subdirectory: - hbook files for plotting
	* user subdirectory: - user defined plot files
	  ** plot_user.f90: - the file for user to plot(s) what his/her wants
	  ** plot_default.f90: - the default plot file
        * PYTHIA8 subdirectory: - Plot files for LHEF+PYTHIA8.
        * HepMC subdirectory: - It contains a useful program to generate plots or ROOT tree file with a HepMC file.
        * heptoptagger subdirectory: - source codes of HEPTopTagger for top quark tagging.
        * include subdirectory: - some including files. For example, HEPMC90.INC is used for defining HepMC common variables.
        * various subdirectory: - some useful tools at the analysis stage.
        * TMVA subdirectory: - some examples for using TMVA contained in ROOT for performing multiply variable analysis.
        * LesHouches subdirectory: - some useful tools for dealing the Les Houches Event files.
        * HepMC subdirectory: - a code for converting HepMC file to histograms or ROOT trees by using FastJet or fjcore.

   =====================================
   * cluster - python script files     *
   =====================================

	* create_subdir.sh: - bash shell script for creating subdirectories in working directory. It is useful for running on the cluster or multi-core.
	* bin:
	  ** ho_cluster: - a executable script file.
	* pythoncode:
	  ** cluster.py: - various cluster classes are defined. It is from MadGraph5_aMC@NLO with some special classes added.
	  ** misc.py: - helpful functions performing routine administrative I/O tasks. It is from MadGraph5_aMC@NLO.
	  ** coloring_logging.py: - logging color (from MadGraph5_aMC@NLO).
	  ** extended_cmd.py: - a file containing different extension of the cmd basic python library. It is also from MadGraph5_aMC@NLO.
	  ** files.py: - methods and classes dealing with file access (from MadGraph5_aMC@NLO).
	  ** helaconia_run_interface.py: - a user friendly command line interface to access HELAC-Onia features.
	  ** helaconia_interface.py: -  a user freindly command line interface to access HELAC-Onia features.

   =====================================
   * jets - Jet related code           *
   =====================================

        * fjcore subdirectory: - A core code for fastjet without jet area and siscone. It also includes Fortran wrapper. It will be automatically linked if system doesn't find FastJet.
        * fastjet subdirectory: - A Fortran wrapper for functions in FastJet. If system find FastJet installed, it will ignore fjcore.
        * merge subdirectory: - the code for the merging of the different multiplicity leading order matrix elements and parton shower.
	 
 
   =====================================
   * Various Files                     *
   =====================================
	
	* config: - bash shell script to link external libraries (e.g. lhapdf) automatically and make.
	* makefile: - makefile. It will be covered by a new one if one uses config.sh. The standalone one is in ./input/template_files
	* CHANGES: - a summary of changes since January 2013.
	* README

   =====================================
   * addon - AddOn Code                *
   =====================================
   
        * addon_process.dat: a list of the available addon processes.
	* pp_psipsi_DPS: ad hoc code for DPS production of pp(p~) > psi+psi+X or pp(p~) > psi+Upsilon+X or pp(p~) > Upsilon+Upsilon+X.
	* pp_psiX_CrystalBall: ad hoc code for pp(p~) > psi+X or Upsilon+X via Crystal Ball.
	* fit_pp_psiX_CrystalBall: ad hoc code for fitting Crystal Ball function to pp(p~) > psi+X.
	* fit_pp_upsilonX_CrystalBall: ad hoc code for fitting Crystal Ball function to pp(p~) > Upsilon+X.
        * fit_pp_QQ_CrystalBall: ad hoc code for fitting Crystal Ball function to pp(p~) > Q+Q~ or open flavor meson.
        * pp_QQ_CrystalBall: ad hoc code for pp(p~) > Q+Q~ or open flavor meson via Crystal Ball.
        * pp_aajj_DPS: ad hoc code for DPS production of pp(p~) > diphoton+dijet.   

   =====================================
   * output - Output Files             *
   =====================================
	
	* All output files are generated in directory output.


Runing Instruction (refer to arXiv:1212.5293):

   To run HELAC-Onia directly:
   -----------------------------------------

   1.Specify input parameters in input/user.inp following the format in default.inp.

   2.Provide process information in input/process.inp, and the decay process information in input/decay_user.inp.
   
   3.Edit configurations for external libraries (like LHAPDF) in input/ho_configuration.txt.

   4.If one wants to plot on the fly, edit the user plot file analysis/user/plot_user.f90.  

   5.If one wants to change the renormalization and factorization scales, edit it in src/setscale.f90.

   6.Compile with the command line:
        > make or ./config

   7.Run with the command line:
        > ./Helac-Onia or ./bin/Helac-Onia
     the output files will be generated in output directory.

   8.If one wants to remove the output files, object files and exectuable file, run the command line:
   	> make clean


   To run HELAC-Onia via python script (refer to arXiv:1507.03435):
   -----------------------------------------

   1.Edit configurations for external libraries (like LHAPDF) in input/ho_configuration.txt.

   2.If one wants to plot on the fly, edit the user plot file analysis/user/plot_user.f90.

   3.If one wants to change the renormalization and factorization scales, edit it in src/setscale.f90.

   4. In the HELAC-Onia directory, compile with the command line:
        > ./config

   5. Go into your working directory. Run it with the script
        > /PATH/TO/HELAC-Onia/ho_cluster

   6. Then one sees the prompt "HO>". There are two steps to run it
      * generation:
        ** Example1: leading-order J/psi pair production
      	HO> generate g g > cc~(3S11) cc~(3S11)
	** Example2: beyond leading-order J/psi pair production
	HO> generate g g > cc~(3S11) cc~(3S11)
	HO> generate g g > cc~(3S11) cc~(3S11) g
	HO> generate u g > cc~(3S11) cc~(3S11) u
	HO> generate g u > cc~(3S11) cc~(3S11) u
	** Example3: addon process (the addon number is in addon_process.txt)
	**           J/psi pair production via DPS, the addon number is "1".
	HO> generate addon 1
      * launch:
        HO> launch

    7. Before launch, one can change the input parameters and assign the decay processes via script:
      * set option = value:
        ** Example1: take the maximum monte carlo number is 100000
        HO> set nmc = 100000
	** Example2: take VEGAS as monte carlo
	HO> set gener = 3
      * decay [process] @ [Branching ratio]
        ** Example1: cc~(3S11) > m+ m- with Br = 0.06
	HO> decay cc~(3S11) > m+ m- @ 0.06d0
	** Example2: w+ > m+ vm with Br = 1d0
	HO> decay w+ > m+ vm @ 1d0    

   Particle ids in HELAC-Onia:
   -----------------------------------------

   nue=1 e=2 u=3 d=4 numu=5 mu=6 c=7 s=8 nutau=9 tau=10 t=11 b=12
   A=31 Z=32 W+=33 W-=34 g=35 H=41 G0=42 G+=43 G-=44 Jet=100
   all antifermions are corresponding negative integers
   Jets are only allowed in the summation mode (summation mode is not supported)
   etac(1S01)=441001, etac(1S08)=441008, psi(3S11)=443011
   psi(3S18)=443018,hc(1P11)=441111,hc(1P18)=441118
   chicJ(3PJ1)=4431J1,chicJ(3PJ8)=4431J8
   similar to Bottomnium but with 44 replaced by 55
   Bc+(3S11)=453011,Bc+(3S18)=453018,Bc-(3S11)=-453011,...

   Particle symbols in HELAC-Onia via python script:
   ----------------------------------------------------

   nue='ve' e='e-' u='u' d='d' numu='vm' mu='m-' c='c' s='s' nutau='vt'
   t='t' b='b' A='a' Z='z' W+='w+' W-='w-' g='g' H='h' G0='g0' G+='g+'
   G-='g-'
   all anti-quark and anti-neutrino are appended by '~', while all anti-charged lepton are represented by replacing '-' with '+'.

   Charmonium ((2S+1)LJ[c]): cc~((2S+1)LJc)
   Bottomnium ((2S+1)LJ[c]): bb~((2S+1)LJc)
   Bc+ ((2S+1)LJ[c]): cb~((2S+1)LJc)
   Bc- ((2S+1)LJ[c]): bc~((2S+1)LJc)

   It is irrelevant to upper or lower cases.

   Main input parameters in HELAC-Onia:
   -----------------------------------------

   (1) [colpar] represents for the type of colliding particles,i.e. 1 for pp,2 for ppbar̄ and 3 fo re+e−.
   (2) [energy_beam1] and [energy_beam2] are the energies (in unit of GeV) of beam 1 and beam 2.
   (3) [gener] specifies the Monte Carlo generator,i.e. 0 for PHEGAS, 1 for RAMBO, 2 for DURHAM and 3 for VEGAS.
   (4) [ranhel] is a parameter to determine whether the program uses the Monte Carlo sampling over the helicity configurations. In specific, if ranhel= 0, it does the helicity summation, while if ranhel> 0, it does the Monte Carlo sampling. If ranhel= 1, the program uses Monte Carlo sampling over the helicities of the elementary particles in the Standard Model and summing over helicities of quarkonia, while if ranhel= 2 it also performs Monte Carlo sampling over L polarization vector for the P-wave states, and ranhel= 3 means it does Monte Carlo sampling over all polarization vectors of heavy quarkonia (of course also over helicites of the elementary particles in the standard-model).
   (5) The value of [qcd] determines the amplitudes should be calculated in which theory,i.e. 0 for only electroweak, 1 for electroweak and QCD, 2 for only QCD, 3 for only QED and 4 for QCD and QED.
   (6) [alphasrun] is a parameter to determine whether the strong coupling constant αS should be running(1) or not(0).
   (7) Flags like [gauge], [ihiggs] and [widsch] determine the gauge(0 = Feynman gauge, 1 = unitary gauge), whether inclusion Higgs(1) or not(0) and using the fixed(0) or complex(1) scheme for the widths of W± and Z bosons.
   (8) [nmc] is the number of the Monte Carlo iterations.
   (9) [pdf] is the PDF set number proposed in pdflist.txt or LHAPDF. Entering 0 means no PDF is convoluted. If one wants to use LHAPDF,please edit ho_configuration.txt and set [lhapdf] to be T.
   (10) [ptdisQ] is a flag whether the pT distribution of the first final quarkonium are calculated(T) or just total cross section(F). If ptdisQ is T, one should also specify which pT value ([Pt1]) should be calculated.
   (11) [Scale] specifies which renormalization (and PDF factorization) scale should be used. It is explained in the comment line of default.inp. If the user chooses the fixed value scheme, he/she should also supply the value of the scale ([FScaleValue]).
   (12) [exp3pjQ] is a flag whether summing over(F) 3PJ, J = 0, 1, 2 or not(T).
   (13) [modes] determines whether the calculated result is the polarized one(1) or not(0). If it is 1, the user should also supply the values of [SDME1] and [SDME2] to let the program know which spin density matrix element to calculate. Meanwhile, the value of [LSJ] represents which "spin" (S,L,or J) in quarkonium should be specified. The user should also specify the polarization frame ([PolarFrame]).
   (14) The parameters of the physical cuts in calculating the cross sections are also should be input by the user if he/she wishes to use his/her values.
   (15) The long distance matrix elements are also supplied in default.inp. The user can supply his/her values in user.inp with the same format in default.inp. The conventions are explained in the comment lines of default.inp.
   (16) [topdrawer_output],[gnuplot_output],[root_output] are plot flags to let HELAC-Onia to plot histograms and output into topdrawer,gnuplot and root files.

   KEEP IN MIND:
   -----------------------------------------

   (1) Only unweighted events are generated by PHEGAS or VEGAS.
   (2) Phase space parameterization with VEGAS is only applied to hadronic/e+e- collisions. All 2 > n are available, where n=1(only hadronic),2,3,....
   (3) PHEGAS can be used to integrate phase space at pp,ppbar and e+e- collisions. However 2 > 1 is not available.
   (4) The transverse momentum distribution of the processes that can be calculated by PHEGAS requires:
       1. The first final particle have to be a quarkonium,i.e., only quarkonium's pt distribution can be calculated by PHEGAS.
       2. Only one quarkonium in the final states if there are other final partons.
       3. Or, several quarkonia production but without any final partons in the process. Otherwise, please use VEGAS to calculate pt distributions.