HydPy-GA-GARTO-Sub1 (submodel for calculating the Green-Ampt / Talbot-Ogden infiltration with redistribution)

ga_garto_submodel1 satisfies the SoilModel_V1 interface and works like the stand-alone model ga_garto, although slight deviations are possible depending on how the main model calls the different interface methods. ga_garto_submodel1 is the first submodel implemented into the HydPy framework. Hence, we discussed its development extensively in issue 91. For concrete application examples and further information, see the documentation of method Calc_BoWa_SoilModel_V1 and the integration tests acre (GARTO) of application model lland_dd and acre (GARTO) of application model lland_knauf.

class hydpy.models.ga_garto_submodel1.Model

Bases: Base_SoilModel_V1

HydPy-GA-GARTO-Sub1 (submodel for calculating the Green-Ampt / Talbot-Ogden infiltration with redistribution).

The following interface methods are available to main models using the defined model as a submodel:

• Set_InitialSurfaceWater_V1 Set the given initial surface water depth for the selected soil compartment.

• Set_ActualSurfaceWater_V1 Set the given actual surface water depth for the selected soil compartment.

• Set_SoilWaterSupply_V1 Set the (potential) water supply to the soil’s body.

• Set_SoilWaterDemand_V1 Set the (potential) water withdrawal from the soil’s surface and body.

• Execute_Infiltration_V1 Calculate infiltration (and percolation).

• Add_SoilWater_V1 Add the (direct) soil water supply to the soil’s body.

• Remove_SoilWater_V1 Remove the water demand from the soil’s body and eventually from the soil’s surface.

• Get_Percolation_V1 Get the current percolation from the selected soil compartment.

• Get_Infiltration_V1 Get the current infiltration to the selected soil compartment.

• Get_SoilWaterAddition_V1 Get the current soil water addition to the selected soil compartment.

• Get_SoilWaterRemoval_V1 Get the current soil (and surface water) withdrawal from the selected soil compartment.

• Get_SoilWaterContent_V1 Get the current soil water content of the selected soil compartment.

The following “additional methods” might be called by one or more of the other methods or are meant to be directly called by the user:

• Return_RelativeMoisture_V1 Calculate and return the relative soil water content for the given bin-soil combination.

• Return_Conductivity_V1 Based on the Brooks-Corey soil moisture characteristic model (Brooks and Corey, 1966), calculate and return the conductivity for the given bin-soil combination.

• Return_CapillaryDrive_V1 Based on the Brooks-Corey soil moisture characteristic model (Brooks and Corey, 1966), calculate and return the capillary drive between the water contents of the given bins for the defined soil.

• Return_DryDepth_V1 Calculate and return the “dry depth”.

• Return_LastActiveBin_V1 Find the index of the last active bin (that either contains a wetting front or uniform moisture over the complete soil depth).

• Active_Bin_V1 Activate a bin to the right of the bin with the given index.

• Percolate_FilledBin_V1 Calculate the percolation of water through the filled first bin due to gravitational forcing.

• Shift_Front_V1 Increase the selected bin’s wetting front depth without modifying its relative moisture following a variation of the Talbot-Ogden equation (Talbot and Ogden, 2008).

• Redistribute_Front_V1 Modify the selected bin’s wetting front depth and relative moisture content based on a Green & Ampt redistribution equation.

• Infiltrate_WettingFrontBins_V1 Process infiltration into the wetting front bins.

• Merge_FrontDepthOvershootings_V1 Merge those neighbour bins where the wetting front’s depth of the right neighbour exceeds the wetting front’s depth of the left neighbour.

• Merge_SoilDepthOvershootings_V1 Merge bins with wetting front depth larger than soil depth with their left neighbour bins and add their water excess to percolation.

• Water_AllBins_V1 Water the soil’s body by (potentially) adding water to all active bins.

• Withdraw_AllBins_V1 Take withdrawal from the available surface water and (potentially) from all active bins.

DOCNAME: DocName = ('GA-GARTO-Sub1', 'submodel for calculating the Green-Ampt / Talbot-Ogden infiltration with redistribution')

REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()

cymodel: CyModelProtocol | None

parameters: parametertools.Parameters

sequences: sequencetools.Sequences

masks: masktools.Masks

preparemethod2arguments: dict[str, tuple[tuple[Any, ...], dict[str, Any]]]

class hydpy.models.ga_garto_submodel1.AideSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: AideSequences

Aide sequences of model ga_garto_submodel1.

The following classes are selected:

• InitialSurfaceWater() The initial surface water depth at the beginning of a numerical substep [mm].

• ActualSurfaceWater() The actual surface water depth [mm].

class hydpy.models.ga_garto_submodel1.ControlParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Control parameters of model ga_garto_submodel1.

The following classes are selected:

• NmbSoils() The number of separately modelled soil compartments in the subbasin [-].

• NmbBins() The number of available bins for each soil compartment [-].

• DT() The length of the numerical substeps [T].

• Sealed() Flag indicating if a (soil) compartment is sealed for infiltration [-].

• SoilDepth() Depth of the considered soil domains [mm].

• ResidualMoisture() Relative residual water content [-].

• SaturationMoisture() Relative saturation water content [-].

• SaturatedConductivity() Saturated hydraulic conductivity [mm/T].

• PoreSizeDistribution() Pore-size distribution parameter [-].

• AirEntryPotential() Air entry potential [mm].

class hydpy.models.ga_garto_submodel1.DerivedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Derived parameters of model ga_garto_submodel1.

The following classes are selected:

• NmbSubsteps() The number of numerical substeps in each simulation step [-].

• EffectiveCapillarySuction() The effective capillary suction according to the Brooks-Corey soil moisture characteristic model (Brooks and Corey, 1966) [mm].

class hydpy.models.ga_garto_submodel1.FluxSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FluxSequences

Flux sequences of model ga_garto_submodel1.

The following classes are selected:

• SoilWaterSupply() Water supply to the soil’s body (e.g., capillary rise) [mm/T].

• Demand() (Potential) water withdrawal from the soil’s surface and body [mm/T].

• Infiltration() Infiltration through the soil’s surface [mm/T].

• Percolation() Percolation through the soil’s bottom [mm/T].

• SoilWaterAddition() Actual addition of soil water due to processes like capillary rise [mm/T].

• Withdrawal() Withdrawal from the soil’s surface or body (e.g. due to evaporation) [mm/T].

• SurfaceRunoff() Surface runoff [mm/T].

class hydpy.models.ga_garto_submodel1.LogSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: LogSequences

Log sequences of model ga_garto_submodel1.

The following classes are selected:

• MoistureChange() The (last) change in soil moisture of each bin [-].

class hydpy.models.ga_garto_submodel1.StateSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: StateSequences

State sequences of model ga_garto_submodel1.

The following classes are selected:

• Moisture() The relative soil moisture of each bin (within the wetting front) [-].

• FrontDepth() The depth of the wetting front in each bin [-].