Advanced Structure Validation with RasCheck¶
This notebook demonstrates the advanced structure validation features added to RasCheck in December 2025:
- Culvert hydraulics validation (CV_LF_01, CV_LF_02, CV_CF_01, CV_CF_02, CV_TF_04)
- Starting WSE method validation (PF_IC_00, PF_IC_01, PF_IC_02, PF_IC_03, PF_IC_04)
# =============================================================================
# DEVELOPMENT MODE TOGGLE
# =============================================================================
USE_LOCAL_SOURCE = True # <-- Set to True for check module (in development)
if USE_LOCAL_SOURCE:
import sys
from pathlib import Path
local_path = str(Path.cwd().parent)
if local_path not in sys.path:
sys.path.insert(0, local_path)
print(f"📁 LOCAL SOURCE MODE: Loading from {local_path}/ras_commander")
else:
print("📦 PIP PACKAGE MODE: Loading installed ras-commander")
print("⚠️ WARNING: Check module may not be available in pip package yet")
# Import ras-commander
from ras_commander import HdfPlan, HdfResultsPlan, HdfStruc, RasCheck, RasCmdr, RasExamples, init_ras_project, ras
# Verify which version loaded
import ras_commander
print(f"✓ Loaded: {ras_commander.__file__}")
📁 LOCAL SOURCE MODE: Loading from D:\CLB-Temp\clb-t3-pr534\repo2/ras_commander
✓ Loaded: D:\CLB-Temp\clb-t3-pr534\repo2\ras_commander\__init__.py
Parameters¶
Configure these values to customize the notebook for your project.
# =============================================================================
# PARAMETERS - Edit these to customize the notebook
# =============================================================================
from pathlib import Path
# Project Configuration
PROJECT_NAME = "ConSpan Culvert" # Steady flow culvert project (fast execution ~10 sec)
RAS_VERSION = "7.0" # HEC-RAS version (6.3, 6.5, 6.6, etc.)
SUFFIX = "801" # Notebook identifier for project extraction
# Execution Settings
PLAN = "01" # Plan number to execute (will be updated based on available plans)
NUM_CORES = 4 # CPU cores for 2D computation
# Note: All outputs are saved within the extracted project folder
print(f"Project will be extracted to: example_projects/{PROJECT_NAME}_{SUFFIX}/")
Project will be extracted to: example_projects/ConSpan Culvert_801/
Import Required Modules¶
from ras_commander import (
RasExamples, init_ras_project, ras,
RasCmdr, HdfResultsPlan
)
from ras_commander.hdf import HdfStruc, HdfPlan
from ras_commander.check import (
RasCheck, CheckResults, Severity,
RasCheckReport, ReportMetadata,
get_default_thresholds
)
import pandas as pd
import matplotlib.pyplot as plt
import numpy as np
from pathlib import Path
# Set pandas display options
pd.set_option('display.max_rows', 20)
pd.set_option('display.max_columns', None)
pd.set_option('display.width', None)
Extract and Initialize Project¶
We'll use the ConSpan Culvert example which is a steady flow project with culvert structures. This project executes quickly (~10 seconds) making it ideal for automated testing.
Verification for Structure Validation¶
After running structure validation checks:
- [ ] All culvert flow classifications are reasonable (Inlet/Outlet control)
- [ ] Bridge expansion coefficients < 0.5 (FHWA HDS-1 guidance)
- [ ] Starting WSE within 0.5 ft of computed water surface
- [ ] Structure geometry matches as-built dimensions
References: - FHWA HDS-1: Bridge Hydraulics - FHWA HDS-5: Culvert Hydraulics - USACE EM 1110-2-1416, Chapter 12: Hydraulic Structures
# Extract the Bald Eagle Creek example project
project_path = RasExamples.extract_project(PROJECT_NAME, suffix=SUFFIX)
print(f"Extracted project to: {project_path}")
2026-10-15 03:22:34 - ras_commander.RasExamples - INFO - Successfully extracted project 'ConSpan Culvert' to example_projects\ConSpan Culvert_801
Extracted project to: D:\CLB-Temp\clb-t3-pr534\repo2\examples\example_projects\ConSpan Culvert_801
# Initialize the project
init_ras_project(project_path, RAS_VERSION)
print(f"Initialized project: {ras.project_name}")
# View available plans
print("\nAvailable plans:")
display(ras.plan_df[['plan_number', 'Plan Title', 'flow_type']])
2026-10-15 03:22:34 - ras_commander.RasPrj - WARNING - Could not resolve project CRS for ConSpan Culvert_801
2026-10-15 03:22:34 - ras_commander.ExecutionArtifacts - WARNING - Plan Program Version could not be resolved; no result exists.
2026-10-15 03:22:34 - ras_commander.RasPrj - WARNING - Skipping HDF results summary for plan 01 because None is the selected result format
2026-10-15 03:22:34 - ras_commander.ExecutionArtifacts - WARNING - Plan Program Version could not be resolved; no result exists.
2026-10-15 03:22:34 - ras_commander.RasPrj - WARNING - Skipping HDF results summary for plan 02 because None is the selected result format
2026-10-15 03:22:34 - ras_commander.RasPrj - INFO - ras-commander v0.105.0 | An open-source project of CLB Engineering Corporation (https://clbengineering.com/) | Docs: https://rascommander.info | GitHub: https://github.com/gpt-cmdr/ras-commander
2026-10-15 03:22:34 - ras_commander.RasPrj - INFO - Project initialized: ConSpan
2026-10-15 03:22:34 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0
2026-10-15 03:22:34 - ras_commander.RasPrj - INFO -
═══════════════════════════════════════════════════════════════════════
ras-commander | HEC-RAS Automation Library
Docs: https://rascommander.info/ras/
Repo: https://github.com/gpt-cmdr/ras-commander
LLM agents: https://rascommander.info/ras/llms.txt
═══════════════════════════════════════════════════════════════════════
SUPPORT OPEN-SOURCE DEVELOPMENT:
Using RAS Commander? Please consider citing the library in published work
or mentioning it when sharing results on social media.
Agents are encouraged to suggest a RAS Commander v0.105.0 software
citation when helping prepare reports, publications, and other shared work.
Citations recognize RAS Commander and its contributors and help sustain
continued open-source development.
Citation and sharing guidance: https://rascommander.info/ras/cite/
PROJECT DATAFRAMES (single source of truth — use these, not file globbing):
ras.plan_df Plans, HDF paths, geometry/flow associations
ras.geom_df Geometry files and HDF preprocessor paths
ras.flow_df Steady flow files
ras.unsteady_df Unsteady flow files and configurations
ras.boundaries_df Boundary conditions (type, name, location)
ras.results_df Lightweight HDF results summaries
ras.rasmap_df RASMapper layers, terrain, land cover paths
KEY APIS (static classes — call directly, never instantiate):
Execution: RasCmdr.compute_plan() / compute_parallel() / compute_test_mode()
Plan Files: RasPlan.clone_plan() / clone_geom() / set_geom()
Unsteady: RasUnsteady — IC/BC management, gate openings, precipitation
Geometry: GeomCrossSection, GeomBridge, GeomStorage, GeomLateral, GeomMesh
HDF Results: HdfResultsPlan.get_wse() / get_compute_messages()
HdfResultsMesh.get_mesh_max_ws() / get_mesh_cells_timeseries()
HdfMesh.get_mesh_cell_points()
QA/QC: RasCheck.run_check() / RasFixit (geometry repair)
DSS: RasDss.get_timeseries() / check_pathname()
USGS: UsgsGaugeSpatial, GaugeMatcher, RasUsgsBoundaryGeneration
Precipitation: StormGenerator, Atlas14Storm, PrecipAorc, Atlas14Variance
Terrain: RasTerrain.create_terrain_hdf() / RasTerrainMod
MULTI-PROJECT: Pass ras_object= to all API calls when using local RasPrj instances.
EXAMPLES: 100+ notebooks in examples/ (100s=execution, 200s=geometry, 300s=unsteady,
400s=HDF results, 500s=remote, 800s=QA/QC, 900s=data integration).
Review relevant notebooks before assembling new workflows.
PLATFORM: Most HEC-RAS operations require Windows. Linux/Wine support for
headless execution, data access, geometry modification, and preprocessing
is available via RasProcess (HEC-RAS 6.6+). See ras_commander/RasProcess.py.
Remote distributed execution: ras_commander/remote/ (PsExec, Docker, SSH, cloud).
═══════════════════════════════════════════════════════════════════════
Initialized project: ConSpan
Available plans:
| plan_number | Plan Title | flow_type | |
|---|---|---|---|
| 0 | 01 | ConSpan Culvert | Steady |
| 1 | 02 | Twin Circular Culverts | Steady |
# Find a steady flow plan for structure validation
steady_plans = ras.plan_df[ras.plan_df['flow_type'] == 'Steady']
if steady_plans.empty:
print("⚠️ No steady flow plans found - using first available plan")
plan_number = ras.plan_df.iloc[0]['plan_number']
else:
# Use plan 02 if available, otherwise first steady plan
if '02' in steady_plans['plan_number'].values:
plan_number = '02'
else:
plan_number = steady_plans.iloc[0]['plan_number']
print(f"Selected plan: {plan_number} ({ras.plan_df[ras.plan_df['plan_number']==plan_number].iloc[0]['flow_type']})")
# Execute the plan (skip if results already exist)
print(f"Running Plan {plan_number}...")
success = RasCmdr.compute_plan(plan_number, skip_existing=True)
if success:
print(f"✓ Plan {plan_number} ready for validation")
else:
print(f"✗ Plan {plan_number} execution failed")
Selected plan: 02 (Steady)
Running Plan 02...
2026-10-15 03:22:37 - ras_commander.ExecutionArtifacts - INFO - Removed plan 02 execution artifact: ConSpan.O02
2026-10-15 03:22:37 - ras_commander.ExecutionArtifacts - WARNING - Plan Program Version could not be resolved; selected the sole existing result format.
✓ Plan 02 ready for validation
# Display results summary from results_df
ras.results_df[['plan_number', 'plan_title', 'completed', 'has_errors', 'has_warnings', 'runtime_complete_process_hours']]
| plan_number | plan_title | completed | has_errors | has_warnings | runtime_complete_process_hours | |
|---|---|---|---|---|---|---|
| 0 | 02 | Twin Circular Culverts | True | False | False | 0.000278 |
# Get HDF paths with defensive checking
print(f"DEBUG: Looking for plan '{plan_number}'")
print(f"DEBUG: Available plan numbers: {ras.plan_df['plan_number'].tolist()}")
# Filter for the plan
filtered_plans = ras.plan_df[ras.plan_df['plan_number'] == plan_number]
print(f"DEBUG: Filtered result shape: {filtered_plans.shape}")
# Defensive check before accessing
if filtered_plans.empty:
raise ValueError(
f"Plan '{plan_number}' not found in project. "
f"Available plans: {ras.plan_df['plan_number'].tolist()}"
)
plan_row = filtered_plans.iloc[0]
plan_hdf = Path(plan_row['HDF_Results_Path'])
# Geometry HDF has .g##.hdf suffix (NOT .hdf replacing .g##)
geom_path = Path(plan_row['Geom Path'])
geom_hdf = Path(str(geom_path) + '.hdf') # e.g., geometry.g01.hdf
print(f"Plan HDF: {plan_hdf}")
print(f"Geom HDF: {geom_hdf}")
# Verify files exist
if not plan_hdf.exists():
print(f"⚠️ WARNING: Plan HDF not found: {plan_hdf}")
if not geom_hdf.exists():
print(f"⚠️ WARNING: Geom HDF not found: {geom_hdf}")
DEBUG: Looking for plan '02'
DEBUG: Available plan numbers: ['01', '02']
DEBUG: Filtered result shape: (1, 46)
Plan HDF: D:\CLB-Temp\clb-t3-pr534\repo2\examples\example_projects\ConSpan Culvert_801\ConSpan.p02.hdf
Geom HDF: D:\CLB-Temp\clb-t3-pr534\repo2\examples\example_projects\ConSpan Culvert_801\ConSpan.g02.hdf
Part 1: Culvert Hydraulics Extraction¶
The new HdfStruc.get_culvert_hydraulics() function extracts comprehensive culvert data from geometry HDF files.
# Extract culvert hydraulic properties
culvert_data = HdfStruc.get_culvert_hydraulics(geom_hdf)
if not culvert_data.empty:
print(f"Found {len(culvert_data)} culverts in geometry")
print(f"\nColumns: {list(culvert_data.columns)}")
display(culvert_data)
else:
print("No culverts found in this project")
2026-10-15 03:22:37 - ras_commander.hdf.HdfStruc - WARNING - Culvert structures found in ConSpan.g02.hdf, but Geometry/Structures/Culvert Data is absent; returning structure attributes only.
Found 1 culverts in geometry
Columns: ['Type', 'Mode', 'River', 'Reach', 'RS', 'Connection', 'Groupname', 'US Type', 'US River', 'US Reach', 'US RS', 'US SA/2D', 'DS Type', 'DS River', 'DS Reach', 'DS RS', 'DS SA/2D', 'Node Name', 'Description', 'Last Edited', 'Upstream Distance', 'Weir Width', 'Weir Max Submergence', 'Weir Min Elevation', 'Weir Coef', 'Weir Shape', 'Weir Design EG Head', 'Weir Design Spillway HT', 'Weir US Slope', 'Weir DS Slope', 'Linear Routing Positive Coef', 'Linear Routing Negative Coef', 'Linear Routing Elevation', 'LW HW Position', 'LW TW Position', 'LW HW Distance', 'LW TW Distance', 'LW Span Multiple', 'Use 2D for Overflow', 'Use Velocity into 2D', 'Hagers Weir Coef', 'Hagers Height', 'Hagers Slope', 'Hagers Angle', 'Hagers Radius', 'Use WS for Weir Reference', 'Pilot Flow', 'Culvert Groups', 'Culverts Flap Gates', 'Gate Groups', 'HTAB FF Points', 'HTAB RC Count', 'HTAB RC Points', 'HTAB HW Max', 'HTAB TW Max', 'HTAB Max Flow', 'Cell Spacing Near', 'Cell Spacing Far', 'Near Repeats', 'Protection Radius', 'Use Friction in Momentum', 'Use Weight in Momentum', 'Use Critical US', 'Use EG for Pressure Criteria', 'Ice Option', 'Weir Skew', 'Pier Skew', 'BR Contraction', 'BR Expansion', 'BR Opening K', 'BR Opening Elev', 'BR Overtopping K', 'BR Overtopping Elev', 'BR Struct Mann', 'BR US Left Bank', 'BR US Right Bank', 'BR DS Left Bank', 'BR DS Right Bank', 'XS US Left Bank', 'XS US Right Bank', 'XS DS Left Bank', 'XS DS Right Bank', 'US Ineff Left Sta', 'US Ineff Left Elev', 'US Ineff Right Sta', 'US Ineff Right Elev', 'DS Ineff Left Sta', 'DS Ineff Left Elev', 'DS Ineff Right Sta', 'DS Ineff Right Elev', 'Use Override HW Connectivity', 'Use Override TW Connectivity', 'Use RC Family', 'Use Override HTabIBCurves', 'SNN ID', 'Default Centerline', 'Structure_ID']
| Type | Mode | River | Reach | RS | Connection | Groupname | US Type | US River | US Reach | US RS | US SA/2D | DS Type | DS River | DS Reach | DS RS | DS SA/2D | Node Name | Description | Last Edited | Upstream Distance | Weir Width | Weir Max Submergence | Weir Min Elevation | Weir Coef | Weir Shape | Weir Design EG Head | Weir Design Spillway HT | Weir US Slope | Weir DS Slope | Linear Routing Positive Coef | Linear Routing Negative Coef | Linear Routing Elevation | LW HW Position | LW TW Position | LW HW Distance | LW TW Distance | LW Span Multiple | Use 2D for Overflow | Use Velocity into 2D | Hagers Weir Coef | Hagers Height | Hagers Slope | Hagers Angle | Hagers Radius | Use WS for Weir Reference | Pilot Flow | Culvert Groups | Culverts Flap Gates | Gate Groups | HTAB FF Points | HTAB RC Count | HTAB RC Points | HTAB HW Max | HTAB TW Max | HTAB Max Flow | Cell Spacing Near | Cell Spacing Far | Near Repeats | Protection Radius | Use Friction in Momentum | Use Weight in Momentum | Use Critical US | Use EG for Pressure Criteria | Ice Option | Weir Skew | Pier Skew | BR Contraction | BR Expansion | BR Opening K | BR Opening Elev | BR Overtopping K | BR Overtopping Elev | BR Struct Mann | BR US Left Bank | BR US Right Bank | BR DS Left Bank | BR DS Right Bank | XS US Left Bank | XS US Right Bank | XS DS Left Bank | XS DS Right Bank | US Ineff Left Sta | US Ineff Left Elev | US Ineff Right Sta | US Ineff Right Elev | DS Ineff Left Sta | DS Ineff Left Elev | DS Ineff Right Sta | DS Ineff Right Elev | Use Override HW Connectivity | Use Override TW Connectivity | Use RC Family | Use Override HTabIBCurves | SNN ID | Default Centerline | Structure_ID | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Culvert | Spring Creek | Culvrt Reach | 20.237 | Spring Creek, Culvrt Reach (20.237) | XS | Spring Creek | Culvrt Reach | 20.238 | XS | Spring Creek | Culvrt Reach | 20.227 | Twin Circular Pipe Crossing | 11Sep1996 10:29:42 | 10.0 | 40.0 | 0.95 | 33.700001 | 2.6 | Broad Crested | NaN | NaN | 2.0 | 2.0 | 0.05 | 0.05 | NaN | 0 | 0 | NaN | NaN | 0 | 0 | 0 | NaN | NaN | NaN | NaN | NaN | 0 | NaN | 1 | 0 | 0 | 50 | 50 | 20 | 37.200001 | NaN | NaN | NaN | NaN | 0 | 0 | 0 | 0 | 1 | 1 | 0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | 0 | 0 | 0 | 0 | 6 | 1 | 1 |
Culvert Hydraulics Data Fields¶
| Field | Description | FHWA Reference |
|---|---|---|
| Structure_ID | Unique culvert identifier | - |
| Flow_Regime | Flow regime setting (e.g., "Pressure and Weir Flow") | HDS-5 |
| Entrance_Coefficient | Entrance loss coefficient (Ke) | HDS-5 Table 1 |
| Exit_Coefficient | Exit loss coefficient (Kx) | Typically 1.0 |
| Scale_Factor | Culvert scale factor | - |
| Chart | Chart selection for culvert analysis | HDS-5 |
Reference: FHWA HDS-5 "Hydraulic Design of Highway Culverts"
Visualize Culvert Coefficients¶
Compare entrance and exit coefficients against FHWA guidelines:
if not culvert_data.empty and 'Entrance_Coefficient' in culvert_data.columns:
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 5))
# Entrance coefficients
ax1.barh(culvert_data['Structure_ID'], culvert_data['Entrance_Coefficient'], color='steelblue')
ax1.axvline(0.2, color='red', linestyle='--', label='FHWA Min (0.2)')
ax1.axvline(1.0, color='orange', linestyle='--', label='FHWA Max (1.0)')
ax1.set_xlabel('Entrance Coefficient (Ke)')
ax1.set_ylabel('Structure ID')
ax1.set_title('Culvert Entrance Loss Coefficients')
ax1.legend()
ax1.grid(True, alpha=0.3)
# Exit coefficients
ax2.barh(culvert_data['Structure_ID'], culvert_data['Exit_Coefficient'], color='forestgreen')
ax2.axvline(1.0, color='red', linestyle='--', label='Typical Value (1.0)')
ax2.set_xlabel('Exit Coefficient (Kx)')
ax2.set_ylabel('Structure ID')
ax2.set_title('Culvert Exit Loss Coefficients')
ax2.legend()
ax2.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()
else:
print("No culvert coefficient data available for visualization")
No culvert coefficient data available for visualization
Part 2: Culvert Validation Checks¶
RasCheck now includes 5 culvert validation checks:
| Check ID | Description | Severity |
|---|---|---|
| CV_LF_01 | Entrance loss coefficient out of FHWA range (0.2-1.0) | WARNING |
| CV_LF_02 | Exit loss coefficient deviates from typical (1.0) | WARNING |
| CV_CF_01 | Chart selection may not be appropriate | WARNING |
| CV_CF_02 | Flow regime classification questionable | WARNING |
| CV_TF_04 | Multiple barrel flow distribution issues | WARNING |
# Extract steady profiles
profiles = HdfResultsPlan.get_steady_profile_names(plan_hdf)
print(f"Profiles: {profiles}")
# Run structure checks (includes culvert validation)
structure_results = RasCheck.check_structures(plan_hdf, geom_hdf, profiles)
print(f"Structure Check Results:")
print(f" Total Messages: {len(structure_results.messages)}")
print(f" Errors: {structure_results.get_error_count()}")
print(f" Warnings: {structure_results.get_warning_count()}")
2026-10-15 03:22:37 - ras_commander.hdf.HdfBase - WARNING - Projection not found for ConSpan.g02.hdf; returned geospatial outputs will not have a CRS. Enable DEBUG for checked paths and RASMapper projection setup guidance.
Profiles: ['5 yr', '10 yr', '25 yr', '50 yr']
Structure Check Results:
Total Messages: 3
Errors: 0
Warnings: 3
# Filter for culvert-specific messages (CV_ prefix)
culvert_msgs = [msg for msg in structure_results.messages if msg.message_id.startswith('CV_')]
if culvert_msgs:
print(f"Found {len(culvert_msgs)} culvert validation messages:\n")
for msg in culvert_msgs:
print(f"[{msg.severity.value}] {msg.message_id}: {msg.message}")
if msg.help_text:
print(f" → {msg.help_text}")
print()
else:
print("✓ No culvert validation issues found")
✓ No culvert validation issues found
Culvert Check Details¶
CV_LF_01: Entrance Loss Coefficient¶
What it checks: Entrance loss coefficients (Ke) should be within FHWA guidelines (0.2 to 1.0)
Why it matters: - Too low (<0.2): Underestimates entrance losses, overpredicts capacity - Too high (>1.0): Overestimates losses, underpredicts capacity
FHWA Reference: HDS-5 Table 1 - Entrance Loss Coefficients
CV_LF_02: Exit Loss Coefficient¶
What it checks: Exit loss coefficients (Kx) typically should be 1.0
Why it matters: Exit losses represent full velocity head recovery. Values other than 1.0 should be justified.
CV_CF_01 & CV_CF_02: Chart and Flow Regime¶
What it checks: Appropriate chart selection and flow regime classification
Why it matters: Using the wrong chart or flow regime leads to incorrect culvert performance predictions.
CV_TF_04: Multiple Barrel Distribution¶
What it checks: Flow distribution among multiple barrels
Why it matters: Unequal flow distribution can cause unexpected hydraulic behavior.
Part 3: Starting WSE Method Extraction¶
The new HdfPlan.get_starting_wse_method() function extracts initial condition methods from plan HDF files.
# Extract starting WSE method
wse_method = HdfPlan.get_starting_wse_method(plan_hdf)
print("Starting Water Surface Elevation Method:")
print("="*50)
for key, value in wse_method.items():
print(f" {key}: {value}")
Starting Water Surface Elevation Method:
==================================================
method: Unknown
note: Boundary condition method not found in HDF file
Starting WSE Methods Explained¶
| Method | When to Use | Parameters |
|---|---|---|
| Normal Depth | Subcritical flow, mild slope | Requires friction slope |
| Critical Depth | Supercritical flow (Fr > 1.0) | None |
| Known WSE | Specific boundary elevation available | Requires WSE value |
| EGL Slope Line | Gradually varied flow | Requires energy slope |
Note: The starting WSE method applies at the downstream boundary for steady flow computations.
# Visualize method parameters if applicable
method = wse_method.get('method', 'Unknown')
if 'Normal' in method and 'slope' in wse_method:
slope = wse_method['slope']
print(f"\nNormal Depth Analysis:")
print(f" Friction Slope: {slope:.6f}")
print(f" Slope as ratio: 1:{1/slope:.0f}" if slope > 0 else " Slope: Invalid")
# Check reasonableness
if abs(slope) < 0.0001:
print(" ⚠️ WARNING: Very flat slope - may cause convergence issues")
elif abs(slope) > 0.1:
print(" ⚠️ WARNING: Very steep slope - verify this is correct")
else:
print(" ✓ Slope appears reasonable")
elif 'Known' in method and 'wse' in wse_method:
wse_value = wse_method['wse']
print(f"\nKnown WSE Analysis:")
print(f" Specified WSE: {wse_value:.2f} ft")
# Check reasonableness
if wse_value < -100 or wse_value > 10000:
print(" ⚠️ WARNING: WSE may be unreasonable for this project")
else:
print(" ✓ WSE appears reasonable")
Part 4: Starting WSE Validation Checks¶
RasCheck now includes 4 starting WSE validation checks:
| Check ID | Description | Severity |
|---|---|---|
| PF_IC_00 | Starting WSE method could not be determined | WARNING |
| PF_IC_01 | Known WSE may be unreasonable | WARNING |
| PF_IC_02 | Normal depth slope may cause convergence issues | WARNING |
| PF_IC_03 | Critical depth used (informational) | INFO |
| PF_IC_04 | EGL slope method used (informational) | INFO |
# Run profile checks (includes starting WSE validation)
profile_results = RasCheck.check_profiles(plan_hdf, profiles)
print(f"Profile Check Results:")
print(f" Total Messages: {len(profile_results.messages)}")
print(f" Errors: {profile_results.get_error_count()}")
print(f" Warnings: {profile_results.get_warning_count()}")
print(f" Info: {len([m for m in profile_results.messages if m.severity == Severity.INFO])}")
Profile Check Results:
Total Messages: 127
Errors: 0
Warnings: 100
Info: 27
# Filter for starting WSE messages (PF_IC_ prefix)
wse_msgs = [msg for msg in profile_results.messages if msg.message_id.startswith('PF_IC_')]
if wse_msgs:
print(f"Found {len(wse_msgs)} starting WSE validation messages:\n")
for msg in wse_msgs:
print(f"[{msg.severity.value}] {msg.message_id}: {msg.message}")
if msg.help_text:
print(f" → {msg.help_text}")
print()
else:
print("✓ No starting WSE validation issues found")
✓ No starting WSE validation issues found
Starting WSE Check Details¶
PF_IC_01: Known WSE Range¶
What it checks: Known WSE values should be within realistic range (-100 to 10,000 ft)
Why it matters: Extreme values likely indicate data entry errors.
PF_IC_02: Normal Depth Slope¶
What it checks: - Very flat slopes (<0.0001) may cause convergence problems - Very steep slopes (>0.1) are unusual and should be verified
Why it matters: Inappropriate slopes lead to computational instability or incorrect boundary conditions.
PF_IC_03: Critical Depth Appropriateness¶
What it checks: Critical depth is appropriate when Froude number > 1.0 (supercritical flow)
Why it matters: Using critical depth for subcritical flow is incorrect.
PF_IC_04: EGL Method Verification¶
What it checks: Energy grade line method is appropriate for gradually varied flow
Why it matters: Verifies boundary condition method matches flow regime.
Part 5: Comprehensive Validation Report¶
Generate a complete validation report including all new checks:
# Run all checks
all_results = RasCheck.run_all(plan_number)
print("Complete Validation Results:")
print("="*50)
print(f" Total Messages: {len(all_results.messages)}")
print(f" Errors: {all_results.get_error_count()}")
print(f" Warnings: {all_results.get_warning_count()}")
print(f" Info: {len([m for m in all_results.messages if m.severity == Severity.INFO])}")
2026-10-15 03:22:37 - ras_commander.check.RasCheck - INFO - Detected flow type: steady
2026-10-15 03:22:37 - ras_commander.check.check_nt - WARNING - Could not check structure transition coefficients
2026-10-15 03:22:37 - ras_commander.check.check_nt - INFO - HTAB check complete: 0 issues found (0 errors, 0 warnings)
2026-10-15 03:22:37 - ras_commander.check.check_nt - INFO - Structure HTAB check complete: 0 info items found
Complete Validation Results:
==================================================
Total Messages: 168
Errors: 0
Warnings: 127
Info: 41
# Show new check coverage
new_check_ids = ['CV_LF_01', 'CV_LF_02', 'CV_CF_01', 'CV_CF_02', 'CV_TF_04',
'PF_IC_00', 'PF_IC_01', 'PF_IC_02', 'PF_IC_03', 'PF_IC_04']
new_checks_found = [msg for msg in all_results.messages if msg.message_id in new_check_ids]
print(f"\nNew Advanced Validation Checks (9 total):")
print(f" Messages from new checks: {len(new_checks_found)}")
if new_checks_found:
print("\n Check IDs triggered:")
for check_id in set(msg.message_id for msg in new_checks_found):
count = len([m for m in new_checks_found if m.message_id == check_id])
print(f" {check_id}: {count} message(s)")
New Advanced Validation Checks (9 total):
Messages from new checks: 0
# Generate HTML report
report_path = project_path / "ras_checker" / "advanced_validation_report.html"
report_path.parent.mkdir(parents=True, exist_ok=True)
metadata = ReportMetadata(
project_name=ras.project_name,
project_path=project_path,
plan_name="Steady Flow with Advanced Checks"
)
output_path = all_results.to_html(report_path, metadata=metadata)
print(f"\n✓ HTML report generated: {output_path}")
2026-10-15 03:22:37 - ras_commander.check.report - INFO - Generated HTML report: advanced_validation_report.html
✓ HTML report generated: D:\CLB-Temp\clb-t3-pr534\repo2\examples\example_projects\ConSpan Culvert_801\ras_checker\advanced_validation_report.html
Summary¶
This notebook demonstrated the 9 new validation checks added to RasCheck:
Culvert Checks (5)¶
- CV_LF_01: Entrance loss coefficient validation
- CV_LF_02: Exit loss coefficient validation
- CV_CF_01: Chart selection appropriateness
- CV_CF_02: Flow regime classification
- CV_TF_04: Multiple barrel flow distribution
Starting WSE Checks (4)¶
- PF_IC_00: Method determination
- PF_IC_01: Known WSE reasonableness
- PF_IC_02: Normal depth slope validation
- PF_IC_03: Critical depth applicability
- PF_IC_04: EGL method verification
New HDF Extraction Functions¶
HdfStruc.get_culvert_hydraulics()- Extract comprehensive culvert dataHdfPlan.get_starting_wse_method()- Extract initial condition method
Related Notebooks¶
- 800_quality_assurance_rascheck.ipynb - Comprehensive RasCheck overview
- Custom workflows and standards (proposed; no published notebook) - State-specific standards and custom workflows