Merge pull request #325 from DrylandEcology/release/devel_v7.0.0

Release v7.0.0 see https://github.com/DrylandEcology/SOILWAT2/milestone/13 - Read daily weather before the simulations enhancement (#311) - Calculate climate variables before simulation loop (#317) - Estimate vegetation cover from climate before simulation run (#318) - Implement multiple soil water retention curves (#315) - Soil density: input either for < 2 mm fraction or for whole soil? enhancement (#280) - Re-organize repository with more sub-folders question (#89) - Daily variables for atmospheric demand (#341) - STEPWAT2 updated to work with this release (see DrylandEcology/STEPWAT2#535) - rSOILWAT2 updated to work with this release (see DrylandEcology/rSOILWAT2#214)
DrylandEcology · Jun 9, 2023 · 34bd4bf · 34bd4bf
2 parents 0a11f71 + ed6afe3
commit 34bd4bf
Show file tree

Hide file tree

Showing 167 changed files with 15,166 additions and 4,385 deletions.
diff --git a/.LSAN_suppr.txt b/.LSAN_suppr.txt
@@ -5,3 +5,6 @@
 
 # https://github.com/DrylandEcology/SOILWAT2/issues/205
 leak:SW_VPD_construct
+
+# on Apple arm64: https://github.com/google/sanitizers/issues/1501
+leak:realizeClassWithoutSwift
diff --git a/.github/workflows/check_doc.yml b/.github/workflows/check_doc.yml
@@ -13,7 +13,7 @@ jobs:
 
     steps:
     - name: Checkout repository and submodules
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       with:
         submodules: recursive
 
@@ -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
diff --git a/.github/workflows/main_nix.yml b/.github/workflows/main_nix.yml
@@ -20,7 +20,7 @@ jobs:
 
     steps:
     - name: Checkout repository and submodules
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       with:
         submodules: recursive
 
@@ -29,35 +29,36 @@ 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
+    - name: Unit tests (shuffle and repeat 3x)
+      run: make clean test_rep3rnd
 
     - 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:
     runs-on: ubuntu-latest
 
     steps:
     - name: Checkout repository and submodules
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       with:
         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@v2
+      uses: codecov/codecov-action@v3
       with:
         fail_ci_if_error: false # just report, don't fail checks
+        token: ${{ secrets.CODECOV_TOKEN }}
diff --git a/.github/workflows/main_win.yml b/.github/workflows/main_win.yml
@@ -26,12 +26,12 @@ jobs:
       shell: bash
 
     - name: Checkout repository and submodules
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       with:
         submodules: recursive
 
     - name: Install cygwin (windows)
-      uses: cygwin/cygwin-install-action@v1
+      uses: cygwin/cygwin-install-action@v3
       with:
         packages: gcc-core gcc-g++ make
 
@@ -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
+    - name: Unit tests (shuffle and repeat 3x)
+      run: make clean test_rep3rnd
diff --git a/.gitignore b/.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*
 
diff --git a/.gitmodules b/.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
diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,120 @@
+# NEWS
+
+# SOILWAT2 v7.0.0
+* This version produces nearly identical simulation output
+  as the previous release under default values for the new inputs.
+  Small deviations arise due to a fix in the handling of soil moisture values
+  when between field capacity and saturation.
+
+* Multiple soil water release curves (`SWRC`) are now implemented and can be
+  selected with new input `swrc_name`. Implemented `SWRCs` currently include
+  `"Campbell1974"`, `"vanGenuchten1980"`, and `"FXW"`. New input `has_swrcp`
+  determines if parameters for a `SWRC` are estimated at run-time via an
+  implemented pedotransfer function (`PTF`) based on new input `ptf_name` or
+  if they are provided as inputs via new input file `"swrc_params.in"`.
+  `rSOILWAT2` implements additional pedotransfer functions. See documentation
+  entry of `"swrc_ptf"` for additional details and for guidance on how to
+  implement additional `SWRCs` and `PTFs` (issue #315; @dschlaep).
+
+* Soil density inputs can now represent either matric or bulk density
+  (issue #280; @dschlaep).
+    * Automatic conversion between matric and bulk density as needed
+      using the new input `type_soilDensityInput`.
+
+* Daily weather inputs that force a simulation are now processed
+  all at once; previously, values were processed for one year at a time during
+  the main simulation loop (issue #311; @dschlaep, @N1ckP3rsl3y).
+    * Daily weather inputs are now obtained by `readAllWeather()`
+      via `SW_WTH_read()` during `SW_CTL_read_inputs_from_disk()`, i.e.,
+      the same time as other inputs are read from files.
+    * Then, weather values are "finalized", i.e., missing values are imputed
+      (e.g., by the weather generator) and scaled with monthly parameters,
+      by `finalizeAllWeather()` via `SW_WTH_finalize_all_weather()`;
+      this must occur before the simulation is "initialized"
+      by `SW_CTL_init_run()`.
+    * Imputation of missing daily weather values by `generateMissingWeather()`
+      can be done either by last-observation-carried-forward `"LOCF"`
+      (which handles all daily weather variables) or by the Markov weather
+      generator (which handles only temperature and precipitation).
+
+* Daily weather inputs, in addition to the previous variables
+  maximum air temperature, minimum air temperature, and precipitation amount,
+  can now process the following variables (issue #341; @dschlaep, @N1ckP3rsl3y):
+    * Cloud cover (can be replaced by shortwave radiation)
+    * Wind speed (can be replaced by wind components)
+    * Wind speed eastward component (optional)
+    * Wind speed northward component (optional)
+    * Relative humidity (can be replaced by max/min humidity, specific humidity,
+      dew point temperature, or vapor pressure)
+    * Maximum relative humidity (optional)
+    * Minimum relative humidity (optional)
+    * Specific humidity (optional)
+    * Dew point temperature (optional)
+    * Actual vapor pressure (optional)
+    * Downward surface shortwave radiation (optional)
+
+* SOILWAT2 gains the ability to calculate long-term climate summaries
+  (issue #317; @N1ckP3rsl3y, @dschlaep).
+    * New `calcSiteClimate()` calculates monthly and annual time
+      series of climate variables from daily weather.
+    * New `averageClimateAcrossYears()` calculates long-term climate summaries.
+    * Both functions are based on `rSOILWAT2::calc_SiteClimate()`
+      which was previously coded in R.
+    * This version fixes issues from the previous R version:
+       * Mean annual temperature is now the mean across years of
+         means across days within year of mean daily temperature.
+       * Years at locations in the southern hemisphere are now adjusted to start
+         on July 1 of the previous calendar year.
+       * The cheatgrass-related variables, i.e., `Month7th_PPT_mm`,
+         `MeanTemp_ofDriestQuarter_C`, and `MinTemp_of2ndMonth_C`,
+         are now adjusted for location by hemisphere.
+
+* SOILWAT2 gains the ability to estimate fractional land cover
+  representing a potential natural vegetation based on climate relationships
+  (using new input `veg_method`) instead of reading land cover values
+  from input files (issue #318; @N1ckP3rsl3y, @dschlaep).
+    * New `estimatePotNatVegComposition()` estimates
+      fractional land cover representing a potential natural vegetation
+      based on climate relationships.
+      This function is based on `rSOILWAT2::estimate_PotNatVeg_composition()`
+      which was previously coded in R.
+    * New `estimateVegetationFromClimate()`
+      (which is called by `SW_VPD_init_run()`) uses `veg_method` to determine
+      at run time if a simulation utilizes `averageClimateAcrossYears()` and
+      `estimatePotNatVegComposition()` to set land cover values
+      instead of using the cover values provided in the input file.
+    * This version fixes issues from the previous R version:
+       * The `C4` grass correction based on Teeri & Stowe 1976 is now applied
+         as documented (`rSOILWAT2` issue #218).
+       * The sum of all grass components, if fixed, is now incorporated into
+         the total sum of all fixed components (`rSOILWAT2` issue #219).
+
+
+## Changes to inputs
+* New inputs via `"weathsetup.in"` determine whether monthly or daily inputs
+  for cloud cover, relative humidity, and wind speed are utilized;
+  describe which daily weather variables are contained in the weather input
+  files `weath.YYYY`; and describe units of (optional) input shortwave
+  radiation.
+* New (optional) variables (columns) in weather input files `weath.YYYY` that
+  are described via `"weathsetup.in"`.
+* New inputs via `"siteparam.in"` select a soil water release curve `swrc_name`
+  and determine parameter source `has_swrcp`, i.e.,
+  either estimated via selected pedotransfer function `ptf_name` or
+  values obtained from new input file `"swrc_params.in"`.
+  Default values `"Campbell1974"`, `"Cosby1984AndOthers"`, and 0
+  (i.e., use `PTF` to estimate paramaters) reproduce previous behavior.
+* New input file `"swrc_params.in"` to provide parameters of the selected
+  soil water release curve (if not estimated via a pedotransfer function)
+  for each soil layer.
+* SOILWAT2 gains `type_soilDensityInput` as new user input (`siteparam.in`)
+  with default value 0 (i.e., matric soil density)
+  that reproduces previous behavior.
+* SOILWAT2 gains `veg_method` as new user input (`"veg.in"`)
+  with default value 0 (i.e., land cover are obtained from input files)
+  that reproduces previous behavior.
+
+
 # SOILWAT2 v6.7.0
 * This version produces exactly the same simulation output
   as the previous release under default values
@@ -16,15 +133,20 @@
 
 
 # SOILWAT2 v6.6.0
-* Random number generators now produce sequences that can be exactly reproduced.
-* `RandSeed()` gains arguments "initstate" and "initseq" (and lost "seed") to
-  fully seed a `pcg32` random number generator.
-* `RandNorm()` is now re-entrant and discards one of the two generated values.
-  Compilation with `"RANDNORMSTATIC"` re-produces the old, not re-entrant
-  implementation.
+* Random number generators now produce sequences that can be exactly reproduced
+  (@dschlaep).
+    * `RandSeed()` gains arguments "initstate" and "initseq" (and lost "seed")
+      to fully seed a `pcg32` random number generator.
+    * `RandNorm()` is now re-entrant and discards one of the two generated
+      values. Compilation with `"RANDNORMSTATIC"` re-produces the old,
+      not re-entrant implementation.
+    * `SW_MKV_construct()` now only seeds `markov_rng` (the random number
+      generator of the weather generator) if run as `SOILWAT2` using the new
+      input `rng_seed`; `SW_MKV_construct()` does not seed `markov_rng`
+      when run as part of `STEPWAT2` or `rSOILWAT2`
+      (both of which use their own `RNG` initialization procedures).
+* `SW_WTH_init_run()` now also initializes yesterday's weather values
+  (@dschlaep).
+
+## Changes to inputs
 * SOILWAT2 gains `rng_seed` as new user input (`"weathsetup.in"`).
-* `SW_MKV_construct()` now only seeds `markov_rng` (the random number generator
-  of the weather generator) if run as `SOILWAT2` using the new input `rng_seed`;
-  `SW_MKV_construct()` does not seed `markov_rng` when run as part of `STEPWAT2`
-  or `rSOILWAT2` (both of which use their own `RNG` initialization procedures).
-* `SW_WTH_init_run()` now also initializes yesterday's weather values.
diff --git a/README.md b/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
 ```