RUFAS.routines.field.soil.soil_erosion module#

class RUFAS.routines.field.soil.soil_erosion.SoilErosion(soil_data: SoilData | None, field_size: float | None = None)#

Bases: object

Manages and simulates soil erosion based on the Modified Universal Soil Loss Equation (MUSLE).

Parameters#

soil_dataSoilData, optional: The SoilData object used by this module to track and simulate erosion.
field_sizefloat, optional, default=None: The size of the field (ha).

Attributes#

dataSoilData: The SoilData instance used for tracking and simulating soil erosion throughout the simulation process.

__init__(soil_data: SoilData | None, field_size: float | None = None)#

This method initializes the SoilData object that this module will work with, or create one if none provided.

Parameters#

soil_dataSoilData, optional: The SoilData object used by this module to track erosion, creates new one if one is not provided.
field_sizefloat, optional: Used to initialize a SoilData object for this module to work with, if a pre-configured SoilData object is not provided (ha)

erode(field_size: float, minimum_cover_management_factor: float, surface_residue: float, rainfall: float) → None#

Main routine for SoilErosion. Runs necessary soil erosion methods and updates attributes.

Parameters#

field_sizefloat: Size of the field that contains this Soil object (hectares).
minimum_cover_management_factorfloat: Minimum value for cover and management factor for water erosion applicable to land cover/plant (unitless).
surface_residuefloat: Amount of residue on the soil surface (kg per hectare).
rainfallfloat: Amount of rain that fell on the field on the current day (mm).

Notes#

This method calculates the mass of soil that gets eroded from the soil profile based on the content of the soil, how the soil is being farmed, how much rainfall there is and how much of that rain gets absorbed into the soil, and the geometry of the field.

static _determine_coarse_sand_factor(sand_fraction: float, silt_fraction: float) → float#

Calculates the coarseness factor of soil erodibility.

Parameters#

sand_fractionfloat: Fraction of soil content that is sand.
silt_fractionfloat: Fraction of soil content that is silt.

Notes#

The coarseness of a soil affects the overall erodibility of the soil. Specifically, soils with high levels of coarse-sand content will have relatively low erodibility compared to soils with less sand.

Returns#

float: Coarseness factor of erodibility, based on sand content (unitless).

References#

SWAT Theoretical documentation eqn. 4:1.1.6

static _determine_clay_silt_ratio_factor(silt_fraction: float, clay_fraction: float) → float#

Calculates the component factor of erodibility that is based on the clay-silt ratio.

Parameters#

silt_fractionfloat: Fraction of silt in the given layer of soil.
clay_fractionfloat: Fraction of clay in the given layer of soil.

Notes#

The clay-silt ratio affects the erodibility of the soil, specifically soils with a high ratio of clay to silt are less susceptible to erosion than soils with lower ratios of clay to silt.

Returns#

float: The clay-silt ratio factor, based on clay and silt content (unitless).

References#

SWAT Theoretical documentation eqn. 4:1.1.7

static _determine_carbon_content_factor(organic_carbon_fraction: float) → float#

Calculate a factor based on the fraction of organic carbon content for use in calculating soil erodibility factor.

Parameters#

organic_carbon_fractionfloat: The fraction of organic carbon content in the given layer of soil.

Notes#

The amount of organic carbon content in the soil affects the erodibility of the soil. Soils with higher amounts of organic carbon content will have less erosion compared to soils with lower organic carbon content.

Returns#

float: The carbon factor of erodibility based on the organic carbon content of the soil (unitless).

References#

SWAT Theoretical documentation eqn. 4:1.1.8

static _determine_high_sand_factor(sand_fraction: float) → float#

Calculate a factor based on the percent sand content for use in calculating soil erodibility factor.

Parameters#

sand_fractionfloat: The fraction of sand in the given layer of soil.

Notes#

When a soil has an extremely high sand content, it reduces the erodibility of that soil.

Returns#

float: The high sand content factor of erodibility, based on the amount of sand in the soil (unitless).

References#

SWAT Theoretical documentation eqn. 4:1.1.9

static _determine_soil_erodibility_factor(sand_fraction: float, silt_fraction: float, clay_fraction: float, organic_carbon_fraction: float) → float#

Calculate the soil erodibility factor for use in calculating the sediment yield on a given day.

Parameters#

sand_fractionfloat: Fraction of sand in the given layer of soil.
silt_fractionfloat: Fraction of silt in the given layer of soil.
clay_fractionfloat: Fraction of clay in the given layer of soil.
organic_carbon_fractionfloat: Fraction of organic carbon content in the given layer of soil.

Notes#

Some soils are more prone to erosion than others, based on how much sand, silt, clay, and organic carbon they contain.

Returns#

float: The soil erodibility factor based on its coarse sand content, clay-silt ratio, clay content, and organic carbon content (compound unit, irrelevant).

Reference#

SWAT Theoretical documentation eqn. 4:1.1.5

static _determine_cover_management_factor(minimum_cover_management_factor: float, surface_residue: float) → float#

Calculate cover and management factor for use in calculating sediment yield.

Parameters#

minimum_cover_management_factorfloat: Minimum value for cover and management factor for land cover (unitless).
surface_residuefloat: Amount of residue on the soil surface (kg per hectare).

Notes#

This factor accounts for what is planted in and/or physically covering the field. Erodibility is affected by this because rainfall energy is either reduced or entirely eliminated when it hits the plant canopy or residue on the soil surface, which means less energy is transferred to soil when the water reaches it.

Returns#

float: The cover and management factor (unitless).

References#

SWAT Theoretical documentation eqn. 4:1.1.10

static _determine_support_practice_factor() → float#: SWAT Reference: section 4:1.1.3 (only applies to fields that are doing contour tillage/planting, stripcropping, and/or terracing)

static _determine_exponential_term(average_subbasin_slope: float) → float#

Calculate the exponential term used to determine the topographic factor.

Parameters#

average_subbasin_slopefloat: Average slope fraction of the subbasin (unitless).

Returns#

float: The exponential term (unitless).

References#

SWAT Theoretical documentation eqn. 4:1.1.13

static _determine_topographic_factor(slope_length: float, average_subbasin_slope: float) → float#

Calculate the topographic factor, which represents the expected ratio of soil loss per unit area from a field slope to that from a 22.1 m length of uniform 9% slope under otherwise identical conditions.

Parameters#

slope_lengthfloat: Length of the slope (m).
average_subbasin_slopefloat: Average slope fraction of the subbasin (m rise over m run).

Returns#

float: The topographic factor (unitless).

References#

SWAT Theoretical documentation eqn. 4:1.1.12

Notes#

The length and slope of a soil have an effect on erodibility, with shorter lengths and steeper slopes resulting in more soil erosion. A shorter length means more erosion because sediment does not have to travel as far to reach channels and be removed from the soil. A steeper slope means that there is less resistance against the gravitational forces acting on a piece of sediment as it moves down the slope, resulting in the soil eroding more easily.

arctan(tan(x)) == x does not always hold, it is only true from -90 to 90 degrees, inclusive. It is safe to use here because there will never be a field at an angle < -90 or > 90 degrees.

static _determine_coarse_fragment_factor(rock_fraction: float) → float#

Calculate the coarse fragment factor for use in calculating sediment yield.

Parameters#

rock_fractionfloat: Fraction rock in the first soil layer.

Notes#

The mass of rocks is much greater than particles of sand, silt, clay, etc., requiring significantly more force to move them off a field, resulting in slower erosion in soils with higher rock content.

Returns#

float: Coarse fragment factor based on the rock content of the soil (unitless).

References#

SWAT Theoretical documentation eqn. 4:1.1.15

static _determine_peak_runoff_rate(surface_runoff: float, rainfall: float, slope_length: float, manning: float, average_subbasin_slope: float, field_size: float) → float#

Determines the maximum runoff flow rate that occurs with a given rainfall event.

Parameters#

surface_runofffloat: Amount of rainfall that did not infiltrate into the soil on the current day (mm).
rainfallfloat: Amount of rainfall on the current day (mm).
slope_lengthfloat: Length of the subbasin slope (m).
manningfloat: Manning roughness coefficient for the subbasin (unitless).
average_subbasin_slopefloat: Average slope length of the subbasin expressed as rise over run (meters / meters).
field_sizefloat: Size of the field (ha)

Returns#

float: Peak runoff rate (cubic meters per second).

References#

SWAT Theoretical documentation equation 2:1.3.1

Notes#

This equation actually demands the area of the subbasin, not the field, as a parameter. But the field area was used in the old code, and is used here until the data for subbasin areas can be found.

static _determine_runoff_coefficient(surface_runoff: float, rainfall: float) → float#

Calculates the surface runoff coefficient for the current day.

Parameters#

surface_runofffloat: Amount of rainfall that did not infiltrate into the soil on the current day (mm).
rainfallfloat: Amount of rainfall on the current day (mm).

Returns#

float: Ratio of runoff to rainfall on the current day (unitless).

References#

SWAT Theoretical documentation equation 2:1.3.15

static _determine_rainfall_intensity(rainfall: float, slope_length: float, manning: float, average_subbasin_slope: float) → float#

Determines the average rainfall rate during the time of concentration.

Parameters#

rainfallfloat: Amount of rain that fell on the current day (mm).
slope_lengthfloat: Length of the subbasin slope (m).
manningfloat: Manning roughness coefficient for the subbasin (unitless).
average_subbasin_slopefloat: Average slope length of the subbasin expressed as rise over run (meters / meters).

Returns#

float: Rainfall intensity (mm / hour).

References#

SWAT Theoretical documentation equation 2:1.3.16

static _determine_time_of_concentration(slope_length: float, manning: float, average_subbasin_slope) → float#

Calculates the time of concentration for the subbasin.

Parameters#

slope_lengthfloat: Length of the subbasin slope (m).
manningfloat: Manning roughness coefficient for the subbasin (unitless).
average_subbasin_slopefloat: Average slope length of the subbasin expressed as rise over run (m / m).

Returns#

float: RufasTime of concentration (hour).

References#

SWAT Theoretical documentation section 2:1.3.6

Notes#

According to the SWAT Theoretical documentation, “the time of concentration is the amount of time from the beginning of a rainfall event until the entire subbasin area is contributing to flow at the outlet.”. In SWAT, this is calculated as the overland flow time of concentration plus the channel flow time of concentration, but in this version of the RuFaS Field module as well as the previous one, it is only the overland flow time of concentration. This equation in SWAT also assumes an average flow rate of 6.35 mm per hour.

static _determine_half_hour_rainfall_fraction(rainfall: float) → float#

Calculates the fraction of total rainfall that falls during the half-hour of most intense rainfall of this storm event.

Parameters#

rainfallfloat: Amount of rain that fell on the current day (mm).

Returns#

float: The fraction of total rainfall that fell during the half-hour of most intense rainfall on the current day (unitless).

References#

SWAT Theoretical documentation section 1:3.2.2

Notes#

This method for calculating the maximum half-hour rainfall is from the old version of the Field module, and has been significantly simplified from the method in SWAT.

static _determine_fraction_rainfall_during_time_of_concentration(time_of_concentration: float, half_hour_rainfall_fraction: float) → float#

Calculates the fraction of rainfall that occurs over the time of concentration.

Parameters#

time_of_concentrationfloat: RufasTime of concentration for this subbasin (hours).
half_hour_rainfall_fractionfloat: Fraction of rainfall that falls during half-hour of highest rainfall intensity (unitless).

Returns#

float: Fraction of rainfall that occurs over the time of concentration (unitless).

References#

SWAT Theoretical documentation equation 2:1.3.19

static _determine_sediment_yield(surface_area_runoff: float, peak_runoff_rate: float, field_area: float, soil_erodibility_factor: float, cover_management_factor: float, support_practice_factor: float, topographic_factor: float, coarse_fragment_factor: float) → float#

Calculate the sediment yield for a given day.

Parameters#

surface_area_runofffloat: Surface runoff volume (mm per hectare).
peak_runoff_ratefloat: Peak runoff rate (cubic meters per second).
field_areafloat: Area of the field/HRU that contains this soil (hectares).
soil_erodibility_factorfloat: Factor for how easily the soil erodes (unitless).
cover_management_factorfloat: Ratio of soil loss from land cropped under given conditions to corresponding loss from clean-tilled, continuous fallow (unitless).
support_practice_factorfloat: Ratio of soil loss with specific support practice to corresponding loss with up-and-down slope culture (unitless).
topographic_factorfloat: Expected ratio of soil loss per unit area from a field slope to that from a 22.1 m length of uniform 9% slope under identical conditions (unitless).
coarse_fragment_factorfloat: Factor that adjusts for the percent rock in the first soil layer (unitless).

Returns#

float: Sediment yield on a given day (metric tons).

static _determine_adjusted_sediment_yield(sediment_yield: float, snow_water_content: float) → float#

Adjust the sediment yield based on the amount of snow cover.

Parameters#

sediment_yieldfloat: Sediment yield on a given day (metric tons).
snow_water_contentfloat: Water content of the snow cover (mm).

Returns#

float: The sediment yield on a given day adjusted for the water content of the snow cover.

Reference#

SWAT Theoretical documentation eqn. 4:1.3.1