Hydro-Flow CLI: Solving Inverse Hydraulic Problems with AI & Scipy

This is a submission for the GitHub Copilot CLI Challenge

What I Built

Hydro-Flow CLI is an AI-augmented command-line tool designed to bring HEC-RAS caliber hydrology directly to the terminal.

Typically, civil engineers rely on expensive, heavy GUI software to model river floods. This creates a barrier between engineering physics and modern software practices like CI/CD and Containerization.

Hydro-Flow breaks this barrier. It is a "Headless" engineering engine that allows you to:

1. Auto-Design Channels: Solve the "Inverse Hydraulic Problem" using Scipy Optimization (Newton-Raphson) to find the exact channel width that minimizes excavation costs.
2. Stress-Test Infrastructure: Run 1,000 Monte Carlo simulations in seconds to predict flood failure probabilities under climate change scenarios.
3. Generate Digital Twins: Instantly plot hydraulic cross-sections using procedural Matplotlib generation.
4. Ship Anywhere: Run complex physics models on any machine using Docker.

Battle-tested on data from the Ona River Basin (Nigeria), this project merges rigorous Civil Engineering physics with modern DevOps.

Demo

Here is Hydro-Flow in action, demonstrating the Auto-Designer, Risk Analysis, and Docker Containerization.

⏩ VIDEO NAVIGATION (Skip to the features):

• 0:45 - THE AI AGENT: How Copilot CLI wrote the Scipy Optimization logic.
• 1:30 - DEMO 1: Auto-Designing Channels (The Inverse Solver).
• 2:15 - DEMO 2: Monte Carlo Risk Analysis (1,000 Simulations).
• 3:45 - DEMO 3: Visualization (Generating the Digital Twin).
• 4:30 - THE DOCKER RUN: Proof of Production-Readiness.

🔗 Project Links:

• GitHub Repository: https://github.com/AdMub/hydro-flow-cli

My Experience with GitHub Copilot CLI

Building a physics engine in the terminal is difficult because it requires deep knowledge of two very different fields: Fluid Dynamics and Systems Programming.

I used the GitHub Copilot CLI not just as a code completer, but as a Domain Expert and DevOps Engineer. It transformed my workflow from "searching StackOverflow" to "conversational coding."

1. The "Math Expert": Solving Inverse Problems

I needed to implement a cost-minimization function for the river channel width, which involves finding the root of the Manning Equation derivative.

• The Prompt: I asked Copilot CLI how to map engineering constraints (Max Depth < 5.0m) into a scipy.optimize.minimize_scalar function.
• The Result: It generated the exact Python bounds logic and objective function needed to solve the optimization problem mathematically, saving me hours of deriving formulas.

2. The "DevOps Expert": Debugging Docker

Towards the end of the project, I hit a critical wall. When I tried to run the tool inside Docker, I kept getting ModuleNotFoundError: No module named 'hydro'.

• The Interaction: I used Copilot CLI to analyze my file structure. It correctly identified that my PYTHONPATH was not set in the container and that I was missing specific __init__.py files.
• The Fix: It generated a production-ready Dockerfile that explicitly set ENV PYTHONPATH=/app and handled the package resolution, allowing the tool to run anywhere.

3. The "Visual Expert": Procedural Geometry

Plotting a trapezoidal river channel with varying water levels requires complex coordinate geometry (calculating the intersection points of the water surface with the sloped banks). Copilot CLI generated the Matplotlib fill logic ("PolyCollection") to render the "Digital Twin" images dynamically based on the user's JSON profile.

---

Built with Python, Typer, Rich, Scipy, Matplotlib, and GitHub Copilot.