A python package for the truncation of scattering phase functions in radiative transfer applications

Mustapha Moulana
HYGEOS website
Documentation

Features

• Analytic scattering phase functions: Henyey-Greenstein, two-term Henyey-Greenstein and Fournier-Forand
• Phase function Legendre moments, computed numerically for an arbitrary phase function or analytically for the Henyey-Greenstein family
• Truncation of the forward peak with the delta-m method of Wiscombe (1977) and the geometrical truncation (GT) method of Iwabuchi and Suzuki (2009)
• Truncation results returned as xarray datasets, gathering the approximated and truncated phase functions, the truncation factor, the truncation angle and the exact and truncated moments
• Numerical utilities: Legendre polynomials and their derivatives, Bessel functions of the first kind, and a Lobatto quadrature with cached abscissas and weights, for accurate integration of strongly peaked phase functions on a limited number of angles

Installation

The installation can be performed using one of the following commands:

$ conda install -c conda-forge pytrunc

$ pip install pytrunc

$ pip install git+https://github.com/hygeos/pytrunc.git

Quickstart

Truncate a Henyey-Greenstein phase function with the delta-m method and get the result as an xarray dataset:

>>> import numpy as np
>>> from pytrunc.phase import henyey_greenstein
>>> from pytrunc.truncation import delta_m_phase_approx
>>> theta = np.linspace(0., 180., 1801)  # scattering angles in degrees
>>> phase = henyey_greenstein(theta, g=0.85, normalize=2)
>>> ds = delta_m_phase_approx(phase, theta, m_max=20)
>>> ds['f'].values
array(0.03874944)

The same phase function truncated with the GT method, using the last moment as the truncation fraction:

>>> from pytrunc.phase import calc_moments
>>> from pytrunc.truncation import gt_phase_approx
>>> chi = calc_moments(phase, theta, m_max=20, normalize=True)
>>> ds = gt_phase_approx(phase, theta, trunc_frac=chi[20])
>>> ds['f'].values, ds['theta_f'].values
(array(0.03874944), array(7.1))

Examples

Truncation of a realistic water cloud phase function (Mie calculation at 500 nm, effective radius of 8 µm) with the delta-m method:

Show figure

>>> ...
>>> from pytrunc.truncation import delta_m_phase_approx
>>> m_max = 20  # stream / term number
>>> # phase_exact -> P11 of a liquid cloud at 500nm, effective radius of 8 micrometers
>>> # theta -> the phase angles in degrees
>>> ds = delta_m_phase_approx(phase_exact, theta, m_max)  # return an xarray dataset
>>> ...

The same phase function truncated with the geometrical truncation (GT) method:

Show figure

>>> ...
>>> from pytrunc.truncation import gt_phase_approx
>>> from pytrunc.phase import calc_moments
>>> m_max = 20  # stream / term number
>>> # phase_exact -> P11 of a liquid cloud at 500nm, effective radius of 8 micrometers
>>> # theta -> the phase angles in degrees
>>> chi = calc_moments(phase_exact, theta, m_max=m_max, normalize=True)  # the phase moments
>>> f = chi[m_max]  # the truncation factor
>>> ds = gt_phase_approx(phase_exact, theta, f)  # return an xarray dataset
>>> ...

Documentation

The complete documentation is available at hygeos.github.io/pytrunc. It includes example notebooks (truncation of a realistic water cloud phase function, Lobatto quadrature, and the validation against Iwabuchi and Suzuki (2009)) and the full API reference. The docstrings are also available from the built-in help function, e.g. help(delta_m_phase_approx).

License

Pytrunc is licensed under the Apache License 2.0, see LICENSE.txt.