Ways to run NGIAB

Last updated on 2026-06-16 | Edit this page

Overview

Questions

  • How do I execute a NextGen run?

Objectives

  • Recognize methods to execute NextGen models
  • Execute a NextGen run using NGIAB

1. Model Execution using guide.sh

guide.sh is used to execute pre-configured NextGen runs in NGIAB. These settings can be configured by users ahead of time using the Data Preprocessor tool. Execute the following commands:

BASH 

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

guide.sh will prompt you to enter input data pathways and allow you to select a computational mode (serial or parallel processing). After the run is complete, guide.sh will give you the option to evaluate model predictions and visualize results (discussed in the next two episodes).

2. Model Execution using Data Preprocessor

A secondary method for executing a NextGen run in NGIAB is by using the Data Preprocessor’s CLI. The Data Preprocessor prepares a complete NGIAB run package by subsetting the hydrofabric, generating forcings, and creating realization and BMI configuration files. It can also automatically launch a Docker-based NGIAB run after preprocessing using the --run flag.

BASH 

uvx -p 3.10 --from ngiab_data_preprocess cli -i gage-02342500 -sfr --start 2020-01-01 --end 2020-01-07 --source aorc --run

In this command, uvx runs the Data Preprocessor without installing it as a package. The -i argument specifies the location to model, -sfr subsets the hydrofabric, generates forcings, and creates realization files, --source aorc selects AORC forcing data, and --run automatically launches the NGIAB simulation after preprocessing.

As this module is being updated constantly, check back on the (NGIAB_data_preprocess GitHub Repository) for the latest updates on its functionality.

3. Model Execution using CIROH-2i2c JupyterHub

Another way to interactively run NextGen is through Jupyter notebooks using the CIROH-2i2c JupyterHub. To get started, log in to the CIROH-2i2c JupyterHub. If you do not yet have access, please refer to the Infrastructure Access page for instructions on requesting an account. Launch a JupyterHub server by selecting your preferred server size (or the default Small option for testing), choosing the CIROH Community NextGen Hub image, and clicking Start. For additional setup instructions, tutorials, and usage details, see the CIROH Hub documentation.

4. Model Execution using DataStreamCLI

DataStreamCLI provides an alternative command-line workflow for executing NextGen simulations. In this workflow, users can subset the hydrofabric using the Data Preprocessor and then use that subset hydrofabric as input to DataStreamCLI. DataStreamCLI automatically generates forcings, realizations, and BMI configuration files as part of the execution workflow before launching a NextGen simulation. This approach is useful for users who prefer an automated and scriptable workflow for running simulations and managing forcing data.

BASH 

 uvx --from ngiab_data_preprocess cli -i gage-02342500 -s
cd /path/to/datastreamcli
cp ~/ngiab_preprocess_output/gage-02342500/config/gage-02342500_subset.gpkg .
chmod +x ./scripts/datastream
./scripts/datastream -s 202001010100 \
                    -e 202001070000 \
                    -C NWM_RETRO_V3 \
                    -d $(pwd)/data/datastream_test \
                    -g $(pwd)/gage-02342500_subset.gpkg \
                    -R $(pwd)/configs/ngen/realization_sloth_nom_cfe_pet_troute.json \
                    -n 4

In this command, -s specifies the simulation start time, -e specifies the end time, -C selects the forcing source, -d specifies the output directory, -g provides the hydrofabric geopackage, -R specifies the realization template, and -n sets the number of processes used during execution.

For installation instructions and additional examples, refer to the DataStreamCLI GitHub Repository.

Your Turn

Try one of the four methods described in this lesson to execute a NextGen run:

  • Use guide.sh to execute a run from a preprocessed NGIAB dataset.
  • Use the Data Preprocessor tool with the --run option to automatically prepare and execute a simulation.
  • Explore the CIROH-2i2c JupyterHub workflow for cloud-based execution.
  • Review the DataStreamCLI workflow and compare it with the Data Preprocessor and guide.sh approaches.
Key Points
  • 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.