Update README instructions

build/README.md

@@ -12,36 +12,48 @@ This section describes the use of the pre-existing programs, once the binaries h
 
 ### cluster
 
-1. cd to the `build/cluster` folder
-2. run `edfb`
+1. cd to the `build/cluster` folder.
+2. Run `edfb`:
    
    > ./edfb
    
-3. run `clu`
+3. Run `clu`:
    
    > ./clu
    
 *NOTE:* both `edfb` and `clu` expect an input which is assumed to be in a folder named `../../test_data/cluster/` (i.e. two levels above the current execution path)
 
-*TODO:* set up a code variable to locate the input data (data file paths should not be hard-coded)
+4. Run `np_cluster`:
+
+   > ./np_cluster
+
+*NOTE:* The C++ version does not need to run a configuration program because all configuration operations are handled by the code at run-time.
+
+5. Check the consistency between the output files (the default output file for the FORTRAN code is named `OCLU`, while the corresponding C++ output has the default name of `c_OCLU`).
 
 ### sphere
 
-1. cd to the `build/sphere` folder
-2. run `edfb`
+1. cd to the `build/sphere` folder.
+2. Run `edfb`:
 
    > ./edfb
    
-3. run `sph`
+3. Run `sph`:
 
    > ./sph
    
 *NOTE:* both `edfb` and `sph` expect an input which is assumed to be in a folder named `../../test_data/sphere/` (i.e. two levels above the current execution path)
 
-*TODO:* set up a code variable to locate the input data (data file paths should not be hard-coded)
+4. Run `np_sphere`:
+
+   > ./np_sphere
+
+*NOTE:* The C++ version does not need to run a configuration program because all configuration operations are handled by the code at run-time.
+
+5. Check the consistency between the output files (the default output file for the FORTRAN code is named `OSPH`, while the corresponding C++ output has the default name of `c_OSPH`).
 
 ### trapping
 
 The execution of trapping programs requires at least one of the previous programs to have produced a complete output set.
 
-*TODO:* investigate which conditions allow `clu` or `sph` to write `TTMS` output files.
+*TODO:* Define a common format for binary I/O operations on the TTMS file.

src/README.md

@@ -10,24 +10,28 @@ In all cases, build commands executed through `make` will output the object file
 
 ## FORTRAN code setup and execution (requires `gfortran` and GNU `make`)
 
-1. cd to the `src` folder
-2. run `make`
+1. cd to the `src` folder.
+2. Run `make` as:
 
    > make
 
-3. cd to the `build/sphere` folder
-4. run `sph` following the instructions given in `build\README.md`
+3. cd to the `build/sphere` folder.
+4. Run `sph` following the instructions given in `build\README.md`
+3. cd to the `build/cluster` folder.
+4. Run `clu` following the instructions given in `build\README.md`
 
 ## C++ code setup and execution (requires `g++` and GNU `make`)
 
-1. cd to the `src` folder
-2. run `make np_sphere`
+1. Follow the FORTRAN code setup steps (this builds the C++ version too).
+2. cd to the `build/sphere` folder.
+3. run `np_sphere`:
 
-   > make np_sphere
+   > ./np_sphere
 
-3. cd to the `build/sphere` folder
-4. run `np_sphere`
+4. Check the consistency between the text files named `OSPH` and `c_OSPH`
+5. cd to the `build/cluster` folder.
+6. Run `np_cluster`:
 
-   > ./np_sphere
+   > ./np_cluster
 
-5. check the consistency between the text files named `OSPH` and `c_OSPH`
+7. Check the consistency between the text files named `OCLU` and `c_OCLU`

src/scripts/README.md

+# Folder instructions
+
+This directory contains scripts and tools to evaluate the code functionality.
+
+## Instructions
+
+The code migration stage can be considered successfully fulfilled with the solution of the single sphere and of the cluster of spheres cases in C++. To test the reliability of the code, the C++ version needs to produce consistent output with respect to the original FORTRAN code. Since the output files are generally too large for manual inspection and they can be affected by different approximations or numeric noise, a series of scripts designed to compare the two versions and to pin-point possible differences is provided in this folder. The scripts are written in *python*, therefore they need an available *python* environment to work.
+
+## Comparing the results of FORTRAN and C++ codes
+
+1. Follow the instructions to build and run the FORTRAN and C++ versions of the code.
+2. Run the `pycompare.py` script providing the following minimal arguments:
+
+   > $PATH_TO_SCRIPT/pycompare.py --ffile=FORTRAN_OUTPUT --cfile=C++_OUTPUT
+
+(The above assumes that `PATH_TO_SCRIPT` is a variable that expands to the path were the script is located). The required output files are called by default `OSPH` and `OCLU` by FORTRAN and `c_OSPH` and `c_OCLU` by C++, depending on whether the sphere or the cluster case was executed. 
+4. Check the output of the script to verify that it detects 0 errors and finishes in a `SUCCESS` state.
+5. In case of need, add the `--html` argument to produce an *HTML* log showing the possible differences and a classification of their severity.
+6. Issuing:
+
+   > $PATH_TO_SCRIPT/pycompare.py --help
+
+or just:
+
+   > $PATH_TO_SCRIPT/pycompare.py
+
+will print a help screen, giving a brief explanation of all the possible options.
\ No newline at end of file