landlab.components.soil_moisture.soil_moisture_dynamics¶

class SoilMoisture[source]¶

Bases: Component

Landlab component that simulates root-zone average soil moisture at each cell using inputs of potential evapotranspiration, live leaf area index, and vegetation cover.

This component uses a single soil moisture layer and models soil moisture loss through transpiration by plants, evaporation by bare soil, and leakage. The solution of water balance is based on Laio et. al 2001. The component requires fields of initial soil moisture, rainfall input (if any), time to the next storm and potential transpiration.

Ref: Laio, F., Porporato, A., Ridolfi, L., & Rodriguez-Iturbe, I. (2001). Plants in water-controlled ecosystems: active role in hydrologic processes and response to water stress: II. Probabilistic soil moisture dynamics. Advances in Water Resources, 24(7), 707-723.

Code author: Sai Nudurupati and Erkan Istanbulluoglu

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.components.soil_moisture import SoilMoisture
>>> grid = RasterModelGrid((5, 4), xy_spacing=(0.2, 0.2))
>>> SoilMoisture.name
'Soil Moisture'
>>> sorted(SoilMoisture.output_var_names)
['soil_moisture__root_zone_leakage',
 'soil_moisture__saturation_fraction',
 'surface__evapotranspiration',
 'surface__runoff',
 'vegetation__water_stress']
>>> sorted(SoilMoisture.units)
[('rainfall__daily_depth', 'mm'),
 ('soil_moisture__initial_saturation_fraction', 'None'),
 ('soil_moisture__root_zone_leakage', 'mm'),
 ('soil_moisture__saturation_fraction', 'None'),
 ('surface__evapotranspiration', 'mm'),
 ('surface__potential_evapotranspiration_rate', 'mm'),
 ('surface__runoff', 'mm'),
 ('vegetation__cover_fraction', 'None'),
 ('vegetation__live_leaf_area_index', 'None'),
 ('vegetation__plant_functional_type', 'None'),
 ('vegetation__water_stress', 'None')]
>>> grid["cell"]["vegetation__plant_functional_type"] = np.zeros(
...     grid.number_of_cells, dtype=int
... )
>>> _ = grid.add_zeros("vegetation__cover_fraction", at="cell")
>>> _ = grid.add_zeros("vegetation__live_leaf_area_index", at="cell")
>>> _ = grid.add_zeros("surface__potential_evapotranspiration_rate", at="cell")
>>> _ = grid.add_zeros("soil_moisture__initial_saturation_fraction", at="cell")
>>> _ = grid.add_zeros("rainfall__daily_depth", at="cell")
>>> SM = SoilMoisture(grid)
>>> SM.grid.number_of_cell_rows
3
>>> SM.grid.number_of_cell_columns
2
>>> SM.grid is grid
True
>>> import numpy as np
>>> np.allclose(grid.at_cell["soil_moisture__saturation_fraction"], 0.0)
True
>>> grid["cell"]["surface__potential_evapotranspiration_rate"] = np.array(
...     [0.2554777, 0.2554777, 0.22110221, 0.22110221, 0.24813062, 0.24813062]
... )
>>> grid["cell"]["soil_moisture__initial_saturation_fraction"] = 0.75 * np.ones(
...     grid.number_of_cells
... )
>>> grid["cell"]["vegetation__live_leaf_area_index"] = 2.0 * np.ones(
...     grid.number_of_cells
... )
>>> grid["cell"]["vegetation__cover_fraction"] = np.ones(grid.number_of_cells)
>>> grid["cell"]["rainfall__daily_depth"] = 25.0 * np.ones(grid.number_of_cells)
>>> SM.current_time = 0.5
>>> current_time = SM.update()
>>> np.allclose(grid.at_cell["soil_moisture__saturation_fraction"], 0.0)
False

References

Required Software Citation(s) Specific to this Component

None Listed

Additional References

Laio, F., Porporato, A., Ridolfi, L., Rodriguez-Iturbe, I. (2001). Plants in water-controlled ecosystems: active role in hydrologic processes and response to water stress II. Probabilistic soil moisture dynamics. Advances in Water Resources 24(7), 707-723. https://dx.doi.org/10.1016/s0309-1708(01)00005-7

Parameters:

grid (RasterModelGrid) – A grid.
runon (float, optional) – Runon from higher elevation (mm).
f_bare (float, optional) – Fraction to partition PET for bare soil (None).
soil_ew (float, optional) – Residual Evaporation after wilting (mm/day).
intercept_cap (float, optional) – Plant Functional Type (PFT) specific full canopy interception capacity.
zr (float, optional) – Root depth (m).
I_B (float, optional) – Infiltration capacity of bare soil (mm/h).
I_V (float, optional) – Infiltration capacity of vegetated soil (mm/h).
pc (float, optional) – Soil porosity (None).
fc (float, optional) – Soil saturation degree at field capacity (None).
sc (float, optional) – Soil saturation degree at stomatal closure (None).
wp (float, optional) – Soil saturation degree at wilting point (None).
hgw (float, optional) – Soil saturation degree at hygroscopic point (None).
beta (float, optional) – Deep percolation constant = 2*b+3 where b is water retention (None).
LAI_max (float, optional) – Maximum leaf area index (m^2/m^2).
LAIR_max (float, optional) – Reference leaf area index (m^2/m^2).
method (str) – Method used
Tr (float, optional) – Storm duration (hours).
Tb (float, optional) – Inter-storm duration (hours).
current_time (float) – Current time (years).

property Tb¶: Storm duration (hours).

property Tr¶: Inter-storm duration (hours).

__init__(grid, runon=0.0, f_bare=0.7, soil_ew=0.1, intercept_cap_grass=1.0, zr_grass=0.3, I_B_grass=20.0, I_V_grass=24.0, pc_grass=0.43, fc_grass=0.56, sc_grass=0.33, wp_grass=0.13, hgw_grass=0.1, beta_grass=13.8, LAI_max_grass=2.0, LAIR_max_grass=2.88, intercept_cap_shrub=1.5, zr_shrub=0.5, I_B_shrub=20.0, I_V_shrub=40.0, pc_shrub=0.43, fc_shrub=0.56, sc_shrub=0.24, wp_shrub=0.13, hgw_shrub=0.1, beta_shrub=13.8, LAI_max_shrub=2.0, LAIR_max_shrub=2.0, intercept_cap_tree=2.0, zr_tree=1.3, I_B_tree=20.0, I_V_tree=40.0, pc_tree=0.43, fc_tree=0.56, sc_tree=0.22, wp_tree=0.15, hgw_tree=0.1, beta_tree=13.8, LAI_max_tree=4.0, LAIR_max_tree=4.0, intercept_cap_bare=1.0, zr_bare=0.15, I_B_bare=20.0, I_V_bare=20.0, pc_bare=0.43, fc_bare=0.56, sc_bare=0.33, wp_bare=0.13, hgw_bare=0.1, beta_bare=13.8, LAI_max_bare=0.01, LAIR_max_bare=0.01, method='Grid', Tb=24.0, Tr=0.0, current_time=0)[source]¶

Parameters:

grid (RasterModelGrid) – A grid.
runon (float, optional) – Runon from higher elevation (mm).
f_bare (float, optional) – Fraction to partition PET for bare soil (None).
soil_ew (float, optional) – Residual Evaporation after wilting (mm/day).
intercept_cap (float, optional) – Plant Functional Type (PFT) specific full canopy interception capacity.
zr (float, optional) – Root depth (m).
I_B (float, optional) – Infiltration capacity of bare soil (mm/h).
I_V (float, optional) – Infiltration capacity of vegetated soil (mm/h).
pc (float, optional) – Soil porosity (None).
fc (float, optional) – Soil saturation degree at field capacity (None).
sc (float, optional) – Soil saturation degree at stomatal closure (None).
wp (float, optional) – Soil saturation degree at wilting point (None).
hgw (float, optional) – Soil saturation degree at hygroscopic point (None).
beta (float, optional) – Deep percolation constant = 2*b+3 where b is water retention (None).
LAI_max (float, optional) – Maximum leaf area index (m^2/m^2).
LAIR_max (float, optional) – Reference leaf area index (m^2/m^2).
method (str) – Method used
Tr (float, optional) – Storm duration (hours).
Tb (float, optional) – Inter-storm duration (hours).
current_time (float) – Current time (years).

static __new__(cls, *args, **kwds)¶

cite_as = ''¶

property coords¶: Return the coordinates of nodes on grid attached to the component.

property current_time¶

Current time.

Some components may keep track of the current time. In this case, the current_time attribute is incremented. Otherwise it is set to None.

Return type:: current_time

definitions = (('rainfall__daily_depth', 'Rain in (mm) as a field, allowing spatio-temporal soil moisture saturation analysis.'), ('soil_moisture__initial_saturation_fraction', 'initial soil_moisture__saturation_fraction'), ('soil_moisture__root_zone_leakage', 'leakage of water into deeper portions of the soil not accessible to the plant'), ('soil_moisture__saturation_fraction', 'relative volumetric water content (theta) - limits=[0,1]'), ('surface__evapotranspiration', 'actual sum of evaporation and plant transpiration'), ('surface__potential_evapotranspiration_rate', 'potential sum of evaporation and potential transpiration'), ('surface__runoff', 'runoff from ground surface'), ('vegetation__cover_fraction', 'fraction of land covered by vegetation'), ('vegetation__live_leaf_area_index', 'one-sided green leaf area per unit ground surface area'), ('vegetation__plant_functional_type', 'classification of plants (int), grass=0, shrub=1, tree=2, bare=3, shrub_seedling=4, tree_seedling=5'), ('vegetation__water_stress', 'parameter that represents nonlinear effects of water deficit on plants'))¶

classmethod from_path(grid, path)¶

Create a component from an input file.

Parameters:

grid (ModelGrid) – A landlab grid.
path (str or file_like) – Path to a parameter file, contents of a parameter file, or a file-like object.

Returns:

A newly-created component.

Return type:

Component

property grid¶: Return the grid attached to the component.

initialize(runon=0.0, f_bare=0.7, soil_ew=0.1, intercept_cap_grass=1.0, zr_grass=0.3, I_B_grass=20.0, I_V_grass=24.0, pc_grass=0.43, fc_grass=0.56, sc_grass=0.33, wp_grass=0.13, hgw_grass=0.1, beta_grass=13.8, LAI_max_grass=2.0, LAIR_max_grass=2.88, intercept_cap_shrub=1.5, zr_shrub=0.5, I_B_shrub=20.0, I_V_shrub=40.0, pc_shrub=0.43, fc_shrub=0.56, sc_shrub=0.24, wp_shrub=0.13, hgw_shrub=0.1, beta_shrub=13.8, LAI_max_shrub=2.0, LAIR_max_shrub=2.0, intercept_cap_tree=2.0, zr_tree=1.3, I_B_tree=20.0, I_V_tree=40.0, pc_tree=0.43, fc_tree=0.56, sc_tree=0.22, wp_tree=0.15, hgw_tree=0.1, beta_tree=13.8, LAI_max_tree=4.0, LAIR_max_tree=4.0, intercept_cap_bare=1.0, zr_bare=0.15, I_B_bare=20.0, I_V_bare=20.0, pc_bare=0.43, fc_bare=0.56, sc_bare=0.33, wp_bare=0.13, hgw_bare=0.1, beta_bare=13.8, LAI_max_bare=0.01, LAIR_max_bare=0.01)[source]¶

Parameters:

grid (RasterModelGrid) – A grid.
runon (float, optional) – Runon from higher elevation (mm).
f_bare (float, optional) – Fraction to partition PET for bare soil (None).
soil_ew (float, optional) – Residual Evaporation after wilting (mm/day).
intercept_cap (float, optional) – Plant Functional Type (PFT) specific full canopy interception capacity.
zr (float, optional) – Root depth (m).
I_B (float, optional) – Infiltration capacity of bare soil (mm/h).
I_V (float, optional) – Infiltration capacity of vegetated soil (mm/h).
pc (float, optional) – Soil porosity (None).
fc (float, optional) – Soil saturation degree at field capacity (None).
sc (float, optional) – Soil saturation degree at stomatal closure (None).
wp (float, optional) – Soil saturation degree at wilting point (None).
hgw (float, optional) – Soil saturation degree at hygroscopic point (None).
beta (float, optional) – Deep percolation constant = 2*b+3 where b is water retention (None).
(None) (parameter)
LAI_max (float, optional) – Maximum leaf area index (m^2/m^2).
LAIR_max (float, optional) – Reference leaf area index (m^2/m^2).

initialize_optional_output_fields()¶

Create fields for a component based on its optional field outputs, if declared in _optional_var_names.

This method will create new fields (without overwrite) for any fields output by the component as optional. New fields are initialized to zero. New fields are created as arrays of floats, unless the component also contains the specifying property _var_type.

initialize_output_fields(values_per_element=None)¶

Create fields for a component based on its input and output var names.

This method will create new fields (without overwrite) for any fields output by, but not supplied to, the component. New fields are initialized to zero. Ignores optional fields. New fields are created as arrays of floats, unless the component specifies the variable type.

Parameters:: values_per_element (int (optional)) – On occasion, it is necessary to create a field that is of size (n_grid_elements, values_per_element) instead of the default size (n_grid_elements,). Use this keyword argument to acomplish this task.

input_var_names = ('rainfall__daily_depth', 'soil_moisture__initial_saturation_fraction', 'surface__potential_evapotranspiration_rate', 'vegetation__cover_fraction', 'vegetation__live_leaf_area_index', 'vegetation__plant_functional_type')¶

name = 'Soil Moisture'¶

optional_var_names = ()¶

output_var_names = ('soil_moisture__root_zone_leakage', 'soil_moisture__saturation_fraction', 'surface__evapotranspiration', 'surface__runoff', 'vegetation__water_stress')¶

property shape¶: Return the grid shape attached to the component, if defined.

unit_agnostic = False¶

units = (('rainfall__daily_depth', 'mm'), ('soil_moisture__initial_saturation_fraction', 'None'), ('soil_moisture__root_zone_leakage', 'mm'), ('soil_moisture__saturation_fraction', 'None'), ('surface__evapotranspiration', 'mm'), ('surface__potential_evapotranspiration_rate', 'mm'), ('surface__runoff', 'mm'), ('vegetation__cover_fraction', 'None'), ('vegetation__live_leaf_area_index', 'None'), ('vegetation__plant_functional_type', 'None'), ('vegetation__water_stress', 'None'))¶

update()[source]¶

Update fields with current loading conditions.

This method looks to the properties current_time, Tb, and Tr, and uses their values in updating fields.

classmethod var_definition(name)¶

Get a description of a particular field.

Parameters:: name (str) – A field name.
Returns:: A description of each field.
Return type:: tuple of (name, *description*)

classmethod var_help(name)¶

Print a help message for a particular field.

Parameters:: name (str) – A field name.

classmethod var_loc(name)¶

Location where a particular variable is defined.

Parameters:: name (str) – A field name.
Returns:: The location (‘node’, ‘link’, etc.) where a variable is defined.
Return type:: str

var_mapping = (('rainfall__daily_depth', 'cell'), ('soil_moisture__initial_saturation_fraction', 'cell'), ('soil_moisture__root_zone_leakage', 'cell'), ('soil_moisture__saturation_fraction', 'cell'), ('surface__evapotranspiration', 'cell'), ('surface__potential_evapotranspiration_rate', 'cell'), ('surface__runoff', 'cell'), ('vegetation__cover_fraction', 'cell'), ('vegetation__live_leaf_area_index', 'cell'), ('vegetation__plant_functional_type', 'cell'), ('vegetation__water_stress', 'cell'))¶

classmethod var_type(name)¶

Returns the dtype of a field (float, int, bool, str…).

Parameters:: name (str) – A field name.
Returns:: The dtype of the field.
Return type:: dtype

classmethod var_units(name)¶

Get the units of a particular field.

Parameters:: name (str) – A field name.
Returns:: Units for the given field.
Return type:: str

assert_method_is_valid(method)[source]¶