Metadata-Version: 2.4
Name: fastflowx
Version: 0.1.0
Summary: GPU-accelerated flow and depression routing for terrains
Author: Aryamaan Jain
License-Expression: LicenseRef-Inria-NonCommercial
Project-URL: Homepage, https://gitlab.inria.fr/landscapes/fastflowx
Project-URL: Repository, https://gitlab.inria.fr/landscapes/fastflowx
Project-URL: Issues, https://gitlab.inria.fr/landscapes/fastflowx/-/issues
Project-URL: Paper, https://doi.org/10.1145/3811288
Project-URL: FastFlow paper, https://doi.org/10.1111/cgf.15243
Keywords: terrain,heightmap,heightfield,dem,erosion,computer-graphics,procedural-generation,terrain-generation,hydrology,flow-routing,depression-filling,geomorphology,landscape-evolution,cuda,gpu,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# 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](https://doi.org/10.1111/cgf.15243) (2024). The code released with that paper lives at [`landscapes/fastflow`](https://gitlab.inria.fr/landscapes/fastflow) and is kept as-is for reproducing the paper; FastFlowX extends it with API improvements and the additional functions developed for [Pixels2Peaks](https://doi.org/10.1145/3811288) (2026). See [`docs/API.md`](https://gitlab.inria.fr/landscapes/fastflowx/-/blob/main/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

```sh
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:

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

## Usage

```python
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`](https://gitlab.inria.fr/landscapes/fastflowx/-/blob/main/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:

```sh
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:

```sh
pip install pytest
pytest
```

The timing sweep also runs on its own:

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

## Citation

If you use this library, please cite FastFlow:

```bibtex
@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:

```bibtex
@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}
}
```
