==============================================================Incorporating Green-Ampt infiltration into the PyTOPKAPI model==============================================================The purpose of this document is the describe the changes applied tothe PyTOPKAPI model formulation by including infiltration into themodel processes.Infiltration calculations-------------------------*A few words on why Green-Ampt was chosen* - Parameters can beestimated from available information; some authors show it's goodperformance relative to observed data and full 1D solution of Richardsequation (Ma et al., 2010).; Easy to code/implement and quick to run?;Can be extended to multiple layers (Han et al., 2001)Description of Green-Ampt applied to PyTOPKAPI~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~The infiltration depth during each interval is calculated using theGreen-Ampt method (Green and Ampt, 1911). The Green-Ampt cumulativeinfiltration during an infiltration event is determined by solving.. math:: F_{t+\Delta t} - F_t - \psi\Delta\theta ln(\frac{F_{t+\Delta t} + \psi\Delta\theta}{F_t + \psi\Delta\theta}) = K\Delta twhere :math:`F_{t+\Delta t}` is the cumulative infiltration depth atthe end of the time-step :math:`t`, :math:`F_t` is the cumulativeinfiltration depth at the start of time-step :math:`t`, :math:`\psi`is the soil suction head at the wetting front and :math:`K` is thesaturated hydraulic conductivity of the soil. :math:`\Delta\theta` isequal to the difference between the effective porosity :math:`\eta_e`and the effective saturation at the start of the infiltration event:math:`s_e` . If the porosity is :math:`\eta`, the soil moisturecontent at the start of the event is :math:`\theta` and the residualsoil moisture content is :math:`\theta_r`, then.. math:: \eta_e = \eta - \theta_rand.. math:: s_e = \frac{\theta - \theta_r}{\eta_e}so.. math:: \Delta\theta = \eta_e - s_eSince PyTOPKAPI works from time-step to time-step by tracking thewater volumes in the soil, overland and channel stores, the modelkeeps track of :math:`s_e`, which is updated at each time-step and:math:`F_t` can be reset to zero each time. The Green-Ampt cumulativeinfiltration equation therefore reduces to.. math:: F_{t+\Delta t} - \psi\Delta\theta ln(\frac{F_{t+\Delta t} + \psi\Delta\theta}{\psi\Delta\theta}) - K\Delta t = 0This equation is non-linear in :math:`F_{t+\Delta t}` and the rootsmust be obtained by an iterative technique. The solver used inPyTOPKAPI is a modified version of the Powell hybrid method (Powell,1970), accessed via the Scipy (Jones et al., 2001) wrappers of theMINPACK FORTRAN library (Mor et al., 1980)The parameters of the Green-Ampt model are :math:`K`,:math:`\Delta\theta` and :math:`\psi`. :math:`K` and:math:`\Delta\theta` are already easily obtainable from the PyTOPKAPImodel. Therefore :math:`\psi` must be estimated. Since :math:`\psi`varies as a function of :math:`\theta` and soil type (Chow et al.,1988), it is necessary to obtain a functional form for:math:`\psi(\theta)` by soil type. El-Kadi (1985) evaluated a numberof well-known models for :math:`\psi(\theta)` by fitting them tomeasured data for a selection of soil samples and comparing the modelfits. In general El-Kadi (1985) found that there was relatively littledifference in the model performances, but suggested that the Brooksand Corey relationship (Brooks and Corey, 1964) was most insensitiveto the number of :math:`\psi` samples near saturation. This suggeststhat the model is most robust out of those tested by El-Kadi (1985)and is one of the reasons for selecting the Brooks Corey model for usein PyTOPKAPI. The Brooks and Corey model is given by.. math:: \theta_e = [\frac{\psi_b}{\psi}]^\lambdaor.. math:: \psi = \frac{\psi_b}{\theta_e^{-\lambda}}where :math:`\psi_b` is the bubbling pressure and :math:`\lambda` is apore size distribution index for the soil.A second reason to choose the Brooks and Corey model is theavailability of model parameter estimates (:math:`\psi_b` and:math:`\lambda`) for a large number of soil samples in the UnitedStates produced by Rawls et al. (1982). The Brooks and Corey modelparameters given by Rawls et al. (1982) are provided 11 different soiltexture classes, which are readily available for South Africa fromMiddleton and Bailey (2009), and are already used to estimate otherparameters in the PyTOPKAPI model.Revised water transfer mechanism in the model---------------------------------------------Currently the total rainfall volume for each time-step enters the soilstore directly at a constant rate over the interval. The final volumein the soil store is calculated by solving the differential equationfor a generic cell.. math:: \frac{dV}{dt} = a - bV^\alphawhere :math:`V` is the water volume in the store, :math:`a` is theconstant input rate during the time-step, and :math:`b` and:math:`\alpha` are parameters describing the drainage properties ofthe store.In the current model formulation, all water entering the channel store(if it exists) comes from upstream channel stores or fromcontributions by the soil and overland stores of the cell. Water canonly exit a channel store via direct evaporation or flow to adown-slope channel store. All other input (precipitation and flow fromupstream cells) goes directly to the soil store. The consequence ofthis is that water can only enter the overland store via the mechanismof saturation excess when the soil store becomes saturated during atime-step. For a given cell, the total inflow rate to the overlandstore :math:`Q_{in}^O` is given by.. math:: Q_{in}^O = Q_{in}^S - ( \frac{\Delta V^S}{\Delta t} + Q_{out}^S )where :math:`Q_{in}^S` is the combined inflow rate to the soil storefor the current time-step as a result of rainfall, overland flow fromup-slope cells and soil drainage from up-slope cells. :math:`\DeltaV^S` is change is storage in the soil store during the interval and:math:`Q_{out}^S` is the outflow to the down-slope cell from theoverland and soil stores. In the revised model formulation:math:`Q_{in}^O` becomes.. math:: Q_{in}^O = Q_{in}^S - ( \frac{\Delta V^S}{\Delta t} + Q_{out}^S ) + P_{excess}where :math:`P_{excess}` is calculated as.. math:: P_{excess} = P - FReferences----------**Brooks R.H. and Corey A.T., 1964**, "Hydraulic properties of porousmedia", Hydrology Paper No. 3, Colorado State University, FortCollins, Colorado.**El-Kadi A.I., 1985**, "On estimating the Hydraulic properties ofsoils, Part 1. Comparison between forms to estimate the soil-watercharacteristic function, Adv. Water Res., vol 8, pp 136-147.**Green W.H. and Ampt G.A.**, 1911, "Studies on soil physics, part 1,the flow of air and water through soils", J. Agric. Sci., vol 4(1),pp. 1-24**Jones E., Oliphant T., Peterson P., and others.**, 2001, "SciPy:Open Source Scientific Tools for Python ", http://www.scipy.org/**Middleton B.J. and Bailey A.K., 2009**, "Water Resources of SouthAfrica, 2005 Study", WRC Report No. TT 380/08, Water ResearchCommission, Pretoria, South Africa.**Mor J.J., Garbow B.S., and Hillstrom K.E.**, 1980, "User Guide forMINPACK-1", Argonne National Laboratory Report ANL-80-74, Argonne,Ill.**Powell M.J.D.**, 1970, "A Hybrid Method for Nonlinear Equations" in"Numerical Methods for Nonlinear Algebraic Equations", Rabinowitz P.,editor. Gordon and Breach.**Rawls W.J., Brakensiek D.L. and Saxton K.E., 1982**, "Estimation ofsoil water properties", Trans. of the ASAE, vol 25(5), pp 1316-1320and 1328