Merge pull request #115 from UW-SASWE/low_latency

Updated docs: actual ST forecasting scenario

docs/Development/PatchNotes.md

@@ -4,13 +4,14 @@
 In this release, we have:
 
 1. **Enhanced Low-Latency Functionality:** RAT can now run in operational mode with significantly reduced latency as low as 0.  
-2. **Updated Forecasting Plugin:** The forecasting plugin has been upgraded to allow forecast generation for multiple past dates.  
+2. **Updated Forecasting Plugin:** The forecasting plugin has been upgraded to allow forecast generation for multiple past dates. Also, user can now provide scenarios to get forecasted outflow. One of the scenarios is 'ST' where user can provide different values of storage change expressed as a percentage of maximum reservoir capacity.
 3. **Updated IMERG Precipitation Web Links:** The web links for downloading historical IMERG data (prior to 2024) have been updated to match those for current data. This change reflects the revision of the IMERG product version for historical data to V07B, which is now the same as the version for recent IMERG data. These updates were implemented on June 1, 2024, on the IMERG web servers.
 4. **Updated RAT documentation:** To reflect the changes in the forecasting plugin and the possibility of using low latency in operational mode.
 
 !!!note
     1. Previously, a latency of 3 or more days was recommended due to delays in retrieving meteorological data from servers. However, RAT can now operate with latencies of less than 3 days, including real-time data (0-day latency). This is a major improvement over earlier versions, enabling users to generate data for the current day and produce forecasts up to 15 days ahead from the current day.
     2. Previously, forecasts could only be generated for the final date of the RAT run, which worked well for operational use. Now, for case studies and research purposes, users can generate forecasts for several historical dates, offering greater flexibility and utility.
+    3. If a user selects the 'ST' scenario, the current storage of the reservoir is estimated using a probability distribution function of the surface area time series, provided the time series is sufficiently long. The scenario where the storage changes from the current storage level to the maximum reservoir storage level is also included as part of the forecast scenarios for predicting outflow in this case.
 
 ### v3.0.13
 In this release, we have:

docs/Plugins/Forecasting.md

@@ -15,15 +15,22 @@ PLUGINS:
 	forecast_reservoir_shpfile_column_dict: {column_id: GRAND_ID, column_capacity: CAP_MCM}
 	forecast_vic_init_state: 			# path of VIC state file or date in YYYY-MM-DD format (Optional)
 	forecast_rout_init_state: 			# path of Routing state file or date in YYYY-MM-DD format (Optional)
-	forecast_storage_scenario: [ST, GO, CO]
+	forecast_storage_scenario: [ST, GO, GC, RC]
   	forecast_storage_change_percent_of_smax: [20, 10, 5]
 ```
 
-The `forecast_gen_start_date` option controls when the generation of forecast will begin. If the value is set to `end_date`, the forecast will begin on the end date of RAT’s normal mode of running, i.e., in nowcast mode, which are controlled by `start_date` and `end_date` options in the BASIN section. Alternatively, a date in the YYYY-MM-DD format can also be provided to start the generation of forecast from that date. The `forecast_gen_end_date` option defines the end date for which forecasts will be generated. The forecast window for each date when the forecast is being generated or the number of days ahead for which the forecast is generated is controlled by the `forecast_lead_time` option, with a maximum of 15 days ahead.  The `forecast_rule_curve_dir` option should point to the directory containing the rule curve files for the reservoir. The `forecast_reservoir_shpfile_column_dict` option specifies the names of the columns that correspond to the ID and capacity of the reservoir, named `column_id` and `column_capacity`. These columns should be present in the [`reservoir_vector_file` in the GEE section](../../Configuration/rat_config/#gee) in the configuration file for running the forecasting plugin. The `forecast_vic_init_state` option can be used to define the date in 'YYYY-MM-DD' format of vic init file to be used. It can also be the path of the vic init state file that the user want to use. In case the path of vic init state file is provided instead of date, it is assumed that the state file is for the `forecast_gen_start_date`. Also, in this case, `forecast_rout_init_state` becomes a required parameter and has to be the actual path of the rout init state file.
+The `forecast_gen_start_date` option controls when the generation of forecast will begin. If the value is set to `end_date`, the forecast will begin on the end date of RAT’s normal mode of running, i.e., in nowcast mode, which are controlled by `start_date` and `end_date` options in the BASIN section. Alternatively, a date in the YYYY-MM-DD format can also be provided to start the generation of forecast from that date. The `forecast_gen_end_date` option defines the end date for which forecasts will be generated. The forecast window for each date when the forecast is being generated or the number of days ahead for which the forecast is generated is controlled by the `forecast_lead_time` option, with a maximum of 15 days ahead.   
+
+The `forecast_rule_curve_dir` option should point to the directory containing the rule curve files for the reservoir. The `forecast_reservoir_shpfile_column_dict` option specifies the names of the columns that correspond to the ID and capacity of the reservoir, named `column_id` and `column_capacity`. These columns should be present in the [`reservoir_vector_file` in the GEE section](../../Configuration/rat_config/#gee) in the configuration file for running the forecasting plugin. The `forecast_vic_init_state` option can be used to define the date in 'YYYY-MM-DD' format of vic init file to be used. It can also be the path of the vic init state file that the user want to use. In case the path of vic init state file is provided instead of date, it is assumed that the state file is for the `forecast_gen_start_date`. Also, in this case, `forecast_rout_init_state` becomes a required parameter and has to be the actual path of the rout init state file.  
+
+`forecast_storage_scenario` is a list of scenarios that a user can provide to RAT to assume storage change during the forecasting period. It can include options like 'GO' (Gates Open), 'GC' (Gates Closed) or 'RC' (Rule Curve based). Or the user can include an option 'ST' to specify the values of storage change during the forecasting period expressed as a percentage of the maximum reservoir capacity using the `forecast_storage_change_percent_of_smax`.
 
 !!!note
 	The files in the `forecast_rule_curve_dir` should be named according to their IDs, corresponding to the values in `column_id`. For instance, if the id of a reservoir is 7001, then the file name of the reservoir's rule curve should be `7001.txt`. The rule curve files should be in `.txt` format with the following columns - `Month,S/Smax`, corresponding to the month and the storage level as a fraction of the maximum storage level. Rule curve files for reservoirs in the [GRAND](https://www.globaldamwatch.org/grand) database can be downloaded [here](https://www.dropbox.com/scl/fi/jtquzasjdv2tz1vtupgq5/rc.zip?rlkey=4svbutjd3aup255pnrlgnxbkl&dl=0). 
 
+!!! tip_note "Tip"
+	If a user selects the 'ST' scenario, the current storage of the reservoir is estimated using a probability distribution function of the surface area time series, provided the time series is sufficiently long. Then the scenario where the storage changes from the current storage level to the maximum reservoir storage level is also included as part of the forecast scenarios for predicting outflow in this case.
+
 ## Forecasted inflow and evaporation 
 - The inflow to the reservoir is simulated using forecasted precipitation from Climate Hazards Center InfraRed Precipitation with Stations-Global Ensemble Forecasting System [(CHIRPS-GEFS)](https://chc.ucsb.edu/data/chirps-gefs) and forecasted temperature and wind data from Global Forecasting System [(GFS)](https://www.ncei.noaa.gov/products/weather-climate-models/global-forecast). CHIRPS-GEFS uses satellite and observations of precipitation (CHIRPS) for bias correction and downscaling of the Global Ensemble Forecasting System (GEFS) precipitation forecasts. The Global Forecasting System (GFS) is a Numerical Weather Prediction system for operational weather prediction which forecasts meteorological variables, including temperature and wind.
 - The forecasted meteorology is used to run the hydrological model component of RAT (MetSim + VIC + VIC Routing) to obtain forecasted streamflow and evaporation for each reservoir.