From d7d389a7fe4950e18804d9214701010eca4be164 Mon Sep 17 00:00:00 2001 From: vgro Date: Mon, 2 Oct 2023 14:23:41 +0100 Subject: [PATCH] docs updated, references added and updated --- docs/source/refs.bib | 87 ++++++++++++++++--- .../models/hydrology/above_ground.py | 23 +++-- .../models/hydrology/below_ground.py | 12 +-- .../models/hydrology/constants.py | 21 ++--- .../models/hydrology/hydrology_model.py | 6 +- 5 files changed, 108 insertions(+), 41 deletions(-) diff --git a/docs/source/refs.bib b/docs/source/refs.bib index 98e9a0c46..20176c1a7 100644 --- a/docs/source/refs.bib +++ b/docs/source/refs.bib @@ -1,7 +1,77 @@ +@article{mahfouf_comparative_1991, + title = {Comparative {Study} of {Various} {Formulations} of {Evaporations} from {Bare} {Soil} {Using} {In} {Situ} {Data}}, + volume = {30}, + doi = {https://doi.org/10.1175/1520-0450(1991)030<1354:CSOVFO>2.0.CO;2}, + journal = {Journal of Applied Meteorology and Climatology}, + author = {Mahfouf, J. F. and Noilhan, J.}, + year = {1991}, + pages = {1354--1365}, +} + +@article{barton_parameterization_1979, + series = {(1962-1982)}, + title = {A {Parameterization} of the {Evaporation} from {Nonsaturated} {Surfaces}}, + volume = {18}, + url = {https://www.jstor.org/stable/26178635}, + number = {1}, + journal = {Journal of Applied Meteorology}, + author = {Barton, I. J.}, + year = {1979}, + pages = {43--47}, +} + +@article{mualem_new_1976, + title = {A new model for predicting the hydraulic conductivity of unsaturated porous media}, + volume = {12}, + doi = {10.1029/WR012i003p00513}, + number = {3}, + journal = {Water Resources Research}, + author = {Mualem, Yechezkel}, + year = {1976}, + pages = {513--522}, +} + +@article{van_genuchten_closed-form_1980, + title = {A {Closed}-form {Equation} for {Predicting} the {Hydraulic} {Conductivity} of {Unsaturated} {Soils}}, + volume = {44}, + doi = {https://doi.org/10.2136/sssaj1980.03615995004400050002x}, + journal = {Science Society of America Journal}, + author = {Van Genuchten, Martinus Th.}, + year = {1980}, + pages = {892--898}, +} + +@article{van_der_knijff_lisflood_2010, + title = {{LISFLOOD}: a {GIS}‐based distributed model for river basin scale water balance and flood simulation}, + volume = {24}, + doi = {10.1080/13658810802549154}, + number = {2}, + journal = {International Journal of Geographical Information Science}, + author = {Van Der Knijff, J. M. and Younis, J. and De Roo, A. P. J.}, + year = {2010}, + pages = {189--212}, +} + +@article{wang_development_2013, + title = {Development of microbial-enzyme-mediated decomposition model parameters through steady-state and dynamic analyses}, + volume = {23}, + issn = {1051-0761}, + url = {http://doi.wiley.com/10.1890/12-0681.1}, + doi = {10.1890/12-0681.1}, + language = {en}, + number = {1}, + urldate = {2023-09-22}, + journal = {Ecological Applications}, + author = {Wang, Gangsheng and Post, Wilfred M. and Mayes, Melanie A.}, + month = jan, + year = {2013}, + pages = {255--272}, +} + @techreport{von_hoyningen-huene_interzeption_1981, address = {Braunschweig}, - title = {Die {Interzeption} des {Niederschlags} in landwirtschaftlichen {Pflanzenbeständen} ({Rainfall} interception in agricultural plant stands).}, + title = {Die {Interzeption} des {Niederschlags} in landwirtschaftlichen {Pflanzenbeständen} ({Rainfall} interception in agricultural plant stands)}, institution = {DVWK}, author = {Von Hoyningen-Huene, J.}, year = {1981}, @@ -9,7 +79,7 @@ @techreport{von_hoyningen-huene_interzeption_1981 } @article{merriam_note_1960, - title = {A note on the interception loss equation.}, + title = {A note on the interception loss equation}, volume = {65}, doi = {https://doi.org/10.1029/JZ065i011p03850}, journal = {Journal of Geophysical Research}, @@ -19,7 +89,7 @@ @article{merriam_note_1960 } @article{aston_rainfall_1979, - title = {Rainfall interception by eight small trees.}, + title = {Rainfall interception by eight small trees}, volume = {42}, doi = {https://doi.org/10.1016/0022-1694(79)90057-X}, journal = {Journal of Hydrology}, @@ -106,17 +176,6 @@ @article{mills_tropical_2023 pages = {e2214462120}, } -@article{van_genuchten_describing_1985, - title = {On {Describing} and {Predicting} the {Hydraulic} {Properties} of {Unsaturated} {Soils}}, - volume = {3}, - doi = {https://doi.org/10.1016/0148-9062%2886%2991047-8}, - number = {5}, - journal = {Annales Geophysicae}, - author = {Van Genuchten, Martinus Th. and Nielsen, D.R.}, - year = {1985}, - pages = {615--628}, -} - @article{jucker_canopy_2018, title = {Canopy structure and topography jointly constrain the microclimate of human-modified tropical landscapes.}, volume = {24}, diff --git a/virtual_rainforest/models/hydrology/above_ground.py b/virtual_rainforest/models/hydrology/above_ground.py index afee4c7b6..126a5c3c0 100644 --- a/virtual_rainforest/models/hydrology/above_ground.py +++ b/virtual_rainforest/models/hydrology/above_ground.py @@ -1,5 +1,5 @@ """The ``models.hydrology.above_ground`` module simulates the above-ground hydrological -processes for the Virtual Rainforest. At the moment, this includes rainwater +processes for the Virtual Rainforest. At the moment, this includes rain water interception by the canopy, soil evaporation, and all functions related to surface runoff. """ # noqa: D205, D415 @@ -30,8 +30,9 @@ def calculate_soil_evaporation( ) -> NDArray[np.float32]: r"""Calculate soil evaporation based classical bulk aerodynamic formulation. - This function uses the so-called 'alpha' method to estimate the evaporative flux. - We here use the implementation by Barton (1979): + This function uses the so-called 'alpha' method to estimate the evaporative flux + :cite:p:`mahfouf_comparative_1991`. + We here use the implementation by :cite:t:`barton_parameterization_1979`: :math:`\alpha = \frac{1.8 * \Theta}{\Theta + 0.3}` @@ -41,7 +42,7 @@ def calculate_soil_evaporation( content), :math:`E_{g}` is the evaporation flux (W m-2), :math:`\rho_{air}` is the density of air (kg m-3), :math:`R_{a}` is the aerodynamic resistance (unitless), :math:`q_{sat}(T_{s})` (unitless) is the saturated specific humidity, and - :math:`q_{g}` is the surface specific humidity (unitless); see Mahfouf (1991). + :math:`q_{g}` is the surface specific humidity (unitless). TODO add references TODO move constants to HydroConsts or CoreConstants and check values @@ -215,7 +216,8 @@ def estimate_interception( r"""Estimate canopy interception. This function estimates canopy interception using the following storage-based - equation after :cite:t:`aston_rainfall_1979` and :cite:t:`merriam_note_1960`: + equation after :cite:t:`aston_rainfall_1979` and :cite:t:`merriam_note_1960` as + implemented in :cite:t:`van_der_knijff_lisflood_2010` : :math:`Int = S_{max} * [1 - e \frac{(-k*R*\delta t}{S_{max}})]` @@ -287,15 +289,18 @@ def calculate_bypass_flow( available for infiltration is added to the groundwater directly (i.e. without first entering the soil matrix). It is assumed that this fraction is a power function of the relative saturation of the superficial and upper soil layers. This results in - the following equation (after LISFLOOD model): + the following equation (after :cite:t:`van_der_knijff_lisflood_2010`): :math:`D_{pref, gw} = W_{av} * (\frac{w_{1}}{w_{s1}})^{c_{pref}}` where :math:`D_{pref, gw}` is the amount of preferential flow per time step [mm], :math:`W_{av}` is the amount of water that is available for infiltration, and - :math:`c_{pref}` is an empirical shape parameter. The equation results in a - preferential flow component that becomes increasingly important as the soil gets - wetter. + :math:`c_{pref}` is an empirical shape parameter. This parameter affects how much of + the water available for infiltration goes directly to groundwater via preferential + bypass flow; a value of 0 means all surface water goes directly to groundwater, a + value of 1 gives a linear relation between soil moisture and bypass flow. + The equation returns a preferential flow component that becomes increasingly + important as the soil gets wetter. Args: top_soil_moisture: soil moisture of top soil layer, [mm] diff --git a/virtual_rainforest/models/hydrology/below_ground.py b/virtual_rainforest/models/hydrology/below_ground.py index 62def8a82..5f64fdad8 100644 --- a/virtual_rainforest/models/hydrology/below_ground.py +++ b/virtual_rainforest/models/hydrology/below_ground.py @@ -25,7 +25,8 @@ def calculate_vertical_flow( To calculate the flow of water through unsaturated soil, this function uses the Richards equation. First, the function calculates the effective saturation :math:`S` and effective hydraulic conductivity :math:`K(S)` based on the moisture content - :math:`\Theta` using the van Genuchten/Mualem model: + :math:`\Theta` using the Mualem-van Genuchten model + :cite:p:`van_genuchten_closed-form_1980`: :math:`S = \frac{\Theta - \Theta_{r}}{\Theta_{s} - \Theta_{r}}` @@ -118,8 +119,9 @@ def update_soil_moisture( """Update soil moisture profile. This function calculates soil moisture for each layer by removing the vertical flow - of the current layer and adding it to the layer below. Additionally, the - evapotranspiration is removed from the second soil layer. + of the current layer and adding it to the layer below. The implementation is based + on :cite:t:`van_der_knijff_lisflood_2010`. Additionally, the evapotranspiration is + removed from the second soil layer. Args: soil_moisture: soil moisture after infiltration and surface evaporation, [mm] @@ -174,7 +176,7 @@ def soil_moisture_to_matric_potential( nonlinearily_parameter: Union[float, NDArray[np.float32]], alpha: Union[float, NDArray[np.float32]], ) -> NDArray[np.float32]: - r"""Convert soil moisture to matric potential using van Genuchten/Mualem model. + r"""Convert soil moisture to matric potential using the Mualem-van Genuchten model. The soil water content is converted to matric potential as follows: @@ -184,7 +186,7 @@ def soil_moisture_to_matric_potential( :math:`\Theta_{s}` are the residual and saturated moisture content or soil moisture capacity, respectively. `math`:\Phi` is the soil water matric potential and :math:`m`, :math:`n`, and :math:`\alpha` are shape parameters of the water retention - curve. + curve :cite:p:`van_genuchten_closed-form_1980`. Args: soil_moisture: Volumetric relative water content in top soil, [unitless] diff --git a/virtual_rainforest/models/hydrology/constants.py b/virtual_rainforest/models/hydrology/constants.py index e904a7085..a4021df7d 100644 --- a/virtual_rainforest/models/hydrology/constants.py +++ b/virtual_rainforest/models/hydrology/constants.py @@ -49,8 +49,8 @@ class HydroConsts: """Factor to convert variable unit from seconds to day.""" nonlinearily_parameter: float = 2.0 - """Nonlinearity parameter n (dimensionless) in van Genuchten model for hydraulic - conductivity :cite:p:`van_genuchten_describing_1985`.""" + """Nonlinearity parameter n (dimensionless) in Mualem-van Genuchten model for + hydraulic conductivity :cite:p:`van_genuchten_closed-form_1980`.""" meters_to_mm: float = 1000 """Factor to convert variable unit from meters to millimeters.""" @@ -76,30 +76,31 @@ class HydroConsts: intercept_param_1: float = 0.935 """Parameter in equation that estimates maximum canopy interception capacity after - Von Hoyningen-Huene, (1981).""" + :cite:t:`von_hoyningen-huene_interzeption_1981`.""" intercept_param_2: float = 0.498 """Parameter in equation that estimates maximum canopy interception capacity after - Von Hoyningen-Huene, (1981).""" + :cite:t:`von_hoyningen-huene_interzeption_1981`.""" intercept_param_3: float = 0.00575 """Parameter in equation that estimates maximum canopy interception capacity after - Von Hoyningen-Huene, (1981).""" + :cite:t:`von_hoyningen-huene_interzeption_1981`.""" veg_density_param: float = 0.046 """Parameter used to estimate vegetation density for maximum canopy interception - capacity estimate after Von Hoyningen-Huene, (1981).""" + capacity estimate after :cite:t:`von_hoyningen-huene_interzeption_1981`.""" groundwater_capacity: float = 0.9 """Ground water storage capacity in relative volumetric water content. This might be replaced with the implementation of below ground horizontal flow.""" alpha: float = 0.3 - """Dimensionless parameter alpha in van Genuchten model that corresponds - approximately to the inverse of the air-entry value, [kPa-1]""" + r"""Dimensionless parameter :math:`alpha` in van Genuchten model that corresponds + approximately to the inverse of the air-entry value, [kPa-1] + :cite:p:`van_genuchten_closed-form_1980`""" infiltration_shape_parameter: float = 1.0 """Empirical shape parameter that affects how much of the water available for infiltration goes directly to groundwater via preferential bypass flow. A value of - 0 mean all surface water goes directly to groundwater, a value of 1 gives a linear - relation.""" + 0 means all surface water goes directly to groundwater, a value of 1 gives a linear + relation between soil moisture and bypass flow.""" diff --git a/virtual_rainforest/models/hydrology/hydrology_model.py b/virtual_rainforest/models/hydrology/hydrology_model.py index 3583a1905..92003f0e4 100644 --- a/virtual_rainforest/models/hydrology/hydrology_model.py +++ b/virtual_rainforest/models/hydrology/hydrology_model.py @@ -186,9 +186,9 @@ def setup(self) -> None: At the moment, this function initializes variables that are required to run the first update(). For the within grid cell hydrology, soil moisture is initialised homogenously for all soil layers. This design might change with the - implementation of the SPLASH model in the plant module which will take care of - the above-ground hydrology. Air temperature and relative humidity below the - canopy are set to the 2 m reference values. + implementation of the SPLASH model :cite:p:`davis_simple_2017` in the plant + model which will take care of the above-ground hydrology. Air temperature and + relative humidity below the canopy are set to the 2 m reference values. For the hydrology across the grid (above-/below-ground and accumulated runoff), this function uses the upstream neighbours of each grid cell (see