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.27250572)
pytrunc.truncation.gt_phase_approx(phase: ndarray[tuple[Any, ...], dtype[float64]], theta: ndarray[tuple[Any, ...], dtype[float64]], trunc_frac: float | None, 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 or None

The truncation fraction f, the part of the scattering the forward peak takes away. None requires th_f: f is then the one that makes the plateau continuous with the phase matrix at th_f, see Notes

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. Only the angles within which the forward peak holds at least the fraction trunc_frac of the scattering are candidates, the others leaving a negative plateau: a ValueError is raised if there is none below th_tol

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. With a trunc_frac, the plateau is then the one the normalization gives, negative if the forward peak within th_f holds less than the fraction trunc_frac of the scattering

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. The False value is the slow reference path: the node solve is repeated at every candidate angle, which is about 70 times slower on a 1801-point grid

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

  • trunc_frac: The trunc_frac parameter value (None when f comes from the continuity of the plateau)

  • 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

Notes

The truncated phase matrix is flat below the truncation angle θf and proportional to the exact one above it, P*(θ) = P(θ)/(1 - f), the forward peak being replaced by a Dirac of weight f. Two of the angle, the fraction f and the level of the plateau set the third (the normalization of P*):

  • trunc_frac alone: f is imposed and θf is searched, the angle whose truncated matrix best keeps the first moment, (χ1 - f)/(1 - f), among those leaving a non-negative plateau (Iwabuchi and Suzuki, 2009);

  • trunc_frac and th_f: both are imposed, the plateau follows, and is in general not continuous with the phase matrix at θf;

  • th_f alone (trunc_frac=None): the plateau is the value of the phase matrix at θf, which is cut flat below that angle, and f follows. It is the fraction of the scattering above that level within θf.

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)

Cut the phase matrix flat below 8 degrees, the fraction following:

>>> ds = gt_phase_approx(phase, theta, trunc_frac=None, th_f=8.0)
>>> round(float(ds['f']), 4)
0.0871