RUFAS.routines.field.soil.percolation module#

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

Bases: object

This class is based on the ‘Percolation’ section (2:3.2) in SWAT, designed to manage and simulate soil percolation processes. It either accepts an existing SoilData object to work with or creates a new one based on the provided field size.

Parameters#

soil_dataOptional[SoilData]: The SoilData object used by this module to track percolation. A new SoilData object is created if one is not provided.
field_sizeOptional[float], default=None: The size of the field (ha).

Attributes#

dataSoilData: The SoilData instance being used by the Percolation model.

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

percolate(has_seasonal_high_water_table: bool) → None#

Execute percolation of excess water in each layer of soil profile to the layer directly beneath it.

Parameters#

has_seasonal_high_water_tablebool: A flag indicating whether the HRU has a seasonal high water table (True/False).

Notes#

RuFaS allows percolation even when the temperature of the soil layer is below zero degrees Celsius.

This routine calls the subroutine _percolate_infiltrated_water to handle percolating water from infiltration into the soil profile. If that routine percolates water out of any soil layers (which is the case when there are high or sustained amounts of infiltration), this routine will only percolate water out of the soil layers which have not had water percolated out of them on the current day.

References#

SWAT sections 2:3.1 and 2

percolate_infiltrated_water() → None#: Percolates infiltrated water into the soil profile.

Notes#

The amount of water allowed to infiltrate the soil on any given day is based on the available capacity of the entire soil profile. So when there is an extreme amount of infiltration or there are multiple days of high infiltration in a row, this method fills soil layers to their saturation point going top-down, and records water that is put below a layer as being percolated by it.

static _determine_percolation_travel_time(saturation: float, field_capacity_content: float, saturated_hydraulic_conductivity: float) → float#

Calculate the travel time for percolation.

Parameters#

saturationfloat: Amount of water in the soil layer when completely saturated (mm).
field_capacity_contentfloat: Water content of the soil layer at field capacity (mm).
saturated_hydraulic_conductivityfloat: Saturated hydraulic conductivity of the layer (mm per hour).

Returns#

float: Travel time for percolation (hours).

References#

SWAT 2:3.2.4

static _determine_percolation_to_next_layer(drainable_volume_water: float, time_step: float, travel_time: float) → float#

Calculate the amount of water that percolates to the soil layer below it on a given day.

Parameters#

drainable_volume_waterfloat: Drainable volume of water in the soil layer on a given day (mm).
time_stepfloat: Length of the time step over which percolation occurs (hours).
travel_timefloat: Travel time for percolation (hours).

Returns#

float: Amount of water percolating to the underlying soil layer on a given day (mm).

References#

SWAT 2:3.2.3

static _determine_if_percolation_allowed(soil_water_content: float, field_capacity_content: float, saturated_capacity_content: float, is_seasonal_high_water_table: bool) → bool#

Determine if a layer of soil has enough available capacity to accept more water via percolation.

Parameters#

soil_water_contentfloat: Water content of the given soil layer (mm).
field_capacity_contentfloat: Water content of the given soil layer at field capacity (mm).
saturated_capacity_contentfloat: Water content of the given soil layer when completely saturated (mm).
is_seasonal_high_water_tablebool: Boolean indicating if HRU has a seasonal high water table (True/False).

Returns#

bool: True if the soil layer can accept more water from percolation, False if not.

References#

SWAT Paragraph in between equations 2:3.2.3, 4

static _percolate_between_layers(time_step: float, upper_layer: LayerData, lower_layer: LayerData) → float#

Determine the actual amount of water that will percolate from the given upper layer to the given lower layer over the provided time step.

Parameters#

upper_layerLayerData: Given layer of soil to percolate from (LayerData object).
lower_layerLayerData: Given layer of soil to percolate to (LayerData object).
time_stepfloat: Length of time over which percolation occurs (hours).

Returns#

float: Amount of water that will actually be percolated from the upper layer to the lower layer (mm).

References#

SWAT Section 2:3.2