---
title: "Modeling C3 Photosynthesis: recommendations for common scenarios"
author: "Chris Muir"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Modeling C3 Photosynthesis: recommendations for common scenarios}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(photosynthesis)
```

# 'Typical' hypostomatous leaf

Here I show how to implement a model close to the most widely used ones, in which boundary layer conductances are high, cuticular conductance is 0, all stomatal conductance is through the lower (abaxial) leaf surface, and there is a single mesophyll conductance. The advantage of this approach are that is its simplicity. You can ignore several complexities such as:

* Low boundary layer conductance that varies between surfaces (can happen in large leaves at low wind speed)
* Large cuticular conductance (this can be happen in young leaves)
* Stomatal conductance can occur through both surface in amphistomatous leaves (this is common in herbs, for example)
* Mesophyll conductance can be partitioned into air and liquid phases

If these complexities are important to you, consider more complex models you can implement with **photosynthesis**. But, if you don't care, here's how to make things simple:

```{r, simple leaf, message = FALSE, eval=TRUE}
library(photosynthesis)
bake_par   = make_bakepar()                       # temperature response parameters
constants  = make_constants(use_tealeaves = FALSE) # physical constants
# leaf parameters
leaf_par   = make_leafpar(
  replace = list(
    # Set cuticular conductance to 0
    g_uc = set_units(0, mol / m^2 / s),
    # All conductance through lower stomata and mesophyll
    k_mc = set_units(0, 1),
    k_sc = set_units(0, 1)
  ),
  use_tealeaves = FALSE
  )   
enviro_par = make_enviropar(use_tealeaves = FALSE) # environmental parameters

photo(leaf_par, enviro_par, bake_par, constants, use_tealeaves = FALSE) |>
  dplyr::select(g_sc, A) |>
  knitr::kable(caption = "Stomatal conductance to CO2 (g_sc) and net photosynthetic carbon assimilation (A) from C3 photosynthesis model.")
```


# Amphistomatous leaf

Most leaves, especially on woody plants, are hypostomatous (Muir 2015) meaning that all the stomatal conductance is through the lower (abaxial surface). But many fast-growing herbaceous species, especially crops (Milla *et al.* 2013), are amphistomatous. There are not a lot of measurements of how much conductance occurs through each surface (but see Wall *et al.* 2022), but we assume that if stomata are present on both leaf surfaces there is CO~2~ flux through each surface. For amphistomatous leaves, I suggest explicitly modeling conductance through the internal airspace ($g_\mathrm{ias,c}$) and liquid phase ($g_\mathrm{liq,c}$). As of version 2.1.0 this is possible in **photosynthesis**. Here's a simple example:

```{r, amphi leaf, message = FALSE, eval=TRUE}
library(photosynthesis)
bake_par   = make_bakepar()                       # temperature response parameters
constants  = make_constants(use_tealeaves = FALSE) # physical constants
# leaf parameters
leaf_par   = make_leafpar(
  replace = list(
    # Set cuticular conductance to 0
    g_uc = set_units(0, mol / m^2 / s),
    # Half of conductance through each surface
    k_mc = set_units(0, 1),
    # airspace conductance: define effective distance through airspace
    # See Nobel (2020) pg. 431
    delta_ias_lower = set_units(100, um),
    delta_ias_upper = set_units(100, um),
    # liquid conductance: sum of cell wall, plasma membrane, and cytosol resistance
    # We are implicitly ignoring chloroplast resistance
    # See Nobel (2020) pg. 448-452
    A_mes_A = set_units(20, 1),
    g_liqc25 = set_units(0.02, mol / m^2 / s),
    k_sc = set_units(1, 1)
  ),
  use_tealeaves = FALSE
  )   
enviro_par = make_enviropar(use_tealeaves = FALSE) # environmental parameters

photo(leaf_par, enviro_par, bake_par, constants, use_tealeaves = FALSE) |>
  dplyr::select(g_sc, g_iasc_lower, g_iasc_upper, g_liqc, A) |>
  knitr::kable(caption = "Stomatal conductance to CO2 (g_sc), internal airspace resistance through lower and upper surfaces (g_iasc_x), liquid-phase conductance (g_liqc), and net photosynthetic carbon assimilation (A) from C3 photosynthesis model.")
```

# References

Muir CD. 2015. Making pore choices: repeated regime shifts in stomatal ratio. *Proc Roy Soc B* 282: 20151498.

Nobel PS. 2020. *Physicochemical and Environmental Plant Physiology*. 5th Edition. Academic Press. 

Rubén M, N de Diego-Vico, N Martín-Robles. 2013. Shifts in stomatal traits following the domestication of plant species. *Journal of Experimental Botany* 64(11): 3137–3146. 

Wall S, S Vialet-Chabrand, P Davey, JV Rie, A Galle, J Cockram, T Lawson. 2022. Stomata on the abaxial and adaxial leaf surfaces contribute differently to leaf gas exchange and photosynthesis in wheat. *New Phytologist* 235(5): 1743-1756.