FastFlowX

A library to accelerate flow and depression routing for terrains on the GPU.

FastFlowX ships a PyTorch CUDA extension that is compiled from source on your machine at install time. This repository is the maintained release of FastFlow (2024). The code released with that paper lives at landscapes/fastflow and is kept as-is for reproducing the paper; FastFlowX extends it with API improvements and the additional functions developed for Pixels2Peaks (2026). See docs/API.md for the full API.

Requirements

You must have all of these in your environment before installing FastFlow:

• An NVIDIA GPU + driver
• A CUDA toolkit (nvcc) matching your PyTorch build (e.g. CUDA 12.4)
• A C++ compiler (GCC/Clang on Linux, MSVC on Windows)
• PyTorch. FastFlow compiles against whichever torch you already have.

Tested on: Debian 11 (Linux 5.10), Python 3.9.23, PyTorch 2.4.1, CUDA 12.4 (nvcc 12.2), NVIDIA H100 NVL.

Installation

pip install "setuptools>=77" wheel ninja
pip install fastflowx --no-build-isolation

Or from a local checkout: pip install --no-build-isolation .

--no-build-isolation lets the build compile against your existing PyTorch, but it also stops pip from installing build tools, hence the first command. ninja is optional; it only makes the compile ~9x faster.

Or use the provided conda environment, which brings its own Python, PyTorch and build tools:

conda env create -f environment.yml
conda activate fastflow
pip install fastflowx --no-build-isolation

Usage

import torch
import fastflow as ff

z = torch.rand(512, 512, device="cuda") * 1000.0

filled = ff.fill_depressions(z)          # pit-free surface
area   = ff.drainage_area(z, dx=30.0)    # drainage area

See docs/API.md for the full API and more examples.

Tests

The extension is compiled on your machine, so it is worth checking the build:

python -c "import torch, fastflow; print(fastflow.drainage_area(torch.rand(64, 64, device='cuda')).shape)"

The full suite (imports, the invariant sweep up to 4096x4096, and the benchmarks) needs pytest and a CUDA device:

pip install pytest
pytest

The timing sweep also runs on its own:

python tests/test_benchmark.py --sizes 512 1024 2048 --iters 50

Citation

If you use this library, please cite FastFlow:

@article{jain2024fastflow,
  title={FastFlow: GPU Acceleration of Flow and Depression Routing for Landscape Simulation},
  author={Jain, Aryamaan and Kerbl, Bernhard and Gain, James and Finley, Brandon and Cordonnier, Guillaume},
  journal={Computer Graphics Forum},
  volume={43},
  number={7},
  year={2024},
}

The API improvements and additional functions in this release were developed for:

@article{jain2026pixels2peaks,
  title={Pixels2Peaks: Converting Terrain Images to Heightmaps},
  author={Jain, Aryamaan and Gain, James and Cordonnier, Guillaume},
  journal={ACM Transactions on Graphics},
  volume={45},
  number={4},
  year={2026}
}