fatcuda 0.1.3

Optical Tweezers Force Engine — Python port of the OTS toolbox (Phase 1: Mie sphere, non-paraxial focused-beam force)

fatcuda

fatcuda is an intent-first optical tweezers force and field engine. It starts from physical declarations - beam intent, optical system, particle or task, and device policy - then lowers them into auditable intermediate representations and verified CPU/CUDA/Metal execution paths.

The current production package lives in fatcuda/. The historical direct-port implementation is archived in fatcuda_old/ and is kept only as an oracle, comparison source, and history bundle.

Status

This project is still early. The current verified path focuses on homogeneous Mie spheres, non-paraxial Debye-Wolf focusing, multipole coefficients, field slices, force maps, and CPU/Metal/CUDA interface parity. APIs may still move while the package is prepared for a first public PyPI release.

Installation

After publication:

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

For local development from this checkout:

python -m pip install -e ".[test,demo]"
python -m pip install -e ".[test,demo,metal]"
python -m pip install -e ".[test,demo,cuda12]"

The default portable execution path is CPU-only and depends on NumPy and SciPy.

Minimal Example

import numpy as np

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

system = OpticalSystem(grid=PupilGrid(Nphi=32, Nr=16), power=1.0e-3)
beam = GaussianBeam(Ex0=1.0, Ey0=0.0)
sphere = Sphere(radius=0.2e-6, n_p=1.59, L=8)
task = ForceAtPositions(
    positions=np.array(
        [
            [0.0, 0.0, 0.0],
            [0.1e-6, 0.0, 0.0],
        ]
    ),
    particle=sphere,
)

result = solve(
    beam=beam,
    system=system,
    task=task,
    strategy="auto",
    device="cpu",
)

print(result.force)
print(result.torque)
print(result.audit.operator_plan)

Progress Callbacks

Execution progress is opt-in and reported as immutable structured events. The callback runs synchronously on the caller thread; use "stage" for stage-only events or the default "detailed" mode for bounded force/field advances.

def on_progress(event):
    print(event.stage, event.state, event.completed, event.total, event.unit)

result = solve(
    beam=beam,
    system=system,
    task=task,
    device="cuda",
    progress_callback=on_progress,
    progress_granularity="detailed",
)

Callbacks do not become part of the task, IR, audit, or result. CUDA detailed events are emitted only after their selected stream events complete.

Debye Incident-Field Slices

Use the public Debye route when the required observable is the incident field itself, without a Mie T-matrix or multipole reconstruction:

from fatcuda import FieldSlice

field_task = FieldSlice(
    particle=sphere,
    plane="xz",
    extent=1.0e-6,
    n_pix=64,
    kind="incident",
)
field_result = solve(
    beam=beam,
    system=system,
    task=field_task,
    strategy="debye",
    device="cpu",  # also "cuda" or "metal"
)

strategy="debye" is incident-only and currently requires FieldSlice.position == (0, 0, 0); plane, extent, n_pix, and offset remain available. Use direct or fft for scattered and total fields.

Public API Shape

The recommended user flow is:

beam intent + optical system + particle/task + device/strategy -> auditable IR -> kernels

Common public declarations include:

Concept	Examples
Beams	GaussianBeam, LaguerreGaussBeam, HermiteGaussBeam, AiryBeam, VortexBeam, SLMPhaseBeam
System	OpticalSystem, PupilGrid
Particles	Sphere
Tasks	ForceAtPositions, FieldSlice
Execution	solve, compile_problem, DevicePolicy, OperatorStrategy, PrecisionPolicy

Verification

The repository uses MATLAB OTS fixtures, the current CPU NumPy path, and closed-form physics sanity checks as oracles. Typical local verification:

python -m pytest -q -p no:cacheprovider

CUDA numerical validation requires a CUDA machine. On macOS without CUDA, CUDA tests are limited to import, collection, skip behavior, and shared-interface non-breakage. Metal validation requires Apple Silicon with the metal extra installed and MLX reporting Metal availability.

Documentation

• Documentation index
• Quickstart
• Forward plan

The detailed code-layer notes live under doc/obsidian/fatcuda/代码层/.