RUFAS.routines.field.soil.soil_data module

class RUFAS.routines.field.soil.soil_data.SoilData(*, name: str | None = 'generic soil configuration', soil_layers: ~typing.List[~RUFAS.routines.field.soil.layer_data.LayerData] | None = None, field_size: dataclasses.InitVar[float] = None, initial_water_content: float = None, initial_nitrates_total: float = None, annual_soil_evaporation_total: float = 0, annual_runoff_total: float = 0, annual_eroded_sediment_total: float = 0, annual_surface_runoff_total: float = 0, annual_runoff_fertilizer_phosphorus: float = 0, annual_soil_phosphorus_runoff: float = 0, annual_runoff_nitrates_total: float = 0, annual_runoff_ammonium_total: float = 0, annual_eroded_fresh_organic_nitrogen_total: float = 0, annual_eroded_stable_organic_nitrogen_total: float = 0, annual_eroded_active_organic_nitrogen_total: float = 0, water_evaporated: float = 0.0, second_moisture_condition_parameter: float = 85, previous_retention_parameter: float | None = None, average_subbasin_slope: float = 0.05, moisture_condition_parameter: float | None = None, accumulated_runoff: float = 0.0, infiltrated_water: float = 0.0, vadose_zone_layer: ~RUFAS.routines.field.soil.layer_data.LayerData | None = None, time_step: float = 24, albedo: float = 0.16, previous_temperature_effect: float = 0.8, snow_content: float = 0.0, snow_melt_amount: float = 0.0, previous_day_snow_temperature: float | None = None, current_day_snow_temperature: float | None = None, snow_lag_factor: float = 1.0, snow_coverage_fraction: float = 1.0, snow_melt_base_temperature: float = 0.5, snow_coverage_maximum: float = 1.0, snow_melt_factor_maximum: float = 4.5, snow_melt_factor_minimum: float = 4.5, water_sublimated: float = 0.0, slope_length: float = 3, manning: float = 0.4, eroded_sediment: float = 0, surface_runoff_volume: float | None = None, cover_type: str = 'BARE', full_available_phosphorus_pool: float = 0, available_phosphorus_pool: float = 0, recalcitrant_phosphorus_pool: float = 0, runoff_fertilizer_phosphorus: float = 0.0, days_since_application: int = 0, rain_events_after_fertilizer_application: int = 0, machine_manure: ~RUFAS.routines.field.soil.manure_pool.ManurePool = <factory>, grazing_manure: ~RUFAS.routines.field.soil.manure_pool.ManurePool = <factory>, soil_phosphorus_runoff: float = 0.0, nitrate_runoff: float = 0.0, ammonium_runoff: float = 0.0, eroded_fresh_organic_nitrogen: float = 0.0, eroded_stable_organic_nitrogen: float = 0.0, eroded_active_organic_nitrogen: float = 0.0, humus_mineralization_rate_factor: float = 0.0003, denitrification_rate_coefficient: float = 1.4, denitrification_threshold_water_content: float = 1.1, residue_fresh_organic_mineralization_rate: float = 0.05, plant_residue_lignin_composition: float = 0.17, plant_lignin_nitrogen_ratio: float = 0, plant_residue_metabolic_fraction: float = 0, crop_yield_nitrogen: float = 0)

Bases: object

This is a data class that stores and tracks all Soil attributes that are given in input files as well as ones that are generated by modules in Soil.

Attributes

namestring, optional, default “generic soil configuration”

Name of the soil configuration.

soil_layersList[LayerData], optional, default None

List of soil layer data objects, where the top layer is the 0th element and the bottom is the nth element.

field_sizeInitVar[float], default None

Size of the field (ha). Note: this attribute is only used for initialization. After that, it cannot be used.

initial_water_contentfloat, default None

Total soil water content at the beginning of a year, for use in determining annual change (mm).

initial_nitrates_totalfloat, default None

Total soil nitrate amounts at the beginning of a year, for use in determining annual change (kg per hectare).

annual_soil_evaporation_totalfloat, default 0

Cumulative total of water evaporated from the soil this year (mm).

annual_runoff_totalfloat, default 0

Cumulative total of runoff that occurred in a year (mm).

annual_eroded_sediment_totalfloat, default 0

Cumulative total of sediment that eroded in a year (metric tons).

annual_surface_runoff_totalfloat, default 0

Cumulative total of the volume of surface runoff that occurred in a year (mm per hectare).

annual_runoff_fertilizer_phosphorusfloat, default 0

Cumulative total of phosphorus from surface-applied fertilizer that was carried off the field by runoff (kg).

annual_runoff_machine_manure_inorganic_phosphorusfloat, default 0

Cumulative total of inorganic phosphorus from machine-applied manure that was carried off the field by runoff (kg).

annual_runoff_machine_manure_organic_phosphorusfloat, default 0

Cumulative total of organic phosphorus from machine-applied manure that was carried off the field by runoff (kg).

annual_runoff_grazing_manure_inorganic_phosphorusfloat, default 0

Cumulative total of inorganic phosphorus from grazer-applied manure that was carried off the field by runoff (kg).

annual_runoff_grazing_manure_organic_phosphorusfloat, default 0

Cumulative total of organic phosphorus from grazer-applied manure that was carried off the field by runoff (kg).

annual_soil_phosphorus_runofffloat, default 0

Cumulative total of phosphorus that was from the top layer of the soil profile by runoff (kg / ha).

annual_runoff_nitrates_totalfloat, default 0

Cumulative total of nitrates that were removed from the top soil layer by runoff (kg).

annual_runoff_ammonium_totalfloat, default 0

Cumulative total of ammonium that was removed from the top soil layer by runoff (kg).

annual_eroded_fresh_organic_nitrogen_totalfloat, default 0

Cumulative total of fresh organic nitrogen that was removed from the top soil layer by erosion (kg).

annual_eroded_stable_organic_nitrogen_totalfloat, default 0

Cumulative total of stable organic nitrogen that was removed from the top soil layer by erosion (kg).

annual_eroded_active_organic_nitrogen_totalfloat, default 0

Cumulative total of active organic nitrogen that was removed from the top soil layer by erosion (kg).

water_evaporatedfloat, default 0.0

Amount of water evaporated from the soil profile on the current day (mm).

second_moisture_condition_parameterfloat, default 85

‘Curve number’ parameter for average moisture conditions equation (unitless).

previous_retention_parameterOptional[float], default None

Retention parameter for the previous day (mm) (used in SWAT 2:1.1.9).

average_subbasin_slopefloat, default 0.05

Average slope of the subbasin expressed as rise over run (meters/meters).

moisture_condition_parameterOptional[float], default None

Curve number value adjusted for moisture content (unitless) (SWAT 2:1.1.11).

accumulated_runofffloat, default 0.0

Amount of rainfall discharged as runoff on the current day (mm).

infiltrated_waterfloat, default 0.0

Amount of water that infiltrated the soil profile on the day (mm).

vadose_zone_layerOptional[LayerData], default None

LayerData object that represents the vadose zone layer, where the top depth is set equal to the bottom depth of the lowest soil layer and the bottom depth is arbitrary, starting with no water.

time_stepfloat, default 24

Length of the time step over which percolation occurs (hours).

albedofloat, default 0.16

Proportion of solar radiation that is reflected by the soil surface (unitless).

previous_temperature_effectfloat, default 0.8

Variable that controls the influence of the previous day’s temperature on the current day’s temperature, ranging from 0 to 1, inclusive. SWAT sets the lag coefficient to 0.8 (unitless).

snow_contentfloat, default 0.0

Water content of the snow pack (mm H2O).

snow_melt_amountfloat, default 0.0

Water content of the snow that melted on the current day (mm H2O).

previous_day_snow_temperatureOptional[float], default None

Snow pack temperature on the previous day (ºC).

current_day_snow_temperatureOptional[float], default None

Snow pack temperature of the current day (ºC).

snow_lag_factorfloat, default 1.0

Snow pack temperature lag factor (unitless).

snow_coverage_fractionfloat, default 1.0

Fraction of snow coverage (unitless).

snow_melt_base_temperaturefloat, default 0.5

Snow melt base temperature (ºC). The snow pack will not melt until the snow pack temperature exceeds this threshold value.

snow_coverage_maximumfloat, default 1.0

Minimum snow water content that corresponds to 100% snow cover (mm H2O).

snow_melt_factor_maximumfloat, default 4.5

Melt factor for snow on June 21, SMFMX (mm H2O/°C-day).

snow_melt_factor_minimumfloat, default 4.5

Melt factor for snow on December 21, SMFMN (mm H2O/°C-day).

water_sublimatedfloat, default 0.0

Amount of snow water content lost through sublimation on the current day (mm).

slope_lengthfloat, default 3

Length of the slope (meters).

manningfloat, default 0.4

Manning roughness coefficient for this subbasin (unitless).

eroded_sedimentfloat, default 0

Cumulative amount of sediment that has been eroded off of the field in a day (metric tons).

surface_runoff_volumefloat, optional, default None

Volume of surface runoff (mm per hectare), used in SWAT equation 4:1.1.1.

cover_typestr, default “BARE”

The cover type of the soil surface, which can be bare, residue covered, or grassed.

full_available_phosphorus_poolfloat, default 0

Starting value of the available phosphorus pool (kg). This value does not change when phosphorus is removed from the available phosphorus pool, but does change when a new application of fertilizer phosphorus is applied.

available_phosphorus_poolfloat, default 0

Amount of phosphorus available for soil adsorption and leaching via runoff before the first rainfall event after application (kg).

recalcitrant_phosphorus_poolfloat, default 0

Amount of phosphorus available for soil adsorption and leaching via runoff after the first rainfall event (kg).

runoff_fertilizer_phosphorusfloat, default 0.0

Amount of solubilized phosphorus that has been leached off the field by runoff (kg).

days_since_applicationint, default 0

Number of days since phosphorus was applied to the field via fertilizer.

rain_events_after_fertilizer_applicationint, default 0

Number of rain events that have occurred since phosphorus was applied to the field via fertilizer.

soil_phosphorus_runofffloat, default 0.0

Amount of phosphorus removed from the surface soil layer by runoff (kg / ha).

nitrate_runofffloat, default 0.0

Amount of nitrate removed from the soil surface by runoff (kg / ha).

ammonium_runofffloat, default 0.0

Amount of ammonium removed from the soil surface by runoff (kg / ha).

eroded_fresh_organic_nitrogenfloat, default 0.0

Amount of fresh organic nitrogen removed from the soil surface by eroded sediment (kg / ha).

eroded_stable_organic_nitrogenfloat, default 0.0

Amount of stable organic nitrogen removed from the soil surface by eroded sediment (kg / ha).

eroded_active_organic_nitrogenfloat, default 0.0

Amount of active organic nitrogen removed from the soil surface by eroded sediment (kg / ha).

humus_mineralization_rate_factorfloat, default 0.0003

Rate factor for humus mineralization of active organic nutrients (nitrogen and phosphorus) (unitless). Reference: SWAT Input .BSN file, see “CMN” on page 101.

denitrification_rate_coefficientfloat, default 1.4

Controls the rate of denitrification in this layer of soil (unitless). Note: acceptable values for this attribute are in the range [0.0, 3.0]. Reference: SWAT Input .BSN file, see “CDN” on page 101.

denitrification_threshold_water_contentfloat, default 1.10

Fraction of field capacity water content above which denitrification takes place (unitless). Reference: SWAT Input .BSN file, see “SDNCO” on page 102.

residue_fresh_organic_mineralization_ratefloat, default 0.05

Rate coefficient for mineralization of residue fresh organic nutrients (nitrogen and phosphorus) (unitless). Reference: SWAT Input .BSN file (see “RSDCO” on page 101) and SWAT Input CROP.DAT file (see “RSDCO_PL” on page 205).

plant_residue_lignin_compositionfloat, default 0.17

Lignin fraction of plant residue (unitless).

plant_lignin_nitrogen_ratiofloat, default 0

Plant lignin to nitrogen ratio (unitless).

plant_residue_metabolic_fractionfloat, default 0

Plant residue fraction that is metabolic (unitless).

crop_yield_nitrogenfloat, default 0

Nitrogen contained in the harvested yield (kg/ha).

machine_manureManurePool

A ManurePool instance holding data for machine-applied manure.

grazing_manureManurePool

A ManurePool instance holding data for grazing-applied manure

name: str | None = 'generic soil configuration'

soil_layers: List[LayerData] | None = None

field_size: dataclasses.InitVar[float] = None

initial_water_content: float = None

initial_nitrates_total: float = None

annual_soil_evaporation_total: float = 0

annual_runoff_total: float = 0

annual_eroded_sediment_total: float = 0

annual_surface_runoff_total: float = 0

annual_runoff_fertilizer_phosphorus: float = 0

annual_soil_phosphorus_runoff: float = 0

annual_runoff_nitrates_total: float = 0

annual_runoff_ammonium_total: float = 0

annual_eroded_fresh_organic_nitrogen_total: float = 0

annual_eroded_stable_organic_nitrogen_total: float = 0

annual_eroded_active_organic_nitrogen_total: float = 0

water_evaporated: float = 0.0

second_moisture_condition_parameter: float = 85

previous_retention_parameter: float | None = None

average_subbasin_slope: float = 0.05

moisture_condition_parameter: float | None = None

accumulated_runoff: float = 0.0

infiltrated_water: float = 0.0

vadose_zone_layer: LayerData | None = None

time_step: float = 24

albedo: float = 0.16

previous_temperature_effect: float = 0.8

snow_content: float = 0.0

snow_melt_amount: float = 0.0

previous_day_snow_temperature: float | None = None

current_day_snow_temperature: float | None = None

snow_lag_factor: float = 1.0

snow_coverage_fraction: float = 1.0

snow_melt_base_temperature: float = 0.5

snow_coverage_maximum: float = 1.0

snow_melt_factor_maximum: float = 4.5

snow_melt_factor_minimum: float = 4.5

water_sublimated: float = 0.0

slope_length: float = 3

manning: float = 0.4

eroded_sediment: float = 0

surface_runoff_volume: float | None = None

cover_type: str = 'BARE'

full_available_phosphorus_pool: float = 0

available_phosphorus_pool: float = 0

recalcitrant_phosphorus_pool: float = 0

runoff_fertilizer_phosphorus: float = 0.0

days_since_application: int = 0

rain_events_after_fertilizer_application: int = 0

machine_manure: ManurePool

grazing_manure: ManurePool

soil_phosphorus_runoff: float = 0.0

nitrate_runoff: float = 0.0

ammonium_runoff: float = 0.0

eroded_fresh_organic_nitrogen: float = 0.0

eroded_stable_organic_nitrogen: float = 0.0

eroded_active_organic_nitrogen: float = 0.0

humus_mineralization_rate_factor: float = 0.0003

denitrification_rate_coefficient: float = 1.4

denitrification_threshold_water_content: float = 1.1

residue_fresh_organic_mineralization_rate: float = 0.05

plant_residue_lignin_composition: float = 0.17

plant_lignin_nitrogen_ratio: float = 0

plant_residue_metabolic_fraction: float = 0

crop_yield_nitrogen: float = 0

property total_residue: float

Amount of total plant residue, above and below-ground, on the field which is to be transferred to litter pools in the soil profile (kg/ha).

_subdivide_top_layer(field_size: float) → None

This method ensures that the soil profile has a top layer that is 20 mm deep.

Parameters

field_sizefloat

Size of the field (ha).

Notes

The presence of a top layer of soil that is 20 mm deep is a necessity to properly execute SurPhos. This top 20 mm of soil is where most of the phosphorus that is applied stays in the soil profile, and keeping it in the top 20 mm of soil makes it more available to be eroded off the field by runoff.

This method assumes that the top layer of soil defined by the user is greater than 20 mm thick.

get_vectorized_layer_attribute(attribute: str) → List[any]

Returns a list containing the specified attribute for each soil layer.

Parameters

attributestr

The LayerData attribute or property to be vectorized.

Returns

layered_attributelist[any]

Values of the specified attribute for each layer.

set_vectorized_layer_attribute(attribute: str, values: List[any]) → None

Sets a given attribute for all layers in soil_data.

Parameters

attributestr

The LayerData attribute to set.

valueslist[any]

Values of the attribute to set for each layer.

do_annual_reset() → None

This method resets all annual totals to zero at the end of the year/beginning of a new year

property profile_soil_water_content: float

Calculate the amount of water in the entire soil profile (excluding the amount of water held in the profile at the wilting point) (mm).

Returns

float

The total soil water content in millimeters (mm).

Notes

This method calculates the total soil water content in the entire soil profile. It assumes that the lower bound of water is 0. The calculation is done per layer, meaning that if one layer has water content greater than its wilting water point and another layer has water content less than its wilting point, the first layer will not have to compensate for the deficit in the second layer.

property profile_saturation: float

Calculate the amount of water in the soil profile when completely saturated (mm).

Returns

float

The saturated soil water content in millimeters (mm).

property profile_field_capacity: float

Calculate the total amount of water contained in the entire soil profile at field capacity (but not saturated) (mm).

Returns

float

The soil water content at field capacity in millimeters (mm).

property soil_water_factor: float

Get the soil water factor (unitless).

Returns

float

The soil water factor, in the range [0.0, 1.0] (unitless).

References

SWAT Theoretical documentation eqn. 5:2.3.18

property profile_bulk_density: float

Calculate the average bulk density of the soil profile based on the bulk density of each soil layer, weighted by the thickness.

Returns

float

The average bulk density of the soil profile (Mg per cubic meter).

property profile_nitrates_total: float

Calculate and return the total amount of nitrates in the soil.

Returns

float

The total amount of nitrates in the soil (kg per hectare).

property profile_ammonium_total: float

Calculate and return the total amount of nitrates in the soil.

Returns

float

The total amount of ammonium in the soil (kg / ha).

property profile_active_organic_nitrogen_total: float

Calculate and return the total amount of active organic nitrogen in the soil.

Returns

float

The total amount of active organic nitrogen in the soil (kg / ha).

property profile_stable_organic_nitrogen_total: float

Calculate and return the total amount of stable organic nitrogen in the soil.

Returns

float

The total amount of stable organic nitrogen in the soil (kg / ha).

property profile_fresh_organic_nitrogen_total: float

Calculate and return the total amount of fresh organic nitrogen in the soil.

Returns

float

The total amount of fresh organic nitrogen in the soil (kg / ha).

property cover_factor: float

Returns the cover factor based on the cover type for determining phosphorus absorption by soil from surface-applied fertilizer before the first rainfall event after application.

Returns

float

The cover factor (unitless).

Raises

ValueError

If the cover type is not one of the acceptable types (“BARE”, “RESIDUE_COVER”, or “GRASSED”).

References

pseudocode_soil [S.5.C.I.1], SurPhos [14] (Note: constants may differ between documents; defer to pseudocode_soil and old code).

property solubilizing_factor: float

Returns the fraction of fertilizer phosphorus removed from the available or recalcitrant pool based on the number of rain events.

Parameters

rain_eventsint

The number of rain events.

Returns

float

The fraction of fertilizer phosphorus removed (unitless).

References

SurPhos paragraph just below [16].

property profile_carbon_total: float

property profile_carbon_emissions: float

Calculates the total amount of CO2 respirated from the soil profile.

Returns

float

Total amount of CO2 emitted from carbon decomposition in the soil profile (kg/ha).

property average_clay_percent: float

Calculates the average percent of soil.

Returns

float

Average clay percent of the soil (unitless).

__init__(*, name: str | None = 'generic soil configuration', soil_layers: ~typing.List[~RUFAS.routines.field.soil.layer_data.LayerData] | None = None, field_size: dataclasses.InitVar[float] = None, initial_water_content: float = None, initial_nitrates_total: float = None, annual_soil_evaporation_total: float = 0, annual_runoff_total: float = 0, annual_eroded_sediment_total: float = 0, annual_surface_runoff_total: float = 0, annual_runoff_fertilizer_phosphorus: float = 0, annual_soil_phosphorus_runoff: float = 0, annual_runoff_nitrates_total: float = 0, annual_runoff_ammonium_total: float = 0, annual_eroded_fresh_organic_nitrogen_total: float = 0, annual_eroded_stable_organic_nitrogen_total: float = 0, annual_eroded_active_organic_nitrogen_total: float = 0, water_evaporated: float = 0.0, second_moisture_condition_parameter: float = 85, previous_retention_parameter: float | None = None, average_subbasin_slope: float = 0.05, moisture_condition_parameter: float | None = None, accumulated_runoff: float = 0.0, infiltrated_water: float = 0.0, vadose_zone_layer: ~RUFAS.routines.field.soil.layer_data.LayerData | None = None, time_step: float = 24, albedo: float = 0.16, previous_temperature_effect: float = 0.8, snow_content: float = 0.0, snow_melt_amount: float = 0.0, previous_day_snow_temperature: float | None = None, current_day_snow_temperature: float | None = None, snow_lag_factor: float = 1.0, snow_coverage_fraction: float = 1.0, snow_melt_base_temperature: float = 0.5, snow_coverage_maximum: float = 1.0, snow_melt_factor_maximum: float = 4.5, snow_melt_factor_minimum: float = 4.5, water_sublimated: float = 0.0, slope_length: float = 3, manning: float = 0.4, eroded_sediment: float = 0, surface_runoff_volume: float | None = None, cover_type: str = 'BARE', full_available_phosphorus_pool: float = 0, available_phosphorus_pool: float = 0, recalcitrant_phosphorus_pool: float = 0, runoff_fertilizer_phosphorus: float = 0.0, days_since_application: int = 0, rain_events_after_fertilizer_application: int = 0, machine_manure: ~RUFAS.routines.field.soil.manure_pool.ManurePool = <factory>, grazing_manure: ~RUFAS.routines.field.soil.manure_pool.ManurePool = <factory>, soil_phosphorus_runoff: float = 0.0, nitrate_runoff: float = 0.0, ammonium_runoff: float = 0.0, eroded_fresh_organic_nitrogen: float = 0.0, eroded_stable_organic_nitrogen: float = 0.0, eroded_active_organic_nitrogen: float = 0.0, humus_mineralization_rate_factor: float = 0.0003, denitrification_rate_coefficient: float = 1.4, denitrification_threshold_water_content: float = 1.1, residue_fresh_organic_mineralization_rate: float = 0.05, plant_residue_lignin_composition: float = 0.17, plant_lignin_nitrogen_ratio: float = 0, plant_residue_metabolic_fraction: float = 0, crop_yield_nitrogen: float = 0) → None