Added check to ensure mask variable in the input domain file is integ…

…er type (UW-Hydro#645)

* Added check to ensure mask varible in domain file is integer type

* Cleaned up some printing lines

* Added get_nc_var_type.c

* Minor update of comments and ReleaseNotes

* Added domain file description in docs

* Small fix of table in docs

* Added ncdump -h results for domain file in docs

* Minor docs update

docs/Development/ReleaseNotes.md

@@ -31,6 +31,8 @@ To check which release of VIC you are running:
 3. Fixed a problem with image restarts when using multiple processors ([GH#638](https://github.com/UW-Hydro/VIC/pull/638))
 
 	After the fix, only the master node is assigned the task of validating state file dimensions and coordinate variables. Multiprocessing was also added to the VIC testing framework.
+
+4. Ensured that the mask variable in the input domain file must be integer type; otherwise an error is raised. ([GH#645](https://github.com/UW-Hydro/VIC/pull/645))
 
 ------------------------------
 

docs/Documentation/Drivers/Image/Domain.md

@@ -0,0 +1,51 @@
+# VIC Domain file
+
+The Image Driver uses the [NetCDF](http://www.unidata.ucar.edu/software/netcdf/) file format to define model running domain.
+
+Below is a list of variables in the domain netCDF file. The dimensions of the netCDF file are `lat` and `lon`. Note that here only the type of variables (i.e., MASK, AREA, FRAC, LAT and LON) is listed; corresponding variable names in the input netCDF file are specified by user in the [Global Parameter File](GlobalParam.md). All the listed variables are required.
+
+| Variable   | Dimension   | Units    | Type   | Description |
+|------------|-------------|----------|--------|-------------|
+| LAT        | [lat]       | degree   | double | Latitudes   |
+| LON        | [lon]       | degree   | double | Longitues   |
+| MASK       | [lat, lon]  | N/A      | integer | Mask of VIC run. 1 for active cells for VIC run; 0 indicates inactive grid cells. VIC will not run at grid cells with MASK = 0 or missing value. |
+| AREA       | [lat, lon]  | m2       | double | Area of grid cells.   |
+| FRAC       | [lat, lon]  | N/A      | double | Fraction of grid cells that is land. |
+
+# Example netCDF format VIC 5 image driver domain file
+
+```shell
+ncdump -h /ArkRed.domain.nc
+netcdf ArkRed.domain {                                                                       
+dimensions:                                                                                  
+        lat = 66 ;                                                                           
+        lon = 125 ;                                                                          
+variables:                                                                                   
+        int mask(lat, lon) ;
+                mask:comment = "0 indicates grid cell is not active" ;
+                mask:long_name = "domain mask" ;
+        double lon(lon) ;
+                lon:long_name = "longitude coordinate" ;
+                lon:units = "degrees_east" ;
+        double lat(lat) ;
+                lat:long_name = "latitude coordinate" ;
+                lat:units = "degrees_north" ;
+        double frac(lat, lon) ;
+                frac:long_name = "fraction of grid cell that is active" ;
+                frac:units = "1" ;
+        double area(lat, lon) ;
+                area:standard_name = "area" ;
+                area:long_name = "area of grid cell" ;
+                area:units = "m2" ;
+
+// global attributes:
+                :title = "VIC domain data" ;
+                :Conventions = "CF-1.6" ;
+                :history = "Wed Oct 12 15:48:42 2016: ncap2 -s mask=int(mask) ArkRed.domain.nc.float_mask ArkRed.domain.nc\n",
+                        "created by ymao, 2016-09-23 18:17:58.761256" ;
+                :user_comment = "VIC domain data" ;
+                :source = "generated from VIC CONUS 1.8 deg model parameters, see Maurer et al. (2002) for more information" ;
+                :nco_openmp_thread_number = 1 ;
+}
+```
+

docs/Documentation/Drivers/Image/GlobalParam.md

@@ -157,7 +157,7 @@ See the [example file](#example-global-parameter-file) at the end of this page f
 
 # Define Domain file
 
-The folloiwng options describe the input domain file information.
+The folloiwng options describe the input domain file information. See [Domain File](Domain.md) for details about the domain file.
 
 | Name        | Type          | Units    | Description                                                                                                                                  |
 |-------------|---------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------|

docs/Documentation/Drivers/Image/Inputs.md

@@ -7,6 +7,7 @@ To run VIC, several sets of input data are necessary:
 *   [Global Parameter File](GlobalParam.md): This is the main input file for VIC. It points VIC to the locations of the other input/output files and sets parameters that govern the simulation (e.g., start/end dates, modes of operation).
 *   [Meteorological Forcing Files](ForcingData.md): Gridded, sub-daily timeseries of meteorological variables as inputs.
 *   [Parameters File](Params.md): Spatially distributed parameters describing the land surface.
+*   [Domain File](Domain.md): Domain information of VIC run.
 
 And a few more are optional:
 

mkdocs.yml

@@ -64,6 +64,7 @@ pages:
     - 'Inputs': 'Documentation/Drivers/Image/Inputs.md'
     - 'Outputs': 'Documentation/Drivers/Image/Outputs.md'
     - 'Params': 'Documentation/Drivers/Image/Params.md'
+    - 'Domain': 'Documentation/Drivers/Image/Domain.md'
     - 'RunVIC': 'Documentation/Drivers/Image/RunVIC.md'
     - 'Lake Param': 'Documentation/Drivers/Image/LakeParam.md'
     - 'StateFile': 'Documentation/Drivers/Image/StateFile.md'

vic/drivers/shared_image/include/vic_driver_shared_image.h

@@ -201,6 +201,7 @@ size_t get_global_domain(char *fname, domain_struct *global_domain,
 size_t get_nc_dimension(char *nc_name, char *dim_name);
 void get_nc_var_attr(char *nc_name, char *var_name, char *attr_name,
                      char **attr);
+int get_nc_var_type(char *nc_name, char *var_name);
 int get_nc_varndimensions(char *nc_name, char *var_name);
 int get_nc_field_double(char *nc_name, char *var_name, size_t *start,
                         size_t *count, double *var);

vic/drivers/shared_image/src/get_global_domain.c

@@ -35,6 +35,7 @@ get_global_domain(char          *nc_name,
                   bool           coords_only)
 {
     int    *run = NULL;
+    int     typeid;
     double *var = NULL;
     double *var_lon = NULL;
     double *var_lat = NULL;
@@ -60,6 +61,12 @@ get_global_domain(char          *nc_name,
     run = malloc(global_domain->ncells_total * sizeof(*run));
     check_alloc_status(run, "Memory allocation error.");
 
+    // Check whether mask variable is int type
+    typeid = get_nc_var_type(nc_name, global_domain->info.mask_var);
+    if (typeid != NC_INT) {
+        log_err("Mask variable in the domain file must be integer type.");
+    }
+
     get_nc_field_int(nc_name, global_domain->info.mask_var, d2start, d2count,
                      run);
 

vic/drivers/shared_image/src/get_nc_var_attr.c

@@ -27,7 +27,7 @@
 #include <vic_driver_shared_image.h>
 
 /******************************************************************************
- * @brief    Get netCDF dimension.
+ * @brief    Get netCDF variable attributes.
  *****************************************************************************/
 void
 get_nc_var_attr(char  *nc_name,

vic/drivers/shared_image/src/get_nc_var_type.c

@@ -0,0 +1,60 @@
+/******************************************************************************
+ * @section DESCRIPTION
+ *
+ * Get netCDF variable type.
+ *
+ * @section LICENSE
+ *
+ * The Variable Infiltration Capacity (VIC) macroscale hydrological model
+ * Copyright (C) 2016 The Computational Hydrology Group, Department of Civil
+ * and Environmental Engineering, University of Washington.
+ *
+ * The VIC model is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ *****************************************************************************/
+
+#include <vic_driver_shared_image.h>
+
+/******************************************************************************
+ * @brief    Get netCDF variable type.
+ *****************************************************************************/
+int
+get_nc_var_type(char  *nc_name,
+                char  *var_name)
+{
+    int    nc_id;
+    int    var_id;
+    int    status;
+    int    xtypep;
+
+    // open the netcdf file
+    status = nc_open(nc_name, NC_NOWRITE, &nc_id);
+    check_nc_status(status, "Error opening %s", nc_name);
+
+    // get variable id
+    status = nc_inq_varid(nc_id, var_name, &var_id);
+    check_nc_status(status, "Error getting variable id %s in %s", var_name,
+                    nc_name);
+
+    // get type ID
+    status = nc_inq_var(nc_id, var_id, NULL, &xtypep, NULL, NULL, NULL);
+    check_nc_status(status, "Error getting variable type %s in %s", var_name,
+                    nc_name);
+
+    // close the netcdf file
+    status = nc_close(nc_id);
+    check_nc_status(status, "Error closing %s", nc_name);
+
+    return(xtypep);
+}