landlab.components.soil_moisture.infiltrate_soil_green_ampt

class SoilInfiltrationGreenAmpt[source]

Bases: Component

Infiltrate surface water into a soil following the Green-Ampt method.

This component calculates the infiltation of surface water into the soil, using the Green-Ampt method. The component tracks the depth of infiltrated water over time, in the field soil_water_infiltration__depth. It also modifies the depth of surface water (surface_water__depth) as surface water progressively infiltrates into the soil below.

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.components import SoilInfiltrationGreenAmpt
>>> mg = RasterModelGrid((4, 3), xy_spacing=10.0)
>>> hydraulic_conductivity = mg.ones("node") * 1.0e-6
>>> hydraulic_conductivity.reshape((4, 3))[0:2, :] *= 10000.0
>>> h = mg.add_ones("surface_water__depth", at="node")
>>> h *= 0.01
>>> d = mg.add_ones("soil_water_infiltration__depth", at="node", dtype=float)
>>> d *= 0.2
>>> SI = SoilInfiltrationGreenAmpt(
...     mg, hydraulic_conductivity=hydraulic_conductivity
... )
>>> for i in range(10):  # 100s total
...     SI.run_one_step(10.0)
...
>>> mg.at_node["surface_water__depth"]
array([1.00000000e-08, 1.00000000e-08, 1.00000000e-08,
       1.00000000e-08, 1.00000000e-08, 1.00000000e-08,
       9.88530416e-03, 9.88530416e-03, 9.88530416e-03,
       9.88530416e-03, 9.88530416e-03, 9.88530416e-03])
>>> mg.at_node["soil_water_infiltration__depth"]
array([0.20999999, 0.20999999, 0.20999999, 0.20999999, 0.20999999,
       0.20999999, 0.2001147 , 0.2001147 , 0.2001147 , 0.2001147 ,
       0.2001147 , 0.2001147 ])

Notes

This code is based on an overland flow model by Francis Rengers and colleagues, after Julien et al., 1995. The infiltration scheme follows the Green and Ampt equation. It was implemented in Landlab by DEJH, March 2016.

Where to learn more

A description of the Green-Ampt infiltration equation can be found in many hydrology texts, as well as online resources. The original theory was published by Green and Ampt (1911).

References

Required Software Citation(s) Specific to this Component

Rengers, F. K., McGuire, L. A., Kean, J. W., Staley, D. M., and Hobley, D.: Model simulations of flood and debris flow timing in steep catchments after wildfire, Water Resour. Res., 52, 6041–6061, doi:10.1002/2015WR018176, 2016.

Additional References

Julien, P. Y., Saghafian, B., and Ogden, F. L.: Raster-based hydrologic modeling of spatially-varied surface runoff, J. Am. Water Resour. As., 31, 523–536, doi:10.1111/j.17521688.1995.tb04039.x, 1995.

Green, W. H., & Ampt, G. A. (1911). Studies on Soil Phyics. The Journal of Agricultural Science, 4(1), 1-24.

Parameters:

  • grid (RasterModelGrid) – A grid.

  • hydraulic_conductivity (float, array, or field name (m/s)) – The soil effective hydraulic conductivity.

  • soil_bulk_density (float (kg/m**3)) – The dry bulk density of the soil.

  • rock_density (float (kg/m**3)) – The density of the soil constituent material (i.e., lacking porosity).

  • initial_soil_moisture_content (float (m**3/m**3, 0. to 1.)) – The fraction of the initial pore space filled with water.

  • soil_type (str) – A soil type to automatically set soil_pore_size_distribution_index and soil_bubbling_pressure, using mean values from Rawls et al., 1992. The following options are supported: ‘sand’, loamy sand’, ‘sandy loam’, ‘loam’, ‘silt loam’, ‘sandy clay loam’, ‘clay loam’, ‘silty clay loam’, ‘sandy clay’, ‘silty clay’, or ‘clay’.

  • volume_fraction_coarse_fragments (float (m**3/m**3, 0. to 1.)) – The fraction of the soil made up of rocky fragments with very little porosity, with diameter > 2 mm.

  • coarse_sed_flag (boolean, optional) – If this flag is set to true, the fraction of coarse material in the soil column with be used as a correction for phi, the porosity factor.

  • surface_water_minimum_depth (float (m), optional) – A minimum water depth to stabilize the solutions for surface flood modelling. Leave as the default in most normal use cases.

  • soil_pore_size_distribution_index (float, optional) – An index describing the distribution of pore sizes in the soil, and controlling effective hydraulic conductivity at varying water contents, following Brooks and Corey (1964). Can be set by soil_type. Typically denoted “lambda”.

  • soil_bubbling_pressure (float (m), optional) – The bubbling capillary pressure of the soil, controlling effective hydraulic conductivity at varying water contents, following Brooks and Corey (1964). Can be set by soil_type. Typically denoted “h_b”.

  • wetting_front_capillary_pressure_head (float (m), optional) – The effective head at the wetting front in the soil driven by capillary pressure in the soil pores. If not set, will be calculated by the component from the pore size distribution and bubbling pressure, following Brooks and Corey.

SOIL_PROPS = {'clay': (0.165, 0.373), 'clay loam': (0.242, 0.2589), 'loam': (0.252, 0.1115), 'loamy sand': (0.553, 0.0869), 'sand': (0.694, 0.0726), 'sandy clay': (0.223, 0.2917), 'sandy clay loam': (0.319, 0.2808), 'sandy loam': (0.378, 0.1466), 'silt loam': (0.234, 0.2076), 'silty clay': (0.15, 0.3419), 'silty clay loam': (0.177, 0.3256)}
__init__(grid, hydraulic_conductivity=0.005, soil_bulk_density=1590.0, rock_density=2650.0, initial_soil_moisture_content=0.15, soil_type='sandy loam', volume_fraction_coarse_fragments=0.2, coarse_sed_flag=False, surface_water_minimum_depth=1e-08, soil_pore_size_distribution_index=None, soil_bubbling_pressure=None, wetting_front_capillary_pressure_head=None)[source]
Parameters:

  • grid (RasterModelGrid) – A grid.

  • hydraulic_conductivity (float, array, or field name (m/s)) – The soil effective hydraulic conductivity.

  • soil_bulk_density (float (kg/m**3)) – The dry bulk density of the soil.

  • rock_density (float (kg/m**3)) – The density of the soil constituent material (i.e., lacking porosity).

  • initial_soil_moisture_content (float (m**3/m**3, 0. to 1.)) – The fraction of the initial pore space filled with water.

  • soil_type (str) – A soil type to automatically set soil_pore_size_distribution_index and soil_bubbling_pressure, using mean values from Rawls et al., 1992. The following options are supported: ‘sand’, loamy sand’, ‘sandy loam’, ‘loam’, ‘silt loam’, ‘sandy clay loam’, ‘clay loam’, ‘silty clay loam’, ‘sandy clay’, ‘silty clay’, or ‘clay’.

  • volume_fraction_coarse_fragments (float (m**3/m**3, 0. to 1.)) – The fraction of the soil made up of rocky fragments with very little porosity, with diameter > 2 mm.

  • coarse_sed_flag (boolean, optional) – If this flag is set to true, the fraction of coarse material in the soil column with be used as a correction for phi, the porosity factor.

  • surface_water_minimum_depth (float (m), optional) – A minimum water depth to stabilize the solutions for surface flood modelling. Leave as the default in most normal use cases.

  • soil_pore_size_distribution_index (float, optional) – An index describing the distribution of pore sizes in the soil, and controlling effective hydraulic conductivity at varying water contents, following Brooks and Corey (1964). Can be set by soil_type. Typically denoted “lambda”.

  • soil_bubbling_pressure (float (m), optional) – The bubbling capillary pressure of the soil, controlling effective hydraulic conductivity at varying water contents, following Brooks and Corey (1964). Can be set by soil_type. Typically denoted “h_b”.

  • wetting_front_capillary_pressure_head (float (m), optional) – The effective head at the wetting front in the soil driven by capillary pressure in the soil pores. If not set, will be calculated by the component from the pore size distribution and bubbling pressure, following Brooks and Corey.

static __new__(cls, *args, **kwds)
static calc_moisture_deficit(soil_bulk_density=1590.0, rock_density=2650.0, volume_fraction_coarse_fragments=0.0, soil_moisture_content=0.0)[source]

Calculate the moisture deficit in a soil.

Parameters:

  • soil_bulk_density (float or array of float) – Bulk density of the soil [kg / m3].

  • rock_density (float or array of float) – Density of rock [kg / m3].

  • volume_fraction_coarse_fragments (float or array of float) – Volume fraction of sediment made up of coarse grains [-].

  • soil_moisture_content (float or array of float) – Fraction of soil filled with water [-].

Returns:

Moisture deficit.

Return type:

float or array of float

static calc_pressure_head(lam, h_b)[source]

Calculate pressure head.

Pressure head is set using lambda and h_b, using an equation after Brooks-Corey (1964), following Rawls et al., 1992.

Parameters:

  • lam (float, optional) – Pore-size distribution index. Exponent that describes the distribution of pore sizes in the soil, and controls effective hydraulic conductivity at varying water contents, following Brooks and Corey (1964) [-].

  • h_b (float (m), optional) – Bubbling pressure. Capillary pressure of the soil, controlling effective hydraulic conductivity at varying water contents, following Brooks and Corey (1964) [m]

static calc_soil_pressure(soil_type=None, soil_pore_size_distribution_index=1.0, soil_bubbling_pressure=0.0)[source]

Calculate capillary pressure in a soil type.

Parameters:

  • soil_type (str, optional) – The name of a soil type.

  • soil_pore_size_distribution_index (float) – Pore-size distribution index [-].

  • soil_bubbling_pressure (float) – Bubbling pressure [m].

property capillary_pressure

Capillary pressure of soil.

cite_as = '\n    @article{rengers2016model,\n      author = {Rengers, F K and McGuire, L A and Kean, J W and Staley, D M\n                and Hobley, D E J},\n      title = {{Model simulations of flood and debris flow timing in steep\n                catchments after wildfire}},\n      doi = {10.1002/2015wr018176},\n      pages = {6041 -- 6061},\n      number = {8},\n      volume = {52},\n      journal = {Water Resources Research},\n      year = {2016},\n    }\n    '
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 = (('soil_water_infiltration__depth', 'Water column height above the surface previously absorbed into the soil. Note that this is NOT the actual depth of the wetted front, which also depends on the porosity.'), ('surface_water__depth', 'Depth of water on the surface'))
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.

property hydraulic_conductivity

Hydraulic conductivity of soil.

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 = ('soil_water_infiltration__depth', 'surface_water__depth')
property min_water

Minimum surface water depth.

property moisture_deficit

Moisture deficit of soil.

name = 'SoilInfiltrationGreenAmpt'
optional_var_names = ()
output_var_names = ('soil_water_infiltration__depth', 'surface_water__depth')
run_one_step(dt)[source]

Update fields with current hydrologic conditions.

Parameters:

dt (float (s)) – The imposed timestep for the model.

property shape

Return the grid shape attached to the component, if defined.

unit_agnostic = False
units = (('soil_water_infiltration__depth', 'm'), ('surface_water__depth', 'm'))
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 = (('soil_water_infiltration__depth', 'node'), ('surface_water__depth', 'node'))
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