Merge pull request #26 from N3PDF/docs1

Documentation - first batch

.github/workflows/unittests.yml

@@ -1,7 +1,9 @@
 name: yadism - unit tests
 
 on:
-  - push
+  push:
+    branches-ignore:
+      - '*docs*'
 
 defaults:
   run:

docs/notes/apfel/TMC.md

@@ -0,0 +1,66 @@
+# TMC
+How APFEL computes target mass corrections
+
+## Variable definition
+Source: `F2light.f` and similar
+
+As in the docs pdf (`dis.pdf`)  aux variables are defined (`xi`, `rho` that is
+called `rhop` in the code) directly in `F2light.f`
+
+## Integration
+Source: `ConvolutePDFwithDISOperators.f` for `I2`
+Source: `ComputeDISOperators.f` for `OpI2`
+
+The integration is already provided, since it is precomputed on a grid. The
+matrix of coefficients it's called `I2(ihq,g,alpha)` where:
+- `ihq` is the flavour number (so 3 for light, 4 for charm and so on)
+- `g` is the subgrid number (since APFEL is breaking the global grid currently
+    we don't know why), 0 means the joint (total) grid
+- `alpha` is the replacement for `xi` value, i.e. it is its discretization over
+    the grid
+
+Two kinds of `I2` are provided:
+- `I2` as described above, used when pdf are already applied
+- `OpI2`, that is the correspondent of `OpF2`, in which instead of a number it
+    provides an array to be dotted with the pdf once available (so it has one
+    index more w.r.t. the former, since it is waiting for the pdf array)
+
+Since `OpI2` has one interpolation index more it has also another index on a
+subgrid (in order to identify the interpolation two index are used, one to get
+the subgrid and the other internal to the subgrid), so the signature it is
+`OpI2(jgrid,ihq,ipdf,alpha,beta)`:
+- `jgrid` and `alpha` are the subgrid and internal index for `xi` interpolant
+- `ipdf` and `beta` are the subgrid and internal index for pdf interpolant
+- `ihq` flavour index, as before
+
+### Integration
+Source: `RSLintegralsDIS.f` for `J_TMC`
+Source: `Evolution/interpolants.f` for `w_int`
+
+The actual integral of `I2` it's performed not on `F2(x)/x^2`, but on the basis
+functions (as documented in `dis.pdf` eq. 2.5), and the result of integration of
+basis functions is provided as another matrix `J_TMC(igrid,beta,alpha)`:
+- `igrid` and `alpha` are the subgrid and internal index for `xi` interpolant
+- `beta` is the index on which the sum is performed (the discrete replacement of
+    `F2` integration)
+
+`J_TMC` it's defined integrating (it uses `dgauss`) the `w_int(k,beta,x)`
+polynomials:
+- `k` is the interpolation degree
+- `beta` is the interpolant index
+- `x` is the argument of the polynomial function
+
+For integrating `J_TMC` polynomials of degree 1 are used.
+
+#### About integration routine
+Note that `J_TMC` is computed through `dgauss` function of `cernlib` (see
+http://hep.fi.infn.it/cernlib.pdf pp.94-95), which signature is
+`dgauss(integrand,a,b,eps)`
+- `integrand` is the integrand
+- `a` and `b` are extremes of integration
+- `eps` is the required precision (relative is the integration `|I|>1`, otherwise
+    absolute)
+Since the integrand in APFEL are interpolants of degree 1 they are always
+smaller than 1, and with a domain smaller than `[0,1]`, so we have for sure
+`|I|<1`. Since APFEL is also requiring an `eps = 1e-5` the *absolute*
+integration error of APFEL it's probably of that order of magnitude.

docs/sphinx/Makefile

@@ -14,8 +14,9 @@ help:
 .PHONY: help html view clean cleanall
 
 html:
-	sphinx-apidoc -o ./source/modules/yadism ../../src/yadism/
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	sphinx-apidoc -o ./source/modules --module-first ../../src/yadism/
+	@rm -f ./source/modules/modules.rst ./source/modules/*/modules.rst}
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 view: html
 	$(BROWSER) $(BUILDDIR)/html/index.html

docs/sphinx/source/_templates/footer.html

@@ -0,0 +1,15 @@
+{% extends '!footer.html' %}
+
+{% block extrafooter %}
+  <!-- your html code here -->
+  <p style="text-align: center;">Made with ❤  and ⏲  by N3PDF team.</p>
+
+  {%- if hasdoc('copyright') %}
+    {% set path = pathto('copyright') %}
+    {% set copyright = copyright|e %}
+    <p style="text-align: center; font-size: 7pt;">&copy; <a href="{{ path }}">{% trans %}Copyright{% endtrans %}</a> {{ copyright }}</p>
+  {%- else %}
+    {% set copyright = copyright|e %}
+    <p style="text-align: center; font-size: 7pt;">&copy; {% trans %}Copyright{% endtrans %} {{ copyright }}</p>
+  {%- endif %}
+{% endblock %}

docs/sphinx/source/conf.py

@@ -12,8 +12,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
 # import sys
+# import os
+# import pathlib
 # sys.path.insert(0, os.path.abspath('.'))
 
 from recommonmark.transform import AutoStructify
@@ -54,6 +55,7 @@
     "sphinx.ext.autosectionlabel",
     "recommonmark",
     "sphinx.ext.napoleon",
+    "sphinx.ext.graphviz",
     "sphinxcontrib.bibtex",
 ]
 
@@ -88,11 +90,14 @@
 # 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 = ["shared/*"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+# A string to be included at the beginning of all files
+shared = pathlib.Path(__file__).absolute().parent / "shared"
+rst_prolog = "\n".join([open(x).read() for x in os.scandir(shared)])
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -105,7 +110,29 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    # "canonical_url": "",
+    # "analytics_id": "UA-XXXXXXX-1",  #  Provided by Google in your dashboard
+    # "logo_only": False,
+    "display_version": True,
+    # "prev_next_buttons_location": "bottom",
+    # "style_external_links": False,
+    # "vcs_pageview_mode": "",
+    # "style_nav_header_background": "white",
+    # # Toc options
+    # "collapse_navigation": True,
+    # "sticky_navigation": True,
+    # "navigation_depth": 4,
+    # "includehidden": True,
+    # "titles_only": False,
+}
+
+# set variables for template system
+html_context = {
+    # # footer:
+    "show_copyright": False,
+    "show_sphinx": False,
+}
 
 # 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,
@@ -122,6 +149,19 @@
 #
 # html_sidebars = {}
 
+# -- Options for HTML output -------------------------------------------------
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = True
+napoleon_use_param = True
+napoleon_use_rtype = True
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -207,6 +247,19 @@
 
 # -- Extension configuration -------------------------------------------------
 
+# -- Options for autodc extension --------------------------------------------
+autodoc_default_options = {
+    # "members": "var1, var2",
+    # "member-order": "bysource",
+    "special-members": True,
+    # "inherited-members": True,
+    # "undoc-members": True,
+    "exclude-members": "__weakref__, __init__, __dict__, __module__"
+    ", __abstractmethods__",
+}
+
+autoclass_content = "class"
+
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
@@ -217,6 +270,11 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+# -- Options for edit on github extension ------------------------------------
+# https://gist.github.com/mgedmin/6052926
+# edit_on_github_project = 'username/reponame'
+# edit_on_github_branch = 'master'
+
 # Adapted this from
 # https://github.com/readthedocs/recommonmark/blob/ddd56e7717e9745f11300059e4268e204138a6b1/docs/conf.py
 # app setup hook

docs/sphinx/source/dev.rst

@@ -0,0 +1,40 @@
+Development
+===========
+
+Feature to be implemented
+-------------------------
+Known list of features to be implemented
+
+
+Known bugs
+----------
+like behaviour Q2 APFEl & blabla
+
+Testing
+-------
+Description of testing workflows.
+
+Unit testing
+""""""""""""
+Where are used unit tests and other interesting facts related to them.
+
+List and description of unit tests (currently only ``convolution`` related
+stuffs).
+
+APFEL benchmarks
+""""""""""""""""
+Organization (db and so on), matrix (all the alternatives tested) and other
+benchmark related stuffs description.
+
+How to use benchmark tools
+''''''''''''''''''''''''''
+Description of script ecosystem for running benchmarks and further analyzing
+their output (logs).
+
+Other stuffs
+------------
+
+.. toctree::
+   :maxdepth: 1
+
+   todo

docs/sphinx/source/docutils.conf

@@ -0,0 +1,4 @@
+# conf for docutils
+
+[restructuredtext parser]
+#syntax_highlight = short

docs/sphinx/source/index.rst

@@ -1,22 +1,56 @@
 .. DIS documentation master file.
 
+
+#################
 DIS documentation
-===================
+#################
+
+.. the following transition is only used for highlight the main title
+
+---------
+
+`yadism` is a wonderful package for computing |DIS| observables replacing the
+corresponding one inside |APFEL|.
 
 .. toctree::
-    :maxdepth: 4
+   :maxdepth: 1
+   :caption: Package Reference
+
+   yadism.rst
+   dev.rst
+   interpolation.rst
+
+   zzz-refs.rst
 
-    Physics
+In these :underlined:`documents` you can find the reference for all *yadism* API and internals.
+
+
+Features
+~~~~~~~~
+Current features:
+
+* |LO| structure functions (|NC|)
+* |NLO| structure functions (|NC|)
+* |NLO| scale variations
 
-.. automodule:: yadism
-    :members:
-    :noindex:
 
 .. toctree::
-  :maxdepth: 4
-  :caption: Dev:
+   :maxdepth: 1
+   :caption: Theory
+
+   theory/LO.rst
+   theory/NLO.rst
+   theory/NNLO.rst
+   theory/N3LO.rst
+   theory/heavy-flavors.rst
+   theory/scale-variations.rst
+
+And here there is some *physics documentation*.
+
+Some of these are trivial and will be replaced, they are here just to create a
+structure.
 
-  todo.rst
+---------
 
 
 Indices and tables

docs/sphinx/source/interpolation.rst

@@ -0,0 +1,36 @@
+Interpolation
+=============
+
+Interpolation kicks in the game in a lot of ways, namely 3:
+- there is an interpolation involved at the **pdf level**, that is really the only
+  one `yadism` cares about, and is managed through `eko`: pdfs are delivered as
+  an array of coefficient over an interpolation basis made of polynomials (of
+  `x` or `logx`, chosen as an option)
+- there is an interpolation involved at the **structure functions level**: this
+  is done by `APFEL` since it's precomputing the structure functions on the
+  xgrid at initialization time, and when asked for a specific observable it
+  interpolates it on the precomputed grid
+  this is not done in `yadism` since we are computing the structure functions
+  only when required, so we are computing exactly on that point and there is no
+  need to interpolate it
+  *note*: we can also do this quite easily, if required or for benchmarking,
+  since the caching system makes it easier to switch on *precomputing model*,
+  because if we setup the interpolation the precomputed grid is already stored,
+  even if as a cache
+  *note2*: everything in `APFEL` is discretized, so not only the structure
+  functions themselves, but also everything that is integrated or the result of
+  an integral (such as `I2` in `TMC`, see 2.5 in dis pdf in `apfel` docs, there
+  is already a basis function involved to discretized the integrand, but also
+  the result will be discretized on `xi` inserting other basis functions, as it
+  is done in `F2light.f` for example)
+- there is a second *really bad* interpolation involved at the *level of the
+  pdf* (at least in benchmarking), that is the `lhapdf` one: in order to get
+  the pdf to interpolate we are using `lhapdf` grids. So `eko`, e.g., it's
+  making pdf interpolation over our `xgrid`, but when evaluating the `pdf` on
+  our `xgrid` you should take care that this is already interpolated, since our
+  `xgrid` may not match the `lhapdf` one.
+  This is done in both `yadism` and `APFEL`, so it's not a source of
+  discrepancy, but it's make it approximate w.r.t. to the exact shape (for
+  example when we are generating the `lhapdf` grids with a known function)
+  *note*: this is not happening in `toyLH`, since we are not passing through
+  `lhapdf` in that case, but mimic it

docs/sphinx/source/refs.bib

@@ -1,4 +1,4 @@
-@article{Vermaseren:2005qc,
+@article{vogt,
       author         = "Vermaseren, J. A. M. and Vogt, A. and Moch, S.",
       title          = "{The Third-order QCD corrections to deep-inelastic
                         scattering by photon exchange}",
@@ -14,6 +14,14 @@ @article{Vermaseren:2005qc
                         SFB-CPP-05-13",
       SLACcitation   = "%%CITATION = HEP-PH/0504242;%%"
 }
+@misc{fh-thesis,
+    title            = {Next-to-Leading Order QCD Corrections to Heavy-Flavour Production in Neutral Current DIS},
+    author           = {Felix Hekhorn},
+    year             = {2019},
+    eprint           = {1910.01536},
+    archivePrefix    = {arXiv},
+    primaryClass     = {hep-ph}
+}
 @article{Schienbein:2007gr,
     author = "Schienbein, Ingo and others",
     archivePrefix = "arXiv",