hydro/Routing/Reservoirs/RFC_Forecasts_Module_README.md

   1 # RFC Forecasts Module
   2
   3 ### General Purpose and Functionality
   4
   5 The purpose of this module is to integrate RFC (River Forecast Center) produced forecasts for individual reservoirs into
   6 the Reservoir module in real-time. This utilizes the expertise that each RFC has for forecasting reservoirs in their domain.
   7 This module replaces the normal Level Pool object for a particular reservoir that is selected to run as RFC_Forecast.
   8
   9
  10 ### Module Architecture
  11
  12 This module builds off of the same class structure and architecture of the Level Pool module. As in Level Pool, each reservoir in this
  13 module is instantiated into an object at model initialization. The **RFC_Forecasts** directory contains the following files:
  14
  15 * **module_rfc_forecasts.F** defines and instantiates objects for an rfc forecasts type
  16 reservoir. **module_RT.F** will call and pass parameters to the constructor in this module to instantiate the rfc forecasts reservoir
  17 object and its sub-objects. The rfc forecasts reservoir type inherits input and output types from the reservoir base module and calls
  18 instantiation of these into sub-objects. The rfc forecasts reservoir type also points to types for parameters and state and calls
  19 instantiation of these into sub-objects. This reservoir type will also point to and instantiate a corresponding level pool reservoir, that
  20 also runs at every timestep. The run function will output the corresponding discharges from the RFC time series discharge array. If the
  21 corresponding RFC time series file is not found or the array values are unusable, then the level pool output will be used instead.
  22
  23 * **module_rfc_forecasts_properties.F** defines and instantiates objects for an rfc forecasts type reservoir's
  24 properties. Properties holds static/unchanging variables that are set when the given reservoir object is
  25 initialized/instantiated.
  26
  27 * **module_rfc_forecasts_state.F** defines and instantiates objects for an rfc forecasts type reservoir's state.
  28 State holds and tracks dynamic/changing variables that are only relevant to the given reservoir object and not other
  29 modules or areas of the system.
  30
  31 * **module_rfc_forecasts_tests.F** holds unit tests that test for all components of an rfc forecasts reservoir
  32 are properly initialized.
  33
  34 * **module_reservoir_read_rfc_time_series_data.F**, within the **Reservoirs** directory, searches for and reads RFC time series
  35 forecast files for an array of time series forecast values.
  36
  37 ### Input Parameters
  38
  39 This module requires four input parameters that are set in hydro.namelist.
  40
  41 * ```reservoir_rfc_forecasts``` is a boolean parameter that will need to be set to ```.TRUE.``` for this module to be activated.
  42 This will set the model variable ```reservoir_type_specified``` to ```TRUE``` and cause the model to read the reservoir_type variable from the
  43 reservoir parameter file. The reservoir_type for a RFC (River Forecast Center) Forecast reservoir is currently set to '4' in the reservoir
  44 parameter file.
  45
  46 * ```reservoir_rfc_forecasts_time_series_path``` is the path to all the
  47 RFC time series files used by this module.
  48
  49 * ```reservoir_rfc_forecasts_lookback_hours``` is an integer parameter that specifies how many hours before the model start time the module will
  50 search for a corresponding time series file, and '28' would be a typical value and is the default.
  51
  52 * ```reservoir_parameter_file``` is the NetCDF parameter file that holds the corresponding gage ID for each lake ID.
  53
  54 ### Testing
  55
  56 To compile and run the unit tests, first go to the NDHMS directory and type
  57 ```
  58 ./compile_offline_NoahMP.sh template/setEnvar.sh
  59 ```
  60
  61 and hit enter. Then go to the Reservoir directory in the terminal and type
  62
  63 ```
  64 make
  65 ```
  66
  67 and hit enter. Then type
  68
  69 ```
  70 make test
  71 ```
  72
  73 and hit enter. Then type
  74
  75 ```
  76 ./reservoir_tests
  77 ```
  78
  79 and hit enter.
  80 The user should see "All Reservoir Tests Passed".