From e654ac8329aa1378f7bcd46e452962883b4f5a8f Mon Sep 17 00:00:00 2001 From: Felix Hekhorn Date: Mon, 27 Nov 2023 16:44:29 +0200 Subject: [PATCH] Rework mg5 docs --- docs/source/external/mg5.rst | 66 ++++++++++++++++++---------- docs/source/external/mg5_cuts.rst | 55 ----------------------- docs/source/external/mg5_launch.rst | 16 ------- docs/source/external/mg5_patches.rst | 19 -------- docs/source/external/yadism.rst | 6 +-- 5 files changed, 47 insertions(+), 115 deletions(-) delete mode 100644 docs/source/external/mg5_cuts.rst delete mode 100644 docs/source/external/mg5_launch.rst delete mode 100644 docs/source/external/mg5_patches.rst diff --git a/docs/source/external/mg5.rst b/docs/source/external/mg5.rst index 87781f0..0879be6 100644 --- a/docs/source/external/mg5.rst +++ b/docs/source/external/mg5.rst @@ -1,17 +1,8 @@ MadGraph5_aMC\@NLO ================== -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - mg5_launch - mg5_cuts - mg5_patches - - -Runcard structure ------------------ +Pinecard structure +------------------ - The ``output.txt`` file (compulsory). This file contains the instructions to generate the source code for the relevant process. For details, please see @@ -20,20 +11,54 @@ Runcard structure ``@OUTPUT@`` must be used to generate the directory containing the source files. -- The ``launch.txt`` file (compulsory). This file contains the instructions to - run the relevant process, including the relevant physical parameters and cuts, - more info in :doc:`mg5_launch`. - - The ``analysis.f`` file (compulsory). This Fortran file must fill the histograms from which the |hwu| files and - the PineAPPL grids are generated. Note that a single histogram must not + the |pineappl| grids are generated. Note that a single histogram must not contain more than 100 bins, otherwise |mg5| will crash. However, big histograms can be split up into multiple histograms, for which the runner - will merge the PineAPPL grids together. + will merge the |pineappl| grids together. - The ``*.patch`` file(s) (optional). These are one or more ``.patch`` files that are applied after |mg5| has generated the sources. +launch.txt (compulsory) +^^^^^^^^^^^^^^^^^^^^^^^ +This file contains the instructions to +run the relevant process, including the relevant physical parameters and cuts. + +Theory parameters +################# + +To insert the actual values of the theory parameters coming from the theorycard +we provide a special syntax. You can use the names +``@GF``, ``@MH@``, ``@MT@``, ``@MW@``, ``@MZ@``, ``@WH@``, ``@WT@``, ``@WW@``, +and ``@WZ@``, which will be replaced with their numerical values upon generation. +The names are the same as chosen by ``mg5_aMC``, but written in +uppercase and surrounded with ``@``. For details about more parameters, please +see the ``Template/NLO/Cards/run_card.dat`` file in |mg5|. + +Cuts +#### + +They are implemented in two steps: + +1. cuts relevant *variables* are defined +2. cuts *code* is implemented + +A list of available codes and variables can be obtained from the +`repository `_. + +Patches +####### + +For instance, to use a dynamical scale, a patch modifying ``setscales.f`` file +should be included in the directory. To create patches use the command ``diff +-Naurb original new > patch.patch``. The patches are applied in an unspecified +order, using ``patch -p1 ...``. + +A list of available patches can be obtained from the +`repository `_. + Additional metadata ------------------- @@ -42,10 +67,10 @@ Additional metadata - ``launch.txt``: contains the generated ``launch.txt`` script (after all substitutions have been done) - ``patch``: a list of patches' names, one per row (corresponding to those - described in :doc:`mg5_patches`) + described in Patches) - ``tau_min``: the minimum :math:`\tau` value set by the user - ``user_cuts``: user defined cuts and cuts values, one per row in the format - ``cut=value`` (cuts are those defined in :doc:`mg5_cuts`) + ``cut=value`` (cuts are those defined in Cuts) - ``mg5amc_repo`` and ``mg5amc_revno``: The repository and revision number of the |mg5| version that was used to generate the grid. @@ -79,6 +104,3 @@ Output The final three columns give the per mille differences of the central, minimum, and maximum scale varied results. Ideally the first two columns are the same and the remaining columns are zero. -- ``pineappl.convolute``: Output of ``pineappl convolute`` -- ``pineappl.orders``: Output of ``pineappl orders`` -- ``pineappl.pdf_uncertainty``: Output of ``pineappl pdf_uncertainty`` diff --git a/docs/source/external/mg5_cuts.rst b/docs/source/external/mg5_cuts.rst deleted file mode 100644 index e7ddd42..0000000 --- a/docs/source/external/mg5_cuts.rst +++ /dev/null @@ -1,55 +0,0 @@ -Cuts -==== - -They are implemented in two steps: - -1. cuts relevant *variables* are defined -2. cuts *code* is implemented - -List of cuts ------------- - -- ``abscoscsmax`` -- ``abscoscsmin`` -- ``atlas_1jet_8tev_r06`` -- ``atlas_2jet_7tev_r06_0005`` -- ``atlas_2jet_7tev_r06_0510`` -- ``atlas_2jet_7tev_r06_1015`` -- ``atlas_2jet_7tev_r06_1520`` -- ``atlas_2jet_7tev_r06_2025`` -- ``atlas_2jet_7tev_r06_2530`` -- ``atlas_dy3d_8tev`` -- ``atlas_wzrap11_cf`` -- ``cms_2jet_3d_8tev`` -- ``cms_2jets_7tev_0005`` -- ``cms_2jets_7tev_0510`` -- ``cms_2jets_7tev_1015`` -- ``cms_2jets_7tev_1520`` -- ``cms_2jets_7tev_2025`` -- ``dyjj`` -- ``minetal`` -- ``mjj`` -- ``mmllmax`` -- ``mtw`` -- ``ptj1min`` -- ``ptl1min`` -- ``ptmiss`` -- ``ptzmax`` -- ``ptzmin`` -- ``yh`` -- ``yll`` -- ``yt`` -- ``yz`` -- ``yzmin`` - - -Cuts variables --------------- - -- ``abscoscs`` -- ``atlas_1jet_8tev_r06`` -- ``atlas_dy3d_8tev`` -- ``atlas_wzrap11_cf`` -- ``cms_2jet_3d_8tev`` -- ``mtw`` -- ``ptmiss`` diff --git a/docs/source/external/mg5_launch.rst b/docs/source/external/mg5_launch.rst deleted file mode 100644 index 2a850db..0000000 --- a/docs/source/external/mg5_launch.rst +++ /dev/null @@ -1,16 +0,0 @@ -Launch -====== - -Here is briefly recapped |mg5|'s '``launch.txt`` -special syntax that is allowed for (and introduced by) pinecards. - - -Special syntax --------------- - -Since the parameter values are inserted by ``run.sh``, do not insert the -numerical values into the text file but rather the run variables. Supported are -``@GF``, ``@MH@``, ``@MT@``, ``@MW@``, ``@MZ@``, ``@WH@``, ``@WT@``, ``@WW@``, -and ``@WZ@``. The names are the same as chosen by ``mg5_aMC``, but written in -uppercase and surrounded with ``@``. For details about more parameters, please -see the ``Template/NLO/Cards/run_card.dat`` file in |mg5|. diff --git a/docs/source/external/mg5_patches.rst b/docs/source/external/mg5_patches.rst deleted file mode 100644 index e166aa7..0000000 --- a/docs/source/external/mg5_patches.rst +++ /dev/null @@ -1,19 +0,0 @@ -Patches -======= - -For instance, to use a dynamical scale, a patch modifying ``setscales.f`` file -should be included in the directory. To create patches use the command ``diff --Naurb original new > patch.patch``. The patches are applied in an unspecified -order, using ``patch -p1 ...``. - -List of available patches -------------------------- - -``change_etaj_to_rapj`` -~~~~~~~~~~~~~~~~~~~~~~~ - -``no_pole_cancellation_checks`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``set_tau_min`` -~~~~~~~~~~~~~~~ diff --git a/docs/source/external/yadism.rst b/docs/source/external/yadism.rst index e65d5db..b04079e 100644 --- a/docs/source/external/yadism.rst +++ b/docs/source/external/yadism.rst @@ -1,8 +1,8 @@ Yadism ====== -Runcard structure ------------------ +Pinecard structure +------------------ - The ``observable.yaml`` file (compulsory). This file contains the description of the observable requested (kind and kinematics), together with further @@ -18,5 +18,5 @@ Additional metadata Output ------ -- ``DATASET.yaml``: is the other |yadism| output format, fully human readable +- ``.yaml``: is the other |yadism| output format, fully human readable (but a bit verbose)