Merge pull request #52 from NNPDF/update-docs

Update docs

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
     hooks:
       - id: pycln
         args: [--config=pyproject.toml]
-  - repo: https://github.com/psf/black
+  - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 24.1.1
     hooks:
       - id: black

README.md

@@ -15,19 +15,8 @@ pinefarm is available via
 pip install pinefarm
 ```
 
-### Dev
-
-For development you need the following tools:
-
-- `poetry`, follow [installation
-  instructions](https://python-poetry.org/docs/#installation)
-- `poetry-dynamic-versioning`, used to manage the version (see
-  [repo](https://github.com/mtkennerly/poetry-dynamic-versioning))
-- `pre-commit`, to run maintenance hooks before commits (see
-  [instructions](https://pre-commit.com/#install))
-
-See [below](.github/CONTRIBUTING.md#non-python-dependencies) for a few more
-dependencies (already available on most systems).
+Please check the [online documentation](https://pinefarm.readthedocs.io/en/latest/install.html) for more detailed
+instructions.
 
 ## Documentation
 - The documentation is available here: <a href="https://pinefarm.readthedocs.io/en/latest/?badge=latest"><img alt="Docs" src="https://readthedocs.org/projects/pinefarm/badge/?version=latest"></a>

docs/source/cli.rst

@@ -1,5 +1,5 @@
-``pinefarm`` command line interface
-===================================
+Command line interface
+======================
 
 You can get the full update help of the command line interface (CLI) with:
 
@@ -17,18 +17,18 @@ Installs various programs, used to run pinecards.
 ``run``
 -------
 
-It is the main command provided, and it runs the specified pinecard in the
+This is the main command provided, and it runs the specified pinecard in the
 context of the selected theory.
 
 The output will be stored in a directory in the current path, with the name
-``<RUNCARD>-<YYYYMMDDhhmmss>``, where:
+``<PINECARD>-<YYYYMMDDhhmmss>``, where:
 
 - the first part is the name of the selected pinecard (that is also the name of
   the folder in which all the files are stored)
 - the second part is the timestamp of the moment in which the command is issued
 
 ``update``
----------
+----------
 
 Update the metadata of the specified grid, with the content of the
 ``metadata.txt`` file in the current version of the pinecard.

docs/source/external/index.rst

@@ -1,41 +1,9 @@
-External runners
-================
+Overview
+========
 
-The ``pinefarm run`` is mainly a uniform interface to some Monte Carlo (and non)
-generator that are able to produce PineAPPL grids.
+`pinefarm` itself is mostly physics agnostic, but the external programs
+contain the actual physics.
 
-Internally the runners are managed through a class system, with a base class
-:class:`~pinefarm.external.interface.External`, that defines the basic
-steps and attributes, while implementing the common actions.
-
-Attributes:
-
-- ``name``: name of the dataset
-- ``theory``: identifier of the theory
-- ``pdf``: PDF used for the comparison
-- ``timestamp``, *optional*: the timestamp of the previous run, if rerunning an
-  already present grid
-
-Computed attributes:
-
-- ``dest``: folder used for all the output
-- ``source``: folder containing pinecard
-- ``grid``: path of the computed grid
-- ``gridtmp``: path used for auxiliary grid (removed at the end of the run)
-
-Steps:
-
-- :meth:`~pinefarm.external.interface.External.install`: further install
-  steps, needed for the runner (not needed if the runner available as a python
-  package on PyPI)
-- :meth:`~pinefarm.external.interface.External.run`: compute the actual
-  predictions
-- :meth:`~pinefarm.external.interface.External.generate_pineappl`: collect
-  predictions into a |pineappl| grid
-- :meth:`~pinefarm.external.interface.External.results`: provide runner
-  results on chosen PDF, for comparison with |pineappl| ``convolute`` ones
-- :meth:`~pinefarm.external.interface.External.annotate_versions`: collect
-  versions of all the program used to compute the results (for reproducibility)
-- :meth:`~pinefarm.external.interface.External.postprocess`: apply any
-  further step specified in :doc:`postprocess file <../pinecards/postrun>`, save
-  :doc:`metadata <../pinecards/metadata>`, and compress the final grid
+If you want to add a new program take a look to the interface class
+:class:`~pinefarm.external.interface.External`
+from which you should derive your new interface.

docs/source/external/int.rst

@@ -0,0 +1,21 @@
+PDF integrability
+=================
+
+These pseudo-observables can be used to enforce the integrability of PDFs in a PDF fit
+- see e.g. :cite:`NNPDF:2021njg`.
+This is a built-in interface.
+
+Pinecard structure
+------------------
+
+- The ``integrability.yaml`` file (compulsory). This file contains the |pid| and kinematics of the pseudo-observable.
+
+Additional metadata
+-------------------
+
+No additional metadata is written.
+
+Output
+------
+
+No additional output files are created.

docs/source/external/mg5.rst

@@ -1,39 +1,66 @@
-Mg5aMC\@NLO
-===========
+MadGraph5_aMC\@NLO
+==================
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+|mg5| :cite:`Alwall:2014hca` :cite:`Frederix:2018nkq` is a general-purpose event generator
+that is mainly used to compute observables in double hadronic environments such as the LHC.
 
-   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
-  `arXiv:1804.10017 <http://arxiv.org/abs/arXiv:1804.10017>`_ and
-  `arXiv:1405.0301 <http://arxiv.org/abs/arXiv:1405.0301>`_. The variable
+  :cite:`Alwall:2014hca` and :cite:`Frederix:2018nkq`. The variable
   ``@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 (histograms with uncertainties) and
-  the PineAPPL grids are generated. Note that a single histogram must not
+  histograms from which the |hwu| files and
+  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 <https://github.com/NNPDF/pinefarm/tree/main/src/pinefarm/external/mg5>`_.
+
+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 <https://github.com/NNPDF/pinefarm/tree/main/src/pinefarm/external/mg5>`_.
+
 Additional metadata
 -------------------
 
@@ -42,10 +69,13 @@ 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.
 
 .. note::
 
@@ -58,7 +88,7 @@ Output
 - ``DATASET``: The directory created by ``mg5_aMC``. A few interesting files in
   this subdirectory are:
 
-  - ``Events/-/MADatNLO.HwU``: histograms with uncertainties (HwU)
+  - ``Events/-/MADatNLO.HwU``: |hwu|
   - ``Events/-/amcblast_obs_-.pineappl``: grids created by ``mg5_aMC``, not yet
     merged together
 
@@ -68,6 +98,11 @@ Output
 - ``launch.txt``: Run card for the 'launch' phase, with all variables substituted
   to their final values
 - ``launch.log``: Output of the external runner during the 'launch' phase
-- ``pineappl.convolute``: Output of ``pineappl convolute``
-- ``pineappl.orders``: Output of ``pineappl orders``
-- ``pineappl.pdf_uncertainty``: Output of ``pineappl pdf_uncertainty``
+- ``results.log``: The numerical results of the run, comparing the results of the
+  grid against the results from ``mg5_aMC``. The first column (PineAPPL) are the
+  interpolated results, which should be similar to the Monte Carlo (MC) results
+  in the second column. The third column gives the relative MC uncertainty
+  (sigma). The next column gives the differences in terms of multiples of sigma.
+  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.

docs/source/external/pos.rst

@@ -0,0 +1,21 @@
+PDF positivity
+==============
+
+These pseudo-observables can be used to enforce the positivity of PDFs in a PDF fit
+:cite:`Candido:2020yat,Collins:2021vke,Candido:2023ujx`.
+This is a built-in interface.
+
+Pinecard structure
+------------------
+
+- The ``positivity.yaml`` file (compulsory). This file contains the |pid| and kinematics of the pseudo-observable.
+
+Additional metadata
+-------------------
+
+No additional metadata is written.
+
+Output
+------
+
+No additional output files are created.

docs/source/external/vrap.rst

@@ -0,0 +1,20 @@
+Hawaiian Vrap
+=============
+
+Hawaiian Vrap :cite:`Barontini:2023vmr` is a modified version of the original Vrap :cite:`Anastasiou:2003ds`.
+It is used to compute observables in fixed-target Drell-Yan experiments.
+
+Pinecard structure
+------------------
+
+- The ``vrap.yaml`` file (compulsory). This file contains the kinematics of the calculation.
+
+Additional metadata
+-------------------
+
+- ``vrap_version``: The Vrap version used to generate the grid
+
+Output
+------
+
+No additional output files are created.