GUI Tutorial

Launching the GUI

Start the application:

python -m pyhnhtools.gui.app

Or programmatically:

from pyhnhtools.gui import make_main_window

window = make_main_window()
window.show()

Interface Overview

The GUI consists of three main panels:

Left Panel (Input)

  • Load/Save models

  • Create new models

  • Edit parameters

Center Panel (Visualization)

  • Interactive plots

  • Profile display

  • Cross-section view

Right Panel (Results)

  • Summary statistics

  • Detailed results table

  • Analysis information

Main Workflow

  1. Load or Create a Model

    • Click “Load Model” to open existing JSON file

    • Or click “New Model” to start fresh

  2. Edit Model Parameters

    • Set reach name

    • Specify discharge (Q)

    • Set Manning’s roughness (n)

  3. Add/Edit Cross-Sections

    • Define station and elevation

    • Input cross-section coordinates

    • Add multiple sections

  4. Validate Model

    • Check for errors

    • Verify data completeness

  5. Run Analysis

    • Click “Run Solver”

    • Monitor progress

    • View results in real-time

  6. Visualize Results

    • Water surface profile plot

    • Cross-section plots

    • Velocity visualization

  7. Save Results

    • Export to JSON

    • Save plots as images

    • Export to CSV

Creating a New Model

Step-by-step model creation:

  1. Click “New Model” button

  2. Enter reach name (e.g., “Example Reach”)

  3. Set discharge: 500 cfs

  4. Set Manning’s n: 0.035

  5. Click “Add Cross-Section” button

  6. Enter section 1:

    • Station: 0.0

    • Elevation: 100.0

    • Coordinates (click to add points): - (0, 100) - (10, 105) - (20, 100)

  7. Add section 2:

    • Station: 100.0

    • Elevation: 99.5

    • Coordinates: - (0, 99.5) - (10, 104.5) - (20, 99.5)

  8. Click “Run Solver” to analyze

  9. Review results in right panel

Editing Cross-Sections

Modify existing cross-sections:

  1. Select section from table

  2. Click “Edit Section”

  3. Modify coordinates

  4. Click “Update Section”

  5. Click “Run Solver” to recalculate

Plotting Options

Interactive Plot Features:

  • Hover for values

  • Zoom by clicking and dragging

  • Pan with middle mouse button

  • Reset view with home icon

  • Export as PNG using camera icon

Interpretation

Profile Plot

  • Blue line: Channel bed

  • Red line: Water surface

  • Green line: Critical depth (if calculated)

Cross-Section Plot

  • Black line: Channel geometry

  • Blue fill: Wetted area

Velocity Plot

  • Color gradient: Velocity magnitude

  • Warmer colors: Higher velocities

Saving Your Work

Save Model (JSON)

  • Preserves all geometry and parameters

  • Human-readable format

  • Can be opened in any text editor

Export Results (CSV)

  • Station, elevation, WSE, velocity, depth

  • Easy import to Excel or other tools

Save Plot (PNG/SVG)

  • High-resolution images

  • Suitable for reports

Keyboard Shortcuts

  • Ctrl+O: Open model

  • Ctrl+S: Save model

  • Ctrl+N: New model

  • Ctrl+R: Run solver

  • Ctrl+Q: Quit application

  • Ctrl+Z: Undo (if available)

Tips & Tricks

Quick Model Setup

Use template models and modify parameters

Batch Analysis

Create multiple models with varying discharge

Quality Checks

Always run model validation before solving

Performance

Large cross-sections (>100 points) may slow rendering

Export Workflow

Save JSON model → Run → Export results → Process in Excel

Troubleshooting

Plots not displaying

  • Check data validity

  • Ensure cross-sections overlap

  • Verify water surface solution

Solver errors

  • Add more cross-sections

  • Check Manning’s n reasonableness (0.02-0.08)

  • Verify coordinate units consistency

Memory issues

  • Close other applications

  • Reduce number of cross-section points

  • Use command-line API for large batches

Next Steps