Merge branch 'prepare_autoconf' into 'master'

Configuration script

Closes #13

See merge request giacomo.mulas/np_tmcode!51

.gitignore

-build/include
+build/aclocal.m4
+build/autom4te.cache
+build/config.*
 build/cluster/*
+build/error.log
+build/libtool
+build/Makefile
 build/sphere/*
 build/testing/*
 build/trapping/*
 build/libnptm/*
 containers/singularity/*.sif
 doc/build/*
-src/*/objects/*
-src/*/dynobjects/*
+src/libnptm/.libs
+src/libnptm/*.lo
+src/*/.deps
+src/*/.dirstamp
+src/*/*.o
\ No newline at end of file

.gitlab-ci.yml

@@ -29,11 +29,7 @@ compatibility_stage:
    allow_failure: true
    artifacts:
       paths:
-         - build/cluster/*
-         - build/sphere/*
-         - build/testing/*
-         - build/trapping/*
-         - build/libnptm/*
+         - build_*
       exclude:
          - ".git*"
          - ".git/**/*"
@@ -46,25 +42,80 @@ compatibility_stage:
       - echo $CI_COMMIT_BRANCH
       - echo "Getting system info ..."
       - cat /etc/os-release
-      - cd src
       - echo "Running make with gnu compilers version 11..."
-      - make clean && BUILDDIR=$PWD/../build_gnu11 CXX=g++-11 FC=gfortran-11 make -j
+      - mkdir build_gnu11
+      - cd build_gnu11
+      - cp -r ../build/* .
+      - CXX=g++-11 F77=gfortran-11 ./configure
+      - make clean
+      - make -j
       - echo "Running make with gnu compilers version 12..."
-      - make clean && BUILDDIR=$PWD/../build_gnu12 CXX=g++-12 FC=gfortran-12 make -j
+      - cd ..
+      - rm -rf build_gnu11
+      - mkdir build_gnu12
+      - cd build_gnu12
+      - cp -r ../build/* .
+      - CXX=g++-12 F77=gfortran-12 ./configure
+      - make clean
+      - make -j
       - echo "Running make with gnu compilers version 13..."
-      - make clean && BUILDDIR=$PWD/../build_gnu13 CXX=g++-13 FC=gfortran-13 make -j
+      - cd ..
+      - rm -rf build_gnu12
+      - mkdir build_gnu13
+      - cd build_gnu13
+      - cp -r ../build/* .
+      - CXX=g++-13 F77=gfortran-13 ./configure
+      - make clean
+      - make -j
       - echo "Running make with gnu compilers version 14..."
-      - make clean && BUILDDIR=$PWD/../build_gnu14 CXX=g++-14 FC=gfortran-14 make -j
+      - cd ..
+      - rm -rf build_gnu13
+      - mkdir build_gnu14
+      - cd build_gnu14
+      - cp -r ../build/* .
+      - CXX=g++-14 F77=gfortran-14 ./configure
+      - make clean
+      - make -j
       - echo "Running make with flang version 16 and clang version 16..."
-      - make clean && BUILDDIR=$PWD/../build_clang16 CXX="clang++-16 -stdlib=libstdc++ -I/usr/include/c++/13 -I/usr/include/x86_64-linux-gnu/c++/13" FC=flang-new-16 FCFLAGS=-O3 LDFLAGS="-L/usr/lib/llvm-16/lib -L/usr/lib/gcc/x86_64-linux-gnu/13" make -j
+      - cd ..
+      - rm -rf build_gnu14
+      - mkdir build_clang16
+      - cd build_clang16
+      - cp -r ../build/* .
+      - CXX=clang++-16 F77=flang-new-16 ./configure --with-fflags="-O3" --with-include="-I/usr/include/c++/13 -I/usr/include/x86_64-linux-gnu/c++/13" --with-ldflags="-L/usr/lib/llvm-16/lib -L/usr/lib/gcc/x86_64-linux-gnu/13" --disable-openmp
+      - make clean
+      - make -j
       - echo "Running make with flang version 17 and clang version 17..."
-      - make clean && BUILDDIR=$PWD/../build_clang17 CXX="clang++-17 -stdlib=libstdc++ -I/usr/include/c++/13 -I/usr/include/x86_64-linux-gnu/c++/13" FC=flang-new-17 FCFLAGS=-O3 LDFLAGS="-L/usr/lib/llvm-17/lib -L/usr/lib/gcc/x86_64-linux-gnu/13" make -j
+      - cd ..
+      - rm -rf build_clang16
+      - mkdir build_clang17
+      - cd build_clang17
+      - cp -r ../build/* .
+      - CXX=clang++-17 F77=flang-new-17 ./configure --with-fflags="-O3" --with-include="-I/usr/include/c++/13 -I/usr/include/x86_64-linux-gnu/c++/13" --with-ldflags="-L/usr/lib/llvm-17/lib -L/usr/lib/gcc/x86_64-linux-gnu/13"  --disable-openmp
+      - make clean
+      - make -j
       - echo "Running make with Intel ifort and Intel icpx..."
-      - make clean && LD_LIBRARY_PATH=/opt/intel/oneapi/compiler/2024.2/lib PATH=/opt/intel/oneapi/compiler/2024.2/bin:$PATH BUILDDIR=$PWD/../build_ifort-icpx CXX=icpx FC=ifort FCFLAGS="-O3 -diag-disable=10448" make -j
+      - cd ..
+      - rm -rf build_clang17
+      - mkdir build_ifort_icpx
+      - cd build_ifort_icpx
+      - cp -r ../build/* .
+      - export LD_LIBRARY_PATH=/opt/intel/oneapi/compiler/2024.2/lib
+      - export PATH=/opt/intel/oneapi/compiler/2024.2/bin:$PATH
+      - CXX=icpx F77=ifort ./configure --with-fflags="-O3 -diag-disable=10448" --disable-openmp
+      - make clean
+      - make -j
       - echo "Running make with Intel ifx and Intel icpx..."
-      - make clean && LD_LIBRARY_PATH=/opt/intel/oneapi/compiler/2024.2/lib PATH=/opt/intel/oneapi/compiler/2024.2/bin:$PATH BUILDDIR=$PWD/../build_ifx-icpx CXX=icpx FC=ifx FCFLAGS=-O3 make -j
-      - echo "Running make with default MPI compilers"
-      - make clean && BUILDDIR=$PWD/../build_mpi CXX=mpicxx FC=mpif90 USE_MPI=1 make -j
+      - cd ..
+      - rm -rf build_ifort_icpx
+      - mkdir build_ifx_icpx
+      - cd build_ifx_icpx
+      - cp -r ../build/* .
+      - export LD_LIBRARY_PATH=/opt/intel/oneapi/compiler/2024.2/lib
+      - export PATH=/opt/intel/oneapi/compiler/2024.2/bin:$PATH
+      - CXX=icpx F77=ifx ./configure --with-fflags="-O3" --disable-openmp
+      - make clean
+      - make -j
    
 building_stage:
    stage: build
@@ -90,10 +141,17 @@ building_stage:
       - echo $CI_COMMIT_BRANCH
       - echo "Getting system info ..."
       - cat /etc/os-release
-      - cd src
-      - echo "Running make with default compilers..."
-      - make clean && USE_LAPACK=1 USE_ILP64=1 make -j
-      - make docs -j && make -C ../doc/build/latex -j
+      - cd build
+      - echo "Configuring with default compilers (MAGMA disabled)..."
+      - ./configure --without-magma
+      - make clean
+      - echo "Building the default configuration..."
+      - make -j
+      - echo "Building the documentation..."
+      - cd ../doc/src
+      - doxygen config.dox
+      - cd ../build/latex
+      - make
 
 running_stage:
    stage: run
@@ -125,7 +183,7 @@ running_stage:
       - cd ../cluster
       - echo "Running np_cluster"
       - chmod +x np_cluster
-      - ./np_cluster
+      - OMP_NUM_THREADS=1 ./np_cluster
       
 testing_stage:
    stage: test
@@ -162,7 +220,7 @@ testing_stage:
       - export FFILE=../../test_data/cluster/OCLU
       - python3 ../../src/scripts/pycompare.py --no-progress --ffile=$FFILE --cfile=c_OCLU --html
       - echo "Testing cluster with 24 spheres"
-      - ./np_cluster ../../test_data/cluster/DEDFB_24 ../../test_data/cluster/DCLU_24 .
+      - OMP_NUM_THREADS=1 OMPI_ALLOW_RUN_AS_ROOT=1 OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1 mpirun -n 2 ./np_cluster ../../test_data/cluster/DEDFB_24 ../../test_data/cluster/DCLU_24 .
       - echo "Comparing output of CLUSTER with 24 spheres"
       - export FFILE=../../test_data/cluster/OCLU_24
       - python3 ../../src/scripts/pycompare.py --no-progress --ffile=$FFILE --cfile=c_OCLU --html

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/Makefile.am

+LDADD=libnptm/libnptm.la -L/usr/lib64 ${USER_LDFLAGS} ${HDF5_LDFLAGS} ${LAPACKLDFLAGS} ${MAGMALDFLAGS}
+lib_LTLIBRARIES=libnptm/libnptm.la
+libnptm_libnptm_la_SOURCES=../src/libnptm/algebraic.cpp ../src/libnptm/clu_subs.cpp ../src/libnptm/Commons.cpp ../src/libnptm/Configuration.cpp ../src/libnptm/file_io.cpp ../src/libnptm/lapack_calls.cpp ../src/libnptm/logging.cpp ../src/libnptm/magma_calls.cpp ../src/libnptm/Parsers.cpp ../src/libnptm/sph_subs.cpp ../src/libnptm/tfrfme.cpp ../src/libnptm/TransitionMatrix.cpp ../src/libnptm/tra_subs.cpp ../src/libnptm/types.cpp
+bin_PROGRAMS=cluster/edfb_clu cluster/clu cluster/np_cluster sphere/edfb_sph sphere/sph sphere/np_sphere trapping/frfme trapping/lffft trapping/np_trapping testing/test_TEDF testing/test_TTMS
+cluster_edfb_clu_SOURCES=../src/cluster/edfb_clu.f
+cluster_clu_SOURCES=../src/cluster/clu.f
+cluster_np_cluster_SOURCES=../src/cluster/np_cluster.cpp ../src/cluster/cluster.cpp
+sphere_edfb_sph_SOURCES=../src/sphere/edfb_sph.f
+sphere_sph_SOURCES=../src/sphere/sph.f
+sphere_np_sphere_SOURCES=../src/sphere/np_sphere.cpp ../src/sphere/sphere.cpp
+trapping_frfme_SOURCES=../src/trapping/frfme.f
+trapping_lffft_SOURCES=../src/trapping/lffft.f
+trapping_np_trapping_SOURCES=../src/trapping/np_trapping.cpp ../src/trapping/cfrfme.cpp ../src/trapping/clffft.cpp
+testing_test_TEDF_SOURCES=../src/testing/test_TEDF.cpp
+testing_test_TTMS_SOURCES=../src/testing/test_TTMS.cpp

build/README.md

 # Folder instructions
-
-This directory collects all the output of make builds.
+This directory contains the configuration and building system.
 
 ## 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:
+
+   > ./configure --help
+
+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.
+
+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
+
+## 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:
+
+   > ./configure [CONFIGURE_OPTIONS]
 
-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`.
+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
 
@@ -80,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`
 
@@ -96,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
 

build/build_aux/ar-lib

+#! /bin/sh
+# Wrapper for Microsoft lib.exe
+
+me=ar-lib
+scriptversion=2019-07-04.01; # UTC
+
+# Copyright (C) 2010-2021 Free Software Foundation, Inc.
+# Written by Peter Rosin <peda@lysator.liu.se>.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+# As a special exception to the GNU General Public License, if you
+# distribute this file as part of a program that contains a
+# configuration script generated by Autoconf, you may include it under
+# the same distribution terms that you use for the rest of that program.
+
+# This file is maintained in Automake, please report
+# bugs to <bug-automake@gnu.org> or send patches to
+# <automake-patches@gnu.org>.
+
+
+# func_error message
+func_error ()
+{
+  echo "$me: $1" 1>&2
+  exit 1
+}
+
+file_conv=
+
+# func_file_conv build_file
+# Convert a $build file to $host form and store it in $file
+# Currently only supports Windows hosts.
+func_file_conv ()
+{
+  file=$1
+  case $file in
+    / | /[!/]*) # absolute file, and not a UNC file
+      if test -z "$file_conv"; then
+	# lazily determine how to convert abs files
+	case `uname -s` in
+	  MINGW*)
+	    file_conv=mingw
+	    ;;
+	  CYGWIN* | MSYS*)
+	    file_conv=cygwin
+	    ;;
+	  *)
+	    file_conv=wine
+	    ;;
+	esac
+      fi
+      case $file_conv in
+	mingw)
+	  file=`cmd //C echo "$file " | sed -e 's/"\(.*\) " *$/\1/'`
+	  ;;
+	cygwin | msys)
+	  file=`cygpath -m "$file" || echo "$file"`
+	  ;;
+	wine)
+	  file=`winepath -w "$file" || echo "$file"`
+	  ;;
+      esac
+      ;;
+  esac
+}
+
+# func_at_file at_file operation archive
+# Iterate over all members in AT_FILE performing OPERATION on ARCHIVE
+# for each of them.
+# When interpreting the content of the @FILE, do NOT use func_file_conv,
+# since the user would need to supply preconverted file names to
+# binutils ar, at least for MinGW.
+func_at_file ()
+{
+  operation=$2
+  archive=$3
+  at_file_contents=`cat "$1"`
+  eval set x "$at_file_contents"
+  shift
+
+  for member
+  do
+    $AR -NOLOGO $operation:"$member" "$archive" || exit $?
+  done
+}
+
+case $1 in
+  '')
+     func_error "no command.  Try '$0 --help' for more information."
+     ;;
+  -h | --h*)
+    cat <<EOF
+Usage: $me [--help] [--version] PROGRAM ACTION ARCHIVE [MEMBER...]
+
+Members may be specified in a file named with @FILE.
+EOF
+    exit $?
+    ;;
+  -v | --v*)
+    echo "$me, version $scriptversion"
+    exit $?
+    ;;
+esac
+
+if test $# -lt 3; then
+  func_error "you must specify a program, an action and an archive"
+fi
+
+AR=$1
+shift
+while :
+do
+  if test $# -lt 2; then
+    func_error "you must specify a program, an action and an archive"
+  fi
+  case $1 in
+    -lib | -LIB \
+    | -ltcg | -LTCG \
+    | -machine* | -MACHINE* \
+    | -subsystem* | -SUBSYSTEM* \
+    | -verbose | -VERBOSE \
+    | -wx* | -WX* )
+      AR="$AR $1"
+      shift
+      ;;
+    *)
+      action=$1
+      shift
+      break
+      ;;
+  esac
+done
+orig_archive=$1
+shift
+func_file_conv "$orig_archive"
+archive=$file
+
+# strip leading dash in $action
+action=${action#-}
+
+delete=
+extract=
+list=
+quick=
+replace=
+index=
+create=
+
+while test -n "$action"
+do
+  case $action in
+    d*) delete=yes  ;;
+    x*) extract=yes ;;
+    t*) list=yes    ;;
+    q*) quick=yes   ;;
+    r*) replace=yes ;;
+    s*) index=yes   ;;
+    S*)             ;; # the index is always updated implicitly
+    c*) create=yes  ;;
+    u*)             ;; # TODO: don't ignore the update modifier
+    v*)             ;; # TODO: don't ignore the verbose modifier
+    *)
+      func_error "unknown action specified"
+      ;;
+  esac
+  action=${action#?}
+done
+
+case $delete$extract$list$quick$replace,$index in
+  yes,* | ,yes)
+    ;;
+  yesyes*)
+    func_error "more than one action specified"
+    ;;
+  *)
+    func_error "no action specified"
+    ;;
+esac
+
+if test -n "$delete"; then
+  if test ! -f "$orig_archive"; then
+    func_error "archive not found"
+  fi
+  for member
+  do
+    case $1 in
+      @*)
+        func_at_file "${1#@}" -REMOVE "$archive"
+        ;;
+      *)
+        func_file_conv "$1"
+        $AR -NOLOGO -REMOVE:"$file" "$archive" || exit $?
+        ;;
+    esac
+  done
+
+elif test -n "$extract"; then
+  if test ! -f "$orig_archive"; then
+    func_error "archive not found"
+  fi
+  if test $# -gt 0; then
+    for member
+    do
+      case $1 in
+        @*)
+          func_at_file "${1#@}" -EXTRACT "$archive"
+          ;;
+        *)
+          func_file_conv "$1"
+          $AR -NOLOGO -EXTRACT:"$file" "$archive" || exit $?
+          ;;
+      esac
+    done
+  else
+    $AR -NOLOGO -LIST "$archive" | tr -d '\r' | sed -e 's/\\/\\\\/g' \
+      | while read member
+        do
+          $AR -NOLOGO -EXTRACT:"$member" "$archive" || exit $?
+        done
+  fi
+
+elif test -n "$quick$replace"; then
+  if test ! -f "$orig_archive"; then
+    if test -z "$create"; then
+      echo "$me: creating $orig_archive"
+    fi
+    orig_archive=
+  else
+    orig_archive=$archive
+  fi
+
+  for member
+  do
+    case $1 in
+    @*)
+      func_file_conv "${1#@}"
+      set x "$@" "@$file"
+      ;;
+    *)
+      func_file_conv "$1"
+      set x "$@" "$file"
+      ;;
+    esac
+    shift
+    shift
+  done
+
+  if test -n "$orig_archive"; then
+    $AR -NOLOGO -OUT:"$archive" "$orig_archive" "$@" || exit $?
+  else
+    $AR -NOLOGO -OUT:"$archive" "$@" || exit $?
+  fi
+
+elif test -n "$list"; then
+  if test ! -f "$orig_archive"; then
+    func_error "archive not found"
+  fi
+  $AR -NOLOGO -LIST "$archive" || exit $?
+fi

build/build_aux/compile

+#! /bin/sh
+# Wrapper for compilers which do not understand '-c -o'.
+
+scriptversion=2018-03-07.03; # UTC
+
+# Copyright (C) 1999-2021 Free Software Foundation, Inc.
+# Written by Tom Tromey <tromey@cygnus.com>.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+# As a special exception to the GNU General Public License, if you
+# distribute this file as part of a program that contains a
+# configuration script generated by Autoconf, you may include it under
+# the same distribution terms that you use for the rest of that program.
+
+# This file is maintained in Automake, please report
+# bugs to <bug-automake@gnu.org> or send patches to
+# <automake-patches@gnu.org>.
+
+nl='
+'
+
+# We need space, tab and new line, in precisely that order.  Quoting is
+# there to prevent tools from complaining about whitespace usage.
+IFS=" ""	$nl"
+
+file_conv=
+
+# func_file_conv build_file lazy
+# Convert a $build file to $host form and store it in $file
+# Currently only supports Windows hosts. If the determined conversion
+# type is listed in (the comma separated) LAZY, no conversion will
+# take place.
+func_file_conv ()
+{
+  file=$1
+  case $file in
+    / | /[!/]*) # absolute file, and not a UNC file
+      if test -z "$file_conv"; then
+	# lazily determine how to convert abs files
+	case `uname -s` in
+	  MINGW*)
+	    file_conv=mingw
+	    ;;
+	  CYGWIN* | MSYS*)
+	    file_conv=cygwin
+	    ;;
+	  *)
+	    file_conv=wine
+	    ;;
+	esac
+      fi
+      case $file_conv/,$2, in
+	*,$file_conv,*)
+	  ;;
+	mingw/*)
+	  file=`cmd //C echo "$file " | sed -e 's/"\(.*\) " *$/\1/'`
+	  ;;
+	cygwin/* | msys/*)
+	  file=`cygpath -m "$file" || echo "$file"`
+	  ;;
+	wine/*)
+	  file=`winepath -w "$file" || echo "$file"`
+	  ;;
+      esac
+      ;;
+  esac
+}
+
+# func_cl_dashL linkdir
+# Make cl look for libraries in LINKDIR
+func_cl_dashL ()
+{
+  func_file_conv "$1"
+  if test -z "$lib_path"; then
+    lib_path=$file
+  else
+    lib_path="$lib_path;$file"
+  fi
+  linker_opts="$linker_opts -LIBPATH:$file"
+}
+
+# func_cl_dashl library
+# Do a library search-path lookup for cl
+func_cl_dashl ()
+{
+  lib=$1
+  found=no
+  save_IFS=$IFS
+  IFS=';'
+  for dir in $lib_path $LIB
+  do
+    IFS=$save_IFS
+    if $shared && test -f "$dir/$lib.dll.lib"; then
+      found=yes
+      lib=$dir/$lib.dll.lib
+      break
+    fi
+    if test -f "$dir/$lib.lib"; then
+      found=yes
+      lib=$dir/$lib.lib
+      break
+    fi
+    if test -f "$dir/lib$lib.a"; then
+      found=yes
+      lib=$dir/lib$lib.a
+      break
+    fi
+  done
+  IFS=$save_IFS
+
+  if test "$found" != yes; then
+    lib=$lib.lib
+  fi
+}
+
+# func_cl_wrapper cl arg...
+# Adjust compile command to suit cl
+func_cl_wrapper ()
+{
+  # Assume a capable shell
+  lib_path=
+  shared=:
+  linker_opts=
+  for arg
+  do
+    if test -n "$eat"; then
+      eat=
+    else
+      case $1 in
+	-o)
+	  # configure might choose to run compile as 'compile cc -o foo foo.c'.
+	  eat=1
+	  case $2 in
+	    *.o | *.[oO][bB][jJ])
+	      func_file_conv "$2"
+	      set x "$@" -Fo"$file"
+	      shift
+	      ;;
+	    *)
+	      func_file_conv "$2"
+	      set x "$@" -Fe"$file"
+	      shift
+	      ;;
+	  esac
+	  ;;
+	-I)
+	  eat=1
+	  func_file_conv "$2" mingw
+	  set x "$@" -I"$file"
+	  shift
+	  ;;
+	-I*)
+	  func_file_conv "${1#-I}" mingw
+	  set x "$@" -I"$file"
+	  shift
+	  ;;
+	-l)
+	  eat=1
+	  func_cl_dashl "$2"
+	  set x "$@" "$lib"
+	  shift
+	  ;;
+	-l*)
+	  func_cl_dashl "${1#-l}"
+	  set x "$@" "$lib"
+	  shift
+	  ;;
+	-L)
+	  eat=1
+	  func_cl_dashL "$2"
+	  ;;
+	-L*)
+	  func_cl_dashL "${1#-L}"
+	  ;;
+	-static)
+	  shared=false
+	  ;;
+	-Wl,*)
+	  arg=${1#-Wl,}
+	  save_ifs="$IFS"; IFS=','
+	  for flag in $arg; do
+	    IFS="$save_ifs"
+	    linker_opts="$linker_opts $flag"
+	  done
+	  IFS="$save_ifs"
+	  ;;
+	-Xlinker)
+	  eat=1
+	  linker_opts="$linker_opts $2"
+	  ;;
+	-*)
+	  set x "$@" "$1"
+	  shift
+	  ;;
+	*.cc | *.CC | *.cxx | *.CXX | *.[cC]++)
+	  func_file_conv "$1"
+	  set x "$@" -Tp"$file"
+	  shift
+	  ;;
+	*.c | *.cpp | *.CPP | *.lib | *.LIB | *.Lib | *.OBJ | *.obj | *.[oO])
+	  func_file_conv "$1" mingw
+	  set x "$@" "$file"
+	  shift
+	  ;;
+	*)
+	  set x "$@" "$1"
+	  shift
+	  ;;
+      esac
+    fi
+    shift
+  done
+  if test -n "$linker_opts"; then
+    linker_opts="-link$linker_opts"
+  fi
+  exec "$@" $linker_opts
+  exit 1
+}
+
+eat=
+
+case $1 in
+  '')
+     echo "$0: No command.  Try '$0 --help' for more information." 1>&2
+     exit 1;
+     ;;
+  -h | --h*)
+    cat <<\EOF
+Usage: compile [--help] [--version] PROGRAM [ARGS]
+
+Wrapper for compilers which do not understand '-c -o'.
+Remove '-o dest.o' from ARGS, run PROGRAM with the remaining
+arguments, and rename the output as expected.
+
+If you are trying to build a whole package this is not the
+right script to run: please start by reading the file 'INSTALL'.
+
+Report bugs to <bug-automake@gnu.org>.
+EOF
+    exit $?
+    ;;
+  -v | --v*)
+    echo "compile $scriptversion"
+    exit $?
+    ;;
+  cl | *[/\\]cl | cl.exe | *[/\\]cl.exe | \
+  icl | *[/\\]icl | icl.exe | *[/\\]icl.exe )
+    func_cl_wrapper "$@"      # Doesn't return...
+    ;;
+esac
+
+ofile=
+cfile=
+
+for arg
+do
+  if test -n "$eat"; then
+    eat=
+  else
+    case $1 in
+      -o)
+	# configure might choose to run compile as 'compile cc -o foo foo.c'.
+	# So we strip '-o arg' only if arg is an object.
+	eat=1
+	case $2 in
+	  *.o | *.obj)
+	    ofile=$2
+	    ;;
+	  *)
+	    set x "$@" -o "$2"
+	    shift
+	    ;;
+	esac
+	;;
+      *.c)
+	cfile=$1
+	set x "$@" "$1"
+	shift
+	;;
+      *)
+	set x "$@" "$1"
+	shift
+	;;
+    esac
+  fi
+  shift
+done
+
+if test -z "$ofile" || test -z "$cfile"; then
+  # If no '-o' option was seen then we might have been invoked from a
+  # pattern rule where we don't need one.  That is ok -- this is a
+  # normal compilation that the losing compiler can handle.  If no
+  # '.c' file was seen then we are probably linking.  That is also
+  # ok.
+  exec "$@"
+fi
+
+# Name of file we expect compiler to create.
+cofile=`echo "$cfile" | sed 's|^.*[\\/]||; s|^[a-zA-Z]:||; s/\.c$/.o/'`
+
+# Create the lock directory.
+# Note: use '[/\\:.-]' here to ensure that we don't use the same name
+# that we are using for the .o file.  Also, base the name on the expected
+# object file name, since that is what matters with a parallel build.
+lockdir=`echo "$cofile" | sed -e 's|[/\\:.-]|_|g'`.d
+while true; do
+  if mkdir "$lockdir" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 1
+done
+# FIXME: race condition here if user kills between mkdir and trap.
+trap "rmdir '$lockdir'; exit 1" 1 2 15
+
+# Run the compile.
+"$@"
+ret=$?
+
+if test -f "$cofile"; then
+  test "$cofile" = "$ofile" || mv "$cofile" "$ofile"
+elif test -f "${cofile}bj"; then
+  test "${cofile}bj" = "$ofile" || mv "${cofile}bj" "$ofile"
+fi
+
+rmdir "$lockdir"
+exit $ret
+
+# Local Variables:
+# mode: shell-script
+# sh-indentation: 2
+# eval: (add-hook 'before-save-hook 'time-stamp)
+# time-stamp-start: "scriptversion="
+# time-stamp-format: "%:y-%02m-%02d.%02H"
+# time-stamp-time-zone: "UTC0"
+# time-stamp-end: "; # UTC"
+# End:

doc/src/README.md

@@ -4,15 +4,11 @@ This directory contains the material to build the project documentation with *do
 
 ## 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 `config.dox` file, specifically `np_tmcode/doc/src`) and finally run:
 
-> doxygen conf.dox
+> doxygen config.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`.
+*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`. If the host system has a recommended LaTeX installation, the full PDF documentation can be built with a further execution of `make` from the `np_tmcode/doc/build/latex` folder.
 
 # 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