NextGen In A Box (NGIAB)

Run the NextGen National Water Resources Modeling Framework locally with ease.

NGIAB provides a containerized and user-friendly solution for running the NextGen framework, allowing you to control inputs, configurations, and execution on your local machine.

	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).

Features

• Run NextGen Locally: Experiment with the framework on your machine
• Control Over Inputs: Choose specific regions/basins and modify input data
• Simplified Setup: Easy deployment using Docker containers
• Open Research: Promote transparency through open-source tools
• Visualization: Built-in support for output visualization
• Evaluation Tools: Integrated TEEHR evaluation capabilities

Prerequisites

Windows

1. Install WSL

   wsl --install
   # If the above doesn't work, try:
   sudo apt install wsl

2. Install Docker Desktop

   • Download from Docker's official website
   • Launch Docker Desktop
   • Open WSL as Administrator
   • Verify installation: docker ps -a

Mac

1. Install Docker Desktop
   • Download from Docker's Mac installer page
   • Launch Docker Desktop
   • Verify installation: docker ps -a

Linux

1. Install Docker
   • Follow Linux installation guide
   • Start Docker service
   • Verify installation: docker ps -a

Quick Start Guide

1. Set Up Project Directory

mkdir -p NextGen/ngen-data
cd NextGen/ngen-data

2. Download Sample Data

Option 1: AWI-007 input data (realization file includes - SLOTH, NoahOWP, CFE)

wget https://ciroh-ua-ngen-data.s3.us-east-2.amazonaws.com/AWI-007/AWI_16_2863657_007.tar.gz
tar -xf AWI_16_2863657_007.tar.gz

Option 2: AWI-008 input data (realization file includes - SLOTH, Demostration LSTM)

wget --no-parent https://ciroh-ua-ngen-data.s3.us-east-2.amazonaws.com/AWI-008/AWI_16_2863806_008.tar.gz
tar -xf AWI_16_2863806_008.tar.gz

3. Clone and Run

cd NextGen
git clone https://github.com/CIROH-UA/NGIAB-CloudInfra.git
cd NGIAB-CloudInfra
./guide.sh

4. NextGen Run Directory Structure (ngen-run/)

Running NextGen requires building a standard run directory complete with only the necessary files. Below is an explanation of the standard. Reference for discussion of the standard here.

A NextGen run directory ngen-run is composed of three necessary subfolders config, forcings, outputs and an optional fourth subfolder metadata.

ngen-run/
│
├── config/
│
├── forcings/
│
├── lakeout/
|
├── metadata/
│
├── outputs/
│
├── restart/

The ngen-run directory contains the following subfolders:

• config: model configuration files and hydrofabric configuration files. A deeper explanation here
• forcings: catchment-level forcing timeseries files. These can be generated with the forcingprocessor. Forcing files contain variables like wind speed, temperature, precipitation, and solar radiation.
• lakeout: for t-route
• metadata is an optional subfolder. This is programmatically generated and it used within to ngen. Do not edit this folder.
• outputs: This is where ngen will place the output files.
• restart: For restart files

Configuration directory ngen-run/config/

This folder contains the NextGen realization file, which serves as the primary model configuration for the ngen framework. This file specifies which models to run and with which parameters, run parameters like date and time, and hydrofabric specifications.

Based on the models defined in the realization file, BMI configuration files may be required. For those models that require per-catchment configuration files, a folder will hold these files for each model in ngen-run/config/cat-config. See here for which models ngen-datastream supports automated BMI configuration file generation. See the directory structure convention below.

ngen-run/
|
├── config/
|   │
|   ├── nextgen_09.gpkg
|   |
|   ├── realization.json
|   |
|   ├── ngen.yaml
|   |
|   ├── cat-config/
|   │   |
|   |   ├──PET/
|   │   |
|   |   ├──CFE/
|   │   |
|   |   ├──NOAH-OWP-M/
...

Hydrofabric Example files: conus_nextgen.gpkg NextGen requires a single geopackage file. This file is the hydrofabric (spatial data). An example geopackage can be found on Lynker-Spatial here. Tools to subset a geopackage into a smaller domain can be found at Lynker's hfsubset.

Case Study: Provo River Basin, UT

This repository includes a complete case study of the Provo River Basin, demonstrating NGIAB's capabilities in a real-world scenario.

Output Visualization

NGIAB provides comprehensive visualization options through the Tethys Platform:

1. Geospatial Visualization

2. Time Series Analysis

   • Catchments
   • Nexus Points

Advanced Usage

Running the Visualizer

./viewOnTethys.sh

Building NGIAB Locally

cd docker
docker build -f Dockerfile -t awiciroh/ciroh-ngen-image:latest . --no-cache

Note: For ARM64 architecture, use latest tag; for X86 architecture, use latest-x86 tag.

Additional Resources

• End-to-End Setup Guide
• NextGen Framework Prototype
• Community ngen Repository
• Community troute Repository
• NGIAB Data Preprocessor
• ngen-datastream Repository