Merge pull request #521 from ImperialCollegeLondon/519-review-abiotic…

…-simple-and-hydrology-docstrings-to-match-updated-documentation

519 review abiotic simple and hydrology docstrings to match updated documentation

docs/source/_toc.yaml

@@ -171,6 +171,8 @@ subtrees:
                 title: The constants submodule
               - file: api/models/hydrology/hydrology_model
                 title: The hydrology_model submodule
+              - file: api/models/hydrology/hydrology_tools
+                title: The hydrology_tools submodule
           - file: api/models/litter
             title: The litter model
             entries:

docs/source/api/models/hydrology/hydrology_tools.md

@@ -0,0 +1,24 @@
+---
+jupytext:
+  cell_metadata_filter: -all
+  formats: md:myst
+  main_language: python
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.13.8
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+#  API for the {mod}`~virtual_ecosystem.models.hydrology.hydrology_tools` module
+
+```{eval-rst}
+.. automodule:: virtual_ecosystem.models.hydrology.hydrology_tools
+    :autosummary:
+    :members:
+    :special-members: __init__
+```

tests/models/hydrology/test_hydrology_model.py

@@ -291,7 +291,10 @@ def test_setup(
             exp_var[soil_indices] = expected_vals
 
             np.testing.assert_allclose(
-                model.data[var_name], exp_var, rtol=1e-4, atol=1e-4
+                model.data[var_name],
+                exp_var,
+                rtol=1e-4,
+                atol=1e-4,
             )
 
         # Test one dimensional variables

virtual_ecosystem/models/abiotic_simple/__init__.py

@@ -2,7 +2,7 @@
 models of the Virtual Ecosystem. It is comprised of several submodules that calculate
 the microclimate for the Virtual Ecosystem.
 
-Each of the abiotic sub-modules has its own API reference page:
+Each of the abiotic simple sub-modules has its own API reference page:
 
 * The :mod:`~virtual_ecosystem.models.abiotic_simple.abiotic_simple_model` submodule
   instantiates the AbioticSimpleModel class which consolidates the functionality of the
@@ -11,11 +11,12 @@
 
 * The :mod:`~virtual_ecosystem.models.abiotic_simple.microclimate` submodule
   contains a set functions and parameters that are used to calculate atmospheric
-  temperature, humidity, :math:`\ce{CO2}`, and atmospheric pressure profiles as well as
-  soil temperature profiles.
+  temperature, relative humidity, vapour pressure deficit, :math:`\ce{CO2}`, and
+  atmospheric pressure profiles as well as soil temperature profiles.
 
 * The :mod:`~virtual_ecosystem.models.abiotic_simple.constants` submodule provides a
-  set of dataclasses containing the constants required by the broader abiotic model.
+  set of dataclasses containing the constants required by the broader abiotic model
+  including the regression parameters for deriving vertical profiles.
 
 """  # noqa: D205
 

virtual_ecosystem/models/abiotic_simple/abiotic_simple_model.py

@@ -1,20 +1,11 @@
 """The :mod:`~virtual_ecosystem.models.abiotic_simple.abiotic_simple_model` module
 creates a
 :class:`~virtual_ecosystem.models.abiotic_simple.abiotic_simple_model.AbioticSimpleModel`
-class as a child of the :class:`~virtual_ecosystem.core.base_model.BaseModel` class. At
-present a lot of the abstract methods of the parent class (e.g.
-:func:`~virtual_ecosystem.core.base_model.BaseModel.spinup`) are overwritten using
-placeholder functions that don't do anything. This will change as the Virtual Ecosystem
-model develops. The factory method
-:func:`~virtual_ecosystem.models.abiotic_simple.abiotic_simple_model.AbioticSimpleModel.from_config`
-exists in a more complete state, and unpacks a small number of parameters from our
-currently pretty minimal configuration dictionary. These parameters are then used to
-generate a class instance. If errors crop here when converting the information from the
-config dictionary to the required types they are caught and then logged, and at the end
-of the unpacking an error is thrown. This error should be caught and handled by
-downstream functions so that all model configuration failures can be reported as one.
-
-TODO update temperatures to Kelvin
+class as a child of the :class:`~virtual_ecosystem.core.base_model.BaseModel` class.
+
+Todo:
+* update temperatures to Kelvin
+* pressure and CO2 profiles should only be filled for filled/true above ground layers
 """  # noqa: D205
 
 from __future__ import annotations
@@ -89,8 +80,6 @@ def __init__(
     ):
         super().__init__(data=data, core_components=core_components, **kwargs)
 
-        self.data
-        """A Data instance providing access to the shared simulation data."""
         self.model_constants = model_constants
         """Set of constants for the abiotic simple model"""
         self.bounds = AbioticSimpleBounds()
@@ -130,9 +119,9 @@ def from_config(
     def setup(self) -> None:
         """Function to set up the abiotic simple model.
 
-        At the moment, this function only initializes soil temperature for all
-        soil layers and calculates the reference vapour pressure deficit for all time
-        steps. Both variables are added directly to the self.data object.
+        This function initializes soil temperature for all soil layers and calculates
+        the reference vapour pressure deficit for all time steps. Both variables are
+        added directly to the self.data object.
         """
 
         # create soil temperature array
@@ -165,8 +154,7 @@ def update(self, time_index: int, **kwargs: Any) -> None:
         """
 
         # This section performs a series of calculations to update the variables in the
-        # abiotic model. This could be moved to here and written directly to the data
-        # object. For now, we leave it as a separate routine.
+        # abiotic model. The updated variables are then added to the data object.
         output_variables = microclimate.run_microclimate(
             data=self.data,
             layer_structure=self.layer_structure,

virtual_ecosystem/models/abiotic_simple/constants.py

@@ -1,7 +1,7 @@
 """The ``models.abiotic_simple.constants`` module contains a set of dataclasses
-containing parameters  required by the broader
-:mod:`~virtual_ecosystem.models.abiotic_simple` model. These parameters are constants
-in that they should not be changed during a particular simulation.
+containing parameters required by the :mod:`~virtual_ecosystem.models.abiotic_simple`
+model. These parameters are constants in that they should not be changed during a
+particular simulation.
 """  # noqa: D205
 
 from dataclasses import dataclass, field
@@ -23,9 +23,9 @@ class AbioticSimpleConsts(ConstantsDataclass):
 class AbioticSimpleBounds(ConstantsDataclass):
     """Upper and lower bounds for abiotic variables.
 
-    When a values falls outside these bounds, it is set to the bound value. Note that
-    this approach does not conserve energy and matter in the system. This will be
-    implemented at a later stage.
+    When a values falls outside these bounds, it is set to the bound value.
+    NOTE that this approach does not conserve energy and matter in the system.
+    This will be implemented at a later stage.
     """
 
     air_temperature: tuple[float, float, float] = (-20.0, 80.0, -1.27)
@@ -43,11 +43,11 @@ class AbioticSimpleBounds(ConstantsDataclass):
     """
 
     vapour_pressure_deficit: tuple[float, float, float] = (0.0, 10.0, -252.24)
-    """Bounds and gradient for vapour pressure deficit, [kPa]."""
+    """Bounds and gradient for vapour pressure deficit, [kPa].
+    
+    Gradient for linear regression to calculate vapour pressure deficit as a function of
+    leaf area index from :cite:t:`hardwick_relationship_2015`.
+    """
 
     soil_temperature: tuple[float, float] = (-10.0, 50.0)
-    """Bounds for soil temperature, [C].
-
-    Gradient for linear regression to calculate vapour pressure deficit as a function
-    of leaf area index from :cite:t:`hardwick_relationship_2015`
-    """
+    """Bounds for soil temperature, [C]."""

virtual_ecosystem/models/abiotic_simple/microclimate.py

@@ -9,7 +9,7 @@
 The module also provides a constant vertical profile of atmospheric pressure and
 :math:`\ce{CO2}`.
 
-TODO change tenperatures to Kelvin
+TODO change temperatures to Kelvin
 """  # noqa: D205
 
 import numpy as np
@@ -50,17 +50,19 @@ def run_microclimate(
     The other atmospheric layers are calculated by logarithmic regression and
     interpolation between the input at the top of the canopy and the 1.5 m values.
     Soil temperature is interpolated between the surface layer and the temperature at
-    1 m depth which equals the mean annual temperature.
-    The function also provides constant atmospheric pressure and :math:`\ce{CO2}` for
-    all atmospheric levels.
+    1 m depth which which approximately equals the mean annual temperature, i.e. can
+    assumed to be constant over the year.
+
+    The function also broadcasts the reference values for atmospheric pressure and
+    :math:`\ce{CO2}` to all atmospheric levels as they are currently assumed to remain
+    constant during one time step.
 
     The `layer_roles` list is composed of the following layers (index 0 above canopy):
 
-    * above canopy (canopy height)
-    * canopy layers (maximum of ten layers, minimum one layers)
-    * subcanopy (1.5 m)
+    * above canopy (canopy height + 2 m)
+    * canopy layers
     * surface layer
-    * soil layers (currently one near surface layer and one layer at 1 m below ground)
+    * soil layers
 
     The function expects a data object with the following variables:
 
@@ -75,9 +77,9 @@ def run_microclimate(
     Args:
         data: Data object
         layer_structure: The LayerStructure instance for the simulation.
-        time_index: time index, integer
+        time_index: Time index, integer
         constants: Set of constants for the abiotic simple model
-        bounds: upper and lower allowed values for vertical profiles, used to constrain
+        bounds: Upper and lower allowed values for vertical profiles, used to constrain
             log interpolation. Note that currently no conservation of water and energy!
 
     Returns:
@@ -86,13 +88,12 @@ def run_microclimate(
         atmospheric :math:`\ce{CO2}` [ppm]
     """
 
-    # TODO make sure variables are representing correct time interval, e.g. mm per day
     output = {}
 
-    # sum leaf area index over all canopy layers
+    # Sum leaf area index over all canopy layers
     leaf_area_index_sum = data["leaf_area_index"].sum(dim="layers")
 
-    # interpolate atmospheric profiles
+    # Interpolate atmospheric profiles
     for var in ["air_temperature", "relative_humidity", "vapour_pressure_deficit"]:
         lower, upper, gradient = getattr(bounds, var)
 
@@ -151,14 +152,14 @@ def log_interpolation(
 
     Args:
         data: Data object
-        reference_data: input variable at reference height
-        leaf_area_index_sum: leaf area index summed over all layers, [m m-1]
+        reference_data: Input variable at reference height
+        leaf_area_index_sum: Leaf area index summed over all layers, [m m-1]
         layer_structure: The LayerStructure instance for the simulation.
-        layer_heights: vertical layer heights, [m]
-        lower_bound: minimum allowed value, used to constrain log interpolation. Note
+        layer_heights: Vertical layer heights, [m]
+        lower_bound: Minimum allowed value, used to constrain log interpolation. Note
             that currently no conservation of water and energy!
-        upper_bound: maximum allowed value, used to constrain log interpolation.
-        gradient: gradient of regression from :cite:t:`hardwick_relationship_2015`
+        upper_bound: Maximum allowed value, used to constrain log interpolation.
+        gradient: Gradient of regression from :cite:t:`hardwick_relationship_2015`
 
     Returns:
         vertical profile of provided variable
@@ -192,7 +193,7 @@ def calculate_saturation_vapour_pressure(
     temperature: DataArray,
     saturation_vapour_pressure_factors: list[float],
 ) -> DataArray:
-    r"""Calculate saturation vapour pressure.
+    r"""Calculate saturation vapour pressure, kPa.
 
     Saturation vapour pressure :math:`e_{s} (T)` is here calculated as
 
@@ -219,7 +220,7 @@ def calculate_vapour_pressure_deficit(
     relative_humidity: DataArray,
     saturation_vapour_pressure_factors: list[float],
 ) -> dict[str, DataArray]:
-    """Calculate vapour pressure and vapour pressure deficit.
+    """Calculate vapour pressure and vapour pressure deficit, kPa.
 
     Vapor pressure deficit is defined as the difference between saturated vapour
     pressure and actual vapour pressure.
@@ -258,21 +259,21 @@ def interpolate_soil_temperature(
     """Interpolate soil temperature using logarithmic function.
 
     Args:
-        layer_heights: vertical layer heights, [m]
-        layer_roles: list of layer roles (from top to bottom: above, canopy, subcanopy,
+        layer_heights: Vertical layer heights, [m]
+        layer_roles: List of layer roles (from top to bottom: above, canopy, subcanopy,
             surface, soil)
-        surface_temperature: surface temperature, [C]
-        mean_annual_temperature: mean annual temperature, [C]
+        surface_temperature: Surface temperature, [C]
+        mean_annual_temperature: Mean annual temperature, [C]
         layer_structure: The LayerStructure instance for the simulation.
-        upper_bound: maximum allowed value, used to constrain log interpolation. Note
+        upper_bound: Maximum allowed value, used to constrain log interpolation. Note
             that currently no conservation of water and energy!
-        lower_bound: minimum allowed value, used to constrain log interpolation.
+        lower_bound: Minimum allowed value, used to constrain log interpolation.
 
     Returns:
         soil temperature profile, [C]
     """
 
-    # select surface layer (atmosphere) and generate interpolation heights
+    # Select surface layer (atmosphere) and generate interpolation heights
     surface_layer = layer_heights[layer_structure.index_surface].to_numpy()
     soil_depths = layer_heights[layer_structure.index_all_soil].to_numpy()
     interpolation_heights = np.concatenate(

virtual_ecosystem/models/hydrology/__init__.py

@@ -21,7 +21,12 @@
   matric potential, groundwater storage, and subsurface horizontal flow.
 
 * The :mod:`~virtual_ecosystem.models.hydrology.constants` submodule contains
-  parameters and constants for the hydrology model. This is a temporary solution.
+  parameters and constants for the hydrology model.
+
+* The :mod:`~virtual_ecosystem.models.hydrology.hydrology_tools` submodule
+  contains a set of functions that support the data preprocessing for the model update,
+  for example by preselecting relevant layers, distributing monthly rainfall over 30
+  days, and so on.
 """  # noqa: D205
 
 from virtual_ecosystem.models.hydrology.hydrology_model import (  # noqa: F401