Changelog¶
All notable changes to this project are documented here. The format follows Keep a Changelog and the project uses Semantic Versioning.
[0.4.3] - 2026-11-18¶
Models, weights and default outputs are unchanged; the benchmark numbers of 0.4.1 still apply.
Added¶
super_resolve(..., window=(row, col, height, width))orbounds=(left, bottom, right, top)(CLI--window,--bounds) processes part of a large GeoTIFF without reading the rest; the_scl.tifsidecar is read over the same area.Result.load(path)reopens a saved result..npzsaves now keep every layer (x_base,prior,context), the georeference, consistency, metadata and calibration; GeoTIFFs store the run information in aSYNAPSE_SRtag.Result.to_xarray(dataset=True): anxarray.Datasetwith every layer. Withrioxarrayinstalled the CRS and transform are written the rioxarray way.synapse_sr.clear_cache()releases the modelssuper_resolvekeeps loaded.- A memory check before any work: a scene whose 2 m output cannot fit raises a
MemoryErrorthat says how large a part fits (SYNAPSE_SR_PREFLIGHT=0skips it). SYNAPSE_SR_MEMORY(GB) sets the tiling budget on any device;HF_ENDPOINTpoints the weight download at a mirror;SYNAPSE_OFFLINE=1(orHF_HUB_OFFLINE=1) never downloads.fetch_sentinel2(..., rank="local")(default, CLI--rank) picks the scene with the fewest cloud, shadow and no-data pixels over the requested area, not over the whole tile, and records that fraction in theAREA_INVALID_FRACTIONtag.super_resolve_folder(..., with_confidence=, preview_dir=, verbose=).- Python 3.13 and 3.14 in the classifiers and in continuous integration; CLI and edge-case test suites.
Changed¶
- The CPU tiling budget is half the available RAM, at most 6 GB as before, so 8 GB laptops and Colab no longer plan tiles for memory they do not have.
- Flash picks Apple MPS automatically when there is no CUDA GPU; if an operation is missing there it warns once and
finishes on the CPU.
device="mps"still raises. - Weight downloads retry up to four times and resume an interrupted file. The SHA-256 of a cached checkpoint is remembered next to it and recomputed only when the file changes (a small saving: the checkpoints are 12-58 MB).
synapse-sr[all]addsrioxarray,psutil,openvinoandonnxruntime(the latter not on Intel Macs);synapse-sr[xarray]addsrioxarray.- Folder runs process
.tifand.tiffin any letter case. - Python 3.8 is no longer declared as supported (
requires-python >= 3.9); it was not tested since 0.4.0.
Fixed¶
synapse-sr folder/ out/ --jsonprinted its per-file lines on stdout, so the JSON could not be parsed; they go to stderr now.--no-confidence,--previewand--quietwere ignored in folder mode.- A failing OpenVINO / ONNX Runtime / TensorRT window silently fell back to PyTorch. It still falls back (same
model) but warns once and counts the windows in
metadata["detail_backend_fallbacks"]. - An SCL raster finer than the scene crashed, and the SCL scale was taken from the height only. Coarser SCL is sampled nearest, finer SCL marks a pixel invalid when any SCL pixel inside it is, and a different aspect ratio raises.
- Saved GeoTIFFs wrote NaN for invalid pixels without declaring it as NoData, so GIS software showed them as
pixels; NaN is now the declared NoData, and
ERRSCALE_*is NaN there too. change()compared only array shapes: two scenes of the same size in different places were differenced. It now requires the same CRS and geotransform.- Reflectance input with a few pixels above 2 (hot or saturated pixels) was taken for DN and divided by 10000. Float input is now judged on its 99.9th percentile and integer input is always DN.
--fetch/fetch_sentinel2now reject swapped or out-of-range coordinates, malformed or reversed dates and dates before Sentinel-2, before any download.- Weight downloads cut off without a network error were accepted as complete (and then failed the checksum).
[0.4.2] - 2026-11-18¶
Added¶
- Optional OpenVINO and ONNX Runtime backends for the Flash detail network (
enable_openvino,enable_onnxruntime,enable_tensorrt) with--backend/--backend-deviceon the CLI. The physics pipeline stays in PyTorch. - Hardware compatibility guide covering PyTorch CPU/CUDA/ROCm/MPS, OpenVINO, ONNX Runtime and TensorRT.
- CUDA, ONNX Runtime CUDA and TensorRT validated on 2× NVIDIA T4; Pro runs natively on CUDA.
synapse-sr --envnow reports OpenVINO and ONNX Runtime availability.
Fixed¶
- The bad-band consistency warning now scales with the requested
discrepancy(5 tau for Pro, 20 tau for Flash) instead of always using Flash's 20 tau, and names the offending bands with their measured values.
[0.4.1] - 2026-09-28¶
Changed¶
- Benchmark: SYNAPSE is now best on five of the seven official opensr-test columns (means over NAIP, SPOT, Spain-urban, Spain-crops, VENuS; 178 scenes). Pro: improvement 0.199, spectral error 0.223, reflectance error 0.0011. Flash: detail correlation 0.300, RMSE 0.0234.
- Flash restores each 10 m pixel's measured mean reflectance with a smooth bicubic correction after the physics
projection (
super_resolve(..., restore_mean=True), its new default). The correction is counted inx_base, soprioris still exactly the network's contribution. - Pro fits the measurement tightly by default (
discrepancy=0.5) for the most recovered detail.discrepancy=4, restore_mean=Falsereproduces 0.4.0 for either model. - Both checkpoints recalibrated for the new defaults: Pro 82 / 91 / 96 % and Flash 82 / 91 / 95 % coverage at 80 / 90 / 95 % on held-out references.
Fixed¶
- Intel Macs: numpy is pinned below 2 there, because the last PyTorch built for Intel macOS (2.2.2) needs numpy 1. Continuous integration now runs the published-weights suite on an Intel Mac runner.
[0.4.0] - 2026-09-28¶
Added¶
- SYNAPSE Flash v1 released and now the default model. It runs a 1.28 km scene in about 1 s on a laptop CPU and a
10 km x 10 km scene in about 14 s. It matches Pro on the official opensr-test benchmark (knowledge distillation from Pro;
trained on real Sentinel-2 / NAIP pairs, a streamed NAIP corpus and ISRO Cartosat-derived pairs). It ships with
calibrated uncertainty (82 / 91 / 95 % coverage at 80 / 90 / 95 %). Pro stays one argument away:
model="pro". synapse_sr.super_resolve_folder(src_dir, out_dir)andsynapse-sr in_dir/ out_dir/: batch a folder, skip cloud sidecars and existing outputs, and keep going past a bad file.synapse-sr --fetch LAT,LON --dates START:END out.tif: download and super-resolve in one command.Result.save(..., cog=True)/--cog: Cloud-Optimised GeoTIFF with overviews.Result.quicklook("preview.png")/--preview: side-by-side 10 m / 2 m / support preview.super_resolve(..., tta=True): test-time augmentation over 8 flips / rotations (small accuracy gain).super_resolve(..., discrepancy=): how tightly the physics baseline fits the measurement.- Documentation: cheat sheet, benchmark table in the README,
llms.txt/llms-full.txtfor AI assistants,AGENTS.md,CITATION.cff; every documentation example is executed in CI-like runs. tools/stress.py: 27-case stress suite with the published weights.
Changed¶
- Physics baseline: one regularisation weight for all bands, fitted to 4x the L2A sensor noise (it absorbs forward-model error). This strongly reduces hallucinated detail and spectral-angle error on the official benchmark (VENuS hallucination 0.351 -> 0.198). The consistency readout is correspondingly a few noise units.
- Memory-aware tiling: tile and batch sizes follow free GPU memory (or a RAM budget on CPU). Pro is about 2.5x faster.
- Uncertainty calibration refitted for the new physics defaults (Pro 82 / 91 / 96 %).
Fixed¶
- Some Earth Search Sentinel-2 items flag the baseline-04.00 offset as not applied when it already was. Such scenes
were read about 0.1 reflectance too dark. The offset is now decided from the pixel values (with a warning),
in
fetch_sentinel2and for tagged GeoTIFFs; an explicitoffset=is always respected. - NaN / inf inputs are masked instead of zeroed. Outputs are clamped to [0, 1.5] reflectance, and clamped pixels
get LOW support. Consistency is NaN when no pixel is valid.
halo >= tileraises. Saving array input to.tifraises instead of silently writing.npz.torch.cuda.mem_get_infoworks on torch < 2.1. - Flash: the confidence head no longer steers the network body.
[0.3.0] - 2026-09-24¶
Added¶
- SYNAPSE Flash (
synapse_sr.Flash,--model flash): a re-parameterised SPAN-style CNN on the same observation-consistent pipeline, for CPUs, laptops, integrated graphics, Apple silicon and ARM. Weights are not released yet;Pro.from_pretrained(weights=...)recognises Flash checkpoints automatically. - Triton selective-scan kernel: Pro runs its Mamba layers at GPU speed on Colab, Kaggle and any CUDA machine
with Triton, with no
mamba-ssmbuild. It is self-tested against the exact scan once per process. - Live feedback (Rich): progress bar with stages and tile counts, download bar, one-line result summary;
automatic in terminals and notebooks, silent when piped (
progress=,SYNAPSE_SR_QUIET=1). Result.summary(),Result.show()(matplotlib panels: image, x_base, prior, support, uncertainty, NDVI) and a conciserepr.- CLI:
--models,--json,--batch,--quiet;--envshows CPU threads, MPS, and the scan backend Pro will use. - Quick-start notebook for Colab and Kaggle; new guides: Colab and Kaggle, Choosing a model and a device.
- Tests for every fast path against its exact reference (operator, scan at extreme decay rates, preconditioned solvers, Triton, Flash re-parameterisation and checkpoint dispatch).
Changed¶
- Pro is 3-4x faster with unchanged outputs.
- The Sentinel-2 forward operator is evaluated as one strided convolution on the 2 m grid. This is algebraically identical to the 0.5 m fine-grid form and about 100x faster.
- The physics solves (lambda calibration, Tikhonov baseline, null-space projection) use conjugate gradients preconditioned with the operator's closed-form periodic inverse. The answers are the same and fewer iterations are needed.
- The PyTorch scan is rewritten as elementwise operations plus a cumulative sum in float32: no chunk matrices, and memory bounded at any batch size.
- Equal-size tiles and calibration windows are batched.
- End-to-end check against 0.2.0 on a real scene: x_base within 3e-5, the image within bf16 rounding (0.002).
- The CLI prints a summary table; JSON output is now behind
--json. richis a dependency.
Fixed¶
fetch_sentinel2applied the processing-baseline 04.00 offset to Earth Search scenes that already had it removed (earthsearch:boa_offset_applied). Scenes came out 0.1 reflectance too dark and dark surfaces went negative. Re-download scenes fetched with 0.2.0.- Normalised-difference indices are NaN where both bands are essentially dark and are clipped to [-1, 1]; EVI is
clipped to [-1, 1]; negative L2A reflectance counts as zero.
change()excludes pixels whose index is undefined. - Windows consoles without UTF-8 get ASCII symbols instead of garbled characters.
Corrected claim¶
- The effective-resolution statement made in 0.2.0 is withdrawn. No effective-resolution figure is claimed.
[0.2.0] - 2026-09-23¶
Added¶
- Application layer:
Result.indices()(NDVI, SAVI, EVI, GNDVI, NDWI; with 20 m context NDRE, NDBI, NBR, MNDWI),Result.band(), 20 m context bands on the output grid (context=True, labelled not super-resolved),synapse_sr.change()(support-aware change detection) andsynapse_sr.boundaries()(field, water, urban). - Calibrated uncertainty:
Result.uncertainty()andResult.interval(level)from a checkpoint-shipped error model with split-conformal coverage (Pro v1: 82 / 91 / 96 % at 80 / 90 / 95 %). - Local checkpoints matching a registered model (by SHA-256) receive that model's calibration.
- Documentation: Applications page; calibrated-uncertainty guide.
Changed¶
- Default model is now SYNAPSE Pro v2 (
pro-v2, 5000 training steps): best field / urban / water edge F1 on the development benchmark, calibrated uncertainty shipped. Known limitation: low-contrast wide strips (about 24 m) can be split by a false gap.pro-v1remains available. - The CLI
--modeldefault follows the registry default. - The 20 m context stem is zero-initialised without a scalar gate; Pro v1 checkpoints load unchanged (gate folded).
- The frequency mixer pads in float32.
scipyis now a dependency.
[0.1.0] - 2026-09-23¶
Added¶
Promodel interface:from_pretrained,super_resolve,save_pretrained,to.synapse_sr.super_resolveone-call function with a cached default model.- Inputs: GeoTIFF paths, numpy arrays, torch tensors and xarray DataArrays; DN or reflectance; automatic band
mapping (10-, 12- and 13-band layouts or band names) and
BOA_ADD_OFFSEThandling. - Preprocessing: NoData, NaN and Sentinel-2 SCL masking (automatic
<input>_scl.tifpick-up), grid validation, seamless tiling with context halo for any scene size. Resultwith reflectance, error scale, support classes, validity mask, round-trip consistency, observed / inferred decomposition,rgb(),ndvi(),to_xarray()and GeoTIFF / npz export.fetch_sentinel2STAC helper (synapse-sr[stac]).synapse-srcommand line andpython -m synapse_sr, with--envdiagnostics and--version.- Fused
mamba-ssmselective scan when available, with a verified PyTorch fallback. - SYNAPSE Pro v1 research-preview checkpoint on Hugging Face.