Skip to content

CIROH-UA/NGIAB-CloudInfra

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

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

ARM Build and push final image

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

Mac

  1. Install Docker Desktop

Linux

  1. Install Docker

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

Provo River Basin Map

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 Nexus Output

  2. Time Series Analysis

    • Catchments Catchment Time Series
    • Nexus Points Nexus Time Series

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