geoswe 1.0.0__tar.gz

geoswe-1.0.0/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: "If you use GeoSWE in your research, please cite it as below."
+title: "GeoSWE: Geophysical Shallow-Water Engine"
+abstract: >-
+  GeoSWE is a GPU-accelerated finite-volume solver for the 2D nonlinear
+  shallow-water equations, designed for flood modeling from coastal county to
+  continental scale. It combines HLLC/Lax-Friedrichs fluxes, well-balanced
+  surface reconstruction, implicit Manning friction, rainfall and coastal-stage
+  forcings, and a compressed active-cell mesh that reaches continental scale on
+  a single GPU node and scales across nodes with MPI.
+type: software
+authors:
+  - family-names: Chen
+    given-names: Peng
+    email: pchen402@gatech.edu
+    affiliation: "Georgia Institute of Technology"
+version: "1.0.0"
+date-released: "2026-10-06"
+license: BSD-3-Clause
+repository-code: "https://github.com/GeoSWE/geoswe"
+url: "https://geoswe.github.io/geoswe"
+keywords:
+  - shallow-water equations
+  - flood modeling
+  - GPU computing
+  - finite-volume method
+  - CuPy
+# Add a `preferred-citation:` block for the article once it is accepted
+# (title, authors, journal, year, doi), so citation tools prefer the paper.

geoswe-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Peng Chen and the GeoSWE contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

geoswe-1.0.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include LICENSE
+include README.md
+include CITATION.cff
+include environment.yml
+recursive-include src/geoswe *.py
+graft examples
+graft tests
+graft docs
+prune docs/_build
+# internal review notes and release planning stay in the repo, not the sdist
+prune docs/dev
+global-exclude __pycache__/*
+global-exclude *.py[cod]

geoswe-1.0.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: geoswe
+Version: 1.0.0
+Summary: GeoSWE (Geophysical Shallow-Water Engine): a GPU flood solver with a NumPy CPU fallback.
+Author-email: Peng Chen <pchen402@gatech.edu>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/GeoSWE/geoswe
+Project-URL: Documentation, https://geoswe.github.io/geoswe
+Project-URL: Repository, https://github.com/GeoSWE/geoswe
+Project-URL: Issues, https://github.com/GeoSWE/geoswe/issues
+Keywords: shallow-water-equations,flood-modeling,computational-fluid-dynamics,GPU,CuPy,finite-volume,HLLC,well-balanced
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x[ctk]>=14.0; extra == "gpu"
+Requires-Dist: scipy>=1.10; extra == "gpu"
+Provides-Extra: gpu-cuda13
+Requires-Dist: cupy-cuda13x[ctk]>=14.0; extra == "gpu-cuda13"
+Requires-Dist: scipy>=1.10; extra == "gpu-cuda13"
+Provides-Extra: gpu-rocm
+Requires-Dist: cupy-rocm-7-0>=14.0; extra == "gpu-rocm"
+Requires-Dist: scipy>=1.10; extra == "gpu-rocm"
+Provides-Extra: mpi
+Requires-Dist: mpi4py>=3.1; extra == "mpi"
+Provides-Extra: io
+Requires-Dist: rasterio>=1.3; extra == "io"
+Requires-Dist: pyproj>=3.5; extra == "io"
+Provides-Extra: forcings
+Requires-Dist: pandas>=2.0; extra == "forcings"
+Requires-Dist: scipy>=1.10; extra == "forcings"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: myst-parser>=2; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: all
+Requires-Dist: geoswe[forcings,gpu,io,mpi]; extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/GeoSWE/geoswe/main/docs/images/helene_cascade.gif" alt="Animation of Hurricane Helene rainfall and flood depth on three nested GeoSWE domains: CONUS at 30 m, Florida at 10 m, Pinellas County at 3 m" width="720">
+</p>
+
+<h1 align="center">GeoSWE</h1>
+<p align="center"><b>Geophysical Shallow-Water Engine</b><br>
+A GPU finite-volume solver for the full 2D shallow-water equations,<br>
+from a 3 m coastal county to the conterminous United States on one multi-GPU node.</p>
+
+<p align="center">
+  <a href="https://github.com/GeoSWE/geoswe/actions/workflows/test.yml"><img src="https://github.com/GeoSWE/geoswe/actions/workflows/test.yml/badge.svg" alt="tests"></a>
+  <a href="https://github.com/GeoSWE/geoswe/actions/workflows/lint.yml"><img src="https://github.com/GeoSWE/geoswe/actions/workflows/lint.yml/badge.svg" alt="lint"></a>
+  <a href="https://github.com/GeoSWE/geoswe/actions/workflows/docs.yml"><img src="https://github.com/GeoSWE/geoswe/actions/workflows/docs.yml/badge.svg" alt="docs"></a>
+  <a href="https://github.com/GeoSWE/geoswe/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-BSD--3--Clause-blue.svg" alt="BSD 3-Clause"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
+</p>
+
+*Above: 72 hours of Hurricane Helene (September 2024) simulated by the same code on three nested domains: MRMS rainfall in purple, flood depth in color, and the NOAA CO-OPS tide gauges that drive the coastal boundary as stars. [Full-resolution video (MP4)](https://github.com/GeoSWE/geoswe/blob/main/docs/images/helene_cascade.mp4).*
+
+---
+
+GeoSWE solves the nonlinear shallow-water equations with a well-balanced HLLC
+finite-volume scheme, Manning friction, wetting and drying, rainfall, and an
+observation-driven coastal stage boundary. Its distinguishing feature is a
+**compressed active-cell mesh**: the cells that matter (land plus a nearshore
+band) are packed into flat arrays before the run, so memory and work scale
+with the flooded landscape rather than its bounding rectangle. The same
+finite-volume kernel runs on the dense grid and on the compressed mesh, bit for
+bit. It runs on NVIDIA and AMD GPUs through [CuPy](https://cupy.dev), scales across
+GPUs with `mpi4py`, and falls back to NumPy on the CPU for prototyping and CI.
+
+## Highlights
+
+| | |
+|---|---|
+| **Continental domains on one node** | A 72-hour Hurricane Helene scenario over CONUS at 30 m (8.88 billion active cells, 207-gauge coastal boundary) runs on eight H100 GPUs in 10.8 h; Florida at 10 m (1.78 billion active cells) on four GPUs in 9.5 h. |
+| **Fastest and leanest in a four-code benchmark** | On a 214-million-cell county case against TRITON, SynxFlow, and SERGHEI, GeoSWE's active-cell configuration has the lowest wall time and GPU memory at every GPU count: 3.5 to 3.9 times faster and 1.5 to 1.9 times leaner than the nearest peer, with pairwise CSI near 0.99. |
+| **Compression without a numerical penalty** | Dense and compressed runs take identical step counts and agree to 0.05 cm RMSE (CSI 1.000) on the same cells. |
+| **Near-ideal scaling** | 99.5 % weak-scaling efficiency at 16 H100 GPUs (10.24 billion cells) and 98.8 % at 32 Blackwell MIG slices across two nodes (20.48 billion cells). |
+| **Thin-film accuracy** | On a steady rained slope with a high-accuracy reference solution, GeoSWE stays within 1 % of the reference film depth where other codes depart by tens of percent. |
+
+The application runs are computational demonstrations under stated, uncalibrated settings, not validated flood hindcasts.
+
+## How it compares
+
+<p align="center"><img src="https://raw.githubusercontent.com/GeoSWE/geoswe/main/docs/images/intro_bench.png" alt="Benchmark: per-step wall time versus peak GPU memory per code, and thin-film depth error on a rained slope" width="900"></p>
+
+*(a) Per-step wall time against peak GPU memory per rank for each code's fastest configuration on the 3 m Pinellas County benchmark (1, 2, and 4 GPUs; large marker = 4 GPUs). (b) Depth error against the steady shallow-water reference on a uniformly rained slope.*
+
+Comparison codes as benchmarked: TRITON (commit `ec35bc4`), SERGHEI (commit `39a10f2`), and SynxFlow 1.0.2; all four in fp32 at CFL 0.5, first-order well-balanced schemes, same H100 node, identical inputs. Builds, decks, and patches are in the paper's reproducibility appendix.
+
+## How it scales
+
+<p align="center"><img src="https://raw.githubusercontent.com/GeoSWE/geoswe/main/docs/images/scaling.png" alt="Strong scaling, weak scaling, and memory per rank on 1 to 16 H100 GPUs" width="900"></p>
+
+*Dense and flat storage layouts on an everywhere-wet synthetic domain, 640 million cells per GPU, 1 to 16 H100 GPUs across two nodes. Strong scaling reaches 15.5x on 16 GPUs for the flat layout; weak scaling stays above 99 %.*
+
+<p align="center"><img src="https://raw.githubusercontent.com/GeoSWE/geoswe/main/docs/images/scaling_frontier.png" alt="Weak scaling on OLCF Frontier at one billion cells per GPU: 1 to 32 GPUs, and 1 to 128 nodes with 1.024 trillion cells" width="900"></p>
+
+*The flat layout on AMD GPUs at OLCF Frontier, one billion cells per GPU (one GCD, half of an MI250X card; eight per node): time per step divided by that of the smallest size, so ideal weak scaling is the dashed line. On 128 nodes, 1.024 trillion cells advance at 162 ms per step: 98.0 % weak-scaling efficiency against one node and 96.7 % against one GPU. A marker is the mean of up to three launches, each timed over one 40-second window; see [`benchmark/frontier_amd`](https://github.com/GeoSWE/geoswe/blob/main/benchmark/frontier_amd/README.md).*
+
+## What is inside
+
+- **Numerics:** HLLC and local Lax-Friedrichs fluxes; the Xia et al. (2017) surface-reconstruction method and Audusse hydrostatic reconstruction for exact lake-at-rest balance over arbitrary bathymetry; first-order, MUSCL, and fifth-order reconstruction; forward Euler and SSP-RK3.
+- **Physics:** point-implicit Manning friction, wetting and drying, gridded rainfall, Green-Ampt infiltration, depth sinks, and an inverse-distance-weighted coastal stage ring driven by NOAA CO-OPS gauge records.
+- **Compressed active-cell mesh:** static active set chosen from terrain criteria before the run, `int16` neighbor offsets, a two-cell ghost halo, build-once caching, active-cell-balanced multi-GPU partitions, and checkpoint/restart.
+- **Backends:** CuPy on NVIDIA GPUs (CUDA) and AMD GPUs (ROCm), with a fused single-kernel time step; `mpi4py` for multi-GPU runs with GPU-aware halo exchange; and a NumPy CPU fallback that runs the same scheme in float64.
+
+## Installation
+
+```bash
+# CPU only (NumPy backend): enough for the examples, tests, and docs
+pip install geoswe
+
+# GPU on CUDA 12 or CUDA 13 drivers, multi-GPU, GeoTIFF I/O, and forcing readers
+# (installs one CuPy build with its CUDA headers; do not add a second CuPy build)
+pip install "geoswe[gpu,mpi,io,forcings]"
+
+# The same on an AMD GPU with ROCm 7
+pip install "geoswe[gpu-rocm,mpi,io,forcings]"
+
+# From a source checkout (needed for the examples and the bundled terrain)
+git clone https://github.com/GeoSWE/geoswe.git && cd geoswe
+pip install -e ".[all]"
+```
+
+The development version installs straight from the repository:
+`pip install "geoswe @ git+https://github.com/GeoSWE/geoswe.git"`.
+
+See the [installation page](https://geoswe.github.io/geoswe/installation.html) for CUDA and CuPy version notes and the conda environment, and the [AMD GPUs page](https://geoswe.github.io/geoswe/amd_gpus.html) for ROCm.
+
+## Quick start
+
+A storm on real terrain, from the repository root. The same script runs on the
+CPU (about half a minute) and on a GPU (two seconds):
+
+```python
+import numpy as np
+from geoswe import Mesh2D, Config, Solver2D, RainfallForcing
+
+# terrain and roughness: arrays indexed [x, y], elevations in metres
+case = np.load("examples/data/cookcounty_mini.npz")
+win = np.s_[336:464, 336:464]                # a 1.3 km window; use np.s_[:, :] on a GPU
+bed, manning = case["bed"][win], case["manning"][win]
+nx, ny = bed.shape
+mesh = Mesh2D(nx=nx, ny=ny, dx=float(case["dx"]), dy=float(case["dy"]))
+
+# 75 mm/h for one hour on a dry bed; water leaves freely at the edges
+rain = RainfallForcing(time_s=[0, 3600], rate_mm_h=[75, 0])
+cfg = Config(friction="manning", bc_x="fall", bc_y="fall", rainfall_forcing=rain)
+solver = Solver2D(mesh, cfg, np.zeros((3, nx, ny)), bed)
+solver.set_manning(manning)
+
+solver.run(t_end=2 * 3600)
+peak = solver.max_depth()                    # NumPy array (nx, ny), metres
+print(f"deepest water {peak.max():.2f} m; {100 * (peak > 0.05).mean():.0f}% of the area reached 5 cm")
+```
+
+`Config()` with no arguments is the production scheme of the paper (first-order
+HLLC, SRM well balancing, forward Euler, CFL 0.5). The
+[flood tutorial](https://geoswe.github.io/geoswe/flood_tutorial.html) explains each line and adds your own
+GeoTIFF terrain, a tide or surge, and the compressed active-cell mesh.
+
+[`examples/`](https://github.com/GeoSWE/geoswe/tree/main/examples) has runnable scripts for 1D and 2D dam breaks, a
+lake-at-rest check, rain on a slope, convergence order, multi-GPU scaling, a
+rain-driven flood on real terrain with bundled data, and the compressed mesh on
+that terrain.
+
+## Reproducing the paper
+
+[`benchmark/`](https://github.com/GeoSWE/geoswe/tree/main/benchmark) holds the GeoSWE-side pipeline for the paper's
+benchmark cases: the four-code Pinellas County comparison, the steady sheet-flow
+plane, and the synthetic scaling sweep. Each case ships the scripts that
+prepare the inputs, run the simulations, and produce the reported numbers; see
+[`benchmark/README.md`](https://github.com/GeoSWE/geoswe/blob/main/benchmark/README.md) for data requirements and command
+sequences. The Florida and CONUS application pipelines are not part of this
+release; they exercise the same solver paths as the Pinellas case.
+
+## Documentation
+
+User guide, configuration reference, the compressed mesh, multi-GPU runs, and
+the API reference: **https://geoswe.github.io/geoswe** (or build locally with
+`pip install ".[docs]" && sphinx-build -b html docs docs/_build`).
+
+## Citing
+
+If you use GeoSWE, please cite it; see [CITATION.cff](https://github.com/GeoSWE/geoswe/blob/main/CITATION.cff). A paper
+describing the method, the cross-code benchmark, and the county-to-continent
+applications is in preparation.
+
+## Acknowledgments
+
+This material is based upon work supported by the National Science Foundation
+under Grant No. 2325631, by a 2025 IDEaS + Cloud Hub award with support from
+Microsoft at the Georgia Institute of Technology, and by the U.S. Department of
+Energy under Contract No. DE-AC05-00OR22725 through the Genesis Mission project,
+in collaboration with Oak Ridge National Laboratory, the Tennessee Valley
+Authority, and AMD. Computing resources were provided in part by the Partnership
+for an Advanced Computing Environment (PACE) at Georgia Tech and by the Frontier
+supercomputer at the Oak Ridge Leadership Computing Facility.
+
+## License
+
+BSD 3-Clause; see [LICENSE](https://github.com/GeoSWE/geoswe/blob/main/LICENSE).

geoswe-1.0.0/README.md

@@ -0,0 +1,164 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/GeoSWE/geoswe/main/docs/images/helene_cascade.gif" alt="Animation of Hurricane Helene rainfall and flood depth on three nested GeoSWE domains: CONUS at 30 m, Florida at 10 m, Pinellas County at 3 m" width="720">
+</p>
+
+<h1 align="center">GeoSWE</h1>
+<p align="center"><b>Geophysical Shallow-Water Engine</b><br>
+A GPU finite-volume solver for the full 2D shallow-water equations,<br>
+from a 3 m coastal county to the conterminous United States on one multi-GPU node.</p>
+
+<p align="center">
+  <a href="https://github.com/GeoSWE/geoswe/actions/workflows/test.yml"><img src="https://github.com/GeoSWE/geoswe/actions/workflows/test.yml/badge.svg" alt="tests"></a>
+  <a href="https://github.com/GeoSWE/geoswe/actions/workflows/lint.yml"><img src="https://github.com/GeoSWE/geoswe/actions/workflows/lint.yml/badge.svg" alt="lint"></a>
+  <a href="https://github.com/GeoSWE/geoswe/actions/workflows/docs.yml"><img src="https://github.com/GeoSWE/geoswe/actions/workflows/docs.yml/badge.svg" alt="docs"></a>
+  <a href="https://github.com/GeoSWE/geoswe/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-BSD--3--Clause-blue.svg" alt="BSD 3-Clause"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
+</p>
+
+*Above: 72 hours of Hurricane Helene (September 2024) simulated by the same code on three nested domains: MRMS rainfall in purple, flood depth in color, and the NOAA CO-OPS tide gauges that drive the coastal boundary as stars. [Full-resolution video (MP4)](https://github.com/GeoSWE/geoswe/blob/main/docs/images/helene_cascade.mp4).*
+
+---
+
+GeoSWE solves the nonlinear shallow-water equations with a well-balanced HLLC
+finite-volume scheme, Manning friction, wetting and drying, rainfall, and an
+observation-driven coastal stage boundary. Its distinguishing feature is a
+**compressed active-cell mesh**: the cells that matter (land plus a nearshore
+band) are packed into flat arrays before the run, so memory and work scale
+with the flooded landscape rather than its bounding rectangle. The same
+finite-volume kernel runs on the dense grid and on the compressed mesh, bit for
+bit. It runs on NVIDIA and AMD GPUs through [CuPy](https://cupy.dev), scales across
+GPUs with `mpi4py`, and falls back to NumPy on the CPU for prototyping and CI.
+
+## Highlights
+
+| | |
+|---|---|
+| **Continental domains on one node** | A 72-hour Hurricane Helene scenario over CONUS at 30 m (8.88 billion active cells, 207-gauge coastal boundary) runs on eight H100 GPUs in 10.8 h; Florida at 10 m (1.78 billion active cells) on four GPUs in 9.5 h. |
+| **Fastest and leanest in a four-code benchmark** | On a 214-million-cell county case against TRITON, SynxFlow, and SERGHEI, GeoSWE's active-cell configuration has the lowest wall time and GPU memory at every GPU count: 3.5 to 3.9 times faster and 1.5 to 1.9 times leaner than the nearest peer, with pairwise CSI near 0.99. |
+| **Compression without a numerical penalty** | Dense and compressed runs take identical step counts and agree to 0.05 cm RMSE (CSI 1.000) on the same cells. |
+| **Near-ideal scaling** | 99.5 % weak-scaling efficiency at 16 H100 GPUs (10.24 billion cells) and 98.8 % at 32 Blackwell MIG slices across two nodes (20.48 billion cells). |
+| **Thin-film accuracy** | On a steady rained slope with a high-accuracy reference solution, GeoSWE stays within 1 % of the reference film depth where other codes depart by tens of percent. |
+
+The application runs are computational demonstrations under stated, uncalibrated settings, not validated flood hindcasts.
+
+## How it compares
+
+<p align="center"><img src="https://raw.githubusercontent.com/GeoSWE/geoswe/main/docs/images/intro_bench.png" alt="Benchmark: per-step wall time versus peak GPU memory per code, and thin-film depth error on a rained slope" width="900"></p>
+
+*(a) Per-step wall time against peak GPU memory per rank for each code's fastest configuration on the 3 m Pinellas County benchmark (1, 2, and 4 GPUs; large marker = 4 GPUs). (b) Depth error against the steady shallow-water reference on a uniformly rained slope.*
+
+Comparison codes as benchmarked: TRITON (commit `ec35bc4`), SERGHEI (commit `39a10f2`), and SynxFlow 1.0.2; all four in fp32 at CFL 0.5, first-order well-balanced schemes, same H100 node, identical inputs. Builds, decks, and patches are in the paper's reproducibility appendix.
+
+## How it scales
+
+<p align="center"><img src="https://raw.githubusercontent.com/GeoSWE/geoswe/main/docs/images/scaling.png" alt="Strong scaling, weak scaling, and memory per rank on 1 to 16 H100 GPUs" width="900"></p>
+
+*Dense and flat storage layouts on an everywhere-wet synthetic domain, 640 million cells per GPU, 1 to 16 H100 GPUs across two nodes. Strong scaling reaches 15.5x on 16 GPUs for the flat layout; weak scaling stays above 99 %.*
+
+<p align="center"><img src="https://raw.githubusercontent.com/GeoSWE/geoswe/main/docs/images/scaling_frontier.png" alt="Weak scaling on OLCF Frontier at one billion cells per GPU: 1 to 32 GPUs, and 1 to 128 nodes with 1.024 trillion cells" width="900"></p>
+
+*The flat layout on AMD GPUs at OLCF Frontier, one billion cells per GPU (one GCD, half of an MI250X card; eight per node): time per step divided by that of the smallest size, so ideal weak scaling is the dashed line. On 128 nodes, 1.024 trillion cells advance at 162 ms per step: 98.0 % weak-scaling efficiency against one node and 96.7 % against one GPU. A marker is the mean of up to three launches, each timed over one 40-second window; see [`benchmark/frontier_amd`](https://github.com/GeoSWE/geoswe/blob/main/benchmark/frontier_amd/README.md).*
+
+## What is inside
+
+- **Numerics:** HLLC and local Lax-Friedrichs fluxes; the Xia et al. (2017) surface-reconstruction method and Audusse hydrostatic reconstruction for exact lake-at-rest balance over arbitrary bathymetry; first-order, MUSCL, and fifth-order reconstruction; forward Euler and SSP-RK3.
+- **Physics:** point-implicit Manning friction, wetting and drying, gridded rainfall, Green-Ampt infiltration, depth sinks, and an inverse-distance-weighted coastal stage ring driven by NOAA CO-OPS gauge records.
+- **Compressed active-cell mesh:** static active set chosen from terrain criteria before the run, `int16` neighbor offsets, a two-cell ghost halo, build-once caching, active-cell-balanced multi-GPU partitions, and checkpoint/restart.
+- **Backends:** CuPy on NVIDIA GPUs (CUDA) and AMD GPUs (ROCm), with a fused single-kernel time step; `mpi4py` for multi-GPU runs with GPU-aware halo exchange; and a NumPy CPU fallback that runs the same scheme in float64.
+
+## Installation
+
+```bash
+# CPU only (NumPy backend): enough for the examples, tests, and docs
+pip install geoswe
+
+# GPU on CUDA 12 or CUDA 13 drivers, multi-GPU, GeoTIFF I/O, and forcing readers
+# (installs one CuPy build with its CUDA headers; do not add a second CuPy build)
+pip install "geoswe[gpu,mpi,io,forcings]"
+
+# The same on an AMD GPU with ROCm 7
+pip install "geoswe[gpu-rocm,mpi,io,forcings]"
+
+# From a source checkout (needed for the examples and the bundled terrain)
+git clone https://github.com/GeoSWE/geoswe.git && cd geoswe
+pip install -e ".[all]"
+```
+
+The development version installs straight from the repository:
+`pip install "geoswe @ git+https://github.com/GeoSWE/geoswe.git"`.
+
+See the [installation page](https://geoswe.github.io/geoswe/installation.html) for CUDA and CuPy version notes and the conda environment, and the [AMD GPUs page](https://geoswe.github.io/geoswe/amd_gpus.html) for ROCm.
+
+## Quick start
+
+A storm on real terrain, from the repository root. The same script runs on the
+CPU (about half a minute) and on a GPU (two seconds):
+
+```python
+import numpy as np
+from geoswe import Mesh2D, Config, Solver2D, RainfallForcing
+
+# terrain and roughness: arrays indexed [x, y], elevations in metres
+case = np.load("examples/data/cookcounty_mini.npz")
+win = np.s_[336:464, 336:464]                # a 1.3 km window; use np.s_[:, :] on a GPU
+bed, manning = case["bed"][win], case["manning"][win]
+nx, ny = bed.shape
+mesh = Mesh2D(nx=nx, ny=ny, dx=float(case["dx"]), dy=float(case["dy"]))
+
+# 75 mm/h for one hour on a dry bed; water leaves freely at the edges
+rain = RainfallForcing(time_s=[0, 3600], rate_mm_h=[75, 0])
+cfg = Config(friction="manning", bc_x="fall", bc_y="fall", rainfall_forcing=rain)
+solver = Solver2D(mesh, cfg, np.zeros((3, nx, ny)), bed)
+solver.set_manning(manning)
+
+solver.run(t_end=2 * 3600)
+peak = solver.max_depth()                    # NumPy array (nx, ny), metres
+print(f"deepest water {peak.max():.2f} m; {100 * (peak > 0.05).mean():.0f}% of the area reached 5 cm")
+```
+
+`Config()` with no arguments is the production scheme of the paper (first-order
+HLLC, SRM well balancing, forward Euler, CFL 0.5). The
+[flood tutorial](https://geoswe.github.io/geoswe/flood_tutorial.html) explains each line and adds your own
+GeoTIFF terrain, a tide or surge, and the compressed active-cell mesh.
+
+[`examples/`](https://github.com/GeoSWE/geoswe/tree/main/examples) has runnable scripts for 1D and 2D dam breaks, a
+lake-at-rest check, rain on a slope, convergence order, multi-GPU scaling, a
+rain-driven flood on real terrain with bundled data, and the compressed mesh on
+that terrain.
+
+## Reproducing the paper
+
+[`benchmark/`](https://github.com/GeoSWE/geoswe/tree/main/benchmark) holds the GeoSWE-side pipeline for the paper's
+benchmark cases: the four-code Pinellas County comparison, the steady sheet-flow
+plane, and the synthetic scaling sweep. Each case ships the scripts that
+prepare the inputs, run the simulations, and produce the reported numbers; see
+[`benchmark/README.md`](https://github.com/GeoSWE/geoswe/blob/main/benchmark/README.md) for data requirements and command
+sequences. The Florida and CONUS application pipelines are not part of this
+release; they exercise the same solver paths as the Pinellas case.
+
+## Documentation
+
+User guide, configuration reference, the compressed mesh, multi-GPU runs, and
+the API reference: **https://geoswe.github.io/geoswe** (or build locally with
+`pip install ".[docs]" && sphinx-build -b html docs docs/_build`).
+
+## Citing
+
+If you use GeoSWE, please cite it; see [CITATION.cff](https://github.com/GeoSWE/geoswe/blob/main/CITATION.cff). A paper
+describing the method, the cross-code benchmark, and the county-to-continent
+applications is in preparation.
+
+## Acknowledgments
+
+This material is based upon work supported by the National Science Foundation
+under Grant No. 2325631, by a 2025 IDEaS + Cloud Hub award with support from
+Microsoft at the Georgia Institute of Technology, and by the U.S. Department of
+Energy under Contract No. DE-AC05-00OR22725 through the Genesis Mission project,
+in collaboration with Oak Ridge National Laboratory, the Tennessee Valley
+Authority, and AMD. Computing resources were provided in part by the Partnership
+for an Advanced Computing Environment (PACE) at Georgia Tech and by the Frontier
+supercomputer at the Oak Ridge Leadership Computing Facility.
+
+## License
+
+BSD 3-Clause; see [LICENSE](https://github.com/GeoSWE/geoswe/blob/main/LICENSE).

geoswe-1.0.0/docs/amd_gpus.md

@@ -0,0 +1,165 @@
+# AMD GPUs (ROCm)
+
+GeoSWE runs on AMD GPUs through CuPy's ROCm build. The API, the kernels and the
+`SWE_*` settings are the same as on NVIDIA; `geoswe.gpu_platform()` returns
+`"hip"` instead of `"cuda"`.
+
+```{admonition} What has been tested
+:class: note
+
+AMD Instinct MI210 and MI250X (`gfx90a`) on OLCF Frontier, with ROCm 7.0.2 and
+7.2.0 and two CuPy builds: `cupy-rocm-7-0` 14.2.0 from PyPI and AMD's `amd-cupy`
+13.5.1. Both pass the whole GPU test suite. Other AMD GPUs and ROCm versions are
+untested. CuPy itself still labels its ROCm support experimental.
+```
+
+## Installing
+
+CuPy's ROCm build compiles kernels with the ROCm installation on the machine, so
+ROCm 7 must be installed and visible at run time:
+
+- `hipcc` on `PATH` (CuPy runs it to find the include directories), and
+- `ROCM_HOME` pointing at the ROCm tree, for example `/opt/rocm-7.2.0`.
+
+```bash
+pip install "geoswe[gpu-rocm]"                       # CuPy for ROCm 7 from PyPI
+pip install "geoswe[gpu-rocm,mpi,io,forcings]"       # with MPI, GeoTIFF I/O and forcings
+```
+
+AMD also publishes its own build, which OLCF documents for Frontier. Install it
+instead of the extra, never next to it:
+
+```bash
+pip install amd-cupy --extra-index-url https://pypi.amd.com/rocm-7.2.0/simple
+pip install "geoswe[mpi,io,forcings]"
+```
+
+Check the install:
+
+```bash
+python -c "import geoswe; print(geoswe.get_backend(), geoswe.gpu_platform())"   # cupy hip
+pytest -m gpu -q
+```
+
+The first run compiles every kernel, which takes a minute or so; later runs load
+them from CuPy's cache. On a cluster, put that cache on a filesystem the compute
+nodes share, and keep AMD's own compiler cache off NFS inside jobs:
+
+```bash
+export CUPY_CACHE_DIR=/path/on/scratch/cupy_cache       # default: ~/.cupy/kernel_cache
+export AMD_COMGR_CACHE_DIR=/tmp/$USER-comgr             # default: ~/.cache/comgr
+```
+
+## What differs from NVIDIA
+
+The kernels are CUDA C. NVIDIA's compiler (NVRTC) and AMD's (clang, through HIP)
+disagree about three things in them, and `geoswe.backend` handles each one. On
+NVIDIA nothing changes: kernel sources and options reach CuPy exactly as before.
+
+| | NVIDIA | AMD | What GeoSWE does on AMD |
+|---|---|---|---|
+| Register cap `-maxrregcount` (`SWE_DENSE_MAXRREG`, `SWE_FLAT_MAXRREG`) | applied on H100 | not an option of the compiler | never requested; ignored with a warning if set by hand |
+| `__fmul_rn` / `__fadd_rn` | never fused into a multiply-add | plain `*` and `+`, which clang fuses | redefined with contraction switched off |
+| Warp-level compaction | 32 lanes, 32-bit masks | 64 lanes, 64-bit masks | a kernel without warp intrinsics |
+
+The first one also needed a fix to device detection: CuPy reports the compute
+capability of a `gfx90a` card as `"90"`, the same string as an H100.
+
+### Floating-point contraction
+
+`GEOSWE_HIP_FP_CONTRACT` sets how the ROCm compiler may fuse `a*b + c` into one
+multiply-add:
+
+| Value | Meaning |
+|---|---|
+| `off` (default) | never; every operation rounds once, in source order |
+| `on` | only inside a single source expression |
+| `fast` | at the optimizer's discretion, across statements (clang's own default for HIP) |
+
+GeoSWE relies on several code paths giving identical bits: the fused and the
+split time step, the dense and the compressed mesh, a run and its restart. With
+`fast` the same expression can be fused in one kernel and not in another, and the
+fused and split steps with sub-grid storage then differ in the last bit
+(`tests/test_gpu_storage_fused.py` fails). With `off` or `on` the arithmetic is
+fixed by the source text.
+
+`off` is the default because it makes those identities hold by construction: two
+kernels agree whenever their statements do. It is the only mode in which the
+dense and the compressed solver agree bit for bit on the bowl-and-dam problem of
+`tests/test_gpu_compressed_equiv.py`; `on` and `fast` leave one unit in the last
+place between them. `on` is about 3 % faster (25.0 against 25.8 ms/step on an
+MI250X at 147 M cells; `fast` is in between) and keeps the fused and split steps
+identical in the test suite. All three modes keep a lake at rest to round-off.
+
+Results on AMD and NVIDIA are not bit-identical to each other: the compilers and
+their math libraries differ, at round-off level.
+
+## Multiple GPUs
+
+One MPI rank drives one GPU, as on NVIDIA. Under Slurm, let the scheduler bind
+the devices:
+
+```bash
+srun -n 8 --gpus-per-task=1 --gpu-bind=closest python my_run.py
+```
+
+The halo travels through host memory unless `SWE_HALO_CUDA_AWARE=1` asks for
+GPU-aware MPI. Despite the name, that setting is not specific to CUDA: CuPy's
+ROCm build exposes device arrays through the same interface, and `mpi4py` hands
+the pointers to MPI. With HPE Cray MPICH this needs two more things:
+
+- `mpi4py` built with the `craype-accel-amd-*` module loaded, so that it links the
+  GPU transport library, and
+- `MPICH_GPU_SUPPORT_ENABLED=1` in the job.
+
+If `SWE_HALO_CUDA_AWARE=1` is set while Cray MPICH runs without its GPU support,
+GeoSWE warns and stages through the host instead of passing device pointers to a
+library that would treat them as host memory.
+
+## OLCF Frontier
+
+`benchmark/frontier_amd/` in the repository has the module set, the build steps
+for a GPU-aware `mpi4py`, and a one-node job that runs the GPU test suite, a
+partition-invariance check and a weak-scaling sweep. Measured there on one node
+(an MI250X card is two devices, so eight per node; 147 M cells per device,
+float32, host-staged halo):
+
+| Tier | 1 device | 8 devices | Weak efficiency |
+|---|---|---|---|
+| Dense | 25.8 ms/step | 26.1 ms/step | 99.0 % |
+| Compressed | 23.7 ms/step | 23.9 ms/step | 99.2 % |
+
+Repeat launches differ by up to 2 %. The global solution is bit-identical on 1,
+2, 4 and 8 devices, with the host-staged and the GPU-aware halo, with and without
+the halo/compute overlap.
+
+On two nodes, the scaling harness of `benchmark/scaling_640m` (640 M cells per
+device, in the configuration its launchers pin) gives:
+
+| Layout | Weak scaling, 16 devices, 10.24 B cells | Strong scaling, 16 devices |
+|---|---|---|
+| Flat | 118.7 ms/step, 99.2 % efficiency | 15.0x |
+| Dense | 190.2 ms/step, 99.6 % efficiency | 15.4x |
+
+With the solver's defaults the same 10.24 billion cells take 102 ms/step (flat)
+and 112 ms/step (dense). The solution on sixteen devices across the two nodes has
+the digest of the one-device run.
+
+```{note}
+A device here is one GCD, half an MI250X card. For the same 640 M cells with the
+solver's defaults, the H100 of the scaling figure in the
+[repository README](https://github.com/GeoSWE/geoswe#how-it-scales) takes about
+42 ms/step (flat) and 46 ms/step (dense), where one GCD takes 101 and 111. That
+is 2.4 times faster, the ratio of their FP32 lanes (16,896 CUDA cores to 7,040
+stream processors), so a whole MI250X card delivers about 0.83 of an H100. The
+machines differ in more than the GPU: read this as arithmetic on published
+numbers, not as a controlled comparison.
+```
+
+## Not done yet
+
+- Of the paper's benchmark cases, only the synthetic scaling harness has been run
+  on AMD hardware.
+- The register cap that speeds up the residual kernel on H100 has no ROCm
+  counterpart, and no AMD-specific tuning of block sizes has been tried.
+- Two nodes (16 devices) are the most that has been used.

geoswe-1.0.0/docs/api/compressed.rst

@@ -0,0 +1,13 @@
+Compressed active-cell solver
+=============================
+
+GPU-only. Imported lazily as ``geoswe.CompressedSolver``. See
+:doc:`../compressed_mesh` for the concepts.
+
+.. currentmodule:: geoswe.compressed_solver
+
+.. autoclass:: CompressedSolver
+   :members:
+   :member-order: bysource
+
+.. autofunction:: run_cached

geoswe-1.0.0/docs/api/forcing.rst

@@ -0,0 +1,21 @@
+Forcings and I/O
+================
+
+.. currentmodule:: geoswe.forcing
+
+.. autoclass:: RainfallForcing
+   :members:
+
+.. autoclass:: StageBoundary
+   :members:
+
+GeoTIFF I/O
+-----------
+
+.. currentmodule:: geoswe.io_geotiff
+
+.. autoclass:: GeoArray
+   :members:
+
+.. autofunction:: read_geotiff
+.. autofunction:: write_geotiff