Merge pull request #388 from DrylandEcology/feature_nc_progress

Create a "Progress" netCDF

* Simulation progress (success/failure) is now tracked by `"progress.nc"` for `"netCDF"`-based SOILWAT2 (close #387; @N1ckP3rsl3y, @dschlaep).
  
* A user provided `"progress.nc"` (e.g., from a previous partial run) that describes the simulation `"progress"`. Specifications must be consistent with `"domain.nc"`. If absent, it is automatically generated based on `"domain.nc"`.

* Progress tracking makes re-starts after partial completion of the simulation set by an earlier execution possible.

* Simple progress messages printed to the console (if not quiet mode).

NEWS.md

@@ -29,6 +29,11 @@
     * 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 `"netCDF"`-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.
+
 
 * Tests now utilize the same template/deep-copy approach (@dschlaep),
   i.e., input files from `test/example/` populate a `"template"` and
@@ -79,14 +84,17 @@
 * 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)
+  (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"`.
+  If absent, it is automatically generated based on `"domain.nc"`.
 
 
 # SOILWAT2 v7.2.0

doc/additional_pages/A_SOILWAT2_user_guide.md

@@ -122,6 +122,11 @@ on your side.
     CPPFLAGS=-DSWNETCDF NC_CFLAGS="-I/path/to/include" NC_LIBS="-L/path/to/lib" make
 ```
 
+  * User-specified username and hostname, e.g.,
+```{.sh}
+    USERNAME=nobody HOSTNAME=nowhere make
+```
+
 <br>
 
 

include/SW_Domain.h

@@ -13,10 +13,13 @@ extern "C" {
 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 ncSuid[]);
-void SW_DOM_CreateProgress(SW_DOMAIN* SW_Domain);
+Bool SW_DOM_CheckProgress(int progFileID, int progVarID,
+                          unsigned long ncSuid[], LOG_INFO* LogInfo);
+void SW_DOM_CreateProgress(SW_DOMAIN* SW_Domain, LOG_INFO* LogInfo);
 void SW_DOM_read(SW_DOMAIN* SW_Domain, LOG_INFO* LogInfo);
-void SW_DOM_SetProgress(char* domainType, unsigned long ncSuid[]);
+void SW_DOM_SetProgress(Bool isFailure, const char* domType, int progFileID,
+                        int progVarID, unsigned long ncSuid[],
+                        LOG_INFO* LogInfo);
 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);

include/SW_datastructs.h

@@ -26,7 +26,7 @@
 #endif
 
 #define SW_NFILES 26 // For `InFiles`
-#define SW_NVARNC 1 // For `InFilesNC`
+#define SW_NVARNC 2 // For `InFilesNC`
 
 
 /* =================================================== */
@@ -769,7 +769,8 @@ typedef struct {
 	Bool stopRun;           // Specifies if an error has occurred and
                             // the program needs to stop early (backtrack)
 
-  Bool QuietMode; /**< Don't print version, error message, or notify user about logfile (only used by SOILWAT2) */
+  Bool QuietMode, /**< Don't print version, error message, or notify user about logfile (only used by SOILWAT2) */
+    printProgressMsg; /**< Do/don't print progress messages to the console */
 } LOG_INFO;
 
 typedef struct {
@@ -1066,6 +1067,7 @@ typedef struct {
     char *InFilesNC[SW_NVARNC];
 
     int ncFileIDs[SW_NVARNC];
+    int ncVarIDs[SW_NVARNC];
 } SW_NETCDF;
 
 /* =================================================== */

include/SW_netCDF.h

@@ -12,6 +12,7 @@ extern "C" {
 /* --------------------------------------------------- */
 
 #define vNCdom 0 // Domain netCDF index within `InFilesNC` and `varNC` (SW_NETCDF)
+#define vNCprog 1 // Progress netCDF index within `InFilesNC` and `varNC` (SW_NETCDF)
 
 #define DOMAIN_TEMP "Input_nc/domain_template.nc"
 
@@ -21,17 +22,26 @@ extern "C" {
 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_create_template(const char* domFile, int domFileID,
+    const char* fileName, int* newFileID, int newVarType,
+    unsigned long timeSize, unsigned long vertSize, const char* varName,
+    const char* attNames[], const char* attVals[], int numAtts, Bool isInput,
+    const char* freq, LOG_INFO* LogInfo);
+void SW_NC_create_progress(SW_DOMAIN* SW_Domain, LOG_INFO* LogInfo);
+void SW_NC_set_progress(Bool isFailure, const char* domType, int progFileID,
+                        int progVarID, unsigned long ncSUID[],
+                        LOG_INFO* LogInfo);
+Bool SW_NC_check_progress(int progFileID, int progVarID,
+                          unsigned long ncSUID[], 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_open_dom_prog_files(SW_NETCDF* SW_netCDF, LOG_INFO* LogInfo);
 void SW_NC_close_files(SW_NETCDF* SW_netCDF);
+void SW_NC_deepCopy(SW_NETCDF* source, SW_NETCDF* dest, LOG_INFO* LogInfo);
 
 #ifdef __cplusplus
 }

include/Times.h

@@ -99,6 +99,7 @@ double diff_walltime(WallTimeSpec start, Bool ok_start);
 void SW_WT_StartTime(SW_WALLTIME *wt);
 void SW_WT_TimeRun(WallTimeSpec ts, Bool ok_ts, SW_WALLTIME *wt);
 void SW_WT_ReportTime(SW_WALLTIME wt, LOG_INFO* LogInfo);
+void timeStringISO8601(char *timeString, int stringLength);
 
 #ifdef __cplusplus
 }

include/filefuncs.h

@@ -32,6 +32,7 @@ Bool MkDir(const char *dname, LOG_INFO* LogInfo);
 Bool RemoveFiles(const char *fspec, LOG_INFO* LogInfo);
 Bool CopyFile(const char *from, const char *to, LOG_INFO* LogInfo);
 void LogError(LOG_INFO* LogInfo, const int mode, const char *fmt, ...);
+void sw_message(const char *msg);
 
 int key_to_id(const char* key, const char **possibleKeys,
                      int numPossKeys);

makefile

@@ -80,10 +80,11 @@ SHELL = /bin/sh
 
 #------ Identification
 SW2_VERSION := "$(shell git describe --abbrev=7 --dirty --always --tags)"
-HOSTNAME := "$(shell uname -sn)"
+HOSTNAME ?= "$(shell uname -sn)"
+USERNAME ?= "$(USER)"
 
 sw_info := -DSW2_VERSION=\"$(SW2_VERSION)\" \
-					-DUSERNAME=\"$(USER)\" \
+					-DUSERNAME=\"$(USERNAME)\" \
 					-DHOSTNAME=\"$(HOSTNAME)\"
 
 

src/SW_Control.c

@@ -210,10 +210,25 @@ void SW_CTL_RunSimSet(SW_ALL *sw_template, SW_OUTPUT_POINTERS SW_OutputPtrs[],
     char tag_suid[32]; /* 32 = 11 character for "(suid = ) " + 20 character for ULONG_MAX + '\0' */
     tag_suid[0] = '\0';
     WallTimeSpec tss, tsr;
-    Bool ok_tss = swFALSE, ok_tsr = swFALSE;
+    Bool ok_tss = swFALSE, ok_tsr = swFALSE, ok_suid;
+
+    int progFileID = 0; // Value does not matter if SWNETCDF is not defined
+    int progVarID = 0; // Value does not matter if SWNETCDF is not defined
+
+    #if defined(SWNETCDF)
+    progFileID = SW_Domain->netCDFInfo.ncFileIDs[vNCprog];
+    progVarID = SW_Domain->netCDFInfo.ncVarIDs[vNCprog];
+    #endif
 
     set_walltime(&tss, &ok_tss);
 
+    #if defined(SOILWAT)
+    if(main_LogInfo->printProgressMsg) {
+        sw_message("is running simulations across the domain ...");
+    }
+    #endif
+
+    /* Loop over suids in simulation set of domain */
     for(suid = SW_Domain->startSimSet; suid < SW_Domain->endSimSet; suid++)
     {
         /* Check wall time against limit */
@@ -229,41 +244,53 @@ void SW_CTL_RunSimSet(SW_ALL *sw_template, SW_OUTPUT_POINTERS SW_OutputPtrs[],
 
         LOG_INFO local_LogInfo;
         sw_init_logs(main_LogInfo->logfp, &local_LogInfo);
+        local_LogInfo.printProgressMsg = main_LogInfo->printProgressMsg;
+
 
+        /* Check if suid needs to be simulated */
         SW_DOM_calc_ncSuid(SW_Domain, suid, ncSuid);
-        if(SW_DOM_CheckProgress(SW_Domain->DomainType, ncSuid)) {
 
-            nSims++; // Counter of simulation runs
+        ok_suid = SW_DOM_CheckProgress(progFileID, progVarID, ncSuid,
+                                       &local_LogInfo);
 
+        if(ok_suid && !local_LogInfo.stopRun) {
+            /* Count simulation run */
+            nSims++;
+
+            /* Simulate suid */
             set_walltime(&tsr, &ok_tsr);
             SW_CTL_run_sw(sw_template, SW_Domain, ncSuid,
                           SW_OutputPtrs, NULL, &local_LogInfo);
             SW_WT_TimeRun(tsr, ok_tsr, SW_WallTime);
 
-            if(local_LogInfo.stopRun) {
-                main_LogInfo->numDomainErrors++; // Counter of simulation units with error
+            /* Report progress for suid */
+            SW_DOM_SetProgress(local_LogInfo.stopRun,
+                               SW_Domain->DomainType, progFileID,
+                               progVarID, ncSuid, &local_LogInfo);
+        }
 
-            } else {
-                // Set simulation run progress
-                SW_DOM_SetProgress(SW_Domain->DomainType, ncSuid);
-            }
+        /* Report errors and warnings for suid */
+        if(local_LogInfo.stopRun) {
+            main_LogInfo->numDomainErrors++; // Counter of simulation units with error
+        }
 
-            if (local_LogInfo.numWarnings > 0) {
-                main_LogInfo->numDomainWarnings++;  // Counter of simulation units with warnings
-            }
+        if (local_LogInfo.numWarnings > 0) {
+            main_LogInfo->numDomainWarnings++;  // Counter of simulation units with warnings
+        }
 
-            if (local_LogInfo.stopRun || local_LogInfo.numWarnings > 0) {
-                snprintf(tag_suid, 32, "(suid = %lu) ", suid + 1);
-                sw_write_warnings(tag_suid, &local_LogInfo);
-            }
+        if (local_LogInfo.stopRun || local_LogInfo.numWarnings > 0) {
+            snprintf(tag_suid, 32, "(suid = %lu) ", suid + 1);
+            sw_write_warnings(tag_suid, &local_LogInfo);
         }
     }
 
-    if (nSims == main_LogInfo->numDomainErrors) {
+    /* Produce global error if all suids failed */
+    if (nSims > 0 && nSims == main_LogInfo->numDomainErrors) {
         LogError(
             main_LogInfo,
             LOGERROR,
-            "All simulated units produced errors."
+            "All simulated units (n = %zu) produced errors.",
+            nSims
         );
     }
 
@@ -364,7 +391,7 @@ void SW_CTL_setup_domain(unsigned long userSUID,
     }
 
     // Open necessary netCDF input files and check for consistency with domain
-    SW_NC_open_files(&SW_Domain->netCDFInfo, LogInfo);
+    SW_NC_open_dom_prog_files(&SW_Domain->netCDFInfo, LogInfo);
     if(LogInfo->stopRun) {
         return; // Exit function prematurely due to error
     }
@@ -376,6 +403,11 @@ void SW_CTL_setup_domain(unsigned long userSUID,
     }
     #endif
 
+    SW_DOM_CreateProgress(SW_Domain, LogInfo);
+    if(LogInfo->stopRun) {
+        return; // Exit function prematurely due to error
+    }
+
     SW_DOM_SimSet(SW_Domain, userSUID, LogInfo);
 }