From 772eeb90af45019b10ef36e1d11703cfa427502b Mon Sep 17 00:00:00 2001
From: Giovanni La Mura <giovanni.lamura@inaf.it>
Date: Mon, 11 Dec 2023 16:40:22 +0100
Subject: [PATCH] Use standard format for mark-down README instructions
---
build/README.md | 16 ++++++++++++----
doc/src/README.md | 15 +++++++++------
src/README.md | 10 +++++-----
src/scripts/README.md | 10 +++++-----
test_data/README.md | 35 +++++++++++++++++++++++++++++++----
5 files changed, 62 insertions(+), 24 deletions(-)
diff --git a/build/README.md b/build/README.md
index 52dbdc33..012238bd 100644
--- a/build/README.md
+++ b/build/README.md
@@ -27,9 +27,13 @@ This section describes the use of the pre-existing programs, once the binaries h
> ./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.
+*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`).
+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`).
+
+The default behaviour of `np_cluster` is to take the same input files as `edfb` and `clu` and to write the output in the current folder. If needed, different input and output paths can be given as command-line arguments:
+
+ > ./np_cluster PATH_TO_DEDFB PATH_TO_DCLU OUTPUT_PATH
### sphere
@@ -48,9 +52,13 @@ This section describes the use of the pre-existing programs, once the binaries h
> ./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.
+*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`).
+
+The default behaviour of `np_sphere` is to take the same input files as `edfb` and `sph` and to write the output in the current folder. If needed, different input and output paths can be given as command-line arguments:
-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`).
+ > ./np_sphere PATH_TO_DEDFB PATH_TO_DSPH OUTPUT_PATH
### trapping
diff --git a/doc/src/README.md b/doc/src/README.md
index 42ef6f6c..94056c18 100644
--- a/doc/src/README.md
+++ b/doc/src/README.md
@@ -1,12 +1,15 @@
# Folder instructions
-This directory contains the material to build the project documentation with `doxygen`.
+This directory contains the material to build the project documentation with *doxygen*.
## Instructions
-The project documentation is managed by `doxygen`, a documentation generator that is able to extract documents directly from properly formatted comment sections of the source code. To build a local instance of project documents, make sure that you have `doxygen` installed, then `cd` into the document source folder (the folder containing the `conf.dox` file, specifically `np_tmcode/doc/src`) and finally run:
-```
-doxygen conf.dox
-```
+The project documentation is managed by *doxygen*, a documentation generator that is able to extract documents directly from properly formatted comment sections of the source code. To build a local instance of project documents, make sure that you have *doxygen* installed, then `cd` into the document source folder (the folder containing the `conf.dox` file, specifically `np_tmcode/doc/src`) and finally run:
-`doxygen` will automatically build the HTML structure to cover all the documented source code and it will additionally provide the fundamental structure to prepare a LaTeX formatted version of the documents. These two outputs will be placed, respectively, under the folders `np_tmcode/doc/build/html` and `np_tmcode/doc/build/latex`.
\ No newline at end of file
+> doxygen conf.dox
+
+Alternatively, you can use `make` from the project `src` folder (named `np_tmcode/src`) and just issue:
+
+> make docs
+
+*doxygen* will automatically build the HTML structure to cover all the documented source code and it will additionally provide the fundamental structure to prepare a LaTeX formatted version of the documents. These two outputs will be placed, respectively, under the folders `np_tmcode/doc/build/html` and `np_tmcode/doc/build/latex`.
\ No newline at end of file
diff --git a/src/README.md b/src/README.md
index 34b34c1d..6e7b540e 100644
--- a/src/README.md
+++ b/src/README.md
@@ -8,7 +8,7 @@ The original code is contained in the folders named `cluster`, `sphere` and `tra
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.
-## FORTRAN code setup and execution (requires `gfortran` and GNU `make`)
+## *FORTRAN* code setup and execution (requires `gfortran` and GNU `make`)
1. cd to the `src` folder.
2. Run `make` as:
@@ -16,13 +16,13 @@ In all cases, build commands executed through `make` will output the object file
> make
3. cd to the `build/sphere` folder.
-4. Run `sph` following the instructions given in `build\README.md`
+4. Run `sph` following the instructions given in `build/README.md`
5. cd to the `build/cluster` folder.
-6. Run `clu` following the instructions given in `build\README.md`
+6. Run `clu` following the instructions given in `build/README.md`
-## C++ code setup and execution (requires `g++` and GNU `make`)
+## *C++* code setup and execution (requires `g++` and GNU `make`)
-1. Follow the FORTRAN code setup steps (this builds the C++ version too).
+1. Follow the *FORTRAN* code setup steps (these build the *C++* version too).
2. cd to the `build/sphere` folder.
3. Run `np_sphere`:
diff --git a/src/scripts/README.md b/src/scripts/README.md
index b3babd3e..b865eaca 100644
--- a/src/scripts/README.md
+++ b/src/scripts/README.md
@@ -4,19 +4,19 @@ 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.
+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
+## Comparing the results of *FORTRAN* and *C++* codes
-1. Follow the instructions to build and run the FORTRAN and C++ versions of the code.
+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.
+(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.
3. Check the output of the script to verify that it detects 0 errors and finishes in a `SUCCESS` state.
-4. In case of need, add the `--html` argument to produce an *HTML* log showing the possible differences and a classification of their severity.
+4. In case of necessity, add the `--html` argument to produce an *HTML* log showing the possible differences and a classification of their severity.
5. Issuing:
> $PATH_TO_SCRIPT/pycompare.py --help
diff --git a/test_data/README.md b/test_data/README.md
index d6f22fda..b075b9e1 100644
--- a/test_data/README.md
+++ b/test_data/README.md
@@ -4,19 +4,46 @@ This directory collects the input files to test the code.
## Instructions
-The execution of the original code can be controlled through a set of configuration files that define the characteristics of the problem and affect the type of output. The following sections describe the contents of the configuration files and, to some extent, thos of the output ones, presenting one code in each section.
+The execution of the original code can be controlled through a set of configuration files that define the characteristics of the problem and affect the type of output. The following sections describe the contents of the configuration files and, to some extent, those of the output ones, presenting one code in each section.
### cluster
-cluster is designed to calculate a complex geometry made up by many spheres. These can be either fully embedded in a larger sphere or separated within the external medium. Sphere compenetration is not accounted for.
+`clu` is designed to calculate a complex geometry made up by many spheres. These can be either fully embedded in a larger sphere or separated within the external medium. Sphere compenetration is not accounted for.
*TODO:* add the description of the cluster configuration files
### sphere
-sphere is designed to perform the simplest case calculation, namely the scattering of incident radiation on a single sphere. To perform the calculation, the two following formatted files need to be provided:
+`sph` is designed to perform the simplest case calculation, namely the scattering of incident radiation on a single sphere. To perform the calculation, the two following formatted files need to be provided:
-*TODO:* write the the DEDFB documentation
+- DEDFB
+```
+ SPHERE_NUMBER EXTERNAL_SPHERE_FLAG
+ EXT_DIEL_CONST PEAK_WAVE PEAK_SCALE DIEL_TYPE SCALE_NUMBER SCALE_STEP_FLAG CONTROL_VARIABLE
+ SCALE_VECTOR [SCALE_VECTOR_STEP]
+ |
+ v
+ SPHERE_ID_VECTOR ->
+ LAYER_NUMBER_VECTOR SPHERE_RADII_VECTOR
+ | |
+ v v
+ FRACTIONAL_BREAK_RADII ->
+ |
+ v
+ DIEL_CONST_VECTOR ->
+ |
+ v
+ EOF_CODE
+```
+were the different lines have the following roles:
+1. declare the number of spheres and whether to add an external layer
+2. define the external dielectric constant and the scaling configuration
+3. define the vector of scales (either explicitly, with one element per row, or in steps, with only first element and step declared)
+4. create a vector of IDs to attach to the spheres
+5. define the vectors spcifying the number of layers and the radii of the spheres (one sphere per line)
+6. define the fractional break radii (one line per sphere, one column per layer)
+7. define the vector of dielectric constants or starting functions (one line per sphere, one column per layer)
+8. an end-of-file code (generally 0)
- DSPH
```
--
GitLab