applgrid – Hepforge

Convolution Code Download

Basic example code here
A standalone convolution utility is here

The hoppet code version 1.2.0 for QCD evolution from Gavin Salam and Juan Rojo.

Calculation Code

MCFM: (use standard mcfm 6.8 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

Please note, that grids should now be downloaded using the ploughshare website. from the grid download page

Quick Start Guide

how to run the APPLgrid code

Citation

Please cite 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 Mon 14 Mar 2022 17:15:08 GMT