crt1d.leaf_area
===============

.. py:module:: crt1d.leaf_area

.. autoapi-nested-parse::

   Distribute leaf area amongst model layers.

   Based on a quantitative description of the leaf area profile,
   and desired number of model layers,
   allocate equal increments of dlai to layers,
   and assign heights (z; m) to give the desired leaf area profile.

   LAI is cumulative and defined at the model interface levels.



Functions
---------

.. autoapisummary::

   crt1d.leaf_area.distribute_lai_beta
   crt1d.leaf_area.distribute_lai_beta_bonan
   crt1d.leaf_area.distribute_lai_from_cdd
   crt1d.leaf_area.distribute_lai_gamma
   crt1d.leaf_area.distribute_lai_weibull
   crt1d.leaf_area.distribute_lai_weibull_z


Module Contents
---------------

.. py:function:: distribute_lai_beta(h_c, LAI, n, *, h_min=0.5)

   Create LAI profile using beta distribution for leaf area density.
   This uses a set fractional height of maximum LAD and corresponding beta distribution shape.

   :param h_c: canopy height
   :type h_c: :class:`float`
   :param n: number of layers (LAI/interface levels)
   :type n: :class:`int`
   :param LAI: total LAI
   :type LAI: :class:`float`
   :param h_min: height above ground of the canopy bottom
   :type h_min: :class:`float`

   :returns: :class:`NamedTuple` --

             lai : numpy.ndarray
                 cumulative LAI profile; accumulates from top, so decreasing with z
             lad : numpy.ndarray
                 leaf area density profile
             z : numpy.ndarray
                 height above ground (increasing)


.. py:function:: distribute_lai_beta_bonan(h_c, LAI, n, *, h_min=0.5, p=3.5, q=2.0)

   Beta distribution based on Bonan SP 2.1.

   :param h_c: canopy height
   :type h_c: :class:`float`
   :param n: number of layers (LAI/interface levels)
   :type n: :class:`int`
   :param LAI: total LAI
   :type LAI: :class:`float`
   :param h_min: height above ground of the canopy bottom
   :type h_min: :class:`float`
   :param p: beta distribution shape parameters
   :type p: :class:`float`
   :param q: beta distribution shape parameters
   :type q: :class:`float`

   :returns: :class:`NamedTuple` --

             lai : numpy.ndarray
                 cumulative LAI profile; accumulates from top, so decreasing with z
             lad : numpy.ndarray
                 leaf area density profile
             z : numpy.ndarray
                 height above ground (increasing)


.. py:function:: distribute_lai_from_cdd(cdd, n)

   Create LAI profile based on input descriptors of the leaf area distribution.

   :param cdd: canopy description dict. contains many things. see the default CSV for example
   :type cdd: :class:`dict`
   :param n: desired number of levels (LAI/interface levels)
   :type n: :class:`int`


.. py:function:: distribute_lai_gamma(h_c, LAI, n)

   Create LAI profile using Gamma distribution for leaf area density.

   :param h_c: canopy height
   :type h_c: :class:`float`
   :param n: number of layers (LAI/interface levels)
   :type n: :class:`int`
   :param LAI: total LAI
   :type LAI: :class:`float`

   :returns: :class:`NamedTuple` --

             lai : numpy.ndarray
                 cumulative LAI profile; accumulates from top, so decreasing with z
             lad : numpy.ndarray
                 leaf area density profile
             z : numpy.ndarray
                 height above ground (increasing)


.. py:function:: distribute_lai_weibull(h_c, LAI, n, *, h_min=0.5, b=None, c=None, species=None)

   Leaf area profile with equal LAI increments from the Weibull distribution
   using :func:`distribute_lai_weibull_z` and interpolation (as such, lad(z) and
   lai(z) might not be completely consistent).

   :param h_c: canopy height
   :type h_c: :class:`float`
   :param n: number of layers (LAI/interface levels)
   :type n: :class:`int`
   :param LAI: total LAI
   :type LAI: :class:`float`
   :param h_min: Canopy minimum height above ground. The default is 0.5.
   :type h_min: :class:`float`, *optional*
   :param b: Weibull shape parameter 1. The default is None.
   :type b: :class:`float`, *optional*
   :param c: Weibull shape parameter 2. The default is None.
   :type c: :class:`TYPE`, *optional*
   :param species: One of 'spruce', 'spruce', or 'birch'. Used to look up typical shape parameter values.
                   The default is None.
   :type species: :class:`str`, *optional*

   :returns: :class:`NamedTuple` --

             lai : numpy.ndarray
                 cumulative LAI profile; accumulates from top, so decreasing with z
             lad : numpy.ndarray
                 leaf area density profile
             z : numpy.ndarray
                 height above ground (increasing)


.. py:function:: distribute_lai_weibull_z(z, LAI, h, hb=0.0, *, b=None, c=None, species=None)

   Leaf area profile from Weibull distribution for given `z` grid.

   Samuli's notes:

   .. code:: none

      Generates leaf-area density profile from Weibull-distribution
      Args:
          z: height array (m), monotonic and constant steps
          LAI: leaf-area index (m2m-2)
          h: canopy height (m), scalar
          hb: crown base height (m), scalar
          b: Weibull shape parameter 1, scalar
          c: Weibull shape parameter 2, scalar
          species: 'pine', 'spruce', 'birch' to use table values
      Returns:
          LAD: leaf-area density (m2m-3), array
      SOURCE:
          Teske, M.E., and H.W. Thistle, 2004, A library of forest canopy structure for
          use in interception modeling. Forest Ecology and Management, 198, 341-350.
          Note: their formula is missing brackets for the scale param.
          Here their profiles are used between hb and h
      AUTHOR:
          Gabriel Katul, 2009. Coverted to Python 16.4.2014 / Samuli Launiainen