Merge pull request #333 from DrylandEcology/feature_restructure

Feature restructure

- close #89 

- new folder organization with
    - bin
    - build
        - sw2
        - test
    - include
    - external
        - googletest
        - pcg
    - src
    - tests
        - example
        - gtests
    - tools

.github/workflows/check_doc.yml

@@ -24,4 +24,4 @@ jobs:
         sudo apt-get install doxygen doxygen-latex graphviz
 
     - name: Build documentation and check for warnings
-      run: make clean doc
+      run: make clean clean_doc doc

.github/workflows/main_nix.yml

@@ -29,20 +29,20 @@ jobs:
 
     - name: Run binary
       run: |
-        make clean bin bint_run
-        make clean bin_debug_severe bint_run
+        make clean bin_run
+        make clean bin_debug_severe
 
     - name: Unit tests
-      run: make clean test test_run
+      run: make clean test_run
 
     - name: Severe unit tests (without sanitizers)
       if: ${{ runner.os == 'macOS' }}
-      run: make clean test_severe test_run
+      run: make clean test_severe
 
     - name: Severe unit tests (with sanitizers)
       # Apple clang does not support "AddressSanitizer: detect_leaks" (at least as of clang-1200.0.32.29)
       if: ${{ runner.os != 'macOS' }}
-      run: ASAN_OPTIONS=detect_leaks=1:strict_string_checks=1:detect_stack_use_after_return=1:check_initialization_order=1:strict_init_order=1 LSAN_OPTIONS=suppressions=.LSAN_suppr.txt make clean test_severe test_run
+      run: make clean test_leaks
 
 
   check_code_coverage:
@@ -55,7 +55,7 @@ jobs:
         submodules: recursive
 
     - name: Generate coverage report
-      run: make clean cov cov_run
+      run: CC=gcc CXX=g++ GCOV=gcov make clean clean_cov cov
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v3

.github/workflows/main_win.yml

@@ -40,7 +40,7 @@ jobs:
 
     # AddressSanitizer and LeakSanitizer not available on cygwin
     - name: Run binary
-      run: make clean bin bint_run
+      run: make clean bin_run
 
     - name: Unit tests
-      run: make clean test test_run
+      run: make clean test_run

.gitignore

@@ -14,8 +14,9 @@
 /Debug/
 
 # Test project output
-/testing/Output/*
-/testing/Output_*
+/tests/example/Output/*
+/tests/example/Output_*
+
 
 # Figures created by scripts in tools/
 /tools/Fig*
@@ -37,9 +38,11 @@ doc/html/*
 doc/log_doxygen.log
 doc/Doxyfile.bak
 
-# Binary files
+# Build and binary directories and files
+bin/*
+build/*
 SOILWAT2
-testing/SOILWAT2
+tests/example/SOILWAT2
 libSOILWAT2*
 libcovSOILWAT2*
 

.gitmodules

@@ -1,8 +1,8 @@
 [submodule "googletest"]
-	path = googletest
+	path = external/googletest
 	url = https://github.com/google/googletest
 	branch = main
 [submodule "pcg"]
-	path = pcg
+	path = external/pcg
 	url = https://github.com/imneme/pcg-c-basic
         branch = master

README.md

@@ -99,7 +99,7 @@ A full code documentation may be built, see [here](#get_documentation).
       - for unit tests (using `googletest`), additionally,
         - `g++ >= v5.0` or `clang++ >= v5.0` compliant with `C++11`
         - `POSIX API`
-    - POSIX- or GNU-compliant `make`
+    - GNU-compliant `make`
     - On Windows OS: an installation of `cygwin`
 
   * Clone the repository
@@ -239,15 +239,15 @@ __Integration tests__
 We use integration tests to check that the entire simulation model works
 as expected when used in a real-world application setting.
 
-The folder `testing/` contains all necessary inputs to run `SOILWAT2`
+The folder `tests/example/` contains all necessary inputs to run `SOILWAT2`
 for one generic location
 (it is a relatively wet and cool site in the sagebrush steppe).
 
 ```{.sh}
-      make bin bint_run
+      make bin_run
 ```
 
-The simulated output is stored at `testing/Output/`.
+The simulated output is stored at `tests/example/Output/`.
 
 
 Another use case is to compare output of a new (development) branch to output
@@ -262,16 +262,16 @@ The following steps provide a starting point for such comparisons:
 ```{.sh}
       # Simulate on refernce branch and copy output to "Output_ref"
       git checkout master
-      make bin bint_run
-      cp -r testing/Output testing/Output_ref
+      make bin_run
+      cp -r tests/example/Output tests/example/Output_ref
 
       # Switch to development branch <branch_xxx> and run the same simulation
       git checkout <branch_xxx>
-      make bin bint_run
+      make bin_run
 
       # Compare the two sets of outputs
       #   * Lists all output files and determine if they are exactly they same
-      diff testing/Output/ testing/Output_ref/ -qs
+      diff tests/example/Output/ tests/example/Output_ref/ -qs
 ```
 
 
@@ -289,17 +289,17 @@ Currently, the following is implemented:
        and some slope/aspect/day of year combinations
 
 ```{.sh}
-      CPPFLAGS=-DSW2_SolarPosition_Test__hourangles_by_lat_and_doy make test test_run
+      CPPFLAGS=-DSW2_SolarPosition_Test__hourangles_by_lat_and_doy make test_run
       Rscript tools/plot__SW2_SolarPosition_Test__hourangles_by_lat_and_doy.R
 
-      CPPFLAGS=-DSW2_SolarPosition_Test__hourangles_by_lats make test test_run
+      CPPFLAGS=-DSW2_SolarPosition_Test__hourangles_by_lats make test_run
       Rscript tools/plot__SW2_SolarPosition_Test__hourangles_by_lats.R
 ```
 
   - PET plots as function of radiation, relative humidity, wind speed, and cover
 
 ```{.sh}
-      CPPFLAGS=-DSW2_PET_Test__petfunc_by_temps make test test_run
+      CPPFLAGS=-DSW2_PET_Test__petfunc_by_temps make test_run
       Rscript tools/plot__SW2_PET_Test__petfunc_by_temps.R
 ```
 

doc/Doxyfile

@@ -876,8 +876,8 @@ WARN_LOGFILE           =
 
 INPUT                  = . \
                          doc/additional_pages/ \
-                         testing/ \
-                         testing/Input
+                         tests/example/ \
+                         tests/example/Input
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -925,7 +925,7 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = testing/README.md
+EXCLUDE                = tests/example/README.md
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -958,8 +958,8 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = testing \
-                         testing/Input
+EXAMPLE_PATH           = tests/example \
+                         tests/example/Input
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

doc/additional_pages/A_SOILWAT2_user_guide.md

@@ -133,18 +133,16 @@ on your side.
 
 
 ### Example
-  * The source code contains a complete example simulation project in `testing/`
-  * Copy the executable to the testing path, modify inputs as desired,
-    and run a simulation, e.g.,
+  * The source code contains a complete example simulation project in
+    `tests/example/`
+  * Modify inputs as desired and run a simulation, e.g.,
 ```{.sh}
-    make bint bint_run
+    make bin_run
 ```
     or, equivalently,
 ```{.sh}
     make bin
-    cp SOILWAT2 testing/
-    cd testing/
-    ./SOILWAT2
+    bin/SOILWAT2 -d ./tests/example -f files.in
 ```
 
   * The inputs comprise the master file `files.in` and the content of the
@@ -154,7 +152,7 @@ on your side.
     warnings and errors. The output files are in `.csv` format and can be
     opened by a spreadsheet program (e.g., `LibreOffice` or `Excel`) or
     imported into `R`
-    (e.g., `data <- read.csv("testing/Output/sw2_yearly.csv")`).
+    (e.g., `data <- read.csv("tests/example/sw2_yearly.csv")`).
     Outputs are explained in detail
     [here](doc/additional_pages/SOILWAT2_Inputs.md).
 

doc/additional_pages/SOILWAT2_Inputs.md

@@ -8,20 +8,19 @@ Note: this document is best viewed as part of the doxygen-built documentation
 <br>
 
 ### Example
-  * The source code contains a complete example simulation project in `testing/`
-  * Copy the executable to the testing path, modify inputs as desired,
-    and run a simulation, e.g.,
+  * The source code contains a complete example simulation project in
+    `tests/example/`
+  * Modify inputs as desired and run a simulation, e.g.,
 ```{.sh}
-    make bint bint_run
+    make bin_run
 ```
     or, equivalently,
 ```{.sh}
     make bin
-    cp SOILWAT2 testing/
-    cd testing/
-    ./SOILWAT2
+    bin/SOILWAT2 -d ./tests/example -f files.in
 ```
 
+
   * The inputs comprise the master file `files.in` and the content of the
     `Input/` folder. They are explained in detail
     \ref explain_inputs "below".
@@ -64,78 +63,78 @@ Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section yearsin years.in
-\verbinclude testing/Input/years.in
+\verbinclude tests/example/Input/years.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section siteparamin siteparam.in
-\verbinclude testing/Input/siteparam.in
+\verbinclude tests/example/Input/siteparam.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section soilsin soils.in
-\verbinclude testing/Input/soils.in
+\verbinclude tests/example/Input/soils.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section swrcpin swrc_params.in
-\verbinclude testing/Input/swrc_params.in
+\verbinclude tests/example/Input/swrc_params.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section weathsetupin weathsetup.in
-\verbinclude testing/Input/weathsetup.in
+\verbinclude tests/example/Input/weathsetup.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section mkvprobin mkv_prob.in
-\verbinclude testing/Input/mkv_prob.in
+\verbinclude tests/example/Input/mkv_prob.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section mkvcovarin mkv_covar.in
-\verbinclude testing/Input/mkv_covar.in
+\verbinclude tests/example/Input/mkv_covar.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section climatein climate.in
-\verbinclude testing/Input/climate.in
+\verbinclude tests/example/Input/climate.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section vegin veg.in
-\verbinclude testing/Input/veg.in
+\verbinclude tests/example/Input/veg.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section estabin estab.in
-\verbinclude testing/Input/estab.in
+\verbinclude tests/example/Input/estab.in
 <hr>
 Go back to the \ref explain_inputs "list of input files"
 
 \section carbonin carbon.in
-\verbinclude testing/Input/carbon.in
+\verbinclude tests/example/Input/carbon.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section swcsetupin swcsetup.in
-\verbinclude testing/Input/swcsetup.in
+\verbinclude tests/example/Input/swcsetup.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>
 
 \section outsetupin outsetup.in
-\verbinclude testing/Input/outsetup.in
+\verbinclude tests/example/Input/outsetup.in
 
 Go back to the \ref explain_inputs "list of input files"
 <hr>

doc/additional_pages/SOILWAT2_Outputs.md

@@ -8,18 +8,16 @@ Note: this document is best viewed as part of the doxygen-built documentation
 <br>
 
 ### Example
-  * The source code contains a complete example simulation project in `testing/`
-  * Copy the executable to the testing path, modify inputs as desired,
-    and run a simulation, e.g.,
+  * The source code contains a complete example simulation project in
+    `tests/example/`
+  * Modify inputs as desired and run a simulation, e.g.,
 ```{.sh}
-    make bint bint_run
+    make bin_run
 ```
     or, equivalently,
 ```{.sh}
     make bin
-    cp SOILWAT2 testing/
-    cd testing/
-    ./SOILWAT2
+    bin/SOILWAT2 -d ./tests/example -f files.in
 ```
 
   * The inputs comprise the master file `files.in` and the content of the

SW_Carbon.h → include/SW_Carbon.h

@@ -7,7 +7,7 @@
 #ifndef CARBON
 #define CARBON
 
-#include "SW_Defines.h"
+#include "include/SW_Defines.h"
 
 
 #ifdef __cplusplus

SW_Defines.h → include/SW_Defines.h

@@ -20,7 +20,7 @@
 #define SOILW_DEF_H
 
 #include <math.h>  /* >= C99; for: atan(), isfinite() */
-#include "generic.h"
+#include "include/generic.h"
 
 #ifdef __cplusplus
 extern "C" {

SW_Markov.h → include/SW_Markov.h

@@ -13,7 +13,7 @@
 #ifndef SW_MARKOV_H
 #define SW_MARKOV_H
 
-#include "pcg/pcg_basic.h"
+#include "external/pcg/pcg_basic.h"
 
 #ifdef __cplusplus
 extern "C" {