Merge pull request #15 from rgknox/rgknox-allometry-diagrams

Some descriptions of allometry, and forcing the allometric curve

docs/source/CLM50_Tech_Note_References.rst

@@ -372,6 +372,13 @@ Cao, M., Marshall, S. and Gregson, K., 1996. Global carbon exchange and
 methane emissions from natural wetlands: Application of a process-based
 model. J. Geophys. Res. 101(D9):14,399-14,414.
 
+.. _Chaveetal2014:
+
+|br|
+
+Chave et al, 2015. Improved allometric models to estimate the abovegroud
+biomass of tropical trees.  Global Change Biology. V20, p3177-3190.
+
 .. _Chuangetal2006:
 
 |br|
@@ -1714,6 +1721,16 @@ Martin, J.P., Haider, K. and Kassim, G., 1980. Biodegradation and
 stabilization after 2 years of specific crop, lignin, and polysaccharide
 carbons in soils. Soil Science Society of America Journal 44:1250-1255.
 
+.. _MartinezCanoetal2019:
+
+ |br|
+
+Martinez Cano, I., Muller-Landau, H. C., Wright, S. J., Bohlman, S. A. and Pacala S. W., 2019. 
+Tropical tree height and crown allometries for the Barro Colorado Nature Monument, Panama: 
+a comparison of alternative hierarchical models incorporating interspecific variation in relation 
+to life history traits. Biogeosciences 16(4):847-862.
+
+
 .. _Maryetal1993:
 
 |br|
@@ -1880,6 +1897,12 @@ basins. J. Geophys. Res. 112:D21101. DOI:10.1029/2007JD008674.
 
 Norman, J.M., 1979. Modeling the complete crop canopy. Modification of the Aerial Environment of Crops, pp. 249-280.
 
+.. _Obrienetal1995:
+
+|br|
+
+O'Brien, S.T., S. T., Hubbell, S. P., Spiro, P., Condit, R., and Foster, R. B. 1995. Diameter, Height, Crown, and Age Relationship in Eight Neotropical Tree Species, Ecology, 76: 1926–1939.
+
 .. _Oikawaetal2005:
 
 |br|
@@ -2124,6 +2147,13 @@ Pomeroy, J. W., D. M. Gray, K. R. Shook, B. Toth, R. L. H. Essery,
 A. Pietroniro, and N. Hedstrom. 1998. An evaluation of snow accumulation
 and ablation processes for land surface modelling. Hydrol. Process. 12:2339–2367.
 
+.. _Poorteretal2006:
+
+|br|
+
+Poorter, L., L. Bongers and F. Bongers. 2006.  Architecture of 54 moist-forest tree species: Traits, trade-offs, and functional groups.  Ecology, 87(5): 1289-1301.
+
+
 .. _Portmannetal2010:
 
 |br|
@@ -2318,6 +2348,12 @@ DOI:10.1029/2008JD010834.
 
 Sato, H., A. Itoh, and T. Kohyama, 2007. SEIB-DGVM: A new Dynamic Global Vegetation Model using a spatially explicit individual-based approach. Ecological Modelling 200.3, pp. 2793307.
 
+.. _Saldarriaga1988:
+
+|br|
+
+Saldarriaga, J.G. et al., 1998. Journal of Ecology vol 76 p938-958.
+
 .. _Schaafetal2002:
 
 |br|

docs/source/fates_tech_note.rst

@@ -526,42 +526,13 @@ by the model. Smaller plants are not considered, and their emergence
 from the recruitment processes is unresolved and therefore implicitly
 parameterized in the seedling establishment model.
 
+The diameter of each cohort is then specified according to the height-diameter allometry function associated with the PFT of interest, see :ref:`allometry_table`. The biomass pools for the newly recruited plant are then determined from the allometry equations that define the target (idealized) sizes for each pool.
 
-**NOTE: With Modular allometry, the following is 1 of several different height to diameter relationships**
-
-The diameter of each cohort is then specified using the log-linear allometry between stem
-diameter and canopy height.
-
-.. math:: \mathit{dbh}_{coh} = 10^{\frac{\log_{10}(h_{coh}) - c_{allom}}{m_{allom}}  }
-
-where the slope of the log-log relationship, :math:`m_{allom}` is 0.64
-and the intercept :math:`c_{allom}` is 0.37. The structural biomass
-associated with a plant of this diameter and height is given (as a
-function of wood density, :math:`\rho`, g cm\ :math:`^{-3}`)
-
-.. math:: C_{struc,coh} =c_{str}h_{coh}^{e_{str,hite}} dbh_{coh}^{e_{str,dbh}} \rho_{ft}^{e_{str,dens}}
-
-taken from the original ED1.0 allometry
-:ref:`Moorcroft et al. 2001<mc_2001>` (values of the allometric constants in
-Table `[table:allom] <#table:allom>`__. The maximum amount of leaf
-biomass associated with this diameter of tree is calculated according to
-the following allometry
-
-.. math:: C_{max,leaf,coh} =c_{leaf}\it{dbh}_{coh}^{e_{leaf,dbh}} \rho_{ft}^{e_{leaf,dens}}
-
-from this quantity, we calculate the active/fine root biomass
-:math:`C_{root,coh}` as
-
-.. math:: C_{root,coh} =  C_{max,leaf,coh}\cdot f_{frla}
-
-where :math:`f_{frla}` is the fraction of fine root biomass to leaf
-biomass, assigned per PFT.
-
-**The previous section should be expanded to include the modular allometry options.**
+.. _model_init_params_coldstart:
 
 .. raw:: latex
 
-   \captionof{table}{Parameters needed for model initialization.}
+   \captionof{table}{(INCOMPLETE) List of the parameters that define the intialization of new plants during a "cold-start" simulation.}
 
 +-----------------+-----------------+-----------------+-----------------+
 | Parameter       | Parameter Name  | Units           | Default Value   |
@@ -574,25 +545,127 @@ biomass, assigned per PFT.
 |                 | Planting        | m\ :math:`^{-2}`|                 |
 |                 | density         |                 |                 |
 +-----------------+-----------------+-----------------+-----------------+
-| :math:`A_{tot}` | Model area      | m\ :math:`^{2}` | 10,000          |
-+-----------------+-----------------+-----------------+-----------------+
 
-[table:init]
 
+.. _parteh_section:
 
 Allocation and Reactive Transport (PARTEH)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The **Plant Allocation** and **Reactive Transport Extensible Hypotheses (PARTEH)** is a suite of modules that handle the processes of allocation, transport and reactions (i.e. thos processes related to movement and change, yet perhaps not the genesis) of various arbitrary species (carbon, nutrients, toxins, etc) within the various organs of live vegetation.  In FATES, these processes are resolved per unit plant, for each cohort.
 
 .. toctree::
-   :maxdepth: 2
-   :numbered:
+   :maxdepth: 1
 
    parteh/overview_domain.rst
    parteh/hypotheses.rst
 
 
+.. _allometry_section:
+
+Allometry and Growth Along Allometric Curves
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the previous section,  :ref:`parteh_section`, we covered the equations that describe how growth is implemented, as well the order of operations and logic of that forumlation.  In this section, we will discuss the various allometric functions that generate the relative rates of change, as well as the target biomass quantities :math:`\grave{X}`.
+
+"Forced" Growth Along Allometric Curves
+---------------------------------------
+
+Growth specified by current PARTEH hypotheses follow along the allometric curves.  A hypothetical example of a cohorts integration along such a curve is provided in the top panel of the diagram below. It is assumed that when a plant grows in stature, the structural biomass matches the target structural biomass for its size (DBH).  This is represented by the grey dot sitting on the allometry line for structural biomass.
+
+**A state of being "on allometry" is consistent with the cohort (grey dot) existing on the allometric curve.**
+
+It is expected, and it is represented in the model, that due to either continuous or event based turnover, that biomass pools are continually depleted, thus pulling the grey dot straight down, away from the allometry line.  Recall from the PARTEH description, that the first step in the growth algorithm is to use available carbon to replace these lost biomass pools (without increasing dbh) so that it is "on allometry". 
+
+Also, all numerical integration has some amount of truncation error (step error). When FATES conducts the stature growth integration step, it typically uses Euler integration, because it is fast and simple.  As a result, all biomass pools are projected along the tangent of the allometric curves from where they started.  When the curvature parameters that govern these relationships are greater than 1, this results in continual "undershooting" of the actual target quantity.  This is not a liability, firstly because growth is forced to be mass conservative.  And secondly, to re-iterate the explanation above, upon the next growth step the algorithm will spend carbon to first get the pools back "on allometry", before it projects along the tangent again.  This is represented in the lower panel.
+
+
+.. figure:: images/growth_allometry_p1.png
+
+
+However, we also have to accomodate for cases where the actual amount of biomass in the cohort's pools are larger than the target sizes dictated by the cohort's diameter.  This can be visualized by the cohort residing somewhere above the line.  This can happen for two reasons, 1) cohort fusion or 2) growth along allometric curves with curvature parameters (exponents) less than 1.
+
+For woody plants, if a non-structural biomass pool is greater than the target pool size, the solution is simple.  That pool is flagged to be ignored during the stature growth step, and eventually the cohort's dbh will increase such that the target size exceeds its actual size again.  This is visualized in the top panel of the diagram below.
+
+There is a caveat here.  The diameter must be "tied" to one of the biomass pools.  And for woody plants, we choose structural carbon.  And thus, we cannot flag to ignore structural carbon during stature growth since it is inextricably linked to diameter.  Therefore, cohorts that have structural biomass that is greater than the target biomass dictated by its diameter, will have their DBH forceably increased (without increasing any biomass) until the allometric target matches the actual biomass.  See the lower panel in the diagram below.
+
+.. figure:: images/growth_allometry_p2.png
+
+Note, the explanation above was explained for woody plants, which tie diameter to structural biomass.  For non-woody plants, such as grasses, we tie leaf biomass to diameter instead.
+
+Allometric Relationships
+------------------------
+
+.. _FatesAllometryMod.F90: https://github.com/NGEET/fates/blob/master/biogeochem/FatesAllometryMod.F90
+
+FATES-PARTEH (in its base hypotheses) uses allometry to dictate the target biomass quantities of structure, sapwood, leaf, fine-root, reproduction and storage. Further, FATES also uses allometric relationships to define a cohort's height and crown area.  All of these target quantities are tied to diameter. Biomass pools may also be functionally dependent on other biomass pools, as long as a cyclical relationship is not generated, and can ultimately be related to diameter or other external factors.  For instance, target root biomass is typically defined as proportional to leaf biomass.  Target leaf biomass is dependent on height and a canopy trimming function, while crown area and above ground biomass are each also dependent on height.
+
+The FATES code is written in a way that offers flexibility in how these relationships are cast.  Each of these forumulations uses one or more user defined constant parameters, but it also allows for completely different functional forms. All of FATES allometric relationships can be found in the file FatesAllometryMod.F90_.  
+
+Important note. Most allometry relationships from field research define total above ground biomass (AGB) as their estimated quantity instead of structural biomass.  In FATES, since AGB is not a state-variable, it must be derived from the portions of several state variables.  However, we make a simplification in FATES, and assume that the allometric relationships for AGB only contain structural wood and sapwood, and do not contain leaves, storage or reproductive tissues.  Diagnostics on AGB will include all terms.  Thus the allometric target for AGB contains the state targets and the fraction of above ground biomass (pft constant parameter) :math:`f_{a}`.
+
+.. math::
+   :label: allom_agb_eq
+
+   \grave{C}_{(AGB)} &= (\grave{C}_{(structure)} + \grave{C}_{(sapwood)}) * f_{agb}
+
+
+Note that the diameter to height relationships all use an effective diameter, :math:`d_*`.  This is the minimum between the actual plant diameter, and the PFT specific parameter that specifies the diameter at which maximum height occurs :math:`d_{hmax}`.
+
+.. math::
+   :label: allom_dbh_maxh
+
+   d_* = \text{min}(d,d_{hmax})
+
+
+
+The following table details the different allometric relationships that governs growth and stature, and the optional relationships and parameters associated with those relationships.  
+
+
+.. _allometry_table:
+
+.. table:: Table of Allometric Functions
+   :align: center
+
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | Reference                                               | Function                                                                                 |
+   +=========================================================+==========================================================================================+
+   | Diameter to Height                                                                                                                                 |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | Power Function                                          | :math:`h = p_1 \cdot d_*^{p_2}`                                                          |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | :Ref:`Obrien et al (1995)<Obrienetal1995>`              | :math:`h = 10^{(log10(d_*) \cdot p_1+p_2)}`                                              |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | :ref:`Poorter et al (2006)<Poorteretal2006>`            | :math:`h = p_1 \cdot (1 - e^{p_2 \cdot d_*^{p_3}})`                                      |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | :ref:`Martinez Cano et al (2019)<MartinezCanoetal2019>` | :math:`h = (p_1 \cdot d_*^{p_2}) / (p_3+ d_*^{p_2})`                                     |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | Target Above Ground Biomass                                                                                                                        |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | :ref:`Saldarriaga et al. (1998)<Saldarriaga1988>`       | :math:`\grave{C}_{agb} = f_{agb} \cdot p_1 \cdot h^{p_2} \cdot d^{p_3} \cdot \rho^{p_4}` |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | 2 Parameter power function                              | :math:`\grave{C}_{agb} = p_1/\text{c2b} \cdot d^{p_2}`                                   |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | :ref:`Chave et al. (2014)<Chaveetal2014>`               | :math:`\grave{C}_{agb} = p_1/\text{c2b} \cdot (\rho \cdot d^{2} \cdot h)^{p_2}`          |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | Target Leaf Biomass  (TBD)                                                                                                                         |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | Target Sapwood Biomass    (TBD)                                                                                                                    |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | Target Fine-root Biomass    (TBD)                                                                                                                  |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+   | Target Storage Biomass    (TBD)                                                                                                                    |
+   +---------------------------------------------------------+------------------------------------------------------------------------------------------+
+
+
+*List of allometric relationships, their functional forms, and relevant parameters.*
+
+
 Canopy Structure and the Perfect Plasticity Approximation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/source/index.rst

@@ -7,7 +7,7 @@ Welcome to FATES's documentation!
 =================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :numbered:
 
    fates_tech_note.rst

docs/source/parteh/h1_callom_only.rst

@@ -231,7 +231,7 @@ Grow Stature Concurrently
 
 Note, it possible that some pools may be larger than their allometric targets.  This is due to numerical imprecisions, and also may be an artifact of the fusion process in demographic scaling routines (FATES/ED). While it has not been explicitly stated yet, many of the previous calculations in this chapter prevent negative fluxes out of the carbon pools in such cases.  In this step, we define the set of organs :math:`o` that match allometry with some precision, but not above. This is the stature growth set, :math:`\mathbb{O}_{sg}`.
 
-The allometric functions governing the target sizes of the carbon pools also provide the rate of change in the pool with respect to plant diameter. These functions can be related to the plants diameter, and uses parameterizations that are tuned to the plant's functional type.  Since the plant is on allometry, the actual carbon pools should match the target pools, to some precision.  Therefore, for any diameter :math:`d`, we also know for each organ :math:`o` in :math:`\mathbb{O}_{sg}` we can obtain the differential from the allometry module.  A description of the allometry module is provided in the :ref:`allometry_chapter`.
+The allometric functions governing the target sizes of the carbon pools also provide the rate of change in the pool with respect to plant diameter. These functions can be related to the plants diameter, and uses parameterizations that are tuned to the plant's functional type.  Since the plant is on allometry, the actual carbon pools should match the target pools, to some precision.  Therefore, for any diameter :math:`d`, we also know for each organ :math:`o` in :math:`\mathbb{O}_{sg}` we can obtain the differential from the allometry module.  A description of the allometry module is provided in the allometry chapter.
 
 .. math::
    :label: h1_sgrowth_allom_genic