Requirements

You need a
  1. C/C++ compiler (there should be no problems with versions, but we have tested gcc 4.0.1 in mac OS X, gcc version 4.3.2 in Debian and 4.1.2 in Red Hat).
  2. Fortran comiler (g77 and gfortran work, ifort is not yet supported)
  3. A python installation (like gcc, it is already installed in most systems). If you don't have one (i.e. if
    python
    does not invoke the interpreter and
    locate python
    doesn't return anything), you can always install it from
    the official python web site
Optionally, an installation of the ROOT data analysis framework allows for the automatic production of scan plots and histograms.  

Installation

  • STEP ONE: download the source from the download page. The code needs various PDF sets. Currently only MRST and MSTW2008 pdfs are supported. If you already have the older MRST sets or the latest MSTW2008 sets, you can download the latest stable version without the pdfs. Otherwise, download the latest stable version with the pdfs (102MB). The necessary PDFs alone are also provided in the download page.
  • STEP TWO: Untar the source
    tar -zxvpf fehipro3.x.tar.gz
    Change directory to fehipro. The default configuration is using g++ (gcc) and g77. If you want to change to gfortran you have to modify the header of the makefile (fehipro/makefile) *and* the ./configure command of install.sh . Otherwise install by running the script
    ./install.sh
 

Set Up

  • Set the path to the pdfs: when the code runs, it gets its input from an input card, the "runcard", at Run/runcard. The syntax of the runcard will be explained below. One of the variables is called "gridpath". This should be set to the (absolute or relative to the Run/ directory) path to the grids. If the grids are at MYPATH/pdfdat/Grids then set
    gridpath = MYPATH
 

Usage

  • STEP ONE: fehipro interacts with the user through input from the runcard at Run/runcard. To set up a new run, copy the whole directory Run to MY_FIRST_RUN. The original Run directory should be kept for later reference.
    cp -r Run MY_FIRST_RUN
  • STEP TWO: change to MY_FIRST_RUN and customize the runcard to your needs. The syntax and a short description of the various posibilities are described in the Runcard section, below.
  • STEP THREE: run the code
    ./fehipro.py
  • STEP FOUR: collect the results
    ./fehipro.py collect
    The type of results vary depending on the mode of operation (inclusive/exclusive), the perturbative order (LO, NLO, NNLO), and the decay mode.
    • Inclusive run: In the case of a single run, without scans, the total result is located at
      results/m_X/muF_Y_as_Z/CollectedResultsW.txt
      where X is the value of the mass of the Higgs in the run, Y is the factorization scale, Z is the PDF set with respect to the prefered alpha strong value and W is the order in perturbation series (LO,NLO or NNLO). The file includes the central value for the total cross section, the Monte Carlo error and the error due to the PDFs (symmetric and assymetric). In the case of a factorization scale / alpha_s scan there is, on top, a file
      results/m_X/fscan_mXW.txt
      where X is the value of the mass of the Higgs in the run and W is the order in perturbation series. The file contains the data of interest (e.g. the cross section with the pdf errors, if requested, for the various choices of factorization scale defined in the runcard) for the particular scan. In the case of a mass scan, one gets, moreover,
      results/mscanW.txt
      where W is the order in perturbation series. This file contains the values of the total cross section with errors (if requested) for every value of the mass in the mass scan. For each scan there is also a root file produced, of the type
      root*.C
      which, if ROOT is installed, is the code that produces automatically the plots (*.eps) in the respective directories.
    • Exclusive Run: In every local directory
      results/m_X/muF_Y_as_Z
      one finds a series of files that contain results for the current order in perturbation series in all the mass approximations used: heavy top limit (res_mtinfty), including top mass effects (res_top) or including top and bottom mass effects (res_topbottom). Their name is of the form
      results/m_X/muF_Y_as_Z/res_topbottom_NLO.txt
      Moreover, one gets data files for each histogram requested (See how to request a histogram), with names like
      results/m_X/muF_Y_as_Z/Histogram_name.data.txt
      where Histogram_name is the name of the histogram, as declared in the analysis*/intUserHist.F directory (see Histograms). Finally, ROOT script files and plots can be produced if ROOT is installed, see the advanced usage section.
 

Runcard

All statements in the runcard are of the type
keyword = value
There are broadly two separate kinds of input statements. The first kind is input necessary to fix the run. The second kind is only active in the case of an exclusive, differential run: it is input that determines the kinematical cuts imposed on the final state particles, i.e. on the higgs boson, the possible outgoing quarks and gluons, and the decay products of the higgs boson. They are described locally in the template runcard. Below some short explanation is provided for the first kind of input variables:
  • type =
    • exclusive : NNLO differential cross section - allows for decays, distributions and cuts
    • inclusive : fast inclusive NNLO total cross section - no decays, but much much faster
  • decay =
    • none : no decay
    • gamma gamma : decay to two photons
    • WW : decay to WW to lvlv
    • ZZ : decay to ZZ to llll (identical leptons)
    • WW-ZZ : decay to lvlv including WW and ZZ intermediate states
    • ZZ->l1 l1 l2 l2 : decay to two different pairs of leptons
  • m_higgs = 220 : mass of the higgs boson, in GeV. If there is a mass scan, the value is ignored
  • mass_scan =
    • yes : if a mass scan is declared the code runs for every value of m_higgs from mass_scan_low_end (see below) to mass_scan_high_end (see below) with a step of mass_scan_step. This mode of running is available for both inclusive and exclusive runs, but note that each NNLO exclusive run consists of 100 jobs. Also note that all scans can be performed simultaneously.
    • no : no mass scan - the values of mass_scan_low_end, mass_scan_low_end and mass_scan_step are ignored.
  • mass_scan_low_end = 100 : the lowest value for m_higgs in the scan
  • mass_scan_high_end = 300 : the highest value for m_higgs in the scan
  • mass_scan_step = 20 : the step in the scan. For example, a mass scan from 100 to 150 with a step of 10 will run for m_higgs = (100,110,120,130,140,150)
  • factorization_scale = 0.5 : the value for the factorization scale *in units of m_higgs*. For example, if m_higgs=220 and factorization_scale = 0.5 that means that the scale used in the calculation is 110 GeV. If a factorization scale scan is asked, this will be the central value for the factorization scale.
  • factorization_scale_scan =
    • yes : a factorization scale scan is declared. The code will run for the central scale defined above and the two exteremes defined below. This mode of running is available for both inclusive and exclusive runs, but note that each NNLO exclusive run consists of 100 jobs. Also note that all scans can be performed simultaneously.
    • no : no factorization scale scan - the values of factorization_scale_low_end and factorization_scale_high_end are ignored.
  • factorization_scale_low_end = 0.25 : lower extreme, in units of m_higgs.
  • factorization_scale_high_end = 1.0 : higher extreme, in units of m_higgs.
  • factorization_scale_scan_step = 0.25 : step for the scan. This allows for more than the extreme and the central values for the scale.
  • factorization_scale_grid = [0.1,0.25,0.5,1.0,2.0,4.0,10.0] : a concrete grid for the scale values used. This allows for a scan with unequal steps.
  • vary_a_s =
    • yes : varying alpha_s to produce a combined PDF+alpha_s error, when calculating the error due to the pdfs. This produces effectively three different runs: one with the 41 MSTW grids corresponding to the best fited alpha_s value, and two with the grids corresponding to the X% confidence level alpha_s bands. See the MSTW detailed explanation for those.
    • no : the PDF error is calculated with the grids corresponding to the best fitted alpha_s value.
  • perturbative_order =
    • LO : Leading order in alpha_s (cpu time estimate: 1 minute for reasonable monte carlo settings)
    • NLO : Next-to-Leading order in alpha_s (cpu time estimate: 5 minutes for reasonable monte carlo settings)
    • NNLO : Next-to-Leading order in alpha_s (cpu time estimate: 60 minutes for reasonable monte carlo settings in the inclusive mode, days in the exclusive mode)
  • collider = LHC : LHC or Tevatron
  • sqrtS = 7000 : the available energy in GeV
  • electroweak_corrections =
    • off : No electroweak corrections included.
    • only-virtual : Mixed QCD-electroweak corrections included, as calculated at arXiv: 0811.3458.
    • virtual-real : Mixed QCD-electroweak corrections included, as calculated at arXiv: 0811.3458 together with real emmission corrections from arXiv: 0905.2775.
  • massive_corrections =
    • none : The calculation is performed at the heavy top limit and corrected with the ratio of the full LO cross section over the LO cross section in the heavy top limit.
    • top-only : the top mass is fully retained at NLO. At NNLO the heavy-top result is rescaled with the NLO ratio of exact over heavy-top limit.
    • top-bottom : also the bottom mass effects are fully retained to NLO and used in the rescaling factor at NNLO.
  • higgs_width_flag =
    • yes : The calculation is performed with a finite higgs width. The higgs width itself is provided by HDecay
    • no : The calculation is performed in the narrow width approximation.
  • WilsonFile = xxxxx : file that can be used for the redefinition of Wilson coefficients (see advanced use)
  • pdfset = MSTW2008 : also supported are older versions MRST2001, MRST2004, MRST2006 (the necessary pdfs are also provided in the version with the pdfs included)
  • calculate_pdf_error =
    • yes : No pdf error is calculated. The run is performed with the central MSTW grid.
    • no : The run is performed with the various MSTW grids that correspond to a X% CL error estimate, where X is defined by the ConfidenceLevel variable.
  • gridpath = /home/mstw_pdfs : the path to the pdf grids
  • TevatronSpecialScan = false
  • ConfidenceLevel = 68% : determines the confidence level related to the PDF error evaluation. Can be 68% or 90%. If calculate_pdf_error = no its value is irrelevant.
  • ifcluster =
    • yes : The run is performed in a cluster. This means that all different jobs will be submitted via scripts at the same time. The submission syntax currently assumes that the batch system in the cluster is the platform LSF batch system used at ETH.
    • no : The run is performed in a workstation, so jobs are submitted sequentially.
  • walltime = 480 : if running on cluster with queues that have time limits, this is the time in minutes that the job is allowed to run before it is terminated
  • submitts = 4 : if running on cluster with queues that have time limits, this allows you to submit a number of chained jobs (each of which runs after the previous one is terminated)
  • real_run =
    • yes : The run is normally submitted
    • no : Pseudorun - the python script is producing the directory structure and the input files for the c++/fortran executable, but the real calculation is not done. this is useful for debugging purposes as well as for getting an idea of how manu jobs are going to be submitted.
  • accRel = 0.8 : the relative error for the VEGAS algorithm that performs the Monte Carlo integration. The value is in percentage, i.e. 0.8 means 0.8%
  • accAbs = 0.0 : the absolute error for the VEGAS algorithm that performs the Monte Carlo integration. Note that in the exclusive NNLO mode, each sector has its own Monte Carlo integration and hence setting an absolute error limit is dangerous (in view of the existence of sectors with negative central values!!).
  • ncalls = 10000 : number of points per VEGAS iteration. A safe guess is 10000 for inclusive or LO and NLO exclusive mode and 50000 for NNLO differential runs with decays
  • nincr = 0 : increase in points from one iteration to the next
  • ntherm = 10 : number of thermalization iterations. These iterations are used to adjust the grid of VEGAS and then discarded from the final result.
  • root_installed = yes /no : determines whether or not the ROOT analysis framework is installed and hence whether the corresponding scripts and plots that will be produced automatically (see the advanced usage section).
 

Default Histograms and Cuts

The following histograms are provided by default in each decay mode:
  • none : no decay - histograms determined in analysisSrc/initUserHist.F
    • PT HIGGS : the transverse monentum of the higgs boson (low scale)
    • PT HIGGS : the transverse monentum of the higgs boson (low scale)
    • Y HIGGS : the rapidity of the higgs boson (low scale)
    • Y JET : the rapidity of the hardest jet
    • Y JET 2 : the rapidity of the softest jet
    • Y JET-H :
    • Y JET-H2 :
  • gamma gamma : decay to two photons - histograms determined in analysisSrcGG/initUserHist.F
    • PT AVG: the average transverse momentum of the two photons
    • Ystar : the pseudorapidity difference of the two photons
    • PT LEAD : the transverse monentum of the hardest photon
    • PT HIGGS : the tranverse momentum of the higgs boson
    • Y HIGGS : the rapidity of the higgs boson
  • WW : decay to WW to lvlv - histograms determined in analysisSrcWW/initUserHist.F
    • PHILL : the azimuthal separation of the two leptons
    • INV MASS : the invariant mass of the two leptons
    • MET : the missing transverse energy
    • PT HARD : the transverse momentum of the hardest lepton
    • PT SOFT: the transverse momentum of the softest lepton
    • ANN OUT
  • ZZ : decay to ZZ to llll (identical leptons) - histograms determined in analysisSrcZZ/initUserHist.F
    • PT ONE : the transverse momentum of the hardest lepton
    • PT TWO : the transverse momentum of the second hardest lepton
    • PT THREE : the transverse momentum of the third hardest lepton
    • PT FOUR : the transverse momentum of the fourth hardest lepton
    • Y_ONE : the pseudorapidity of the hardest lepton
    • Y_TWO : the pseudorapidity of the second hardest lepton
    • Y_THREE : the pseudorapidity of the third hardest lepton
    • Y_FOUR : the pseudorapidity of the fourth hardest lepton
  • WW-ZZ : decay to lvlv including WW and ZZ intermediate states - histograms determined in analysisSrcWW/initUserHist.F
    • PHILL : the azimuthal separation of the two leptons
    • INV MASS : the invariant mass of the two leptons
    • MET : the missing transverse energy
    • PT HARD : the transverse momentum of the hardest lepton
    • PT SOFT: the transverse momentum of the softest lepton
    • ANN OUT
  • ZZ->l1 l1 l2 l2 : decay to two different pairs of leptons - histograms determined in analysisSrcZZ/initUserHist.F
    • PT ONE : the transverse momentum of the hardest lepton
    • PT TWO : the transverse momentum of the second hardest lepton
    • PT THREE : the transverse momentum of the third hardest lepton
    • PT FOUR : the transverse momentum of the fourth hardest lepton
    • Y_ONE : the pseudorapidity of the hardest lepton
    • Y_TWO : the pseudorapidity of the second hardest lepton
    • Y_THREE : the pseudorapidity of the third hardest lepton
    • Y_FOUR : the pseudorapidity of the fourth hardest lepton
 

Advanced Usage

Using ROOT for automatic plotting:

If the optional runcard parameter root_installed is set to yes then ROOT script files are generated automatically for histograms, in the exclusive mode, and scans. They are also executed automatically and plots are produced in .eps format. This, however, presupposes that ROOT is installed in the system and its path is visible to the bash shell. If any of the above requirements is not met you will be getting messages like failed: sh: root: command not found which can safely be ignored.

Defining further histograms and cuts:

Help