diff --git a/.github/workflows/upload_docs.yml b/.github/workflows/upload_docs.yml index fb643e5139..a46b62741d 100644 --- a/.github/workflows/upload_docs.yml +++ b/.github/workflows/upload_docs.yml @@ -18,7 +18,7 @@ jobs: shell: bash -l {0} run: | cd doc/sphinx - make html + make html SPHINXOPTS="-W --keep-going" - name: Upload documentation shell: bash -l {0} if: github.ref == 'refs/heads/master' diff --git a/doc/sphinx/source/ci/index.rst b/doc/sphinx/source/ci/index.rst index cf02456c80..68d3035517 100644 --- a/doc/sphinx/source/ci/index.rst +++ b/doc/sphinx/source/ci/index.rst @@ -6,7 +6,7 @@ Continuous integration and deployment The NNPDF code base makes use of externally hosted services, to aid development and testing. These are typically called *Continuous integration (CI)* or *Continuous deployment* services. Their main task is to execute automated tests -on the code and produce :ref:`binary builds ` which allow it to be +on the code and produce :ref:`binary builds ` which allow it to be automatically deployed. The tests automatically run upon ``git push`` to any branch in the GitHub server (see :ref:`git `). @@ -30,7 +30,7 @@ Our CI service works roughly as follows: - Compiling the code. - Running the tests. - - Possibly, uploading the compiled binaries and documentation to the :ref:`NNPDF server `. + - For release tags, uploading the documentation to the :ref:`NNPDF server `. We use `Conda-build `_ to do much of the heavy lifting for these actions. 3. The CI service reports whether it has *succeeded* or *failed* to the GitHub, server, which displays that information next to the relevant pull request or @@ -61,9 +61,6 @@ them, do something like:: The secrets are: - - ``NETRC_FILE`` a base64 encoded string containing a ``~/.netrc`` file with - the :ref:`credentials ` to the private conda repository - https://packages.nnpdf.science/conda-private/ - ``NNPDF_SSH_KEY`` a base64 string containing a private SSH key which is authorized to access the :ref:`upload account of the NNPDF server `. @@ -107,5 +104,5 @@ Our GitHub Action service implements: commit. Some logs are generated, which can aid in determining the cause of errors. 4. If the workflow succeeds, a comment to the initial pull request will appear with link references to the generated report and fit. -The progress reports of the various jobs at `GitHub Actions `_, upon logging in +The progress reports of the various jobs can be seen at the `NNPDF Github Actions `_, upon logging in with an authorized GitHub account. diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py index 1fba35b2fe..f482b47516 100644 --- a/doc/sphinx/source/conf.py +++ b/doc/sphinx/source/conf.py @@ -75,7 +75,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] +exclude_patterns = ['modules/**'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = None @@ -92,7 +92,7 @@ # further. For a list of options available for each theme, see the # documentation. # -html_theme_options = {"logo_only": True, "display_version": False} +html_theme_options = {"logo_only": True} # 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, diff --git a/doc/sphinx/source/contributing/python-tools.rst b/doc/sphinx/source/contributing/python-tools.rst index 5b749ceb32..785c7f6815 100644 --- a/doc/sphinx/source/contributing/python-tools.rst +++ b/doc/sphinx/source/contributing/python-tools.rst @@ -31,7 +31,7 @@ Python code can be evaluated interactively, which can speed up the development. environment running on the browser. Useful for bigger experiments. .. note:: - When developing :ref:`validphys ` related code interactively, be + When developing :ref:`validphys ` related code interactively, be sure to read about the :ref:`API functionality `. Testing @@ -153,7 +153,7 @@ Before beginning you will need to ensure that you have the tests dependencies, which can be checked in :code:`nnpdf/conda-recipe/meta.yml`. The next step is to write the test function. It is highly recommended to use the -:ref:`validphys API ` for this, both to simplify the code and to make it agnostic to the +:ref:`validphys API ` for this, both to simplify the code and to make it agnostic to the structure of backend providers - provided that they produce the same results. See for example a function which tests the ``plot_pdfs`` provider: diff --git a/doc/sphinx/source/data/intro.rst b/doc/sphinx/source/data/intro.rst index 7fdddc0a6f..473ef6569f 100644 --- a/doc/sphinx/source/data/intro.rst +++ b/doc/sphinx/source/data/intro.rst @@ -54,5 +54,5 @@ using these terms in this sense, they will be italicised for clarity. Dataset naming conventions -------------------------- -See :ref:`dataset_naming_convention` for a definition of how datasets should be +See :ref:`dataset-naming-convention` for a definition of how datasets should be named. diff --git a/doc/sphinx/source/external-code/pdf-codes.rst b/doc/sphinx/source/external-code/pdf-codes.rst index 2df016bc5d..5333aab74b 100644 --- a/doc/sphinx/source/external-code/pdf-codes.rst +++ b/doc/sphinx/source/external-code/pdf-codes.rst @@ -1,4 +1,4 @@ -.. _lhapdf: +.. _lhapdf-code: PDF set storage and interpolation ================================= @@ -23,7 +23,7 @@ alongside NNPDF, and so it therefore contains the features and settings required That is, it includes quark masses in the MSbar scheme, the various FONLL heavy quark schemes, scale variations up to NLO, etc. Note that at the time of writing, a more streamlined code is being written to replace APFEL, which is currently dubbed EKO ('Evolution Kernel Operator'). To find more -general information about PDF evolution and the DGLAP equations, you can go to the :ref:`Theory section `. +general information about PDF evolution and the DGLAP equations, you can go to the :ref:`Theory section `. PDF compression --------------- diff --git a/doc/sphinx/source/figuresofmerit/index.rst b/doc/sphinx/source/figuresofmerit/index.rst index 65905342ae..908db5e968 100644 --- a/doc/sphinx/source/figuresofmerit/index.rst +++ b/doc/sphinx/source/figuresofmerit/index.rst @@ -1,5 +1,5 @@ Chi square figures of merit -================================================================================ +=========================== Within the NNPDF methodology various figures of merit are used, each of which can be used in different situations. To avoid confusion, it is important to @@ -13,7 +13,7 @@ when each of them is used. The basis of the loss functions: 𝜒² --------------------------------------------------------------------------------- +----------------------------------- The :math:`\chi^2` figures of merit used in the NNPDF methodology are all based on the chi square statistic: @@ -73,7 +73,7 @@ set, which needs to be specified. Missing higher order uncertainties --------------------------------------------------------------------------------- +---------------------------------- Another source of uncertainties that we may want to include in the covariance matrix are theoretical uncertainties, particularly missing higher order uncertainties estimated through scale variations. These uncertainties can be @@ -84,7 +84,7 @@ covariance matrix'. A paper discussing the formalism can be found here: Future test: including PDF errors --------------------------------------------------------------------------------- +---------------------------------- To test the generalization power of the NNPDF fitting framework in the region where PDFs are not constrained by data, the 'future test' has been developed. The figure of merit considered in a future test is again the :math:`\chi^2`, @@ -101,7 +101,7 @@ For a more detailed discussion of the future test formalism see e.g. .. _covmat-reg: Regularized covariance matrices --------------------------------------------------------------------------------- +------------------------------- Information about the accuracy of the experimental uncertainty is generally not available, nevertheless inaccuracies in an experimental covariance matrix can lead to problems during optimization. Simply making a conservative estimate of @@ -130,7 +130,7 @@ within NNPDF can be found in sections 4.2 and 8.7 of the NNPDF4.0 paper The weighted fit method --------------------------------------------------------------------------------- +----------------------- To determine whether a specific dataset shows inconsistencies with the global dataset, one can produce a PDF determination in which that measurement is given an increased weight (usually equal to the combined weight of the other @@ -159,7 +159,7 @@ HERACOMB_SIGMARED_C dataset to 100 by adding the following to the runcard: Experimental, validation, and training 𝜒² --------------------------------------------------------------------------------- +----------------------------------------- When performing a PDF fit we generally distinguish three different definitions of the :math:`\chi^2` loss function, namely the experimental loss :math:`\chi^2_{\rm exp}`, the training loss :math:`\chi^2_{rm tr}` and the @@ -180,6 +180,7 @@ of the neural network can be found in the :ref:`methodology overview .. _lagrange-multipliers: + Positivity and integrability: Lagrange multipliers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Generally in an NNPDF fit we will want to ensure positivity and integrability of @@ -198,7 +199,7 @@ while the analogous information for integrability can be found Hyperoptimized figure of merit --------------------------------------------------------------------------------- +------------------------------ To test the generalization power of a given methodology (a specific set of hyperparameter values), we employ hyperoptimization, specifically we use K-folds cross-validation. The idea of K-folds cross-validation is to create diff --git a/doc/sphinx/source/get-started/installation.rst b/doc/sphinx/source/get-started/installation.rst index 07a756f428..570eb6f9ea 100644 --- a/doc/sphinx/source/get-started/installation.rst +++ b/doc/sphinx/source/get-started/installation.rst @@ -67,7 +67,7 @@ In the case of conda, it defaults to ``${CONDA_PREFIX}/share/NNPDF``. It is possible to configure where to download theory and results using a ``nnprofile`` file as described in :ref:`nnprofile`. - +.. _docker: Using the code with docker -------------------------- diff --git a/doc/sphinx/source/n3fit/methodology.rst b/doc/sphinx/source/n3fit/methodology.rst index 42b3c33f29..a4543c8cc8 100644 --- a/doc/sphinx/source/n3fit/methodology.rst +++ b/doc/sphinx/source/n3fit/methodology.rst @@ -127,8 +127,8 @@ provide a faster convergence to the solution. Parameters like the number of layers, nodes, activation functions are hyper-parameters that require tuning. -To see the structure of the model, one can use Keras's ``plot_model`` function as illustrated in the script below. -See the `Keras documentation `_ for more details. +To see the structure of the model, one can use Keras' ``plot_model`` function as illustrated in the script below. +See the `this section of the Keras documentation `_ for more details. .. code-block:: python @@ -206,10 +206,7 @@ Following the gradient descent approach the training is performed in iteration s descent update scheme (which controls the convergence step size and speed). The gradient descent schemes are usually controlled by the **learning rate**, and the total -**number of iterations**. Examples of fits using the ``n3fit`` methodology are available here: - -- DIS-only fit based on NNPDF3.1 NNLO setup: `view `_ -- Global fit based on NNPDF3.1 NNLO setup: `view `_ +**number of iterations**. .. important:: The gradient descent scheme (RMSprop, Adagrad, etc.), the learning rate, the number of iteractions are hyper-parameters that require tuning. diff --git a/doc/sphinx/source/releases.rst b/doc/sphinx/source/releases.rst index 1189bef0f0..34910b82f2 100644 --- a/doc/sphinx/source/releases.rst +++ b/doc/sphinx/source/releases.rst @@ -1,17 +1,19 @@ .. _releases: + Releases and compatibility policy ================================= Development occur in the tip of the `master branch `_ while we aim for this branch to be stable, tested and correct, this is not guaranteed. Premade packages are available for the latest tag -:ref:`generated automatically` and can be :ref:`readily installed`. +:ref:`generated automatically` and can be :ref:`readily installed `. See the compatibility policy below. The main results, such as NNPDF 4.0 :cite:p:`nnpdf40` will be produced with a frozen -:ref:`tag `, a :ref:`conda environment ` and a :ref:`docker image +:ref:`tag `, a :ref:`conda environment ` and a :ref:`docker image ` so that they can be reproduced entirely. .. _tags: + Tags ---- @@ -54,6 +56,7 @@ significant releases since the code was made public are: Used to produce the NNPDF 4.0 :cite:p:`nnpdf40` fits. .. _compatibility_policy: + Compatibility Policy -------------------- diff --git a/doc/sphinx/source/serverconf/index.rst b/doc/sphinx/source/serverconf/index.rst index e03df2cb0e..9f47664e49 100644 --- a/doc/sphinx/source/serverconf/index.rst +++ b/doc/sphinx/source/serverconf/index.rst @@ -8,7 +8,7 @@ meant for both public and internal consumption. It hosts the following URLs: - https://data.nnpdf.science: Hosts **public** NNPDF data such as PDF fits, releases etc. - - https://vp.nnpdf.science: Hosts the :ref:`validphys ` + - https://vp.nnpdf.science: Hosts the :ref:`validphys ` report and displays an index of all of the reports. - https://wiki.nnpdf.science: Hosts the github wiki version. - https://packages.nnpdf.science/: Hosts the ``conda`` binary packages. @@ -29,6 +29,7 @@ to the ``nnpdf@lxplus`` account at CERN. .. _server-access: + Access ------ @@ -39,35 +40,22 @@ The access to the server is provided by ``ssh``/:ref:`vp-upload ` with the following restrictions: - ``ssh`` access to ``root`` is forbidden. -- There is a shared ``nnpdf`` user with low privileges. In order to login -the user must send his public ssh key (usually in ``~/.ssh/id_rsa.pub``) to SC. -The ``nnpdf`` is not allowed to login with password. +- There is a shared ``nnpdf`` user with low privileges. In order to login the user must send his public ssh key (usually in ``~/.ssh/id_rsa.pub``) to JCM. This ``nnpdf`` user is not allowed to login with password. The ``nnpdf`` user shares a common ``/home/nnpdf`` folder where all NNPDF -material is stored. Public access to data is available for all files -in the ``/home/nnpdf/WEB`` folder. The ``validphys`` reports are stored in -``/home/nnpdf/validphys-reports`` and the wiki in -``/home/nnpdf/WEB/wiki``. - -Access for continuous deployment tools -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :ref:`conda packages` as well as the documentation are -automatically uploaded to the server by the Continous Integration service -(Travis), through an user called ``dummy`` which has further reduction in -privileges (it uses the ``rssh`` `shell `_ and it -is only allowed to run the ``scp`` command. An accepted private key is stored -securely in the :ref:`Travis configuration `. The packages -are uploaded to ``/home/nnpdf/packages``. +material is stored. Public access to data is available +in the ``/home/nnpdf/WEB`` folder and the ``validphys`` reports are stored in +``/home/nnpdf/validphys-reports``. + HTTP access ~~~~~~~~~~~ -Tools such as :ref:`conda ` and :ref:`vp-get` require access to +Tools such as the private :ref:`conda ` and :ref:`vp-get` require access to private URLs, which are password-protected, using HTTP basic_auth. The access is granted by a ``/.netrc`` file containing the user and password for the relevant servers. The ``/.netrc`` file is typically generated -at :ref:`installation` time. It should look similar to:: +at :ref:`installation ` time. It should look similar to:: machine vp.nnpdf.science login nnpdf @@ -157,9 +145,9 @@ Cron jobs The following cron jobs are registered for the ``nnpdf`` user: - every day at 4 AM run the ``index-email.py`` script. -- at every reboot run ``index-reports.py``, ``index-fits.py``, ``index-hyperscan.py``, ``index-packahes-public.sh`` - and ``index-packages-private.sh``, which monitor continuously the respective folders and create indexes that - can be used by various applications. The first two are homegrown scripts (see :ref:`Web Scripts `) +- at every reboot run ``index-reports.py``, ``index-fits.py``, ``index-hyperscan.py``, ``index-packahes-public.sh`` + and ``index-packages-private.sh``, which monitor continuously the respective folders and create indexes that + can be used by various applications. The first two are homegrown scripts (see :ref:`Web Scripts `) and the later two use `conda-index `_. @@ -170,6 +158,8 @@ The following cron jobs are registered for the ``root`` user: - reboot every Sunday at 6am (in order to use new kernels). - perform system update every day. +.. _web-server: + Web server Configuration ------------------------ diff --git a/doc/sphinx/source/theory/FastInterface.rst b/doc/sphinx/source/theory/FastInterface.rst index 19bf080fd0..11eb503a23 100644 --- a/doc/sphinx/source/theory/FastInterface.rst +++ b/doc/sphinx/source/theory/FastInterface.rst @@ -72,8 +72,8 @@ using the (interpolated) DGLAP evolution operators, \begin{equation} f_{i,\beta \tau} = \sum_j \sum_{\alpha} \Gamma^{\tau}_{ij,\alpha \beta}\,f_j(x_{\alpha},Q_0^2) \, , \end{equation} -so that the nuclear DIS structure function can be -evaluated as + +so that the nuclear DIS structure function can be evaluated as .. math:: diff --git a/doc/sphinx/source/theory/PTevol.rst b/doc/sphinx/source/theory/PTevol.rst index 03cd9433d7..9136bbee7c 100644 --- a/doc/sphinx/source/theory/PTevol.rst +++ b/doc/sphinx/source/theory/PTevol.rst @@ -687,7 +687,7 @@ N space solutions to the evolution equations (Ref. ) \binom{\Sigma}{g}(N,a_s) = \bigg[\mathbb{I}+\sum_{k=1}^{\infty}a_s^kU_k(N)\bigg] \mathbf{L}(a_s,a_0,N)\bigg[\mathbb{I}+\sum_{k=1}^{\infty}a_0^kU_k(N)\bigg]^{-1}\binom{\Sigma}{g}(N,a_0)\equiv \mathbf{\Gamma}_S(N,a_s,a_0)\binom{\Sigma}{g}(N,a_0) -- The *fully truncated*\ [1]_ expression of the matrix evolution +- The *fully truncated* expression of the matrix evolution kernel up to NNLO reads .. math:: @@ -761,20 +761,20 @@ N space solutions to the evolution equations (Ref. ) .. math:: - \Gamma_{NS,LO}^{\pm,v}(N,a_s,a_0)= (\frac{a_s}{a_0})^{-R_0^{ns}} + \Gamma_{\rm NS,LO}^{\pm,v}(N,a_s,a_0)= (\frac{a_s}{a_0})^{-R_0^{ns}} - Both iterated and truncated non-singlet solutions can be written down in a compact closed form at NLO as well. Iterated solution: .. math:: - \Gamma^{\pm,v}_{NS,NLO}(N,a_s,a_0) =\exp\bigg{\frac{U^{\pm,v}_1} {b_1}\ln(\frac{1+b_1a_s}{1+b_1 a_0})\bigg}(\frac{a_s}{a_0})^{-R_0^{ns}}. + \Gamma^{\pm,v}_{\rm NS,NLO}(N,a_s,a_0) =\exp\bigg(\frac{U^{\pm,v}_1} {b_1}\ln(\frac{1+b_1a_s}{1+b_1 a_0})\bigg)(\frac{a_s}{a_0})^{-R_0^{ns}}. - Truncated solution: -$$\label{ns-sol0} \\Gamma^{\pm,v}_{\rm NS,NLO} (N,a_s,a_0)\: = \\:\left( -1 - U_1^{\,\pm,v} (a_s - a_0) \\right) \\left( \\frac{a_s}{a_0} -\\right)^{-R_0^{\:\!\rm ns}}.$$ +.. math:: + + \Gamma^{\pm,v}_{\rm NS,NLO}(N,a_s,a_0) = \left(1 - U_1^{\,\pm,v} (a_s - a_0) \right) \left( \frac{a_s}{a_0}\right)^{-R_0^{\:\!\rm ns}}. Getting back the x-space PDF’s ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/sphinx/source/tutorials/closuretest.rst b/doc/sphinx/source/tutorials/closuretest.rst index e14639fe69..e5dbe8649d 100644 --- a/doc/sphinx/source/tutorials/closuretest.rst +++ b/doc/sphinx/source/tutorials/closuretest.rst @@ -1,6 +1,5 @@ .. _tut_closure: - How to run a closure test ========================= @@ -46,6 +45,7 @@ The main obvious disadvantage is that a pre-existing PDF may not be a suitable proxy for the underlying law. .. _prep_ct_runcard: + Preparing the closure test runcard ---------------------------------- diff --git a/doc/sphinx/source/tutorials/conda.rst b/doc/sphinx/source/tutorials/conda.rst index efe08cac2a..8dab7e4b6e 100644 --- a/doc/sphinx/source/tutorials/conda.rst +++ b/doc/sphinx/source/tutorials/conda.rst @@ -1,3 +1,5 @@ +.. _conda-packages: + How to build conda-packages --------------------------- diff --git a/doc/sphinx/source/tutorials/futuretests.rst b/doc/sphinx/source/tutorials/futuretests.rst index 0ba546588d..e28635c73c 100644 --- a/doc/sphinx/source/tutorials/futuretests.rst +++ b/doc/sphinx/source/tutorials/futuretests.rst @@ -1,4 +1,5 @@ .. _futuretests: + How to run a Future Test ======================== diff --git a/doc/sphinx/source/tutorials/general_th_covmat.rst b/doc/sphinx/source/tutorials/general_th_covmat.rst index b75dcf221d..17ab850858 100644 --- a/doc/sphinx/source/tutorials/general_th_covmat.rst +++ b/doc/sphinx/source/tutorials/general_th_covmat.rst @@ -58,10 +58,8 @@ generation). The default is ``True`` for both. Changing either of these to ``False`` will affect the fit outcome and should be avoided unless you know what you are doing. -1. Make sure that datasets are grouped under one big experiment called "BIGEXP", - just like in :ref:`vptheorycov-index`. - -2. For an example runcard, see `here `_ +When the theory covmat is active, all datasets are grouped toghether. +For an example runcard see `here `_. Including both scale variation uncertainties and user uncertainties @@ -69,4 +67,4 @@ Including both scale variation uncertainties and user uncertainties User uncertainties and scale variation uncertainties are included independently. By default neither are included. To include both see the separate tutorial on scale variation uncertainties and use the -union of the contributions in ``theorycovmatconfig``. For an example runcard see `here `_ +union of the contributions in ``theorycovmatconfig``. diff --git a/doc/sphinx/source/tutorials/hessian2mc.rst b/doc/sphinx/source/tutorials/hessian2mc.rst index 344bece3ab..30b103ae70 100644 --- a/doc/sphinx/source/tutorials/hessian2mc.rst +++ b/doc/sphinx/source/tutorials/hessian2mc.rst @@ -1,4 +1,5 @@ .. _hessian2mc: + How to transform a Hessian set into the corresponding Monte Carlo PDF ===================================================================== diff --git a/doc/sphinx/source/tutorials/list-resources.rst b/doc/sphinx/source/tutorials/list-resources.rst index ce7d4c81c1..703db4ba85 100644 --- a/doc/sphinx/source/tutorials/list-resources.rst +++ b/doc/sphinx/source/tutorials/list-resources.rst @@ -5,7 +5,7 @@ How to list the available resources Using ``vp-list`` ----------------- +----------------- In order to check what resources are available locally and for download, use ``vp-list`` which will print out the names of resources. diff --git a/doc/sphinx/source/tutorials/mc2hessian.rst b/doc/sphinx/source/tutorials/mc2hessian.rst index a889fc12b5..7017e8ca6a 100644 --- a/doc/sphinx/source/tutorials/mc2hessian.rst +++ b/doc/sphinx/source/tutorials/mc2hessian.rst @@ -1,4 +1,5 @@ .. _mc2hessian: + How to transform a Monte Carlo PDF set into a Hessian PDF set ============================================================= diff --git a/doc/sphinx/source/tutorials/pdfbases.rst b/doc/sphinx/source/tutorials/pdfbases.rst index 5da6f3aa08..a531d24ce4 100644 --- a/doc/sphinx/source/tutorials/pdfbases.rst +++ b/doc/sphinx/source/tutorials/pdfbases.rst @@ -1,4 +1,5 @@ .. _pdfbases: + Plotting non-trivial combinations of PDFs ========================================= @@ -16,6 +17,7 @@ We need to begin by assigning each parton a numerical index. This convention is laid out by the PDG as follows: .. _pdgflavs: + ========== =============== Index Parton ========== =============== diff --git a/doc/sphinx/source/tutorials/plot_pdfs.rst b/doc/sphinx/source/tutorials/plot_pdfs.rst index ae26b414ea..322acc6f13 100644 --- a/doc/sphinx/source/tutorials/plot_pdfs.rst +++ b/doc/sphinx/source/tutorials/plot_pdfs.rst @@ -6,7 +6,7 @@ How to plot PDFs, distances and luminosities Plotting any number of PDFs can be done using ``validphys``. There are several kinds of plots which can be made using the actions in the module ``pdfplots.py``. The runcards in this section can be found -`here `_. +`in this section of the NNPDF repository `_. Runcard basics -------------- @@ -239,6 +239,6 @@ Luminosity plots range of the plot, while ``mxmin`` and ``mxmax`` (in GeV) control the horizontal axis of invariant masses. - The option ``y_cut`` can be supplied to define a rapidity cut - (|y|<``y_cut``) on the integration range of 1D plots. + (:math:`|y|<` ``y_cut``) on the integration range of 1D plots. - Other options for the band plots, such as ``pdfs_noband`` and ``show_mc_errors`` work for ``plot_lumi1d``. diff --git a/doc/sphinx/source/tutorials/pseudodata.rst b/doc/sphinx/source/tutorials/pseudodata.rst index 9bfe25eab8..73b803867b 100644 --- a/doc/sphinx/source/tutorials/pseudodata.rst +++ b/doc/sphinx/source/tutorials/pseudodata.rst @@ -1,4 +1,5 @@ .. _pseudodata: + Obtaining the pseudodata used by an ``n3fit`` fit ================================================= diff --git a/doc/sphinx/source/tutorials/reportengine_parallel.rst b/doc/sphinx/source/tutorials/reportengine_parallel.rst index 975be07851..dcb3586a07 100644 --- a/doc/sphinx/source/tutorials/reportengine_parallel.rst +++ b/doc/sphinx/source/tutorials/reportengine_parallel.rst @@ -48,7 +48,7 @@ explicit examples of the use of memory for some standard validphys scripts. Example 1: PDF plots, ``validphys2/examples/plot_pdfs.yaml`` ----------------------------------------------------------- +------------------------------------------------------------ Suppose we have the following runcard diff --git a/doc/sphinx/source/tutorials/run-qed-fit.rst b/doc/sphinx/source/tutorials/run-qed-fit.rst index 161b0a3cf3..dcb900b969 100644 --- a/doc/sphinx/source/tutorials/run-qed-fit.rst +++ b/doc/sphinx/source/tutorials/run-qed-fit.rst @@ -230,6 +230,7 @@ Using ``vp-setupfit`` (preferred) locally, the user can proceed to run the fit with ``n3fit`` as usual. .. _photon_n3fit: + Using ``n3fit`` (discouraged) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the user prefers to compute the photon PDF set during the fitting step with diff --git a/doc/sphinx/source/tutorials/thcov_tutorial.rst b/doc/sphinx/source/tutorials/thcov_tutorial.rst index b6cc4c41f6..14fadf33b7 100644 --- a/doc/sphinx/source/tutorials/thcov_tutorial.rst +++ b/doc/sphinx/source/tutorials/thcov_tutorial.rst @@ -1,3 +1,5 @@ +:orphan: + .. _thcov_tutorial: How to include a theory covariance matrix in a fit @@ -46,6 +48,7 @@ Next, add necessary flags to the runcard where to use the theory covmat in the code. There are two possible places: the fitting (i.e. :math:`\chi^2` minimiser) and the sampling (i.e. pseudodata generation). The default is ``True`` for both. + .. warning:: Changing either of these to ``False`` will affect the fit outcome and should be avoided unless you know what you are doing. diff --git a/doc/sphinx/source/vp/complex_runcards.rst b/doc/sphinx/source/vp/complex_runcards.rst index ea39434f82..2622c7019e 100644 --- a/doc/sphinx/source/vp/complex_runcards.rst +++ b/doc/sphinx/source/vp/complex_runcards.rst @@ -447,10 +447,10 @@ the `fitcontext` rule. The above example can be simplified like this: Note that one still needs to set manually other keys like `description` and `pdfs`. -from_: Null ------------ +``from_: Null`` +--------------- -As a special case, `from_: Null` will retrieve the variable from the +As a special case, ``from_: Null`` will retrieve the variable from the current namespace. This comes handy to transform lists of items into other items. Consider for example: diff --git a/doc/sphinx/source/vp/customplots.rst b/doc/sphinx/source/vp/customplots.rst index d91a18fdb5..95537b6e1c 100644 --- a/doc/sphinx/source/vp/customplots.rst +++ b/doc/sphinx/source/vp/customplots.rst @@ -44,6 +44,7 @@ of the code, making runcards using it much more likely to work in the future. That others can benefit from the work is of course also a good thing. .. _extramodules: + Hooking ``validphys`` to external code -------------------------------------- @@ -70,24 +71,27 @@ There are two ways to take advantage of resources produced using the there is currently no way of adding production rules or parsers in this way. Prefer this for actions that are too difficult to upstream to ``validphys``, but should work as if they were internal. A minimal example - for an external module could be:: - # extra_plots.py + for an external module could be: + + .. code:: python + + # extra_plots.py - from matplotlib.figure import Figure - from reportengine.figure import figure + from matplotlib.figure import Figure + from reportengine.figure import figure - from nnpdf_data.commondataparser import load_commondata + from nnpdf_data.commondataparser import load_commondata - # A simple plot that probably should be in validphys to begin with. + # A simple plot that probably should be in validphys to begin with. - @figure - def plot_central_values(commondata): - fig = Figure() - ax = fig.subplots() - ax.plot(load_commondata(commondata).central_values) - return fig + @figure + def plot_central_values(commondata): + fig = Figure() + ax = fig.subplots() + ax.plot(load_commondata(commondata).central_values) + return fig - The action ``plot_central_values`` can now be used in a runcard: + The action ``plot_central_values`` can now be used in a runcard: .. code:: yaml diff --git a/doc/sphinx/source/vp/design.rst b/doc/sphinx/source/vp/design.rst index 0ea713d5bf..21f23828cd 100644 --- a/doc/sphinx/source/vp/design.rst +++ b/doc/sphinx/source/vp/design.rst @@ -1,4 +1,4 @@ - .. _design: +.. _design: The design of ``validphys 2`` ============================= diff --git a/doc/sphinx/source/vp/developer.rst b/doc/sphinx/source/vp/developer.rst index 10f50a932a..6cf38bcbd2 100644 --- a/doc/sphinx/source/vp/developer.rst +++ b/doc/sphinx/source/vp/developer.rst @@ -21,22 +21,27 @@ Key modules Some of the most important modules are - `validphys.core` + Core data structures that represent objects such as PDFs and data sets. - `validphys.loader` + Tools to obtain NNPDF resources locally or remotely. See :ref:`upload` and :ref:`download`. - `validphys.config` + Defines how resources are to be parsed from the configuration file. This is largely using `validphys.loader`. - `validphys.results` + Implements tools to store and manipulate results from data and theory predictions. - `validphys.gridvalues`, `validphys.bases`, `validphys.pdfgrids` + These contain tools to evaluate PDFs over grids of points. `validphys.gridvalues` contains low level functionality that might use `lhapdf`, `validphys.pdfbases` contain several different bases @@ -45,14 +50,17 @@ over PDF flavour space and functionality to manipulate them, and using for plotting and as an input to other computations. - `validphys.plotoptions` + Tools for interpreting the dataset PLOTTING files, including the transformations on the kinematics and the data. - `validphys.fitdata` + Contains parsers for various files produced by the fitting code along with tools to manipulate and display them. - `validphys.checks` + Contains `reportengine`-style checks that are used in several places. diff --git a/doc/sphinx/source/vp/download.rst b/doc/sphinx/source/vp/download.rst index 493c3d642c..05b010ad23 100644 --- a/doc/sphinx/source/vp/download.rst +++ b/doc/sphinx/source/vp/download.rst @@ -50,6 +50,7 @@ resource locally will result in an error and exiting the program. The ``--net`` flag makes the default behaviour explicit and has no effect otherwise. .. _what-can-be-downloaded: + What can be downloaded ---------------------- @@ -89,14 +90,14 @@ Hyperparameter scans Files produced by ``validphys`` can be used as input to subsequent validphys analyses (for example χ² tables are used for αs fits). The user needs to have HTTP access to the repository, which is provided when installing using - the :ref:`bootstrap script `. Output files are not specified by any + the :ref:`bootstrap script `. Output files are not specified by any top level config key, but instead actions can specify their own logic, for example for using an existing file instead of computing it. .. _vp-get: The ``vp-get`` tool ------------------ +------------------- The ``vp-get`` tool can be used to download resources manually, in the same way ``validphys`` would do. diff --git a/doc/sphinx/source/vp/filters.rst b/doc/sphinx/source/vp/filters.rst index 391f1ac773..ef1b45ab42 100644 --- a/doc/sphinx/source/vp/filters.rst +++ b/doc/sphinx/source/vp/filters.rst @@ -106,11 +106,11 @@ The kinematic variables that can be used within the rule depends on the process type. A full list of available parameters can be found by running: -.. code:: ipython +.. code:: pycon - In [1]: from NNPDF import CommonData + >>> from NNPDF import CommonData - In [2]: print(dict(CommonData.kinLabel)) + >>> print(dict(CommonData.kinLabel)) The user may additionally define their own variables by adding the ``local_variables`` field to their rule. For example, I can use ``w2`` @@ -307,7 +307,7 @@ append a list of filter rules to the rules obtained by the mechanisms described The value of ``added_filter_rules`` should be a list of rules with the same format as ``filter_rules``. -.. _drop_filter_rules:: +.. _drop_filter_rules: Dropping filter rules for selected datasets ------------------------------------------- @@ -370,16 +370,16 @@ be evaluated provided the ``theory`` perturbative order is **strictly** less than NNLO (i.e LO or NLO). I check what the process type of ``CMSDY2D12`` is: -.. code:: ipython +.. code:: pycon - In [1]: from validphys.loader import Loader + >>> from validphys.loader import Loader - In [2]: l = Loader() + >>> l = Loader() - In [3]: cd = l.check_commondata("CMSDY2D12") + >>> cd = l.check_commondata("CMSDY2D12") - In [4]: cd.process_type - Out[4]: 'EWK_RAP' + >>> cd.process_type + 'EWK_RAP' Then cross check this against ``NNPDF.CommonData.kinLabels`` to see that the relevant kinematic variables are: diff --git a/doc/sphinx/source/vp/index.rst b/doc/sphinx/source/vp/index.rst index 5d5eda67a4..bb90c16f75 100644 --- a/doc/sphinx/source/vp/index.rst +++ b/doc/sphinx/source/vp/index.rst @@ -1,4 +1,5 @@ .. _vp-index: + Code for data: validphys ======================== @@ -78,7 +79,7 @@ More detailed functionality .. toctree:: :maxdepth: 1 - ./design.md + ./design.rst ./namespaces.rst ./resolving_dependencies.rst ./collect.rst diff --git a/doc/sphinx/source/vp/nnprofile.rst b/doc/sphinx/source/vp/nnprofile.rst index e4242867be..fd03f078b8 100644 --- a/doc/sphinx/source/vp/nnprofile.rst +++ b/doc/sphinx/source/vp/nnprofile.rst @@ -1,7 +1,7 @@ .. _nnprofile: The ``nnprofile.yaml`` file -========================= +=========================== The NNPDF code stores some configuration options (mostly various URLs and paths) in a ``.yaml`` file which is installed alongside the code. @@ -11,7 +11,7 @@ This configuration is used by ``validphys`` to locate, :ref:`upload ` and :ref:`download ` resources. Altering profile settings --------------------------- +------------------------- It is possible to set up a custom profile file in: :: @@ -66,9 +66,8 @@ the code. These should be specified in YAML format. A list of URLs where to search completed fits from. ``fit_index`` - A filename that, when appended to each fit urls, points to an index with a - list of fits available from that location. You shouldn't change this as it - is configurable for historical reasons. + A filename that, when appended to each fit urls, points to an index with a list of fits available + from that location. It reflects the current location of the server. ``theory_urls`` A list of URLs pointing to theory repositories. diff --git a/doc/sphinx/source/vp/theorycov/examples.rst b/doc/sphinx/source/vp/theorycov/examples.rst index eea0111c10..f94980d7be 100644 --- a/doc/sphinx/source/vp/theorycov/examples.rst +++ b/doc/sphinx/source/vp/theorycov/examples.rst @@ -14,7 +14,7 @@ You need to provide the central theory under the ``default_theory`` flag, corresponding to :math:`(\mu_F, \mu_R) = (0,0)`, which for NLO is theory 163. You need to provide the required point prescription using the flag in -:ref:`this section `, e.g. ``point_prescription: "3 point"`` +:ref:`this section `, e.g. ``point_prescription: "3 point"`` in the case below. ``dataspecs`` associates a chosen label (``speclabel``) with each of the theory diff --git a/doc/sphinx/source/vp/upload.rst b/doc/sphinx/source/vp/upload.rst index 16f32c4ccd..61af96b9ac 100644 --- a/doc/sphinx/source/vp/upload.rst +++ b/doc/sphinx/source/vp/upload.rst @@ -1,7 +1,7 @@ .. _upload: Uploading results to the ``validphys`` repository -=============================================== +================================================= The primary method to share results within the collaboration is by uploading the corresponding files to the :ref:`NNPDF server `. Most commonly, results are @@ -10,14 +10,14 @@ uploaded to the ``validphys`` repository, so that they are accessible from `https://vp.nnpdf.science `_ The files in this repository are backed up to two locations, indexed and cross -referenced with the :ref:`mailing list `. The HTTP access to the files is +referenced with the mailing list. The HTTP access to the files is password protected. The uploading system is designed to be integrated with ``validphys``. Reports, hopefully filled with the :ref:`appropriate metadata ` in the runcard, can be :ref:`uploaded directly `, or after they have been completed using the ``vp-upload`` :ref:`script `. Arbitrary -files can be uploaded using the ``wiki-upload `` :ref:`script `, +files can be uploaded using the ``wiki-upload`` :ref:`script `, which will interactively ask the user to fill in the metadata. In either case an URL will be returned with the location of the resource accessible with a web browser. @@ -30,6 +30,7 @@ Several settings relevant to uploading files are configured in :ref:`profile files `. .. _vpmetadata: + Metadata -------- @@ -116,6 +117,7 @@ This is mostly useful for sub-reports not at the top level, in more complicated documents. .. _uploading-directly-from-validphys: + Uploading directly from ``validphys`` ------------------------------------- @@ -123,12 +125,13 @@ When the ``--upload`` flag is set in the invocation of the ``validphys`` command the contents of the output folder will be uploaded to the NNPDF data server, after validphys is done. Use this if you have :ref:`filled the meta mapping in the runcard ` and already know that the output is going to be good enough -to share. Otherwise use :ref:`vp-upload ` after checking the result. +to share. Otherwise use :ref:`vp-upload ` after checking the result. ``validphys`` will check the SSH connection before doing any work, and it will fail early if it cannot be established. .. _vpupload: + The ``vp-upload`` script ------------------------ @@ -158,6 +161,7 @@ Note that fits are indexed separately, and can be retrieved with the ``vp-get`` :ref:`command `. .. _the-wiki-upload-script: + The ``wiki-upload`` script -------------------------- diff --git a/n3fit/src/evolven3fit/evolve.py b/n3fit/src/evolven3fit/evolve.py index 70c752adcf..5f2b54ba3a 100644 --- a/n3fit/src/evolven3fit/evolve.py +++ b/n3fit/src/evolven3fit/evolve.py @@ -58,7 +58,7 @@ class ExportGrid: A list of the flavours contained in each element of the pdfgrid, by label. Not necessary if pids is given. replica: int - Index of the corresponding monte carlo replica or member + Index of the corresponding monte carlo replica or member. """ q20: float @@ -91,10 +91,13 @@ def pdfvalues(self): def evolve_exportgrid(eko_path: pathlib.Path, exportgrids: list[ExportGrid]): - """Takes the path to an EKO and a list of exportgrids, + """ + Takes the path to an EKO and a list of exportgrids, returns a tuple with an info file and the evolved exportgrid as a dictionary of the form: + .. code-block:: python + { (Q_1^2, nf1): (replica, flavours, x), (Q_2^2, nf1): (replica, flavours, x), @@ -102,24 +105,24 @@ def evolve_exportgrid(eko_path: pathlib.Path, exportgrids: list[ExportGrid]): (Q_3^2, nf2): (replica, flavours, x), } - with the output grouped by nf and sorted in ascending order by Q2 + + with the output grouped by nf and sorted in ascending order by Q2. Parameters ---------- - eko_path: pathlib.Path - Path to the evolution eko - exportgrids: list[ExportGrid] - List of ExportGrid objects to be evolved + eko_path: pathlib.Path + Path to the evolution eko + exportgrids: list[ExportGrid] + List of ExportGrid objects to be evolved Returns ------- - info_file: eko_box.info_file - dict-like object with the info file information - - evolved_replicas: dict - a dictionary containing all evolved PDF. - The format of the output is - { (q2, flavour number): np.ndarray(replica, flavours, x) } + info_file: eko_box.info_file + Dict-like object with the info file information. + evolved_replicas: dict + a dictionary containing all evolved PDFs. + The format of the output is + { (q2, flavour number): np.ndarray(replica, flavours, x) } """ # Check that all exportgrid objects have been evaluated for 1) The same value of Q, the same value of x ref = exportgrids[0] diff --git a/n3fit/src/n3fit/model_trainer.py b/n3fit/src/n3fit/model_trainer.py index 287b0e8348..28ca25e8c5 100644 --- a/n3fit/src/n3fit/model_trainer.py +++ b/n3fit/src/n3fit/model_trainer.py @@ -11,8 +11,8 @@ from collections import namedtuple from itertools import zip_longest -import logging import json +import logging import numpy as np @@ -84,15 +84,14 @@ class ModelTrainer: Wrapper around the fitting code and the generation of the Neural Network - When the "hyperparametrizable"* function is called with a dictionary of parameters, + The ``hyperparametrizable`` method accepts a dictionary of hyper-parameters + which defines the Neural Network. + When it is called with a dictionary of parameters, it generates a NN and subsequentially performs a fit. The motivation behind this class is minimising the amount of redundant calls of each hyperopt run, in particular this allows to completely reset the NN at the beginning of each iteration reusing some of the previous work. - - *called in this way because it accept a dictionary of hyper-parameters - which defines the Neural Network """ def __init__( @@ -172,7 +171,7 @@ def __init__( self.lux_params = lux_params self.replicas = replicas self.experiments_data = experiments_data - self.trials=trials + self.trials = trials # Initialise internal variables which define behaviour if debug: @@ -851,6 +850,7 @@ def hyperparametrizable(self, params): Parameters used only here: - ``epochs``: maximum number of iterations for the fit to run - ``stopping_patience``: patience of the stopper after finding a new minimum + All other parameters are passed to the corresponding functions """ @@ -875,7 +875,6 @@ def hyperparametrizable(self, params): stopping_patience = self.trials["stopping_patience"][idx_hyperparamters] stopping_epochs = int(epochs * stopping_patience) - # Fill the 3 dictionaries (training, validation, experimental) with the layers and losses # when k-folding, these are the same for all folds positivity_dict = params.get("positivity", {}) @@ -936,7 +935,9 @@ def hyperparametrizable(self, params): # read hyperparameter values from hyperopt results for rep, seed in zip(self.replicas, self._nn_seeds): idx_hyperparamters = rep % self.trials["number_of_trials"] - activations = [self.trials["activation_per_layer"][idx_hyperparamters]] * (len(self.trials["nodes_per_layer"][idx_hyperparamters])-1) + activations = [self.trials["activation_per_layer"][idx_hyperparamters]] * ( + len(self.trials["nodes_per_layer"][idx_hyperparamters]) - 1 + ) # last layer activation is always linear activations.append('linear') @@ -1019,7 +1020,7 @@ def hyperparametrizable(self, params): threshold_positivity=threshold_pos, threshold_chi2=threshold_chi2, ) - + if self.mode_hyperopt or (not self.trials): optimizer_params = params["optimizer"] else: @@ -1028,8 +1029,8 @@ def hyperparametrizable(self, params): optimizer_params["clipnorm"] = self.trials['clipnorm'][idx_hyperparamters] optimizer_params["learning_rate"] = self.trials['learning_rate'][idx_hyperparamters] optimizer_params["optimizer_name"] = self.trials['optimizer'][idx_hyperparamters] - - # Compile each of the training/validation models with the same optimization parameters + + # Compile each of the training/validation models with the same optimization parameters for model in models.values(): model.compile(**optimizer_params) self._train_and_fit(models["training"], stopping_object, epochs=epochs) diff --git a/n3fit/src/n3fit/msr.py b/n3fit/src/n3fit/msr.py index 721eb6b38d..31e7484573 100644 --- a/n3fit/src/n3fit/msr.py +++ b/n3fit/src/n3fit/msr.py @@ -31,9 +31,11 @@ def generate_msr_model_and_grid( Number of flavours of the output PDF mode: str Mode of sum rules to apply. It can be: + - "ALL": applies both the momentum and valence sum rules - "MSR": applies only the momentum sum rule - "VSR": applies only the valence sum rule + nx: int Number of points of the integration grid scaler: Scaler @@ -44,13 +46,17 @@ def generate_msr_model_and_grid( model: MetaModel Model that applies the sum rules to the PDF It takes as inputs: + - pdf_x: the PDF output of the model - pdf_xgrid_integration: the PDF output of the model evaluated at the integration grid - xgrid_integration: the integration grid - photon_integral: the integrated photon contribution + It returns the PDF with the sum rules applied + xgrid_integration: dict Dictionary with the integration grid, with: + - values: the integration grid - input: the input layer of the integration grid """ diff --git a/validphys2/src/validphys/lhapdf_compatibility.py b/validphys2/src/validphys/lhapdf_compatibility.py index 83cc6fbd88..33c355a71e 100644 --- a/validphys2/src/validphys/lhapdf_compatibility.py +++ b/validphys2/src/validphys/lhapdf_compatibility.py @@ -105,14 +105,14 @@ def make_pdf(pdf_name, member=None): for lhapdf functions for the selected backend Parameters: - ---------- + ----------- pdf_name: str name of the PDF to load member: int index of the member of the PDF to load Returns: - ------- + -------- list(pdf_sets) """ if USING_LHAPDF: diff --git a/validphys2/src/validphys/pdfbases.py b/validphys2/src/validphys/pdfbases.py index c2364676b9..3d67025383 100644 --- a/validphys2/src/validphys/pdfbases.py +++ b/validphys2/src/validphys/pdfbases.py @@ -152,7 +152,7 @@ class UnknownElement(KeyError): class Basis(abc.ABC): """A Basis maps a set of PDF flavours (typically as given by - :ref:`LHAPDF `) to functions thereof. This abstract class provides + :ref:`LHAPDF `) to functions thereof. This abstract class provides functionalities to manage labels (used for plotting) and defaults, while the concrete implementation of the transformations is handled by the subclasses (by implementing the