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).

Full Changelog

v7.2.0...v8.0.0