Installation

GeoSWE needs only NumPy to run on the CPU. GPU acceleration, multi-GPU runs, and GeoTIFF I/O are opt-in extras. Python 3.10 or newer is required; the test suite runs on 3.10, 3.12 and 3.13, on Linux and on macOS.

pip

An unpinned install gives the newest release. For work whose numbers you intend to publish, pin the version you ran instead (pip install geoswe==1.1.1) and record it beside the results: releases change what the solver computes, and citing explains what to put in the paper.

# CPU only (NumPy backend): the solver and the examples
pip install geoswe

# NVIDIA GPU (CUDA 12 or CUDA 13 drivers)
pip install "geoswe[gpu]"

# AMD GPU (ROCm 7.x)
pip install "geoswe[gpu-rocm]"

# everything a run needs: GPU + MPI + GeoTIFF I/O + CSV forcings + the examples' plots
pip install "geoswe[all]"

Note

The distribution, repository, and import name are all geoswe. The development version installs straight from the repository: pip install "geoswe[gpu] @ git+https://github.com/GeoSWE/geoswe.git".

From a source checkout, which also gives you the examples, the bundled terrain and the tests:

git clone https://github.com/GeoSWE/geoswe.git
cd geoswe
pip install -e ".[all]"

Extras

Extra	Pulls in	Needed for
gpu	cupy-cuda12x[ctk], scipy	GPU acceleration (dense and compressed solvers) on CUDA 12 and CUDA 13 drivers
gpu-cuda13	cupy-cuda13x[ctk], scipy	the same with the CUDA 13 build of CuPy, if you prefer it
gpu-rocm	cupy-rocm-7-0, scipy	GPU acceleration on AMD GPUs with ROCm 7; see AMD GPUs
mpi	mpi4py	multi-GPU / distributed runs (halo exchange)
io	rasterio, pyproj	reading DEMs and writing flood GeoTIFFs
forcings	pandas, scipy	CSV rainfall/tide ingestion, case conditioning, the high-level runner
examples	matplotlib	the plots the examples and the benchmark scripts draw
docs	sphinx, myst-parser, …	building this documentation
test	pytest, scipy	running the test suite

all is gpu, mpi, io, forcings and examples together; docs and test are not part of it. Without examples the examples still run and print their numbers, and say that they are skipping their plot.

Note

Install one CuPy build per environment. The gpu extra ships the CUDA headers CuPy compiles against, so it works on CUDA 12 and CUDA 13 machines alike, with or without a system CUDA toolkit; a CUDA 13 machine does not need the CUDA 13 build. To switch builds anyway, remove the old one first (pip uninstall -y cupy-cuda12x cupy-cuda13x), then install the extra you want. GeoSWE refuses the GPU backend when two CuPy builds are installed, because they overwrite each other; that includes a ROCm build next to a CUDA one. On CUDA 11, install GeoSWE without the gpu extra and add cupy-cuda11x yourself.

Note

The all extra installs the NVIDIA build. On an AMD GPU, name the extras: pip install "geoswe[gpu-rocm,mpi,io,forcings]". CuPy’s ROCm build compiles kernels with the machine’s own ROCm installation, so ROCm must be installed and on the path at run time. AMD GPUs has the details and the settings for OLCF Frontier.

conda

A development environment (GPU build) is provided:

conda env create -f environment.yml
conda activate geoswe
pip install -e ".[all]"

Choosing the backend

GeoSWE picks its array backend at import time from the GEOSWE_BACKEND environment variable:

GEOSWE_BACKEND	Behaviour
unset	the GPU (CuPy) when CuPy and a GPU, NVIDIA or AMD, are present, otherwise NumPy on the CPU
cupy	the GPU; an error if no device is visible, and a warning with the NumPy backend if CuPy is not installed
numpy	the NumPy CPU backend

Precision follows the backend unless Config(dtype=...) says otherwise: float32 on the GPU, float64 on the CPU.

GEOSWE_BACKEND=numpy python my_script.py     # force CPU

The choice is made once, when geoswe is first imported, because several modules specialize for the backend at import time. From Python, set the variable before the import:

import os
os.environ["GEOSWE_BACKEND"] = "numpy"       # or "cupy"; before importing geoswe
import geoswe
print(geoswe.get_backend(), geoswe.USING_CUPY)
print(geoswe.gpu_platform())                 # "cuda" (NVIDIA), "hip" (AMD ROCm), or None on the CPU

geoswe.set_backend(...) only works before any solver module has been imported; calling it later raises a RuntimeError pointing you back to GEOSWE_BACKEND.

Verifying the install

python -c "import geoswe; print(geoswe.__version__, geoswe.get_backend())"
pip install ".[test]" && pytest             # from a source checkout; GPU tests skip unless a GPU is free

Some tests skip without an optional tool, and pytest -rs lists each skip with its reason. pip install ".[test,io,forcings]" adds the GeoTIFF and CSV ingestion tests, and the check that compiles every CUDA kernel source runs only where nvcc is on PATH or under CUDA_PATH or CUDA_HOME (it needs the compiler, not a device).

Tip

Failed to find CUDA headers means CuPy can run on the device but cannot compile kernels: CuPy was installed without its headers (for example pip install cupy-cuda12x directly, or CuPy 13) and the machine has no CUDA toolkit. It does not mean you need a different CUDA build. Reinstall through the extra (gpu), add the headers (pip install "cupy-cuda12x[ctk]"), or point CUDA_PATH at a CUDA toolkit installation.