fatcuda

fatcuda is an intent-first optical-tweezers engine for vectorial, non-paraxial force, torque, and electric-field calculations. A problem is declared with a beam, optical system, particle, observable, position, and execution policy; fatcuda compiles that declaration to an auditable route and runs verified CPU, CUDA, or Metal operators.

The project is pre-1.0, so public APIs may still change before 1.0.

Capability overview

The current public capability map is available as the capability pipeline.

Installation

Python 3.10 or newer is required. The portable installation uses NumPy and SciPy 1.15 or newer on CPU:

python -m pip install fatcuda

Optional backends are installed separately:

python -m pip install "fatcuda[metal]"   # Apple Silicon / MLX
python -m pip install "fatcuda[cuda12]"  # CUDA 12 / CuPy

Public API

solve(...) is the main execution entry point; compile_problem(...) exposes the compiled IR and audit before execution. Both are keyword-only and require explicit beam= and position= arguments. Fixed force queries use ForceTorque. Sweeps use SweepSpec with named BeamAxis, PositionAxis, or OrientationAxis coordinates and return SweepResult. Fixed field queries use FieldSlice and take their focus/particle position from the top level.

Each beam declaration is one incident state. A phase scan is an explicit BeamAxis of scalar SLMPhaseBeam declarations; SLMPhaseBeam.phase is one finite 2-D image.

Experimental expert numerics

fatcuda.numerics provides curated direct aliases for explicit SLM synthesis, pupil-to-coefficient focusing, FCD response preparation/solve, coefficient MST observables, and Debye/multipole field reconstruction. The marker fatcuda.numerics.API_STABILITY is exactly "experimental"; these actions are not exported from the package root.

from fatcuda.numerics import API_STABILITY
from fatcuda.numerics.field import reconstruct_multipole_field

assert API_STABILITY == "experimental"

This surface does not select devices, transfer arrays, build physical models, package audits, or validate credibility; its arrays and carriers are not a Result audit snapshot. It is a supported, documented 0.x expert entrance. Canonical equations, acceptance gates, and object identities are unchanged, but names and grouping may change before a stable expert-API declaration. The intent API remains recommended for route selection, cache, progress, lifecycle, and audit. Focusing and Debye reconstruction are host NumPy/SciPy actions. FCD supports explicit NumPy/CuPy namespaces, not MLX; coefficient MST supports NumPy/CuPy with a compatible prepared operator; and multipole reconstruction supports NumPy/CuPy/MLX. Radiating reconstruction keeps every coefficient that is exactly nonzero after target-dtype conversion; exact-zero tails may skip work without changing declared order, packing, masks, or progress. An unrepresentable exact-nonzero radial request fails before device recurrence.

Minimal examples

A fixed force/torque calculation returns two (3,) vectors in SI units:

from fatcuda import (
    ForceTorque,
    GaussianBeam,
    OpticalSystem,
    PupilGrid,
    Sphere,
    solve,
)

system = OpticalSystem(
    lambda0=1.064e-6,
    NA=1.20,
    nm=1.33,
    grid=PupilGrid(Nphi=32, Nr=16),
    power=1.0e-3,
)
result = solve(
    beam=GaussianBeam(Ex0=1.0, Ey0=0.0),
    position=(0.0, 0.0, 0.0),
    system=system,
    particle=Sphere(radius=0.2e-6, n_p=1.59, L=8),
    task=ForceTorque(),
    device="cpu",
)

print(result.force)   # N
print(result.torque)  # N m

An explicit position sweep returns a SweepResult with shape (P, 3):

import numpy as np

from fatcuda import ForceTorque, PositionAxis, SweepSpec

positions = np.array([
    [0.0, 0.0, 0.0],
    [0.1e-6, 0.0, 0.0],
])
task = SweepSpec(ForceTorque(), (PositionAxis(positions),))

sweep = solve(
    beam=GaussianBeam(Ex0=1.0, Ey0=0.0),
    position=None,
    system=system,
    particle=Sphere(radius=0.2e-6, n_p=1.59, L=8),
    task=task,
    device="cpu",
)

print(sweep.dims)        # ("position",)
print(sweep.force.shape) # (2, 3)

Backends

• CPU is the fp64/c128 reference path and supports the complete portable surface.
• CUDA accelerates supported focusing, coefficient evaluation, force/torque sweeps, field reconstruction, Debye fields, and Janus DDA response routes.
• Metal accelerates supported focusing, coefficient application, sweeps, and field reconstruction through MLX; verified cancellation-sensitive operations may remain on CPU c128 and are reported in the audit.

Unsupported backend routes fail explicitly; they do not silently fall back to a different physical model.

Limitations

• Calculations use SI units and the exp(+i k z) propagation convention with implicit exp(-i omega t) time dependence.
• Photophoretic, thermophoretic, and self-heating forces are not modeled.
• The validated Janus capability is dielectric-dielectric. Idealized metal-capped inputs may be executable, but they do not carry a package credibility claim and can be sensitive to discretization and material modeling.
• Ordinary validated Mie ranges are supported. Inputs that make the current OTS-faithful coefficient formulation nonfinite fail explicitly at response construction; extreme Rayleigh or large-lossy special-function stability is not claimed.
• DDA responses are mesh-limited. Prefer analytic Sphere or LayeredSphere models for spherical limits. Reusable LDR-DDA removes exact index-matched (alpha == 0) sites algebraically; a fully matched particle returns an exact-zero T.
• Normalized scalar harmonics use scipy.special.sph_harm_y; the OTS central-difference derivative and pole-remap convention remains in force. Focusing/operator construction is host CPU complex128 work.
• Automatic response order selection does not refine PupilGrid. High-order users must converge Nphi, Nr, and the observable; same-grid direct/FFT agreement validates factorization, not continuum pupil convergence.
• Radiating multipole fields fail explicitly when an exact-nonzero target-precision order is not representable on the physical slice domain; nonzero modes are never discarded by magnitude or hidden by a precision fallback.
• CUDA requires a compatible CUDA 12 environment; Metal requires Apple Silicon with an available MLX Metal device.

License and support

The fatcuda distribution is released under the MIT License. See the LICENSE file for the full text.

Project and support links:

• fatcuda project
• Issue tracker
• Capability pipeline