The APPLgrid project
====================

Introduction
------------

This contains the complete development installation of the 
APPLgrid project allowing the user to also generation grids
using custom versions of mcfm and nlojet++ which are included.


If simply performing the fast convolution is required, only 
the appl_grid directory is required, the hoppet installation 
if arbitrary scale changes during the fast convolution is 
required.

Installation prerequisites
--------------------------

Because the whole installation contains several distinct 
packages these is the 

 install.sh 

script, which can guide the installation, although the packages
can also be installed independently, although *please* ensure 
that your path contains instances of the 

 root-config
 lhapdf-config

package config utilities. In addition, if you have hoppet already 
installed, please ensure that 

 hoppet-config

is in your path.

In addition, the APPLgrid convolution code generates a config 
utility of it's own..

 applgrid-config

Please ensure that this is placed in your path also. 

All this can be ensured by specifying the usual 

  --prefix=<installation_base>

either to install.sh, or directly to the 

 ./configure  
 
script calls if building individually. 

In addition, please ensure that your LD_LIBRARY_PATH is set to include
the installation directory for all the dynamic libraries, and that 
if hoppet is installed independently it is installed with compile
option -fPIC for position independent code so it can be linked against 
dynamic library code. 

Installation
------------

By default, include files, libraries and the config utilities mentioned
above are installed in the include, lib and bin directories from the 
installation directory.

The nlojet executable is installed in the bin directory below the 
installation directory. 

A: Install and run the code

1) run the install script 

    install.sh

   the install script can be given arguments

   usage: install.sh [OPTIONS]

     --help| -h   this help
     --all|-a     do everything
     --none|-n    don't do anything
     --appl       install appl_grid
     --pdf        install hoppet
     --mcfm       install mcfm
     --nlo        install nlojet
     --mod        install nlojet module
     --runmcfm    run mcfm
     --runmod     run nlojet module

   The default is to install and run everything (except mcfm) so to 
   eg compile the appl_grid code only you should use

    install.sh --none --appl

   the argument --none being used to switch off everything before 
   enabling the appl_grid compilation.


Additional details, not checked, and which may be somewhat out of date,
but which may in any case, still be of help... 

1) run the setup.sh script (Only if you *really* need to, shouldn't any longer)
2) run the install.sh script. 
3) compile the fillgrid.cxx

   cd $BASEDIR/jetmod

   make fillgrid

4) Make the weighting tables with nlojet
   
   nlojet++ --calculate -c full -u fillgrid.la --max-event 1000010 
 
  (This command explores first the phase space to optimise the
   grid boundaries. In a next step the weighting tables are filled
   There is a problem, if you run to few events, then the program 
   never stops, since no weight file is produce. This we have to change...)

   The weighting tables are in the output directory 
   weight_c.root (central jets)
   weight_f.root (forward jets)

5) Example to convolute the weighting tables with the PDFs and alphas

   make stand

  ./stand output/weight_c.root

6) Check the result
   open root
   .x check.C
   to look at the histogram compring the results of the convolution
   of the grid with the reference histograms

B) Software organisation:

   files and directories in BASEDIRECTORY:
   README this files giving some basic explanations
   setup.sh: setup.sh file to set variables need to run nlojet and standalone
   install.sh: script to install all libraries and run some examples   


   appl_grid: The source code of the applgrid    

   jetmod: nlojet examples to make weight tables and validating them  

   lhpdf-1.0.0: The LHAPDF library interface for nlojet 

   mcfm:  The source library of the mcfm program                  

   nlojet++-4.0.1   The source library of the NLOJET progrom 
   bld-nlo: build directory of the nlojet program  
   bld-pdf: build directory of the nlojet pdf-code implementation  

C) appl_grid software:
   
   a) appl_grid.cxx  and appl_grid.h  (explained below)
   b) appl_igrid.cxx and appl_igrid.h (explained below)
   c) fappl_grid.cxx fortran callable wrapper 

   d) implementation of sparse matrix to store the weighting grid
   
      tsparse1d.h tsparse2d.h
      Sparse3d.h          tsparse3d.h
      sparse.h            tsparse_base.h
      SparseMatrix3d.cxx SparseMatrix3d.h

   e) pdf class, stores the combinations of the variuos pdf 
      elements to the more generalised subprocesses, ie 7 
      for the pp combinations, rather than the 13x13 

       base class: 
       appl_pdf.cxx and appl_pdf.h

       generalised pdf combinations for Z production: 
       mcfmz_pdf.h         
       mcfmz_pdf.cxx       

       for W production:
       mcfmw_pdf.h         
       mcfmw_pdf.cxx         

       and for jet production using either nlojet or jetrad:
       nlojet_pdf.cxx nlojet_pdf.h             
       jetrad_pdf.cxx  jetrad_pdf.h    

   g) helper functions to test CPU performance
       appl_timer.cxx    
       appl_timer.h    

   j) helper function: TObject string vector class for writing string vectors
       TFileString.cxx
       TFileString.h

      The following dictionary files are generated automatically
       TFileStringDict.h
       TFileStringDict.cxx 

Additional documentation (not checked)

        1) appl_grid.cxx  and appl_grid.h  (explained below)
           user interface for the grid software

        2) appl_igrid.cxx  and appl_igrid.h  (explained below)
           internal grid function where the action is

        3) constructors/distructors
        4) operators to add/copy grids

        5) void grid::fill_phasespace(const double x1, const double x2, const double Q2, 
                           const double obs, 
                           const double* weight, const int iorder)

        fill a default grid to explore the phase space in order to
        make a optimised grid in the next step

        6) void grid::trim() untrim() ??
   
        7) void grid::print() ??
           void grid::Write(const string& filename, const string& dirname)
           write the grid to a root file  

        8) void grid::pdfinterp(double x, double Q2, double* f) interpolate the pdfs
        9) convolute the grid with the pdf

        TH1D* grid::convolute(void (*pdf)(const double& , const double&, double* ), 
                      double (*alphas)(const double& ), 
                      int     nloops, 
                      double  rscale_factor,
                      double  fscale_factor,
                      void (*splitting)(const double& , const double&, double* ) )

        The use has to provide a pointer to the follwing functions:
        pdf       the interface to the pdf function
        alphas    the interface to the alphas function
        splitting the interface to the splitting function needed for the
                  factorisation scale dependence
        nloops =0 leading order  =1: next to leading order =-1: only NLO

        rscale_factor  renormalisation scale factor
        fscale_factor  factorsation    scale factor

        make a new operator in this function should be avoided

        10) TH1D* grid::convolute_subproc(int subproc,
                              void (*pdf)(const double& , const double&, double* ), 
                              double (*alphas)(const double& ), 
                              int     nloops, 
                              double  rscale_factor,
                              double  fscale_factor,
                              void (*splitting)(const double& , const double&, double* ) )
       as 9, but for each sub-process

       11) void grid::optimise() 
           void grid::optimise(int NQ2, int Nx)
           
           optimise the grid boundaries

       12) redefine grid boundaries by hand
           void grid::redefine(int iobs, int iorder,
                    int NQ2, double Q2min, double Q2max, 
                    int Nx,  double  xmin, double  xmax )
       

C) Some problems:

   1) on my ubunutu I had problems to run libtool in appl_grid
  
      I got
      libtool  X-tag=CXX command not found
 
       etc

       running autoreconf -i
       in ~/applgrid/appl_grid
       solved the problem