easy_vic_build.tools.routing_func.create_uh

Module: create_uh

This module provides functions for generating Unit Hydrographs (UH) using different methodologies, including the General Unit Hydrograph (gUH) and Nash Unit Hydrograph (NashUH). These functions allow for the creation of dimensionless unit hydrographs based on specified time parameters and other relevant inputs. The module includes utilities for plotting and visualizing the generated unit hydrographs, and it also includes functionality for determining the maximum day for the UH based on convergence criteria.

Functions:

get_max_day: Determines the maximum day for UH calculation based on the convergence of the hydrograph.

createGUH: Generates a General Unit Hydrograph using an analytical expression based on time parameters.

createNashUH: Generates a Nash Unit Hydrograph using a gamma distribution with specified parameters.

Dependencies:

numpy: Used for numerical operations, particularly with arrays and time-related calculations.

pandas: For creating and manipulating data structures, especially DataFrames for output.

matplotlib.pyplot: Used for creating static visualizations of the unit hydrographs.

scipy.stats.gamma: Provides tools for generating the gamma distribution used in the NashUH calculation.

os: For interacting with the file system, including saving plot images.

Author:

Xudong Zheng Email: zhengxd@sehemodel.club

Functions

`createGUH`(evb_dir[, uh_dt, tp, mu, m, ...])	Create a General Unit Hydrograph (gUH) and optionally plot and save the results.
`createNashUH`(evb_dir[, uh_dt, n, K, tp, qp, ...])	Create a Nash Unit Hydrograph (UH) using a gamma distribution and optionally plot and save the results.
`get_max_day`(UH_func_frozen_param[, ...])	Calculate the maximum day (in days) at which the unit hydrograph (UH) function converges below a specified threshold.

easy_vic_build.tools.routing_func.create_uh.get_max_day(UH_func_frozen_param, max_day_range=(0, 10), max_day_converged_threshold=0.001)[source]

Calculate the maximum day (in days) at which the unit hydrograph (UH) function converges below a specified threshold.

This function automatically calculates the maximum day for the UH function, starting with an initial guess for the top time and iterating to find the day at which the function falls below the convergence threshold.

Parameters:

UH_func_frozen_param (function) – A function representing the unit hydrograph (UH) at a given time in hours. The function should take a single argument t (time in hours) and return the UH value.
max_day_range (tuple, optional) – The range of maximum days (in days) to consider for the search. Defaults to (0, 10), i.e., searching within 0 to 10 days.
max_day_converged_threshold (float, optional) – The threshold below which the UH function is considered converged. Defaults to 0.001.

Returns:

max_day – The maximum day (rounded up to the nearest whole day) at which the UH function converges below the specified threshold.

Return type:

int

Notes

The function uses a binary search approach to find the time when the UH function value first falls below the specified threshold, with the search range defined by max_day_range. The result is returned in days (rounded up).

easy_vic_build.tools.routing_func.create_uh.createGUH(evb_dir, uh_dt=3600, tp=1.4, mu=5.0, m=3.0, plot_bool=False, max_day=None, max_day_range=(0, 10), max_day_converged_threshold=0.001)[source]

Create a General Unit Hydrograph (gUH) and optionally plot and save the results.

This function calculates the General Unit Hydrograph (gUH) using parameters defined in the SCS UH method, including time steps, and generates a UHBOX file for hydrological analysis. The function also provides an option to plot the gUH functions and save the plots as images.

Parameters:

evb_dir (object) – The directory object where the results, including plots, will be saved.
uh_dt (int, optional) – The time step (in seconds) for the UH calculation. Default is 3600 seconds (1 hour).
tp (float, optional) – The time parameter for the General Unit Hydrograph (gUH) model in hours. Default is 1.4 hours.
mu (float, optional) – The scaling factor for the gUH model. Default is 5.0, based on SCS UH.
m (float, optional) – A parameter for the gUH model. Should be greater than 1. Default is 3.0, based on SCS UH.
plot_bool (bool, optional) – If True, the function will plot the gUH and save the plot. Default is False.
max_day (int, optional) – The maximum day for the UH calculation. If None, the function will calculate it using get_max_day.
max_day_range (tuple, optional) – The range of maximum days (in days) to consider for the search. Default is (0, 10).
max_day_converged_threshold (float, optional) – The threshold below which the UH function is considered converged. Default is 0.001.

Returns:

max_day (int) – The maximum day (rounded up to the nearest whole day) at which the UH function converges below the specified threshold.
UHBOX_file (pandas.DataFrame) – A DataFrame containing the time and corresponding General Unit Hydrograph (gUH) values.

Notes

The function uses the method from Guo (2022) to calculate the general and analytic unit hydrograph (gUH). It also supports plotting the results for visualization purposes. The calculated UHBOX file is saved as a DataFrame containing the time series and corresponding gUH values.

easy_vic_build.tools.routing_func.create_uh.createNashUH(evb_dir, uh_dt=3600, n=None, K=None, tp=1.4, qp=0.15, plot_bool=False, max_day=None, max_day_range=(0, 10), max_day_converged_threshold=0.001)[source]

Create a Nash Unit Hydrograph (UH) using a gamma distribution and optionally plot and save the results.

This function calculates the Nash Unit Hydrograph (NashUH) based on the Nash gamma distribution. The function also provides an option to plot the NashUH function and save the plots as images.

Parameters:

evb_dir (object) – The directory object where the results, including plots, will be saved.
uh_dt (int, optional) – The time step (in seconds) for the UH calculation. Default is 3600 seconds (1 hour).
n (float, optional) – The shape parameter for the gamma distribution. If None, it is calculated based on beta and tp. Default is None.
K (float, optional) – The scale parameter for the gamma distribution. If None, it is calculated based on n and tp. Default is None.
tp (float, optional) – The time parameter for the Nash UH model in hours. Default is 1.4 hours.
qp (float, optional) – A parameter for the Nash UH model. Default is 0.15.
plot_bool (bool, optional) – If True, the function will plot the Nash UH and save the plot. Default is False.
max_day (int, optional) – The maximum day for the UH calculation. If None, the function will calculate it using get_max_day.
max_day_range (tuple, optional) – The range of maximum days (in days) to consider for the search. Default is (0, 10).
max_day_converged_threshold (float, optional) – The threshold below which the UH function is considered converged. Default is 0.001.

Returns:

max_day (int) – The maximum day (rounded up to the nearest whole day) at which the UH function converges below the specified threshold.
UHBOX_file (pandas.DataFrame) – A DataFrame containing the time and corresponding Nash Unit Hydrograph (NashUH) values.

Notes

The function uses a gamma distribution to model the Nash Unit Hydrograph (NashUH) and calculates the maximum day for which the UH function converges. It also supports plotting the results for visualization purposes. The calculated UHBOX file is saved as a DataFrame containing the time series and corresponding NashUH values.