Skip to content

treams-rs

treams-rs is a Rust port of treams with a Python interface and analytic gradients.

Get started Coming from treams

All credit for treams belongs to the original treams contributors.

Their work is described in the treams paper; please cite it when using this port.

treams-rs computes electromagnetic scattering with T-matrices: spheres, cylinders and layered or chiral particles, finite clusters, periodic arrays and planar stacks, with their fields, cross sections and power. A T-matrix is the linear map from the multipole coefficients of an incident wave to those of the scattered wave.

treams-rs follows the numerical conventions of treams 0.4.7 and keeps its numerical modules (special, sw, cw, pw, lattice, coeffs, misc, ebcm, io) with the same function names. Its Python interface differs; Coming from treams shows the corresponding functions and objects.

Example

import numpy as np
import treams_rs as tr

sphere = tr.sphere_tmatrix(k0=2.0, lmax=3, radius=0.5, material=4)
incident = tr.plane_wave(direction=[0, 0, 1], pol="positive_helicity", k0=2.0)
cross_sections = sphere.cross_sections(incident)
# A lossless sphere scatters all the power it removes from the incident wave.
np.testing.assert_allclose(cross_sections.extinction, cross_sections.scattering)
# The extinction cross section of treams.TMatrix.sphere for the same sphere.
np.testing.assert_allclose(cross_sections.extinction, 0.6258290233441384, rtol=1e-12)

What treams-rs adds

  • Analytic gradients

    Advect, JAX, PyTorch and HIPS Autograd differentiate calculations involving T-matrices, clusters, periodic arrays and S-matrices through the ordinary API in first-order forward and reverse mode. Rust computes each derivative analytically, without finite differences.

    Differentiation →

  • Measured performance

    Archived Linux CPU benchmarks recorded a median speedup of 5.1× over treams 0.4.5 across 527 cases. The results apply to the measured builds and machine.

    Performance →

  • Requested illuminations

    Cluster.scatter and Cluster.factor solve only for the incident waves you ask for, without building the full T-matrix of the cluster.

    Clusters →

  • Matrix-free solves

    iterative.SphereCluster solves sphere clusters with GMRES, an iterative solver that needs only matrix-vector products, and does not store the dense coupling matrix. An archived benchmark of 1,024 spheres with lmax=1 on four Linux threads recorded 2.2 s for the solve and 2.8 s for its gradient, within 48 MiB.

    Large clusters →

Limits

  • CPU execution. Computations use CPU threads, not GPUs.
  • First-order derivatives. Forward and reverse mode are supported; second and higher derivatives are unsupported.
  • NumPy arithmetic. Operations on .array return ordinary arrays. The objects retain the basis, wavenumber and media. The treams PhysicsArray is available in operators for evaluating operators.
  • Explicit polarization. Each object and function takes its polarization convention as an argument; there is no global config.POLTYPE setting.

Where to go next

  • Getting started

    Install and four short examples

  • Coming from treams

    Workflows, the name map, conventions and differences from treams

  • User guide

    Particles, clusters, periodic arrays, planar stacks and numerical functions

  • Examples

    The treams gallery in treams-rs, plus gradient-based design

  • Differentiation

    Gradients through Advect, JAX, PyTorch, HIPS Autograd and diff

  • Design

    Why treams-rs is built the way it is

  • Validation

    How the results are tested, and their limits

  • Performance

    Timings and memory against treams

  • Reference

    Every public function and class, and the glossary

  • Development

    Setup and checks for contributors

  • How it was built

    The AI agents that wrote treams-rs, and the messages that directed them