pytrunc.truncation module#

Scattering phase function truncation methods.

This module provides the approximation of a scattering phase function by truncation of its forward peak, using either the delta-m method of Wiscombe (1977) or the geometrical truncation (GT) method of Iwabuchi and Suzuki (2009), and returns the truncated phase function together with its truncation factor.

pytrunc.truncation.delta_m_phase_approx(phase: ndarray[tuple[Any, ...], dtype[float64]], theta: ndarray[tuple[Any, ...], dtype[float64]], m_max: int, theta_unit: str = 'deg', phase_moments: ndarray[tuple[Any, ...], dtype[float64]] | None = None, method: str = 'trapezoid', ds_output: bool = True) → Dataset | tuple[ndarray[tuple[Any, ...], dtype[float64]], float, ndarray[tuple[Any, ...], dtype[float64]]][source]#

Calculate the approximation of the exact phase matrix using the delta-m method

Parameters:
phasendarray

The exact phase matrix, it must be 1-D

thetandarray

The phase matrix angles, it must be 1-D. See the theta_unit parameter for the unit

m_maxint

The maximum term number

theta_unitstr, optional

The unit of the theta angles. Default is ‘deg’, other choice is ‘rad’

phase_momentsndarray or None, optional

The moments of the phase matrix, it must be 1-D. The size of phase_moments must be >= m_max+1. If this parameter is not None, circumvent the calculation of the phase matrix moments. This parameter can be useful in case we have the exact moment values like for the H-G phase function. Default is None

methodstr, optional

The method parameter of the calc_moments function, and also the integral method for the dirac normalization. Default is ‘trapezoid’

ds_outputbool, optional

If True the output is a dataset, else return a tuple. Default is True

Returns:
Dataset or tuple

Xarray dataset containing the truncation information if ds_output is True, else a tuple.

Key variables included:

  • phase_approx: The approximation of the exact phase matrix

  • f: The truncation factor

  • phase_tr: The truncated phase matrix

  • chi: The moments of the exact phase matrix

  • chi_star: The moments of the truncated phase matrix

Form of the tuple:

  • phase_approxndarray

    -> The approximation of the exact phase matrix, it is 1-D

  • ffloat

    -> The truncation factor

  • phase_starndarray

    -> The truncated scattering phase matrix, it is 1-D

References

Wiscombe, W. J. (1977). The delta-M method: Rapid yet accurate radiative flux calculations for strongly asymmetric phase functions. Journal of Atmospheric Sciences, 34(9), 1408-1422.

Examples

>>> import numpy as np
>>> from pytrunc.phase import henyey_greenstein
>>> from pytrunc.truncation import delta_m_phase_approx
>>> theta = np.linspace(0.0, 180.0, 1801)
>>> phase = henyey_greenstein(theta, g=0.85, normalize=2)
>>> ds = delta_m_phase_approx(phase, theta, m_max=8)
>>> ds['f'].values
array(0.27248273)
pytrunc.truncation.gt_phase_approx(phase: ndarray[tuple[Any, ...], dtype[float64]], theta: ndarray[tuple[Any, ...], dtype[float64]], trunc_frac: float, theta_unit: str = 'deg', method: str = 'trapezoid', phase_moments_1: float | None = None, th_tol: float | None = None, th_f: float | None = None, lobatto_optimization: bool = True, ds_output: bool = True) → Dataset | tuple[ndarray[tuple[Any, ...], dtype[float64]], float, ndarray[tuple[Any, ...], dtype[float64]]][source]#

Compute the approximation of the exact phase matrix using the Iwabuchi GT method

Parameters:
phasendarray

The exact phase matrix, it must be 1-D

thetandarray

The phase matrix angles, it must be 1-D. See the theta_unit parameter for the unit

trunc_fracfloat

The truncation fraction

theta_unitstr, optional

The unit of the theta angles. Default is ‘deg’, other choice is ‘rad’

methodstr, optional

The method parameter of the calc_moments function, and also the integral method for the dirac normalization. Default is ‘trapezoid’

phase_moments_1float or None, optional

The value of the first moment of the phase matrix. Default is None, meaning it is computed with the calc_moments function

th_tolfloat or None, optional

While finding matching moments for Pf we look between 0 and th_tol. The unit depends on the theta_unit parameter. Default is None, meaning th_tol is equal to pi/2

th_ffloat or None, optional

Impose the truncation angle. The unit depends on the theta_unit parameter. Default is None, meaning the truncation angle is searched

lobatto_optimizationbool, optional

Whether to use lobatto optimization for integration (reuse the full-grid Lobatto quadrature, affinely rescaled to the truncation sub-interval, instead of solving for a new quadrature at every candidate angle during the truncation angle search). Default is True

ds_outputbool, optional

If True the output is a dataset, else return a tuple. Default is True

Returns:
Dataset or tuple

Xarray dataset containing the truncation information if ds_output is True, else a tuple.

Key variables included:

  • phase_approx: The approximation of the exact phase matrix

  • f: The truncation factor

  • phase_tr: The truncated phase matrix

  • chi_star_ideal: The truncated phase matrix moments if moment conservation (ideal case)

  • chi_star: The actual truncated phase matrix moments

  • theta_f: The truncation angle

  • th_f: The th_f parameter value (to force the truncation angle)

  • th_tol: The th_tol parameter value

Form of the tuple:

  • phase_approxndarray

    -> The approximation of the exact phase matrix, it is 1-D

  • ffloat

    -> The truncation factor

  • phase_starndarray

    -> The truncated scattering phase matrix, it is 1-D

References

Iwabuchi, H., & Suzuki, T. (2009). Fast and accurate radiance calculations using truncation approximation for anisotropic scattering phase functions. Journal of Quantitative Spectroscopy and Radiative Transfer, 110(17), 1926-1939.

Examples

>>> import numpy as np
>>> from pytrunc.phase import henyey_greenstein
>>> from pytrunc.truncation import gt_phase_approx
>>> theta = np.linspace(0.0, 180.0, 1801)
>>> phase = henyey_greenstein(theta, g=0.85, normalize=2)
>>> ds = gt_phase_approx(phase, theta, trunc_frac=0.2)
>>> ds['theta_f'].values
array(16.8)