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 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.

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.
• DDA responses are mesh-limited. Prefer analytic Sphere or LayeredSphere models for spherical limits.
• 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