Inflow from Land Surface Models¶

Code to use to prepare input data for RAPID from Land Surface Models (LSM) such as:

ECMWF’s ERA Interim Data
NASA’s GLDAS/NLDAS/LIS Data
CMIP5 Data (daily VIC data available from 1950 to 2099)

Step 1: Retrieve Land Surface Model Runoff Output¶

Download the data into a local directory.

Step 2: Create folders for RAPID input and output¶

In this instance:

$ cd $HOME
$ mkdir -p rapid-io/input rapid-io/output

Step 3: Create script using LSM process¶

Here is the API for the function to use. Follow the example to create a script to use the code such as in ~/run_lsm.py.

RAPIDpy.inflow.lsm_rapid_process.run_lsm_rapid_process(rapid_executable_location, lsm_data_location, rapid_io_files_location=None, rapid_input_location=None, rapid_output_location=None, simulation_start_datetime=None, simulation_end_datetime=datetime.datetime(2017, 7, 6, 18, 35, 51, 99019), file_datetime_pattern=None, file_datetime_re_pattern=None, initial_flows_file=None, ensemble_list=[None], generate_rapid_namelist_file=True, run_rapid_simulation=True, generate_return_periods_file=False, return_period_method='weibul', generate_seasonal_averages_file=False, generate_seasonal_initialization_file=False, generate_initialization_file=False, use_all_processors=True, num_processors=1, mpiexec_command='mpiexec', cygwin_bin_location='', modeling_institution='US Army Engineer Research and Development Center', convert_one_hour_to_three=False, expected_time_step=None)[source]¶

This is the main process to generate inflow for RAPID and to run RAPID.

Parameters:	rapid_executable_location (str) – Path to the RAPID executable. lsm_data_location (str) – Path to the directory containing the Land Surface Model output files. rapid_io_files_location (Optional[str]) – Path to the directory containing the input and output folders for RAPID. This is for running multiple watersheds. rapid_input_location (Optional[str]) – Path to directory with RAPID simulation input data. Required if rapid_io_files_location is not set. rapid_output_location (Optional[str]) – Path to directory to put output. Required if rapid_io_files_location is not set. simulation_start_datetime (Optional[datetime]) – Datetime object with date bound of earliest simulation start. simulation_end_datetime (Optional[datetime]) – Datetime object with date bound of latest simulation end. Defaults to datetime.utcnow(). file_datetime_pattern (Optional[str]) – Datetime pattern for files (Ex. ‘%Y%m%d%H’). If set, file_datetime_re_pattern is required. Various defaults used by each model. file_datetime_re_pattern (Optional[raw str]) – Regex pattern to extract datetime (Ex. r’d{10}’). If set, file_datetime_pattern is required. Various defaults used by each model. initial_flows_file (Optional[str]) – If given, this is the path to a file with initial flows for the simulaion. ensemble_list (Optional[list]) – This is the expexted ensemble name appended to the end of the file name. generate_rapid_namelist_file (Optional[bool]) – If True, this will create a RAPID namelist file for the run in your RAPID input directory. Default is True. run_rapid_simulation (Optional[bool]) – If True, the RAPID simulation will run after generating the inflow file. Default is True. generate_return_periods_file (Optional[bool]) – If True, the return period file will be generated in the output. Default is False. return_period_method (Optional[str]) – If True, the return period file will be generated in the output. Default is False. generate_seasonal_averages_file (Optional[bool]) – If True, the season average file will be generated. Default is False. generate_seasonal_initialization_file (Optional[bool]) – If True, an intialization based on the seasonal average for the current day of the year will be created. Default is False. generate_initialization_file (Optional[bool]) – If True, an initialization file from the last time step of the simulation willl be created. Default is False. use_all_processors (Optional[bool]) – If True, it will use all available processors to perform this operation. Default is True. num_processors (Optional[int]) – If use_all_processors is False, this argument will determine the number of processors to use. Default is 1. mpiexec_command (Optional[str]) – This is the command to execute RAPID. Default is “mpiexec”. cygwin_bin_location (Optional[str]) – If using Windows, this is the path to the Cygwin bin location. Default is “”. modeling_institution (Optional[str]) – This is the institution performing the modeling and is in the output files. Default is “US Army Engineer Research and Development Center”. convert_one_hour_to_three (Optional[bool]) – If the time step is expected to be 1-hr it will convert to 3. Set to False if the LIS, NLDAS, or Joules grid time step is greater than 1-hr. expected_time_step (Optional[int]) – The time step in seconds of your LSM input data if only one file is given. Required if only one file is present.
Returns:	A list of output file information.
Return type:	list

Example of regular run:

from datetime import datetime
from RAPIDpy.inflow import run_lsm_rapid_process
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    run_lsm_rapid_process(
        rapid_executable_location='/home/alan/rapid/src/rapid',
        rapid_io_files_location='/home/alan/rapid-io',
        lsm_data_location='/home/alan/era_data',
    )

Example of single input/output run:

from datetime import datetime
from RAPIDpy.inflow import run_lsm_rapid_process
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    run_lsm_rapid_process(
        rapid_executable_location='/home/alan/rapid/src/rapid',
        rapid_input_location='/home/alan/rapid-io/input/provo_watershed',
        rapid_output_location='/home/alan/rapid-io/output/provo_watershed',
        lsm_data_location='/home/alan/era_data',
    )

Example of run with FLDAS and datetime filter:

Note

http://disc.sci.gsfc.nasa.gov/uui/datasets?keywords=FLDAS

from datetime import datetime
from RAPIDpy.inflow import run_lsm_rapid_process
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    run_lsm_rapid_process(
        rapid_executable_location='/home/alan/rapid/src/rapid',
        rapid_io_files_location='/home/alan/rapid-io',
        lsm_data_location='/home/alan/lsm_data',
        simulation_start_datetime=datetime(1980, 1, 1),
        file_datetime_re_pattern = r'\d{8}',
        file_datetime_pattern = "%Y%m%d",
    )

Example of run with CMIP5:

Note

http://gdo-dcp.ucllnl.org/downscaled_cmip_projections/techmemo/BCSD5HydrologyMemo.pdf

from datetime import datetime
from RAPIDpy.inflow import run_lsm_rapid_process
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    run_lsm_rapid_process(
        rapid_executable_location='/home/jimwlewis/rapid/src/rapid',
        rapid_io_files_location='/data/rapid-io4',
        lsm_data_location='/data/rapid-io4/input/cmip5-jun01',
        simulation_start_datetime=datetime(2001, 1, 1),
        simulation_end_datetime=datetime(2002, 12, 31),
        file_datetime_pattern="%Y",
        file_datetime_re_pattern=r'\d{4}',
    )

Step 4: Add RAPID files to the rapid-io/input directory¶

Make sure the directory is in the format [watershed name]-[subbasin name] with lowercase letters, numbers, and underscores only. No spaces!

Example:

$ ls /rapid-io/input
nfie_texas_gulf_region-huc_2_12

$ ls /rapid-io/input/nfie_texas_gulf_region-huc_2_12
comid_lat_lon_z.csv
k.csv
rapid_connect.csv
riv_bas_id.csv
weight_era_t511.csv
weight_nldas.csv
weight_gldas.csv
weight_lis.csv
weight_wrf.csv
weight_cmip5.csv
x.csv

If you have not generated these files yet, see RAPID GIS Tools

Step 5: Run the code¶

$ python ~/run_lsm.py