System to allow constants to be altered based on configuration

docs/source/api/abiotic_simple/abiotic_constants.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: vr_python3
+  language: python
+  name: vr_python3
+---
+
+#  API for the {mod}`~virtual_rainforest.models.abiotic_simple.constants` module
+
+```{eval-rst}
+.. automodule:: virtual_rainforest.models.abiotic_simple.constants
+    :autosummary:
+    :members:
+    :special-members: __init__
+```

docs/source/development/defining_new_models.md

@@ -34,7 +34,7 @@ directory.
 mkdir virtual_rainforest/models/freshwater
 ```
 
-You will need to create at least three files within this folder, although you may choose
+You will need to create at least four files within this folder, although you may choose
 to add other python modules containing different parts of the module functionality.
 
 * An `__init__.py` file, which tells Python that the folder is a submodule within the
@@ -43,13 +43,16 @@ to add other python modules containing different parts of the module functionali
   object.
 * A JSON Schema file defining the model configuration, called
   `{model_name}_schema.json`.
+* A python module  `constants.py` that will contain the constants relevant to the model
+  (in one or more dataclasses).
 
 For example:
 
 ```bash
 touch virtual_rainforest/models/freshwater/__init__.py
 touch virtual_rainforest/models/freshwater/freshwater_model.py
 touch virtual_rainforest/models/freshwater/freshwater_schema.json
+touch virtual_rainforest/models/freshwater/constants.py
 ```
 
 ## Defining the new model class
@@ -177,6 +180,7 @@ def __init__(
     data: Data,
     update_interval: pint.Quantity,
     no_of_ponds: int,
+    constants: FreshwaterConsts,
     **kwargs: Any,
 ):
 
@@ -193,6 +197,9 @@ def __init__(
 
     # Store model specific details as attributes.
     self.no_of_ponds = int(no_of_ponds)
+
+    # Store the constants relevant to the freshwater model
+    self.constants = constants
 
     # Save attribute names to be used by the __repr__
     self._repr.append("no_of_ponds")
@@ -300,6 +307,14 @@ The method then uses those parsed arguments to actually call the `__init__` meth
 return an initialised instance of the model using the settings. The `from_config`
 method should raise an `InitialisationError` if the configuration fails.
 
+The `from_config` method should also check if any constants have been provided as part
+of the configuration. If they haven't a default set of constants is generated. If they
+have been supplied they are used to generate a custom set of constants. The
+{func}`~virtual_rainforest.core.utils.check_constants` utility function is used to check
+that no constant has been supplied with an incorrect name. At least one constants class
+should be created, but it's fine to split constants across more classes if that makes
+for clearer code.
+
 As an example:
 
 ```python
@@ -322,11 +337,22 @@ def from_config(
     # Non-timing details now extracted
     no_of_pools = config["freshwater"]["no_of_pools"]
 
-    LOGGER.info(
-            "Information required to initialise the soil model successfully "
-            "extracted."
+    # Check if any constants have been supplied
+    if "freshwater" in config and "constants" in config["freshwater"]:
+        # Checks that constants is config are as expected
+        check_constants(config, "freshwater", "FreshwaterConsts")
+        # If an error isn't raised then generate the dataclass
+        constants = FreshwaterConsts(
+            **config["freshwater"]["constants"]["FreshwaterConsts"]
         )
-        return cls(data, update_interval, no_pools)
+    else:
+        # If no constants are supplied then the defaults should be used
+        constants = FreshwaterConsts()
+
+    LOGGER.info(
+        "Information required to initialise the soil model successfully extracted."
+    )
+    return cls(data, update_interval, no_pools, constants)
 
 ```
 

docs/source/index.md

@@ -66,6 +66,7 @@ team.
   virtual_rainforest/module_overview.md
   virtual_rainforest/usage.md
   virtual_rainforest/main_simulation.md
+  virtual_rainforest/parameterisation.md
   virtual_rainforest/soil/soil_details.md
   virtual_rainforest/core/grid.md
   virtual_rainforest/core/data.md
@@ -96,6 +97,7 @@ team.
   Abiotic Simple Overview <api/abiotic_simple.md>
   Abiotic Simple Model <api/abiotic_simple/abiotic_simple_model.md>
   Abiotic Simple Microclimate <api/abiotic_simple/microclimate.md>
+  Abiotic Simple Constants <api/abiotic_simple/abiotic_constants.md>
   Abiotic Hydrology Overview <api/hydrology.md>
   Abiotic Hydrology Model <api/hydrology/hydrology_model.md>
   Abiotic Hydrology Constants <api/hydrology/hydrology_constants.md>

docs/source/virtual_rainforest/parameterisation.md

@@ -0,0 +1,59 @@
+# Virtual Rainforest parameterisation
+
+The Virtual Rainforest contains a very large number of constants. These constants are
+assigned default values based on either site specific data or best estimates from the
+literature. However, in many cases this still leads to significant uncertainty about
+true values of constants. Because of this, the Virtual Rainforest is set up to allow all
+constants to be changed. This allows end users to change constant values if they have
+access to better estimates, and also allows for sensitivity analysis to be performed.
+
+As a quick note on terminology, we have chosen to call all our parameters "constants",
+despite many of them not being truly universal constants. This is to make it clear that
+none of them should be changed within a given Virtual Rainforest simulation. Though it
+is fine to use different values for them across different simulations.
+
+## Defining constants and their default values
+
+Each model should define a `constants.py` submodule. Constants and their default values
+should be defined in this submodule using {func}`dataclasses.dataclass`. These constants
+can be stored in a single data class or spread over multiple data classes. However,
+having a large number of data classes is likely to make the downstream code messier, so
+constants should only be split across multiple classes when there's a strong reason to
+do so. It's also important that every constant is given an explicit type hint, otherwise
+the default value cannot be overwritten. An example `constants.py` file is shown below:
+
+```python
+from dataclasses import dataclass
+
+# The dataclass must be frozen to prevent constants from being accidentally altered
+# during runtime
+@dataclass(frozen=True)
+class ExampleConsts:
+    """Dataclass to store all constants for the `example_model` model."""
+
+    # Each constant must be given a type hint, otherwise its default value cannot be
+    # changed
+    example_constant_1: float = -1.27
+    """Details of source of constant and its units."""
+
+    example_constant_2: float = 5.4
+    """Details of source of constant and its units."""
+```
+
+## Using non-default values for constants
+
+If you want to use a non-default value for a constant this can be accomplished using the
+configuration system. The configuration for each specific model contains a `constants`
+section. Within this section each constants are grouped based on the name of the data
+class they belong to. An example of this can be seen below:
+
+```toml
+[example_model.constants.ExampleConsts]
+example_constant_1 = 23.0
+example_constant_2 = -7.7
+```
+
+Any values supplied in this way will be used to override the default values for the data
+class in question. Only constants for which non-default values are supplied will be
+replaced, anything that is not included within the configuration will just use the
+default value.

tests/core/test_config.py

@@ -464,6 +464,46 @@ def test_Config_build_schema(
             ),
             id="unexpected_property",
         ),
+        pytest.param(
+            {
+                "core": {"modules": ["abiotic_simple"]},
+            },
+            does_not_raise(),
+            ((INFO, "Configuration validated"),),
+            id="no constants",
+        ),
+        pytest.param(
+            {
+                "core": {"modules": ["abiotic_simple"]},
+                "abiotic_simple": {
+                    "constants": {"AbioticSimpleConsts": {"constant1": 1.0}}
+                },
+            },
+            does_not_raise(),
+            ((INFO, "Configuration validated"),),
+            id="correct constant",
+        ),
+        pytest.param(
+            {
+                "core": {"modules": ["abiotic_simple"]},
+                "abiotic_simple": {"constants": {"constant1": 1.0}},
+            },
+            pytest.raises(ConfigurationError),
+            (
+                (
+                    ERROR,
+                    "Configuration error in ['abiotic_simple', 'constants']: "
+                    "'AbioticSimpleConsts' is a required property",
+                ),
+                (
+                    ERROR,
+                    "Configuration error in ['abiotic_simple', 'constants']: Additional"
+                    " properties are not allowed ('constant1' was unexpected)",
+                ),
+                (CRITICAL, "Configuration contains schema violations: check log"),
+            ),
+            id="missing AbioticSimpleConsts",
+        ),
     ],
 )
 def test_Config_validate_config(

tests/core/test_utils.py

@@ -1,7 +1,7 @@
 """Testing the utility functions."""
 
 from contextlib import nullcontext as does_not_raise
-from logging import CRITICAL, ERROR
+from logging import CRITICAL, ERROR, INFO
 from pathlib import Path
 
 import pytest
@@ -131,3 +131,60 @@ def test_set_layer_roles(soil_layers, canopy_layers, raises, caplog, exp_log):
 
     # Final check that expected logging entries are produced
     log_check(caplog, exp_log)
+
+
+@pytest.mark.parametrize(
+    "config,raises,exp_log",
+    [
+        pytest.param(
+            {
+                "abiotic_simple": {
+                    "constants": {
+                        "AbioticSimpleConsts": {"air_temperature_gradient": -1.0}
+                    }
+                }
+            },
+            does_not_raise(),
+            (),
+            id="expected_constants",
+        ),
+        pytest.param(
+            {
+                "abiotic_simple": {
+                    "constants": {
+                        "AbioticSimpleConsts": {
+                            "air_temperature_gradient": -1.0,
+                            "invented_constant": 37.9,
+                            "saturation_vapour_pressure_factor4": 0.07,
+                        }
+                    }
+                }
+            },
+            pytest.raises(ConfigurationError),
+            (
+                (
+                    ERROR,
+                    "Incorrect constant names supplied for AbioticSimpleConsts "
+                    "dataclass: ['invented_constant', "
+                    "'saturation_vapour_pressure_factor4']",
+                ),
+                (
+                    INFO,
+                    "Valid names are as follows: [",
+                ),
+            ),
+            id="unexpected_constants",
+        ),
+    ],
+)
+def test_check_constants(caplog, config, raises, exp_log):
+    """Check that function to check constants behaves as expected."""
+    from virtual_rainforest.core.utils import check_constants
+
+    with raises:
+        check_constants(
+            config, model_name="abiotic_simple", class_name="AbioticSimpleConsts"
+        )
+
+    # Final check that expected logging entries are produced
+    log_check(caplog, exp_log)