Merge pull request #82 from NNPDF/docs-delivery

Add delivery page to docs
NNPDF · Feb 16, 2023 · 230acfb · 230acfb
2 parents f5c3827 + 9f6c58d
commit 230acfb
Show file tree

Hide file tree

Showing 9 changed files with 207 additions and 78 deletions.
diff --git a/README.md b/README.md
@@ -1,55 +1,45 @@
-<h1 align="center">NνSF</h1>
-
-NνSF is a python module that provides predictions for neutrino structure functions. It relies on [Yadism](https://github.com/N3PDF/yadism) for the large-$Q^2$ region while the low-$Q^2$ regime is modelled in terms of a Neural Network (NN).
-
-## Installation & Development
-
-The package can be installed from source using the following commands:
-
-```bash
-git clone https://github.com/NNPDF/nnusf.git --depth 1
-cd nnusf
-poetry install
+<h1 align="center">NNSFν</h1>
+<p align="center">
+  <img alt="Zenodo" src="https://zenodo.org/badge/DOI/10.1101/2023.02.15.204701.svg">
+  <img alt="arXiv" src="https://img.shields.io/badge/arXiv-2223.04638-b31b1b?labelColor=222222">
+  <img alt="Docs" src="https://assets.readthedocs.org/static/projects/badges/passing-flat.svg">
+  <img alt="Status" src="https://www.repostatus.org/badges/latest/active.svg">
+  <img alt="License" src="https://img.shields.io/badge/License-MIT-yellow.svg">
+</p>
+
+NNSFν is a python module that provides predictions for neutrino structure functions. 
+It relies on [Yadism](https://github.com/N3PDF/yadism) for the large $Q^2$ region 
+while the low $Q^2$ regime is modelled in terms of a Neural Network (NN). The NNSFν 
+determination is also made available in terms of fast interpolation
+[LHAPDF](https://lhapdf.hepforge.org/) grids that can be accessed through an independent
+driver code and directly interfaced to the [GENIE](http://www.genie-mc.org/) neutrino 
+event generators.
+
+# Quick links
+
+- [Installation instructions](https://nnpdf.github.io/nnusf/quickstart/installation.html)
+- [Tutorials](https://nnpdf.github.io/nnusf/tutorials/datasets.html)
+- [Delivery & Usage](https://nnpdf.github.io/nnusf/delivery/lhapdf.html)
+
+# Citation
+
+To refer to NNSFν in a scientific publication, please use the following:
+```bibtex
+@article {reference_id,
+   author = {Alessandro Candido, Alfonso Garcia, Giacomo Magni, Tanjona Rabemananjara, Juan Rojo, Roy Stegeman},
+   title = {Neutrino Structure Functions from GeV to EeV Energies},
+   year = {2023},
+   doi = {10.1101/2020.07.15.204701},
+   eprint = {https://arxiv.org/list/hep-ph/},
+   journal = {aRxiv}
+}
 ```
-
-This also provides the user the ability to develop on the codes.
-
-## Usage
-
-NνSF provides an extensive Command Line Interface (CLI) that permits the user to perform various classes of tasks. To know more about all the available options, just run `nnu --help`. For convenience, below we provide details on how the fitting part of the codes can be run.
-
-#### Perform a fit
-
-To run a fit, one can simplify type the following commands:
-
-```bash
-nnu fit run <runcard> <replica> -d <output_path>
+And if NNSFν proved to be useful in your work, consider also to reference the codes:
+```bibtex
+@article {reference_id,
+   author = {Alessandro Candido, Alfonso Garcia, Giacomo Magni, Tanjona Rabemananjara, Juan Rojo, Roy Stegeman},
+   title = {Neutrino Structure Functions from GeV to EeV Energies},
+   year = {2023},
+   doi = {10.1101/2020.07.15.204701},
+}
 ```
-An example of a runcard to perform a fit is [./runcards/fit_runcard.yml](./runcards/fit_runcard.yml).
-
-This will generate inside the folder `<output_path>` a folder named `replica_<replica>` which in turn contains a tensorflow model that can be used to generate predictions. In general, one needs to run the above command for `replica={1, ..., n}`.
-
-#### Perform a Postfit
-
-If needed, one can perform a post-selection on the replicas generated from the fit. For instance, one can only select the replicas whose $\chi^2$ values are below some thresholds. Below is an example in which we only select replicas with $\chi^2_{\rm tr}$ and $\chi^2_{\rm vl}$ below `10`:
-```bash
-nnu fit postfit <output_path> -t '{"tr_max": 10, "vl_max": 10}'
-```
-This will generate inside `<output_path>` a folder named `postfit` which contains the replicas that satisfy the selection criteria.
-
-#### Generate a report & Predictions
-
-To generate a report from a fit, one can simply run:
-```bash
-nnu report generate <output_path>/postfit -t "<Title>" -a "<author>" -k "<keyword>"
-```
-This will generate a folder called `output` inside `<output_path>` which contains an `index.html` summarizing the results. If `postfit` was not run in the previous step, simply remove `/postfit` in the command above.
-
-Finally, to generate predictions using the trained models, just run the following commands:
-
-```bash
-nnu plot fit <output_path> <runcard>
-```
-An example of such a runcard is [./runcards/generate_predictions.yml](./runcards/generate_predictions.yml).
-
-This will generate a `.txt` file containing the NN predictions for the different structure functions.
diff --git a/docs/source/assets/nnusf_xsec.png b/docs/source/assets/nnusf_xsec.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -66,9 +66,21 @@
     "sidebar_hide_name": False,
     "top_of_page_button": "edit",
     "navigation_with_keys": True,
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/pradyunsg/furo",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
diff --git a/docs/source/delivery/lhapdf.rst b/docs/source/delivery/lhapdf.rst
@@ -0,0 +1,110 @@
+Grids & Usage
+=============
+
+LHAPDF grids
+------------
+
+The NNSFν structure function grids are available in the LHAPDF format
+for various nuclear targets. For a given nuclear target, the grids is
+split into small- and large-:math:`Q`, which could be combined according
+to a prescription described below.
+
+.. list-table:: LHAPDF GRIDS
+   :widths: 30 60 60
+   :header-rows: 1
+
+   * - :math:`(Z, A)` [target]
+     - Low-:math:`Q` Grid
+     - High-:math:`Q` Grid
+   * - :math:`(1, 2)`
+     - `NNSFnu\_D\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_D_lowQ.tar.gz>`_
+     - `NNSFnu\_D\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_D_highQ.tar.gz>`_
+   * - :math:`(2, 4)`
+     - `NNSFnu\_He\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_He_lowQ.tar.gz>`_
+     - `NNSFnu\_He\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_He_highQ.tar.gz>`_
+   * - :math:`(3, 6)`
+     - `NNSFnu\_Li\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Li_lowQ.tar.gz>`_
+     - `NNSFnu\_Li\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Li_highQ.tar.gz>`_
+   * - :math:`(4, 9)`
+     - `NNSFnu\_Be\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Be_lowQ.tar.gz>`_
+     - `NNSFnu\_Be\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Be_highQ.tar.gz>`_
+   * - :math:`(6, 12)`
+     - `NNSFnu\_C\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_C_lowQ.tar.gz>`_
+     - `NNSFnu\_C\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_C_highQ.tar.gz>`_
+   * - :math:`(7, 14)`
+     - `NNSFnu\_N\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_N_lowQ.tar.gz>`_
+     - `NNSFnu\_N\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_N_highQ.tar.gz>`_
+   * - :math:`(8, 16)`
+     - `NNSFnu\_O\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_O_lowQ.tar.gz>`_
+     - `NNSFnu\_O\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_O_highQ.tar.gz>`_
+   * - :math:`(13, 27)`
+     - `NNSFnu\_Al\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Al_lowQ.tar.gz>`_
+     - `NNSFnu\_Al\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Al_highQ.tar.gz>`_
+   * - :math:`(15, 31)`
+     - `NNSFnu\_Ea\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Ea_lowQ.tar.gz>`_
+     - `NNSFnu\_Ea\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Ea_highQ.tar.gz>`_
+   * - :math:`(20, 40)`
+     - `NNSFnu\_Ca\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Ca_lowQ.tar.gz>`_
+     - `NNSFnu\_Ca\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Ca_highQ.tar.gz>`_
+   * - :math:`(26, 56)`
+     - `NNSFnu\_Fe\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Fe_lowQ.tar.gz>`_
+     - `NNSFnu\_Fe\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Fe_highQ.tar.gz>`_
+   * - :math:`(29, 64)`
+     - `NNSFnu\_Cu\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Cu_lowQ.tar.gz>`_
+     - `NNSFnu\_Cu\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Cu_highQ.tar.gz>`_
+   * - :math:`(47, 108)`
+     - `NNSFnu\_Ag\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Ag_lowQ.tar.gz>`_
+     - `NNSFnu\_Ag\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Ag_highQ.tar.gz>`_
+   * - :math:`(50, 119)`
+     - `NNSFnu\_Sn\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Sn_lowQ.tar.gz>`_
+     - `NNSFnu\_Sn\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Sn_highQ.tar.gz>`_
+   * - :math:`(54, 131)`
+     - `NNSFnu\_Xe\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Xe_lowQ.tar.gz>`_
+     - `NNSFnu\_Xe\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Xe_highQ.tar.gz>`_
+   * - :math:`(74, 184)`
+     - `NNSFnu\_W\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_W_lowQ.tar.gz>`_
+     - `NNSFnu\_W\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_W_highQ.tar.gz>`_
+   * - :math:`(79, 197)`
+     - `NNSFnu\_Au\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Au_lowQ.tar.gz>`_
+     - `NNSFnu\_Au\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Au_highQ.tar.gz>`_
+   * - :math:`(82, 208)`
+     - `NNSFnu\_Pb\_lowQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Pb_lowQ.tar.gz>`_
+     - `NNSFnu\_Pb\_highQ <https://data.nnpdf.science/NNSFnu/NNSFnu_Pb_highQ.tar.gz>`_
+
+The structure function grids can then be used to compute the
+double differential cross-sections using the following command:
+
+.. code-block:: bash
+
+   nnu extra compute_xsecs ${SET_NAME} [-q '{"min": 1e-3, "max": 400, "num": 100}]' [-q ${type}]
+
+where :mod:`type` can be either :mod:`neutrino` or :mod:`antineutrino`, if not
+specified the default value is chosen to be :mod:`neutrino`.
+
+One can also from a given structure function set compute the integrated
+cross-sections via the command:
+
+.. code-block:: bash
+
+   nnu extra integrated_xsecs ${SET_NAME} [-q '{"min": 1e-3, "max": 400, "num": 100}]' [-q ${type}]
+
+
+NNSFν pre-trained model
+-----------------------
+
+We also make publicly available the pre-trained NNSFν model used to generate
+the predictions published in the paper. The model can be downloaded at the
+following `link <https://data.nnpdf.science/NNUSF/Models/nnsfnu.tar.gz>`_.
+Such a model can be used for various purposes but as explained in the
+tutorial part it can be mainly used to generate structure function grids:
+
+.. code-block:: bash
+
+   nnu fit dump_grids nnsfnu/postfit -a ${A_VALUE} -o ${SET_NAME} [-q '{"min": 1e-3, "max": 500, "num": 100}]'
+
+
+.. note:: 
+
+   If one encouters the issue that the git version does not match, one just
+   needs to checkout to the commit from which the fit was generated.
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -93,6 +93,13 @@ If NNSFν proves to be useful in your work, please also reference the codes:
    tutorials/yadism
    tutorials/fitting
 
+.. toctree::
+   :maxdepth: 2
+   :caption: 📦 Delivery
+   :hidden:
+
+   delivery/lhapdf
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

diff --git a/docs/source/quickstart/description.rst b/docs/source/quickstart/description.rst
@@ -1,19 +1,19 @@
 Description
 ===========
 
-NNSFν is a python package that can be used to compute of (anti-)neutrino structure
+NNSFν is a python package that can be used to compute (anti-)neutrino structure
 functions at all energies. It relies on `Yadism <https://github.com/N3PDF/yadism>`_
 for the description of the medium- and large-:math:`Q^2` regions while the 
 low-:math:`Q^2` regime is modelled in terms of a Neural Network (NN).
 
 .. image:: ../assets/matching.png
-   :width: 550
+   :width: 800
    :align: center
    :alt: Strategy to parametrise the structure functions
 
-The low- and intermediate-:math:`Q^2` regions we construct a parametrisation of
+In the low- and intermediate-:math:`Q^2` regions we construct a parametrisation of
 the neural network structure functions with its associated uncertainties by training
-a machine learning model to available experimental data. Given an observable
+a machine learning model to available experimental data. That is, given an observable
 :math:`\mathcal{O}` that is defined as a linear combination of structure functions:
 
 .. math::
@@ -28,4 +28,16 @@ we fit the structure functions :math:`F_i^{k} \equiv F_i^{k} \left( x, Q^2, A \r
 for :math:`i=2, 3, L` and :math:`k =\nu, \bar{\nu}`. Note that for :math:`i = 3` we
 actually fit :math:`xF_3` instead of :math:`F_3`. The coefficients :math:`C_j` which
 depend on :math:`(x, Q^2, y)` are computed using Yadism and they have to match data
-point per data point to the experimental datasets.
+point per data point to the experimental datasets while the normalisation :math:`N`
+depends on how the observable is measured experimentally.
+
+
+The resulting predictions from NNSFν is also made available in terms of fast interpolation
+`LHAPDF <https://lhapdf.hepforge.org/>`_ grids that can be accessed through an independent
+driver code and directly interfaced to the `GENIE <http://www.genie-mc.org/>`_ Monte Carlo
+event generator.
+
+.. image:: ../assets/nnusf_xsec.png
+   :width: 550
+   :align: center
+   :alt: Strategy to parametrise the structure functions
diff --git a/docs/source/tutorials/datasets.rst b/docs/source/tutorials/datasets.rst
@@ -1,5 +1,5 @@
 Adding new datasets
-==============
+===================
 
 The following is not mandatory in order to run a fit given that all the
 necessary inputs in order to reproduce the published NNSFν have already
@@ -11,7 +11,7 @@ Yadism.
 
 
 Implementation of the experimental dataset
---------------------
+------------------------------------------
 
 The implementation of a new data set starts by downloading the
 `hepdata <https://www.hepdata.net/>`_ tables and store them in
@@ -79,9 +79,7 @@ We can now generate the grids containing the predictions using the following:
 
 .. code-block:: bash
 
-   nnu grids # for general matching
-    # or
-   nnu grids # for proton boundary condition
+   nnu theory grids ${path_to_data_card}
 
 In order to generate the central values and uncertainties for the matching data sets
 we need to convolute the grids with the corresponding nuclear PDFs (nPDFs). To do

diff --git a/docs/source/tutorials/fitting.rst b/docs/source/tutorials/fitting.rst
@@ -108,36 +108,36 @@ For future convenience, the NNSFν predictions can be stored as LHAPDF
 grids. The structure functions have the following LHAPDF IDs:
 
 .. list-table:: LHAPDF ID
-   :widths: 60 50
+   :widths: 20 20 20 20 20 20 20 20 20 20
    :header-rows: 1
 
-   * - Structure Functions
-     - LHAPDF ID
-   * - :math:`F_2^{\nu}`
+   * - SFs
+     - :math:`F_2^{\nu}`
+     - :math:`F_L^{\nu}`
+     - :math:`xF_3^{\nu}`
+     - :math:`F_2^{\bar{\nu}}`
+     - :math:`F_L^{\bar{\nu}}`
+     - :math:`xF_3^{\bar{\nu}}`
+     - :math:`\langle F_2^{\bar{\nu}} \rangle`
+     - :math:`\langle F_L^{\bar{\nu}} \rangle`
+     - :math:`\langle xF_3^{\bar{\nu}} \rangle`
+   * - LHAID
      - 1001
-   * - :math:`F_L^{\nu}`
      - 1002
-   * - :math:`xF_3^{\nu}`
      - 1003
-   * - :math:`F_2^{\bar{\nu}}`
      - 2001
-   * - :math:`F_L^{\bar{\nu}}`
      - 2002
-   * - :math:`xF_3^{\bar{\nu}}`
      - 2003
-   * - :math:`\langle F_2^{\bar{\nu}} \rangle`
      - 3001
-   * - :math:`\langle F_L^{\bar{\nu}} \rangle`
      - 3002
-   * - :math:`\langle xF_3^{\bar{\nu}} \rangle`
      - 3003
 
 
 The LHAPDF set can be generated using the following command:
 
 .. code-block:: bash
 
-   nnu fit dump_grids ${RUNCARD_NAME}/postfit -a ${A_VALUE} -o ${SET_NAME} [-q '{"min": 1e-3, "max": 400, "num": 100}]'
+   nnu fit dump_grids ${RUNCARD_NAME}/postfit -a ${A_VALUE} -o ${SET_NAME} [-q '{"min": 1e-3, "max": 500, "num": 100}]'
 
 .. note:: 
 

diff --git a/docs/source/tutorials/yadism.rst b/docs/source/tutorials/yadism.rst
@@ -2,7 +2,7 @@ Yadism predictions
 ==================
 
 Generating Yadism theory cards
------------------------
+------------------------------
 
 An alternative way to generate Yadism theory cards that will be used to
 generate theory predictions is to use the :mod:`nnusf.theory.runcards` module.