Improve IO docs and add other minor fixes

.pre-commit-config.yaml

@@ -14,12 +14,12 @@ repos:
       - id: check-merge-conflict
       - id: debug-statements
   - repo: https://github.com/hadialqattan/pycln
-    rev: v2.4.0
+    rev: v2.5.0
     hooks:
       - id: pycln
         args: [--config=pyproject.toml]
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.6
+    rev: v0.9.0
     hooks:
       # Run the linter.
       - id: ruff

doc/source/code/IO.rst

@@ -5,36 +5,25 @@ Input
 -----
 
 The input is split into two runcards: a **theory runcard** and an **operator runcard**.
-Note that we are not assuming any default values for the keywords, but instead the user has to provide
+Note that we are not assuming any default values for the fields, but instead the user has to provide
 the full definition.
 
 The theory card defines the general setup of the calculation, such as used perturbative orders or heavy quark masses.
 Please see :class:`~eko.io.runcards.TheoryCard` for the actual format.
 
-.. Operator Runcard
-.. ^^^^^^^^^^^^^^^^
+The observable card defines the specific setup of the EKOs, such as the target scales or the interpolation grid.
+Please see :class:`~eko.io.runcards.OperatorCard` for the actual format.
 
-.. .. autoclass:: eko.io.runcards::OperatorCard
-..    :members:
-..    :no-index:
+The runcard objects are independent objects, but they can be parsed from a :py:obj:`dict` and, as usual, a :py:obj:`dict`
+can be described, e.g., by a `yaml <https://github.com/yaml/pyyaml>`_ file.
 
 Output
 ------
 
+We output tar-compressed folder, which contains the used settings and the actual |EKO|.
+To access the file you should use the interface provided by the :class:`~eko.io.struct.EKO` class and
+you can follow :doc:`the tutorial </overview/tutorials/output>` to see how.
 
-Since the final |EKO| is a rank 4-tensor we store in the output all the different grids
-for each dimension:``targetpids,targetgrid,inputpids,inputgrid``.
-The ``Q2grid`` values are the actual tensor for the requested :math:`Q^2`. Each of them contains two keys:
-
-- ``operators`` a :py:obj:`dict` with all evolution kernel operators where the key indicates which distribution is generated by which other one
-  and the value represents the eko in matrix representation - this can either be the plain list representation or the binary representation
-  (as provided by :py:meth:`numpy.ndarray.tobytes`)
-- ``errors`` a :py:obj:`dict` with the integration errors associated to the respective operators following the same conventions as
-  the ``operator`` dictionary
-
-Each element (|EKO|) is a rank-4 tensor with the indices ordered in the following way: ``EKO[pid_out][x_out][pid_in][x_in]`` where ``pid_out`` and ``x_out``
-refer to the outgoing |PDF| and ``pid_in`` and ``x_in`` to the incoming |PDF|. The ordering of ``pid_out/pid_in`` is determined by the ``targetpids/inputpids``
-parameter of the output and the order of ``x_out/x_in`` by ``targetgrid/inputgrid``.
-
-To further explore how an :class:`~eko.output.Output` object looks like
-you can follow :doc:`this tutorial </overview/tutorials/output>`.
+Each |EKO| is a rank-4 tensor with the indices ordered in the following way: ``EKO[pid_out][x_out][pid_in][x_in]``
+where ``pid_out`` and ``x_out`` refer to the |PID| and the grid point
+of the outgoing |PDF| and ``pid_in`` and ``x_in`` to the incoming |PDF|.

doc/source/conf.py

@@ -24,7 +24,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "EKO"
-copyright = "2019-2024, the NNPDF team"  # pylint: disable=redefined-builtin
+copyright = "2019-2025, the NNPDF team"  # pylint: disable=redefined-builtin
 author = "NNPDF team"
 
 # The short X.Y version

doc/source/refs.bib

@@ -1051,13 +1051,16 @@ @article{Moch:2023tdj
 
 @article{Falcioni:2024qpd,
     author = "Falcioni, G. and Herzog, F. and Moch, S. and Pelloni, A. and Vogt, A.",
-    title = "{Four-loop splitting functions in QCD -- The gluon-gluon case --}",
+    title = "{Four-loop splitting functions in QCD \textendash{} the gluon-gluon case \textendash{}}",
     eprint = "2410.08089",
     archivePrefix = "arXiv",
     primaryClass = "hep-ph",
     reportNumber = "ZU-TH 47/24, DESY-24-144, LTH 1384",
-    month = "10",
-    year = "2024"
+    doi = "10.1016/j.physletb.2024.139194",
+    journal = "Phys. Lett. B",
+    volume = "860",
+    pages = "139194",
+    year = "2025"
 }
 
 @article{Ablinger:2024xtt,
@@ -1076,11 +1079,14 @@ @article{Ablinger:2024xtt
 
 @article{Falcioni:2024xyt,
     author = "Falcioni, G. and Herzog, F. and Moch, S. and Pelloni, A. and Vogt, A.",
-    title = "{Four-loop splitting functions in QCD -- The quark-to-gluon case}",
+    title = "{Four-loop splitting functions in QCD \textendash{} The quark-to-gluon case}",
     eprint = "2404.09701",
     archivePrefix = "arXiv",
     primaryClass = "hep-ph",
     reportNumber = "ZU-TH 20/24, DESY-24-053, LTH 1367",
-    month = "4",
+    doi = "10.1016/j.physletb.2024.138906",
+    journal = "Phys. Lett. B",
+    volume = "856",
+    pages = "138906",
     year = "2024"
 }