easy_vic_build.tools.params_func.TransferFunction

Transfer functions and soil-layer resampling utilities for VIC parameters.

Classes

`SoilLayerResampler`(original_depths[, ...])	Resample original soil layers into grouped layers by breakpoints.
`TF_VIC`()	Transfer-function collection for VIC parameter derivation.

class easy_vic_build.tools.params_func.TransferFunction.TF_VIC[source]

Bases: object

Transfer-function collection for VIC parameter derivation.

__init__() → None[source]

static b_infilt(elev_std, g1, g2)[source]

Calculate VIC infiltration parameter b_infilt.

Parameters:

elev_std (ndarray) – Elevation standard-deviation values.
g1 (float) – Calibration coefficient.
g2 (float) – Calibration coefficient.

Returns:

b_infilt values clipped to valid range.

Return type:

ndarray

static total_depth(total_depth_original, g)[source]

Scale total soil depth.

Parameters:

total_depth_original (ndarray) – Original total depth values.
g (float) – Multiplicative scaling factor.

Returns:

Scaled total depth values.

Return type:

ndarray

static depth(total_depth, soillayerresampler, g)[source]

Distribute total depth into VIC layers using breakpoints.

Parameters:

total_depth (ndarray) – Total soil depth.
soillayerresampler (SoilLayerResampler) – Layer resampler instance used to create grouping.
g (sequence of int) – Breakpoint indices, for example [2, 6].

Returns:

Depth values of each aggregated layer.

Return type:

list of ndarray

Notes

g is treated as breakpoint indices of original layers. For example, with 11 source layers and g=[2, 6], grouped layers are: [0,1], [2,3,4,5], and [6,7,8,9,10].

Examples

>>> resampler = SoilLayerResampler([10,10,10,20,20,30,30,40,50,50,50])
>>> TF_VIC.depth(np.array([320.0]), resampler, [2, 6])
[array([20.]), array([80.]), array([220.])]

static ksat(sand, clay, g1, g2, g3)[source]

Calculate the saturated hydraulic conductivity (Ks) using the formula from Cosby et al. (1984).

Parameters:

sand (float) – The percentage of sand in the soil.
clay (float) – The percentage of clay in the soil.
g1 (float) – The constant parameter for the model.
g2 (float) – The constant parameter for the model.
g3 (float) – The constant parameter for the model.

Returns:

The saturated hydraulic conductivity in mm/s.

Return type:

float

static phi_s(sand, clay, g1, g2, g3)[source]

Calculate the saturated water content (phi_s) or porosity using the formula from Cosby et al. (1984).

Parameters:

sand (float) – The percentage of sand in the soil.
clay (float) – The percentage of clay in the soil.
g1 (float) – The constant parameter for the model.
g2 (float) – The constant parameter for the model.
g3 (float) – The constant parameter for the model.

Returns:

The saturated water content in m3/m3 (or mm/mm).

Return type:

float

static psis(sand, silt, g1, g2, g3)[source]

Calculate the saturation matric potential (psis) using the formula from Cosby et al. (1984).

Parameters:

sand (float) – The percentage of sand in the soil.
silt (float) – The percentage of silt in the soil.
g1 (float) – The constant parameter for the model.
g2 (float) – The constant parameter for the model.
g3 (float) – The constant parameter for the model.

Returns:

The saturation matric potential in kPa.

Return type:

float

static b_retcurve(sand, clay, g1, g2, g3)[source]

Calculate the slope of the retention curve (b) using the formula from Cosby et al. (1984).

Parameters:

sand (float) – The percentage of sand in the soil.
clay (float) – The percentage of clay in the soil.
g1 (float) – The constant parameter for the model.
g2 (float) – The constant parameter for the model.
g3 (float) – The constant parameter for the model.

Returns:

The slope of the retention curve.

Return type:

float

static expt(b_retcurve, g1, g2)[source]

Calculate the exponent in Campbell’s equation for hydraulic conductivity.

Parameters:

b_retcurve (float) – The slope of the retention curve.
g1 (float) – The constant parameter for the model.
g2 (float) – The constant parameter for the model.

Returns:

The exponent in Campbell’s equation for hydraulic conductivity (k = ks (θ/θs)^(2b+3)).

Return type:

float

static fc(phi_s, b_retcurve, psis, sand, g)[source]

Calculate the field capacity (fc) using Campbell’s equation for hydraulic conductivity.

Parameters:

phi_s (float) – The saturated water content (porosity).
b_retcurve (float) – The slope of the retention curve (b).
psis (float) – The saturation matric potential (ψs).
sand (float) – The percentage of sand in the soil.
g (float) – The constant parameter for the model.

Returns:

The field capacity (θ) in m³/m³ or %.

Return type:

float

static d1(Ks, slope_mean, phi_s, depth, g)[source]

Calculate the d1 parameter, with units of day^-1, the coefficient of the linear reservoir (baseflow, bottom layer). Darcy law. Mizukami, N., Clark, M., Newman, A., Wood, A., Gutmann, E., Nijssen, B., Rakovec, O., and Samaniego, L.: Toward seamless large domain parameter estimation for hydrologic models, Water Resources Research, 53, 10.1002/2017wr020401, 2017.

Parameters:

Ks (float) – Hydraulic conductivity at layer 3 (m/s).
slope_mean (float) – Mean slope value.
g (float) – Constant parameter for the model (2.0 (1.75, 3.5)).

Returns:

The d1 value in day^-1, bounded between a minimum and maximum range.

Return type:

float

static d2(Ks, slope_mean, d4, g)[source]

Calculate the d2 parameter with units of day^-d4, the coefficient of the nonlinear reservoir (baseflow, bottom layer). Darcy law. Mizukami, N., Clark, M., Newman, A., Wood, A., Gutmann, E., Nijssen, B., Rakovec, O., and Samaniego, L.: Toward seamless large domain parameter estimation for hydrologic models, Water Resources Research, 53, 10.1002/2017wr020401, 2017.

Parameters:

Ks (float) – Hydraulic conductivity at layer 3 (m/s).
slope_mean (float) – Mean slope value.
d4 (float) – Exponent for d4.
g (float) – Constant parameter for the model (2.0 (1.75, 3.5)).

Returns:

The d2 value, bounded between a minimum and maximum range.

Return type:

float

static d3(fc, phi_s, depth, g)[source]

Calculate the d3 parameter in mm, the soil mois-ture level at which the baseflow transitions from linear to nonlinear. Darcy law. Mizukami, N., Clark, M., Newman, A., Wood, A., Gutmann, E., Nijssen, B., Rakovec, O., and Samaniego, L.: Toward seamless large domain parameter estimation for hydrologic models, Water Resources Research, 53, 10.1002/2017wr020401, 2017.

Parameters:

fc (float) – Field capacity (m³/m³).
depth (float) – Depth of the soil layer (m).
g (float) – Constant parameter for the model (1.0 (0.001, 2.0)).

Returns:

The d3 value in mm, bounded between a minimum and maximum range.

Return type:

float

static d4(g=2)[source]

Return the value for d4, typically set to 2, the exponent of the nonlinear part of the outflow curve (note that d4>=1).

Parameters:: g (float, optional) – Constant parameter for the model (default is 2.0 (1.2, 2.5)).
Returns:: The value of d4.
Return type:: float

static cexpt(d4)[source]

Return the value for cexpt, which is equal to d4.

Parameters:: d4 (float) – Exponent value for the d4 parameter.
Returns:: The value of cexpt.
Return type:: float

static Dsmax(d1, d2, d3, cexpt, phi_s, depth)[source]

Calculate the maximum soil moisture (Dsmax).

Parameters:

d1 (float) – The d1 parameter value.
d2 (float) – The d2 parameter value.
d3 (float) – The d3 parameter value.
cexpt (float) – The cexpt parameter value, typically equal to d4.
phi_s (float) – The saturated soil water content (m³/m³).
depth (float) – Depth of the soil layer (m).

Returns:

The maximum soil moisture (Dsmax) in mm or mm/day.

Return type:

float

static Ds(d1, d3, Dsmax)[source]

Calculate the Ds parameter, typically used as a fraction.

Parameters:

d1 (float) – The d1 parameter value.
d3 (float) – The d3 parameter value.
Dsmax (float) – The maximum soil moisture (Dsmax).

Returns:

The Ds value, bounded between a minimum and maximum range.

Return type:

float

static Ws(d3, phi_s, depth)[source]

Calculate the fraction of water available in the soil (Ws).

Parameters:

d3 (float) – The d3 parameter value (mm).
phi_s (float) – The saturated soil water content (m³/m³).
depth (float) – The depth of the soil layer (m).

Returns:

The fraction of available water in the soil (Ws), bounded between a minimum and maximum range.

Return type:

float

static init_moist(phi_s, depth)[source]

Initialize the soil moisture (init_moist) in mm.

Parameters:

phi_s (float) – The saturated soil water content (m³/m³).
depth (float) – The depth of the soil layer (m).

Returns:

The initialized soil moisture in mm.

Return type:

float

static dp(g)[source]

Calculate the dp parameter based on the given constant (g).

Parameters:: g (float) – A constant parameter for the model (typically 1.0 (0.9, 1.1)).
Returns:: The dp value.
Return type:: float

static bubble(expt, g1, g2)[source]

Calculate the bubble parameter based on Schaperow et al. (2021).

Parameters:

expt (float) – The exponent in Campbell’s equation.
g1 (float) – Constant parameter for the model (typically 0.32 (0.1, 0.8)).
g2 (float) – Constant parameter for the model (typically 4.3 (0.0, 10.0)).

Returns:

The bubble parameter value.

Return type:

float

static quartz(sand, g)[source]

Calculate the quartz content in the soil based on sand content and g.

Parameters:

sand (float) – The sand content in the soil (%).
g (float) – Constant parameter for the model (typically 0.8 (0.7, 0.9)).

Returns:

The quartz content, bounded between a minimum and maximum range.

Return type:

float

static bulk_density(bulk_density, g)[source]

Calculate the bulk density of the soil based on the given value and g.

Parameters:

bulk_density (float) – The bulk density of the soil (kg/m³), read from file.
g (float) – Constant parameter for the model (typically 1.0 (0.9, 1.1)).

Returns:

The bulk density value, bounded between a minimum and maximum range.

Return type:

float

static soil_density(g)[source]

Calculate the soil mineral density based on a scaling factor.

Parameters:: g (float) – Constant parameter for the model (typically 1.0 (0.9, 1.1)).
Returns:: The soil mineral density (kg/cm³), scaled by the factor g.
Return type:: float

static Wcr_FRACT(fc, phi_s, g)[source]

Calculate the fraction of water retention at field capacity (Wcr) based on soil properties.

Parameters:

fc (float) – The field capacity of the soil (m³/m³).
phi_s (float) – The saturated soil water content (m³/m³).
g (float) – Constant parameter for the model (typically 1.0 (0.8, 1.2)).

Returns:

The fraction of water retention, bounded between a minimum and maximum range.

Return type:

float

static wp(phi_s, b_retcurve, psis, g)[source]

Calculate the wilting point based on Campbell’s (1974) equation.

Parameters:

phi_s (float) – The saturated soil water content (m³/m³).
b_retcurve (float) – The exponent of the retention curve.
psis (float) – The soil water potential at saturation (kPa).
g (float) – Constant parameter for the model (typically 1.0 (0.8, 1.2)).

Returns:

The wilting point (θ), computed based on the Campbell equation.

Return type:

float

static Wpwp_FRACT(wp, phi_s, g)[source]

Calculate the fraction of the wilting point moisture content (Wpwp) based on soil properties.

Parameters:

wp (float) – The wilting point moisture content (m³/m³).
phi_s (float) – The saturated soil water content (m³/m³).
g (float) – Constant parameter for the model (typically 1.0 (0.8, 1.2)).

Returns:

The fraction of the wilting point moisture content, bounded between a minimum and maximum range.

Return type:

float

static rough(g)[source]

Calculate the soil surface roughness based on a scaling factor.

Parameters:: g (float) – Constant parameter for the model (typically 1.0 (0.9, 1.1)).
Returns:: The surface roughness (m), scaled by the factor g.
Return type:: float

static snow_rough(g)[source]

Calculate the snow surface roughness based on a scaling factor.

Parameters:: g (float) – Constant parameter for the model (typically 1.0 (0.9, 1.1)).
Returns:: The snow surface roughness (m), scaled by the factor g.
Return type:: float

static off_gmt(lon)[source]

Calculate the offset from GMT based on longitude.

Parameters:: lon (float) – The longitude of the location (degrees).
Returns:: The offset from GMT in hours.
Return type:: float

static fs_active(activate=0)[source]

Activate or deactivate a flag.

Parameters:: activate (int, optional) – A flag to activate or deactivate (default is 0, which means inactive).
Returns:: The activation flag value.
Return type:: int

static velocity(acc_km2, slope_mean, g1, g2, g3, landcover=None)[source]

Estimate spatially distributed velocity (m/s) for RVIC using a transfer function. Chen, Y., Shi, P., Ji, X., Qu, S., Zhao, L., and Dong, F.: New method to calculate the dynamic factor-flow velocity in Geomorphologic instantaneous unit hydrograph, Scientific Reports, 9, 10.1038/s41598-019-50723-x, 2019. Duc, N., Oki, T., and Kanae, S.: A variable streamflow velocity method for global river routing model: Model description and preliminary results, Hydrology and Earth System Sciences Discussions, 4, 10.5194/hessd-4-4389-2007, 2007. K, S., M, H., and Doell, P.: Simulating river flow velocity on global scale, Advances in Geosciences, 5, 10.5194/adgeo-5-133-2005, 2005.

Parameters:

acc (float) – Flow accumulation / upstream area (km^2).
slope (float) – Local slope (m/m).
g1 (float) – Global calibration parameter (scale factor).
g2 (float) – Exponent for flow accumulation.
g3 (float) – Exponent for slope.

Returns:

Estimated flow velocity in m/s.

Return type:

float

static diffusion(velocity, flow_distance_m, g)[source]

Estimate diffusion coefficient matrix D from flow velocity and river segment length. Yang, Y., Endreny, T. A., and Nowak, D. J. J. J. o. E. s.: Application of advection-diffusion routing model to flood wave propagation: A case study on Big Piney River, Missouri USA, 27, 9-14, 2016. D=alpha*v*L g: alpha, 0.1, (0.001, 0.5)

Units: D in m^2/s, v in m/s, flow_distance in m.

Parameters:

v (np.ndarray) – Flow velocity matrix (m/s), same shape as the grid.
flow_distance_m (np.ndarray) – River segment length or flow distance matrix (m), same shape as v.
alpha (float, optional) – Scaling factor for diffusion coefficient, default 0.1.

Returns:

D – Diffusion coefficient matrix (m^2/s), same shape as input.

Return type:

np.ndarray

class easy_vic_build.tools.params_func.TransferFunction.SoilLayerResampler(original_depths, breakpoints=None)[source]

Bases: object

Resample original soil layers into grouped layers by breakpoints.

orig_depths

Thickness of original layers.

Type:: numpy.ndarray

n_orig

Number of original layers.

Type:: int

orig_total

Total original depth.

Type:: float

orig_cumsum

Cumulative depth of original layers.

Type:: numpy.ndarray

orig_boundaries

Layer boundaries with leading zero.

Type:: numpy.ndarray

grouping

Group metadata after create_grouping().

Type:: dict or None

Examples

>>> import numpy as np
>>> # Original 11 layers
>>> original_depths = [10,10,10,20,20,30,30,40,50,50,50]
>>> resampler = SoilLayerResampler(original_depths)
>>> resampler.create_grouping([2, 6])

>>> # 1) Create grouping
>>> grouping = resampler.grouping
>>> print("Original grouping:")
Original grouping:
>>> print("Depths:", grouping["depths"])
Depths: [ 20.  80. 220.]
>>> print("Depth percentages:", grouping["depth_percentages"])
Depth percentages: [0.0625 0.25   0.6875]

>>> # 2) Scale to new total depth
>>> scaled_grouping = resampler.scale_grouping(grouping, 500)
>>> print("Scaled grouping (500cm total):")
Scaled grouping (500cm total):
>>> print("Scaled depths:", scaled_grouping["depths"])
Scaled depths: [ 31.25 125.   343.75]
>>> print("Boundaries:", scaled_grouping["boundaries"])
Boundaries: [  0.    31.25 156.25 500.  ]

>>> # 3) Value conversion
>>> print("=== Value conversion ===")
=== Value conversion ===
>>> orig_values = np.array([1,2,3,4,5,6,7,8,9,10,11])
>>> grouped_values = resampler.convert_to_grouping(orig_values, grouping, method="mean")
>>> print("Original:", orig_values)
Original: [ 1  2  3  4  5  6  7  8  9 10 11]
>>> print("Grouped (mean):", grouped_values)
Grouped (mean): [1.5 4.5 9. ]

Initialize resampler.

Parameters:

original_depths (sequence of float) – Thickness of each original soil layer.
breakpoints (sequence of int, optional) – Breakpoint indices used to build grouping at initialization. Example: [2, 6] creates three groups from 11 original layers.

__init__(original_depths, breakpoints=None)[source]

Initialize resampler.

Parameters:

original_depths (sequence of float) – Thickness of each original soil layer.
breakpoints (sequence of int, optional) – Breakpoint indices used to build grouping at initialization. Example: [2, 6] creates three groups from 11 original layers.

create_grouping(breakpoints)[source]

Create grouped-layer metadata from breakpoints.

Parameters:: breakpoints (sequence of int) – Group end indices (exclusive in group construction).
Returns:: Grouping is stored in self.grouping.
Return type:: None
Raises:: ValueError – If breakpoints are invalid or do not cover full layer range.

Notes

Breakpoints are interpreted as group end indices in the original-layer index space. Internally, 0 and n_orig are added automatically.

Examples

>>> resampler = SoilLayerResampler([10,10,10,20,20,30,30,40,50,50,50])
>>> resampler.create_grouping([2, 6])
>>> resampler.grouping["grouping_scheme"]
[[0, 1], [2, 3, 4, 5], [6, 7, 8, 9, 10]]

scale_grouping(grouping, new_total_depth)[source]

Scale grouped layers to a new total depth.

Parameters:

grouping (dict) – Grouping dictionary generated by create_grouping.
new_total_depth (float) – Target total depth after scaling.

Returns:

Grouping dictionary with updated depths and boundaries.

Return type:

dict

Examples

>>> resampler = SoilLayerResampler([10,10,10,20,20,30,30,40,50,50,50])
>>> resampler.create_grouping([2, 6])
>>> scaled = resampler.scale_grouping(resampler.grouping, 500.0)
>>> scaled["depths"]
array([ 31.25, 125.  , 343.75])

convert_to_grouping(values, grouping, direction='orig_to_new', method='mean')[source]

Convert values between original layers and grouped layers.

Parameters:

values (array-like) – Input values to convert.
grouping (dict) – Grouping dictionary from create_grouping.
direction ({'orig_to_new', 'new_to_orig'}, optional) – Conversion direction.
method ({'mean', 'sum'}, optional) – Aggregation method used for orig_to_new.

Returns:

Converted values in the target layer space.

Return type:

numpy.ndarray

Raises:

ValueError – If direction/method is invalid or input length is inconsistent.

Examples

>>> resampler = SoilLayerResampler([10,10,10,20,20,30,30,40,50,50,50])
>>> resampler.create_grouping([2, 6])
>>> vals = np.array([1,2,3,4,5,6,7,8,9,10,11])
>>> resampler.convert_to_grouping(vals, resampler.grouping, method="mean")
array([1.5, 4.5, 9. ])
>>> resampler.convert_to_grouping(np.array([1.5, 4.5, 9. ]), resampler.grouping, direction="new_to_orig")
array([1.5, 1.5, 4.5, 4.5, 4.5, 4.5, 9. , 9. , 9. , 9. , 9. ])

get_optimal_grouping(target_n_layers, method='equal_thickness')[source]

Generate breakpoint proposal for a target layer count.

Parameters:

target_n_layers (int) – Desired number of grouped layers.
method ({'equal_thickness', 'equal_layers'}, optional) – Strategy for generating breakpoints.

Returns:

Breakpoints that can be passed to create_grouping.

Return type:

list of int

Raises:

ValueError – If method is unsupported.

Notes

Returned breakpoints can be passed directly to create_grouping().

Examples

>>> resampler = SoilLayerResampler([10,10,10,20,20,30,30,40,50,50,50])
>>> bp = resampler.get_optimal_grouping(3, method="equal_thickness")
>>> isinstance(bp, list)
True