eradiate.radprops.ParticleProperties

class eradiate.radprops.ParticleProperties(data)

Bases: object

An interface to scattering particle radiative properties.

This class manages scattering particle radiative properties and implements interpolation routines to produce kernel-level input data.

Parameters:

data (xarray.Dataset) – Single-scattering property dataset.

Fields:

data (xarray.Dataset) – Single-scattering property dataset.

classmethod convert(value)

Conversion logic:

  • If value is a ParticleProperties instance, return it.

  • If value is a string, attempt resolving it as a dataset keyword.

  • If value is a path-like, load the dataset into memory and close the file.

  • If value is a Dataset, initialize a ParticleProperties with it.

Notes

xr.load_dataset (eager) is used instead of xr.open_dataset (lazy) so that the underlying file handle is closed immediately after reading. With lazy loading, the handle stays open until the dataset is garbage-collected. If construction later raises (e.g. a validator rejects the arguments), the partial object is kept alive by pytest’s traceback capture and the handle is never closed. This leads to handle accumulation and eventual C-level crashes in the HDF5/netCDF4 library.

eval_ext(w)

Evaluate the extinction coefficient at wavelength(s) w by plain linear interpolation.

Parameters:

w (quantity) – Query wavelength(s); scalar or array.

Returns:

quantity – Extinction coefficient, same shape as w.

eval_phase(w, n_mu=None)

Evaluate the phase function at wavelength w by interpolation.

Parameters:

  • w (quantity) – Query wavelength (scalar only; array input raises ValueError because each wavelength can have a different angular grid).

  • n_mu (int, optional) – Number of output mu points. Defaults to 2 * n_iangle, where n_iangle = data.sizes["iangle"]. Since each bracketing wavelength has at most n_iangle valid angular points, their union is at most 2 * n_iangle, so the default never triggers RDP decimation in practice.

Returns:

  • mu (ndarray) – Scattering angle cosines of the output grid, shape (n_mu,).

  • phase (ndarray) – Phase function values in sr⁻¹, shape (n_phamat, n_mu).

Notes

The spectral interpolation scheme is similar to libRadtran’s and weighs bracketing wavelengths by their scattering coefficient.

When the two bracketing wavelengths have different mu grids, the phase function is resampled onto their union grid before interpolation. The result is then brought to exactly n_mu points: decimated with a greedy log-space RDP algorithm when the union is larger, or upsampled with linear interpolation in μ when it is smaller. Upsampling via linear interpolation preserves the piecewise-linear shape that Mitsuba uses during tabulated phase-function look-up, so no distortion is introduced.

eval_pmom(w, clip=False)

Evaluate Legendre moments at wavelength w by interpolation.

The two bracketing wavelengths are weighted by their scattering coefficient (extinction × single-scattering albedo). This ensures that a wavelength with no scattering contributes nothing to the interpolated phase function regardless of its spectral proximity. NaN values in the source data are treated as zero.

Parameters:

  • w (quantity) – Query wavelength(s); scalar or array.

  • clip (bool, optional) – If True, trailing all-zero slices are removed along the imom axis, so values.shape[0] == nleg.

Returns:

  • values (ndarray) – Legendre moment array for the (1,1) phase matrix element, shape (nmom, nw) or (nleg, nw) when clip=True.

  • nleg (int) – Index of the last nonzero moment (+ 1) across all queried wavelengths.

eval_ssa(w)

Evaluate the single-scattering albedo at wavelength w.

Parameters:

w (quantity) – Query wavelength(s); scalar or array.

Returns:

quantity – Dimensionless SSA, same shape as w.

Notes

The spectral interpolation scheme weighs bracketing wavelengths with the extinction coefficient, similar to libRadtran. The interpolated SSA is computed as:

ssa(w) = [(1-t)*ext_l*ssa_l + t*ext_r*ssa_r] / ext(w)

where ext(w) is the linearly interpolated extinction coefficient. When ext(w) is zero the method falls back to plain linear interpolation.

property abs
Returns:

pint.Quantity – Absorption coefficient array, cached to minimize overhead.

property ext
Returns:

pint.Quantity – Extinction coefficient array, cached to minimize overhead.

property has_fixed_mu_grid
Returns:

bool – True iff all wavelengths share an identical mu grid (same nangles and same mu values). When True, eval_phase uses n_iangle output points instead of 2 * n_iangle, preserving the original grid exactly.

property has_polarization
Returns:

bool – True iff the phase matrix has more than one coefficient.

property particle_shape
Returns:

str – Particle shape, described as a string, inferred from dataset contents and cached to minimize overhead.

property phase
Returns:

xarray.DataArray – The phase variable of data, transposed to ensure a correct layout during interpolation, cached to minimize overhead.

property pmom
Returns:

xarray.DataArray – The pmom variable of data, cached to minimize overhead.

property scat
Returns:

pint.Quantity – Scattering coefficient array, cached to minimize overhead.

property ssa
Returns:

pint.Quantity – Single-scattering albedo array, cached to minimize overhead.

property w
Returns:

pint.Quantity – Wavelength array, cached to minimize overhead.