crt1d.leaf_angle
================

.. py:module:: crt1d.leaf_angle

.. autoapi-nested-parse::

   Parameterizations of the impact of leaf angles on canopy RT.

   Leaf angle factor :math:`G` and the black leaf extinction coeff :math:`K_b`
   have the following relationship:

   .. math::
      K_b = G / \cos(\psi)

   where :math:`\psi` is the solar zenith angle and :math:`K_b = K_b(\psi), G = G(\psi)`.

   :math:`G` is the mean relative projection of leaf area in the direction :math:`\psi`.

   :math:`g(\theta_l)` is the PDF of leaf inclination angle :math:`\theta_l`
   (relative to the horizontal plane).
   :math:`G(\psi)` functions are derived from these distributions.
   The azimuth angle is usually assumed to have a uniform distribution
   and so does not have an impact.



Functions
---------

.. autoapisummary::

   crt1d.leaf_angle.G_ellipsoidal
   crt1d.leaf_angle.G_ellipsoidal_approx
   crt1d.leaf_angle.G_ellipsoidal_approx_bonan
   crt1d.leaf_angle.G_horizontal
   crt1d.leaf_angle.G_spherical
   crt1d.leaf_angle.G_vertical
   crt1d.leaf_angle.g_ellipsoidal
   crt1d.leaf_angle.g_erectophile
   crt1d.leaf_angle.g_plagiophile
   crt1d.leaf_angle.g_planophile
   crt1d.leaf_angle.g_spherical
   crt1d.leaf_angle.g_uniform
   crt1d.leaf_angle.mla_from_g
   crt1d.leaf_angle.mla_to_x_approx
   crt1d.leaf_angle.mla_to_x_integ
   crt1d.leaf_angle.x_to_mla_approx
   crt1d.leaf_angle.x_to_mla_integ
   crt1d.leaf_angle.xl_from_g


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

.. py:function:: G_ellipsoidal(psi, x)

   :math:`G(\psi)` for the ellipsoidal leaf angle distribution
   with parameter `x`.

   *Reference*: Campbell (1986) eqs. 5, 6 :cite:`campbell_extinction_1986`

   :param psi: Solar zenith angle in radians.
   :type psi: :class:`float`
   :param x: b/a -- the ratio of ellipse horizontal semixaxis length to vertical,
             s.t. `x` > 1 indicates an oblate spheroid.
   :type x: :class:`float`


.. py:function:: G_ellipsoidal_approx(psi, x)

   Campbell :math:`G` approximate form.

   .. rubric:: References

   * area ratio term: Campbell (1990) eq. 14 :cite:`campbellDerivationAngleDensity1990`
   * exact formula: Campbell & Norman eq. 15.4 :cite:`campbell_introduction_2012`


.. py:function:: G_ellipsoidal_approx_bonan(psi, xl)

   Campbell :math:`G` approximate form -- Bonan version.

   This uses :math:`\chi_l`, an index which quantifies the departure of the
   leaf angle distribution from spherical.

   .. warning::
      `xl` is not the same parameter as the ``x`` used elsewhere in this module.
      ``xl=0`` gives spherical, whereas ``x=1`` gives spherical.


.. py:function:: G_horizontal(psi)

   :math:`G(\psi)` for horizontal leaves.


.. py:function:: G_spherical(psi)

   :math:`G(\psi)` for the spherical leaf inclination angle distribution.


.. py:function:: G_vertical(psi)

   :math:`G(\psi)` for vertical leaves.


.. py:function:: g_ellipsoidal(theta_l, x)

   PDF of :math:`\theta_l` for the ellipsoidal distribution
   with parameter `x`.
   Following :cite:t:`bonan_climate_2019` (p. 30, eqs. 2.11--14).


.. py:function:: g_erectophile(theta_l)

   PDF of :math:`\theta_l` for a mostly vertical distribution.


.. py:function:: g_plagiophile(theta_l)

   PDF of :math:`\theta_l` for a distribution between horizontal and vertical.


.. py:function:: g_planophile(theta_l)

   PDF of :math:`\theta_l` for a mostly horizontal distribution.


.. py:function:: g_spherical(theta_l)

   PDF of :math:`\theta_l` for the spherical distribution.
   Vertical leaves are favored, but not as much so as for erectophile.


.. py:function:: g_uniform(theta_l)

   PDF of :math:`\theta_l` for a uniform distribution.


.. py:function:: mla_from_g(g_fn)

   Calculate (estimate) the mean leaf inclination angle (deg.)
   by numerically integrating the distribution's PDF: :math:`g(\psi)`.


.. py:function:: mla_to_x_approx(mla)

   Convert mean leaf angle (deg.) to `x`
   for the ellipsoidal leaf angle distribution.
   Using Campbell (1990) :cite:`campbellDerivationAngleDensity1990` eq. 16 inverted.


.. py:function:: mla_to_x_integ(mla)

   Convert mean leaf angle (deg.) to `x`
   for the ellipsoidal leaf angle distribution
   by optimization.


.. py:function:: x_to_mla_approx(x)

   Convert `x` to mean leaf angle (deg.)
   for the ellipsoidal leaf angle distribution.
   Using Campbell (1990) :cite:`campbellDerivationAngleDensity1990` eq. 16.


.. py:function:: x_to_mla_integ(x)

   Convert `x` to mean leaf angle (deg.)
   for the ellipsoidal leaf angle distribution
   by numerically integrating the leaf angle PDF.


.. py:function:: xl_from_g(g_fn)

   Compute :math:`\chi_l`, an index which quantifies the departure of the
   leaf angle distribution from spherical.

   Vertical leaves have :math:`\chi_l = -1` and horizontal leaves :math:`\chi_l = +1`.

   :cite:t:`bonan_climate_2019` eq. 2.16