Metadata-Version: 2.4
Name: fastsar
Version: 0.1.3
Summary: Synthetic aperture radar image formation on x86 CPUs, Nvidia GPUs and Cloud TPUs
Author: Paul Singerman
License-Expression: MIT
Project-URL: Homepage, https://github.com/saulpingerman/FastSAR
Project-URL: Documentation, https://github.com/saulpingerman/FastSAR/tree/main/docs
Project-URL: Source, https://github.com/saulpingerman/FastSAR
Project-URL: Issues, https://github.com/saulpingerman/FastSAR/issues
Project-URL: Changelog, https://github.com/saulpingerman/FastSAR/blob/main/CHANGELOG.md
Keywords: synthetic aperture radar,SAR,backprojection,image formation,CPHD,SICD,GPU,TPU
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: GPU :: NVIDIA CUDA :: 12
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.2.6
Requires-Dist: scipy>=1.15.3
Requires-Dist: jax>=0.6.2
Provides-Extra: cuda
Requires-Dist: cupy-cuda12x>=13; extra == "cuda"
Provides-Extra: io
Requires-Dist: sarpy>=1.3.64; extra == "io"
Provides-Extra: tpu
Requires-Dist: jax[tpu]>=0.6.2; extra == "tpu"
Provides-Extra: geo
Requires-Dist: rasterio>=1.4.4; extra == "geo"
Provides-Extra: raw
Requires-Dist: h5py>=3.10; extra == "raw"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-timeout; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: sarpy>=1.3.64; extra == "test"
Requires-Dist: sarkit; python_version >= "3.11" and extra == "test"
Requires-Dist: rasterio>=1.4.4; extra == "test"
Requires-Dist: finufft; extra == "test"
Requires-Dist: h5py>=3.10; extra == "test"
Dynamic: license-file

# FastSAR

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/saulpingerman/FastSAR/blob/main/LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/saulpingerman/FastSAR/blob/main/pyproject.toml)

FastSAR forms synthetic aperture radar (SAR) images on x86 CPUs, Nvidia GPUs and Google Cloud TPUs from Python. It
reads frequency-domain CPHD files, forms spotlight, stripmap and sliding spotlight images by factorized
backprojection, and provides autofocus, interferometry, geolocation, map GeoTIFFs and SICD output.

![FastSAR image of the Panama Canal's Pacific entrance from an Umbra spotlight collection](https://raw.githubusercontent.com/saulpingerman/FastSAR/main/docs/images/hero_panama.jpg)

*Panama Canal, Pacific entrance (Umbra open data, 2023-07-18): 12,207 by 8,808 pixels in 2.9 s on an Nvidia L4
(warm former, transfers included; float32, -59.9 dB against the float64 reference of
[precision.md](https://github.com/saulpingerman/FastSAR/blob/main/docs/precision.md)), downsampled. A
c4d-highmem-16 CPU instance (16 vCPUs, 8 cores) takes 11.3 s. ISCE3, the fastest open-source code that forms this
collection, would take an estimated 4.8 h on that CPU and 27 min on the L4.*

![Cost per 1000 images against error for FastSAR and five open-source implementations](https://raw.githubusercontent.com/saulpingerman/FastSAR/main/docs/images/teaser.png)

*Cost per 1000 Panama images (October 2026 prices) against error over the lock, port and ship regions, relative to
the float64 reference ([performance](https://github.com/saulpingerman/FastSAR/blob/main/docs/performance.md), [comparison](https://github.com/saulpingerman/FastSAR/blob/main/docs/comparison.md)).*

## Install

Linux on x86-64 or 64-bit ARM and macOS on Apple silicon, Python 3.10 to 3.13. The CPU kernels compile on first
use: with `g++` and OpenMP on Linux (Debian and Ubuntu: `apt install g++`), with Apple's clang on macOS (the command
line tools, `xcode-select --install`, which also serve the Metal backend of `ExactFormer` on Apple GPUs); the
`cuda` extra needs an Nvidia driver for CUDA 12 and the `tpu` extra a Cloud TPU VM.

```bash
pip install fastsar                  # CPU (and JAX on whatever device it has)
pip install "fastsar[io]"            # io: sarpy for CPHD and SICD
pip install "fastsar[cuda]"          # cuda: CuPy for Nvidia GPUs
pip install "fastsar[tpu]"           # tpu: jax[tpu] for Cloud TPUs
pip install "fastsar[geo]"           # geo: rasterio for GeoTIFFs and DEMs
pip install "fastsar[raw]"           # raw: h5py for the NISAR raw reader
pip install "fastsar[cuda,io,geo]"   # extras combine
```

From a clone: `pip install -e ".[cuda,io]"` or `uv sync`. The CUDA tensor-core kernels (float16, and float32 on compute capability 8.0 and later) need `nvcc` from the CUDA toolkit; without it float32 runs on the CUDA cores, more slowly. On the CPU set
`OMP_NUM_THREADS=<physical cores> OMP_PLACES=cores OMP_PROC_BIND=close`. Importing `fastsar` sets
`XLA_PYTHON_CLIENT_PREALLOCATE=false` unless it is already set, so that JAX does not reserve most of a GPU's memory
before the CUDA kernels run ([performance.md](https://github.com/saulpingerman/FastSAR/blob/main/docs/performance.md#environment-variables)).

## Quickstart

The chain below reads a CPHD file and writes a GeoTIFF and a SICD, so it needs `pip install "fastsar[io,geo]"`.

```python
import fastsar
from fastsar import products

out = fastsar.form_cphd('scene_CPHD.cphd')        # mode, grid and window from the file
img = out['image']                                # complex64 [nx, ny] on a ground plane at the scene height
lat, lon, h = products.geolocate(out, 100, 200)   # pixel (100, 200) on the ground
products.write_geotiff('amp.tif', **products.geocode_image(out))   # amplitude on a north-up UTM grid
products.write_sicd('scene.nitf', out)            # complex image with its geometry
```

[`examples/chain.py`](https://github.com/saulpingerman/FastSAR/blob/main/examples/chain.py) runs this chain from the command line (`--simulate` needs no data);
[`form_umbra.py`](https://github.com/saulpingerman/FastSAR/blob/main/examples/form_umbra.py) and [`form_capella_stripmap.py`](https://github.com/saulpingerman/FastSAR/blob/main/examples/form_capella_stripmap.py) form
vendor grids.

## Supported data, modes and devices

| Data | Modes | Status |
|---|---|---|
| Capella CPHD | stripmap, spotlight, sliding spotlight | checked against vendor SICDs; a 2022 dynamic stripmap is correct near the center only |
| Umbra CPHD | spotlight | three open-data collections on the vendor's grid |
| ICEYE CPHD | dwell spotlight | formed (28 GB history); not compared with the vendor image |
| TOA-domain CPHD, raw Level-0 | | not supported |
| Simulated echoes | stripmap, ScanSAR, TOPS, any track | `fastsar.stripmap`, `burst`, `patches` |

| | CPU (`cpu`) | Nvidia GPU (`cuda`) | Cloud TPU (`tpu`) | Any JAX device (`jax`) |
|---|---|---|---|---|
| Factorized backprojection | C++/OpenMP, AVX-512 or AVX2 | CUDA via CuPy | Pallas | reference program |
| Precision | float32 | float32, float16 | three-pass (default), single-pass | float32, float16 |
| Exact backprojection (`ExactFormer`) | C++/OpenMP, float32 with float64 tile centers | CUDA, the same | falls back to `jax` | float32, float64 block centers |

Polar format (`algorithm='pfa'`) runs as a JAX program on any device.

## Documentation

[docs/README.md](https://github.com/saulpingerman/FastSAR/blob/main/docs/README.md) lists every page; start with the [processing chain](https://github.com/saulpingerman/FastSAR/blob/main/docs/processing-chain.md).
Measurement records are in [sar-accel-study](https://github.com/saulpingerman/sar-accel-study). To cite FastSAR, use
[CITATION.cff](https://github.com/saulpingerman/FastSAR/blob/main/CITATION.cff).

## Contributing and license

[CONTRIBUTING.md](https://github.com/saulpingerman/FastSAR/blob/main/CONTRIBUTING.md) explains how to run the tests
(GitHub Actions runs the CPU suite; the CUDA and TPU tests run on those machines before a release). MIT license ([LICENSE](https://github.com/saulpingerman/FastSAR/blob/main/LICENSE)).
