Key Points

Introduction

---

• The Next Generation Water Resources Modeling Framework (NextGen) advances the National Water Model with flexible, modular, and regionally adaptive hydrologic modeling at national scale.
• NextGen In A Box (NGIAB) packages the complex NextGen system into an open-source, containerized application for easier access and usability.
• NGIAB uses Docker and Singularity for portability across local machines, cloud platforms, and HPC systems.
• NGIAB’s ecosystem includes the Community Hydrofabric, Data Preprocessor, TEEHR, Data Visualizer, and calibration tools that support end-to-end hydrologic modeling workflows.
• NGIAB fosters an open ecosystem where researchers, developers, and practitioners actively contribute new models, extensions, and workflows.

Installation and Setup

---

• NGIAB simplifies NextGen framework deployment through Docker.
• Use guide.sh for interactive configuration and run execution.
• Always confirm successful setup by executing provided sample runs.

Ways to run NGIAB

---

• NGIAB supports multiple execution workflows, including guide.sh, the Data Preprocessor tool, CIROH-2i2c JupyterHub, and DataStreamCLI.
• The guide.sh workflow provides the most complete NGIAB experience, including optional evaluation and visualization.
• The Data Preprocessor tool can automatically prepare and execute a NextGen simulation using a single command.
• CIROH-2i2c JupyterHub provides a cloud-based environment for running NGIAB without local installation.
• DataStreamCLI automates forcing generation, realization creation, BMI configuration, and model execution through a command-line workflow.

NGIAB-related Software

---

• The Community Hydrofabric provides the watershed connectivity, catchments, flowpaths, and nexus information used throughout NGIAB workflows.
• The Data Preprocessor tool simplifies the creation of NextGen run packages by generating hydrofabric subsets, forcings, and model configurations.
• NGIAB-Cal supports parameter calibration by optimizing model parameters against observed streamflow data.
• TEEHR provides automated model evaluation through hydrograph visualization and performance metrics such as KGE, NSE, and Relative Bias.
• The Data Visualizer enables interactive exploration of model outputs, including geospatial views, time series analysis, and TEEHR results.
• Together, these tools support a complete workflow for preparing, calibrating, evaluating, and interpreting NextGen simulations.

Community Hydrofabric

---

• The Community Hydrofabric is a CIROH-maintained fork of NextGen Hydrofabric v2.2.
• NGIAB uses the Community Hydrofabric during preprocessing, routing, model execution, evaluation, calibration, and visualization.
• The Community Hydrofabric includes corrected gage mappings, GeoPackage compatibility improvements, and database indexing enhancements.
• Hydrofabric data are automatically accessed and subset by NGIAB during study area preparation.

Data Preprocessor

---

• ngen-run/ is the standard NextGen run directory, containing the realization files that define models, parameters, and run settings; forcing data; outputs; as well as the spatial hydrofabric.
• The Data Preprocess tool simplifies preparing data for NextGen by offering a GUI and CLI for selecting catchments and date ranges, subsetting hydrofabric data, generating forcing files, and creating realization files.

TEEHR

---

• Tools for Exploratory Evaluation in Hydrologic Research (TEEHR) is a Python-based package for hydrologic model evaluation.
• NGIAB uses TEEHR to assess model performance, comparing predictions against USGS streamflow and NWM data and calculating performance metrics.
• TEEHR runs automatically with the main guide.sh NGIAB script.

Visualization

---

• The Data Visualizer (built on the Tethys Platform) provides interactive geospatial maps and time series plots for NextGen model outputs in NGIAB.
• It integrates seamlessly with NGIAB via guide.sh or ViewOnTethys.sh.
• Model outputs reside under ~/ngiab_visualizer, with metadata stored in ngiab_visualizer.json.
• You can visualize Nexus points, catchment summaries, Troute variables, and TEEHR hydrographs and performance metrics.

Calibration

---

• The ngiab-cal package is used to calibrate parameters for a NextGen model run.
• ngiab-cal is a command-line tool controlled via a YAML configuration file that determines parameter ranges, time periods, and evaluation metrics.

Advanced Topics

---

• NGIAB supports HPC environments through Singularity, not Docker, but the workflow mirrors the local Docker use.
• Port forwarding is required to use the Data Visualizer through an SSH connection.
• Community contribution guidelines are available in each repository’s GitHub page.
• NGIAB can also be run through JupyterHub or DatastreamCLI.
• Model integration in NGIAB requires model configuration, supporting input datasets, and compatibility with the broader NGIAB ecosystem, including preprocessing, calibration, evaluation, and visualization tools.

Model Integration

---

• Models integrate into NextGen/NGIAB through the Basic Model Interface (BMI), which lets models be swapped in and out of the framework.
• Python models must target Python 3.11, pin netCDF/pydantic/pandas to compatible versions, and ship a PyPI distribution; non-Python models must compile against libc 2.34 or lower.
• A Python model is integrated by installing it in the final stage of the NGIAB Dockerfile, rebuilding the image, and running it against a test data package.