API

A general T-Matrix $T_{m n m^{\prime} n^{\prime}}^{k l}$ stored in a 6-dimensional array, in the order $(m, n, m^{\prime}, n^{\prime}, k, l)$.

A Chebyshev scatterer defined by

\[r(\theta, \phi)=r_0(1+\varepsilon T_n(\cos\theta))\]

where $T_n(\cos\theta)=\cos n\theta$.

Attributes:

• r₀: the radius of the base sphere.
• ε: the deformation parameter, which satisfies $-1\le\varepsilon<1$.
• n: the degree of the Chebyshev polynomial.
• m: the relative complex refractive index.

A cylindrical scatterer.

Attributes:

• r: the radius of the cylinder base.
• h: the height of the cylinder.
• m: the relative complex refractive index.

According to Eq. (5.42) – Eq. (5.44) in Mishchenko et al. (2002), the T-Matrix for a Mie particle can be written as:

\[\begin{array}{l} T_{m n m^{\prime} n^{\prime}}^{12}(P) \equiv 0, \quad T_{m n m^{\prime} n^{\prime}}^{21}(P) \equiv 0, \\ T_{m n m^{\prime} n^{\prime}}^{11}(P)=-\delta_{m m^{\prime}} \delta_{n n^{\prime}} b_n, \\ T_{m n m^{\prime} n^{\prime}}^{22}(P)=-\delta_{m m^{\prime}} \delta_{n n^{\prime}} a_n . \end{array}\]

MieTransitionMatrix{CT, N}(x::Real, m::Number)

Generate the T-Matrix from the Mie coefficients of a homogeneous sphere.

MieTransitionMatrix{CT, N}(x_core::Real, x_mantle::Real, m_core::Number, m_mantle::Number)

Generate the T-Matrix from the Mie coefficients of a coated sphere.

This struct provides the T-Matrix API for a Mie particle.

Iterator for the order-degree pairs of the given maximum order nₘₐₓ.

Example of nₘₐₓ=2:

julia> collect(OrderDegreeIterator(2))
8-element Vector{Tuple{Int64, Int64}}:
 (1, -1)
 (1, 0)
 (1, 1)
 (2, -2)
 (2, -1)
 (2, 0)
 (2, 1)
 (2, 2)

Prism{N, T, CT}(a, h, m)

A prism scatterer. The number of base edges is represented by the type parameter N. The prism is assumed to be aligned with the z-axis, and one of The lateral edges is assumed to have φ=0.

Attributes:

• a: the length of the prism base.
• h: the height of the prism.
• m: the relative complex refractive index.

RandomOrientationTransitionMatrix(𝐓::AbstractTransitionMatrix{CT, N}) where {CT, N}

Calculate the random-orientation T-Matrix according to Eq. (5.96) in Mishchenko et al. (2002).

\[\left\langle T_{m n m^{\prime} n^{\prime}}^{k l}(L)\right\rangle=\frac{\delta_{n n^{\prime}} \delta_{m m^{\prime}}}{2 n+1} \sum_{m_1=-n}^n T_{m_1 n m_1 n}^{k l}(P), \quad k, l=1,2\]

A spheroidal scatterer.

Attributes:

• a: the length of the semi-major axis.
• c: the length of the semi-minor axis.
• m: the relative complex refractive index.

Concrete type for a general T-Matrix.

absorption_cross_section(𝐓::AbstractTransitionMatrix, λ=2π)

Calculate the absorption cross section from the given T-Matrix.

albedo(𝐓::AbstractTransitionMatrix)

Calculate the single scattering albedo from the given T-Matrix.

amplitude_matrix(𝐓::AbstractTransitionMatrix{CT, N}, ϑᵢ, φᵢ, ϑₛ, φₛ; λ=2π)

Calculate the amplitude matrix of the given T-Matrix 𝐓 at the given incidence and scattering angles.

Parameters:

• 𝐓: the T-Matrix of the scatterer.
• ϑᵢ: the incidence zenith angle in radians.
• φᵢ: the incidence azimuthal angle in radians.
• ϑₛ: the scattering zenith angle in radians.
• φₛ: the scattering azimuthal angle in radians.
• λ: the wavelength of the incident wave in the host medium. Default to 2π.

For a general T-Matrix, Eq. (5.11) – Eq. (5.17) in Mishchenko et al. (2002) is used as a fallback.

\[\begin{array}{l} S_{11}\left(\hat{\mathbf{n}}^{\text {sca }}, \hat{\mathbf{n}}^{\text {inc }}\right)=\frac{1}{k_1} \sum_{n=1}^{\infty} \sum_{n^{\prime}=1}^{\infty} \sum_{m=-n}^n \sum_{m^{\prime}=-n^{\prime}}^{n^{\prime}} \alpha_{m n m^{\prime} n^{\prime}}\left[T_{m n m^{\prime} n^{\prime}}^{11} \pi_{m n}\left(\vartheta^{\text {sca }}\right) \pi_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right)\right. \\ +T_{m n m^{\prime} n^{\prime}}^{21} \tau_{m n}\left(\vartheta^{\text {sca }}\right) \pi_{m^{\prime} n^{\prime}}\left(\vartheta^{\mathrm{inc}}\right)+T_{m n m^{\prime} n^{\prime}}^{12} \pi_{m n}\left(\vartheta^{\text {sca }}\right) \tau_{m^{\prime} n^{\prime}}\left(\vartheta^{\mathrm{inc}}\right) \\ \left.+T_{m n m^{\prime} n^2}^{22} \tau_{m n}\left(\vartheta^{\text {sca }}\right) \tau_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right)\right] \exp \left[\mathrm{i}\left(m \varphi^{\text {sca }}-m^{\prime} \varphi^{\text {inc }}\right)\right] \text {, } \\ S_{12}\left(\hat{\mathbf{n}}^{\mathrm{sca}}, \hat{\mathbf{n}}^{\mathrm{inc}}\right)=\frac{1}{\mathrm{i} k_1} \sum_{n=1}^{\infty} \sum_{n^{\prime}=1}^{\infty} \sum_{m=-n}^n \sum_{m^{\prime}=-n^{\prime}}^{n^{\prime}} \alpha_{m n m^{\prime} n^{\prime}}\left[T_{m n m^{\prime} n^{\prime}}^{11} \pi_{m n}\left(\vartheta^{\mathrm{sca}}\right) \tau_{m^{\prime} n^{\prime}}\left(\vartheta^{\mathrm{inc}}\right)\right. \\ +T_{m n m^{\prime} n^{\prime}}^{21} \tau_{m n}\left(\vartheta^{\text {sca }}\right) \tau_{m^{\prime} n^{\prime}}\left(\vartheta^{\mathrm{inc}}\right)+T_{m n m^{\prime} n^{\prime}}^{12} \pi_{m n}\left(\vartheta^{\text {sca }}\right) \pi_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right) \\ \left.+T_{m n m^{\prime} n^{\prime}}^{22} \tau_{m n}\left(\vartheta^{\text {sca }}\right) \pi_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right)\right] \exp \left[\mathrm{i}\left(m \varphi^{\text {sca }}-m^{\prime} \varphi^{\text {inc }}\right)\right] \text {, } \\ S_{21}\left(\hat{\mathbf{n}}^{\mathrm{sca}}, \hat{\mathbf{n}}^{\mathrm{inc}}\right)=\frac{\mathrm{i}}{k_1} \sum_{n=1}^{\infty} \sum_{n^{\prime}=1}^{\infty} \sum_{m=-n}^n \sum_{m^{\prime}=-n^{\prime}}^{n^{\prime}} \alpha_{m n m^{\prime} n^{\prime}}\left[T_{m n m^{\prime} n^{\prime}}^{11} \tau_{m n}\left(\vartheta^{\mathrm{sca}}\right) \pi_{m^{\prime} n^{\prime}}\left(\vartheta^{\mathrm{inc}}\right)\right. \\ +T_{m n m^{\prime} n^{\prime}}^{21} \pi_{m n}\left(\vartheta^{\text {sca }}\right) \pi_{m^{\prime} n^{\prime}}\left(\vartheta^{\mathrm{inc}}\right)+T_{m n m^{\prime} n^{\prime}}^{12} \tau_{m n}\left(\vartheta^{\text {sca }}\right) \tau_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right) \\ \left.+T_{m n m^{\prime} n^{\prime}}^{22} \pi_{m n}\left(\vartheta^{\text {sca }}\right) \tau_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right)\right] \exp \left[\mathrm{i}\left(m \varphi^{\text {sca }}-m^{\prime} \varphi^{\text {inc }}\right)\right] \text {, } \\ S_{22}\left(\hat{\mathbf{n}}^{\text {sca }}, \hat{\mathbf{n}}^{\mathrm{inc}}\right)=\frac{1}{k_1} \sum_{n=1}^{\infty} \sum_{n^{\prime}=1}^{\infty} \sum_{m=-n}^n \sum_{m^{\prime}=-n^{\prime}}^{n^{\prime}} \alpha_{m n m^{\prime} n^{\prime}}\left[T_{m n n^{\prime} n^{\prime}}^{11} \tau_{m n}\left(\vartheta^{\text {sca }}\right) \tau_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right)\right. \\ +T_{m n m^{\prime} n^{\prime}}^{21} \pi_{m n}\left(\vartheta^{\text {sca }}\right) \tau_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right)+T_{m n m^{\prime} n^{12}}^{12} \tau_{m n}\left(\vartheta^{\text {sca }}\right) \pi_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right) \\ \left.+T_{m n m^{\prime} n^{\prime}}^{22} \pi_{m n}\left(\vartheta^{\text {sca }}\right) \pi_{m^{\prime} n^{\prime}}\left(\vartheta^{\text {inc }}\right)\right] \exp \left[\mathrm{i}\left(m \varphi^{\text {sca }}-m^{\prime} \varphi^{\text {inc }}\right)\right], \\ \end{array}\]

Where

\[\begin{array}{l} \alpha_{m n m^{\prime} n^{\prime}}=\mathrm{i}^{n^{\prime}-n-1}(-1)^{m+m^{\prime}}\left[\frac{(2 n+1)\left(2 n^{\prime}+1\right)}{n(n+1) n^{\prime}\left(n^{\prime}+1\right)}\right]^{1 / 2}, \\ \pi_{m n}(\vartheta)=\frac{m d_{0 m}^n(\vartheta)}{\sin \vartheta}, \quad \pi_{-m n}(\vartheta)=(-1)^{m+1} \pi_{m n}(\vartheta), \\ \tau_{m n}(\vartheta)=\frac{\mathrm{d} d_{0 m}^n(\vartheta)}{\mathrm{d} \vartheta}, \quad \tau_{-m n}(\vartheta)=(-1)^m \tau_{m n}(\vartheta) \end{array}\]

amplitude_matrix(axi::AxisymmetricTransitionMatrix{CT, N, V, T}, ϑᵢ, φᵢ, ϑₛ, φₛ;
                          λ = 2π,
                          rot::Union{Nothing, Rotation{3}} = nothing) where {CT, N, V, T}

Calculate the amplitude matrix of an axisymmetric scatterer.

Parameters:

• axi: the T-Matrix of the scatterer.
• ϑᵢ: the zenith angle of the incident wave.
• φᵢ: the azimuth angle of the incident wave.
• ϑₛ: the zenith angle of the scattered wave.
• φₛ: the azimuth angle of the scattered wave.
• λ: the wavelength of the incident wave in the host medium. Default to 2π.
• rot: the rotation of the scatterer.

asymmetry_parameter(𝐓, λ)

Calculate the asymmetry parameter from the given transition matrix, using Eq. (4.92) in Mishchenko et al. (2002):

\[\langle\cos\Theta\rangle=\frac{\alpha_1^1}{3}\]

bhcoat([T=Float64,], xᵢₙ, xₒᵤₜ, mᵢₙ, mₒᵤₜ; nₘₐₓ, tolerance = 1e-8)

Inputs:

• T: Type used for calculation. All real numbers will be stored as T, while complex numbers will be stored as C = complex(T).
• xᵢₙ: Size parameter of the inner sphere. Defined as $\frac{2\pi r}{\lambda}$
• xₒᵤₜ: Size parameter of the coated sphere. xₒᵤₜ >= xᵢₙ should hold.
• mᵢₙ: Refractive index of the inner sphere, relative to the host medium.
• mₒᵤₜ: Refractive index of the mantle, relative to the host medium.

Keyword arguments:

• nₘₐₓ: Maximum order of the Mie coefficients. Default to $\max(x_m + 4\sqrt{3}{x_m} + 2, \max(|m_c|, |m_m|)x_m)$.
• tolerance: Error tolerance. Default to 1e-8.

Outputs:

• a, b: Mie coefficients. Both are of type Vector{C}.

References:

• Bohren, C.F., Huffman, D.R., 1983. Absorption and scattering of light by small particles. John Wiley & Sons.

bhmie([T=Float64,], x, m; nₘₐₓ)

This is a simplified version of Bohren (1983)'s bhmie routine. Only the Mie coefficients are evaluated and returned.

Inputs:

• T: Type used for calculation. Real numbers will be stored as T, while complex numbers will be stored as C = complex(T).
• x: Size parameter of the sphere scatterer. Defined as $\frac{2\pi r}{\lambda}$
• m: Relative refractive index of the scatterer.

Keyword arguments:

• nₘₐₓ: Maximum order of the Mie coefficients. Default to $\max(x + 4\sqrt{3}{x} + 2, |m|x)$.

Outputs:

• a, b: Mie coefficients. Both are Vector{C} with nₘₐₓ elements.

References:

• Bohren, C.F., Huffman, D.R., 1983. Absorption and scattering of light by small particles. John Wiley & Sons.

expansion_coefficients(𝐓::AbstractTransitionMatrix{CT, N}, λ) where {CT, N}

Calculate the expansion coefficients from an arbitrary T-Matrix, using Eq. (24) – (74) in Bi et al. (2014).

Parameters:

• 𝐓: The precalculated T-Matrix of a scatterer.
• λ: The wavelength.

Keyword arguments:

• full: Whether to return the full expansion coefficients (β₃ to β₆). Default to false.

expansion_coefficients(𝐓::AxisymmetricTransitionMatrix{CT, N, V, T}, λ) where {CT, N, V, T}

Calculate the expansion coefficients from an axisymmetric T-Matrix. Translated from Mishchenko et al.'s Fortran code.

Parameters:

• 𝐓: The precalculated T-Matrix of a scatterer.
• λ: The wavelength.

extinction_cross_section(𝐓::AbstractTransitionMatrix{CT, N}, λ=2π) where {CT, N}

Calculate the extinction cross section per particle averaged over the uniform orientation distribution, according to Eq. (5.102) in Mishchenko et al. (2002).

\[\left\langle C_{\mathrm{ext}}\right\rangle=-\frac{2 \pi}{k_1^2} \operatorname{Re} \sum_{n=1}^{\infty} \sum_{m=-n}^n\left[T_{m n n n}^{11}(P)+T_{m n m n}^{22}(P)\right]\]

Parameters:

• 𝐓: the T-Matrix of the scatterer.
• λ: the wavelength of the incident wave in the host medium. Default to 2π.

extinction_cross_section(axi::AxisymmetricTransitionMatrix{CT, N}, λ=2π) where {CT, N}

Calculate the extinction cross section per particle averaged over the uniform orientation distribution, according to Eq. (5.107) in Mishchenko et al. (2002).

\[\left\langle C_{\text {ext }}\right\rangle=-\frac{2 \pi}{k_1^2} \operatorname{Re} \sum_{n=1}^{\infty} \sum_{m=0}^n\left(2-\delta_{m 0}\right)\left[T_{m n m n}^{11}(P)+T_{m n m n}^{22}(P)\right]\]

Parameters:

• 𝐓: the T-Matrix of the scatterer.
• λ: the wavelength of the incident wave in the host medium. Default to 2π.

factorial([T=Float64,], n)

Calculate factorials $n!$. For $n\le20$, the standard Base.factorial is used. For $n>20$, Arblib.gamma! is used instead.

gausslegendre([T=Float64,], n)

Calculate the n-point Gauss-Legendre quadrature nodes and weights.

• For Float64, we use the $\mathcal{O}(n)$ implementation from FastGaussQuadrature.jl.
• For other types, we use the arbitrary precision implementation from Arblib.jl, then convert the results to the desired type.

gaussquad(c::Chebyshev{T}, ngauss) where {T}

Evaluate the quadrature points, weights and the corresponding radius and radius derivative (to $\vartheta$) for a Chebyshev particle.

Returns: (x, w, r, r′)

• x: the quadrature points.
• w: the quadrature weights.
• r: the radius at each quadrature point.
• r′: the radius derivative at each quadrature point.

gaussquad(c::Cylinder{T}, ngauss) where {T}

Evaluate the quadrature points, weights and the corresponding radius and radius derivative (to $\vartheta$) for a cylinder.

Returns: (x, w, r, r′)

• x: the quadrature points.
• w: the quadrature weights.
• r: the radius at each quadrature point.
• r′: the radius derivative at each quadrature point.

gaussquad(s::Spheroid{T}, ngauss) where {T}

Evaluate the quadrature points, weights and the corresponding radius and radius derivative (to $\vartheta$) for a spheroid.

Returns: (x, w, r, r′)

• x: the quadrature points.
• w: the quadrature weights.
• r: the radius at each quadrature point.
• r′: the radius derivative at each quadrature point.

Get the maximum order of a T-Matrix.

orientation_average(mie::MieTransitionMatrix, _pₒ; _kwargs...)

The T-Matrix of a Mie scatterer is invariant under rotation. Therefore, the original T-Matrix will be returned.

orientation_average(ro::RandomOrientationTransitionMatrix, _pₒ; _kwargs...)

The random-orientation T-Matrix is invariant under rotation. Therefore, the original T-Matrix will be returned.

orientation_average(𝐓::AbstractTransitionMatrix{CT, N}, pₒ; Nα = 10, Nβ = 10, Nγ = 10) where {CT, N}

Calculate the orientation average of a transition matrix using numerical integration, given the orientation distribution function $p_o(\alpha,\beta,\gamma)$.

\[\langle T_{m n m^{\prime} n^{\prime}}^{p p^{\prime}}(L)\rangle = \int_0^{2\pi}\mathrm{d}\alpha\int_0^{\pi}\mathrm{d}\beta\sin\beta\int_0^{2\pi}\mathrm{d}\gamma p_o(\alpha,\beta,\gamma) T_{m n m^{\prime} n^{\prime}}^{p p^{\prime}}(L; \alpha,\beta,\gamma)\]

Parameters:

• 𝐓: the T-Matrix to be orientation averaged.
• pₒ: the orientation distribution function. Note that the $\sin\beta$ part is already included.
• Nα: the number of points used in the numerical integration of $\alpha$. Default to 10.
• Nβ: the number of points used in the numerical integration of $\beta$. Default to 10.
• Nγ: the number of points used in the numerical integration of $\gamma$. Default to 10.

phase_matrix(𝐒::AbstractMatrix)

Calculate the phase matrix 𝐙 from the amplitude matrix 𝐒, according to Eq. (2.106) – Eq. (2.121) in Mishchenko et al. (2002).

pi_func([T=Float64,], m::Integer, n::Integer, ϑ::Number; d=nothing)

Calculate

\[\pi_{m n}(\vartheta)=\frac{m d_{0 m}^n(\vartheta)}{\sin \vartheta}\]

• If d is given, it is used as the value of $d_{0 m}^n(\vartheta)$.

ricattibesselj!(ψₙ, ψₙ′, z, nₘₐₓ, nₑₓₜᵣₐ, x)

Parameters:

• ψ: output array for $\psi_n(x)$.
• ψ′: output array for $\psi^{\prime}_n(x)$.
• z: auxiliary array for downward recursion.
• nₘₐₓ: maximum order of $\psi_n(x)$.
• nₑₓₜᵣₐ: extra terms for downward recursion of $z$.
• x: argument.

In-place version of ricattibesselj.

ricattibesselj(nₘₐₓ::Integer, nₑₓₜᵣₐ::Integer, x)

Calculate Ricatti-Bessel function of the first kind, $\psi_n(x)$, and its derivative $\psi^{\prime}_n(x)$ for $1\le n\le n_{\max}$.

$\psi_n(x)$ is defined as

\[\psi_n(x) = xj_n(x)\]

where $j_n(x)$ is the Bessel function of the first kind.

Parameters:

• nₘₐₓ: maximum order of $\psi_n(x)$.
• nₑₓₜᵣₐ: extra terms for downward recursion of $z$.
• x: argument.

Returns: (ψ, ψ′)

• ψ: array of $\psi_n(x)$.
• ψ′: array of $\psi^{\prime}_n(x)$.

ricattibessely!(χ, χ′, nₘₐₓ, x)

Parameters:

• χ: output array for $\chi_n(x)$.
• χ′: output array for $\chi^{\prime}_n(x)$.
• nₘₐₓ: maximum order of $\chi_n(x)$.
• x: argument.

In-place version of ricattibessely.

ricattibessely(nₘₐₓ::Integer, x)

Calculate Ricatti-Bessel function of the second kind, $\chi_n(x)$, and its derivative $\chi^{\prime}_n(x)$ for $1\le n\le n_{\max}$.

$\chi_n(x)$ is defined as

\[\chi_n(x) = xy_n(x)\]

where $y_n(x)$ is the Bessel function of the second kind.

Parameters:

• nₘₐₓ: maximum order of $\chi_n(x)$.
• x: argument.

Returns: (χ, χ′)

• χ: Array of $\chi_n(x)$.
• χ′: Array of $\chi^{\prime}_n(x)$.

rotate(mie::MieTransitionMatrix, ::Rotation{3})

The T-Matrix of a Mie scatterer is invariant under rotation. Therefore, the original T-Matrix will be returned.

rotate(𝐓::AbstractTransitionMatrix{CT, N}, rot::Rotation{3})

Rotate the given T-Matrix 𝐓 by the Euler angle rot and generate a new T-Matrix.

For a general T-Matrix, Eq. (5.29) in Mishchenko et al. (2002) is used as a fallback. A TransitionMatrix will be returned, which is the most general yet concrete type.

\[T_{m n m^{\prime} n^{\prime}}^{p p′}(L ; \alpha, \beta, \gamma)=\sum_{m_1=-n}^n \sum_{m_2=-n^{\prime}}^{n^{\prime}} D_{m m_1}^n(\alpha, \beta, \gamma) T_{m_1 n m_2 n^{\prime}}^{p p′}(P) D_{m_2 m^{\prime}}^{n^{\prime}}(-\gamma,-\beta,-\alpha)\quad p,p′=1,2\]

rotate(ro::RandomOrientationTransitionMatrix{CT, N, V}, ::Rotation{3}) where {CT, N, V}

The random-orientation T-Matrix is invariant under rotation. Therefore, the original T-Matrix will be returned.

scattering_cross_section(𝐓::AbstractTransitionMatrix{CT, N}, λ=2π) where {CT, N}

Calculate the scattering cross section per particle averaged over the uniform orientation distribution, according to Eq. (5.140) in Mishchenko et al. (2002).

\[\left\langle C_{\mathrm{sca}}\right\rangle=\frac{2 \pi}{k_1^2} \sum_{n=1}^{\infty} \sum_{m=-n}^n \sum_{n^{\prime}=1}^{\infty} \sum_{m^{\prime}=-n^{\prime}}^{n^{\prime}} \sum_{k=1}^2 \sum_{l=1}^2\left|T_{m n m^{\prime} n^{\prime}}^{k l}(P)\right|^2\]

Parameters:

• 𝐓: the T-Matrix of the scatterer.
• λ: the wavelength of the incident wave in the host medium. Default to 2π.

scattering_cross_section(axi::AxisymmetricTransitionMatrix{CT, N}, λ=2π) where {CT, N}

Calculate the scattering cross section per particle averaged over the uniform orientation distribution, according to Eq. (5.141) in Mishchenko et al. (2002).

\[\left\langle C_{\text {sca }}\right\rangle=\frac{2 \pi}{k_1^2} \sum_{n=1}^{\infty} \sum_{n^{\prime}=1}^{\infty} \sum_{m=0}^{\min \left(n, n^{\prime}\right)} \sum_{k=1}^2 \sum_{l=1}^2\left(2-\delta_{m 0}\right)\left|T_{m n m n^{\prime}}^{k l}(P)\right|^2\]

Parameters:

• 𝐓: the T-Matrix of the scatterer.
• λ: the wavelength of the incident wave in the host medium. Default to 2π.

scattering_matrix(𝐓, λ, θs)

Calculate expansion coefficients first and then calculate scatterering matrix elements.

Parameters:

• 𝐓: The transition matrix.
• λ: The wavelength.
• θs: The scattering angles to be evaluated in degrees.

scattering_matrix(α₁, α₂, α₃, α₄, β₁, β₂, θs)

Calculate the scatterering matrix elements from the given expansion coefficients.

Parameters:

• α₁, α₂, α₃, α₄, β₁, β₂: The precalculated expansion coefficients.
• θs: The scattering angles to be evaluated in degrees.

scattering_matrix(α₁, α₂, α₃, α₄, β₁, β₂, β₃, β₄, β₅, β₆, θs)

Calculate all 10 independent scatterering matrix elements (F₁₁, F₁₂, F₁₃, F₁₄, F₂₂, F₂₃, F₂₄, F₃₃, F₃₄, F₄₄) from the given expansion coefficients.

The scattering matrix can be expressed as:

\[\mathbf{F}=\left[\begin{array}{cccc} F_{11} & F_{12} & F_{13} & F_{14} \\ F_{12} & F_{22} & F_{23} & F_{24} \\ -F_{13} & -F_{23} & F_{33} & F_{34} \\ F_{14} & F_{24} & -F_{34} & F_{44} \end{array}\right]\]

Parameters:

• α₁, α₂, α₃, α₄, β₁, β₂, β₃, β₄, β₅, β₆: The precalculated expansion coefficients.
• θs: The scattering angles to be evaluated in degrees.

tau_func([T=Float64,], m::Integer, n::Integer, ϑ::Number)

Calculate

\[\tau_{m n}(\vartheta)=\frac{\mathrm{d} d_{0 m}^n(\vartheta)}{\mathrm{d} \vartheta}\]

transition_matrix(s::AbstractAxisymmetricShape{T, CT}, λ, nₘₐₓ, Ng) where {T, CT}

Calculate the T-Matrix for a given scatterer and wavelengthg`.

Parameters:

• s: the axisymmetric scatterer.
• λ: the wavelength.
• nₘₐₓ: the maximum order of the T-Matrix.
• Ng: the number of Gauss-Legendre quadrature points to be used.

Returns:

• 𝐓: an AxisymmetricTransitionMatrix struct representing the T-Matrix.

transition_matrix(s::AbstractAxisymmetricShape{T, CT}, λ; ...) where {T, CT}

Main function for calculating the transition matrix of an axisymmetric shape.

Parameters:

• s: Axisymmetric shape
• λ: Wavelength

Keyword arguments:

• threshold: Convergence threshold, defaults to 0.0001
• ndgs: Number of discrete Gauss quadrature points per degree, defaults to 4
• routine_generator: Function that generates the convergence routine, defaults to routine_mishchenko
• nₛₜₐᵣₜ: The initial number of the truncation order, defaults to 0, and the actual value will be calculated automatically using the following formula:

\[n_{\text{start}} = \max(4, \lceil kr_{\max} + 4.05 \sqrt[3]{kr_{\max}} \rceil)\]

• Ngₛₜₐᵣₜ: The initial number of discrete Gauss quadrature points, defaults to nₛₜₐᵣₜ * ndgs
• nₘₐₓ_only: Only check convergence of nₘₐₓ, defaults to false, meaning that convergence of both nₘₐₓ and Ng will be checked
• full: Whether to calculate the whole transition matrix in each iteration, defaults to false, and only the m=m′=0 block will be calculated
• reuse: Whether to reuse the cache of the previous iteration, defaults to true
• maxiter: Maximum number of iterations, defaults to 20
• zerofn: Function that defines the type used for numerical integration, defaults to () -> zero(CT) where CT is defined by the shape

transition_matrix_iitm(s::AbstractAxisymmetricShape{T, CT}, λ, nₘₐₓ, Nr, Nϑ; rₘᵢₙ) where {T, CT}

Use IITM to calculate the T-Matrix for a given scatterer and wavelength.

Parameters:

• s: the axisymmetric scatterer.
• λ: the wavelength.
• nₘₐₓ: the maximum order of the T-Matrix.
• Nr: the number of radial quadrature points to be used.
• Nϑ: the number of zenithal quadrature points to be used.

Keyword arguments:

• rₘᵢₙ: the starting point of the radial quadrature. Default to rmin(s), which is the radius of the maximum inscribed sphere.

Returns:

• 𝐓: an AxisymmetricTransitionMatrix struct representing the T-Matrix.

transition_matrix_iitm(s::AbstractShape{T, CT}, λ, nₘₐₓ, Nr, Nϑ, Nφ; rₘᵢₙ) where {T, CT}

Use IITM to calculate the T-Matrix for a given scatterer and wavelength.

Parameters:

• s: the scatterer.
• λ: the wavelength.
• nₘₐₓ: the maximum order of the T-Matrix.
• Nr: the number of radial quadrature points to be used.
• Nϑ: the number of zenithal quadrature points to be used.
• Nφ: the number of azimuthal quadrature points to be used.

Keyword arguments:

• rₘᵢₙ: the starting point of the radial quadrature. Default to rmin(s), which is the radius of the maximum inscribed sphere.

Returns:

• 𝐓: an AxisymmetricTransitionMatrix struct representing the T-Matrix.

transition_matrix_iitm(s::AbstractNFoldShape{N, T, CT}, λ, nₘₐₓ, Nr, Nϑ, Nφ; rₘᵢₙ) where {T, CT}

Use IITM to calculate the T-Matrix for a given scatterer and wavelength.

Parameters:

• s: the scatterer.
• λ: the wavelength.
• nₘₐₓ: the maximum order of the T-Matrix.
• Nr: the number of radial quadrature points to be used.
• Nϑ: the number of zenithal quadrature points to be used.
• Nφ: the number of azimuthal quadrature points to be used.

Keyword arguments:

• rₘᵢₙ: the starting point of the radial quadrature. Default to rmin(s), which is the radius of the maximum inscribed sphere.

Returns:

• 𝐓: an AxisymmetricTransitionMatrix struct representing the T-Matrix.

transition_matrix_m(m, s::AbstractAxisymmetricShape{T, CT}, λ, nₘₐₓ, Ng) where {T, CT}

Calculate the m-th block of the T-Matrix for a given axisymmetric scatterer.

transition_matrix_m₀(s::AbstractAxisymmetricShape{T, CT}, λ, nₘₐₓ, Ng) where {T, CT}

Calculate the m=0 block of the T-Matrix for a given axisymmetric scatterer.

wigner_D(::Type{T}, m::Integer, m′::Integer, n::Integer, α::Number, β::Number, γ::Number) where {T}

Calculate the Wigner D-function $D^j_{mn}(\theta)$, which is defined as:

\[D_{m m^{\prime}}^{n}(\alpha, \beta, \gamma)=\mathrm{e}^{-\mathrm{i} m \alpha} d_{m m^{\prime}}^{n}(\beta) \mathrm{e}^{-\mathrm{i} m^{\prime} \gamma}\]

where

\[0 \leq \alpha<2 \pi, \quad 0 \leq \beta \leq \pi, \quad 0 \leq \gamma<2 \pi\]

wigner_D_recursion!(d::AbstractVector{CT}, m::Integer, m′::Integer, nmax::Integer, α::Number, β::Number, γ::Number)

Calculate the Wigner D-function recursively, in place.

wigner_D_recursion([T=Float64,], m::Integer, m′::Integer, nmax::Integer, α::Number, β::Number, γ::Number)

Calculate the Wigner D-function recursively (use wigner_d_recursion).

wigner_d([T=Float64,], m::Integer, n::Integer, s::Integer, ϑ::Number) where {T}

Calculate Wigner (small) d-function $d_{mn}^s(\theta)$ for a single $(m, n, s)$ combination, using Eq. (B.1) of Mishchenko et al. (2002).

\[\begin{aligned} d_{m n}^{s}(\vartheta)=& \sqrt{(s+m) !(s-m) !(s+n) !(s-n) !} \\ & \times \sum_{k=\max(0,m-n)}^{\min(s + m, s - n)}(-1)^{k} \frac{\left(\cos \frac{1}{2} \vartheta\right)^{2 s-2 k+m-n}\left(\sin \frac{1}{2} \vartheta\right)^{2 k-m+n}}{k !(s+m-k) !(s-n-k) !(n-m+k) !} \end{aligned}\]

wigner_d_recursion!(d::AbstractVector{T}, m::Integer, n::Integer, sₘₐₓ::Integer, ϑ::Number; deriv=nothing)

Calculate the Wigner d-function recursively, in place.

wigner_d_recursion([T=Float64,], m::Integer, n::Integer, sₘₐₓ::Integer, ϑ::Number; deriv::Bool = false) where {T}

Calculate Wigner (small) d-function $d_{mn}^s(\theta)$ for $s\in[s_{\min}=\max(|m|, |n|),s_{\max}]$ (alternatively, its derivative as well) via upward recursion, using Eq. (B.22) of Mishchenko et al. (2002).

\[\begin{aligned} d_{m n}^{s+1}(\vartheta)=& \frac{1}{s \sqrt{(s+1)^{2}-m^{2}} \sqrt{(s+1)^{2}-n^{2}}}\left\{(2 s+1)[s(s+1) x-m n] d_{m n}^{s}(\vartheta)\right.\\ &\left.-(s+1) \sqrt{s^{2}-m^{2}} \sqrt{s^{2}-n^{2}} d_{m n}^{s-1}(\vartheta)\right\}, \quad s \geq s_{\min } \end{aligned}\]

The initial terms are given by Eq. (B.23) and Eq. (B.24).

\[\begin{array}{l} d_{m n}^{s_{\min }-1}(\vartheta)=0 \\ d_{m n}^{s_{\min }}(\vartheta)=\xi_{m n} 2^{-s_{\min }}\left[\frac{\left(2 s_{\min }\right) !}{(|m-n|) !(|m+n|) !}\right]^{1 / 2}(1-x)^{|m-n| / 2}(1+x)^{|m+n| / 2} \end{array}\]

where

\[\xi_{m n}=\left\{\begin{array}{ll} 1 & \text { for } n \geq m \\ (-1)^{m-n} & \text { for } n<m \end{array}\right.\]