KIT-CMS · harrypuuter · Sep 8, 2023 · Sep 7, 2023 · Sep 7, 2023 · Sep 7, 2023
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -62,6 +62,13 @@ add_custom_target(Doxygen ALL
                    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
                    COMMENT "Generate doxygen index")
 
+# now run the update_namespace_docs.py script to add any missing namespace docs
+add_custom_command(TARGET Doxygen POST_BUILD
+                    COMMAND ${Python_EXECUTABLE} ${PROJECT_SOURCE_DIR}/update_namespace_docs.py --input ${PROJECT_BINARY_DIR} --output ${PROJECT_SOURCE_DIR}/sphinx_source/c_namespaces/
+                   COMMENT "Updating namespace docs")
+if(ret EQUAL "1")
+    message( FATAL_ERROR "Namespace documentation update failed.")
+endif()
 # Generate sphinx docs from doxygen xml
 set(SPHINX_SOURCE ${PROJECT_SOURCE_DIR}/sphinx_source/)
 set(SPHINX_OUTPUT_DIR ${PROJECT_BINARY_DIR}/docs)

diff --git a/docs/images/root_friends.png b/docs/images/root_friends.png
diff --git a/docs/sphinx_source/c_functions.rst b/docs/sphinx_source/c_functions.rst
diff --git a/docs/sphinx_source/c_namespaces/basefunctions.rst b/docs/sphinx_source/c_namespaces/basefunctions.rst
@@ -0,0 +1,6 @@
+Namespace: Basefunctions
+========================
+.. doxygennamespace:: basefunctions
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/ditau_pairselection.rst b/docs/sphinx_source/c_namespaces/ditau_pairselection.rst
@@ -0,0 +1,6 @@
+Namespace: Ditau_pairselection
+==============================
+.. doxygennamespace:: ditau_pairselection
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/fakefactors.rst b/docs/sphinx_source/c_namespaces/fakefactors.rst
@@ -0,0 +1,6 @@
+Namespace: Fakefactors
+======================
+.. doxygennamespace:: fakefactors
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/genmatching.rst b/docs/sphinx_source/c_namespaces/genmatching.rst
@@ -0,0 +1,6 @@
+Namespace: Genmatching
+======================
+.. doxygennamespace:: genmatching
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/htxs.rst b/docs/sphinx_source/c_namespaces/htxs.rst
@@ -0,0 +1,6 @@
+Namespace: Htxs
+===============
+.. doxygennamespace:: htxs
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/jet.rst b/docs/sphinx_source/c_namespaces/jet.rst
@@ -0,0 +1,6 @@
+Namespace: Jet
+==============
+.. doxygennamespace:: jet
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/lorentzvectors.rst b/docs/sphinx_source/c_namespaces/lorentzvectors.rst
@@ -0,0 +1,6 @@
+Namespace: Lorentzvectors
+=========================
+.. doxygennamespace:: lorentzvectors
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/met.rst b/docs/sphinx_source/c_namespaces/met.rst
@@ -0,0 +1,6 @@
+Namespace: Met
+==============
+.. doxygennamespace:: met
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/metfilter.rst b/docs/sphinx_source/c_namespaces/metfilter.rst
@@ -0,0 +1,6 @@
+Namespace: Metfilter
+====================
+.. doxygennamespace:: metfilter
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/physicsobject.rst b/docs/sphinx_source/c_namespaces/physicsobject.rst
@@ -0,0 +1,6 @@
+Namespace: Physicsobject
+========================
+.. doxygennamespace:: physicsobject
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/quantities.rst b/docs/sphinx_source/c_namespaces/quantities.rst
@@ -0,0 +1,6 @@
+Namespace: Quantities
+=====================
+.. doxygennamespace:: quantities
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/reweighting.rst b/docs/sphinx_source/c_namespaces/reweighting.rst
@@ -0,0 +1,6 @@
+Namespace: Reweighting
+======================
+.. doxygennamespace:: reweighting
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/scalefactor.rst b/docs/sphinx_source/c_namespaces/scalefactor.rst
@@ -0,0 +1,6 @@
+Namespace: Scalefactor
+======================
+.. doxygennamespace:: scalefactor
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/topreco.rst b/docs/sphinx_source/c_namespaces/topreco.rst
@@ -0,0 +1,6 @@
+Namespace: Topreco
+==================
+.. doxygennamespace:: topreco
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/trigger.rst b/docs/sphinx_source/c_namespaces/trigger.rst
@@ -0,0 +1,6 @@
+Namespace: Trigger
+==================
+.. doxygennamespace:: trigger
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/vectoroperations.rst b/docs/sphinx_source/c_namespaces/vectoroperations.rst
@@ -0,0 +1,6 @@
+Namespace: Vectoroperations
+===========================
+.. doxygennamespace:: vectoroperations
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/c_namespaces/whtautau_tripleselection.rst b/docs/sphinx_source/c_namespaces/whtautau_tripleselection.rst
@@ -0,0 +1,6 @@
+Namespace: Whtautau_tripleselection
+===================================
+.. doxygennamespace:: whtautau_tripleselection
+   :members:
+   :undoc-members:
+   :private-members:
diff --git a/docs/sphinx_source/changelog.rst b/docs/sphinx_source/changelog.rst
@@ -1,6 +1,12 @@
 Changelog
 ==========
 
+Sept. 2023 - Version 0.3.0
+
+* Switched to ROOT 6.28 via LCG 104, resulting in about 20% faster processing times.
+* Added support for the generation of friend trees with additional friends as input. For more details, check :ref:`FriendTree Generation`.
+* Added option to compile the CROWNlib only, allowing to reuse the same libary for multiple CROWN executables.
+
 Feb. 2023
 
 * Added support for the generation of friend trees. For more details, check :ref:`FriendTree Generation`.

diff --git a/docs/sphinx_source/conf.py b/docs/sphinx_source/conf.py
@@ -51,7 +51,7 @@ def configureDoxyfile(input_dir, output_dir):
 author = "Sebastian Brommer, Maximilian Burkart, Artur Gottmann, Sebastian Wozniewski, Stefan Wunsch"
 
 # The full version, including alpha/beta/rc tags
-release = "0.2"
+release = "0.3"
 
 
 # -- General configuration ---------------------------------------------------
@@ -77,7 +77,7 @@ def configureDoxyfile(input_dir, output_dir):
 #
 html_theme = "sphinx_rtd_theme"
 html_logo = "../logos/crown_logo_bw.svg"
-html_static_path = ["../_static"]
+# html_static_path = ["../_static"]
 html_theme_options = {
     "logo_only": True,
     "display_version": False,

diff --git a/docs/sphinx_source/contrib.rst b/docs/sphinx_source/contrib.rst
@@ -181,6 +181,8 @@ C++ functions
 
 The main purpose of the framework is to be efficient and fast. Therefore, it is essential to write clear and fast C++ functions, with as little overhead as possible. We try to enforce the following minimal requirements for new functions:
 
+* The producer should live in a well defined namespace. If a producer is meant for electrons only, if should be contained in an electron namespace, rather than putting electron in the function name.
+
 * If possible, no jitting should be used. Although RDataFrames support jitted functions, this should be avoided if possible, since a jitted function can not be optimized at compile time and will slow down the execution time of the framework.
 
 * Use `const` references wherever possible

diff --git a/docs/sphinx_source/friend_trees.rst b/docs/sphinx_source/friend_trees.rst
@@ -1,18 +1,22 @@
 FriendTree Generation
 ===========================
 
-CROWN can be used, to generate FriendTrees based on a CROWN ntuple. The concept of FriendTrees is explained here: https://root.cern/manual/trees/#widening-a-ttree-through-friends. They allow to extend an existing ntuple with new quantities. Common use cases are new high level variables like neural network outputs or additional correction factors. 
+CROWN can be used, to generate FriendTrees based on a CROWN ntuple. The concept of FriendTrees is explained here: https://root.cern/manual/trees/#widening-a-ttree-through-friends. They allow to extend an existing ntuple with new quantities. Common use cases are new high level variables like neural network outputs or additional correction factors.
+
+.. image:: ../images/root_friends.png
+  :width: 900
+  :align: center
+  :alt: Sketch of how Friend trees work
+
+The the example depicated above, two additional friends to the main NTuple are created. During analysis, the quantities stored in the friend trees can be added by using the ``AddFriend`` method. The quantities are then available in the TTree as if they were part of the original NTuple.
 
 A FriendTree is generated using a FriendTreeConfiguration. Such a configuration has some major differences, compared to a regular configuration:
 
 1. The input file is a CROWN ntuple, not a ROOT file.
 2. Only one scope per user is allowed.
 3. No global scope is required
-4. No optimization of the configuration is donw (for now)
-5. The available inputs have to be specified. The available inputs can be provided by using a CROWN ntuple as input, or a json file. The ntuple can be used for debugging proposes, when running a production, it is recommended to use a json file. The basic structure this quantities map is listed below. Such a json can then be used for multiple eras, sampletypes and scopes.
+4. The available inputs have to be specified. The available inputs can be provided by using a CROWN ntuple as input, or a json file. The ntuple can be used for debugging proposes, when running a production, it is recommended to use a json file. The basic structure this quantities map is listed below. Such a json can then be used for multiple eras, sampletypes and scopes.
 
-.. warning::
-    One limitation of the current FriendTree generation is that only one ntuple can be used as input, additional friends as input are not supported yet.
 
 .. code-block:: json
 
@@ -48,4 +52,26 @@ The basic structure of a FriendTreeConfiguration is identical to a regular confi
 
 * ``DQUANTITIESMAP`` - The path to the quantities map json file or the crown ntuple root file.
 
-All other parameters are identical to the regular configuration. Setting up producers, outputs and new systematic shifts works the same way as before. The configuration has to be of type ``FriendTreeConfiguration``. When multiple scopes are provided, one executable per scope is generated.
+All other parameters are identical to the regular configuration. Setting up producers, outputs and new systematic shifts works the same way as before. The configuration has to be of type ``FriendTreeConfiguration``. During the configuration, the available inputs are checked for consistency, to catch any possible misconfiguration early. In addition, as for CROWN ntuples, only required shifts are executed.
+
+FriendTrees with multiple input friend trees
+--------------------------------------------
+
+Starting from version 0.3 of CROWN, it is also possible to use multiple input friend trees. A typical usecase for this feature is the evaluation of Classifiers, and storing the output of the classifier in the friend tree. This way, the classifier can utilizte quantities from both the main ntuple, and from additional friend trees. The interface for configuring such a FriendTree executable is similar to the regular FriendTree configuration, with the following differences:
+
+* The information for all input files has to be provided. This means that the ``DQUANTITIESMAP`` has to be extended. It is possible to
+    1. provide a single json file, that contains the input information for all input files (the crown ntuple + all additional files)
+    2. provide a list of json files, each containing the input information for one input file
+    3. provide a list of root files (crown ntuple + all additional files)
+
+During the execution, all inputfiles have to be provided, resulting in a command line like this:
+
+.. code-block:: bash
+
+    ./FriendTree_executalbe outputfile.root inputfile1.root inputfile2.root inputfile3.root
+
+
+Before execution, the input files are checked for consistency. This means that the following checks are performed:
+
+* All inputfiles have to contain the same number of entries
+* All inputfiles have to be readable (no missing files)
diff --git a/docs/sphinx_source/index.rst b/docs/sphinx_source/index.rst
@@ -45,32 +45,25 @@ Documentation
 
 .. toctree::
    :maxdepth: 2
-   :caption: Python Configuration
+   :caption: Setup your own Configuration
 
+   contrib.rst
    py_configuration.rst
-   py_classes.rst
 
 .. toctree::
    :maxdepth: 2
-   :caption: C++ Configuration
+   :caption: Documentation
 
-   c_functions.rst
+   py_classes.rst
    namespaces.rst
 
-
 .. toctree::
    :maxdepth: 2
    :caption: Tutorials
 
    build_root.rst
    create_nanoaod.rst
 
-.. toctree::
-   :maxdepth: 2
-   :caption: How to contribute
-
-   contrib.rst
-
 
 Index
 ******

diff --git a/docs/sphinx_source/kingmaker.rst b/docs/sphinx_source/kingmaker.rst
@@ -108,7 +108,7 @@ Production of NTuples
 
 To trigger a production of ntuples run
 
-.. code-block::bash
+.. code-block:: bash
 
     law run ProduceSamples --analysis tau --config config --sample-list samples.txt --production-tag debug_2 --workers 10 --scopes mt --print-status -1
 
@@ -142,7 +142,7 @@ Production of friend trees
 
 For the production of friend trees, the same options as for the production of ntuples are available. An example command is given below:
 
-.. code-block::bash
+.. code-block:: bash
 
     law run ProduceFriends --analysis tau --config config --friend-config tau_friends --sample-list samples.txt --shifts None --friend-name test --production-tag debugging_v81 --workers 2
 
@@ -151,6 +151,31 @@ Some additional options are required:
 - ``--friend-config``: The friend config file to be used. The friend config file contains the information about the friend trees to be produced. The friend config file is located in the ``CROWN/analysis_configurations/<analysis>/config`` folder.
 - ``--friend-name``: The name of the friend tree to be produced. The name has to match the name in the friend config file. The resulting friend trees will be stored in the ``/<base>/<production-tag>/CROWNFriends/<friend-name>/`` folder.
 
+if more than one friend tree is required for the final friend tree, an additional option is required:
+
+- ``--friend-dependencies``: A list of additional configurations to be run. The list has to be provided as a comma separated list. The resulting friend trees will be stored in the ``/<base>/<production-tag>/CROWNFriends/<friend-config>/`` folder.
+
+.. warning::
+    Currently, it is not possible to specify an explicit name for the friend trees that are produed automatically using the ``--friend-dependencies`` option. Therefore, the name of the friend tree is set to the name of the friend config file. In a future update, additional functionality will be added to allow the user to specify a name for the friend trees.
+
+As an exmaple, the command
+
+.. code-block:: bash
+
+    law run ProduceFriends --analysis tau --config config --friend-config tau_classifier --friend-dependencies tau_friends,tau_friends_2 --sample-list samples.txt --shifts None --friend-name special_tau_classifier --production-tag debugging_v81 --workers 2
+
+will produce not only ntuples for all samples specified in ``samples.txt`` using the config, but also the friend trees ``tau_friends`` and ``tau_friends_2``. All those three inputs will then be used, to produce the final friend tree ``special_tau_classifier``. The resulting folder structure will be
+
+.. code-block::
+
+    /<base>/<production-tag>/
+        |- CROWNRun/
+        |- CROWNFriends/
+                        |- tau_classifier/
+                        |- tau_friends/      (name automatically generated)
+                        |- tau_friends_2/    (name automatically generated)
+
+
 To perform the generation of friend trees locally, use
 
 - ``--CROWNFriends-workflow local --CROWNRun-workflow local``: This option can be used to run the production locally. This is useful for debugging purposes, of if the batch system is currenty not available. However, be aware, that this option should only run with a limited amount of workers and samples, since it is very easy to overload the local machine.
@@ -167,7 +192,7 @@ The two relevant configuration files can be found in the ``lawluigi_configs`` fo
 
 In the ``KingMaker_law.cfg`` file, the different tasks are defined. Also, the remote filesystem is defined here:
 
-.. code-bloc::config
+.. code-block::
 
     [wlcg_fs]
     base: root://cmsxrootd-kit.gridka.de//store/user/${USER}/CROWN/ntuples/