GSSHA Framework

(Optional) Install spt_dataset_manager

Part of the code depends on spt_dataset_manager. This can be installed by following the instructions here: https://github.com/erdc-cm/spt_dataset_manager.

Warning

Make sure you have your Miniconda gssha environment activated during installation.

GSSHAFramework

class gsshapy.modeling.GSSHAFramework(gssha_executable, gssha_directory, project_filename, gssha_simulation_start=None, gssha_simulation_end=None, gssha_simulation_duration=None, load_simulation_datetime=False, spt_watershed_name=None, spt_subbasin_name=None, spt_forecast_date_string=None, ckan_engine_url=None, ckan_api_key=None, ckan_owner_organization=None, path_to_rapid_qout=None, connection_list_file=None, lsm_folder=None, lsm_data_var_map_array=None, lsm_precip_data_var=None, lsm_precip_type=None, lsm_lat_var=None, lsm_lon_var=None, lsm_time_var='time', lsm_lat_dim=None, lsm_lon_dim=None, lsm_time_dim='time', lsm_search_card='*.nc', precip_interpolation_type=None, event_min_q=None, et_calc_mode=None, soil_moisture_depth=None, output_netcdf=False, write_hotstart=False, read_hotstart=False, hotstart_minimal_mode=False)[source]

This class is for automating the connection between RAPID to GSSHA and LSM to GSSHA. There are several different configurations depending upon what you choose.

There are three options for RAPID to GSSHA:

  1. Download and run using forecast from the Streamflow Prediction Tool (See: https://streamflow-prediction-tool.readthedocs.io)
  2. Run from RAPID Qout file
  3. Don’t run using RAPID to GSSHA

There are two options for LSM to GSSHA:

  1. Run from LSM to GSSHA
  2. Don’t run using LSM to GSSHA
Parameters:
  • gssha_executable (str) – Path to GSSHA executable.
  • gssha_directory (str) – Path to directory for GSSHA project.
  • project_filename (str) – Name of GSSHA project file.
  • gssha_simulation_start (Optional[datetime]) – Datetime object with date of start of GSSHA simulation.
  • gssha_simulation_end (Optional[datetime]) – Datetime object with date of end of GSSHA simulation.
  • gssha_simulation_duration (Optional[timedelta]) – Datetime timedelta object with duration of GSSHA simulation.
  • load_simulation_datetime (Optional[bool]) – If True, this will load in datetime information from the project file. Default is False.
  • spt_watershed_name (Optional[str]) – Streamflow Prediction Tool watershed name.
  • spt_subbasin_name (Optional[str]) – Streamflow Prediction Tool subbasin name.
  • spt_forecast_date_string (Optional[str]) – Streamflow Prediction Tool forecast date string.
  • ckan_engine_url (Optional[str]) – CKAN engine API url.
  • ckan_api_key (Optional[str]) – CKAN api key.
  • ckan_owner_organization (Optional[str]) – CKAN owner organization.
  • path_to_rapid_qout (Optional[str]) – Path to the RAPID Qout file. Use this if you do NOT want to download the forecast and you want to use RAPID streamflows.
  • connection_list_file (Optional[str]) – CSV file with list connecting GSSHA rivers to RAPID river network. See: http://rapidpy.readthedocs.io/en/latest/rapid_to_gssha.html
  • lsm_folder (Optional[str]) – Path to folder with land surface model data. See: lsm_input_folder_path variable at GRIDtoGSSHA().
  • lsm_data_var_map_array (Optional[str]) – Array with connections for LSM output and GSSHA input. See: ()
  • lsm_precip_data_var (Optional[list or str]) – String of name for precipitation variable name or list of precip variable names. See: lsm_precip_to_gssha_precip_gage().
  • lsm_precip_type (Optional[str]) – Type of precipitation. See: lsm_precip_to_gssha_precip_gage().
  • lsm_lat_var (Optional[str]) – Name of the latitude variable in the LSM netCDF files. See: GRIDtoGSSHA().
  • lsm_lon_var (Optional[str]) – Name of the longitude variable in the LSM netCDF files. See: GRIDtoGSSHA().
  • lsm_time_var (Optional[str]) – Name of the time variable in the LSM netCDF files. See: GRIDtoGSSHA().
  • lsm_lat_dim (Optional[str]) – Name of the latitude dimension in the LSM netCDF files. See: GRIDtoGSSHA().
  • lsm_lon_dim (Optional[str]) – Name of the longitude dimension in the LSM netCDF files. See: GRIDtoGSSHA().
  • lsm_time_dim (Optional[str]) – Name of the time dimension in the LSM netCDF files. See: GRIDtoGSSHA().
  • lsm_search_card (Optional[str]) – Glob search pattern for LSM files. See: GRIDtoGSSHA().
  • precip_interpolation_type (Optional[str]) – Type of interpolation for LSM precipitation. Can be “INV_DISTANCE” or “THIESSEN”. Default is “THIESSEN”.
  • event_min_q (Optional[double]) – Threshold discharge for continuing runoff events in m3/s. Default is 60.0.
  • et_calc_mode (Optional[str]) – Type of evapo-transpitation calculation for GSSHA. Can be “PENMAN” or “DEARDORFF”. Default is “PENMAN”.
  • soil_moisture_depth (Optional[double]) – Depth of the active soil moisture layer from which ET occurs (m). Default is 0.0.
  • output_netcdf (Optional[bool]) – If you want the HMET data output as a NetCDF4 file for input to GSSHA. Default is False.
  • write_hotstart (Optional[bool]) – If you want to automatically generate all hotstart files, set to True. Default is False.
  • read_hotstart (Optional[bool]) – If you want to automatically search for and read in hotstart files, set to True. Default is False.
  • hotstart_minimal_mode (Optional[bool]) – If you want to turn off all outputs to only generate the hotstart file, set to True. Default is False.

Example modifying parameters during class initialization:

from gsshapy.modeling import GSSHAFramework

gssha_executable = 'C:/Program Files/WMS 10.1 64-bit/gssha/gssha.exe'
gssha_directory = "C:/Users/{username}/Documents/GSSHA"
project_filename = "gssha_project.prj"

#WRF INPUTS
lsm_folder = '"C:/Users/{username}/Documents/GSSHA/wrf-sample-data-v1.0'
lsm_lat_var = 'XLAT'
lsm_lon_var = 'XLONG'
search_card = '*.nc'
precip_data_var = ['RAINC', 'RAINNC']
precip_type = 'ACCUM'

data_var_map_array = [
                      ['precipitation_acc', ['RAINC', 'RAINNC']],
                      ['pressure', 'PSFC'],
                      ['relative_humidity', ['Q2', 'PSFC', 'T2']],
                      ['wind_speed', ['U10', 'V10']],
                      ['direct_radiation', ['SWDOWN', 'DIFFUSE_FRAC']],
                      ['diffusive_radiation', ['SWDOWN', 'DIFFUSE_FRAC']],
                      ['temperature', 'T2'],
                      ['cloud_cover' , 'CLDFRA'],
                     ]

#INITIALIZE CLASS AND RUN
gr = GSSHAFramework(gssha_executable,
                    gssha_directory,
                    project_filename,
                    lsm_folder=lsm_folder,
                    lsm_data_var_map_array=data_var_map_array,
                    lsm_precip_data_var=precip_data_var,
                    lsm_precip_type=precip_type,
                    lsm_lat_var=lsm_lat_var,
                    lsm_lon_var=lsm_lon_var,
                    )

gr.run_forecast()

GSSHA_WRF_Framework

class gsshapy.modeling.GSSHAWRFFramework(gssha_executable, gssha_directory, project_filename, gssha_simulation_start=None, gssha_simulation_end=None, gssha_simulation_duration=None, load_simulation_datetime=False, spt_watershed_name=None, spt_subbasin_name=None, spt_forecast_date_string=None, ckan_engine_url=None, ckan_api_key=None, ckan_owner_organization=None, path_to_rapid_qout=None, connection_list_file=None, lsm_folder=None, lsm_data_var_map_array=None, lsm_precip_data_var=['RAINC', 'RAINNC'], lsm_precip_type='ACCUM', lsm_lat_var='XLAT', lsm_lon_var='XLONG', lsm_time_var='Times', lsm_lat_dim='south_north', lsm_lon_dim='west_east', lsm_time_dim='Time', lsm_search_card='*.nc', precip_interpolation_type=None, event_min_q=None, et_calc_mode=None, soil_moisture_depth=None, output_netcdf=False, write_hotstart=False, read_hotstart=False, hotstart_minimal_mode=False)[source]

Bases: gsshapy.modeling.framework.GSSHAFramework

This class is for automating the connection between RAPID to GSSHA and WRF to GSSHA. There are several different configurations depending upon what you choose.

There are three options for RAPID to GSSHA:

  1. Download and run using forecast from the Streamflow Prediction Tool (See: https://streamflow-prediction-tool.readthedocs.io)
  2. Run from RAPID Qout file
  3. Don’t run using RAPID to GSSHA

There are two options for WRF to GSSHA:

  1. Run from WRF to GSSHA
  2. Don’t run using WRF to GSSHA
Parameters:
  • gssha_executable (str) – Path to GSSHA executable.
  • gssha_directory (str) – Path to directory for GSSHA project.
  • project_filename (str) – Name of GSSHA project file.
  • gssha_simulation_start (Optional[datetime]) – Datetime object with date of start of GSSHA simulation.
  • gssha_simulation_end (Optional[datetime]) – Datetime object with date of end of GSSHA simulation.
  • gssha_simulation_duration (Optional[timedelta]) – Datetime timedelta object with duration of GSSHA simulation.
  • load_simulation_datetime (Optional[bool]) – If True, this will load in datetime information from the project file. Default is False.
  • spt_watershed_name (Optional[str]) – Streamflow Prediction Tool watershed name.
  • spt_subbasin_name (Optional[str]) – Streamflow Prediction Tool subbasin name.
  • spt_forecast_date_string (Optional[str]) – Streamflow Prediction Tool forecast date string.
  • ckan_engine_url (Optional[str]) – CKAN engine API url.
  • ckan_api_key (Optional[str]) – CKAN api key.
  • ckan_owner_organization (Optional[str]) – CKAN owner organization.
  • path_to_rapid_qout (Optional[str]) – Path to the RAPID Qout file. Use this if you do NOT want to download the forecast and you want to use RAPID streamflows.
  • connection_list_file (Optional[str]) – CSV file with list connecting GSSHA rivers to RAPID river network. See: http://rapidpy.readthedocs.io/en/latest/rapid_to_gssha.html
  • lsm_folder (Optional[str]) – Path to folder with land surface model data. See: lsm_input_folder_path variable at GRIDtoGSSHA().
  • lsm_data_var_map_array (Optional[str]) – Array with connections for WRF output and GSSHA input. See: ()
  • lsm_precip_data_var (Optional[list or str]) – String of name for precipitation variable name or list of precip variable names. See: lsm_precip_to_gssha_precip_gage().
  • lsm_precip_type (Optional[str]) – Type of precipitation. See: lsm_precip_to_gssha_precip_gage().
  • lsm_lat_var (Optional[str]) – Name of the latitude variable in the WRF netCDF files. See: GRIDtoGSSHA().
  • lsm_lon_var (Optional[str]) – Name of the longitude variable in the WRF netCDF files. See: GRIDtoGSSHA().
  • lsm_time_var (Optional[str]) – Name of the time variable in the WRF netCDF files. See: GRIDtoGSSHA().
  • lsm_lat_dim (Optional[str]) – Name of the latitude dimension in the LSM netCDF files. See: GRIDtoGSSHA().
  • lsm_lon_dim (Optional[str]) – Name of the longitude dimension in the LSM netCDF files. See: GRIDtoGSSHA().
  • lsm_time_dim (Optional[str]) – Name of the time dimension in the LSM netCDF files. See: GRIDtoGSSHA().
  • lsm_search_card (Optional[str]) – Glob search pattern for WRF files. See: GRIDtoGSSHA().
  • precip_interpolation_type (Optional[str]) – Type of interpolation for WRF precipitation. Can be “INV_DISTANCE” or “THIESSEN”. Default is “THIESSEN”.
  • event_min_q (Optional[double]) – Threshold discharge for continuing runoff events in m3/s. Default is 60.0.
  • et_calc_mode (Optional[str]) – Type of evapo-transpitation calculation for GSSHA. Can be “PENMAN” or “DEARDORFF”. Default is “PENMAN”.
  • soil_moisture_depth (Optional[double]) – Depth of the active soil moisture layer from which ET occurs (m). Default is 0.0.
  • output_netcdf (Optional[bool]) – If you want the HMET data output as a NetCDF4 file for input to GSSHA. Default is False.
  • write_hotstart (Optional[bool]) – If you want to automatically generate all hotstart files, set to True. Default is False.
  • read_hotstart (Optional[bool]) – If you want to automatically search for and read in hotstart files, set to True. Default is False.
  • hotstart_minimal_mode (Optional[bool]) – If you want to turn off all outputs to only generate the hotstart file, set to True. Default is False.

Example running full framework with RAPID and LSM locally stored:

from gsshapy.modeling import GSSHAWRFFramework

gssha_executable = 'C:/Program Files/WMS 10.1 64-bit/gssha/gssha.exe'
gssha_directory = "C:/Users/{username}/Documents/GSSHA"
project_filename = "gssha_project.prj"

#LSM TO GSSHA
lsm_folder = '"C:/Users/{username}/Documents/GSSHA/wrf-sample-data-v1.0'

#RAPID TO GSSHA
path_to_rapid_qout = "C:/Users/{username}/Documents/GSSHA/Qout.nc"
connection_list_file = "C:/Users/{username}/Documents/GSSHA/rapid_to_gssha_connect.csv"

#INITIALIZE CLASS AND RUN
gr = GSSHAWRFFramework(gssha_executable,
                       gssha_directory,
                       project_filename,
                       lsm_folder=lsm_folder,
                       path_to_rapid_qout=path_to_rapid_qout,
                       connection_list_file=connection_list_file,
                       )

gr.run_forecast()

Example connecting SPT to GSSHA:

from gsshapy.modeling import GSSHAWRFFramework

gssha_executable = 'C:/Program Files/WMS 10.1 64-bit/gssha/gssha.exe'
gssha_directory = "C:/Users/{username}/Documents/GSSHA"
project_filename = "gssha_project.prj"

#LSM TO GSSHA
lsm_folder = '"C:/Users/{username}/Documents/GSSHA/wrf-sample-data-v1.0'

#RAPID TO GSSHA
connection_list_file = "C:/Users/{username}/Documents/GSSHA/rapid_to_gssha_connect.csv"

#SPT TO GSSHA
ckan_engine_url='http://ckan/api/3/action'
ckan_api_key='your-api-key'
ckan_owner_organization='your_organization'
spt_watershed_name='watershed_name'
spt_subbasin_name='subbasin_name'
spt_forecast_date_string='20160721.1200'

#INITIALIZE CLASS AND RUN
gr = GSSHAWRFFramework(gssha_executable,
                       gssha_directory,
                       project_filename,
                       lsm_folder=lsm_folder,
                       connection_list_file=connection_list_file,
                       ckan_engine_url=ckan_engine_url,
                       ckan_api_key=ckan_api_key,
                       ckan_owner_organization=ckan_owner_organization,
                       spt_watershed_name=spt_watershed_name,
                       spt_subbasin_name=spt_subbasin_name,
                       spt_forecast_date_string=spt_forecast_date_string,
                       )

gr.run_forecast()

Example with Hotstart:

from datetime import datetime, timedelta
from gsshapy.modeling import GSSHAWRFFramework

gssha_executable = 'C:/Program Files/WMS 10.1 64-bit/gssha/gssha.exe'
gssha_directory = "C:/Users/{username}/Documents/GSSHA"
project_filename = "gssha_project.prj"
full_gssha_simulation_duration = timedelta(days=5, seconds=0)
gssha_hotstart_offset_duration = timedelta(days=1, seconds=0)

#LSM
lsm_folder = '"C:/Users/{username}/Documents/GSSHA/wrf-sample-data-v1.0'

#RAPID
path_to_rapid_qout = "C:/Users/{username}/Documents/GSSHA/Qout.nc"
connection_list_file = "C:/Users/{username}/Documents/GSSHA/rapid_to_gssha_connect.csv"

#--------------------------------------------------------------------------
# MAIN RUN
#--------------------------------------------------------------------------
mr = GSSHAWRFFramework(gssha_executable,
                       gssha_directory,
                       project_filename,
                       lsm_folder=lsm_folder,
                       path_to_rapid_qout=path_to_rapid_qout,
                       connection_list_file=connection_list_file,
                       gssha_simulation_duration=full_gssha_simulation_duration,
                       read_hotstart=True,
                       )

mr.run_forecast()
#--------------------------------------------------------------------------
# GENERATE HOTSTART FOR NEXT RUN
#--------------------------------------------------------------------------
hr = GSSHAWRFFramework(gssha_executable,
                       gssha_directory,
                       project_filename,
                       lsm_folder=lsm_folder,
                       path_to_rapid_qout=path_to_rapid_qout,
                       connection_list_file=connection_list_file,
                       gssha_simulation_duration=gssha_hotstart_offset_duration,
                       write_hotstart=True,
                       read_hotstart=True,
                       hotstart_minimal_mode=True,
                       )
hr.run_forecast()