Update README instructions and credit information

README.md

@@ -6,7 +6,12 @@ The aim of the project, funded by PNRR-CNS, is to refactor the original, very ol
 
 The current implementation offers a set of elementary tests to check that the original FORTRAN code can be compiled and executed on a limited set of pre-defined input data. The functionality of this initial stage can be verified by cloning the gitLab repository on a local machine and building the binaries from the `src` folder.
 
-*NOTE:* The building process requires a working installation of the GNU Compiler Collection (`gcc`), of the GNU FORTRAN compiler (`gfortran`) and of the GNU `make` builder.
+Distributing the code and its sources is possible under the terms of the GNU GPLv3 license (see *License* below). Use of this code and of any derived implementation should credit the original authors. Scientific publications should do so by citing the following references:
+
+- Saija et al. 2001, ApJ, 559, 993, DOI:10.1086/322350
+- Borghese, Denti, Saija 2007, Scattering from Model Nonspherical Particles (ISBN 978-3-540-37413-8), DOI:10.1007/978-3-540-37414-5
+
+*NOTE:* The building process requires a working installation of a C++ and a FORTRAN compiler. Many solutions are available, but the recommended option is the *GNU Compiler Collection* `gcc` with the addition of `g++` and `gfortran`. The parallel code implementation further requires the use of parallel compilers complying with the MPI standard (*OpenMPI*, *MPICH*).
 
 # License
 

build/README.md

 # Folder instructions
+This directory contains the configuration and building system.
 
-This directory collects all the output of make builds.
+## Instructions
+The set-up and building process of *NP_TMcode* is based on tha automatic detection of the system capabilities, through an *autoconf* generated `configure` script. In case the user wants to override the default configuration, several options are available to modify the configuration behaviour. Use:
 
-## Developing notes
+   > ./configure --help
 
-The configurable version of the package introduces some execution wrappers. These raise no problems on a normal execution work-flow, but they affect debug executions. The correct way to perform a debug run, therefore, is to enter the folder where the executable program is and then issue:
+to obtain a list of the available configuration options. We refer to the code inline documentation and to the PDF release notes of the distribution for advanced instructions on code set up and execution. In the following sections, we give instructions for a simple installation and some elementary tests.
 
-   > ../libtool --mode=execute DEBUGGER_NAME EXECUTABLE_NAME
+Use of this code and of any derived implementation should credit the original authors. Scientific publications should do so by citing the following references:
 
-where `DEBUGGER_NAME` is the preferred debugger (e.g. `gdb`, `ddd` ...) and `EXECUTABLE_NAME` is the program to be debugged.
+- Saija et al. 2001, ApJ, 559, 993, DOI:10.1086/322350
+- Borghese, Denti, Saija 2007, Scattering from Model Nonspherical Particles (ISBN 978-3-540-37413-8), DOI:10.1007/978-3-540-37414-5
 
-## Instructions (deprecated)
+## Installation
+The proper way to install the code and execute it is based on pre-configured builds handled by *GNU make*. To install the code on your local machine, you should enter the `build` folder and issue:
 
-The original code produces output in the current working directory (the path where the code is executed from). The build directory is intended to collect local builds and test run output in a safe place, without cluttering the code development folders, thus helping `git` to filter out unnecessary logs through `.gitignore`.
+   > ./configure [CONFIGURE_OPTIONS]
+
+where `CONFIGURE_OPTIONS` are optional arguments used to enable and disable specific code features, such as parallel implementation and GPU offload of calculations. These features are enabled by default, if the local system has the hardware and software ability to support them. See the help pages of the `configure` script for more details on the available optional features.
 
 ## Code work-flow
+The original code produces output in the current working directory (the path where the code is executed from). The build directory is intended to collect local builds and test run output in a safe place, without cluttering the code development folders, thus keeping the source folders as clean as possible.
 
-This section describes the use of the pre-existing programs, once the binaries have been properly built by a succesful run of `make` in the `src` folder.
+This section describes the use of the single programs that make up the *NP_TMcode* suite, once the binaries have been properly built.
 
-*NOTE:* This set of instructions applies to the serial code implementation only. Please, refer to the Release Notes of `NP_TMcode-M8.02` for more details on how to build and use a parallel implementation of the code.
+*NOTE:* This set of instructions applies to the serial code implementation only. Please, refer to the Release Notes of `NP_TMcode-M8.03` for more details on how to build and use a parallel implementation of the code.
 
 ### cluster
 
@@ -88,7 +95,7 @@ The execution of trapping programs requires at least one of the previous program
 
 ### 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:
+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_ format 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 types of files, the `testing` suite provides two programs:
 
 - `test_TEDF`
 
@@ -104,7 +111,7 @@ This program checks for the consistency of transition matrix data files. It is e
 
 > ./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.
+where the arguments must be valid paths to binary transition matrix files saved in the legacy 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.
 
 # License
 

src/README.md

@@ -4,39 +4,12 @@ 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`. 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.
+This folder is intended to store the sources of the original code and the C++ implementation of the project. Distributing and changing the source is possible under the terms of the GNU GPLv3 license (see *License* below). Use of this code and of any derived implementation should credit the original authors. Scientific publications should do so by citing the following references:
 
-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.
+- Saija et al. 2001, ApJ, 559, 993, DOI:10.1086/322350
+- Borghese, Denti, Saija 2007, Scattering from Model Nonspherical Particles (ISBN 978-3-540-37413-8), DOI:10.1007/978-3-540-37414-5
 
-## *FORTRAN* code setup and execution (requires `gfortran` and GNU `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`
-5. cd to the `build/cluster` folder.
-6. Run `clu` following the instructions given in `build/README.md`
-
-## *C++* code setup and execution (requires `g++` and GNU `make`)
-
-*NOTE:* This set of instructions is for serial code implementation only. Please, refer to the Release Notes of `NP_TMcode-M8.02` for more details on how to build and use a parallel implementation of the code.
-
-1. Follow the *FORTRAN* code setup steps (these build the *C++* version too).
-2. cd to the `build/sphere` folder.
-3. Run `np_sphere`:
-
-   > ./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_cluster
-
-7. Check the consistency between the text files named `OCLU` and `c_OCLU`
+Instructions on how to set up and use the code are instead given in the project's `build` folder.
 
 # License