edits to the docs. more edits to come in the next push.

Author: dtyagi

.github/workflows/run-benchmark.yml

@@ -53,7 +53,7 @@ jobs:
             --reporter metadata4ing \
             --report-metadata4ing-paramscript parameter_extractor.py \
             --report-metadata4ing-filename metadata4ing_provenance
-          unzip metadata4ing_provenance -d reporter_data
+          unzip metadata4ing_provenance -d snakemake_provenance
       
       - name: run_linear-elastic-plate-with-hole-benchmarks_nextflow
         shell: bash -l {0}
@@ -66,7 +66,7 @@ jobs:
         with:
             name: snakemake_results_linear-elastic-plate-with-hole
             path: |
-              benchmarks/linear-elastic-plate-with-hole/reporter_data/
+              benchmarks/linear-elastic-plate-with-hole/snakemake_provenance/
 
       - name: Archive Linear Elastic plate with a hole benchmark data for nextflow
         uses: actions/upload-artifact@v4

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 = "summarise_results.py",
+        script = "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(
@@ -65,4 +65,20 @@ rule summary:
             --input_solution_field_data {input.solution_field_data} \
             --input_benchmark {benchmark} \
             --output_summary_json {output.summary_json}
-        """
+        """
+
+""" 
+Steps to add a new simulation tool to the workflow:
+
+1. Write the tool-specific workflow & scripts and store them in the benchmarks/linear-elastic-plate-with-hole/tool_name/.
+2. Add the tool name to "tools" workflow_config.json (generated here using generate_config.py)
+
+------------------------------------------------------------------------------------------------------------------------
+"rule all" defines the final target of the workflow. Knowing the final target, the snakemake determines
+the dependency chain automatically.
+
+Wildcards in the rule definitions allow to generalize the rules for multiple configurations and tools.
+They act like placeholders (variables) in filenames or paths that get automatically filled in by Snakemake.
+
+Information on snakemake rules: https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html
+"""

…plate-with-hole/plateWithHoleSolution.py …c-plate-with-hole/analytical_solution.pybenchmarks/linear-elastic-plate-with-hole/plateWithHoleSolution.py renamed to benchmarks/linear-elastic-plate-with-hole/analytical_solution.py benchmarks/linear-elastic-plate-with-hole/plateWithHoleSolution.py renamed to benchmarks/linear-elastic-plate-with-hole/analytical_solution.py

@@ -14,7 +14,7 @@
 
 # Add parent directory to sys.path
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-from plateWithHoleSolution import PlateWithHoleSolution
+from analytical_solution import PlateWithHoleSolution
 
 
 def run_fenics_simulation(

benchmarks/linear-elastic-plate-with-hole/fenics/run_fenics_simulation.py

@@ -6,7 +6,7 @@
 import sys
 # Ensure the parent directory is in the path to import PlateWithHoleSolution
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-from plateWithHoleSolution import PlateWithHoleSolution
+from analytical_solution import PlateWithHoleSolution
 
 def create_kratos_input(
     parameter_file: str,

benchmarks/linear-elastic-plate-with-hole/kratos/create_kratos_input.py

@@ -137,8 +137,8 @@ workflow {
 
     //Summarizing results
     def ch_benchmark = Channel.value(params.benchmark)
-    def ch_summarise_python_script = Channel.value(file('summarise_results.py'))
-    summary(ch_summarise_python_script, \
+    def ch_summarize_python_script = Channel.value(file('summarize_results.py'))
+    summary(ch_summarize_python_script, \
             input_summary_configuration, \
             input_summary_parameter_file, \
             input_summary_mesh, \
@@ -148,10 +148,22 @@ workflow {
             ch_tools)
 
 }
+/*
+Steps to add a new simulation tool to the workflow:
 
-// Steps to perform to add a new simulation tool to the workflow:
-// 1. Add the tool name to "tools" workflow_config.json (generated here using generate_config.py)
-// 2. Include the tool-specific workflow script at the top of this file.
-// 3. Create an input channel for the new tool (e.g. see the definition of input_fenics_workflow)
-// 4. Invoke the new tool-specific workflow (similar to fenics_workflow) & using its output, prepare inputs for the summary process.
-// 5. Concatenate the prepared inputs to form the final input channels for the summary process.
+1. Write the tool-specific workflow & scripts and store them in the benchmarks/linear-elastic-plate-with-hole/tool_name/.
+2. Add the tool name to "tools" workflow_config.json (generated here using generate_config.py)
+3. Include the tool-specific workflow script at the top of this file.
+4. Create an input channel for the new tool (e.g. see the definition of input_fenics_workflow)
+5. Invoke the new tool-specific workflow (similar to fenics_workflow) & using its output, prepare inputs for the summary process.
+6. Concatenate the prepared inputs to form the final input channels for the summary process.
+
+---------------------------------------------------------------------------------------------------------------------------------
+
+Remark: Care should be taken to track the entries in the I/O channels, as the process output for a given configuration 
+may not arrive in the same order as the inputs were sent. When reusing channel entries after process execution, outputs should 
+be matched with their corresponding inputs using a common key.
+
+Information on channel operations: https://www.nextflow.io/docs/latest/reference/operator.html
+Information on channels: https://training.nextflow.io/2.2/basic_training/channels/
+*/ 

benchmarks/linear-elastic-plate-with-hole/main.nf

@@ -9,6 +9,20 @@ def create_summary(configurations: list[str],
                    benchmark: str,
                    summary_json: str) -> None:
 
+    """
+    Create a summary JSON file containing simulation results and metadata.
+        
+    Args:
+        configurations: List of configuration names
+        parameter_files: List of paths to parameter JSON files
+        mesh_files: List of paths to mesh files
+        solution_metrics: List of paths to metrics JSON files
+        solution_field_data: List of paths to solution field data files
+        benchmark: Name of the benchmark
+        summary_json: Output path for the summary JSON file
+    """
+    
+    
     all_summaries = []
     for idx, config in enumerate(configurations):
         print(idx, config)

…tic-plate-with-hole/summarise_results.py …tic-plate-with-hole/summarize_results.pybenchmarks/linear-elastic-plate-with-hole/summarise_results.py renamed to benchmarks/linear-elastic-plate-with-hole/summarize_results.py benchmarks/linear-elastic-plate-with-hole/summarise_results.py renamed to benchmarks/linear-elastic-plate-with-hole/summarize_results.py

@@ -1,14 +1,6 @@
 # A Guide to add a Benchmark Problem
 
-The platform uses a hierarchical workflow system that incorporates:
-
-- Multiple simulation tools (e.g., FEniCS, Kratos) for solving a problem.
-- Standardized I/O streams to the simulation tools.
-- Multiple parameter configurations per benchmark.
-- Automated mesh generation.
-<!-- Provenance tracking and metadata collection -->
-
-This guide outlines the algorithm needed to add a benchmark problem.
+The steps are as follows:
 
 1. **Create a folder for the problem** 
 
@@ -30,10 +22,15 @@ This guide outlines the algorithm needed to add a benchmark problem.
         - Develop a workflow script connecting the I/O scripts, simulation code and environment.yml files.
 
 3. **Create the mesh generation script**
-    - Write `create_mesh.py` inside `benchmarks/problem_name/` to define the domain geometry.
-    - Provide user-modifiable inputs via a JSON input interface, cf. `benchmarks/linear-elastic-plate-with-hole/create_mesh.py`.
+
+    **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**
+    - Provide the path to the mesh(es) location directly to the sub-workflow of the simulation tool. `parameter_*.json` will only contain the material parameters in this case.
+
 4. **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. `benchmarks/linear-elastic-plate-with-hole/parameters_*.json`.

docs/benchmark_addition_guide.md

@@ -0,0 +1,84 @@
+The platform uses a hierarchical workflow system that incorporates:
+
+- Multiple simulation tools (e.g., FEniCS, Kratos) for solving a problem.
+- Standardized I/O streams to the simulation tools.
+- Multiple parameter configurations per benchmark.
+- Automated mesh generation.
+
+# 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:
+
+```
+linear-elastic-plate-with-hole/Snakefile 
+│
+├── calls ──> fenics/Snakefile 
+│   └── executes ──> run_fenics_simulation.py
+│
+└── calls ──> kratos/Snakefile 
+    ├── executes ──> msh_to_mdpa.py
+    ├── executes ──> create_kratos_input.py
+    ├── executes ──> run_kratos_simulation.py
+    └── executes ──> postprocess_results.py
+```
+
+# 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`
+
+```json
+{   
+    "configuration": "1",    
+}
+```
+
+The keyword `"configuration"` is a unique identifier for the provided parameter set. It is used in output file naming and workflow tracking and must be unique across all parameter files.
+
+### 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`
+
+
+### 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 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`
+
+### 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`
+
+
+### 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+