@@ -27,9 +27,13 @@ This section describes the use of the pre-existing programs, once the binaries h
> ./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.
*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:
@@ -48,9 +52,13 @@ This section describes the use of the pre-existing programs, once the binaries h
> ./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.
*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`).
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
## 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:
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
```
`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`.
> doxygen conf.dox
No newline at end of file
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`.
@@ -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.
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.
1. cd to the `src` folder.
2. Run `make` as:
2. Run `make` as:
@@ -16,13 +16,13 @@ In all cases, build commands executed through `make` will output the object file
> make
> make
3. cd to the `build/sphere` folder.
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.
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).
@@ -4,19 +4,19 @@ This directory contains scripts and tools to evaluate the code functionality.
## Instructions
## 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:
2. Run the `pycompare.py` script providing the following minimal arguments:
(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.
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.
@@ -4,19 +4,46 @@ This directory collects the input files to test the code.
## Instructions
## 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
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
*TODO:* add the description of the cluster configuration files
### sphere
### 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:
