fimbox 0.1.14

FIMbox- A Testbed for Flood Inundation Mapping Experimentation

A modular open source testbed framework to standardize Flood Inundation Mapping (FIM) simulations and evaluation with custom datasets and hydrologic parameters in reproducible workflows. fimbox provides a streamlined, user friendly and cloud enabled pipeline to generate operational flood inundation maps using the NOAA Office of Water Prediction (OWP) Height Above Nearest Drainage (HAND) FIM framework, driven by National Water Model retrospective and forecasted streamflow. It is developed under the Surface Dynamics Modeling Lab (SDML) at The University of Alabama.

High-level workflow

fimbox implements an extensive Height Above Nearest Drainage (HAND) based flood inundation mapping workflow. It offers great flexibility to change datasets (e.g. resolution and source of river networks, catchments, DEMs) and to investigate different research questions (e.g. changing Manning's n, better representation of the synthetic rating curve, stream network segmentation, slope improvement and many more terrain conditioning options) to improve FIM extents and depths. The HAND preprocessing logic follows the NOAA OWP HAND FIM framework, whose reference implementation lives at https://github.com/NOAA-OWP/inundation-mapping. Ongoing work expands the modeling capability beyond a single model, integrating different models to enable multimodel FIM extents, and more.

Every module shown above ships its own README with a detailed workflow diagram and step by step usage: what the module does, every class and parameter it exposes, and runnable examples (see the Module documentation table below). Worked end to end examples for each stage live in tests/ and the package documentation in docs/.

Install

fimbox targets Python 3.10–3.12.

git clone https://github.com/sdmlua/fimbox.git
cd fimbox

# uv-based environment (recommended)
pip install uv
uv venv
uv pip install -e .

Activate the virtual environment before running any commands:

Mac / Linux

source .venv/bin/activate

Windows (Command Prompt)

.venv\Scripts\activate.bat

Windows (PowerShell)

.venv\Scripts\Activate.ps1

If you prefer Conda, create and activate the environment first, then run uv pip install -e . inside it.

Quick start: from AOI to flood map

1. Stage AOI inputs

Download the DEM, NHD/NWM hydrography, FEMA NFHL, NLD levees, OSM bridges/roads, and USGS gages into an AOI working directory.

from fimbox import getAllInputData

getAllInputData(
    boundary="path/to/aoi_boundary.gpkg",
    aoi_id="my_basin",
    out_dir="out/my_basin",
)

An AOI can also come from a HUC8 ID or from NWM reach IDs, in which case the AOI is the dissolved footprint of those reaches' catchments:

from fimbox import getAllInputData, getAllInputDataBatch

getAllInputData(huc8="03020201", out_dir="out")
getAllInputData(nwm_ids=[5091042, 5091044], out_dir="out")

# Several AOIs at once. Grouping is explicit: a flat reach list is one AOI, a
# nested list is one AOI per inner list, and a flat HUC list is one AOI per HUC.
getAllInputDataBatch(nwm_ids=[[5091042], [11908106]], out_dir="out")
getAllInputDataBatch(hucs=["03020201", "03020202"], out_dir="out")

Reach-ID runs default to no buffer, staging exactly the reaches requested. Pass buffer_m to widen the AOI and pull in the neighbouring reaches inside it — usually what you want for HAND, since flow accumulation at the edge needs the upstream contributing area. See the preprocessing README for the full grouping and buffer rules.

See the tests/ folder for further detailed steps including HAND processing, SRC generation, calibration, and FIM generation. Users can change different parameters based on requirements.

Module documentation

Each module has its own README documenting what it contains, the full parameter surface (including optional parameters), and usage examples:

For more usage notes refer to the tests or docs for the fimbox python package.

Contribution

For contribution guidelines see CONTRIBUTING.md.

Acknowledgements

	Funding for this project was provided by the National Oceanic & Atmospheric Administration (NOAA), awarded to the Cooperative Institute for Research to Operations in Hydrology (CIROH) through the NOAA Cooperative Agreement with The University of Alabama (NA22NWS4320003).

Contact

fimbox is developed at the Surface Dynamics Modeling Lab (SDML) at The University of Alabama.

Sagy Cohen (sagy.cohen@ua.edu), Supath Dhital (sdhital@ua.edu)

NOTE- This repository is still in active development and might contain bugs. Please let us know or create a pull request if you have better ideas. THANK YOU.