Module 3b: AI-Assisted Coding for Water Modellers

Let AI Help You Write Python Code¶

Time required: 20-25 minutes
Prerequisites: Module 3a (Python basics)
What you’ll learn:

• Understand what AI coding assistants can (and cannot) do

• Write effective prompts to get working code

• Debug errors with AI help

• Verify AI-generated code for engineering applications

Why this matters: As a water modeller, you’re an expert in hydrology, hydraulics, or groundwater systems—not necessarily in Python syntax. AI assistants can bridge that gap, letting you focus on the science while they handle the code details.

Why Use AI for Coding?¶

AI coding assistants like Claude and ChatGPT can dramatically accelerate your Python learning:

• Describe what you need in plain language → Get working code

• Fix errors without hours of searching Stack Overflow

• Learn as you go by asking “why does this work?”

• Focus on the science, not memorizing syntax

Free Options to Get Started¶

Both Claude and ChatGPT work similarly for coding tasks. We’ll use Claude in examples, but the approach applies to any AI assistant.

IDE-Integrated AI Tools (Optional)¶

For a more integrated coding experience, these tools embed AI directly into your code editor:

These tools are optional but can speed up your workflow once you’re comfortable with Python basics.

Critical Warning: AI Limitations for Water Modelling¶

Warning: AI is a coding assistant, not a hydrological expert!

What AI CAN Do¶

• ✅ Write correct Python syntax

• ✅ Implement equations you specify

• ✅ Fix coding errors and bugs

• ✅ Explain what code does

• ✅ Suggest improvements to code structure

What AI CANNOT Do¶

• ❌ Tell you if you’re using the wrong equation for your flow regime

• ❌ Validate your conceptual model

• ❌ Verify if results are physically plausible

• ❌ Know the specific conditions of your catchment or aquifer

• ❌ Replace your engineering judgment

You Must Always Verify¶

Remember: AI can write syntactically correct code that produces physically impossible results. Your domain expertise is essential!

The Art of Prompting: How to Ask for Code¶

The quality of AI-generated code depends heavily on how you ask for it. Vague requests produce vague (or wrong) results.

Bad Prompt (Vague)¶

Make me a graph of discharge data

Problems:

• What file? What format?

• What columns? What units?

• What kind of graph?

• Save it or display it?

Good Prompt (Specific)¶

Write Python code that:
1. Reads a CSV file called "discharge.csv" with columns "date" and "Q_m3s"
2. Converts the date column to datetime format
3. Creates a line plot showing discharge over time
4. Adds axis labels with units (Date, Discharge m³/s)
5. Saves the plot as PNG at 300 DPI

Use pandas and matplotlib. Include comments explaining each step.

Why this works: Every detail is specified—file name, column names, units, output format, and even which libraries to use.

Key Elements of Good Prompts¶

Prompt Template for Water Modelling¶

Here’s a template you can adapt:

I'm a [hydrologist/hydraulic engineer/groundwater modeller] working with 
[describe your data or problem].

Input: [file name, format, columns, units]
Output: [what you want to produce]
Tools: Use [pandas/numpy/matplotlib/etc.]

Please write Python code that:
1. [First step]
2. [Second step]
3. [Third step]

Include comments explaining each step for a beginner.

Practical Example 1: Loading Hydrological Data¶

Let’s see what a good prompt produces. Here’s what you might ask Claude:

Your Prompt¶

I'm a hydrologist new to Python. I have a CSV file called "station_data.csv" 
with these columns:
- timestamp (format: 2024-01-15 12:00)
- water_level_m
- discharge_m3s

Write Python code to:
1. Load this CSV using pandas
2. Convert timestamp to proper datetime
3. Set timestamp as the index
4. Print the first 5 rows and basic statistics

Include comments explaining each step for a beginner.

What Claude Might Return¶

import pandas as pd

# Load the CSV file into a pandas DataFrame
# A DataFrame is like an Excel spreadsheet in Python
df = pd.read_csv('station_data.csv')

# Convert the 'timestamp' column from text to actual dates
# This allows us to do time-based operations later
df['timestamp'] = pd.to_datetime(df['timestamp'])

# Set timestamp as the index (row labels)
# This makes time-series operations much easier
df = df.set_index('timestamp')

# Display the first 5 rows to verify data loaded correctly
print("First 5 rows of data:")
print(df.head())
print()

# Show basic statistics (mean, min, max, std, etc.)
print("Basic statistics:")
print(df.describe())

Notice how the AI:

• Added helpful comments explaining each step

• Used exactly the column names you specified

• Followed your step-by-step instructions

Practical Example 2: Asking for Bug Fixes¶

When your code doesn’t work, AI excels at debugging. The key is to provide:

1. The code that’s failing

2. The exact error message

3. What you expected to happen

Your Prompt¶

I'm running this Python code:

import pandas as pd
df = pd.read_csv('my_data.csv')
df['date'] = pd.to_datetime(df['date'])

But I get this error:

KeyError: 'date'

What's wrong and how do I fix it?

What Claude Will Explain¶

The AI will tell you:

• The column ‘date’ doesn’t exist in your CSV (maybe it’s called ‘Date’ or ‘datetime’)

• How to check what columns actually exist: print(df.columns)

• Common causes: typos, different capitalization, extra spaces in column names

• A corrected version of your code

Tip: Always copy the complete error message, not just the last line. The full traceback helps AI understand where the problem occurred.

Practical Example 3: Extending Your Code¶

One of AI’s best uses is adding features to existing code. Let’s say you have the Manning’s equation function from Module 3a and want to extend it.

Your Prompt¶

I have this Python function that calculates flow velocity using Manning's equation:

def calculate_velocity(hydraulic_radius, slope, mannings_n):
    velocity = (1 / mannings_n) * (hydraulic_radius ** (2/3)) * (slope ** 0.5)
    return velocity

Please modify it to:
1. Add a docstring with parameter descriptions and units
2. Add input validation (all values must be positive)
3. Also return the discharge if I provide the cross-sectional area
4. Round results to 3 decimal places

Keep it simple and add comments explaining the changes.

The AI will return an improved version with all your requested features, properly documented.

Verification Strategies: Don’t Trust, Verify!¶

AI-generated code should always be verified, especially for engineering applications. Here are strategies:

1. Test with Known Values¶

Use hand calculations or textbook examples to verify results:

# Verify critical depth calculation
# For q = 2.5 m²/s, textbook says yc ≈ 0.86 m
result = calculate_critical_depth(2.5)
expected = 0.86
print(f"Calculated: {result:.2f} m, Expected: {expected} m")
assert abs(result - expected) < 0.01, "Result doesn't match expected value!"

2. Check Units Consistency¶

Ask AI to verify units:

Are the units in this calculation consistent? 
I have discharge in m³/s and I'm calculating volume in cubic meters over a day.

3. Sanity Check Results¶

Ask if results are physically reasonable:

The calculated groundwater velocity is 500 m/day. 
Does this seem physically reasonable for an alluvial aquifer?

(Spoiler: 500 m/day is extremely high—typical values are 0.1-10 m/day)

4. Compare with Analytical Solutions¶

For problems with known solutions:

Can you add code to compare this numerical Theis solution 
result with the analytical equation?

Tips for Learning While Using AI¶

Don’t just copy-paste code—use AI as a learning tool!

Ask “Why?”¶

After getting working code, ask follow-up questions:

Why did you use `df.set_index()` instead of just keeping the date as a column?

What does the `inplace=True` parameter do?

Ask for Alternatives¶

Show me another way to calculate monthly means in pandas.
When would I use each approach?

Ask for Explanations¶

Explain what this line does as if I'm a hydrologist who knows 
nothing about Python: df.groupby('station').agg({'Q': 'mean'})

Build Incrementally¶

Don’t ask for huge scripts all at once. Build step by step:

1. First: “How do I read a CSV?”

2. Then: “How do I filter for values above a threshold?”

3. Then: “How do I calculate rolling averages?”

This approach:

• Makes debugging easier

• Helps you understand each component

• Builds your knowledge progressively

Common Pitfalls to Avoid¶

Managing AI-Generated Code¶

Even if AI wrote the code, you should manage it properly:

• Save your work in well-named files

• Document what the code does (AI can help with this too!)

• Save successful prompts - they’re reusable for similar tasks

• Share working solutions with colleagues

Prompt Templates for Water Modelling¶

Here are ready-to-use templates for common tasks. Copy, modify, and use!

Template 1: Data Processing¶

I need to process hydrological data.

Input: CSV file "[filename]" with columns [list columns and units]
Output: [what you want to produce]
Tools: Use pandas and numpy

Please write Python code with comments explaining each step.

Template 2: Visualization¶

Create a [type of plot] showing [what data].

The data is in a pandas DataFrame with columns [list columns].
The plot should include:
- X-axis: [label with units]
- Y-axis: [label with units]
- Title: "[title]"
- [any other requirements: legend, grid, colors]
- Save as [format] at [resolution] DPI

Use matplotlib.

Template 3: Debugging¶

This code is supposed to [expected behavior]:

[paste your code]

But instead I get [actual behavior or error message]:

[paste error]

What's wrong and how do I fix it? Explain so I can learn.

Template 4: Code Review¶

Please review this Python code for a water balance calculation:

[paste your code]

Check for:
1. Any bugs or errors
2. Unit consistency
3. Potential improvements
4. Missing edge cases

Try It Yourself: Interactive Exercise¶

Let’s practice! Use Claude or ChatGPT to complete this task.

Your Task¶

Write a prompt asking AI to create a function that:

1. Calculates the Froude number: $Fr = \frac{v}{\sqrt{g \cdot y}}$

2. Takes velocity (m/s) and depth (m) as inputs

3. Returns the Froude number and the flow regime (subcritical/critical/supercritical)

4. Includes a proper docstring with units

Hints for Your Prompt¶

• Specify the formula clearly

• Mention the units for each parameter

• Define what makes flow subcritical (Fr < 1), critical (Fr = 1), or supercritical (Fr > 1)

• Ask for comments and a docstring

Test the Result¶

Once you get code from AI, paste it in the cell below and test it:

Verification Checklist¶

After getting AI-generated code, verify:

• Does the function include a docstring with units?

• Does it use the correct formula?

• Does Fr=0.11 for v=0.5 m/s, y=2.0 m? (subcritical)

• Does Fr≈2.9 for v=5.0 m/s, y=0.3 m? (supercritical)

• Does it correctly identify the flow regime?

Summary: AI-Assisted Coding Best Practices¶

Do’s¶

• ✅ Write specific, detailed prompts

• ✅ Include units and data formats

• ✅ Test with known values

• ✅ Ask “why?” to learn

• ✅ Build code incrementally

• ✅ Verify results make physical sense

Don’ts¶

• ❌ Trust AI for engineering judgment

• ❌ Accept code without understanding it

• ❌ Assume AI knows your specific conditions

• ❌ Skip unit verification

• ❌ Ask for huge scripts all at once

Remember¶

AI is a powerful tool, but you are the engineer.
The AI writes syntax; you ensure physical correctness.

What’s Next?¶

Now you have two powerful skills:

• Python basics from Module 3a

• AI assistance from this module

You’re ready to tackle real-world data!

Module 4a: Getting Hydrological Data

• Access open streamflow datasets (CAMELS, GRDC)

• Download real discharge data with Python

• Use AI to help when you get stuck

Module 4b: Discharge Analysis

• Analyze real streamflow time series

• Calculate statistics and create visualizations

• Apply everything you’ve learned

Next Module: Module 4a: Getting Hydrological Data