fastsar 0.1.0__tar.gz

fastsar-0.1.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## 0.1.0 (2026-10-09)
+
+First release.
+
+### Added
+
+- `fastsar.ExactFormer`: exact backprojection onto the `form_image` grid, set up once per geometry, with CUDA and
+  C++ kernels (float64 tile centers, a third-order expansion within each tile, the tile size chosen from the
+  expansion's predicted error, cubic or linear interpolation of cropped range profiles);
+  `form_image(..., algorithm='bp')` with `interp`, `upsample` and `center`.
+- `fastsar.form_cphd`: one call from a CPHD file to an image; spotlight or moving beam chosen from the scene
+  reference point, ground-plane grid at the scene reference height, SICD optional.
+- `products.geolocate` and `products.locate`: latitude, longitude and height of `form_cphd` pixels on the image
+  plane, at a height or on a DEM, and the inverse; `products.read_dem` for DEM GeoTIFFs.
+- `products.geocode_image`: a `form_cphd` image, or data from it, on a north-up map grid (UTM, any rasterio CRS,
+  or latitude/longitude) with terrain correction; `write_geotiff` writes complex and multi-band data.
+- `products.write_sicd(path, out)` and `products.sicd_meta`: SICD from `form_cphd`'s output with its geometry
+  (PLANE grid, aperture polynomial), whose projection matches `geolocate`.
+- `form_cphd(..., autofocus=True)` for spotlight collections; the result also carries the band, the spatial
+  bandwidths, the windows and the autofocus phase estimate.
+- `sim.write_cphd`, `sim.to_ecf`: simulated collections as CPHD 1.0.1 files placed on the Earth.
+- `ref=` on `ImageFormer` and `form_image`: per-pulse reference ranges other than `|ant|` (bistatic half paths,
+  vendor reference points). Polar format re-references the samples to `|ant|`.
+- `ImageFormer.stage(S)`: the checks, scaling and upload of a history ahead of formation on JAX and TPU.
+- `fastsar.MemoryWarning` when a former falls back to a slower path for lack of memory (smaller first-level
+  groups, CPU pulse blocks, CUDA streaming, a GPU window of mosaic range profiles), stating the memory full speed
+  needs; `ImageFormer.memory()`. A TPU that cannot hold the history raises `MemoryError`. `MemoryWarning`
+  subclasses `UserWarning`, so `python -W error` or pytest's `filterwarnings = error` turns a fallback into an
+  exception.
+- Stripmap and sliding spotlight mosaics apply the azimuth window in the final stage of factorized backprojection
+  (C++, CUDA and JAX); range profiles are computed once per mosaic; the next patches are prepared on worker threads.
+- `patches.gate_bins`, `patches.choose_buckets` and `patch_history(gate_len=)`: JAX and TPU mosaics plan the pulse
+  counts and range gates of their compiled programs for the whole mosaic.
+- The CUDA former streams a host phase history whose device planes exceed half the free GPU memory through the
+  first level; the CPU former reads a complex64 history in place and sizes its first-level groups from the memory
+  available.
+- JAX and TPU formers cache compiled programs and the plan's device arrays by plan signature (up to 32).
+- Polar format keeps its compiled program and geometry arrays per collection geometry (the last four), and applies
+  the window, the spectral weighting and the scaling on the device.
+- `ExactFormer` on CUDA halves its pulses per chunk on an out-of-memory error instead of failing (with a
+  `MemoryWarning`).
+- Environment variables `FASTSAR_SHARED_PROFILES`, `FASTSAR_WEIGHT_TERMS`, `FASTSAR_WEIGHT_GRAD`,
+  `FASTSAR_MOSAIC_PREFETCH`, `FASTSAR_COMPILE_PATCHES`, `FASTSAR_PULSE_SLACK`, `FASTSAR_CPU_GROUP_GB`,
+  `FASTSAR_CUDA_GROUP`, `FASTSAR_TPU_GROUP`, `FASTSAR_CUDA_STREAM` and `FASTSAR_TIMING`
+  ([performance.md](docs/performance.md#environment-variables)); numeric values out of range raise `ValueError`.
+- `examples/chain.py`.
+
+### Changed
+
+- `read_cphd`'s local frame takes z along the ellipsoid normal at the scene reference point instead of the
+  geocentric radial (up to 0.19 degrees apart). `form_cphd`'s ground plane is now horizontal at the scene, as
+  documented; its comparisons with vendor images in `docs/real-data.md` were measured before this change.
+- `read_cphd`'s meta carries the collection start, collector and core name.
+- `form_cphd` references a spotlight history to |ant - c|, the range to the grid center, so its images change.
+- JAX and TPU mosaics widen range gates onto shared lengths, so their images differ slightly from before.
+- `FASTSAR_MOSAIC_PREFETCH` defaults to up to 4 worker threads on a GPU or TPU (1 before; still 1 on the CPU).
+- The JAX program cache holds 32 programs instead of 16.
+- CUDA float32 histories are no longer scaled to their peak.
+- The CUDA former windows and checks a host history on the GPU as its row blocks are uploaded, without a full
+  complex copy on the device (host-side windowing cost a 4-vCPU instance more than the formation); `ExactFormer`
+  scans for NaN and inf on the GPU.
+- Importing FastSAR sets `XLA_PYTHON_CLIENT_PREALLOCATE=false` unless already set, so that JAX does not take 75% of
+  a GPU's memory that the CUDA formers share.
+- CPU first-level groups follow the available memory (MemAvailable), so they vary on a busy host.
+- `form_image`, `ImageFormer`, `backproject`, `patches.form_mosaic`, `io.read_cphd` and `form_cphd` check their
+  inputs: a phase history that is not 2-D or not complex, has NaN or inf samples, fewer than 2 pulses or a pulse
+  count different from the antenna path; antenna positions not [pulses, 3]; pixel counts that are not positive
+  integers, non-positive spacings, axes that are not orthonormal; unknown backends, and `cuda` or `tpu` on a
+  machine without one, raise `ValueError` or `TypeError` with the reason. complex128 and non-contiguous histories
+  are converted.
+
+### Fixed
+
+- An all-zero phase history gave a NaN image on the JAX and TPU paths and with polar format, and a
+  ZeroDivisionError on the CPU path; it now gives a zero image.
+- `api.final_weights` gave weight zero to the final subapertures centered beyond the collection, which hold the
+  decimation filters' tails of the edge pulses: a unit `aperture_weight` changed the image by -32 dB. They now
+  take the weight of the nearest pulse, and a unit weight leaves the image unchanged.
+- `ffbp2.decimator_fir` differed from the column of `ffbp.decimator` by up to 3e-16; it is now equal bit for bit.
+- `backproject` with a `ref` shorter than the pulse count read past its end in the C++ kernel.
+- `patches.fill_gaps` divided by zero for a single position or a platform at rest.
+- `sim.simulate_brute` held a [pulses, samples, scatterers] array (5.8 GB for the dropped-pulse case of
+  `tests/test_patches.py`); it now sums in blocks of scatterers.
+- A failure while the mosaic prefetches the next patch now shuts its thread down.
+
+### Tests
+
+- `tests/run_all.py` runs every test script with a timeout and a memory limit and prints a summary.
+- `tests/test_units.py`: decimation kernels, the JAX program cache, the C++ input paths and group sizes, aperture
+  weights, shared range profiles, pulse spans, gap filling, mosaic prefetch, input checks, `ref=`.
+- `tests/test_cphd.py`: `read_cphd` and `form_cphd` end to end on simulated spotlight and stripmap collections
+  through a stand-in for sarpy's CPHD reader.
+- `tests/test_chain.py`: a simulated CPHD through geolocation, map GeoTIFFs, SICD and autofocus.
+- `tests/test_planning.py`: bucket planning, the CUDA and TPU memory models, the TPU out-of-memory retry, the
+  program cache under concurrent formers, and environment variable checks.
+- `tests/test_accuracy.py`: the tile-size and oversampling figures of `docs/algorithms.md`.
+
+### Documentation
+
+- Processing-chain page and API reference; README reduced to a landing page with a supported-data table.
+- Documentation matches the geolocation, map GeoTIFF, SICD and autofocus calls for `form_cphd` output; each fact
+  stated on one page.
+- Shorter README with figures; the long-form material moved to `docs/`.
+- Contributing guide, issue and pull request templates, and package metadata for PyPI-style tools.
+
+### Initial functionality
+
+- Spotlight image formation by factorized backprojection with kernels for x86 CPUs (C++/OpenMP), Nvidia GPUs
+  (CUDA through CuPy) and Cloud TPUs (Pallas), and the plain JAX program; `form_image` and `ImageFormer`.
+- Final tile size chosen from the predicted error of the collection geometry.
+- Polar format with the planar-wavefront displacement correction.
+- Exact backprojection onto arbitrary points, monostatic or bistatic, with per-pulse reference ranges.
+- CPHD reader: per-pulse frequency grids, moving reference points, channels and polarizations, SICD pixel-grid
+  alignment, troposphere delay, Capella phase sign, a warning for delay windows beyond the unambiguous range.
+- Phase gradient autofocus.
+- Stripmap focusing (range-Doppler, omega-k, backprojection), patch mosaics for long apertures and arbitrary
+  tracks, ScanSAR and TOPS burst modes.
+- Products: multilook, interferogram, coherence, Pauli decomposition, range-Doppler projection and geocoding,
+  GeoTIFF and SICD output.

fastsar-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to FastSAR
+
+Bug reports, questions and pull requests are welcome. Please open an issue first for a change that touches a
+kernel or the public API, so the approach can be agreed before the code is written.
+
+## Development setup
+
+```bash
+git clone https://github.com/saulpingerman/FastSAR
+cd FastSAR
+pip install -e ".[io,test]"     # add cuda on a machine with an Nvidia GPU: ".[cuda,io,test]"
+```
+
+or `uv sync`, which installs the versions pinned in `uv.lock`. The CPU backend needs `g++` with OpenMP. Some
+tests need packages that are not dependencies of the library: `finufft` (`tests/test_insar.py`), `rasterio`
+(`products.write_geotiff`, `read_dem` and map projections other than latitude/longitude) and `sarkit` (optional
+consistency checks in `tests/test_chain.py`).
+
+## Running the tests
+
+The tests are plain scripts, not pytest functions. Each prints its measurements, stops with an `AssertionError`
+when a check fails, and exits 0 when it passes. Run them from the repository root:
+
+```bash
+python tests/run_all.py            # every script below, with a timeout and a memory limit, and a summary
+python tests/test_api.py           # every backend this machine has against the JAX program, and polar format
+python tests/test_ffbp_cpu.py      # C++ kernels against the dense JAX image, two and three levels
+python tests/test_ffbp_cuda.py     # CUDA kernels against the dense JAX image (needs a GPU)
+python tests/test_pallas_fused.py  # TPU level kernel in interpret mode (runs on a CPU)
+python tests/test_pallas_final.py  # TPU final-stage kernel in interpret mode (runs on a CPU)
+python tests/test_pallas_e2e_tpu.py  # TPU kernels end to end in interpret mode (runs on a CPU)
+python tests/test_autofocus.py cpu # phase gradient autofocus; the argument is the backend (default jax)
+python tests/test_stripmap.py      # stripmap omega-k and RDA against float64 backprojection
+python tests/test_patches.py       # patch mosaics for stripmap and non-linear tracks
+python tests/test_burst.py         # ScanSAR and TOPS burst focusing
+python tests/test_products.py      # layover projection, geocoding, multilooking, Pauli
+python tests/test_bp.py            # exact backprojection: backends, bistatic, orbital range, moving reference
+python tests/test_io.py            # CPHD helpers: frequency resampling, re-referencing, geodetic conversions
+python tests/test_wide_angle.py    # 10 to 360 degree apertures against exact backprojection
+python tests/test_insar.py         # change detection and interferometric height (needs finufft)
+python tests/test_chain.py         # simulated CPHD to geolocation, map GeoTIFFs, SICD and autofocus (needs sarpy, rasterio)
+python tests/test_exact.py         # ExactFormer: 1 to 600 km and a wide near-range grid against backprojection, validation
+python tests/test_units.py         # filters, program cache, aperture weights, mosaic pieces, input checks
+python tests/test_cphd.py          # read_cphd and form_cphd on simulated collections (stand-in CPHD reader)
+python tests/test_planning.py      # bucket planning, memory models, TPU out-of-memory retry, program cache
+python tests/test_accuracy.py      # tile-size and oversampling errors against exact backprojection
+```
+
+`run_all.py` reports SKIP for a script that needs hardware this machine lacks (`test_ffbp_cuda.py` without a GPU);
+`--require cuda,tpu` makes that a failure. A script whose test package is missing fails; install them with
+`pip install -e ".[io,test]"`. It stops a script that runs past `-t` seconds (default 600) or holds more than
+`--max-rss-gb` of memory (default 6 GB, 12 GB on a TPU host, whose runtime holds about 5 GB; or `FASTSAR_TEST_MAX_GB`), and exits non-zero if any script fails. `-v` prints
+every script's output.
+
+`test_autofocus.py` is the only script that takes a backend argument. The others pick the backends this machine
+has (`fastsar.available_backends()`) or use the CPU. The tests use small simulated scenes and take seconds to a few
+minutes each. For the CPU kernels, set `OMP_NUM_THREADS` to the number of physical cores.
+
+`test_ffbp_cpu.py`, `test_ffbp_cuda.py` and the three `test_pallas_*.py` scripts compare each error with a limit
+set about 5 dB above the value measured when the limit was set, and exit with a list of the failed cases.
+
+## Pull requests
+
+- Keep a pull request to one change, and state in the description which tests ran and on which devices.
+- A change to a kernel should report the error against the JAX program or exact backprojection before and after,
+  as the tests print it.
+- A change that adds a result to the documentation should say what data it comes from. Results from simulated
+  data are labeled as test results.
+- Do not commit data files (CPHD, SICD, NITF, `.npy`) or build artifacts.
+
+## Reporting a bug
+
+Use the bug report template. Include the FastSAR commit, the backend, the device, the Python, JAX and CuPy
+versions, and if possible a script that reproduces the problem on a simulated scene (`fastsar.sim`), since radar
+data files are often large or not shareable.

fastsar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Singerman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastsar-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include CHANGELOG.md CONTRIBUTING.md
+graft tests
+graft examples
+global-exclude __pycache__ *.py[cod]

fastsar-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: fastsar
+Version: 0.1.0
+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: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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; extra == "cuda"
+Provides-Extra: io
+Requires-Dist: sarpy; extra == "io"
+Provides-Extra: tpu
+Requires-Dist: jax[tpu]; extra == "tpu"
+Provides-Extra: geo
+Requires-Dist: rasterio; extra == "geo"
+Provides-Extra: test
+Requires-Dist: sarpy; extra == "test"
+Requires-Dist: sarkit; extra == "test"
+Requires-Dist: rasterio; extra == "test"
+Requires-Dist: finufft; extra == "test"
+Dynamic: license-file
+
+# FastSAR
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/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/v0.1.0/docs/images/hero_panama.jpg)
+
+*Panama Canal, Pacific entrance (Umbra open data, 2023-07-18): 12,207 by 8,808 pixels in 3.8 s on an Nvidia L4
+(warm former, transfers included; float32, -59.9 dB against float64 exact backprojection), 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/v0.1.0/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/v0.1.0/docs/performance.md), [comparison](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/docs/comparison.md)).*
+
+## Install
+
+```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[cuda,io,geo]"   # extras combine
+```
+
+From a clone: `pip install -e ".[cuda,io]"` or `uv sync`. The CPU kernels need `g++` with OpenMP and compile on
+first use; the float16 CUDA kernel needs `nvcc`. On the CPU set
+`OMP_NUM_THREADS=<physical cores> OMP_PLACES=cores OMP_PROC_BIND=close`.
+
+## Quickstart
+
+```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/v0.1.0/examples/chain.py) runs this chain from the command line (`--simulate` needs no data);
+[`form_umbra.py`](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/examples/form_umbra.py) and [`form_capella_stripmap.py`](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/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/v0.1.0/docs/README.md) lists every page; start with the [processing chain](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/docs/processing-chain.md).
+Measurement records are in [sar-accel-study](https://github.com/saulpingerman/sar-accel-study). A citation file
+will come with the preprint.
+
+## Contributing and license
+
+[CONTRIBUTING.md](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/CONTRIBUTING.md) explains how to run the tests. MIT license ([LICENSE](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/LICENSE)).

fastsar-0.1.0/README.md

@@ -0,0 +1,80 @@
+# FastSAR
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/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/v0.1.0/docs/images/hero_panama.jpg)
+
+*Panama Canal, Pacific entrance (Umbra open data, 2023-07-18): 12,207 by 8,808 pixels in 3.8 s on an Nvidia L4
+(warm former, transfers included; float32, -59.9 dB against float64 exact backprojection), 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/v0.1.0/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/v0.1.0/docs/performance.md), [comparison](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/docs/comparison.md)).*
+
+## Install
+
+```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[cuda,io,geo]"   # extras combine
+```
+
+From a clone: `pip install -e ".[cuda,io]"` or `uv sync`. The CPU kernels need `g++` with OpenMP and compile on
+first use; the float16 CUDA kernel needs `nvcc`. On the CPU set
+`OMP_NUM_THREADS=<physical cores> OMP_PLACES=cores OMP_PROC_BIND=close`.
+
+## Quickstart
+
+```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/v0.1.0/examples/chain.py) runs this chain from the command line (`--simulate` needs no data);
+[`form_umbra.py`](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/examples/form_umbra.py) and [`form_capella_stripmap.py`](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/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/v0.1.0/docs/README.md) lists every page; start with the [processing chain](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/docs/processing-chain.md).
+Measurement records are in [sar-accel-study](https://github.com/saulpingerman/sar-accel-study). A citation file
+will come with the preprint.
+
+## Contributing and license
+
+[CONTRIBUTING.md](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/CONTRIBUTING.md) explains how to run the tests. MIT license ([LICENSE](https://github.com/saulpingerman/FastSAR/blob/v0.1.0/LICENSE)).

fastsar-0.1.0/examples/chain.py

@@ -0,0 +1,76 @@
+"""From a CPHD file to products: a complex SICD with its geometry, a map-projected amplitude GeoTIFF (dB, UTM) and a
+PNG quicklook of it.
+
+    python examples/chain.py scene_CPHD.cphd out [--sicd scene_SICD.ntf] [--dem dem.tif --geoid 31.5] [--autofocus]
+    python examples/chain.py --simulate out          # writes a small simulated collection to out_sim.cphd first
+
+Writes out.nitf (SICD), out_db.tif and out_db.png. --looks sets the multilooking (along track, across track) before
+detection; --dem a DEM GeoTIFF for terrain correction, with --geoid the geoid's height above the ellipsoid at the
+scene when the DEM gives heights above the geoid (without --dem the map lies at the image center's height).
+"""
+import argparse, time
+
+import numpy as np
+
+import fastsar
+from fastsar import products, sim
+
+
+def simulate(path):
+    """A 100 m spotlight scene at 6 km (0.5 m resolution): a 3 x 3 grid of point targets over weak clutter."""
+    rng = np.random.default_rng(0)
+    col = sim.make_collect(res=0.5, scene=100.0, r0=6e3, graze_deg=35.0)
+    g = np.linspace(-30.0, 30.0, 3)
+    pts = np.stack([*np.meshgrid(g, g), np.zeros((3, 3))], -1).reshape(-1, 3)
+    cl = np.concatenate([rng.uniform(-45, 45, (3000, 2)), np.zeros((3000, 1))], 1)
+    pos = np.concatenate([pts, cl])
+    amp = np.concatenate([np.full(9, 30.0), 0.5 * (rng.standard_normal(3000) + 1j * rng.standard_normal(3000))])
+    S = sum(sim.simulate_brute(col, pos[i:i + 50], amp[i:i + 50]) for i in range(0, len(pos), 50))
+    sim.write_cphd(path, col, S.astype(np.complex64), lat=40.7934, lon=-77.86, height=351.0, heading=30.0)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('cphd', nargs='?'); ap.add_argument('out')
+    ap.add_argument('--simulate', action='store_true'); ap.add_argument('--sicd')
+    ap.add_argument('--dem'); ap.add_argument('--geoid', type=float, default=0.0)
+    ap.add_argument('--autofocus', action='store_true'); ap.add_argument('--backend', default='auto')
+    ap.add_argument('--looks', type=int, nargs=2, default=(2, 2)); ap.add_argument('--spacing', type=float)
+    a = ap.parse_args()
+    if a.simulate:
+        a.cphd = a.out + '_sim.cphd'
+        simulate(a.cphd)
+    t = time.perf_counter()
+    out = fastsar.form_cphd(a.cphd, sicd=a.sicd, backend=a.backend, autofocus=a.autofocus)
+    img = out['image']
+    print(f'{out["mode"]} image {img.shape}, {out["spx"]:.3f} x {out["spy"]:.3f} m pixels, '
+          f'{time.perf_counter() - t:.1f} s')
+    for n in out['notes']:
+        print('  ' + n)
+    nx, ny = img.shape
+    lat, lon, h = products.geolocate(out, [0, 0, nx - 1, nx - 1, nx / 2], [0, ny - 1, 0, ny - 1, ny / 2])
+    print('corners and center (lat, lon, height on the image plane):')
+    for v in zip(lat, lon, h):
+        print('  %.6f %.6f %.1f' % v)
+
+    products.write_sicd(a.out + '.nitf', out)
+    dem = products.read_dem(a.dem, offset=a.geoid) if a.dem else None
+    power = products.multilook(img, *a.looks)
+    geo = products.geocode_image(out, power, spacing=a.spacing, height=dem)
+    geo['data'] = products.to_db(geo['data'])
+    products.write_geotiff(a.out + '_db.tif', **geo)
+    print(f'wrote {a.out}.nitf and {a.out}_db.tif ({geo["crs"]}, {geo["data"].shape[1]} x {geo["data"].shape[0]})')
+    try:
+        import matplotlib
+        matplotlib.use('Agg')
+        import matplotlib.pyplot as plt
+        db = geo['data']
+        top = np.nanpercentile(db, 99.5)
+        plt.imsave(a.out + '_db.png', np.nan_to_num(db, nan=top - 40), cmap='gray', vmin=top - 40, vmax=top)
+        print(f'wrote {a.out}_db.png (north up)')
+    except ImportError:
+        print('no matplotlib: PNG skipped')
+
+
+if __name__ == '__main__':
+    main()

fastsar-0.1.0/examples/form_capella_stripmap.py

@@ -0,0 +1,64 @@
+"""Form a crop of a Capella stripmap collection from its CPHD with the patch mosaic, sample it on the pixels of the
+vendor's SICD (a range / zero-Doppler grid) and compare the two amplitude images.
+
+    python examples/form_capella_stripmap.py scene_CPHD.cphd scene_SICD.ntf out [--size 512] [--backend cpu]
+
+The scene reference point of a stripmap CPHD moves with the beam; read_cphd re-references the phase history to the
+mid-aperture point, and each pulse's own point gives the beam center. The beam's extent along track is the azimuth
+bandwidth the vendor processed (SICD Grid.Col.ImpRespBW).
+"""
+import argparse, time
+
+import numpy as np
+
+import fastsar
+from fastsar import io, patches, products
+
+C = 299792458.0
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('cphd'); ap.add_argument('sicd'); ap.add_argument('out')
+    ap.add_argument('--size', type=int, default=512); ap.add_argument('--backend', default='cpu')
+    ap.add_argument('--spacing', type=float, default=0.35)
+    a = ap.parse_args()
+    from sarpy.io.complex.converter import open_complex
+    from sarpy.io.phase_history.converter import open_phase_history
+    col, meta = io.read_cphd(a.cphd, meta=True)
+    S, ant, f0, df = col['S'], col['ant'], col['fmin'], col['df']
+    P, K = S.shape
+    srp = io.ecf_to_local(open_phase_history(a.cphd).read_pvp_variable('SRPPos', 0), meta)
+    lo, hi = meta['pulses']                      # the pulses read_cphd kept
+    srp = srp[lo:hi]
+    rd = open_complex(a.sicd)
+    sm = rd.sicd_meta
+    dsin = float(sm.Grid.Col.ImpRespBW) * C / (f0 + K / 2 * df) / 2      # processed spread of sin(look angle)
+    d = np.gradient(ant, axis=0)
+    d /= np.linalg.norm(d, axis=1, keepdims=True)
+    s_c = ((srp - ant) * d).sum(1) / np.linalg.norm(srp - ant, axis=1)        # beam center of each pulse
+
+    def beam(idx, pts):
+        w = np.asarray(pts)[None] - ant[idx][:, None]
+        return ((w * d[idx][:, None]).sum(-1) / np.linalg.norm(w, axis=-1) - s_c[idx][:, None]) / (dsin / 2)
+
+    n = a.size
+    r0, c0 = int(sm.ImageData.NumRows) // 2 - n // 2, int(sm.ImageData.NumCols) // 2 - n // 2
+    rr, cc = np.meshgrid(np.arange(r0, r0 + n), np.arange(c0, c0 + n), indexing='ij')
+    pts = io.sicd_points(sm, rr, cc, meta)
+    e1, e2 = np.array([1.0, 0, 0]), np.array([0, 1.0, 0])
+    lo, hi = pts.reshape(-1, 3).min(0), pts.reshape(-1, 3).max(0)
+    origin = np.array([lo[0] - 5, lo[1] - 5, pts[..., 2].mean()])
+    nx, ny = int((hi[0] - lo[0] + 10) / a.spacing), int((hi[1] - lo[1] + 10) / a.spacing)
+    t = time.perf_counter()
+    img = patches.form_mosaic(dict(S=S, fmin=f0, df=df, ref=meta['ref'], band=(f0, f0 + K * df)), ant, origin, nx, ny,
+                              a.spacing, a.spacing, e1, e2, beam=beam, backend=a.backend)
+    print(f'{nx} x {ny} ground pixels formed in {time.perf_counter() - t:.0f} s')
+    ours = products.sample(img, np.stack([(pts - origin) @ e1 / a.spacing, (pts - origin) @ e2 / a.spacing], -1))
+    v = rd[r0:r0 + n, c0:c0 + n]
+    print(f'amplitude correlation with the vendor image: {np.corrcoef(np.abs(ours).ravel(), np.abs(v).ravel())[0, 1]:.3f}')
+    np.save(a.out + '.npy', ours)
+
+
+if __name__ == '__main__':
+    main()

fastsar-0.1.0/examples/form_umbra.py

@@ -0,0 +1,33 @@
+"""Form an Umbra spotlight image on the vendor's grid and save it as a complex64 .npy and an amplitude PNG.
+
+    python examples/form_umbra.py scene_CPHD.cphd scene_SICD.nitf out [--backend cpu] [--precision float32]
+"""
+import argparse, time
+
+import numpy as np
+
+import fastsar
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('cphd'); ap.add_argument('sicd'); ap.add_argument('out')
+    ap.add_argument('--backend', default='auto'); ap.add_argument('--precision', default='float32')
+    ap.add_argument('--algorithm', default='ffbp')
+    a = ap.parse_args()
+    col = fastsar.io.read_cphd(a.cphd, sicd=a.sicd)
+    print('pulses, samples', col['S'].shape, 'grid', col['nx'], col['ny'], 'backends', fastsar.available_backends())
+    t = time.perf_counter()
+    img = fastsar.form_image(**col, algorithm=a.algorithm, backend=a.backend, precision=a.precision)
+    print(f'formed in {time.perf_counter() - t:.1f} s (includes compilation on the first call)')
+    np.save(a.out + '.npy', img)
+    try:
+        import matplotlib; matplotlib.use('Agg'); import matplotlib.pyplot as plt
+        db = 20 * np.log10(np.abs(img) + 1e-12); top = np.percentile(db, 99.9)
+        plt.imsave(a.out + '.png', np.clip(db.T, top - 45, top), cmap='gray', vmin=top - 45, vmax=top, origin='lower')
+    except ImportError:
+        pass
+
+
+if __name__ == '__main__':
+    main()

fastsar-0.1.0/fastsar/__init__.py

@@ -0,0 +1,16 @@
+"""Fast spotlight SAR image formation: factorized backprojection with kernels for Cloud TPUs (Pallas), Nvidia GPUs
+(CUDA) and x86 CPUs (C++/OpenMP), and polar format with its geometric resampling.  See fastsar.api.form_image."""
+import os as _os
+
+# JAX takes 75% of a GPU's memory when it first runs there unless told otherwise; FastSAR's CUDA kernels (CuPy) and
+# its JAX programs share the GPU, so JAX allocates as it goes (a setting the user made before importing JAX stands);
+# JAX keeps what it has allocated, and the CuPy formers shrink their working sets to what is left
+_os.environ.setdefault('XLA_PYTHON_CLIENT_PREALLOCATE', 'false')
+from .api import form_image, available_backends, ImageFormer  # noqa: F401
+from . import io, autofocus, stripmap, burst, patches, quality, products  # noqa: F401
+from .bp import backproject, plane_points  # noqa: F401
+from .exact import ExactFormer  # noqa: F401
+from .cphd import form_cphd  # noqa: F401
+from .memory import MemoryWarning  # noqa: F401
+
+__version__ = '0.1.0'