CIROH DevCon 2025 Workshop: Hydrological Model Calibration in the NGIAB Ecosystem

"How do I calibrate, regionalize and share the calibrated parameters in a NextGen Framework ecosystem"

• 📅 Date: Thursday, May 29, 2025
• ⏰ Time: 1:30 PM – 3:00 PM (US Eastern Time)
• 📍 Location: UVM Dudley H. Davis Center – Level 4, 590 Main Street, Burlington, VT 05405
• 🏛️ Organized by: Cooperative Institute for Research to Operations in Hydrology - CIROH

---

🚀 Quick Start

Ready to jump in? Choose your path:

I want to...	Go to...
Start calibrating immediately	🚀 Quickstart Guide
Understand the process first	📚 Step-by-Step Instructions
Learn about NextGen	🔍 What is NextGen?
Modify the code	⚙️ Development Setup

---

🎯 Workshop Purpose

This hands-on workshop provides comprehensive guidance for hydrological model calibration, regionalization, and parameter sharing within the NextGen In A Box (NGIAB) ecosystem. You'll gain practical experience using open-source tools with pre-configured datasets.

What You'll Learn

• ✅ Model Calibration Fundamentals - Theory and practice of improving hydrological model accuracy
• ✅ Hands-on NextGen Experience - Complete calibration workflows using real tools and data
• ✅ Parameter Management - Share and collaborate on calibrated parameters effectively
• ✅ Best Practices - Learn from experts and discuss real-world challenges

Workshop Workflow

Figure 1: End-to-end visual representation of the NextGen In A Box (NGIAB) ecosystem's hydrological simulation workflow, detailing phases for data preparation, model simulation, parameter calibration, and output analysis steps. 1) Python CLI data preparation modules for NGIAB, 2a) NGIAB Docker image, 2b) NGIAB-cal Docker image + Python CLI for Calibration, and 3) TEEHR evaluation + visualizer

---

🛠️ Prerequisites

For Jetstream Virtual Machines:

• Access to provided Jetstream Virtual Machines (instructions emailed before workshop)
• All required software installed (e.g., Docker, UV)
• Pre-installed data at /home/exouser/workshop/calibration/provo-10154200

For Local Setup:

• Download workshop data: https://communityhydrofabric.s3.us-east-1.amazonaws.com/example_data/provo-10154200.tar.gz Click Here to Download

Minimum Requirements:

• Docker (for running containerized tools)
• UV (Python package manager)

📋 For complete setup instructions and requirements: Pre-Workshop Checklist

---

📚 Workshop Resources

🚀 Get Started

• Quickstart Guide - Start calibrating in 5 minutes
• Step-by-Step Instructions - Detailed tutorial
• Workshop Materials - Slides and datasets

🔧 Understanding the Tools

• What is NextGen? - Framework overview
• Tools and Modules - Component explanations
• Workflow Process - How everything connects

🔬 Advanced Topics

• Development Setup - Modify and extend tools
• Directory Structure - File organization reference

📞 Support

• Troubleshooting - Common issues and solutions
• Contact Information - Get help and support
• GitHub Issues - Report bugs or ask questions

---

🏃‍♂️ 5-Minute Start

On Jetstream VMs:

cd /home/exouser/workshop/calibration/
uvx ngiab-cal provo-10154200 -g 10154200 --run -i 4

On Local Systems:

wget https://communityhydrofabric.s3.us-east-1.amazonaws.com/example_data/provo-10154200.tar.gz
tar -xzf provo-10154200.tar.gz
uvx ngiab-cal provo-10154200 -g 10154200 --run -i 4

That's it! Your first calibration will complete in ~10-15 minutes.

🔍 Want details? See the Quickstart Guide for complete instructions.

---

🧩 The NGIAB Ecosystem

This workshop uses four integrated tools:

Tool	Purpose	Type
NGIAB-Data-Preprocess	Prepare hydrofabric and forcing data	Python CLI
NGIAB-Cal	Configure and run calibration	Python CLI
NGIAB	NextGen framework container	Docker Image
NGEN-Cal	Calibration algorithms and analysis	Docker Image

🔧 Learn more: Tools and Modules

---

📖 What is NextGen?

The Next Generation Water Resources Modeling Framework (NextGen) is a model-agnostic, standards-based framework that enables:

• 🔗 Model Interoperability - Connect different hydrological models seamlessly
• 🏗️ Standards-Based Design - Consistent interfaces and data formats
• 🌐 Multi-language Support - C++, C, Fortran, Python models
• ☁️ Flexible Deployment - Cloud, HPC, or local environments

📚 Learn more: What is NextGen?

---

🏗️ For Developers

Quick Development Setup

# Clone and setup
git clone https://github.com/skoriche/NGIAB-Calibration-DevCon25.git
cd NGIAB-Calibration-DevCon25
./dev_install.sh

What You Can Modify

Modify	Tool to Change	Also Update
Data processing, forcing inputs	ngiab_data_preprocess	-
Calibration CLI, default configs	ngiab-cal	-
NextGen core, add models	NGIAB-CloudInfra	-
Calibration algorithms	ngen-cal	NGIAB-CloudInfra

⚙️ Complete guide: Development Setup

---

🤝 Getting Help

• During the Workshop: Ask instructors and assistants
• Common Issues: See Troubleshooting Guide
• Questions/Bugs: Open GitHub Issues
• Email: [email protected], [email protected]

---

📝 License and Acknowledgment

This workshop is supported by the Cooperative Institute for Research to Operations in Hydrology (CIROH) with funding from the NOAA Cooperative Institute Program. The tools, workflows, and concepts presented in this workshop build upon the significant efforts and contributions of several key groups and individuals. We gratefully acknowledge:

• The development of the NextGen In A Box (NGIAB) ecosystem is a central initiative of CIROH-UA, with key development contributions from the AWI Science and Technology Team.
• The core NGEN-Cal tool, fundamental to the calibration processes showcased, was developed by the NOAA Office of Water Prediction (NOAA-OWP) in collaboration with Lynker.
• The NGEN-Cal calibration workflow, initially developed by Xia Feng, was subsequently refactored and integrated to operate within the NGIAB ecosystem by Josh Cunningham, with crucial domain science contributions from Sifan A. Koriche, Md Shahabul Alam, and James Halgren.
• This GitHub repository, which serves as the central hub for all workshop materials, tools, detailed instructions, pre-conference and other relevant information, was prepared and is maintained by Sifan A. Koriche and Josh Cunningham.

The statements, findings, conclusions, and recommendations presented in this workshop and its associated materials are those of the author(s) and do not necessarily reflect the official opinions of NOAA, CIROH, or the other acknowledged contributing organizations and individuals.

---

🚀 Ready to start? Jump to the Quickstart Guide now!