rustmatrix.scatterer

Python-side Scatterer class.

Mirrors the API of pytmatrix.tmatrix.Scatterer so downstream code can use this module as a drop-in replacement. Orientation averaging is provided by rustmatrix.orientation (pure Python; calls into the Rust single-orientation evaluator in a loop). PSD integration is routed through rustmatrix.psd, whose fast paths run inside Rust with the GIL released and parallelise across diameters via rayon.

Notes

The Rust extension caches the built T-matrix on the _handle attribute and reuses it whenever the signature (radius, radius_type, wavelength, m, axis_ratio, shape, ddelt, ndgs) is unchanged. Switching orientation or scattering geometry costs only an amplitude-matrix rotation.

class rustmatrix.scatterer.Scatterer(**kwargs)

Bases: object

T-Matrix scattering from nonspherical particles (Rust backend).

API-compatible with pytmatrix.tmatrix.Scatterer. Construct one with the size / material / geometry attributes below, then call get_SZ() (or get_S(), get_Z()) to obtain the amplitude and phase matrices.

radius

Particle “equivalent” radius in mm. Interpreted according to radius_type. Default: 1.0.

Type:

float

radius_type

One of RADIUS_EQUAL_VOLUME (default), RADIUS_EQUAL_AREA, or RADIUS_MAXIMUM. Controls how radius is converted to the Mishchenko-code equal-volume radius the solver expects.

Type:

float

wavelength

Incident-radiation wavelength in mm. Use the wl_* presets in rustmatrix.tmatrix_aux for standard radar bands.

Type:

float

m

Refractive index of the particle material. Use rustmatrix.refractive for tabulated water/ice values.

Type:

complex

axis_ratio

Horizontal over vertical axis ratio. axis_ratio > 1 is oblate (flattened raindrop); < 1 is prolate (columnar ice); = 1 is a sphere.

Type:

float

shape

Particle shape code. SHAPE_SPHEROID (-1, default), SHAPE_CYLINDER (-2), or SHAPE_CHEBYSHEV (1).

Type:

int

ddelt

Convergence tolerance for the T-matrix solver. 1e-3 is usually fine; tighten to 1e-4 for high-accuracy work. Default: 1e-3.

Type:

float

ndgs

Quadrature density factor. Increase for elongated particles or large size parameters if the solver fails to converge. Default: 2.

Type:

int

alpha, beta

Particle Euler angles in degrees. For a single-orientation evaluation both default to 0.

Type:

float

thet0, thet

Incident and scattering zenith angles in degrees (0 = north pole, 180 = south). Defaults: both 90 (horizontal propagation).

Type:

float

phi0, phi

Incident and scattering azimuth angles in degrees. Defaults: phi0 = 0, phi = 180 (backscatter).

Type:

float

Kw_sqr

|K_w|² dielectric factor used by radar.refl(). Standard radar-band values are in tmatrix_aux.K_w_sqr. Default: 0.93.

Type:

float

orient

Orientation-averaging strategy from rustmatrix.orientation (orient_single, orient_averaged_fixed, or orient_averaged_adaptive). Default: orient_single.

Type:

callable

or_pdf

Orientation PDF returning weight given β in degrees. See orientation.gaussian_pdf(), orientation.uniform_pdf().

Type:

callable

n_alpha, n_beta

Number of α / β samples for orient_averaged_fixed. Defaults: 5 and 10.

Type:

int

psd_integrator

When set, get_SZ() integrates S and Z against psd. See rustmatrix.psd.PSDIntegrator.

Type:

PSDIntegrator, optional

psd

Particle-size distribution instance (e.g. rustmatrix.psd.GammaPSD).

Type:

PSD, optional

suppress_warning

Silence the DeprecationWarning emitted when legacy pytmatrix kwargs (axi, lam, eps, rat, np, scatter) are used.

Type:

bool

Examples

>>> from rustmatrix import Scatterer
>>> s = Scatterer(radius=1.0, wavelength=33.3, m=complex(7.99, 2.21),
...               axis_ratio=1.5, ddelt=1e-4, ndgs=2)
>>> s.set_geometry((90, 90, 0, 180, 0, 0))  # horizontal backscatter
>>> S, Z = s.get_SZ()

set_geometry(geom)

Assign (thet0, thet, phi0, phi, alpha, beta) in one call.

geom is a 6-tuple of degrees — use the geom_* presets from rustmatrix.tmatrix_aux for the common radar cases.

get_geometry()

Return the current (thet0, thet, phi0, phi, alpha, beta) tuple.

equal_volume_from_maximum()

Equal-volume-sphere radius given self.radius as a maximum radius.

Only defined for SHAPE_SPHEROID and SHAPE_CYLINDER. Used internally when radius_type is RADIUS_MAXIMUM.

get_SZ_single(alpha=None, beta=None)

Amplitude and phase matrices at a single Euler orientation.

Parameters:

• alpha (float, optional) – Euler angles in degrees. Default to self.alpha, self.beta.

• beta (float, optional) – Euler angles in degrees. Default to self.alpha, self.beta.

Returns:

• S (ndarray (2, 2) complex) – Amplitude scattering matrix.

• Z (ndarray (4, 4) float) – Phase (Stokes) matrix.

Notes

Cached on the handle; re-building the T-matrix only happens when the size/material signature changes. Advancing only (alpha, beta) or the scattering geometry reuses the existing T-matrix.

get_SZ_orient()

S and Z using self.orient (orientation-averaging dispatcher).

Dispatches to the callable in orient — orientation.orient_single() by default.

get_SZ()

Amplitude + phase matrices, PSD-integrated if configured.

Returns:

• S (ndarray (2, 2) complex)

• Z (ndarray (4, 4) float)

Notes

If psd_integrator is None this is equivalent to get_SZ_orient(). Otherwise it returns the N(D)-weighted average over the scatter table built by PSDIntegrator.init_scatter_table().

get_S()

Amplitude matrix only — convenience wrapper around get_SZ().

get_Z()

Phase matrix only — convenience wrapper around get_SZ().

class rustmatrix.scatterer.TMatrix(**kwargs)

Bases: Scatterer