docs updated, references added and updated

docs/source/refs.bib

@@ -1,15 +1,85 @@
 
+@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},
 	pages = {63},
 }
 
 @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},

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]

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]

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."""

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