Quick Start

Your First Analysis

Create a new Python file to run a quick analysis:

from pyhnhtools import load_input, run_backwater

# Load a model from JSON
model = load_input('example_model.json')

# Run the steady-state analysis
results = run_backwater(model)

# Access results
print(f"Water surface elevation: {results.wse}")
print(f"Velocity: {results.velocity}")

Model File Format

The input JSON file should contain:

{
  "reach_name": "Example Reach",
  "discharge": 500.0,
  "manning_n": 0.035,
  "cross_sections": [
    {
      "station": 0.0,
      "elevation": 100.0,
      "coordinates": [[0, 100], [10, 105], [20, 100]]
    },
    {
      "station": 100.0,
      "elevation": 99.5,
      "coordinates": [[0, 99.5], [10, 104.5], [20, 99.5]]
    }
  ]
}

Using the GUI

For interactive model setup and visualization:

python -m pyhnhtools.gui.app

The GUI provides:

  • Graphical model creation and editing

  • Interactive cross-section editing

  • Real-time plot visualization

  • Scenario management

  • File import/export

Python API Overview

Core Functions

load_input(filepath)

Load a model from JSON file.

Args:

filepath (str): Path to JSON model file

Returns:

ModelInput: Model object

run_backwater(model, output_csv=None)

Run standard step 1D analysis.

Args:

model (ModelInput): Input model output_csv (str, optional): Output CSV filepath

Returns:

Results: Analysis results object

Data Classes

ModelInput

Container for model data.

Attributes:

reach_name (str): Name of reach discharge (float): Flow in cubic feet per second manning_n (float): Manning’s roughness coefficient cross_sections (list): List of CrossSection objects

CrossSection

Cross-section geometry and elevation.

Attributes:

station (float): Distance along reach elevation (float): Invert elevation coordinates (list): [[x1, z1], [x2, z2], …] format

Results

Output from solver.

Attributes:

wse (list): Water surface elevation at each section velocity (list): Velocity at each section profile (dict): Complete profile data

Common Workflows

Batch Analysis

Run multiple discharge scenarios:

from pyhnhtools import load_input, run_backwater

model = load_input('base_model.json')

discharges = [100, 250, 500, 1000]
results_dict = {}

for Q in discharges:
    model.discharge = Q
    results = run_backwater(model)
    results_dict[Q] = results

Parameter Sensitivity

Evaluate Manning’s n sensitivity:

from pyhnhtools import load_input, run_backwater

model = load_input('model.json')
n_values = [0.025, 0.035, 0.045, 0.055]

for n in n_values:
    model.manning_n = n
    results = run_backwater(model)
    print(f"n={n}: WSE={results.wse}")

Next Steps