amcfast is hosted by Hepforge, IPPP Durham

aMCfast - A fast interface between MadGraph5_aMC@NLO and APPLgrid

Running the code

Running MadGraph5_aMC@NLO to produce interpolation grids in the APPLgrid format using the aMCfast interface requires two main steps. The first step consists of setting up and optimizing the interpolation grids that will be subsequently filled up in the second step.
The production of grids is directly connected to a fixed-order analysis in the MadGraph5_aMC@NLO framework. For a more detailed discussion on how to set up a fixed-order analysis, the reader can refer to the manual [arXiv1405.0301], here we just outline the very few additional steps needed to obtain the interpolations grids.

One of the big advantages of the aMCfast interface is the fact that the production of grids does not require any additional coding as compared to a "standard" analysis and it is totally back-compatible. In fact, any working analysis file, possibly used in some past analysis, can be employed without any change.

To illustrate how to produce grids using the aMCfast interface, we consider here a very simple process, i.e. W+ production in proton-proton collision at NLO in QCD.

We first need to start the MadGraph5_aMC@NLO interactive interface, and this is easily done by giving: ./bin/mg5_aMC in the MadGraph5_aMC@NLO main folder. Now we want to generate the process p p → W+ in QCD, so we give: generate p p > w+ [QCD] Once the process has been generated, we need to output it to some forlder and, for instance, we give: output amcfast_test This will dump the relevant code to run the process into the folder "amcfast_test".
Note that we could have omitted the name of the output folder. In this case the code would have chosen some default name, typically PROC*.

Now we can run the process. To this end, we give: launch doing so we get the following message:

The following switches determine which operations are executed:
 1 Perturbative order of the calculation:                              order=NLO
 2 Fixed order (no event generation and no MC@[N]LO matching):   fixed_order=OFF
 3 Shower the generated events:                                       shower=ON
 4 Decay particles with the MadSpin module:                          madspin=OFF
  Either type the switch number (1 to 4) to change its default setting,
  or set any switch explicitly (e.g. type 'order=LO' at the prompt)
  Type '0', 'auto', 'done' or just press enter when you are done.
 [0, 1, 2, 3, 4, auto, done, order=LO, order=NLO, ... ][60s to answer]

This means that by default the code would run in the NLO+PS mode. But for the time being the aMCfast interface works only in the fixed-order mode therefore we need to deactivate the parton shower and this is easily done by typing 2. This way we get the message:

INFO: For coherence 'shower' is set to 'OFF' 
The following switches determine which operations are executed:
 1 Perturbative order of the calculation:                              order=NLO
 2 Fixed order (no event generation and no MC@[N]LO matching):   fixed_order=ON
 3 Shower the generated events:                                       shower=OFF
 4 Decay particles with the MadSpin module:                          madspin=OFF
  Either type the switch number (1 to 4) to change its default setting,
  or set any switch explicitly (e.g. type 'order=LO' at the prompt)
  Type '0', 'auto', 'done' or just press enter when you are done.
 [0, 1, 2, 3, 4, auto, done, order=LO, order=NLO, ... ][60s to answer] 

which confrms that we are about to run MadGraph5_aMC@NLO in the fixed-order mode at NLO, we then give ENTER to go ahead.

Now we get this message:

Do you want to edit a card (press enter to bypass editing)?
  1 / param      : param_card.dat
  2 / run        : run_card.dat
  3 / FO_analyse : FO_analyse_card.dat
 you can also
   - enter the path to a valid card or banner.
   - use the 'set' command to modify a parameter directly.
     The set option works only for param_card and run_card.
     Type 'help set' for more information on this command.
   - call an external program (ASperGE/MadWidth/...).
     Type 'help' for the list of available command
 [0, done, 1, param, 2, run, 3, FO_analyse, enter path][60s to answer] 

We first need to edit the run card, typing 2. To produce grids we cannot use the MadGraph5_aMC@NLO internal PDFs and thus we necessarily have to use LHAPDF. To do so, we just set in the run card: lhapdf = pdlabel ! PDF set
and then we need to specify the identification number of the PDF member that we want to use for the run. If, for instance, we want to use the central replica of the NNPDF23_nlo_as_0118.LHgrid set, we set: 229800 = lhaid ! if pdlabel=lhapdf, this is the lhapdf number Finally, we have to actually enable the grid production. As we said above, the first step consists of setting up an empty grid that will be eventually filled up. In practice, this is done by doing a preliminary "low statistics" run that allows the code to optimize the interpolation grids based on the particular observables defined in the analysis file. Such an optimization acts on the predefined input grids, trimming them in such a way to exclude the unused grid nodes. The parameters of the input grids (number of nodes of the x-space and Q-space grid, interpolation orders, etc.) before the optimization can be set by the user in the analysis file. Otherwise, the code will use the default settings as discussed in the examples section.
To perform this preparatory run, we set in the run card: 1 = iappl ! aMCfast switch (0=OFF, 1=prepare APPLgrids, 2=fill grids) and since at this stage the interpolation grids are not filled up, there is no need of a high accuracy, thus setting something like: 0.01 = req_acc_FO in the run card would be enough.

Now we can save and close the run card and edit the fixed-order analysis card by typing 3. Here we have to specify the analysis file that will be used during the run. Assuming to have written an analysis file named "analysis_amcfast_td_pp_V.f", which is supposed to be the "amcfast_test/FixedOrderAnalysis/" folder, we need to set in the fixed-order analysis card: FO_ANALYSE = analysis_amcfast_td_pp_V.o Of course, the way how the analysis file is written must be consistent with analysis format specified in the fixed-order analysis card itself. In particular, we can set: FO_ANALYSIS_FORMAT = topdrawer or: FO_ANALYSIS_FORMAT = root An example of analysis file for both the format is given in the examples section. However, the way how the interpolation grids are filled is independenf of the analysis format.
We can finally save and close the fixed-order analysis card and start the run by giving ENTER.

If the run finishes successfully, the code will have created the starting grid that now need to be filled up. To do so, we have to run again the code giving: launch -o where the option "-o" ensures that the code restarts the run from the (integration) grids generated in the previous run.

Now a new run starts and the same messages shown above will be displayed. For this second run, we only need to edit the run card and to set: 2 = iappl ! aMCfast switch (0=OFF, 1=prepare APPLgrids, 2=fill grids) In addition, we might want to increase the accuracy of the integration by setting, for example: 0.001 = req_acc_FO This will finally lead to the production of the final interpolation grids which should be found in the "amcfast_test/Events/run_02/" folder. The names of the grids are "aMCfast_obs_0.root", "aMCfast_obs_1.root", "aMCfast_obs_2.root", etc. and they should be as many as the observables defined in the analysis file and the numbering follows the definition order.

Additional options and remarks

A few remarks are in order.
The first remark regards the grids produced with "iappl=1" in the run card. As we said, this step produces empty grids that are optimized and ready to be filled. However, we could produce more than one set of starting grids, possibly changing the interpolation grid parameters or using different statistics to produce them. As a consequence, the strating grids to be used in the second step with "iappl=2" is not always univocally defined. In case no specification is given when giving the command "launch", the code automatically determines which starting grids should be used based on the time stamps of possible grids in amcfast_test/Events/* directories. If instead we want to specify a particular set of starting grids, we can use the "--appl_start_grid" option as follows: launch -o --appl_start_grid=APPL_START_GRID where "APPL_START_GRID" is the name of the folder in the "amcfast_test/Events" directory where the starting grids are supposed to be.

A second important remark regards the combination of different runs with possibly different integration accuracies. If fact, we might want to combine several "high statistics" runs (with "iappl=2") to, for instance improve the global accuracy for a given observable. This is possible by using the "applgrid-combine" script provided by the APPLgrid package. Suppose to have done a number of runs all with different accuracies. In this case in the "amcfast_test/Events" directory we should find the folders "run_01", "run_02", "run_03", etc. (this is true only if we didn't use the option "-n" with the command "launch" to assign a particular name to the runs). To combine the runs for, say, the first observable we could do: cd amcfast_test/Event
applgrid-comibine -o aMCfast_obs_0_combined.root
(note that we skipped the "run_01" folder because it should contain the starting grids that shouldn't be used in the combination). Doing so, we will produce the combined grid "aMCfast_obs_0_combined.root" where the different runs are consistenly combined and weighted according to their integration accuracy.


In order to validate the interpolation grids, it is necessary to check that their convolution with the same PDF set used in the run and the "reference" histograms produced internally by MadGraph5_aMC@NLO are in good agreement with each other. To this end, we have written a small stand-alone validation code that does exactly this.

It is possible to download the validation code from here. It is then necessary to uncompress and complile it by doing: tar xfvz aMCfast_validation.tar.gz
cd aMCfast_validation

The usage is extremely simple. To validate the grids produced in a given run, it is enough to give: ./aMCfast_validation /path/to/the/run/folder/ The code will automatically detect how many observables have been produced, the PDF set used in the run and whether the reference histograms contain or not scale and/or PDF variations. It will then print on screen the ratios between the convolution and the reference histograms at LO, NLO and pure NLO and will produce plots in the ROOT and/or TopDrawer format.