Chapter 7
Histograms

7.1 Output

In addition to the direct output of the program to stdout, after all integration regions have completed the warmup stage and a subsequent sweep has been made for each contribution, the program will produce additional output files as specified below. If a working directory was specified in the command line, then these output files will be written to that directory.

The standard output will detail the iteration-by-iteration best estimate of each contribution to the total cross-section, together with the accompanying error estimate. Estimates of the total cross-sectio, summing over all contributions, will be reported in the form:

 Value of integral is    11.7521       0.58456E-02 nb

Other output files may be produced containing various histograms associated with the calculated process. The write-out of the different output files is controlled by the logical variable nohistograms in the extra section. The default value of this variable is .false., but setting it to ṫrue. may be useful for faster running if no histograms are required.

Histograms are written to a srries of files with the generic naming structure:

procname_part_lhapdfset_scale_facscale_runstring_histoname.txt

where procname is a label assigned by the program corresponding to the calculated process; histoname is the name of the histogram specified in the plotting routine (see below) and the remaining labels are as input by the user in the file input.ini.

A default set of histograms is filled for each process. A snippet of the histogram output is repeated below:

# W rapidity
# underflow   0.0000000       0.0000000
# overflow   0.0000000       0.0000000
# sum   10453523.       7919.1419
# xmin xmax cross numerror
 -6.0000000      -5.8000000       0.0000000       0.0000000
 -5.8000000      -5.6000000       0.0000000       0.0000000
 -5.6000000      -5.4000000       0.0000000       0.0000000
 -5.4000000      -5.2000000       0.0000000       0.0000000
 -5.2000000      -5.0000000       7.1413485      0.24680943
 -5.0000000      -4.8000000       1289.2697       28.436126
 -4.8000000      -4.6000000       11218.037       211.10230
 -4.6000000      -4.4000000       36844.231       656.21780

The header lines provide the name of the histogram and the accumulated cross-section and uncertainty entering the bins (sum), as well as any underflow or overflow outide the bins (zero in this case). The following lines report the results in each bin, in the format: bin lower edge, bin upper edge, accumulated cross section, uncertainty. The units of the reported cross-sections are femtobarns.

To modify existing, or add new, histograms one must edit the plotting routine specified in each process description. These are found in the directory src/User/ and correspond to the (default) value .false. for the flag newstyle in the histogram section.

Additional plotting infrastructure was included in the release of CuTe-MCFM, which is enabled by setting histogram%newstyle = .true. in the input file. At present this is only possible for the processes $W^{\text{±}}$, $Z$, $H$, $\mathit{\gamma \gamma }$, $\mathit{Z\gamma }$, $\mathit{ZH}$, $W^{\text{±}}H$, $\mathit{WW}$, $W^{\text{±}}Z$ and $\mathit{ZZ}$. It is the default for the CuTe-MCFM example input files. The predefined plotting routines that can be adjusted in this case are, for example for $Z$ production, in the file src/User/nplotter_Z_new.f90, and similarly for the other processes.

A brief description of the two alteratives for the plotting routines is provided in the subsections below.

7.1.1 Traditional histograms

Traditional histograms are selected with newstyle = .false.

Modifying the plotting routines in the files src/User/nplotter*.f allows for modification of the pre-defined histograms and addition of any number of arbitrary observables. One can also edit the subroutine nplotter_user in the file src/User/nplotter.f, which is also called for every process in order to allow the user to bin their own histograms. Similar to the other routines, the routine is called as:

      subroutine nplotter_user(p, wt,wt2, nd)
      ....
      include 'mxpart.f'
      ....
      real(dp), intent(in) :: p(mxpart,4),wt,wt2
      integer, intent(in) :: nd

The variables passed to this routine are:

• p(1,:): 4-momenta of incoming partons $(i=1,2)$, outgoing leptons and jets $(i=3,4,....)$ in the format p(i,4) with the particles numbered according to the input file and components labelled by (px,py,pz,E).
• wt: weight of this event
• wt2: weight${}^2$ of this event
• nd: an integer specifying the dipole number of this contribution (if applicable), otherwise equal to zero.

Extra histograms may be added to the plotting files in a fairly straightforward manner. Each histogram is filled by making a call to the routine bookplot and updating the histogram counter n by 1. For example, the pseudorapidity of particle $3$ may be plotted using the following code fragment:

      eta3=etarap(3,p)
      call bookplot(n,tag,'eta3',eta3,wt,wt2,-4d0,4d0,0.1d0,'lin')
      n=n+1

The first two arguments of the call should not be changed. The third argument is a string which is used as the title of the plot in the output files. The fourth argument carries the variable to be plotted, which must have been previously calculated. The arguments wt and wt2 contain information about the phase-space weight and should not be changed. The last arguments tell the histogramming routine to use bins of size 0.1 which run from -4 to 4, and use a linear scale for the plot. A logarithmic scale may be used by changing the final argument to ’log’.

7.1.2 New style histograms

New style histograms are selected with newstyle = .true.

The routine setup first allocates the required space to store all histograms. For instance, space for 2 histograms is requested with:

      allocate(histos(2))

Following this, the histograms can be defined either with uniform binning or custum bin sizes. For example, the line:

      histos(1) = plot_setup_uniform(0._dp,500._dp,10._dp,'mZZ')

initializes the first histogram with bins from 0 to 500, of width 10, named mZZ. The second histogram could be initialized with:

      histos(2) = plot_setup_custom([0d0,25d0,50d0,75d0,100d0,150d0,200d0],'ptZZ')

This time the first argument sets up the array of bin edges – 7 edges to define 6 bins – and the histogram is named ptZZ.

After setup, the routine book is called for each phase space point. The plotting routine is provided the momentum configuration (p) and associated Vegas weight (wt). Given these, it returns the array of histograms (ids), calculated observables in the vals array, and Vegas weights in wts. For instance, for the example above this could be accomplished by:

      ptZZ = ptfour(3,4,5,6,p)
      mZZ = puremass(p(3,:)+p(4,:)+p(5,:)+p(6,:))
      ids = histos
      vals = [ptZZ, mZZ]
      wts = [wt, wt]

The specification of weights for individual histograms allows the original Vegas weights to be reweighted for particular distributions, for instance with the output of the transition function in the case of resummed calculations.

7.2 User modifications to cuts and reweighting

The routine gencuts_user can be adjusted in the file src/User/gencuts_user.f90 for additional cuts after the jet algorithm has performed the clustering.

In the same file the routine reweight_user can be modified to include a manual re-weighting for all integral contributions. This can be used to obtain improved uncertainties in, for example, tails of distributions. One example is included in the subdirectory mcfm/src/User/examplesmcfm/src/User/examples, where the reweight_user function approximately flattens the Higgs transverse momentum distribution, leading to equal relative uncertainties even in the tail at 1 TeV.