Metadata-Version: 2.4
Name: pyfastmm
Version: 1.0.0
Summary: Python bindings for FaSTMM2 (Fast Superposition T-Matrix Method, MLFMM-accelerated)
Keywords: t-matrix,scattering,electromagnetics,mie,optics,mlfmm
Author: pyfastmm contributors
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Fortran
Project-URL: Repository, https://github.com/arunoruto/pyFaSTMM
Requires-Python: >=3.11
Requires-Dist: numpy>=1.25
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: meson>=1.1; extra == "dev"
Requires-Dist: ninja; extra == "dev"
Requires-Dist: meson-python>=0.15; extra == "dev"
Requires-Dist: h5py>=3.0; extra == "dev"
Requires-Dist: pydantic>=2.0; extra == "dev"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.28; extra == "dashboard"
Requires-Dist: pandas>=2.0; extra == "dashboard"
Requires-Dist: plotly>=5.0; extra == "dashboard"
Requires-Dist: pydantic>=2.0; extra == "dashboard"
Description-Content-Type: text/markdown

# pyFaSTMM

Python bindings for [FaSTMM2](https://bitbucket.org/planetarysystemresearch/fastmm2)
(Fast Superposition T-Matrix Method), a Multi-Level Fast Multipole Method
(MLFMM) accelerated solver for electromagnetic scattering from clusters of
spheres.

Geometry goes in and Mueller/Jones/cross-section/T-matrix data comes out
as plain NumPy arrays -- no input/output files required (unlike the
upstream CLI, which reads/writes HDF5).

## Quick start

```python
from pyfastmm import FaSTMM2

f = FaSTMM2()

coords = [[-1.5, 0.0, 0.0], [1.5, 0.0, 0.0]]
radii = [1.0, 1.0]
eps = [3.0 + 0.1j, 3.0 + 0.1j]  # permittivity = (refractive index)**2
k = 1.2  # wavenumber

result = f.solve(coords, radii, eps, k, N_theta=91, N_phi=16)
print(f"Cext = {result['c_ext']:.6f}")
print(f"Csca = {result['c_sca']:.6f}")
print(f"Mueller matrix shape: {result['mueller'].shape}")
```

## Features

- **Fixed-orientation scattering**: Mueller and Jones matrices, extinction/
  absorption/scattering cross sections, asymmetry parameter
- **Orientation-averaged scattering**: Halton-sequence orientation averaging
- **T-matrix computation**: full T-matrix output (`Taa`, `Tab`, `Tba`, `Tbb`)
  for a cluster of spheres
- **MLFMM acceleration**: `formulation=2` (FaSTMM2, default) scales to large
  clusters far better than direct superposition T-matrix (`formulation=0`)

Current scope (v1): spherical (Lorenz-Mie) monomers only -- not the
precomputed-per-monomer-T-matrix ("arbitrarily-shaped constituent
particles") input the upstream CLI also supports.

## Installation

```bash
# Clone with submodules
git clone --recurse-submodules https://github.com/arunoruto/pyFaSTMM.git
cd pyFaSTMM

# Build the extension (requires gfortran, LAPACK; see devenv.nix/flake.nix)
make f2py-ext

# Install in development mode
pip install -e .
```

Note: unlike the upstream CLI, the Python extension itself never links
HDF5 -- only `make cli` (the standalone reference binary used by the
compatibility tests) needs it.

## Requirements

- Python >= 3.12
- NumPy >= 1.25
- gfortran (GCC), LAPACK/BLAS

## Running tests

```bash
pip install -e ".[dev]"
make cli  # optional: builds the CLI reference binary for compatibility tests
pytest tests/
```

## Dashboard

```bash
pip install -e ".[dashboard]"
streamlit run scripts/streamlit_app.py
```

## License

MIT. The bundled FaSTMM2 Fortran code retains its original (BSD-3-Clause/
MIT) licenses -- see `LICENSE` and `external/fastmm2/` for details.
