NWC-CUAHSI Summer Institute 2025: Workshop on Hydrological Model Calibration in the NGIAB Ecosystem

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

• 📅 Date: Wednesday, June 18, 2025
• ⏰ Time: Wednesday, June 18 | 10:45 – 12 pm CT
• 📍 Location: Cyber Hall GWSC classroom, Room number 1160, 248 Kirkbride Ln, Tuscaloosa, AL 35401
• 🏛️ Organized by: CUAHSI and The University of Alabama

---

👥 Instructors

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.

🚀 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

[graphics by Sifan A. Koriche]

---

🛠️ Prerequisites

Data

• Create your own uvx --from ngiab_data_preprocess cli -i gage-10154200 --start 2007-10-01 --end 2013-09-30 -srf --source aorc
• Or 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

uvx --from ngiab_data_preprocess cli -i gage-10154200 --start 2007-10-01 --end 2013-09-30 -srf --source aorc
uvx ngiab-cal ~/ngiab_preprocess_output/gage-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

The Summer Institute is a partnership between CUAHSI, and the University of Alabama that aims to engage the academic community in research to advance water prediction and flood forecasting. 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.

---

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