Metadata-Version: 2.4
Name: fpm-rs
Version: 0.2.0b2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Dist: numpy>=2.1
Requires-Dist: pytest-cov>=5 ; extra == 'coverage'
Requires-Dist: jupyterlab>=4.3 ; extra == 'notebook'
Requires-Dist: matplotlib>=3.9 ; extra == 'notebook'
Requires-Dist: matplotlib>=3.9 ; extra == 'plot'
Requires-Dist: polars>=1 ; extra == 'polars'
Requires-Dist: packaging>=24 ; extra == 'release'
Requires-Dist: twine>=6 ; extra == 'release'
Requires-Dist: pytest>=8.3 ; extra == 'test'
Requires-Dist: ipython>=8.30 ; extra == 'test-full'
Requires-Dist: matplotlib>=3.9 ; extra == 'test-full'
Requires-Dist: polars>=1 ; extra == 'test-full'
Requires-Dist: pytest>=8.3 ; extra == 'test-full'
Provides-Extra: coverage
Provides-Extra: notebook
Provides-Extra: plot
Provides-Extra: polars
Provides-Extra: release
Provides-Extra: test
Provides-Extra: test-full
License-File: LICENSE-MIT
Summary: High-performance Fourier ptychography reconstruction, simulation, and diagnostics for Python, powered by Rust.
Author-email: "Hernán E. Grecco" <hernan.grecco@gmail.com>
License-Expression: MIT
Requires-Python: >=3.12, <3.15
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://hgrecco.github.io/fpm-rs
Project-URL: Homepage, https://github.com/hgrecco/fpm-rs
Project-URL: Issues, https://github.com/hgrecco/fpm-rs/issues
Project-URL: PyPI, https://pypi.org/project/fpm-rs/

# fpm-rs

Reconstruct and simulate image-plane Fourier ptychographic microscopy (FPM)
acquisitions from Rust or Python.

`fpm-rs` gives microscopy researchers and algorithm developers a CPU-based core
for compiling illumination geometry, simulating measurements, and recovering a
complex object. It supports image-plane FPM only: diffraction-plane
ptychography, multislice propagation, and GPU execution are not implemented.

## What it can do for you

- **Compile an optical model.** Resolve source geometry, stable calibration,
  and sparse acquisition structure into Fourier-space sampling and a pupil.
- **Simulate an acquisition.** Generate ideal or camera-affected intensity
  frames from synthetic or supplied complex objects.
- **Reconstruct the object.** Start with alternating projection, or use FPIE,
  EPRY, ADMM, or gradient descent when their calibration and regularization
  options fit the experiment.
- **Calibrate a planar LED array physically.** Alternate analytic object or
  object/pupil updates with bounded pose, pitch, reference-index,
  selected-offset, source-power, or frame-gain updates and reuse the returned
  `Illumination`.
- **Keep a run inspectable.** Record diagnostics, write checkpoints, and
  compare simulations with known ground truth. Optional Parquet support writes
  self-describing result and benchmark bundles for downstream analysis.
- **Measure at the right layer.** Reusable reference/estimate metrics,
  optimization objectives, reconstruction evaluation, and recorder-driven
  diagnostics are separate APIs.

## A typical workflow

1. Compile the optics and illumination into an `ImagePlaneModel`.
1. Load measured intensity frames, or simulate them from a known object.
1. Build a `ReconstructionProblem`, run an algorithm, and inspect amplitude,
   phase, diagnostics, or checkpoints.

The same forward model is used for simulation and reconstruction, while
algorithms consume the compiled model rather than experimental geometry.

## Array layout contract

The Rust API uses native `ndarray` arrays and views. Pointwise utilities and
metrics accept arbitrary logical layouts, including transposed and stepped
views. Computational inputs whose kernels use flat Fourier-grid offsets—such
as pupils, synthetic objects, measurement stacks, crop operations, and direct
forward-model spectra—require standard C-style row-major layout. Those APIs
validate the layout without copying and return a `NonStandardLayout` error for
strided input. Owned result and diagnostic arrays are ordinary `ndarray`
arrays. Result bundle export is a strict persistence boundary and rejects
nonstandard result layouts rather than silently materializing a copy.

Python follows the same distinction. Metrics accept strided NumPy arrays.
Reconstruction, simulation, pupil, and measurement inputs require
C-contiguous arrays and raise an error suggesting `numpy.ascontiguousarray`;
the caller therefore decides whether to pay for that copy. Accepted NumPy
inputs are copied into Rust-owned storage at the binding boundary. Arrays
opened through a result bundle are loaded on first access, cached, and exposed
as immutable NumPy arrays.

## Start here

Install the Python package:

```console
python -m pip install fpm-rs
```

Then compile a small model, simulate it, and reconstruct it:

```python
import numpy as np
import fpm_rs as fpm

optics = fpm.Optics(532e-9, 0.10, 4.0, 6.5e-6)
geometry = fpm.PlanarLEDArray(
    (3, 3),
    4e-3,
    (1.0, 1.0),
    fpm.ArrayPose.from_translation((0.0, 0.0, -90e-3)),
)
illumination = fpm.Illumination(geometry)
model = fpm.compile_model(optics, illumination, (32, 32))

simulation = fpm.simulate(
    model,
    np.ones(model.reconstruction_shape, dtype=np.complex128),
    seed=1234,
)
problem = fpm.ReconstructionProblem(
    simulation.measurements,
    simulation.reconstruction_model,
)
result = fpm.AlternatingProjection(iterations=20).run(problem)
print(result.amplitude.shape)
```

For the Rust equivalent, run:

```console
cargo run --example simulate_and_reconstruct
```

## Go deeper

- [Documentation](https://hgrecco.github.io/fpm-rs/): installation, tutorials,
  guides, concepts, and API references.
- [Quickstart](docs/getting-started/quickstart.md): a narrated Python workflow.
- [Reconstruction guide](docs/guides/reconstruction.md): model sizing,
  algorithms, physical illumination calibration, callbacks, and checkpoints.
- [Measurements](docs/guides/measurements.md), [simulation](docs/guides/simulation.md),
  and [datasets](docs/datasets.md): prepare real data and create test cases.
- [Contributor guide](docs/development/index.md): build, test, and document a
  checkout.

## License

fpm-rs is available under the [MIT License](LICENSE-MIT).

