rustmatrix.orientation#

Orientation-averaging strategies and PDFs.

Port of pytmatrix.orientation. The three orient_* functions all take a Scatterer instance and return the (S, Z) pair averaged (or not) over the Euler angles (alpha, beta) according to the scatterer’s or_pdf.

The module is pure Python — it calls Scatterer.get_SZ_single() repeatedly with different orientations, relying on the Rust core only for the per-orientation evaluation.

rustmatrix.orientation.gaussian_pdf(std=10.0, mean=0.0)[source]#

Gaussian orientation PDF with the spherical Jacobian baked in.

Parameters:

  • std (float) – Standard deviation of the Gaussian in degrees. Default 10°.

  • mean (float) – Mean canting angle β in degrees. Default 0° (vertical symmetry axis). For horizontally-oriented falling particles use 90°.

Returns:

pdf – pdf(beta) with beta in degrees. Includes the sin(β) spherical weight and is normalised to integrate to 1 on [0, 180].

Return type:

callable

Examples

>>> pdf = gaussian_pdf(std=20.0, mean=90.0)
>>> pdf(90.0) > pdf(60.0)
True
rustmatrix.orientation.uniform_pdf()[source]#

Uniform-on-the-sphere orientation PDF.

Returns:

pdf – pdf(beta) equal to sin(β·π/180) / 2, so that ∫pdf dβ on [0, 180] equals 1. Use this when the particle has no preferred orientation.

Return type:

callable

rustmatrix.orientation.orient_single(tm)[source]#

No averaging — evaluate S, Z at the scatterer’s current (α, β).

Parameters:

tm (Scatterer)

Return type:

Tuple[ndarray, ndarray]

Returns:

  • S (ndarray (2, 2) complex)

  • Z (ndarray (4, 4) float)

rustmatrix.orientation.orient_averaged_adaptive(tm)[source]#

Adaptive orientation averaging via scipy.integrate.dblquad.

Integrates each of the 4 (re, im) components of S and the 16 components of Z separately over α ∈ [0, 360], β ∈ [0, 180], weighted by tm.or_pdf(β) and divided by 360 for the uniform α.

Parameters:

tm (Scatterer) – Must have tm.or_pdf set.

Return type:

Tuple[ndarray, ndarray]

Returns:

  • S (ndarray (2, 2) complex)

  • Z (ndarray (4, 4) float)

Notes

Slow: many T-matrix evaluations per diameter. Prefer orient_averaged_fixed() in production; reserve this for reference runs. The Rust PSD fast path replaces this per-diameter with a dense fixed grid and runs ~400× faster overall — see PSDIntegrator.init_scatter_table().

rustmatrix.orientation.orient_averaged_fixed(tm)[source]#

Fixed-quadrature orientation averaging.

α is sampled uniformly at tm.n_alpha points on [0, 360); β is integrated by Gauss-Gautschi quadrature against tm.or_pdf with nodes tm.beta_p and weights tm.beta_w (populated by Scatterer._init_orient()).

Parameters:

tm (Scatterer)

Return type:

Tuple[ndarray, ndarray]

Returns:

  • S (ndarray (2, 2) complex)

  • Z (ndarray (4, 4) float)

Notes

Much faster than orient_averaged_adaptive() and accurate to a few hundredths of a dB in Z_dr for smooth Gaussian PDFs. Default choice for orientation-averaged radar forward modelling.