Eur. Phys. J. C (2018) 78:537 Page 9 of 51 537
impact of the various parameters, which can be accessed
through the input files, are described in Sect. 5.
15
After adjusting the input cards to obtain the desired results,
we can start the run by typing
|===>> run
This will start a complete run, no human intervention
is needed from now on. Once the run is finished the
results from the run are collected in the respective folder
result/${run_name} as printed on screen (see Sect. 4.3
for details on the result-folder structure), the most relevant
results, which are the total rates, are also printed on screen
at the very end of the run.
16
We emphasize that for every run
a CITATION.bib file is created and provided inside the
folder result/${run_name}. Please cite these papers
if you use the results of Matrix to acknowledge the efforts
that have been made to obtain these results with Matrix.
When performing a time-extensive (NNLO) run, we rec-
ommend to start Matrix from a window manager (e.g.
screen or tmux) in order to be able to logout from the
present machine during the run. An alternative is to start
Matrix with nohup as explained in the second example of
Sect. 4.4.2.
Running phases of a complete run
A complete run is divided into various stages (running
phases), each of which may be started directly from the
run shell by typing the name of the respective run mode
(${run_mode}). One must bear in mind, however, that
every run stage depends on all previous run stages and will
fail in case one of the previous ones has not finished success-
fully. The order of the run stages is as follows:
• grid-run: First, the integration grids are created in the
warm-up phase (run_grid).
• pre-run: Next, the expected runtimes for the main-run
are extrapolated from a quick pre-run phase (run_pre);
some preliminary results are already printed on screen.
• main-run: Then, the main run is started, computing all
results to the desired precision (run_main).
• result-collection: Finally, the results are collected, and
all distributions are automatically plotted if gnuplot is
installed (run_results).
15
By default the inputs are already set to use reasonable cuts and param-
eters for each process; the default run (without changing the cards)
computes a simple LO cross section with 1% precision, which we rec-
ommend to use when running for the first time in order to test whether
everything is working properly. As this run should be very quick (a
few minutes), this test can be done in local mode (see Sect. 4.5 for the
settings in the file input/MATRIX_configuration).
16
Note that Matrix provides the extrapolated cross section for r
cut
→
0 as a final result at NNLO (and at NLO if the q
T
-subtraction procedure
is used also at NLO) including an extrapolation uncertainty, see Sect. 7,
which is printed on screen after the cross section with a fixed r
cut
value.
Note that the result-collection will always be started auto-
matically after a successful main-run. Furthermore, if the
run mode run_pre_and_main is used, the code will start
from the pre-run (assuming a successful grid-run) and auto-
matically continue with the main-run and result-collection.
Starting from one of these intermediate stages can be use-
ful in many respects. One example is the continuation of a run
after some unwanted behaviour, if some stages have already
passed successfully and one would like to restart from one
of the later stages. Note that all jobs in the requested run
stage are removed and started from scratch. To continue a
run while keeping already successfully finished jobs of the
requested run stage, or to run with increased precision, the
--continue command can be used, see example seven of
Sect. 4.4.2. Another example is running again with a mod-
ified set of inputs. In the latter case it is sufficient to only
restart the main-run as follows:
$ ./bin/run_process
to start the script,
|===>> ${run_name}
to pick up the old run with name ${run_name}, and
|===>> parameter
to change, e.g., the PDF set in the file parameter.dat
(if not done by hand before). It is essential to also uncom-
ment include_pre_in_results = 0 in the same file
in order to avoid mixing of the different settings in pre-run
and main-run in the result combination. After that, the main-
run is started by
|===>> run_main
Other run modes to be selected involve different behaviour
of the code, such as only setting up the folder ${run_name}
and the corresponding subfolders inside input, log and
result (setup_run) without starting the run (this is help-
ful if one wants to change the inputs by hand, but not through
the interface, e.g. by copying the input files from somewhere
else); deleting a given run including its respective subfolders
inside input, log and result (delete_run); etc.
4.4.2 Running with arguments
The run script allows some of the various settings, which are
typically controlled interactively, to be controlled directly
by arguments in its shell command. This enables, e.g., the
possibility to directly start a certain run without having to
interact with the interface. Type
$ ./bin/run_process --help
in order to see all available options.
123