APPLgrid is hosted by Hepforge, IPPP Durham

Home Downloads Documentation Subversion Nightlies News Links

Convolution Code Download
Current version applgrid-1.4.70
Basic example code here
The hoppet code version 1.1.5 for QCD evolution from Gavin Salam and Juan Rojo.


Calculation Code
MCFM: (use standard mcfm code)
mcfm-patch (mcfm applgrid patch 0.0.8)
mcfm-bridge (version 0.0.35 - for mcfm-6.8)
NLOjet++:
nlojet++ 4.0.1 (applgrid version 0.0.2)
nlojet++ lhapdf wrapper 1.0.0 (applgrid version 0.0.2)
nlojet++ user module (applgrid version 0.0.2)

Grid Download
Full details on the Downloads page:

Grids for sqrt(s)=2.76 TeV:
ATLAS inclusive jets (2011 - 0.2pb-1) grids

Grids for sqrt(s)=7 TeV:
ATLAS inclusive jets (2010 - 17nb-1) grids
ATLAS inclusive jets (2010 - 37pb-1) grids
ATLAS inclusive dijets (2010 - 37pb-1) grids
ATLAS inclusive dijets (2011 - 4.5fb-1) grids
ATLAS inclusive jets (2011 - 4.5fb-1) grids
ATLAS W+, W- data (2010 - 35pb-1) grids
ATLAS Z0 data (2010 - 35pb-1) grids

Quick Start Guide
how to run the APPLgrid code

Citation
Please cite the APPLgrid as
Eur Phys J C 66 (2010) 503


Instructions

Using the code

In APPLgrid, each cross section has it's own grid, stored in it's own grid file. For the convolution, you create a grid, specifying which file to use. For instance, a set of jet measurement with 5 different differential cross sections each corresponding to a different rapidity interval, will have 5 separate grids - one for each rapidity interval.

After installing the APPLgrid code itself, everything needed for reproducing a particular cross section is encapsulated in the grid itself - there is no need to download any additional code specific to that cross section.

As a result, unlike the fastNLO package, which requires both a grid file and a separate fortran routine for each cross section, since all information is encoded within the APPLgrid grids themselves it is simply enough to link against the APPLgrid code and call the convolute method for the appropriate grid,
      // read the grid
      appl::grid grid_eta1("atlas-incljets06-eta1.root");
      
      // perform the convolution
      std::vector< double > xsec_eta1 = grid_eta1.vconvolute( evolvepdf_, alphasqcd_ );
    
The convolution will use whichever PDF and alphas routines are passed into it. If you have multiple PDFs set up, no additional code modification is required. For multiple grids, simply create new instances, specifying the appropriate grid file in the constructor. For example
      /// load the grids
      appl::grid grid_eta1("atlas-incljets06-eta1.root");
      appl::grid grid_eta2("atlas-incljets06-eta2.root");
      
      /// perform the convolutions
      std::vector< double > xsec_eta1 = grid_eta1.vconvolute( evolvepdf_, alphasqcd_ );
      std::vector< double > xsec_eta2 = grid_eta2.vconvolute( evolvepdf_, alphasqcd_ );
    

These latest downloadable grids require no additional scaling and in addition, include the non-perturbative (or additional) bin-by-bin corrections discussed in the relevant papers.

By default, the convolution will return just the NLO cross section without application of the additional bin-by-bin. In order to obtain the complete cross section including the bin-by-bin corrections the class method, eg. for grid grid_eta1 then
  grid_eta1.setApplyCorrections(true);
should be called before performing the convolution. All subsequent convolutions will also apply the corrections. To disable this for grid grid_eta1 call
  grid_eta1.setApplyCorrections(false);
and subsequent convolutions will not apply the corrections.

fastNLO interface

There is also an interface for fastNLO grids, however, since these contain multiple different cross sections, the interface returns a vector of grids, that the user is free to call the convolution
      /// read the fastnlo "scenario"
      fastnlo f( gridname );
      
      /// get the individual grids
      std::vector< appl::grid* > g = f.grids(); 
      
      /// vectopr for the different cross sections
      std::vector< std::vector < double > > xsec(g.size());
      for ( int i=0 ; i < g.size() ; i++ ) xsec[i] = g[i]-> vconvolute(  evolvepdf_, alphasqcd_ );
    
Besides the usual setting up of LHAPDF if it is being used etc, no additional coding is required. In addition to the methods which return the cross section values as simple vectors, routines also exist to return the cropss section directly as a root TH1D, with the appropriate binning
      TH1D* hxsec_eta1 = grid_eta1.convolute( evolvepdf_, alphasqcd_ );
    
As with all root usage, the user should remember to delete the histogram when they have finished with it, should it be required.

Fortran interface

There is a fortran interface, however, since the functionality provided by the APPLgrid code is far more than can be expressed using simple fortran code. For instance, in fortran it is not possible to have multiple instances of complex data types. To get round this obvious limitation, specifying a grid by passing some integer identifer is the solution used in the APPLgrid fortran instance. In fastNLO, this limitation gives rise to the need for different functions for each cross section using fastNLO.

If the user must use fortran, we recommend making their basic data structures used in fortran available to code written in C++ and then writing the APPLgrid access code in C++ rather than use the fortran interface. We recommend this approach, since it is usually preferable for the user to write a wrapper for their own fortran code which will use only basic data types and so they will be free to develop this as they wish, and maintain access to the full, rich APPLgrid functionality, rather than have to request access to existing APPLgrid features that are not implemented in the fortran interface due to limitations or the fortran language.

Examples of how to this might be achieved are available in the full source tree. For addition advice, the user can of course contact us.



Getting Started - compiling the example
  • First, ensure that hoppet, root and LHAPDF are installed. Details can be found on the Downloads page.
  • Create a new directory (for example "applgrid") into which you copy the applgrid code
  • From the link in the left menu bar of this page, download the latest version of the applgrid convolution code, and install it using the standard unix autoconf proceedure, ie after downloading and untaring the code
    	  ./configure --prefix=< path_to_install_directory >
    	  make
    	  make install
    	
    This installs the headers, library and executables in the include, lib and bin directories of <path_to_install_directory> above. Often this path is set to /usr/local but to install there, you will require superuser priviledge.
  • Get the applgrid example code from here or the menu on the left.
  • After untaring this you should just be able to go to the new examples directory and build the examples
    	    make
    	  
    Further details are contained in the README file in the directory.

Remarks

There is the useful
      applgrid-config
    
utility which provides locations of the installation directory, useful include and linking flags etc, eg
      % applgrid-config --help
      applgrid-config: configuration tool for the APPLgrid
      fast cross section convolution code
      http://projects.hepforge.org/applgrid/
      
      Usage: applgrid-config [[--help|-h] | [--prefix] | [...]]
      Options:
      --help | -h    : this help
      
      --prefix       : installation prefix (cf. autoconf)
      --incdir       : path to the APPLgrid header directory
      --libdir       : path to the APPLgrid library directory
      --cxxflags     : compiler flags for the C preprocessor
      --ldflags      : compiler flags for the linker just for c code
      --ldfflags     : compiler flags for the linker including the fortan interface
      --share        : path to APPLgrid pdf conbination config files

      --version      : release version number
      
    
For general compilation and linkage with the users own code, the header and library paths can be specifed to the compiler and linker using the applgrid-config utility as follows
      % applgrid-config --ldflags
      -L/usr/local/lib -lAPPLgrid -lfAPPLgrid
      
      % applgrid-config --cxxflags
      -I/usr/local/include
    


Renormalization and Factorization Scales

For grids cross sections up to NLO, all cross sections can be computed with and different scale factors for the renormalisation scales, ie muR, 2muR, 4muR etc. Any, arbitrary numerical scaling factor can be specified by the user, although changes to use a different scale, ie pT, rather than \hat{s} etc are not currently possible. For changes to the factorisation scale, again any arbitrary numerical factor can be specified by the user, although in this case, APPLgrid uses the hoppet package, so this needs to be installed before APPLgrid.


Interfacing your own PDF/alphas code

If you wish to interface your own PDF or alphas code, you simply need to define a function with the same specification at the evolvePDF and alphaQCD routines from the LHAPDF package. Remember that since the LHAPDF routines are in fortran, then your PDF and alphas functions should have extern "C" linkage.


If you have any further questions, please contact the authors at: applgrid @ projects.hepforge.org

Mark Sutton, Pavel Starovoitov, Tancredi Carli, Claire Gwenlan and Gavin Salam - send mail to the authors: applgrid @ projects.hepforge.org: Last updated Fri 14 Apr 2017 11:09:08 CEST