To execute NextGen-based hydrological model simulations and proceed to calibration, a general workflow involves several key stages. These stages are handled by specialized tools within the NGIAB ecosystem:

This workflow requires Docker and UV.

📋 For setup instructions: Pre-Workshop Checklist

This involves preparing the network and catchment information that defines the spatial domain of the model. The hydrofabric data used as a base for this workshop is the v2.2 CONUS Hydrofabric. Further details on its data model and sources can be found here

The tools/NGIAB_data_preprocess tool manages the subsetting of this hydrofabric for the specific area of interest and prepares essential model inputs such as soil characteristics, land surface properties, catchment attributes, and flowpath (channel) properties.

This step involves preparing the meteorological and other input datasets required to drive the hydrological model. The tools/NGIAB_data_preprocess tool is utilized for processing various forcing data sources.

For this workshop, primary forcing data sources include:

• NWM Retrospective v3 forcing data
• AORC 1km gridded data

Note: For this workshop, a ready-made data package is provided in the ./Data/ directory of this repository.

Once the core data is processed, this stage focuses on generating the specific configuration files that NextGen models require to run:

• Preparing initial conditions for the model
• Defining the NextGen modules configuration (often in a realization.json file)
• Setting up the routing configuration (e.g., troute.yaml)
• Establishing per-catchment model component configurations

# Example: Prepare data for USGS gage 10154200 for Jan 1, 2022, to Feb 28, 2022, using AORC source,
# saving to an output folder named 'cal_demo_run_package'.
uvx run --from ngiab_data_preprocess cli -i gage-10154200 --start 2022-01-01 --end 2022-02-28 -sfr --source aorc -o cal_demo_run_package
# or
uvx ngiab-prep -i gage-10154200 --start 2022-01-01 --end 2022-02-28 -sfr --source aorc -o cal_demo_run_package

This initial step involves using the NGIAB-Cal command-line interface (CLI) to prepare your project for calibration:

• Copying Base Configurations: NGIAB-Cal helps in copying the relevant realization.json and troute.yaml files from your base model setup into the calibration directory structure.
• Preparing Calibration Directories: The tool automates the creation of the specific directory layout required for the calibration workflow.
• Generating Key Configuration Files: NGIAB-Cal creates or places important configuration files that you will interact with.

Before running the calibration, you will typically need to edit one or more configuration files (e.g., ngen_cal_conf.yaml within the calibration directory) to define:

• Paths to observation data (e.g., obs_hourly_discharge.csv)
• Specifics of the calibration algorithm (e.g., DDS parameters)
• The parameters to be calibrated and their ranges
• Time periods for calibration and validation

After the configuration setup is complete and customized, you can initiate the calibration run:

• Procedure: Running the simulation can be done automatically by adding --run to the ngiab-cal command, or manually by running the docker command output by ngiab-cal.
• Monitoring: Progress can usually be monitored via log files generated in the output directories and console output.

# Create calibration configuration
uvx ngiab-cal /path/to/ngiab/data/folder -g USGS_GAGE_ID

# Create and run calibration (200 iterations)
uvx ngiab-cal /path/to/ngiab/data/folder -g USGS_GAGE_ID --run -i 200

# Force recreation of calibration configuration
uvx ngiab-cal /path/to/ngiab/data/folder -g USGS_GAGE_ID -f -i 150

After running the data preprocessing steps and subsequently setting up and executing a calibration run, you'll have a directory structure that organizes input configurations, intermediate files, and calibration outputs.

View detailed directory structure example

🔧 Having issues? Check the Troubleshooting Guide for solutions to common problems.

Back to Home