updated docs.

dtyagi · dtyagi · commit 171d264b9f83 · 2025-11-03T18:24:29.000+01:00
diff --git a/.github/workflows/run-benchmark.yml b/.github/workflows/run-benchmark.yml
@@ -51,15 +51,15 @@ jobs:
           snakemake --use-conda --force --cores 'all'
           snakemake --use-conda --force --cores all \
             --reporter metadata4ing \
-            --report-metadata4ing-paramscript parameter_extractor.py \
+            --report-metadata4ing-paramscript ../common/parameter_extractor.py \
             --report-metadata4ing-filename metadata4ing_provenance
           unzip metadata4ing_provenance -d snakemake_provenance
       
       - name: run_linear-elastic-plate-with-hole-benchmarks_nextflow
         shell: bash -l {0}
         run: |
           cd $GITHUB_WORKSPACE/benchmarks/linear-elastic-plate-with-hole/
-          nextflow run main.nf -params-file workflow_config.json -plugins nf-prov@1.4.0
+          nextflow run main.nf -params-file workflow_config.json -c ../common/nextflow.config -plugins nf-prov@1.4.0
 
       - name: Archive Linear Elastic plate with a hole benchmark data for snakemake
         uses: actions/upload-artifact@v4
@@ -99,7 +99,7 @@ jobs:
       - name: Run plotting script
         shell: bash -l {0}
         run: |
-          python benchmarks/linear-elastic-plate-with-hole/plot_provenance.py ./snakemake_provenance
+          python benchmarks/linear-elastic-plate-with-hole/plot_metrics.py ./snakemake_provenance
 
       - name: Upload PDF plot as artifact
         uses: actions/upload-artifact@v4
diff --git a/benchmarks/common/nextflow.config b/benchmarks/common/nextflow.config
diff --git a/benchmarks/common/parameter_extractor.py b/benchmarks/common/parameter_extractor.py
@@ -4,6 +4,12 @@
     ParameterExtractorInterface,
 )
 
+"""
+Parses the parameter configuration files and their corresponding output files. Returns a dictionary.
+https://github.com/izus-fokus/snakemake-report-plugin-metadata4ing
+
+"""
+
 class ParameterExtractor(ParameterExtractorInterface):
     def extract_params(self, rule_name: str, file_path: str) -> dict:
         results = {}
diff --git a/benchmarks/common/summarize_results.py b/benchmarks/common/summarize_results.py
diff --git a/benchmarks/linear-elastic-plate-with-hole/Snakefile b/benchmarks/linear-elastic-plate-with-hole/Snakefile
@@ -41,7 +41,7 @@ rule summary:
     input:
         # the summary is performed for all configurations saved into a single file 
         # (snakemake_results/linear-elastic-plate-with-hole/fenics/summary.json)
-        script = "summarize_results.py",
+        script = "../common/summarize_results.py",
         parameters = expand("{param}", param=[configuration_to_parameter_file[c] for c in configurations]),
         mesh = expand(f"{result_dir}/mesh/mesh_{{configuration}}.msh", configuration=configurations),
         metrics = lambda wildcards: expand(
diff --git a/benchmarks/linear-elastic-plate-with-hole/environment_mesh.yml b/benchmarks/linear-elastic-plate-with-hole/environment_mesh.yml
@@ -1,4 +1,6 @@
 name: mesh-generation
+# Environment file for create_mesh.py script. Called by the main workflow.
+
 channels:
   - conda-forge
 
diff --git a/benchmarks/linear-elastic-plate-with-hole/environment_postprocessing.yml b/benchmarks/linear-elastic-plate-with-hole/environment_postprocessing.yml
@@ -1,4 +1,6 @@
 name: postprocessing
+# Environment file for summarize_results.py script. Called by the main workflow.
+
 channels:
   - conda-forge
   - defaults
diff --git a/benchmarks/linear-elastic-plate-with-hole/fenics/environment_simulation.yml b/benchmarks/linear-elastic-plate-with-hole/fenics/environment_simulation.yml
@@ -1,4 +1,6 @@
 name: fenics_simulation
+# Environment file for fenics simulation scripts. Called by fenics tool workflow.
+
 channels:
   - conda-forge
 
diff --git a/benchmarks/linear-elastic-plate-with-hole/kratos/environment_simulation.yml b/benchmarks/linear-elastic-plate-with-hole/kratos/environment_simulation.yml
@@ -1,4 +1,6 @@
 name: kratos_simulation
+# Environment file for kratos simulation scripts. Called by kratos tool workflow.
+
 channels:
   - conda-forge
 dependencies:
diff --git a/benchmarks/linear-elastic-plate-with-hole/main.nf b/benchmarks/linear-elastic-plate-with-hole/main.nf
@@ -137,7 +137,7 @@ workflow {
 
     //Summarizing results
     def ch_benchmark = Channel.value(params.benchmark)
-    def ch_summarize_python_script = Channel.value(file('summarize_results.py'))
+    def ch_summarize_python_script = Channel.value(file('../common/summarize_results.py'))
     summary(ch_summarize_python_script, \
             input_summary_configuration, \
             input_summary_parameter_file, \
diff --git a/benchmarks/linear-elastic-plate-with-hole/plot_metrics.py b/benchmarks/linear-elastic-plate-with-hole/plot_metrics.py
diff --git a/docs/benchmark_addition_guide.md b/docs/benchmark_addition_guide.md
diff --git a/docs/getting_started/benchmark_addition_guide.md b/docs/getting_started/benchmark_addition_guide.md
@@ -0,0 +1,89 @@
+# A Guide to add a Benchmark Problem
+
+The steps are as follows:
+
+1. **Create a folder for the problem**
+
+    Inside the `benchmarks` directory, create a folder for the problem e.g. `benchmarks/problem_name`.
+
+2. **Add the simulation tool**
+
+    - For each simulation tool used to solve the problem, create a corresponding subfolder inside the problem directory, e.g.
+
+        ```
+        benchmarks/problem_name/
+        ├── tool_A
+        ├── tool_B
+        ```
+
+    -   Inside each tool’s folder (e.g. tool_A/):
+        - Write a script for running the simulation.
+        - Write the I/O interface scripts needed to ensure a common I/O interface across the tools.
+        - Create an environment.yml file listing out all the tool-specific software dependencies.
+        - Develop a workflow script (Snakemake/Nextflow) connecting the I/O scripts, simulation code and environment.yml files.
+
+3. **Define parameter configurations**
+
+    For each parameter configuration run using simulation tools, create a JSON file in `benchmarks/problem/` specifying parameters related to the domain geometry, mesh information, and constitutive model parameters, cf. [parameter_1.json](https://github.com/BAMresearch/NFDI4IngModelValidationPlatform/blob/main/benchmarks/linear-elastic-plate-with-hole/parameters_1.json).
+
+4. **Create a script for discovering the configurations**
+
+    - Create the script `generate_config.py` in `benchmarks/problem/`.
+    - The script should:
+        - Discover all the configuration JSON files.
+        - Extract configurations.
+        - List the simulation tools for each configuration, cf. [generate_config.py](https://github.com/BAMresearch/NFDI4IngModelValidationPlatform/blob/main/benchmarks/linear-elastic-plate-with-hole/generate_config.py).
+
+        **Note:** The simulation-tool-specific keywords are used by the main workflow to call the corresponding sub-workflows.
+
+5. **Create the mesh generation script**
+
+    **With mesh generation**
+
+    - Create `create_mesh.py` inside `benchmarks/problem_name/` to define the domain geometry.
+    - In the file, provide the interface for the user-adjustable inputs related to geometry, mesh and numerical solver. These inputs are passed to the script via `parameter_*.json`.
+    - If required, include an environment file for the mesh generation script in the same directory.
+
+    **Pre-existing meshes**
+
+    - Ensure that the parameter JSON files and mesh files are named according to their configurations correctly.
+    - Modify generate_config.py to include the key "configuration_to_mesh_file" listing all the meshes for different configurations.
+    - In the main & sub-workflows:
+        - For Snakemake:
+            - Comment out the create_mesh rule in the main workflow.
+            - Change in summary rule's input:
+
+                ```
+                mesh = expand("{mesh}", param=[configuration_to_mesh_file[c] for c in configurations])
+                ```
+
+            - Change in tool's sub-workflow input:
+
+                ```
+                mesh = lambda wildcards: configuration_to_mesh_file[wildcards.configuration]
+                ```
+
+        - For Nextflow:
+            - Comment out the create_mesh process in the main workflow.
+            - Create an input channel for the mesh files.
+
+                ```
+                def mesh_files_path = []
+                params.configurations.each { elem -> mesh_files_path.add(file(params.configuration_to_mesh_file[elem])) }
+
+                def ch_mesh_files = Channel.fromList(mesh_files_path)
+                ```
+
+            - Merge the configurations, parameters and mesh channels before running simulation.
+
+                ```
+                input_process_run_simulation = ch_configurations.merge(ch_parameter_files, ch_mesh_files)
+                ```
+
+6. **Develop the main workflow**
+
+    - Place the main workflow in `benchmarks/problem/`.
+    - Include rules for:
+        - Running `create_mesh.py`.
+        - Calling the simulation-tool-specific sub-workflows.
+    - Additional rules can be added depending on the requirements, cf. [main.nf](https://github.com/BAMresearch/NFDI4IngModelValidationPlatform/blob/main/benchmarks/linear-elastic-plate-with-hole/main.nf).
diff --git a/docs/getting_started/provenance.md b/docs/getting_started/provenance.md
@@ -0,0 +1,23 @@
+# Provenance
+The package also stores the provenance records i.e.:
+
+- which input files were used,
+- which processes or scripts were executed,
+- what parameters, software versions, and container images were used,
+- what outputs each step produced, etc.
+
+While using nextflow, provenance reports of the workflow executions are rendered using [nf-prov](https://github.com/nextflow-io/nf-prov) plugin. In the case of snakemake, [Metadata4ing reporter](https://github.com/izus-fokus/snakemake-report-plugin-metadata4ing) is used. The provenance report is stored in [RO-Crate](https://www.researchobject.org/ro-crate/) format.
+
+## Terminologies
+
+### Parameter Extractor
+
+`parameter_extractor.py` passes arguments to the metadata4ing reporter plugin. It parses the parameter configuration files and their corresponding output files.
+
+### Metrics Plotting
+
+`plot_metrics.py`contains implementation for:
+
+- Reading the RO-Crate files using [rdflib](https://github.com/RDFLib/rdflib).
+- Running a SPARQL query on the rdflib graph objects.
+- Plotting the simulation outputs tool-wise from different parameter configuration runs.
diff --git a/docs/getting_started/workflow.md b/docs/getting_started/workflow.md
@@ -4,14 +4,16 @@ The platform uses a hierarchical workflow system that incorporates:
 - Standardized I/O streams to the simulation tools.
 - Multiple parameter configurations per benchmark.
 - Automated mesh generation.
+- Provenance reports generation.
+- Querying the research objects.
 
 # Workflow
 
 The workflow has a hierarchical structure. The common tasks like mesh generation and results' summary creation are done by the top-level workflow. The top-level workflow interacts with the sub-workflows which are tool-specific. The sub-workflows are responsible for running the scripts containing simulation code and pre/post-processing scripts necessary for processing the mesh files or the simulation output. 
 
 The benchmark `linear-elastic-plate-with-hole` is implemented with nextflow and snakemake packages. For this benchmark, the structure of the snakemake workflow is exemplified below:
 
-```
+```shell
 linear-elastic-plate-with-hole/Snakefile 
 │
 ├── calls ──> fenics/Snakefile 
@@ -24,13 +26,11 @@ linear-elastic-plate-with-hole/Snakefile
     └── executes ──> postprocess_results.py
 ```
 
-# Terminologies
+## Terminologies
 
 ### Parameter JSON File
 
-A `parameter_*.json` file defines all the user-adjustable parameters for mesh generation, material properties, boundary conditions, and solver settings for finite element simulations. Each parameter file represents a unique configuration of these parameters that will be processed by the workflow system.
-
-Cf. `benchmarks/linear-elastic-plate-with-hole/parameters_1.json`
+A `parameter_*.json` file defines all the user-adjustable parameters for mesh generation, material properties, boundary conditions, and solver settings for finite element simulations. Each parameter file represents a unique configuration of these parameters that will be processed by the workflow system, e.g. [parameter_1.json](https://github.com/BAMresearch/NFDI4IngModelValidationPlatform/blob/main/benchmarks/linear-elastic-plate-with-hole/parameters_1.json).
 
 ```json
 {   
@@ -42,43 +42,30 @@ The keyword `"configuration"` is a unique identifier for the provided parameter
 
 ### Configuration Generator
 
-`generate_config.py` file writes a configuration file for the workflow managers (snakemake or nextflow) extracting the configuration information from `parameter_*.json` files. The keywords for simulation tools to run the configurations on are also specified by the user in this file.
-
-Cf. `benchmarks/linear-elastic-plate-with-hole/generate_config.py`
+`generate_config.py` file writes a configuration file for the workflow managers (snakemake or nextflow) extracting the configuration information from `parameter_*.json` files. Further, it lists the simulation tools that are going to run the different parameter configurations, e.g. [generate_config.py](https://github.com/BAMresearch/NFDI4IngModelValidationPlatform/blob/main/benchmarks/linear-elastic-plate-with-hole/generate_config.py).
 
+### Mesh Generation
 
-### Mesh Generation 
-<!--[create_mesh.py](https://github.com/BAMresearch/NFDI4IngModelValidationPlatform/blob/main/benchmarks/linear-elastic-plate-with-hole/create_mesh.py) -->
+The `create_mesh.py` file contains the code for mesh generation. In case the mesh(es) are already available, the file is not needed. In the `linear-elastic-plate-with-hole` example the [create_mesh.py](https://github.com/BAMresearch/NFDI4IngModelValidationPlatform/blob/main/benchmarks/linear-elastic-plate-with-hole/create_mesh.py) file:
 
-The `create_mesh.py` file contains the code for mesh generation. In case the mesh(es) are already available, the file is not needed. In the `linear-elastic-plate-with-hole` example the file: 
-
-1. receives inputs from `\parameter_*.json` and output `.msh` files.
-2. Uses `pint` library for unit conversion.
-3. Uses `gmsh` library for mesh generation.
-
-Cf. `benchmarks/linear-elastic-plate-with-hole/create_mesh.py`
+1. receives inputs from `\parameter_*.json` and outputs `.msh` files.
+2. Uses `gmsh` library for mesh generation.
+3. Uses `pint` library for unit conversion to the SI units.
 
 ### Summarize File
-`summarize_results.py` creates a JSON file containing the solution metrics and their corresponding parameter configurations after simulation runs of a benchmark.
- 
-Cf. `benchmarks/linear-elastic-plate-with-hole/summarize_results.py`
 
+`summarize_results.py` creates a JSON file containing the solution metrics and their corresponding parameter configurations after simulation runs of a benchmark.
 
 ### Environment Files
-The environment files are YML files which configures the environment for running a script. They contain a list of software libraries that build up an environment.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 
+The environment files are YML files which configures the environment for running a script. They contain a list of software libraries that build up an environment. They are present inside the simulation tool's folder for the tool-specific scripts and inside the benchmark folder for common scripts.
+```shell
+benchmarks/
+    ├── linear-elastic-plate-with-hole/
+        ├── environment_mesh.yml
+        ├── environment_postprocessing.yml
+        ├── fenics
+            ├── environment_simulation.yml
+        ├── kratos
+            ├── environment_simulation.yml
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -34,13 +34,15 @@ markdown_extensions:
 
 nav:
   - index.md
-  - introduction.md
-  - benchmark_addition_guide.md
+  - Getting Started:
+      - getting_started/workflow.md
+      - getting_started/provenance.md
+      - getting_started/benchmark_addition_guide.md
   #- conventions.md
   #- data.md
   #- interface.md
   - Benchmarks:
-     - Introduction: "benchmarks/index.md"
+     #- Introduction: "benchmarks/index.md"
      - Linear Elasticity: "benchmarks/linear elasticity"
      #- Plasticity: benchmarks/plasticity
   - "zz_bibliography.md"
