Metadata-Version: 2.4
Name: scatrs
Version: 0.3.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=1.26
Requires-Dist: sphinx>=9 ; extra == 'docs'
Requires-Dist: furo>=2024.8 ; extra == 'docs'
Requires-Dist: myst-nb>=1.1 ; extra == 'docs'
Requires-Dist: numpydoc>=1.8 ; extra == 'docs'
Requires-Dist: ipykernel>=6.29 ; extra == 'docs'
Requires-Dist: matplotlib>=3.8 ; extra == 'docs'
Requires-Dist: sphinx-github-changelog>=2.3 ; extra == 'docs'
Requires-Dist: pytest>=8 ; extra == 'test'
Requires-Dist: packaging>=24 ; extra == 'test'
Requires-Dist: xarray>=2024.7 ; extra == 'xarray'
Provides-Extra: docs
Provides-Extra: test
Provides-Extra: xarray
License-File: LICENSE
Summary: Fast, linearized, rigorously validated single-scattering calculations for spherical and spheroidal particles
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://usask-arg.github.io/scatrs/
Project-URL: Repository, https://github.com/usask-arg/scatrs

# scatrs

Fast, linearized, rigorously validated single-scattering calculations for spherical and
spheroidal particles, written in Rust with a Python interface. The name reads as both "scatterers" and
"scat-rs".

scatrs is built out of the scattering core of the
[sasktran2](https://github.com/usask-arg/sasktran2) radiative transfer model, as a standalone
library for the optical properties of particles.

- **Mie scattering by homogeneous spheres:** coefficients, efficiencies, asymmetry parameter,
  amplitudes, phase matrix and Greek coefficients to every order.
- **Layered spheres:** a core and any number of concentric shells (coated spheres among them),
  with the same outputs and derivatives with respect to every layer.
- **Randomly oriented spheroids:** efficiencies, Greek coefficients and the six-element phase
  matrix of oblate and prolate spheroids, by the T-matrix method, converged to a tolerance
  with an error estimate, and their derivatives.
- **Ensembles of spheres and layered spheres:** averages over seven kinds of size
  distribution, external mixtures and batches of distributions, at many wavelengths in
  parallel, with an error estimate for every output.
- **Derivatives** of every output, in closed form: with respect to the size parameter and
  every layer's refractive index, a spheroid's aspect ratio, and for ensembles the distribution parameters, a layered
  sphere's radius fractions and the mixture weights.
- **Validated accuracy:** every output has a declared accuracy, checked against independent
  arbitrary-precision reference values across the validated domain, and against published
  results.

## Installation

```bash
pip install scatrs
```

```bash
cargo add scatrs
```

## Example

```python
import numpy as np
import scatrs
from scatrs import mie, tmatrix

# One water droplet: efficiencies, asymmetry parameter and the phase matrix.
q = mie.efficiencies(10.0, 1.33 + 1e-8j)  # size parameter, refractive index n + ik
f = mie.phase_matrix(10.0, 1.33 + 1e-8j, np.cos(np.radians([0, 90, 180])))

# A randomly oriented dust spheroid twice as wide as it is tall (aspect ratio a/c = 2).
s = tmatrix.efficiencies(5.0, 1.53 + 0.008j, aspect_ratio=2.0)
print(s.q_ext, s.g, s.error)  # the error estimate of each converged T-matrix

# A lognormal aerosol at three wavelengths (µm), with Greek coefficients to order 32.
sulfate = scatrs.Ensemble(
    scatrs.Sphere(refractive_index=1.43 + 1e-8j),
    scatrs.LogNormal(median_radius=0.08, width=1.6),
)
r = sulfate.compute([0.35, 0.55, 1.0], greek=32)
print(r.c_ext, r.ssa, r.g, r.greek.alpha1[:, :4])
```

```rust
use num_complex::Complex;
use scatrs::mie::{Mie, MieOptions};

let mut mie = Mie::<f64>::new();
let sphere = mie.compute(10.0, Complex::new(1.33, 1e-8), &MieOptions::new())?;
println!("Q_ext = {}", sphere.efficiencies().q_ext);
```

## Documentation

[usask-arg.github.io/scatrs](https://usask-arg.github.io/scatrs/): a quick start, examples, the
validation of the results, the theory behind every method, and the Python and Rust API
references. The Rust API is also on [docs.rs](https://docs.rs/scatrs).

## Contributing

See [`CONTRIBUTING.md`](https://github.com/usask-arg/scatrs/blob/main/CONTRIBUTING.md).

## License

MIT.

