Scattering Module Methods & Types

This page groups the most commonly used APIs in a practical order.

Theory Mapping (Quick)

Reference: Sanghavi (2014).

• compute_aerosol_optical_properties (NAI2): Eq. (1) + Fourier framework around Eq. (17)

• compute_aerosol_optical_properties (PCW): Eq. (22) -> Eq. (24)

• reconstruct_phase: Greek/Fourier reconstruction around Eq. (17)

• phase_function, compute_aerosol_XS, compute_ref_aerosol_extinction: Eq. (1)-based cross-sections

For the expanded mapping table and implementation notes, see the Scattering overview.

High-level Workflow

1) Define model inputs

Use make_mie_model to combine aerosol microphysics, wavelength, polarization, truncation, and quadrature settings into a MieModel.

2) Compute optical properties

Use compute_aerosol_optical_properties to produce RT-facing aerosol optical properties: Fourier/Greek coefficients, single-scattering albedo, extinction, and truncation information.

For analytic test or parameterized aerosols, use HenyeyGreensteinPhaseFunction or SyntheticPolarizedHenyeyGreensteinPhaseFunction with analytic_aerosol_optics. This produces the same AerosolOptics container as the Mie path and therefore feeds the normal CoreRT and StandaloneSS layer optics.

3) Reconstruct phase matrix elements

vSmartMOM.Scattering.reconstruct_phase Function

reconstruct_phase(greek_coefs, μ; returnLeg = false)

Reconstruct angle-space scattering-matrix elements from Greek coefficients.

Reference: Sanghavi (2014), Fourier/Greek framework around Eq. (17).

f₁₁ represents the scalar phase function and is normalized as:

Using Legendre basis matrices computed at μ, this function evaluates:

Arguments

• greek_coefs: GreekCoefs coefficients.

• μ: cosine of scattering angles where the matrix should be reconstructed.

• returnLeg: if true, also return (P, P²).

Returns

• ScatteringMatrix when returnLeg=false.

• (ScatteringMatrix, P, P²) when returnLeg=true.

source

$(FUNCTIONNAME)(greek_coefs, μ; returnLeg = false)

Returns the reconstructed elements of the 4x4 scattering matrix at positions f₁₁, f₁₂, f₂₂, f₃₃, f₃₄, f₄₄ from the greek coefficients

f₁₁ represents the phase function p for the Intensity (first Stokes Vector element) and is normalized as follows:

• greek_coefs greek coefficients (Domke Type)

• returnLeg if false (default), just return f₁₁, f₁₂, f₂₂, f₃₃, f₃₄, f₄₄, if true,

• return f₁₁, f₁₂, f₂₂, f₃₃, f₃₄, f₄₄, P, P² (i.e. also the two legendre polynomials as matrices)

source

Convenience Computations

These are useful if you need cross-sections or scalar phase-function outputs without running the full RT-facing workflow.

vSmartMOM.Scattering.phase_function Function

phase_function(aerosol::Aerosol, λ, r_max, nquad_radius)
    -> (μ, w_μ, p11, C_ext, C_sca, g)

Compute scalar phase-function output for a size-distributed aerosol.

The returned p11(μ) is normalized by the bulk scattering cross-section and satisfies:

Asymmetry factor:

Reference: Sanghavi (2014), Mie-amplitude/cross-section setup from Eq. (1), with NAI-style angular integration discussed in Secs. 3-4.

source

phase_function(r::FT, λ::FT, nᵣ::FT, nᵢ::FT) where {FT<:AbstractFloat}
    -> (μ, w_μ, p11, C_ext, C_sca, g)

Monodisperse version of phase_function, for a single radius r. Returns the same tuple as the size-distribution overload.

source

vSmartMOM.Scattering.compute_aerosol_XS Function

compute_aerosol_XS(aerosol::Aerosol, λ, r_max, nquad_radius)
    -> (XS_ext, XS_sca, Cext_eff, Csca_eff)

Compute bulk extinction/scattering cross-sections for a size-distributed aerosol without reconstructing phase matrices.

Returns

• XS_ext: bulk extinction cross-section

• XS_sca: bulk scattering cross-section

• Cext_eff: area-normalized extinction

• Csca_eff: area-normalized scattering

with

Reference: Sanghavi (2014), Eq. (1) for particle-level C_ext/C_sca.

source

vSmartMOM.Scattering.compute_ref_aerosol_extinction Function

compute_ref_aerosol_extinction(model::MieModel{<:NAI2,FT}, FT_out::Type) -> Real

Compute only the bulk extinction cross-section for the aerosol model:

where is evaluated from the Mie series and is represented with quadrature over [0, r_max].

The second argument FT_out sets the return type. It is supplied by the caller and must be passed explicitly — there is no default. The internal cross-section computation always runs in Float64 for plain floats (same numerical stability rationale as compute_aerosol_optical_properties).

This helper avoids phase-function and Greek-coefficient reconstruction.

Reference: Sanghavi (2014), Eq. (1) for C_ext(r).

source

Analytic Phase Functions

Analytic phase-function aerosols are lightweight scattering sources for idealized tests, sensitivity experiments, and StandaloneSS validation. They are not a separate RT implementation: each analytic source is projected into GreekCoefs and then consumed by the same CoreRT optical-property machinery as Mie-derived aerosols.

vSmartMOM.Scattering.AbstractAnalyticPhaseFunction Type

AbstractAnalyticPhaseFunction

Analytic phase/scattering matrix source that can be converted to Greek coefficients and then used by the standard MOM optical-property path.

source

vSmartMOM.Scattering.HenyeyGreensteinPhaseFunction Type

HenyeyGreensteinPhaseFunction(g)

Scalar Henyey-Greenstein phase function, (1 - g^2) / (1 + g^2 - 2g cosΘ)^(3/2), normalized so its sphere average is (1 - g^2) / (1 + g^2 - 2g cosΘ)^(3/2), normalized so its sphere average is one.

source

vSmartMOM.Scattering.SyntheticPolarizedHenyeyGreensteinPhaseFunction Type

SyntheticPolarizedHenyeyGreensteinPhaseFunction(; g, polarization_fraction)

Diagnostic polarizing Henyey-Greenstein-like scattering matrix. The f11 element is standard Henyey-Greenstein; f12/f11 follows the bounded toy law polarization_fraction * (1 - cosΘ^2) / (1 + cosΘ^2). This is intended for tests and sensitivity experiments, not as a Mie substitute.

source

vSmartMOM.Scattering.greek_coefficients Function

greek_coefficients(phase; l_max=64, nquad=max(2l_max+1, 64))

Project an analytic phase/scattering matrix into Greek coefficients so it can enter the same CoreRT MOM path as Mie-derived aerosol optics.

source

vSmartMOM.Scattering.analytic_aerosol_optics Function

analytic_aerosol_optics(phase; single_scattering_albedo=1, extinction_cross_section=1, l_max=64)

Create an AerosolOptics object from an analytic phase/scattering matrix. The returned object is directly consumable by the existing CoreRT aerosol mixing and Fourier-moment code.

source

vSmartMOM.Scattering.phase_matrix_first_column Function

phase_matrix_first_column(greek, μ₀, μv, Δϕ, Val(N))

Evaluate the first column of the scattering phase matrix for an unpolarized incident beam at one plane-parallel sun-view geometry. μ₀ and μv are positive cosines and Δϕ is the vSmartMOM relative azimuth in radians.

source

phase_matrix_first_column evaluates the single-scatter phase-matrix column needed for an unpolarized direct solar beam at one exact sun-view geometry. It is the shared hook used by StandaloneSS vector paths for the sun-to-atmosphere-to-sensor term.

Wigner Utilities (PCW)

vSmartMOM.Scattering.compute_wigner_values Function

compute_wigner_values(m_max::Integer, n_max::Integer, l_max::Integer)

Compute the Wigner 3j values for all (m, n, l) combinations up to m/n/l max, for (m1, m2, m3) = (-1, 1, 0) (wigner_A) and (-1, -1, 2) (wigner_B)

source

compute_wigner_values(N_max)

Shorthand for compute_wigner_values(2N_max + 1, N_max + 1, 2N_max + 1)

source

vSmartMOM.Scattering.save_wigner_values Function

save_wigner_values(filepath, wigner_A, wigner_B)

Save the Wigner A and Wigner B matrices at the given filepath

source

vSmartMOM.Scattering.load_wigner_values Function

load_wigner_values(filename)

Load the Wigner A and Wigner B matrices from the given filepath

source

Types

Core abstract interfaces

vSmartMOM.Scattering.AbstractAerosolType Type

type AbstractAerosolType

Abstract aerosol type

source

vSmartMOM.Scattering.AbstractFourierDecompositionType Type

type AbstractFourierDecompositionType

Abstract aerosol Fourier Decomposition computation type (NAI2 and PCW)

source

vSmartMOM.Scattering.AbstractPolarizationType Type

type AbstractPolarizationType

Abstract Polarization type

source

vSmartMOM.Scattering.AbstractTruncationType Type

AbstractTruncationType

Abstract supertype for phase-function truncation methods. All concrete methods are dispatched through truncate_phase and supply l_max(t) (the per-band Legendre cutoff that the RT pipeline allocates for). Subtypes:

• NoTruncation — identity. Use when the phase function has no sharp forward peak (canopy, isotropic scattering, smooth Rayleigh).

• δBGE — δ-BGE-fit (Sanghavi & Stephens 2015, JQSRT 159 §3); recommended for hyperspectral retrievals.

The atmospheric Δ_angle (forward exclusion half-angle) lives inside the truncation type that needs it, not as a free parameter on CoreRT.vSmartMOM_Parameters — different methods have different hyper-parameters and NoTruncation has none.

source

Aerosol and model types

vSmartMOM.Scattering.MieModel Type

MieModel{FDT<:AbstractFourierDecompositionType, FT, ARCH}

Configuration for a Lorenz–Mie scattering computation. Specifies the aerosol (size distribution + refractive index), wavelength, polarization type, truncation strategy, integration parameters, and the compute architecture. The computation_type selects between NAI-2 (Siewert) and PCW (Domke) Fourier decomposition algorithms.

Pre-computed Wigner symbol tables (wigner_A, wigner_B) can be supplied for PCW; they default to trivial 1×1×1 placeholders (of element type FT) when unused (NAI2 path).

FT semantics (three orthogonal precision axes)

FT is the output float type of the returned Greek coefficients and optical scalars. It is carried by λ, r_max, and aerosol (which must all share the same FT) so that the entire MieModel is FT-consistent. This is independent of two other precision choices:

1. FT (output type) — what the user consumes downstream in the RT pipeline.

2. The internal Dₙ continued-fraction recursion: on the CPU path the recursion is always promoted to Float64 for numerical stability regardless of FT (see _mie_dn_recursion! in mie_helper_functions.jl); Dual inputs keep native arithmetic for AD compatibility.

3. precision_policy (GPU only) — NativeFloat64 (default on CUDA) runs the GPU Dₙ recursion in hardware FP64; DSEmulated uses Float32 double-single pairs (for Metal/L40S). This axis is inert on the CPU path.

Architecture dispatch

architecture::ARCH is either Architectures.CPU() (default) or Architectures.GPU(). compute_aerosol_optical_properties(mie_model) dispatches on it: NAI2+CPU → analytic CPU path; NAI2+GPU → the KernelAbstractions GPU pipeline; PCW+GPU → CPU fallback (no GPU PCW kernel).

Fields

• computation_type

• aerosol: Aerosol microphysics; element type must match the model's FT

• λ: Wavelength [μm]; must have the same float type as r_max

• polarization_type

• truncation_type

• r_max: Maximum radius [μm]

• nquad_radius: Number of quadrature points for integration over size distribution

• wigner_A: Precomputed Wigner ν=0 table (PCW only; trivial 1×1×1 placeholder for NAI2)

• wigner_B: Precomputed Wigner ν=2 table (PCW only; trivial 1×1×1 placeholder for NAI2)

• architecture: Compute architecture (CPU() or GPU()); selects CPU vs GPU Mie path

• precision_policy: GPU precision policy (NativeFloat64/DSEmulated); nothing = auto-select on GPU, ignored on CPU

source

Aerosol defines a size distribution and complex refractive index. See the Library for its canonical docstring.

Fourier decomposition types

The supported Fourier decomposition families are NAI2 and PCW.

Polarization types

vSmartMOM.Scattering.Stokes_IQUV Type

struct Stokes_IQUV{FT<:AbstractFloat}

A struct which defines full Stokes Vector ([I,Q,U,V]) RT code

Fields

• n: Number of Stokes components (int)

• D: Vector of length n for ... (see eq in Sanghavi )

• I₀: Incoming Stokes vector for scalar only

source

vSmartMOM.Scattering.Stokes_IQU Type

struct Stokes_IQU{FT<:AbstractFloat}

A struct which defines Stokes Vector ([I,Q,U]) RT code

Fields

• n: Number of Stokes components (int)

• D: Vector of length n for ... (see eq in Sanghavi )

• I₀: Incoming Stokes vector for scalar only

source

vSmartMOM.Scattering.Stokes_IQ Type

struct Stokes_IQ{FT<:AbstractFloat}

A struct which defines Stokes Vector ([I,Q]) RT code.

Fields

• n: Number of Stokes components (int)

• D: Vector of length n for ... (see eq in Sanghavi )

• I₀: Incoming Stokes vector for scalar only

source

vSmartMOM.Scattering.Stokes_I Type

struct Stokes_I{FT<:AbstractFloat}

A struct which define scalar I only RT code

Fields

• n: Number of Stokes components (int)

• D: Vector of length n for ... (see eq in Sanghavi )

• I₀: Incoming Stokes vector for scalar only

source

Truncation type

vSmartMOM.Scattering.NoTruncation Type

NoTruncation(; l_max=typemax(Int))

Identity truncation — phase functions are passed through unchanged.

This is the correct choice for radiative transfer through media whose phase function has no sharp forward peak: canopy bi-Lambertian scattering (the f_tr → 0 limit of Sanghavi & Stephens 2015 Eq. 8 is exactly the identity), isotropic scattering, and smooth Rayleigh. For Mie aerosol or ice-cloud forward peaks use δBGE instead.

source

vSmartMOM.Scattering.δBGE Type

δBGE{FT}(l_max, Δ_angle)

δ-BGE-fit truncation, vector form (Sanghavi & Stephens 2015, JQSRT 159, §3 — extension of Hu et al. 2000 to vector RT). Fits truncated Legendre coefficients outside the forward exclusion cone of half-angle Δ_angle and renormalises by the retained scattering fraction   .

Recommended over plain δ-m for hyperspectral retrievals because δ-m has known DSE and PTE errors near exact backscatter (Sanghavi & Stephens 2015 §2.4).

Fields

• l_max: Truncation length for Legendre terms

• Δ_angle: Exclusion angle for forward peak (in fitting procedure) [degrees]

source

Output types

GreekCoefs stores the Fourier/Greek coefficient representation consumed by the RT kernels, and AerosolOptics groups those coefficients with extinction, single-scattering albedo, and truncation outputs.

Linearized output types

vSmartMOM.Scattering.linGreekCoefs Type

struct GreekCoefs{FT}

A struct which holds all Greek coefficient lists (over l) in one object. See eq 16 in Sanghavi 2014 for details.

Fields

• α̇: Greek matrix coefficient α, is in B[2,2]

• β̇: Greek matrix coefficient β, is in B[1,1] (only important one for scalar!)

• γ̇: Greek matrix coefficient γ, is in B[2,1],B[1,2]

• δ̇: Greek matrix coefficient δ, is in B[4,4]

• ϵ̇: Greek matrix coefficient ϵ, is in B[3,4] and - in B[4,3]

• ζ̇: Greek matrix coefficient ζ, is in B[3,3]

source

vSmartMOM.Scattering.linAerosolOptics Type

struct AerosolOptics

A struct which holds all computed aerosol optics

Fields

• lin_greek_coefs: Greek matrix

• ω̃̇: Single Scattering Albedo

• k̇: Extinction cross-section

• ḟᵗ: Truncation factor

source