fatcuda 0.1.2

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.

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/代码层/.