Metadata-Version: 2.4
Name: fatcuda
Version: 0.6.0
Summary: Intent-first optical tweezers force, torque, and field engine with CPU, CUDA, and Metal backends
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/jwangXTS/fatcuda
Project-URL: Issues, https://gitlab.com/jwangXTS/fatcuda/-/issues
Project-URL: Capability, https://fatcuda-aea36b.gitlab.io/capability-pipeline.svg
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: matplotlib; extra == "test"
Provides-Extra: demo
Requires-Dist: matplotlib; extra == "demo"
Provides-Extra: cuda12
Requires-Dist: cupy-cuda12x<14.0,>=13.3; extra == "cuda12"
Provides-Extra: metal
Requires-Dist: mlx<0.32,>=0.31; extra == "metal"
Dynamic: license-file

# 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

[![fatcuda capability pipeline](https://fatcuda-aea36b.gitlab.io/capability-pipeline.svg)](https://fatcuda-aea36b.gitlab.io/capability-pipeline.svg)

The current public capability map is available as the
[capability pipeline](https://fatcuda-aea36b.gitlab.io/capability-pipeline.svg).

## Installation

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

```bash
python -m pip install fatcuda
```

Optional backends are installed separately:

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

```python
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:

```python
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)`:

```python
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](https://gitlab.com/jwangXTS/fatcuda/-/blob/main/LICENSE) for the
full text.

Project and support links:

- [fatcuda project](https://gitlab.com/jwangXTS/fatcuda)
- [Issue tracker](https://gitlab.com/jwangXTS/fatcuda/-/issues)
- [Capability pipeline](https://fatcuda-aea36b.gitlab.io/capability-pipeline.svg)
