started architecture overview

JADE-V-V · Feb 11, 2025 · 2bd2a8e · 2bd2a8e
1 parent 2f9e596
commit 2bd2a8e
Show file tree

Hide file tree

Showing 34 changed files with 130 additions and 2 deletions.
diff --git a/docs/source/dev/architecture_overview.rst b/docs/source/dev/architecture_overview.rst
@@ -1,3 +1,94 @@
 #############################
 Overview of JADE architecture
 #############################
+
+The scope of this section is to describe the architecture of JADE. The section
+is intended for new developers that need to familiarize with the codebase or for
+users that are just more curious to know a bit more of how JADE works.
+
+.. note:: 
+
+    If you do not have time for this and you just want to add a new benchmark
+    using the already available *table* and *plot* types, you do not 
+    need to know how JADE works. You can easily skip directly
+    to the :ref:`add_benchmark` section.
+
+JADE V&V ecosystem
+==================
+
+This documentation describes what we usually refer as the "JADE engine". However,
+This is only a part of the JADE V&V ecosystem.
+
+.. image:: /img/dev_guide/JADE_ecosystem.png
+    :width: 800
+    :align: center
+
+The three repositories fully owned by the JADE team are:
+
+- `JADE <https://github.com/JADE-V-V/JADE>`_: the main repository containing the engine.
+- `JADE-RAW-RESULTS <https://github.com/JADE-V-V/JADE-RAW-RESULTS>`_: where the raw results processed by 
+  JADE can be uploaded by the different users in order to have a centralized database and avoid duplication
+  of efforts.
+- `JADE-WEB-APP <https://github.com/JADE-V-V/JADE-RAW-RESULTS>`_: which stores a web application that allows
+  to interactively plot the benchmark results using the data contained in the JADE-RAW-RESULTS repository.
+  This allows to easily compare the results of different benchmarks and different codes without the need
+  to install JADE. The level of post-processing detail is lower than the one provided by JADE engine 
+  processor, but it has the advantage of being interactive and easy to use.
+
+Moreover, it can bee seen how two further important functions have been separated from the JADE engine scope.
+The first is the storage and version control of the benchmark inputs. Depending on the distribution
+policy, these are stored either in the `IAEA repository <https://github.com/IAEA-NDS/open-benchmarks>`_,
+in the SINBAD project GitLab or in the F4E GitLab.
+
+The second function is the parsing of simulation input and output files. Parsers of this type are
+transport-code dependent and have much more usecases than just being used by JADE. MCNP and D1UNED files
+are parsed using `F4Enix <https://f4enix.readthedocs.io/en/latest/>`_, OpenMC files are parsed using their
+native `Python API <https://docs.openmc.org/en/stable/pythonapi/index.html>`_ while Serpent files are parsed
+thanks to `serpentTools <https://serpent-tools.readthedocs.io/en/master/>`_.
+
+High level overview
+===================
+
+.. image:: /img/dev_guide/JADE_high_lvl_arch.png
+    :width: 800
+    :align: center
+
+The picture above describes the highest level of JADE architecture. As it can 
+be seen, users only interact with 4 main configuration files that are better
+described in the :ref:`config` section. Of these, only the ones related to 
+environmental variables and libraries should be manually modified. Instead, due to
+their complexity, the files controlling jade benchmarks executions and 
+post-processing should be modified through the provided GUI. All this information,
+toghether with the benchmark specific configurations and the status of the 
+local JADE installation (i.e. the contents of the folder structure) are fed into
+the ``JadeApp`` class which controls all JADE operations.
+
+JADE App
+========
+The :class:`JadeApp` class is the main class of JADE. All entry points contained in the
+``src/__main__.py`` and ``src/utilities.py`` files are connected to methods
+of this class. The App is responsible for the following tasks:
+
+- parsing and storing all the configuration options (through speicif data classes)
+- install jade folder structure at the first run (including input fetching). Paths are stored in the
+  :class:`PathsTree` class
+- parse and store information regarding which simulations have been already performed and which
+  data has been already raw processed (through the :class:`GlobalStatus` class)
+- perform the benchmark execution through the :class:`BenchmarkRun` class
+- perform the raw processing through the :class:`RawProcessor` class
+- perform the post-processing through the :class:`ExcelProcessor` and :class:`AtlasProcessor` classes
+
+In the following sections, the different branches of JADE execution and post-processing are described
+in more detail.
+
+Benchmark execution architecture
+================================
+
+Raw processing architecture
+===========================
+
+Excel processing architecture
+=============================
+
+Atlas processing architecture
+=============================
diff --git a/docs/source/dev/insertbenchmarks.rst b/docs/source/dev/insertbenchmarks.rst
@@ -1,3 +1,5 @@
+.. _add_benchmark:
+
 ###################
 Add a new benchmark
 ###################
@@ -282,6 +284,26 @@ Optional configuration options are:
 * ``select_runs``: This option allows
   to specify a regex pattern (in string format). Only the cases/runs that match the pattern will be plotted.
 
+An example of plot configuration is shown below:
+
+.. code-block:: yaml
+
+  Wave plots (Isotopes):
+    results:  
+      - Leakage neutron flux (total)
+      - Leakage photon flux
+      - SDDR
+    plot_type: waves
+    title: Ratio wave plots
+    x_label: Zaid and MT value
+    y_labels: ''
+    x: Case
+    y: Value
+    expand_runs: false
+    plot_args:
+      limits: [0.5, 1.5]
+      shorten_x_name: 2
+    select_runs: SphereSDDR_\d+_[A-Za-z]+-\d+_
 
 Implement new functionalities
 =============================

diff --git a/docs/source/dev/pp_gallery.rst b/docs/source/dev/pp_gallery.rst
@@ -49,4 +49,16 @@ plot_args
   limit line in case the data exceeds it.
 * ``subcases``: a list of subcases to be plotted. The first value is the name of the column that identify the
   subcasese while the second value is a list of the subcases to be plotted. This will cause the plot to be split
-  in as many rows as the number of subcases.
+  in as many rows as the number of subcases.
+
+Waves
+-----
+
+plot_args
+
+* ``limits``: a tuple of two values that define the limits of the plot. The first value is the y min limit while the
+  second value is the y max limit.
+* ``shorten_x_name``: this type of plots are often categorical. In the event of using the 
+  cases as x axis, the long names of the benchmark runs can become problematic. This option
+  will split the name of the benchmark run on the '_' symbols and retain only the last N chunks
+  where N is the specified *shorten_x_name* value.
diff --git a/docs/source/img/OOPscheme.png b/docs/source/img/OOPscheme.png
diff --git a/docs/source/img/compmenu.png b/docs/source/img/compmenu.png
diff --git a/docs/source/img/conf/activation.jpg b/docs/source/img/conf/activation.jpg
diff --git a/docs/source/img/conf/admissiblebin.png b/docs/source/img/conf/admissiblebin.png
diff --git a/docs/source/img/conf/atlasbench.png b/docs/source/img/conf/atlasbench.png
diff --git a/docs/source/img/conf/comp.png b/docs/source/img/conf/comp.png
diff --git a/docs/source/img/conf/excelbench.png b/docs/source/img/conf/excelbench.png
diff --git a/docs/source/img/conf/exp.jpg b/docs/source/img/conf/exp.jpg
diff --git a/docs/source/img/conf/lib.png b/docs/source/img/conf/lib.png
diff --git a/docs/source/img/conf/main_config.JPG b/docs/source/img/conf/main_config.JPG
diff --git a/docs/source/img/dev_guide/CE_example.PNG b/docs/source/img/dev_guide/CE_example.PNG
diff --git a/docs/source/img/dev_guide/Example_config_fnstof.PNG b/docs/source/img/dev_guide/Example_config_fnstof.PNG
diff --git a/docs/source/img/dev_guide/Example_config_oktavian.PNG b/docs/source/img/dev_guide/Example_config_oktavian.PNG
diff --git a/docs/source/img/dev_guide/Example_exp_data.PNG b/docs/source/img/dev_guide/Example_exp_data.PNG
diff --git a/docs/source/img/dev_guide/FNS-TOF_atlas.jpg b/docs/source/img/dev_guide/FNS-TOF_atlas.jpg
diff --git a/docs/source/img/dev_guide/JADE_ecosystem.png b/docs/source/img/dev_guide/JADE_ecosystem.png
diff --git a/docs/source/img/dev_guide/JADE_high_lvl_arch.png b/docs/source/img/dev_guide/JADE_high_lvl_arch.png
diff --git a/docs/source/img/dev_guide/plot_example.PNG b/docs/source/img/dev_guide/plot_example.PNG
diff --git a/docs/source/img/dev_guide/plot_example_tof.PNG b/docs/source/img/dev_guide/plot_example_tof.PNG
diff --git a/docs/source/img/expmenu.png b/docs/source/img/expmenu.png
diff --git a/docs/source/img/main_menu.jpg b/docs/source/img/main_menu.jpg
diff --git a/docs/source/img/postmenu.png b/docs/source/img/postmenu.png
diff --git a/docs/source/img/scheme.png b/docs/source/img/scheme.png
diff --git a/docs/source/img/troubleshooting/notrun.png b/docs/source/img/troubleshooting/notrun.png
diff --git a/docs/source/img/uty/Fe-56_MT102.png b/docs/source/img/uty/Fe-56_MT102.png
diff --git a/docs/source/img/uty/Translation_logic.jpg b/docs/source/img/uty/Translation_logic.jpg
diff --git a/docs/source/img/uty/generate.png b/docs/source/img/uty/generate.png
diff --git a/docs/source/img/uty/printlib.png b/docs/source/img/uty/printlib.png
diff --git a/docs/source/img/uty/printmat1.jpg b/docs/source/img/uty/printmat1.jpg
diff --git a/docs/source/img/uty/printmat2.jpg b/docs/source/img/uty/printmat2.jpg
diff --git a/docs/source/usage/folders.rst b/docs/source/usage/folders.rst
@@ -64,7 +64,10 @@ The following is a scheme of the JADE folder structure:
         |-----logs
         |
         |----- post_processing
-        |        |----- TODO
+        |        |----- <date>
+        |                 |----- <Benchmark name>
+        |                              |----- atlas
+        |                              |----- excel
         |        
         |----- raw_data
         |        |----- _<code>_-_<library>_