OpenFloodLab

OpenFloodLab is an auditable, browser-based shallow-water simulation toolkit for research and education. It combines a reusable solver, a MapLibre custom layer, and a focused web application that runs without a simulation backend.

Try the OpenFloodLab live demo.

Demo

The recording is shown at 2x speed. It demonstrates the research and education prototype only; the visualised output is not an operational flood forecast.

Status

This project is an early scientific prototype. It is not an operational flood forecast or warning service and must not be used as the sole basis for decisions involving life, property, or infrastructure.

Capabilities

• WebGL2 shallow-water simulation on georeferenced DEM grids
• Readable CPU reference solver and deterministic benchmarks
• Point inflow sources, pause, reset, speed control, and open boundaries
• Water-depth GeoJSON, extent GeoJSON, and JSON report export
• Reproducible synthetic data and a documented USGS 3DEP teaching sample
• Static hosting and container deployment

Technical approach

1. Versioned DEM manifests bind georeferencing, provenance, dimensions, units, and a SHA-256 checksum to each elevation grid.
2. Compact, discharge-normalised inflow kernels convert editable point sources from m3/s to per-cell depth rates without changing total injected volume.
3. A conservative four-neighbour hydraulic-head solver advances persistent face discharge, applies Manning bed resistance, and limits outflow to available cell volume.
4. The readable CPU implementation is the numerical reference; the WebGL2 implementation runs the same split flux/continuity update in float textures.
5. An adaptive tile-aligned computational window starts around active sources and expands before wet cells reach its edge. Full-grid state remains allocated, so expansion does not resample or discard water.
6. MapLibre renders the georeferenced terrain and water surface, while GeoJSON and JSON exports retain solver, source-history, DEM, and mass-balance metadata.

The equations, stability bounds, adaptive-domain rules, and current validation scope are documented in the numerical model.

Quick start

Node.js 22.12 or newer is required.

npm install
npm run data:sample
npm run dev

Open http://127.0.0.1:5173.

Repository layout

apps/web                 teaching application
packages/simulation-core reusable numerical core
packages/maplibre-layer  map rendering adapter
packages/data-tools      reproducible DEM tooling
docs                     numerical and architectural documentation

See scientific limitations, numerical model, data provenance, and contribution requirements before using or extending the software.

License

Copyright (c) 2026 RedShameA and SeanWong17.

Code is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). Datasets retain the terms documented in DATA_LICENSES.md.