updating develop branch which has fallen behind master

INSTALL.md

@@ -1,14 +1,25 @@
-# Installation instructions
+# Installation and example instructions
 
-1. Clone the online github repository either from the main git repo source (https://github.com/NOAA-OWP/snow17.git) or your fork of it. 
-   cmd:  `clone [github source]`
+1. Clone the online GitHub repository either from the main git repo source (https://github.com/NOAA-OWP/snow17.git) or your fork of it -- e.g., `git clone https://github.com/NOAA-OWP/snow17.git`
 2. Change directory to the build directory: `cd snow17/build/`
-3. Copy `Makefile` to `Makefile.local` and edit the local version to update the compiler and paths if necessary to match the resources on your system.
-4. Run `make -f Makefile.local` to compile the program and generate the executable, which will be found in `snow17/bin/`
-5. There is a test case in the `snow17/test_cases/` directory.  To run it, first cd to the directory and unpack the example:  `tar -xzvf ex1.tgz`.
-6. cd into `ex1/run/` directory and run the shell script (`./runSnow17.csh`) or type `../../../bin/snow17.exe namelist.HHWM8` into your command line
-7. Check the example output in `snow17/test_cases/ex1//output/`
+3. Copy `Makefile` to `Makefile.local` (`cp Makefile Makefile.local`) and edit the local version to update the compiler and paths if necessary to match the resources on your system.
+4. Run `make -f MakefileLocal` to compile the program and generate the executable, which will be found in `snow17/bin/`
+5. There is a test case in the `snow17/test_cases/` directory.  To run it, first cd to the directory (`cd ../test_cases/`) and unpack the example:  `tar -xzvf ex1.tgz`.
+6. `cd ex1/run/` to get to the run directory and then execute the shell script (`./runSnow17.csh`) or type `../../../bin/snow17.exe namelist.bmi.HHWM8` into your command line
+7. Check the example in the output folder (`cd ../output/`)
 
+TL;DR:
+```
+git clone https://github.com/NOAA-OWP/snow17.git
+cd snow17/build/
+cp Makefile MakefileLocal # edit to match your compiler and system resources
+make -f MakefileLocal
+cd ../test_cases/
+tar -xzvf ex1.tgz
+cd ex1/run/
+./runSnow17.csh           # or ../../../bin/snow17.exe namelist.bmi.HHWM8
+cd ../output/             # to view output data 
+```
 Note that the ex1/ example is part of the repo.  The unpacked directory and test contents will not be included in a push back to the online repo.  To the program for other purposes, create new input files and output directories outside of the `snow17/` repository directory, and link to the executable in `snow17/bin/`. 
 
 

README.md

@@ -4,18 +4,15 @@
 
 Snow17 is a snow accumulation and melt model that has been used by the National Weather Service since the late 1970s for operational streamflow 
 forecasting.  It is a temperature-index model that was first described in Anderson (1973) before being incorporated into the NWS River Forecasting System (NWSRFS) and more recently the NWS Community Hydrologic Prediction System (CHPS).  The version of the Snow17 model maintained in this directory is formulated from original NWS FORTRAN code to be compatible with 
-the NextGen simulation and forecasting framework. 
+the [Next Generation Water Resources Modeling Framework](https://github.com/NOAA-OWP/ngen) (NextGen). 
 
-  - **Technology stack**: The model code is written in FORTRAN with a driver that incorporates Basic Model Interface (BMI) commands to enable Snow17 to be run as a module within the NextGen framework. 
-  is intended as standalone or as a module in a framework or other ecosystem.  It has been compiled using gnu, pgi and intel compilers. 
-  - **Status**: Beta (runs but has not been extensively tested; validates against the orginal repository version listed below, which has been extensively used))
-  - **Links**:  This code was adapted from source code included in https://github.com/NCAR/NWS_hydro_models -- a version used in federally-funded streamflow forecasting research at NCAR. The original source code for that effort was obtained from the NWS Office of Hydrology around 2013. The code has since been copied and adapted into other research repositories. 
+  - **Technology stack**: The model code is written in Fortran with a driver that incorporates [Basic Model Interface](https://csdms.colorado.edu/wiki/BMI) (BMI) commands to enable Snow17 to be run in standalone mode or as a module within the NextGen framework (or other BMI-based systems). It has been compiled using GNU, PGI, and Intel compilers. 
+  - **Status**: Beta (runs but has not been extensively tested; validates against the orginal repository version listed below, which has been extensively used)
+  - **Links**:  This code was adapted from source code included in https://github.com/NCAR/NWS_hydro_models -- a version used in federally funded streamflow forecasting research at NCAR. The original source code for that effort was obtained from the NWS Office of Hydrology around 2013. The code has since been copied and adapted into other research repositories. 
 
 ## Dependencies
 
-TBA: Describe any dependencies that must be installed for this software to work.
-This includes programming languages, databases or other storage mechanisms, build tools, frameworks, and so forth.
-If specific versions of other software are required, or known not to work, call that out.
+There are no current dependencies except for a Fortran-compatible compiler (e.g., GFortran)
 
 ## Installation
 
@@ -27,21 +24,20 @@ TBA:  If the software is configurable, describe it in detail, either here or in
 
 ## How to test the software
 
-Run the included test case example -- see INSTALL.md
+Run the included test case example -- see the [INSTALL](INSTALL.md) document.
 
 ## Known issues
 
 The restart capability has not been implemented, but will be shortly. 
-The software has so far only been tested with the gfortran compiler (on Cheyenne at NCAR)
+The software has so far only been tested with the GFortran compiler (on Cheyenne at NCAR)
 
 ## Getting help
 
-Currently, questions may be sent to Andy Wood (andywood@ucar.edu). 
 If there are concerns or bug fixes, etc., please  file an issue in this repository's Issue Tracker.
 
 ## Getting involved
 
-We encourage community involvement in code development. For more info, please check out our CONTRIBUTING document.
+We encourage community involvement in code development. For more info, please check out our [CONTRIBUTING](CONTRIBUTING.md) document.
 
 ----
 
@@ -56,37 +52,4 @@ We encourage community involvement in code development. For more info, please ch
 If you wish to use or adapt the code in this repository, please make sure that your new repository credits this one as the original source of the code. 
 
 ### References
- - Anderson, E. A., 1973: National Weather Service River Forecast System-Snow Accumulation and Ablation Model. NOAA Tech. Memo. NWS Hydro-17, U.S. National Weather Service. [Avail- able from Office of Hydrologic Development, NOAA/NWS, 1325 East–West Highway, Silver Spring, MD 20910.]
-
-### Related projects
-
-### Books, papers, talks, or other sources that have meaningful impact or influence on this project
-
-
-----
-----
-
-#### OWP Open Source Project Template Instructions
-
-1. Create a new project.
-2. [Copy these files into the new project](#installation)
-3. Update the README, replacing the contents below as prescribed.
-4. Add any libraries, assets, or hard dependencies whose source code will be included
-   in the project's repository to the _Exceptions_ section in the [TERMS](TERMS.md).
-  - If no exceptions are needed, remove that section from TERMS.
-5. If working with an existing code base, answer the questions on the [open source checklist](opensource-checklist.md)
-6. Delete these instructions and everything up to the _Project Title_ from the README.
-7. Write some great software and tell people about it.
-
-> Keep the README fresh! It's the first thing people see and will make the initial impression.
-
-## Installation
-
-To install all of the template files, run the following script from the root of your project's directory:
-
-```
-bash -c "$(curl -s https://raw.githubusercontent.com/NOAA-OWP/owp-open-source-project-template/open_source_template.sh)"
-```
-
-----
-
+ - Anderson, E. A., 1973: National Weather Service River Forecast System-Snow Accumulation and Ablation Model. NOAA Tech. Memo. NWS Hydro-17, U.S. National Weather Service. [Avail- able from Office of Hydrologic Development, NOAA/NWS, 1325 East–West Highway, Silver Spring, MD 20910.]

build/Makefile

@@ -45,9 +45,9 @@ endif
 
 # --- Define flags
 ifeq "$(FC)" "gfortran"
-  FLAGS_DEBUG = -static -Wall -g -ffree-line-length-none -cpp -fcheckall
-  FLAGS = -O3 -fdefault-real-8 -fno-align-commons -ffree-line-length-none -cpp -fcheckall
-  FLAGS2 = -O3 -fdefault-real-8 -fno-align-commons -ffree-line-length-none -cpp -fcheckall
+  FLAGS_DEBUG = -static -Wall -g -ffree-line-length-none -cpp -fcheck=all
+  FLAGS = -O3 -fdefault-real-8 -fno-align-commons -ffree-line-length-none -cpp -fcheck=all
+  FLAGS2 = -O3 -fdefault-real-8 -fno-align-commons -ffree-line-length-none -cpp -fcheck=all
 endif
 
 ifeq "$(FC)" "ifort"

src/bmi/bmi_snow17.f90

@@ -98,7 +98,7 @@ module bmi_snow17_module
 
   ! Exchange items
   integer, parameter :: input_item_count = 2
-  integer, parameter :: output_item_count = 4
+  integer, parameter :: output_item_count = 6
   character (len=BMI_MAX_VAR_NAME), target, &
        dimension(input_item_count) :: input_items
   character (len=BMI_MAX_VAR_NAME), target, &
@@ -155,10 +155,12 @@ function snow17_output_var_names(this, names) result (bmi_status)
     character (*), pointer, intent(out) :: names(:)
     integer :: bmi_status
 
-    output_items(1) = 'precip_scf'   ! precip after scf scaling (mm)
-    output_items(2) = 'sneqv'        ! snow water equivalent (mm)
-    output_items(3) = 'snowh'        ! snow height (mm)
-    output_items(4) = 'raim'         ! rain plus snowmelt (mm/s)
+    output_items(1) = 'tair'         ! tair (degC)
+    output_items(2) = 'precip'       ! precip (mm/s)
+    output_items(3) = 'precip_scf'   ! precip after scf scaling (mm/s)
+    output_items(4) = 'sneqv'        ! snow water equivalent (mm)
+    output_items(5) = 'snowh'        ! snow height (mm)
+    output_items(6) = 'raim'         ! precipitation (liquid) plus snowmelt (mm/s)
 
     names => output_items
     bmi_status = BMI_SUCCESS
@@ -193,7 +195,7 @@ function snow17_start_time(this, time) result (bmi_status)
     double precision, intent(out) :: time
     integer :: bmi_status
 
-    !time = 0.d0                                            ! time relative to start time (s) == 0
+    !time = 0.d0                                           ! time relative to start time (s) == 0
     time = dble(this%model%runinfo%start_datetime)         ! using unix time (s)
 
     bmi_status = BMI_SUCCESS
@@ -206,7 +208,7 @@ function snow17_end_time(this, time) result (bmi_status)
     integer :: bmi_status
 
     !time = dble(this%model%runinfo%ntimes * this%model%runinfo%dt)  ! time relative to start time (s)
-    time = dble(this%model%runinfo%end_datetime)                    ! using unix time (s)
+    time = dble(this%model%runinfo%end_datetime)                     ! using unix time (s)
 
     bmi_status = BMI_SUCCESS
   end function snow17_end_time
@@ -217,7 +219,7 @@ function snow17_current_time(this, time) result (bmi_status)
     double precision, intent(out) :: time
     integer :: bmi_status
 
-    !time = dble(this%model%runinfo%time_dbl)           ! time from start of run (s)
+    !time = dble(this%model%runinfo%time_dbl)        ! time from start of run (s)
     time = dble(this%model%runinfo%curr_datetime)    ! unix time (s)
     bmi_status = BMI_SUCCESS
   end function snow17_current_time
@@ -255,34 +257,23 @@ end function snow17_update
   function snow17_update_until(this, time) result (bmi_status)
     class (bmi_snow17), intent(inout) :: this
     double precision, intent(in) :: time
+    ! local variables
     integer :: bmi_status
-    double precision :: n_steps_real
-    integer :: n_steps, i, s
+    double precision :: tmp_time
+    integer :: s
 
-    ! new code to work with unix time convention
     ! check to see if desired time to advance to is earlier than current time (can't go backwards)
     if (time < this%model%runinfo%curr_datetime) then
        bmi_status = BMI_FAILURE
        return
     end if
     ! otherwise try to advance to end time
-    do while ( time < this%model%runinfo%end_datetime )
+    tmp_time = time
+    do while ( tmp_time < this%model%runinfo%end_datetime )
        s = this%update()
+       tmp_time = this%model%runinfo%curr_datetime
     end do
 
-    ! original code working with time run convention from 0 to n*dt end_time
-    !if (time < this%model%runinfo%time_dbl) then
-    !   bmi_status = BMI_FAILURE
-    !   return
-    !end if
-
-    !n_steps_real = (time - this%model%runinfo%time_dbl) / this%model%runinfo%dt
-    !n_steps = floor(n_steps_real)
-    !do i = 1, n_steps
-    !   s = this%update()
-    !end do
-    !     call update_frac(this, n_steps_real - dble(n_steps)) ! NOT IMPLEMENTED
-
     bmi_status = BMI_SUCCESS
   end function snow17_update_until
 
@@ -294,8 +285,8 @@ function snow17_var_grid(this, name, grid) result (bmi_status)
     integer :: bmi_status
 
     select case(name)
-    case('tair', 'precip', &     ! input vars
-         'precip_scf', 'sneqv', 'snowh', 'raim')        ! output vars
+    case('tair', 'precip', &                       ! input/output vars (can pass forc to output)
+         'precip_scf', 'sneqv', 'snowh', 'raim')   ! output vars
        grid = 0
        bmi_status = BMI_SUCCESS
     case default
@@ -565,7 +556,7 @@ function snow17_var_type(this, name, type) result (bmi_status)
     integer :: bmi_status
 
     select case(name)
-    case('tair', 'precip', &     ! input vars
+    case('tair', 'precip', &                            ! input/output vars
          'precip_scf', 'sneqv', 'snowh', 'raim')        ! output vars
        type = "real"
        bmi_status = BMI_SUCCESS
@@ -584,13 +575,13 @@ function snow17_var_units(this, name, units) result (bmi_status)
 
     select case(name)
     case("precip")
-       units = "mm"
+       units = "mm/s"
        bmi_status = BMI_SUCCESS
     case("tair")
-       units = "C"
+       units = "degC"
        bmi_status = BMI_SUCCESS
     case("precip_scf")
-       units = "mm"
+       units = "mm/s"
        bmi_status = BMI_SUCCESS
     case("sneqv")
        units = "mm"
@@ -599,7 +590,7 @@ function snow17_var_units(this, name, units) result (bmi_status)
        units = "mm"
        bmi_status = BMI_SUCCESS
     case("raim")
-       units = "mm"
+       units = "mm/s"
        bmi_status = BMI_SUCCESS
     case default
        units = "-"
@@ -613,25 +604,28 @@ function snow17_var_itemsize(this, name, size) result (bmi_status)
     character (len=*), intent(in) :: name
     integer, intent(out) :: size
     integer :: bmi_status
+
+    ! note: the combined variables are used assuming ngen is interacting with the
+    !       catchment-averaged result if snowbands are used
 
     select case(name)
     case("precip")
-       size = sizeof(this%model%forcing%precip_comb)    ! 'sizeof' in gcc & ifort
+       size = sizeof(this%model%forcing%precip(1))    ! 'sizeof' in gcc & ifort
        bmi_status = BMI_SUCCESS
     case("tair")
-       size = sizeof(this%model%forcing%tair_comb)      ! 'sizeof' in gcc & ifort
+       size = sizeof(this%model%forcing%tair(1))
        bmi_status = BMI_SUCCESS
     case("precip_scf")
-       size = sizeof(this%model%forcing%precip_scf_comb)     ! 'sizeof' in gcc & ifort
+       size = sizeof(this%model%forcing%precip_scf_comb)
        bmi_status = BMI_SUCCESS
     case("sneqv")
-       size = sizeof(this%model%modelvar%sneqv_comb)     ! 'sizeof' in gcc & ifort
+       size = sizeof(this%model%modelvar%sneqv_comb)
        bmi_status = BMI_SUCCESS
     case("snowh")
-       size = sizeof(this%model%modelvar%snowh_comb)     ! 'sizeof' in gcc & ifort
+       size = sizeof(this%model%modelvar%snowh_comb)
        bmi_status = BMI_SUCCESS
     case("raim")
-       size = sizeof(this%model%modelvar%raim_comb)      ! 'sizeof' in gcc & ifort
+       size = sizeof(this%model%modelvar%raim_comb)
        bmi_status = BMI_SUCCESS
     case default
        size = -1
@@ -701,10 +695,10 @@ function snow17_get_float(this, name, dest) result (bmi_status)
 
     select case(name)
     case("precip")
-       dest(1) = this%model%forcing%precip_comb
+       dest(1) = this%model%forcing%precip(1)
        bmi_status = BMI_SUCCESS
     case("tair")
-       dest(1) = this%model%forcing%tair_comb
+       dest(1) = this%model%forcing%tair(1)
        bmi_status = BMI_SUCCESS
     case("precip_scf")
        dest(1) = this%model%forcing%precip_scf_comb
@@ -872,24 +866,27 @@ function snow17_set_float(this, name, src) result (bmi_status)
     real, intent(in) :: src(:)
     integer :: bmi_status
 
+    ! NOTE: if run in a vector (snowband mode), this code will need revising
+    !       to set the basin average (ie, restart capability)
+
     select case(name)
     case("precip")
-       this%model%forcing%precip_comb = src(1)
+       this%model%forcing%precip(1) = src(1)
        bmi_status = BMI_SUCCESS
     case("tair")
-       this%model%forcing%tair_comb = src(1)
+       this%model%forcing%tair(1) = src(1)
        bmi_status = BMI_SUCCESS
     case("precip_scf")
-       this%model%forcing%precip_scf_comb = src(1)
+       this%model%forcing%precip_scf(1) = src(1)
        bmi_status = BMI_SUCCESS
     case("sneqv")
-       this%model%modelvar%sneqv_comb = src(1)
+       this%model%modelvar%sneqv(1) = src(1)
        bmi_status = BMI_SUCCESS
     case("snowh")
-       this%model%modelvar%snowh_comb = src(1)
+       this%model%modelvar%snowh(1) = src(1)
        bmi_status = BMI_SUCCESS
     case("raim")
-       this%model%modelvar%raim_comb = src(1)
+       this%model%modelvar%raim(1) = src(1)
        bmi_status = BMI_SUCCESS
     case default
        bmi_status = BMI_FAILURE

src/driver/driver_bmi.f90

@@ -66,11 +66,10 @@ program multi_driver
   print*, 'Running model => start: ', start_datehr, ' end: ', end_datehr, ' timesteps: ', int((end_time - current_time)/dt)
   print*,'----'
 
-  ! loop through while current time <= end time (
+  ! loop through timesteps and update model while current time <= end time (
   do while (current_time .le. end_time)
-    !print*, 'Current time:', current_time
     status = m%update()                       ! run the model one time step
-    status = m%get_current_time(current_time) ! update current_time
+    status = m%get_current_time(current_time) ! get updated current_time 
   end do
 
   !---------------------------------------------------------------------

src/share/forcingType.f90

@@ -9,10 +9,10 @@ module forcingType
 type, public :: forcing_type
 
   ! atmospheric inputs & outputs (surface meteorology)
-  real, dimension(:), allocatable   :: tair       ! surface air temperature [K]
+  real, dimension(:), allocatable   :: tair       ! surface air temperature [degC]
   real, dimension(:), allocatable   :: precip     ! total input precipitation [mm/s]
   real, dimension(:), allocatable   :: precip_scf ! total input precipitation with SCF applied [mm/s]
-  real, dimension(:), allocatable   :: pa         ! snow17 surface pressure (Pa) 
+  real, dimension(:), allocatable   :: pa         ! snow17 surface pressure [Pa] 
   real                              :: precip_comb, precip_scf_comb, tair_comb    ! areally averaged forcings across HRUs
 
   contains