From b86331018c220503356a3fcafe07e5b086478fbd Mon Sep 17 00:00:00 2001
From: Giovanni La Mura <giovanni.lamura@inaf.it>
Date: Tue, 13 Feb 2024 18:06:01 +0100
Subject: [PATCH] Add README documentation for testing programs

---
 build/README.md | 20 ++++++++++++++++++++
 src/README.md   |  2 +-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/build/README.md b/build/README.md
index c2634408..2596e698 100644
--- a/build/README.md
+++ b/build/README.md
@@ -75,3 +75,23 @@ The execution of trapping programs requires at least one of the previous program
    > ./np_trapping ../../test_data/trapping/DFRFME ../../test_data/trapping/DLFFT .
 
 5. Check the consistency between `np_trapping` output files (`c_out66.txt` and `c_out67.txt`) and the legacy *FORTRAN* output for this case (the files named, respectively, `fort.66` and `fort.67` in the `test_data/trapping/` folder). Consider that some of the output values will be affected by numeric noise and take substantially different values. However, this is expected for results whose order of magnitude is clearly below the precision level of the calculation, as they represent results appraching zero that were just approximated with different precision.
+
+### testing
+
+The `testing` folder contains programs that are used to test the consistency of data written in different binary formats. At present, the only binary files that can be read and written both in legacy and _HDF5_ formay are the configuration files (named `TEDF`) and the transition matrix files (named `TTMS`). The _HDF5_ versions of these files (marked with an `hd5` extension) can be inspected by standard _HDF5_ tools, such as `h5dump`. To check the consistency of these two type of files, the `testing` suite provides two programs:
+
+- `test_TEDF`
+
+This program checks for the consistency of the configuration data loaded from a formatted configuration file, a legacy binary file and an _HDF5_ binary file. It must be executed as:
+
+> ./test_TEDF PATH_TO_EDFB PATH_TO_c_TEDF PATH_TO_c_TEDF.hd5
+
+where the command line arguments must be valid paths to, respectively, the formatted configuration file, a binary configuration file produced by one of the _NP_ codes presented above (generally named `c_TEDF`) and a binary configuration file saved in _HDF5_ format (`c_TEDF.hd5`). The program checks for the data in each of the above formats and, after writing a short log to the terminal, returns a result value of 0, in case of success, or a positive error code in case of inconsistent data.
+
+- `test_TTMS`
+
+This program checks for the consistency of transition matrix data files. It is executed similarly to the previous one, but with just two arguments:
+
+> ./test_TTMS PATH_TO_c_TTMS PATH_TO_c_TTMS.hd5
+
+where the arguments must be valid paths to binary transition matrix files saved in the legaci or the _HDF5_ format. Similarly to the previous case, the program writes a short log and returns a result value of 0, for success, or a positive number in case of inconsistency detection.
diff --git a/src/README.md b/src/README.md
index 6e7b540e..c345b389 100644
--- a/src/README.md
+++ b/src/README.md
@@ -4,7 +4,7 @@ This directory collects the source code of the original programs and the develop
 
 ## Instructions
 
-The original code is contained in the folders named `cluster`, `sphere` and `trapping`. Each folder contains a `Makefile` to compile either the whole program set or the single programs. A global `Makefile`, which contains instructions to build all the original source code, is available directly in the `src` folder.
+The original code is contained in the folders named `cluster`, `sphere` and `trapping`. The `testing` folder contains additional programs that are used to perform consistency tests during the development state. Each folder contains a `Makefile` to compile either the whole program set or the single programs. A global `Makefile`, which contains instructions to build all the original source code, is available directly in the `src` folder.
 
 In all cases, build commands executed through `make` will output the object files and the linked binaries in the proper folders under the build directory.
 
-- 
GitLab