easy_vic_build.build_RVIC_Param

build_RVIC_Param - A Python module for building RVIC parameter files.

This module provides functions for constructing and modifying RVIC (Routing of VIC model) parameter files, including flow direction files, pour point files, unit hydrograph (UH) box files, and configuration (CFG) files essential for RVIC simulations. The module also includes utilities for setting up and modifying the necessary inputs for hydrological routing within the VIC framework.

Functions:

  • buildRVICParam_general: Generate general RVIC parameter files before using rvic_parameters.

  • buildRVICParam: Constructs RVIC parameters that contains rvic_parameters based on input datasets and configurations.

  • buildRVICFlowDirectionFile: Generates a NetCDF flow direction file using provided input datasets.

  • buildPourPointFile: Creates a pour point file specifying the outlet locations for routing.

  • buildUHBOXFile: Constructs a UHBOX file that defines the unit hydrograph characteristics.

  • buildParamCFGFile: Generates the parameter configuration (CFG) file for RVIC simulations.

  • buildConvCFGFile: Creates a conversion configuration file for RVIC execution.

  • modifyRVICParam_for_pourpoint: Modifies RVIC parameters to include a specific pour point and updates flow direction settings accordingly.

Usage:

  1. Call buildRVICParam_general to generate RVIC parameter files without using rvic_parameters, set the necessary input parameters.

  2. Call buildRVICParam to generate RVIC parameter files and execute RVIC parameter computation.

Example:

basin_index = 213 model_scale = “6km” date_period = [“19980101”, “19981231”] case_name = f”{basin_index}_{model_scale}”

evb_dir = Evb_dir(“./examples”) # cases_home=”/home/xdz/code/VIC_xdz/cases” evb_dir.builddir(case_name)

dpc_VIC_level0, dpc_VIC_level1, dpc_VIC_level2 = readdpc(evb_dir) params_dataset_level0, params_dataset_level1 = readParam(evb_dir)

buildRVICParam_general(evb_dir, dpc_VIC_level1, params_dataset_level1,
ppf_kwargs=dict(), uh_params={“createUH_func”: create_uh.createGUH, “uh_dt”: 3600,

“tp”: default_uh_params[0], “mu”: default_uh_params[1], “m”: default_uh_params[2], “plot_bool”: True, “max_day”:None, “max_day_range”: (0, 10), “max_day_converged_threshold”: 0.001},

cfg_params={“VELOCITY”: 1.5, “DIFFUSION”: 800.0, “OUTPUT_INTERVAL”: 86400, “SUBSET_DAYS”: 10, “CELL_FLOWDAYS”: 2, “BASIN_FLOWDAYS”: 50})

buildRVICParam(evb_dir, dpc_VIC_level1, params_dataset_level1,
ppf_kwargs=dict(), uh_params={“createUH_func”: create_uh.createGUH, “uh_dt”: 3600,

“tp”: default_uh_params[0], “mu”: default_uh_params[1], “m”: default_uh_params[2], “plot_bool”: True, “max_day”:None, “max_day_range”: (0, 10), “max_day_converged_threshold”: 0.001},

cfg_params={“VELOCITY”: 1.5, “DIFFUSION”: 800.0, “OUTPUT_INTERVAL”: 86400, “SUBSET_DAYS”: 10, “CELL_FLOWDAYS”: 2, “BASIN_FLOWDAYS”: 50})

params_dataset_level0.close() params_dataset_level1.close()

Dependencies:

  • os: For file and directory operations.

  • numpy: For numerical operations.

  • pandas: For handling tabular data (CSV files).

  • rasterio: For reading and writing geospatial raster data.

  • copy: For creating deep copies of objects.

  • logging: For logging messages during file processing.

  • xarray: For handling multidimensional arrays and NetCDF files.

  • .tools.params_func.createParametersDataset: For creating flow direction files.

  • .tools.utilities: For reading configuration files.

  • .tools.decoractors: For timing function execution with clock_decorator.

  • .tools.uh_func: For creating unit hydrographs (UH).

  • .tools.geo_func.search_grids: For geospatial grid search functions.

Functions

buildConvCFGFile(evb_dir[, RUN_STARTDATE, ...])

Generate and save the RVIC convolution configuration file.

buildParamCFGFile(evb_dir[, VELOCITY, ...])

Generate and save the RVIC parameter configuration file.

buildPourPointFile(evb_dir[, names, lons, lats])

Generate a pour point CSV file for RVIC.

buildRVICFlowDirectionFile(evb_dir, ...)

Generate an RVIC flow direction file in NetCDF format.

buildRVICParam(evb_dir, domain_dataset[, ...])

Generate RVIC parameter files and execute RVIC parameter computation.

buildRVICParam_basic(evb_dir, domain_dataset)

Generate general RVIC parameter files before using rvic_parameters.

buildUHBOXFile(evb_dir[, createUH_func])

Generate and save the UHBOX (Unit Hydrograph Box) file.

modifyRVICParam_for_pourpoint(evb_dir, ...)

Modify RVIC parameters to integrate a specified pour point.
easy_vic_build.build_RVIC_Param.buildConvCFGFile(evb_dir, RUN_STARTDATE='1979-09-01-00', DATL_FILE='rasm_sample_runoff.nc', PARAM_FILE_PATH='sample_rasm_parameters.nc')[source]

Generate and save the RVIC convolution configuration file.

This function creates a configuration (CFG) file for RVIC convolution settings based on a reference configuration file and specified parameters.

Parameters:

  • evb_dir (Evb_dir) – An instance of the Evb_dir class, containing paths for VIC deployment.

  • RUN_STARTDATE (str, optional) – The start date for the RVIC run in “YYYY-MM-DD-HH” format.

  • DATL_FILE (str, optional) – The name of the input runoff file. Default is “rasm_sample_runoff.nc”.

  • PARAM_FILE_PATH (str, optional) – The path to the RVIC parameter file. Default is “sample_rasm_parameters.nc”.

Notes

  • Reads a reference configuration file and modifies key parameters.

  • Saves the updated configuration file to evb_dir.rvic_conv_cfg_file_path.

easy_vic_build.build_RVIC_Param.buildParamCFGFile(evb_dir, VELOCITY=1.5, DIFFUSION=800.0, OUTPUT_INTERVAL=86400, SUBSET_DAYS=10, CELL_FLOWDAYS=2, BASIN_FLOWDAYS=50)[source]

Generate and save the RVIC parameter configuration file.

This function creates a configuration (CFG) file for RVIC parameter settings based on a reference configuration file and specified routing parameters.

Parameters:

  • evb_dir (Evb_dir) – An instance of the Evb_dir class, containing paths for VIC deployment.

  • VELOCITY (float, optional) – Flow velocity parameter, default is 1.5, and the acceptable range is 1.0 to 3.0 m/s.

  • DIFFUSION (float, optional) – Diffusion coefficient for routing, default is 800.0, and the acceptable range is 200 to 4000m3/s.

  • OUTPUT_INTERVAL (int, optional) – Time interval (seconds) for output, default is 86400 seconds (1 day), and should typically be set as a multiple of 60.

  • SUBSET_DAYS (int, optional) – Number of days used for subset processing, default is 10.

  • CELL_FLOWDAYS (int, optional) – Flow duration at the cell level (days), default is 2.

  • BASIN_FLOWDAYS (int, optional) – Flow duration at the basin level (days), default is 50.

Notes

  • Reads a reference configuration file and modifies key parameters.

  • Saves the updated configuration file to evb_dir.rvic_param_cfg_file_path.

easy_vic_build.build_RVIC_Param.buildPourPointFile(evb_dir, names=None, lons=None, lats=None)[source]

Generate a pour point CSV file for RVIC.

This function creates a CSV file containing longitude, latitude, and names of pour points. If dpc_VIC_level1 is provided, it extracts pour point coordinates from the basin shapefile; otherwise, it uses the manually provided lons, lats, and names lists.

Parameters:

  • evb_dir (Evb_dir) – An instance of the Evb_dir class, containing paths for VIC deployment.

  • dpc_VIC_level1 (dpc_VIC_level1) – An instance of the dpc_VIC_level1 class to determine pour points..

  • names (list, optional) – List of names for the pour points.

  • lons (list, optional) – List of longitude coordinates for pour points.

  • lats (list, optional) – List of latitude coordinates for pour points.

Returns:

The function writes the pour point data to a CSV file.

Return type:

None

Notes

  • If dpc_VIC_level1 is used, the function extracts pour point locations from the “camels_topo” attributes.

  • If dpc_VIC_level1 is not provided, manually specified coordinates must be supplied.

  • Ensure that flow accumulation data is checked to verify pour point locations.

easy_vic_build.build_RVIC_Param.buildRVICFlowDirectionFile(evb_dir, domain_dataset)[source]

Generate an RVIC flow direction file in NetCDF format.

This function reads flow direction, flow accumulation, and flow distance data from GeoTIFF files, applies a mask based on the VIC parameter dataset, and stores the processed data in a NetCDF file.

Parameters:

  • evb_dir (Evb_dir) – An instance of the Evb_dir class, containing paths for VIC deployment.

  • params_dataset_level1 (netCDF.Dataset) – The parameter dataset for level 1, containing flow direction and routing parameters.

Returns:

The function creates a NetCDF file containing flow direction-related information.

Return type:

None

Notes

The function performs the following steps: 1. Sets paths for input and output files. 2. Reads general information from the VIC parameter dataset. 3. Reads flow direction, flow accumulation, and flow distance data from GeoTIFF files. 4. Combines the data into a NetCDF file, applying masks where necessary.

easy_vic_build.build_RVIC_Param.buildRVICParam(evb_dir, domain_dataset, ppf_kwargs={}, uh_params={'createUH_func': <function createGUH>, 'm': 3.0, 'max_day': None, 'max_day_converged_threshold': 0.001, 'max_day_range': (0, 10), 'mu': 5.0, 'plot_bool': True, 'tp': 1.4, 'uh_dt': 3600}, cfg_params={'BASIN_FLOWDAYS': 50, 'CELL_FLOWDAYS': 2, 'DIFFUSION': 800.0, 'OUTPUT_INTERVAL': 86400, 'SUBSET_DAYS': 10, 'VELOCITY': 1.5})[source]

Generate RVIC parameter files and execute RVIC parameter computation.

This function first builds the necessary RVIC input files using buildRVICParam_general, then reads the parameter configuration file and runs the RVIC parameter computation.

Parameters:

  • evb_dir (Evb_dir) – An instance of the Evb_dir class, containing paths for VIC deployment.

  • dpc_VIC_level1 (dpc_VIC_level1) – An instance of the dpc_VIC_level1 class to determine pour points..

  • params_dataset_level1 (netCDF.Dataset) – The parameter dataset for level 1, containing flow direction and routing parameters.

  • ppf_kwargs (dict, optional) – Keyword arguments for buildPourPointFile, by default an empty dictionary.

  • uh_params (dict, optional) – Parameters for buildUHBOXFile, including: - createUH_func: Function to create UH. - uh_dt: Time step for UH computation. - tp, mu, m: Shape parameters for UH function. - plot_bool: Whether to generate UH plots. - max_day, max_day_range, max_day_converged_threshold: Parameters for convergence criteria.

  • cfg_params (dict, optional) – Configuration parameters for buildParamCFGFile, including: - VELOCITY: Flow velocity. - DIFFUSION: Diffusion parameter. - OUTPUT_INTERVAL: Output time interval. - SUBSET_DAYS: Days for subset computation. - CELL_FLOWDAYS: Days for cell flow accumulation. - BASIN_FLOWDAYS: Days for basin flow accumulation.

Returns:

The function generates RVIC parameter files and executes the RVIC parameter computation.

Return type:

None

Raises:

ImportError – If the RVIC module is not available.

Notes

This function performs the following steps: 1. Calls buildRVICParam_general to generate the required input files. 2. Reads the RVIC parameter configuration file. 3. Runs rvic_parameters if RVIC is available; otherwise, raises an ImportError.

easy_vic_build.build_RVIC_Param.buildRVICParam_basic(evb_dir, domain_dataset, ppf_kwargs={}, uh_params={'createUH_func': <function createGUH>, 'm': 3.0, 'max_day': None, 'max_day_converged_threshold': 0.001, 'max_day_range': (0, 10), 'mu': 5.0, 'plot_bool': True, 'tp': 1.4, 'uh_dt': 3600}, cfg_params={'BASIN_FLOWDAYS': 50, 'CELL_FLOWDAYS': 2, 'DIFFUSION': 800.0, 'OUTPUT_INTERVAL': 86400, 'SUBSET_DAYS': 10, 'VELOCITY': 1.5})[source]

Generate general RVIC parameter files before using rvic_parameters.

This function sequentially builds the required input files for the RVIC model, including: - Flow direction file - Pour point file - Unit hydrograph (UH) file - Parameter configuration file

Parameters:

  • evb_dir (Evb_dir) – An instance of the Evb_dir class, containing paths for VIC deployment.

  • dpc_VIC_level1 (dpc_VIC_level1) – An instance of the dpc_VIC_level1 class to determine pour points..

  • params_dataset_level1 (netCDF.Dataset) – The parameter dataset for level 1, containing flow direction and routing parameters.

  • ppf_kwargs (dict, optional) – Keyword arguments for buildPourPointFile, by default an empty dictionary.

  • uh_params (dict, optional) – Parameters for buildUHBOXFile, including: - createUH_func: Function to create UH. - uh_dt: Time step for UH computation. - tp, mu, m: Shape parameters for UH function. - plot_bool: Whether to generate UH plots. - max_day, max_day_range, max_day_converged_threshold: Parameters for convergence criteria.

  • cfg_params (dict, optional) – Configuration parameters for buildParamCFGFile, including: - VELOCITY: Flow velocity. - DIFFUSION: Diffusion parameter. - OUTPUT_INTERVAL: Output time interval. - SUBSET_DAYS: Days for subset computation. - CELL_FLOWDAYS: Days for cell flow accumulation. - BASIN_FLOWDAYS: Days for basin flow accumulation.

Returns:

The function generates necessary RVIC parameter files and does not return any values.

Return type:

None

Notes

This function calls the following sub-functions in order: - buildRVICFlowDirectionFile - buildPourPointFile - buildUHBOXFile - buildParamCFGFile

easy_vic_build.build_RVIC_Param.buildUHBOXFile(evb_dir, createUH_func=<function createGUH>, **kwargs)[source]

Generate and save the UHBOX (Unit Hydrograph Box) file.

This function creates a UHBOX file using a specified unit hydrograph creation function. The resulting UHBOX data is then saved to a CSV file.

Parameters:

  • evb_dir (Evb_dir) – An instance of the Evb_dir class, containing paths for VIC deployment.

  • createUH_func (function, optional) – Function used to generate the unit hydrograph, default is create_uh.createGUH.

  • **kwargs (dict) – Additional parameters to be passed to the createUH_func.

Returns:

max_day – Maximum duration (in days) used in the unit hydrograph generation.

Return type:

float

Notes

  • The function relies on createUH_func to generate the UHBOX data.

  • The resulting UHBOX file is stored in evb_dir.uhbox_file_path.

easy_vic_build.build_RVIC_Param.modifyRVICParam_for_pourpoint(evb_dir, pourpoint_lon, pourpoint_lat, pourpoint_direction_code, params_dataset_level1, domain_dataset, reverse_lat=True, stream_acc_threshold=100.0, flow_direction_pkg='wbw', crs_str='EPSG:4326')[source]

Modify RVIC parameters to integrate a specified pour point.

This function updates the pour point file and modifies the RVIC flow direction file to adjust the direction of the pour point at the edge.

Parameters:

  • evb_dir (Evb_dir) – An instance of the Evb_dir class, containing paths for VIC deployment.

  • pourpoint_lon (float) – Longitude of the pour point.

  • pourpoint_lat (float) – Latitude of the pour point.

  • pourpoint_direction_code (int) – Flow direction code for the pour point (e.g., based on D8 direction encoding).

  • params_dataset_level1 (Dataset) – Parameter dataset at level 1, used to extract grid-based information.

  • domain_dataset (netCDF.Dataset, optional) – Domain dataset containing spatial attributes.

  • reverse_lat (bool) – Boolean flag to indicate whether to reverse latitudes (Northern Hemisphere: large -> small, set as True).

  • stream_acc_threshold (float, optional) – The threshold value for stream accumulation. Default is 100.0. It affect the results generated by hydroanalysis_arcpy.

  • flow_direction_pkg (str, optional) – The package used to calculate flow direction. Options are “arcpy” and “wbw”. Default is “wbw”.

  • crs_str (str, optional) – Coordinate reference system (CRS) in EPSG format (default is “EPSG:4326”).

Notes

  • First, the pour point file is created or updated.

  • Then, the RVIC flow direction file is modified to include the pour point and adjust its flow direction.