This resource includes materials for the workshop about configuring and running a NextGen simulation and analyzing model outputs, presented during the 2026 NWCSI Bootcamp. It's meant to provide an overview of techniques for configuring and executing a model simulation within the NOAA NextGen modeling framework. Code examples leverage tools and techniques established through the Cooperative Institute for Research to Operations in Hydrology (CIROH). This README.md outlines the steps that should be executed before running the code in this resource.

Acquiring a Cloud Computing Environment

The code included in this resource is designed to run in the CIROH JupyterHub environment and the instructions below reflect that, however this should work with very little modification on any system that has the requisite software installed on it.

1. Use HydroShare's "Open With" capabilitiy to launch this resource into the CIROH-2i2c JupyterHub application.
2. You'll need to choose a hardware and software configuration to run the code in. At present, we recommend that you choose a "Medium (11GB RAM, 4 CPUs)" sized machine and the "CIROH Community NextGen Hub" environment. These selections will ensure that (1) you'll have sufficient hardware resources to complete the analysis defined in the notebook and (2) that the NextGen modeling framework is already installed and configured.

Once these steps have been completed, you should have a JupyterHub instance that contains all of the data, code, and software you'll need to run the code in this resource.

Environment Setup

As mentioned in the previous section, the resource contains code that requires a computational environment that has the NOAA NextGen Modeling Framework installed on it. Run the following command to verify that it's installed:

ngen

You should see output that looks like this:

NGen Framework 0.3.0 Usage: ngen <catchment_data_path> <catchment subset ids> <nexus_data_path> <nexus subset ids> <realization_config_path> Arguments for <catchment subset ids> and <nexus subset ids> must be given. Use all as explicit argument when no subset is needed. Build Info: NGen version: 0.3.0 Parallel build NetCDF lumped forcing enabled Fortran BMI enabled C BMI enabled Python active Embedded interpreter version: 3.11.8 Routing active Python Environment Info: VIRTUAL_ENV environment variable: (not set) Discovered venv: None System paths: /srv/conda/envs/notebook/lib/python311.zip /srv/conda/envs/notebook/lib/python3.11 /srv/conda/envs/notebook/lib/python3.11/lib-dynload /srv/conda/envs/notebook/lib/python3.11/site-packages

If you receive an error, you'll need to either choose a computational environment that already contains this software, or install it yourself by following the instructions located on https://github.com/noAA-OWP/ngen.

Next, we need to prepare a Python environment that contains the software we'll be using. To do this, launch a terminal, and deactivate the current (notebook) environment. After executing the command below, you should see that the (notebook) environment is no longer active.

conda deactivate

This will remove the (notebook) item from your terminal prompt string, i.e. (notebook) jovyan@jupyter-<username>$ should now appear as jovyan@jupyter-<username>$

Now create a new virtual environments using the uv library. This will enable us to install and use our own software libaries.

uv venv

Activate the environment

source .venv/bin/activate

Install software dependencies

uv pip install -r requirements.txt

Finally, lets register our new environment with Jupyter so we can use it in our notebook.

python -m ipykernel install --user --name=ngen-preprocess --display-name="NGEN (Venv)"

Data Setup

The ngiab_data_cli tool that we'll be using relies on a large input hydrofabric dataset that spans to contiguous United States (CONUS). This is much larger than we need for this exercise so we'll instead be using a subset of the hydrofabric that covers only the South Atlantic West area (VPU 03W).

To do this, we're going to use a helper script to place a smaller subset of hydrofabric data in the ngiab working directory. This is done by executing:

bash prepare.sh

Upon completion of this notebook, you may wish to run NextGen simulations elsewhere in the USA. To do so, you'll want to revert the files we're using (i.e. 03W) by executing:

bash restore.sh