
                CalcHEP Root Directory

INSTALLATION   - instructions for installation.
License.txt    - CalcHEP license.
CITE           - CalcHEP citation, contributions, acknowledgments. 

Makefile       -  'make' commands for compilation. 
               By its first instruction 'make'  calls 
./getFlags     which  creates/checks files: 
FlagsForMake   -  compiler flags in make format.
               This file is  read by other Makefiles   for compilation of CalcHEP
               libraries and  executables.  
FlagsForSh     -  compiler flags in shell script format. It is used in
               CalcHEP symbolic session to   compile  matrix elements for numerical
               calculations.  
c_source/      -  contains subdirectories with CalcHEP C-codes. 
include/       -  header files  needed for compilation of matrix elements.
lib/           - libraries generated by CalcHEP during installation. They are
               used in symbolic session to generate executable n_calchep for numerical
               manipulations.
bin/           - executable  scripts and binary files. This directory is
               exported to WORK  directory for user convenience. This
               directory contains a README file  with short descriptions of all the
               included  routines. 
sbin/          - other scripts which are not called by the user directly.
utile/         - collection of routines and examples which can be useful for a
               user who would like to enlarge the CalcHEP facilities.  It also
               contains a README file with a description of its contents. 
help/          - CalcHEP messages in  text format which appear in the GUI
               sessions by pressing F1. 
pdTables/      - directory for Parton Distribution Tables included in the CalcHEP
               packages by default. The directory 'utile'  contains routines
               wich allow to increase the set of  distributions.

./mkWorkDir    - command which creates a new working directory for user
               sessions. Several such directories can be generated. Files: 
calchep_batch
calchep
calchep.ini    and  directory 
models/        are copied to the user's working directory.
  

work/          User's WORK directory embedded in the CalcHEP  root directory.



        User's WORK directory contains:
 
./calchep            -  script which launches the CalcHEP symbolic GUI sessions.
./calchep_batch      -  script which launches a batch session for symbolic and
                     numerical calculations
calchep.ini          - allows to choose text font(screen size), switch
                     ON/OFF colors and sound signals.   
models/              - directory for CalcHEP models of particle interactions.
tmp/                 - directory for temporary files generated by symbolic
                     session.  
tmp/safe             keeps setting of symbolic session and point of exit. It 
                     allows to continue  terminated session.  In case of problem 
                     one can delete this file to start a symbolic session from the 
                     beginning. 
results/             - directory for compiled library of matrix elements,
                     compiled  executable n_calchep for numerical calculations, 
                     plots  and  distributions generated during numerical sessions. 
results/session.dat  - keeps last setting of numerical session.
results/prt_N        - contains protocol of  N-th Monte-Carlo session.
results/distr_N      - contains distributions denerated in  N-th session.
                     They  can be  displayed by the show_distr routine.
results/aux/so_generated/  
                     - directory for shared libraries of decay processes
                     generated in run-time. 
results/aux/models/  - contains a copy of the model currently used in numerical
                       session

                     The ./calchep_batch command creates the directories: 
Processes/           -  subdirectory which is used  in batch session
                     for generation of codes of matrix elements.
Events/              -  contains results obtained in the batch sessions. Namely 
                     events files in LHE format and  CalcHEP formatted distributions  
html/                -  contains html files which allows to trace a batch
                     session. The start up file is html/index.html.
html/help/           -  contains help pages explaining how to use the batch interface.

       c_sources directory contains subdirectories: 

   SLHAplus
      Contains: 
          Functions useful for model implementation. 
          They are i)  SLHA file reading routines, 
                  ii)  running QCD couplings, 
                 iii)  routines for matrix diagonalizing, 
                  iv)  Passarivo-Veltman functions for effective  Higgs->AA and Higgs->GG vertexes
                   v)  functions presenting loop corrections to  Higgs->AA 
      Generated library:  libSLHAplus.a 
      Description:  [2], [3] section 9

    ntools: 
       Contains:
            simpson integration, Vegas Monte Carlo integrator  and 
            event generator based on it. Random numbers generator. 
       Generated library: ntools.a 
       Description:  
            Vegas:[1] Press, W.H. and Teukolsky, S.A. and Vetterling, 
            Event generation: [3] section 4.7    
            Random number generator is a copy of standard drand48.

    chep_crt: 
       Contains: 
           i)set of basic  routines for screen/keyboard interface realized via X11
             functions. These routines can work in 'blind mode'   when screen output 
             is suppressed  and an input string is used instead of keyboard. See
             [3], section 6. They also can work in 'tex mode'
             writing LaTex file instead of a screen image. 
           ii) routines for screen messages, screen input, menus, work with
               tables, support of on-line help facility.    
        Library:  serv.a

     service2: 
       Contains:
           i) parser for symbolic expressions. Functions which read  identifiers  
              and perform operations with them  are parameters of CalcHEP
              parser.  Several  CalcHEP readers of symbolic expressions are
              based on this parser.   
           ii) on-line arithmetic calculator based in the parser.
          iii) routines  for file comparison and  file search. 
    
       Library: serv.a
       Executable: calc (on-line calculator) 

     getmem: 
        Contains: 
           special memory allocation functions used by the CalcHEP symbolic
           calculator and other routines. They present  mark/getmem/release
           Pascal service.
        Library: serv.a   

     polynom: 
        Contains: 
          functions  for symbolic calculations with polynoms, tensors,
          spinors, Levi-Chivita tensors. 
        Library: symb.a

     symb: 
        Contains:
          menu system of symbolic part (see section 3 of [3]) 
          routines for  reading model files, control of user input  of process, 
          diagrams generation, diagram squaring, diagram symbolic calculation,
          C/REDUCE/MATHEMATICA output of symbolic expressions for diagrams. 
        Library: symb.a 
          Executables:
              s_calchep  (main program of CalcHEP launched by script ./calchep).
              make_VandP  program which generates and compiles codes
                  of CalcHEP constraints.  
     plot: 
         Contains:
           routines for graphical presentation of plots in CalcHEP
         Library: serv.a
         Executable: plot_view - allows to display on the screen plots and
         histograms generated by CalcHEP and stored in files.  
        
     num: 
       Contains: 
          menu system of numerical  part (see section 4 of [3]);
          Input of parameters and constraints presentation; 
          codes for histogram filling, cuts definition/application, phase space mapping; 
          Vegas and Event generator calls; 
       Library: num_c.a, sqme_aux.so, 
                dummy.a  -  a dummy library of user defined functions. If user 
                version of such functions is  absent then dummy one are used by
                linker. See sections 4.5  of [3]. 
       Object file:  n_calchep.o - main code for n_calchep
       Executables:  Int - command-line integrator (a by-product of CalcHEP)    
            
     dynamicME:
        Contains: 
           codes for dynamic generation and linking  of shared libraries of matrix
           elements and codes for numerical calculation of decay processes
           loaded dynamically. It calls bin/s_calchep via script sbin/newProcess.
        Description: [3] Section 10  
        Libraries:
            dynamic_me.a 
            dynamic_vp.a

   Root: Auxiliary routines for  generation of matrix elements in Root system.
      Description: [3] Section 9.8
 
     mix_events:
        Contains: 
          programs  which mix different event flows generated by  n_calchep, 
          apply decay processes to them and present  final events in LHA
          format  
        Description:  [3] Section 5
        Executables: $(bin)/event_mixer  $(nt_maker) $(bin)/event2lhe
     
    tabs:
       Contains: 
         programs which supports manipulation with distributions generated
         in  numerical CalcHEP sessions.
       Description:  [3] Section 5
       Executables: events2tab  show_distr  sum_distr lhe2tab
 
Bibliography 

[1] Press, W.H. and Teukolsky, S.A. and Vetterling,  W.T. and Flannery,B.P.,
        "Numerical recipes in C: the art of scientific computing" 

[2] arXiv:1008.0181
[3] arXiv:1207.6082
 