Domain - Create netCDF Files

.github/workflows/main_nix.yml

@@ -50,6 +50,25 @@ jobs:
       run: make clean test_sanitizer
 
 
+  build_ncSW2:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository and submodules
+      uses: actions/checkout@v3
+      with:
+        submodules: recursive
+
+    - name: Install netCDF-C
+      run: |
+        sudo apt-get update
+        sudo apt-get install libnetcdf-dev
+
+    - name: Build binary with netCDF support
+      run: CPPFLAGS=-DSWNETCDF make clean all
+
+
+
   check_code_coverage:
     runs-on: ubuntu-latest
 

NEWS.md

@@ -2,21 +2,33 @@
 
 # SOILWAT2 v8.0.0-devel
 
+* SOILWAT2 can now be compiled in one of two modes
+  (#361, #362; @N1ckP3rsl3y, @dschlaep):
+    * `"netCDF"`-based input (currently limited to the `"domain"`);
+      this mode is compiled if the new preprocessor definition `"SWNETCDF"`
+      and the `"netCDF"` library are available,
+      e.g., `CPPFLAGS=-DSWNETCDF make all`
+    * text-based input and output (as previously)
+
 * 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 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 files are read once and now populate a `"template"`.
-    * New `SW_CTL_RunSimSet()` loops over the simulation set or runs
-      one user specified simulation unit.
+    * 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).
 
 * Tests now utilize the same template/deep-copy approach (@dschlaep),
   i.e., input files from `test/example/` populate a `"template"` and
@@ -48,6 +60,7 @@
   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 `"netCDF"`-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;
@@ -58,6 +71,24 @@
   then there is (practically) no wall time limit.
 
 
+## Changes to inputs for `"netCDF"`-based SOILWAT2
+* `"netCDF"`-based SOILWAT2 is compiled if the new preprocessor definition
+  `"SWNETCDF"` is made available, e.g., `CPPFLAGS=-DSWNETCDF make all`
+* User-specified paths to `"netCDF"` header and library can be provided as well,
+  e.g., `CPPFLAGS=-DSWNETCDF NC_CFLAGS="-I/path/to/include" NC_LIBS="-L/path/to/lib" make all`
+* New input directory `"Input_nc/"` that describes `"netCDF"`-based inputs
+  (paths provided by new entries in `"files.in"`).
+* New text input file `"files_nc.in"` that lists for each input purpose
+  (currently, only `"domain"` is 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"`.
+
+
 # SOILWAT2 v7.2.0
 * Simulation output remains the same as the previous version.
 

README.md

@@ -32,6 +32,7 @@
 [doxygen]: https://github.com/doxygen/doxygen
 [GoogleTest]: https://github.com/google/googletest
 [semantic versioning]: https://semver.org/
+[netCDF]: https://downloads.unidata.ucar.edu/netcdf/
 
 <br>
 
@@ -101,26 +102,27 @@ A full code documentation may be built, see [here](#get_documentation).
         - `POSIX API`
     - GNU-compliant `make`
     - On Windows OS: an installation of `cygwin`
+    - the `netCDF-C` library (if compiled with [netCDF][] support)
 
   * Clone the repository
     (details can be found in the
     [manual](doc/additional_pages/A_SOILWAT2_user_guide.md)), for instance,
-    ```{.sh}
+```{.sh}
         git clone --recursive https://github.com/DrylandEcology/SOILWAT2.git SOILWAT2
-    ```
+```
 
   * Build with `make` (see `make help` to print information about all
-    available targets), for instance,
-    ```{.sh}
-        cd SOILWAT2/
-        make
-    ```
-
-    You can use a specific compiler, e.g.,
-    ```{.sh}
+    available targets). For instance,
+```{.sh}
+        make                          # text-based mode
+        CPPFLAGS=-DSWNETCDF make      # netCDF-based mode
+```
+
+  * You can use a specific compiler, e.g.,
+```{.sh}
         CC=gcc make
         CC=clang make
-    ```
+```
 <br>
 
 

doc/additional_pages/A_SOILWAT2_user_guide.md

@@ -11,6 +11,7 @@
 [SOILWAT2]: https://github.com/DrylandEcology/SOILWAT2
 [tinytex]: https://yihui.name/tinytex/
 [xcode]: https://developer.apple.com/xcode
+[netCDF]: https://downloads.unidata.ucar.edu/netcdf/
 
 
 Note: this document is best viewed as part of the doxygen-built documentation
@@ -53,11 +54,11 @@ on your side.
     - xcode command line tools (run `xcode-select --install` on the command line)
     - having agreed to the xcode license (run `xcodebuild -license`)
     - or, alternatively, the full [xcode][] installation
-  - optional:
+  - to build the documentation (optional)
     - [doxygen][] (ideally `>= v1.9.3`) and
-      a minimal `latex` installation (see below)
-      to generate a local copy of the documentation
-
+    - a minimal `latex` installation (see below)
+  - to build with [netCDF][] support (optional)
+    - the `netCDF-C` library
 
 
 #### Example instructions for a minimal `latex` installation
@@ -106,12 +107,21 @@ on your side.
 
 
 ### Compilation
-  * Compile an executable binary, e.g.,
+  * Compile an executable binary with text-based input/output, e.g.,
 ```{.sh}
-    cd SOILWAT2/
     make
 ```
 
+  * Compile an executable binary with [netCDF][] support, e.g.,
+```{.sh}
+    CPPFLAGS=-DSWNETCDF make
+```
+
+  * User-specified paths to [netCDF][] header and library can be provided, e.g.,
+```{.sh}
+    CPPFLAGS=-DSWNETCDF NC_CFLAGS="-I/path/to/include" NC_LIBS="-L/path/to/lib" make
+```
+
 <br>
 
 

include/SW_Control.h

@@ -28,7 +28,7 @@ extern "C" {
 /* =================================================== */
 /*             Global Function Declarations            */
 /* --------------------------------------------------- */
-void SW_CTL_init_ptrs(SW_ALL* sw);
+void SW_CTL_init_ptrs(SW_ALL* sw) ;
 void SW_CTL_alloc_outptrs(SW_ALL* sw, LOG_INFO* LogInfo);
 void SW_ALL_deepCopy(SW_ALL* source, SW_ALL* dest, LOG_INFO* LogInfo);
 void SW_CTL_setup_domain(unsigned long userSUID,
@@ -48,8 +48,8 @@ void SW_CTL_RunSimSet(SW_ALL *sw_template, SW_OUTPUT_POINTERS SW_OutputPtrs[],
                       LOG_INFO *main_LogInfo);
 void SW_CTL_run_current_year(SW_ALL* sw, SW_OUTPUT_POINTERS* SW_OutputPtrs,
                              LOG_INFO* LogInfo);
-void SW_CTL_run_sw(SW_ALL* sw_template, SW_DOMAIN* SW_Domain, unsigned long ncStartSuid[],
-                   char* ncInFiles[], SW_OUTPUT_POINTERS SW_OutputPtrs[],
+void SW_CTL_run_sw(SW_ALL* sw_template, SW_DOMAIN* SW_Domain, unsigned long ncSuid[],
+                   SW_OUTPUT_POINTERS SW_OutputPtrs[],
                    RealD p_OUT[][SW_OUTNPERIODS], LOG_INFO* LogInfo);
 
 

include/SW_Defines.h

@@ -106,6 +106,9 @@ extern "C" {
 #define MAX_FILENAMESIZE 512
 #define MAX_PATHSIZE 2048
 
+/* Large storage for a value when reading in key-value pairs from an input file */
+#define LARGE_VALUE 1024
+
 /* Maximum number of messages to store in LOG_INFO */
 #define MAX_MSGS 10
 

include/SW_Domain.h

@@ -10,16 +10,18 @@ extern "C" {
 /* =================================================== */
 /*                  Local Definitions                  */
 /* --------------------------------------------------- */
-void SW_DOM_calc_ncStartSuid(SW_DOMAIN* SW_Domain, unsigned long suid,
-                             unsigned long ncStartSuid[]);
+void SW_DOM_calc_ncSuid(SW_DOMAIN* SW_Domain, unsigned long suid,
+                             unsigned long ncSuid[]);
 void SW_DOM_calc_nSUIDs(SW_DOMAIN* SW_Domain);
-Bool SW_DOM_CheckProgress(char* domainType, unsigned long ncStartSuid[]);
+Bool SW_DOM_CheckProgress(char* domainType, unsigned long ncSuid[]);
 void SW_DOM_CreateProgress(SW_DOMAIN* SW_Domain);
 void SW_DOM_read(SW_DOMAIN* SW_Domain, LOG_INFO* LogInfo);
-void SW_DOM_SetProgress(char* domainType, unsigned long ncStartSuid[]);
+void SW_DOM_SetProgress(char* domainType, unsigned long ncSuid[]);
 void SW_DOM_SimSet(SW_DOMAIN* SW_Domain, unsigned long userSUID,
                    LOG_INFO* LogInfo);
 void SW_DOM_deepCopy(SW_DOMAIN* source, SW_DOMAIN* dest, LOG_INFO* LogInfo);
+void SW_DOM_init_ptrs(SW_DOMAIN* SW_Domain);
+void SW_DOM_deconstruct(SW_DOMAIN* SW_Domain);
 
 #ifdef __cplusplus
 }

include/SW_Files.h

@@ -31,6 +31,8 @@ typedef enum {
 	eNoFile = -1,
 	/* List of all input files */
 	eFirst = 0,
+    /* netCDF-related input files directory */
+    eNCIn, eNCInAtt,
 	/* Domain information */
 	eDomain,
 	/* Description of a model run */

include/SW_datastructs.h

@@ -25,7 +25,8 @@
 #define SW_OUTTEXT
 #endif
 
-#define SW_NFILES 24 // For `InFiles`
+#define SW_NFILES 26 // For `InFiles`
+#define SW_NVARNC 1 // For `InFilesNC`
 
 
 /* =================================================== */
@@ -131,7 +132,7 @@ typedef struct {
 	Bool newperiod[SW_OUTNPERIODS];
 	Bool isnorth;
 
-    int ncStartSuid[2]; // First element used for domain "s", both used for "xy"
+    int ncSuid[2]; // First element used for domain "s", both used for "xy"
 
 	#ifdef STEPWAT
 	/* Variables from GlobalType (STEPWAT2) used in SOILWAT2 */
@@ -1033,6 +1034,40 @@ typedef struct {
 	#endif
 } SW_GEN_OUT;
 
+/* =================================================== */
+/*         Coordinate Reference System struct          */
+/* --------------------------------------------------- */
+
+typedef struct {
+    char *long_name, *grid_mapping_name, *crs_wkt;
+    double longitude_of_prime_meridian, semi_major_axis, inverse_flattening;
+
+    // Possible attributes if the type is "projected"
+    char *datum, *units;
+    double standard_parallel[2]; // first and second standard parallels; 2nd may be missing (NAN)
+    double longitude_of_central_meridian,
+           latitude_of_projection_origin,
+           false_easting,
+           false_northing;
+} SW_CRS;
+
+/* =================================================== */
+/*                SOILWAT2 netCDF struct               */
+/* --------------------------------------------------- */
+
+typedef struct {
+
+    char *title, *author, *institution, *comment, *coordinate_system;
+    Bool primary_crs_is_geographic;
+
+    SW_CRS crs_geogsc, crs_projsc;
+
+    char *varNC[SW_NVARNC];
+    char *InFilesNC[SW_NVARNC];
+
+    int ncFileIDs[SW_NVARNC];
+} SW_NETCDF;
+
 /* =================================================== */
 /*                    Domain struct                    */
 /* --------------------------------------------------- */
@@ -1052,6 +1087,12 @@ typedef struct {
 		startSimSet,       /**< First SUID in simulation set within domain to simulate */
 		endSimSet;         /**< Last SUID in simulation set within domain to simulate */
 
+    char crs_bbox[27];     /**< Input name/CRS type (domain.in) - holds up to "World Geodetic System 1984" (26) */
+    double min_x,          /**< Minimum x coordinate of the bounding box */
+           min_y,          /**< Minimum y coordinate of the bounding box */
+           max_x,          /**< Maximum x coordinate of the bounding box */
+           max_y;          /**< Maximum y coordinate of the bounding box */
+
 	// Temporal domain information
 	TimeInt startyr,     /**< First calendar year of the simulation runs */
 			endyr,           /**< Last calendar year of the simulation runs */
@@ -1060,6 +1101,9 @@ typedef struct {
 
 	// Information on input files
 	PATH_INFO PathInfo;
+
+    // Information dealing with netCDFs
+    SW_NETCDF netCDFInfo;
 } SW_DOMAIN;
 
 /* =================================================== */

include/SW_netCDF.h

@@ -0,0 +1,40 @@
+#ifndef SWNETCDF_H
+#define SWNETCDF_H
+
+#include "include/SW_datastructs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* =================================================== */
+/*                  Local Definitions                  */
+/* --------------------------------------------------- */
+
+#define vNCdom 0 // Domain netCDF index within `InFilesNC` and `varNC` (SW_NETCDF)
+
+#define DOMAIN_TEMP "Input_nc/domain_template.nc"
+
+/* =================================================== */
+/*             Global Function Declarations            */
+/* --------------------------------------------------- */
+void SW_NC_check(SW_DOMAIN* SW_Domain, int ncFileID, const char* fileName,
+                 LOG_INFO* LogInfo);
+void SW_NC_create_domain_template(SW_DOMAIN* SW_Domain, LOG_INFO* LogInfo);
+void SW_NC_create_template(const char* fileName, unsigned long timeSize,
+                           unsigned long vertSize, const char* varName,
+                           char* varAttributes[], LOG_INFO* LogInfo);
+void SW_NC_read_inputs(SW_ALL* sw, SW_DOMAIN* SW_Domain, unsigned long ncSUID[],
+                       LOG_INFO* LogInfo);
+void SW_NC_check_input_files(SW_DOMAIN* SW_Domain, LOG_INFO* LogInfo);
+void SW_NC_read(SW_NETCDF* SW_netCDF, PATH_INFO* PathInfo, LOG_INFO* LogInfo);
+void SW_NC_init_ptrs(SW_NETCDF* SW_netCDF);
+void SW_NC_deconstruct(SW_NETCDF* SW_netCDF);
+void SW_NC_open_files(SW_NETCDF* SW_netCDF, LOG_INFO* LogInfo);
+void SW_NC_close_files(SW_NETCDF* SW_netCDF);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // SWNETCDF_H