.. _environmental_description:

Environmental description
=========================

Temperature
-----------

Temperature is daily mean. This is translated to a hut temperature, and also influences the mosquito's sporogonic and gonotrophic cycles, as well as larval maturation and adult vector survival.

The model distinguishes between ambient **outdoor temperature** ($T_{outdoor}$) and **indoor temperature** ($T_{indoor}$).

The **indoor temperature** ($T_{indoor}$) is calculated based on the daily mean outdoor temperature using the scheme from Lunde et al. (Malaria Journal 2013, 12:28):

.. math::
   T_{indoor} = 10.33 + 0.58 \times T_{outdoor}

*Important parameter:* $T_{outdoor}$ (``rtemp`` in code)

The **temperature experienced by the vector** ($T_{vector}$) is then a weighted mix of the indoor and outdoor temperatures, controlled by the parameter $\beta_{indoor}$ (``rbeta_indoor`` in code), which represents the proportion of time spent indoors:

.. math::
   T_{vector} = \beta_{indoor} \times T_{indoor} + (1 - \beta_{indoor}) \times T_{outdoor}

*Important parameter:* $\beta_{indoor}$ (``rbeta_indoor`` in code)

Additionally, a **water temperature** ($T_{water}$) is derived by adding an offset ($Offset_{water}$) to the outdoor temperature:

.. math::
   T_{water} = T_{outdoor} + Offset_{water}

*Important parameter:* $Offset_{water}$ (``rwater_tempoffset`` in code)

These calculated temperatures ($T_{vector}$ and $T_{water}$) are then used in various temperature-dependent processes within the model, such as the gonotrophic cycle, sporogonic cycle, and vector/larvae survival.

Hydrology
---------

Temporary Pond parameterization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The model simulates temporary ponding, which is crucial for mosquito breeding. The variable $W_{pond}$ (``rwaterpond`` in code) represents the fraction of water surface available for breeding. The scheme for calculating $W_{pond}$ depends on the parameter $Scheme_{pond}$ (``npud_scheme`` in code).

**Scheme 0: External Data**

If $Scheme_{pond}$ is set to 0, the ponding fraction ($W_{pond}$) is read from an external data file, and rainfall is not used for pond calculation.

**Scheme 1: Simple Hydro Scheme (Tompkins and Ermert 2013)**

This is a simpler hydrological scheme:

.. math::
   W_{pond}^{t+dt} = \frac{W_{pond}^{t} + Rate_{pond} \times dt \times R \times W_{max}}{1 + Rate_{pond} \times dt \times (R + Evap_{pond} + Infil_{soil})}

Where:
* $W_{pond}^{t}$: Pond fraction at current time step.
* $W_{pond}^{t+dt}$: Pond fraction at next time step.
* $R$: Daily rainfall (``zrain`` in code), with safety limits applied (0.0 to 200.0 mm).
* $Rate_{pond}$: Ponding rate (``wpond_rate`` in code).
* $dt$: Timestep.
* $W_{max}$: Maximum pond fraction (``wpond_max`` in code).
* $Evap_{pond}$: Pond evaporation rate (``wpond_evap`` in code).
* $Infil_{soil}$: Soil infiltration rate (``rsoilinfil`` in code).

*Important parameters:* $Rate_{pond}$, $W_{max}$, $Evap_{pond}$, $Infil_{soil}$.

**Scheme 2: Revised Hydrology (Asare et al. 2016a, Geospatial Health)**

This is a more sophisticated implicit scheme that incorporates pond geometry, initial abstraction, runoff calculation, and evaporation/infiltration. This scheme is described in detail in **Asare et al. 2016a (Geospatial Health)** and **Asare, Tompkins and Bomblies (PLOS One 2016)**. It includes a shape factor for pond geometry and initial abstraction, which is important to prevent ponding after light rain events.

The scheme's core equation is based on the change in water depth over time: $dw/dt = K w^{-p/2} (fQ - w(E+fI))$, where:
* $K$: Pond geometry scale factor (related to $S_0$ and $h_0$ in geometry model).
* $p$: Pond geometry power factor (0.5-2 for temporary ponds, 3-5 for lakes).
* $f$: Proportion of maximum pond area factor ($1 - w/w_{max}$).
* $Q$: Runoff.
* $E$: Evaporation from ponds.
* $I$: Maximum infiltration rate from ponds.

First, **runoff** ($Q$) is calculated using the SCS (Soil Conservation Service) formula:

.. math::
   Q = \frac{\max(0.0, R - \lambda_{pond} \times S_{pond})^2}{R + (1 - \lambda_{pond}) \times S_{pond}}

Where:
* $R$: Daily rainfall (``zrain`` in code).
* $\lambda_{pond}$: Initial abstraction coefficient (``wpond_lambda`` in code, traditionally 0.2).
* $S_{pond}$: Potential maximum retention (``wpond_S`` in code).

*Important parameters:* $\lambda_{pond}$, $S_{pond}$.

Then, intermediate parameters for the implicit solution, $C_1$ (``zpud1`` in code) and $C_2$ (``zpud2`` in code), are calculated based on pond geometry parameters:

.. math::
   C_1 = \frac{2 \times dt}{P_{shape} \times D_{ref}}

.. math::
   C_2 = \frac{2 \times dt \times W_{ref}^{P_{shape}/2}}{P_{shape} \times D_{ref}}

Where:
* $P_{shape}$: Pond geometry power factor + 2 (``wpond_shapep2`` in code).
* $D_{ref}$: Reference water depth (``wpond_depthref`` in code).
* $W_{ref}$: Reference pond area (``wpond_ref`` in code).

*Important parameters:* $P_{shape}$, $D_{ref}$, $W_{ref}$.

A **first guess solution** ($W_{guess}$) for $W_{pond}$ is computed:

.. math::
   W_{guess} = \frac{W_{pond}^{t} + C_1 \times (Q \times W_{max})}{1 + C_1 \times (Q + Evap_{pond} - R + \frac{W_{ref} \times R}{W_{max}} + \frac{W_{ref} \times Infil_{soil}}{W_{max}})}

Finally, the **solution for $W_{pond}$** is updated using an implicit formulation:

.. math::
   W_{pond}^{t+dt} = \frac{W_{pond}^{t} + C_2 \times W_{guess}^{-P_{shape}/2} \times Q \times W_{max}}{1 + C_2 \times W_{guess}^{-P_{shape}/2} \times (Q + Evap_{pond} - R + \frac{W_{guess} \times R}{W_{max}} + \frac{W_{guess} \times Infil_{soil}}{W_{max}})}

Regardless of the scheme chosen, the final $W_{pond}$ value is constrained within minimum and maximum bounds ($W_{min}$, $W_{max}$).

*Important parameters:* $W_{min}$ (``wpond_min`` in code), $W_{max}$ (``wpond_max`` in code).

Urban breeding sites
^^^^^^^^^^^^^^^^^^^^

The provided code excerpt does not contain explicit details about "Urban breeding sites" as a separate hydrological component. The pond model described in Section 7.2.1 appears to be a general mechanism for temporary pond formation. If urban breeding sites are handled differently, it would likely be through specific parameterizations within the $W_{pond}$ related variables (e.g., $W_{max}$, $Infil_{soil}$) or by using $Scheme_{pond}=0$ to input urban-specific pond data.

Permanent water features
^^^^^^^^^^^^^^^^^^^^^^^^

The code mentions $W_{perm}$ (``rwaterperm`` in code) as a separate variable for "permanent water bodies" in comments (e.g., "breeding water fraction is the sum of temporary ponds and permanent water bodies"). However, the provided excerpt of the "Pond model" section only shows the update for $W_{pond}$ (temporary ponds). There is no explicit calculation or update for $W_{perm}$ shown in this section of the code. This implies that $W_{perm}$ is likely a static input or is handled in a different part of the model. The final $W_{pond}$ value, after calculation, represents the "temporary pond" component, which would then be combined with $W_{perm}$ (permanent water) elsewhere in the model to determine the total breeding water.