Merge pull request #378 from DrylandEcology/release/devel_v8.0.0

Release v8.0.0

This commit concludes phase 0 (with release v8.0.0): it includes the introduction of a simulation domain (a set of simulation units/runs) and the capability to produce output as netCDFs (full details in release notes and `NEWS`)

.LSAN_suppr.txt

@@ -3,5 +3,12 @@
 
 # These are known leaks that await fixing
 
-# on Apple arm64: https://github.com/google/sanitizers/issues/1501
+# on Apple arm64: suppress system libraries
+#   * https://github.com/google/sanitizers/issues/1501
+#   * https://github.com/llvm/llvm-project/issues/59758
+#   * https://discourse.llvm.org/t/does-leaksanitizer-not-work-on-macos-13-apple-silicon
 leak:realizeClassWithoutSwift
+leak:_fetchInitializingClassList
+leak:libobjc.A.dylib
+leak:libsystem_c.dylib
+leak:libsystem_info.dylib

.clang-format

@@ -0,0 +1,16 @@
+---
+BasedOnStyle: LLVM
+AlignAfterOpenBracket: BlockIndent                  # llvm: Align; >= v14
+AlignEscapedNewlines: Left                          # llvm: right
+BinPackArguments: false                             # llvm: true
+BinPackParameters: false                            # llvm: true
+BreakBeforeTernaryOperators: false                  # llvm: true
+IndentWidth: 4                                      # llvm: 2
+InsertBraces: true                                  # llvm: false; >= v15
+InsertNewlineAtEOF: true                            # llvm: false; >= v16
+MaxEmptyLinesToKeep: 2                              # llvm: 1
+PenaltyReturnTypeOnItsOwnLine: 1000                 # llvm: 60
+SeparateDefinitionBlocks: Always                    # llvm: leave; >= v14
+SortIncludes: CaseInsensitive                       # llvm: CaseSensitive
+SpaceAfterCStyleCast: true                          # llvm: false
+...

.git-blame-ignore-revs

@@ -0,0 +1,27 @@
+# List of specific commits to ignore by git
+
+# Useful for running automatic formatters without losing author information on relevant revisions
+
+# based on information from https://michaelheap.com/git-ignore-rev/
+
+# Run `git blame --ignore-revs-file .git-blame-ignore-revs`
+
+# Or set up global git config:
+#   # Set a global ignoreRevsFile
+#   git config --global blame.ignoreRevsFile .git-blame-ignore-revs
+#
+#   # Mark any lines that have had a commit skipped using --ignore-rev with a `?`
+#   git config --global blame.markIgnoredLines true
+#
+#   # Mark any lines that were added in a skipped commit and can not be attributed with a `*`
+#   git config --global blame.markUnblamableLines true
+
+
+# Initial push of existing code base
+af175f2ba4af18a3957e585a497e4913e2ec8847
+
+# Format entire code base
+0987e33874b8bba546d0cc71f7e096bb9f843869
+
+# Reorganize header include directives
+6853e36433d67be0b9c3a8b46bf46e634352a1b1

.github/workflows/clang-format-check.yml

@@ -0,0 +1,27 @@
+name: clang-format check
+
+# based on https://github.com/marketplace/actions/clang-format-check
+
+on:
+  push:
+    branches: [master, main, release/**]
+  pull_request:
+    branches: [master, main, release/**]
+
+jobs:
+  formatting-check:
+    name: Formatting Check
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        path:
+          - 'include'
+          - 'src'
+          - 'tests/gtests'
+    steps:
+    - uses: actions/checkout@v4
+    - name: Run clang-format style check
+      uses: jidicula/clang-format-action@v4.13.0
+      with:
+        clang-format-version: '18'
+        check-path: ${{ matrix.path }}

.github/workflows/main_nix.yml

@@ -49,6 +49,35 @@ jobs:
       if: ${{ runner.os != 'macOS' }}
       run: make clean test_sanitizer
 
+    - name: Compile as library for STEPWAT2
+      run: CPPFLAGS='-DSTEPWAT' make clean lib
+
+    - name: Compile as library for rSOILWAT2
+      # Rmock/ provides bare-bones headers of R C-API functions required by SOILWAT2
+      run: CPPFLAGS='-DRSOILWAT' CFLAGS='-Iexternal/Rmock' make clean libr
+
+
+  build_ncSW2:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository and submodules
+      uses: actions/checkout@v3
+      with:
+        submodules: recursive
+
+    - name: Install netCDF-C and udunits2
+      run: |
+        sudo apt-get update
+        sudo apt-get install libnetcdf-dev libudunits2-dev
+
+    - name: Build binary with netCDF support
+      run: CPPFLAGS=-DSWNETCDF make clean all
+
+    - name: Build binary with netCDF and udunits2 support
+      run: CPPFLAGS='-DSWNETCDF -DSWUDUNITS' make clean all
+
+
 
   check_code_coverage:
     runs-on: ubuntu-latest

.github/workflows/main_win.yml

@@ -44,3 +44,9 @@ jobs:
 
     - name: Unit tests (shuffle and repeat 3x)
       run: make clean test_rep3rnd
+
+    - name: Compile as library for STEPWAT2
+      run: CPPFLAGS='-DSTEPWAT' sw_sources='SW_Output_outarray.c SW_Output_outtext.c' make clean lib
+
+    - name: Compile as library for rSOILWAT2
+      run: CPPFLAGS='-DRSOILWAT' CFLAGS='-Iexternal/Rmock' sw_sources='SW_Output_outarray.c' make clean libr

.gitignore

@@ -24,6 +24,8 @@
 # Figures created by scripts in tools/
 /tools/Fig*
 /tools/*.pdf
+/tools/figures/
+/tools/figures*
 
 # Google unit test output
 gtest-*.o

.gitmodules

@@ -4,5 +4,5 @@
 	branch = main
 [submodule "pcg"]
 	path = external/pcg
-	url = https://github.com/imneme/pcg-c-basic
-        branch = master
+	url = https://github.com/DrylandEcology/pcg-c-basic
+        branch = feature_sw2

NEWS.md

@@ -1,5 +1,150 @@
 # NEWS
 
+# SOILWAT2 v8.0.0
+* Simulation output remains the same as the previous version.
+  However, output of establishment/recruitment for two species is now
+  generated by default by the example simulation run.
+
+* SOILWAT2 can now be compiled in one of two modes: `"nc"` and `"text"`
+  (#361, #362, #363; @N1ckP3rsl3y, @dschlaep):
+    * `"nc"`-based SOILWAT2: output files are produced in `"netCDF"` format;
+      input files in `"netCDF"` format are currently limited to the `"domain"`.
+      This mode is compiled if the new preprocessor definition `"SWNETCDF"`
+      and the `"netCDF-c"` library are available,
+      e.g., `make CPPFLAGS=-DSWNETCDF all`
+    * `"text"`-based SOILWAT2 (as previously): output files are plain text
+      that are formatted as comma-separated values `"csv"`;
+      input files are plain text.
+
+* SOILWAT2 now represents a simulation `"domain"`, i.e.,
+  a set of (independent) simulation units/runs (#360; @N1ckP3rsl3y, @dschlaep).
+  A `"domain"` is defined by either a set of `"sites"` or by a `"xy"`-grid.
+  The current simulation set consists of simulation units within a `"domain"`
+  that have not yet been simulated.
+  Simulation units are identified via `"suid"` (simulation unit identifier).
+    * Input text files are read once and now populate a `"template"`
+      that is used for each simulation unit.
+    * New `SW_CTL_RunSimSet()` loops over the simulation set or
+      runs one user specified simulation unit.
+      It writes warning and error messages from all simulation units to the
+      `logfile` but does not exit if a simulation unit fails
+      (`main()` will exit with an error if it fails or
+      if every simulation unit produced an error).
+    * New `SW_CTL_run_sw()` takes a deep copy of the `"template"` as basis
+      for each simulation unit.
+    * For `"netCDF"`-based SOILWAT2, information about the `"domain"`
+      (i.e., simulation units and their geographic locations) is obtained from
+      `"domain.nc"` (#361; @N1ckP3rsl3y, @dschlaep).
+    * For `"nc"`-based SOILWAT2, simulation progress (success/failure) is
+      tracked by `"progress.nc"` (#387; @N1ckP3rsl3y, @dschlaep);
+      progress tracking makes re-starts after partial completion of the
+      simulation set by an earlier execution possible.
+
+* SOILWAT2 can now be compiled with `"udunits2"` to convert output to user
+  requested units (#392; @dschlaep, @N1ckP3rsl3y).
+    * Unit conversion is available only in `"nc"`-mode and if compiled
+      with the new preprocessor definition `"SWUDUNITS"`
+      and if the `"udunits2"` library is available,
+      e.g., `make CPPFLAGS='-DSWNETCDF -DSWUDUNITS' all`.
+    * Users request output units via field `"netCDF units"` of the
+      input file `"SW2_netCDF_output_variables.tsv"`.
+
+* Tests now utilize the same template/deep-copy approach (@dschlaep),
+  i.e., input files from `test/example/` populate a `"template"` and
+  test fixture deep copy the `"template"` (avoiding repeated reading from disk).
+
+* SOILWAT2 gained basic time tracking and reporting (#380; @dschlaep).
+  Temporal resolution may only be full seconds (for C99) but
+  could be sub-seconds (for C11 or later).
+  The runs over the simulation set end gracefully
+  if a user specified wall time limit is (nearly) reached
+  (nearly is defined by `SW_WRAPUPTIME`).
+  A report is written to `stdout` or (silently) to the `logfile` if user
+  requested quiet mode; the report includes
+    * Overall wall time and proportion of wall time for the simulation set
+    * Time of simulation units and reports average, standard deviation
+      minimum and maximum time.
+
+* SOILWAT2 gained spin-up functionality (#379; @niteflyunicorns, @dschlaep).
+  A user-requested sequence of (random) years is simulated (without output)
+  before the actual simulation run to provide better starting values
+  (e.g., soil moisture, soil temperature).
+  User inputs are obtained from `"domain.in"`.
+
+* The random number generator `"pcg"` is now a submodule of a forked copy
+  of the previous repository `imneme/pcg-c-basic` (#353; @dschlaep).
+  This allowed us to fix a function declaration without a prototype.
+
+* Specified a consistent code style and formatted code,
+  header include directives, doxygen documentation, and
+  updated code contribution guidelines (#316; @dschlaep).
+
+## Changes to inputs
+* New input file `"domain.in"` with input variables that specify
+  type and spatial dimensions of the simulation `"domain"`
+  (with a backwards compatible default of one site),
+  start and end year (the latter previously in `"years.in"`), and
+  spin-up information (mode, duration, scope).
+  This input file uses a key-value pair approach, i.e., inputs must use
+  the correct key while they don't have to be on a specific line
+  (as they have to be in other input files).
+* Input file `"years.in"` was removed (content moved to `"domain.in"`).
+* New input file `"modelrun.in"` with inputs for geographic coordinates and
+  topography (previously in `"siteparam.in"`).
+* Input file `"siteparam.in"` lost inputs for geographic coordinates and
+  topography (content moved to `"modelrun.in"`).
+* Input file `"files.in"` gained two entries for `"nc"`-based SOILWAT2.
+* New command line option `"-s X"` where `X` is a simulation unit identifier;
+  if the option `"-s X"` is absent or `X` is `0`, then all simulation units
+  in the simulation `"domain"` are run;
+  otherwise, only the simulation unit `X` is run.
+* New command line option `"-t X"` where `X` is the wall time limit in seconds.
+  The code gracefully ends early if the wall time reaches a limit of
+  `X - SW_WRAPUPTIME` seconds; if the option `"-t X"` is absent,
+  then there is (practically) no wall time limit.
+* New command line option `"-r"` to rename netCDF domain template file
+  to domain file name provided in `"Input_nc/files_nc.in"`.
+
+## Changes to outputs
+* Output of establishment/recruitment for two species is now
+  generated by default by the example simulation run (#411; @dschlaep).
+
+## Changes to inputs and outputs for `"nc"`-based SOILWAT2
+* `"nc"`-based SOILWAT2 is compiled if the new preprocessor definition
+  `"SWNETCDF"` is available, e.g., `make CPPFLAGS=-DSWNETCDF all`;
+  the capability to convert units is compiled with the new preprocessor
+  definition `"SWUDUNITS"`, e.g., `make CPPFLAGS='-DSWNETCDF -DSWUDUNITS' all`
+* User-specified paths to external headers and libraries can be provided
+    * `"netCDF-c"` headers: `NC_CFLAGS="-I/path/to/include"`
+    * `"netCDF-c"` library: `NC_LIBS="-I/path/to/lib"`
+    * `"udunits2"` headers: `UD_CFLAGS="-I/path/to/include"`
+    * `"udunits2"` library: `UD_LIBS="-I/path/to/lib"`
+    * `"expat"` headers: `EX_CFLAGS="-I/path/to/include"`
+    * `"expat"` library: `EX_LIBS="-I/path/to/lib"`
+* New input directory `"Input_nc/"` that describes `"nc"`-based inputs
+  (paths provided by new entries in `"files.in"`).
+* New text input file `"files_nc.in"` that lists for each input purpose
+  (currently, `"domain"` and `"progress"` are implemented)
+  the path to the `"netCDF"` input file and associated variable name.
+* New text input file `"attribues_nc.in"` to provide global attributes and a
+  geographic (and optionally a projected) `"CRS"` (coordinate reference system)
+  that describe the `"domain.nc"`.
+* A user provided `"domain.nc"` that describes the simulation `"domain"`.
+  Specifications must be consistent with `"domain.in"`.
+  If absent, a template is automatically generated based on `"domain.in"`.
+* A user provided `"progress.nc"` that describes the simulation `"progress"`.
+  Specifications must be consistent with `"domain.nc"`.
+  The `"progress"` variable can optionally be contained in `"domain.nc"`
+  instead of a separate file.
+  If absent, it is automatically generated based on `"domain.nc"`.
+* New tab-separated value `"tsv"` input file `"SW2_netCDF_output_variables.tsv"`
+  that lists, activates, and describes each output variable in `"netCDF"` mode.
+* All outputs are written to `"netCDF"` files based on user requests from
+  `"SW2_netCDF_output_variables.tsv"`.
+  Each `"netCDF"` output file contains the output variables from one output
+  group `"outkey"` and one output period (daily, weekly, monthly, yearly).
+
+
 # SOILWAT2 v7.2.0
 * Simulation output remains the same as the previous version.