Skip to content

Quality Assurance with RasCheck

Unofficial Implementation

RasCheck is an unofficial Python implementation based on the FEMA cHECk-RAS tool. It is part of the ras-commander library and is not affiliated with or endorsed by FEMA. Results should be independently verified for official submissions.

Attribution

Based on FEMA cHECk-RAS

This module implements the validation checks described in FEMA's cHECk-RAS quality assurance tool for HEC-RAS 6.x/7.x models, using ras-commander's HDF function library.

From FEMA's cHECk-RAS page:

"cHECk-RAS utilizes information generated by HEC-RAS (all versions through the latest version, 5.0.7). Note, cHECk-RAS is not compatible with the two-dimensional component of HEC-RAS 5.0.7."

This Python implementation extends these validation checks to work with modern HEC-RAS 6.x/7.x HDF-based outputs, providing equivalent functionality through the ras-commander library.

For Informational Purposes Only

Outputs from this library are for informational purposes only and should be validated by a qualified engineer. This tool does not replace professional engineering judgment or official FEMA review processes.

Overview

RasCheck provides automated quality assurance validation for HEC-RAS 6.x/7.x models. It performs comprehensive checks based on FEMA guidelines, HEC-RAS best practices, and the original cHECk-RAS methodology.

Flow Type Support: RasCheck automatically detects whether a plan is steady flow or unsteady flow and runs appropriate validation checks for each type.

Key Features

  • Auto-detection of steady vs unsteady flow from plan HDF structure
  • Steady flow validation: Manning's n values, transition coefficients, cross sections, structures, floodway analysis, profile comparison
  • Unsteady flow validation: Mass balance, computation warnings, peak values (WSE/velocity), stability/convergence (2D), mesh quality (2D)
  • HTML report generation with detailed messages and recommendations
  • Customizable thresholds for project-specific requirements

Quick Start

Steady Flow Example

Python
from ras_commander import init_ras_project
from ras_commander.check import RasCheck

# Initialize project
init_ras_project(r"C:\Projects\MySteadyModel", "7.0")

# Run all checks on a steady flow plan
results = RasCheck.run_all(
    plan="01",
    profiles=['10yr', '50yr', '100yr', 'Floodway'],
    floodway_profile='Floodway',
    surcharge=1.0
)

# View summary
print(f"Flow type: {results.flow_type}")  # FlowType.STEADY
print(f"Errors: {results.get_error_count()}")
print(f"Warnings: {results.get_warning_count()}")

# Generate HTML report
results.to_html("validation_report.html")

Unsteady Flow Example

Python
from ras_commander import init_ras_project
from ras_commander.check import RasCheck

# Initialize project
init_ras_project(r"C:\Projects\MyUnsteadyModel", "7.0")

# Run all checks - auto-detects unsteady flow
results = RasCheck.run_all(plan="01")

# View summary
print(f"Flow type: {results.flow_type}")  # FlowType.UNSTEADY
print(f"Errors: {results.get_error_count()}")

# Check mass balance
if results.mass_balance_summary is not None:
    print("\nMass Balance:")
    print(results.mass_balance_summary)

# Check peaks
if results.peaks_summary is not None:
    print("\nTop 5 peak velocities:")
    top_vels = results.peaks_summary.nlargest(5, 'max_velocity')
    print(top_vels[['cross_section', 'max_velocity', 'max_wse']])

# Generate HTML report
results.to_html("unsteady_validation_report.html")

Check Categories

Steady Flow Checks

RasCheck performs five main categories of validation for steady flow:

Check Type Description Key Validations
NT Check Manning's n and Transitions Roughness ranges, transition coefficients, n-value variation
XS Check Cross Section Validation Spacing, ineffective flow, levees, conveyance, energy
Structure Check Bridge/Culvert/Weir Section distances, flow types, loss coefficients
Floodway Check Floodway Analysis Surcharge limits, encroachment methods, discharge matching
Profiles Check Profile Consistency WSE ordering, discharge continuity, regime transitions

Unsteady Flow Checks

RasCheck performs five main categories of validation for unsteady flow:

Check Type Description Key Validations
NT Check Manning's n and Transitions Same geometry-only checks as steady flow
Mass Balance Volume Conservation Volume error %, inflow/outflow balance
Computation HEC-RAS Messages Warnings, errors, convergence issues
Peaks Maximum Value Validation Peak WSE, peak velocity thresholds (1D)
Stability Convergence Analysis Iteration counts, WS errors (2D only)
Mesh Quality 2D Mesh Validation Cell areas, aspect ratios, face velocities (2D only)

Running Individual Checks

You can run specific checks independently:

Python
from pathlib import Path
from ras_commander.check import RasCheck

# Get HDF paths
plan_hdf = Path("MyProject.p01.hdf")
geom_hdf = Path("MyProject.g01.hdf")

# Run NT check only (Manning's n and transitions)
nt_results = RasCheck.check_nt(geom_hdf)

# Run XS check (cross sections)
xs_results = RasCheck.check_xs(plan_hdf, geom_hdf, profiles=['100yr'])

# Run structure check
struct_results = RasCheck.check_structures(plan_hdf, geom_hdf, profiles=['100yr'])

# Run floodway check
fw_results = RasCheck.check_floodways(
    plan_hdf, geom_hdf,
    base_profile='100yr',
    floodway_profile='Floodway',
    surcharge=1.0
)

# Run profiles check
profiles_results = RasCheck.check_profiles(plan_hdf, profiles=['10yr', '50yr', '100yr'])

Customizing Thresholds

RasCheck uses configurable thresholds that can be customized for project requirements:

Python
from ras_commander.check import get_default_thresholds, create_custom_thresholds

# Get default thresholds
thresholds = get_default_thresholds()

# View default Manning's n ranges
print(f"Overbank n range: {thresholds.mannings_n.overbank_min} - {thresholds.mannings_n.overbank_max}")
print(f"Channel n range: {thresholds.mannings_n.channel_min} - {thresholds.mannings_n.channel_max}")

# Create custom thresholds
custom = create_custom_thresholds({
    'mannings_n.overbank_max': 0.150,  # Stricter overbank maximum
    'floodway.surcharge_max_ft': 0.5,  # More restrictive surcharge (e.g., Minnesota)
})

# Run checks with custom thresholds
results = RasCheck.run_all("01", thresholds=custom, ras_object=ras)

State-Specific Surcharge Limits

RasCheck includes built-in state-specific floodway surcharge limits:

Python
from ras_commander.check import get_state_surcharge_limit

# Get state-specific limits
print(get_state_surcharge_limit('TX'))  # 1.0 ft (FEMA default)
print(get_state_surcharge_limit('MN'))  # 0.5 ft (Minnesota)
print(get_state_surcharge_limit('NJ'))  # 0.2 ft (New Jersey)
print(get_state_surcharge_limit('IL'))  # 0.1 ft (Illinois)
print(get_state_surcharge_limit('WI'))  # 0.01 ft (Wisconsin - near zero rise)

Working with Results

Filtering Messages

Python
from ras_commander.check import Severity

# Filter by severity
errors = results.filter_by_severity(Severity.ERROR)
warnings = results.filter_by_severity(Severity.WARNING)

# Filter by check type
nt_messages = results.filter_by_check_type("NT")
xs_messages = results.filter_by_check_type("XS")

# Filter by station
station_msgs = results.filter_by_station("1500")

Converting to DataFrame

Python
# Get all messages as DataFrame
df = results.to_dataframe()

# Group by check type
summary = df.groupby('check_type').size()
print(summary)

# Filter for specific message IDs
overbank_issues = df[df['message_id'].str.startswith('NT_RC')]

Generating Reports

Python
from ras_commander.check import RasCheckReport, ReportMetadata

# Create metadata for report
metadata = ReportMetadata(
    project_name="Sample River Study",
    plan_name="Existing Conditions",
    profiles_checked=['10yr', '50yr', '100yr', 'Floodway'],
    base_flood_profile='100yr',
    floodway_profile='Floodway',
    surcharge_limit=1.0
)

# Generate HTML report
report = RasCheckReport(results, metadata)
report.generate_html("detailed_report.html")

# Export to CSV for further analysis
report.export_csv("messages.csv")

# Get summary statistics
summary = report.get_summary()
print(f"Passed: {summary['passed']}")
print(f"By check type: {summary['by_check_type']}")

Message ID Format

RasCheck uses standardized message IDs following the original cHECk-RAS format:

Text Only
{CHECK_TYPE}_{CATEGORY}_{NUMBER}{SUFFIX}

Components:

Component Values Description
CHECK_TYPE NT, XS, BR, CU, IW, ST, FW, MP Check category
CATEGORY RC, TL, DT, IF, LV, SD, TF, etc. Specific check subcategory
NUMBER 01-99 Message number within category
SUFFIX L, R, C, S1-S4, etc. Position indicator (optional)

Examples:

  • NT_RC_01L - Manning's n roughness check, left overbank
  • XS_IF_02R - Cross section ineffective flow check, right side
  • BR_TF_04 - Bridge type flow check, pressure flow
  • FW_SC_01 - Floodway surcharge check

Detailed Check Documentation

For comprehensive documentation of all validation checks and message IDs:

Comparison with FEMA cHECk-RAS

Feature FEMA cHECk-RAS ras-commander RasCheck
Platform Windows (.NET) Cross-platform (Python)
HEC-RAS Version 4.x (COM) 6.x-7.x (HDF)
Flow Types Steady only Steady only
Data Access Text files + COM HDF5 directly
Report Format HTML/PDF HTML/CSV/DataFrame
Customization Configuration file Python API
Integration Standalone ras-commander library

Limitations

Both Steady and Unsteady Flow Supported

RasCheck now supports both steady flow and unsteady flow models. Flow type is automatically detected and appropriate validation checks are run.

Steady Flow Checks: Manning's n, cross sections, structures, floodway, profiles

Unsteady Flow Checks: Manning's n, mass balance, computation warnings, peak values, stability/convergence, 2D mesh quality

Not Applicable to Unsteady: Floodway analysis (steady-state concept)

  • Only validates HEC-RAS 6.x/7.x models with HDF output
  • Requires computed plan results (not geometry-only)
  • Some original cHECk-RAS features not yet implemented:
    • Interactive flagging/commenting through GUI
    • PDF report generation (use HTML or CSV export)
    • Access database storage

References

  • cHECk-RAS User Guide - Original FEMA cHECk-RAS documentation
  • HEC-RAS User's Manual - U.S. Army Corps of Engineers
  • HEC-RAS Hydraulic Reference Manual - Technical methodology
  • FEMA Guidelines and Standards for Flood Risk Analysis - Regulatory requirements
  • 44 CFR 60.3 - National Flood Insurance Program Regulations (floodway requirements)

See Also

CLB Engineering Corporation  ·  LLM Forward Engineering
RAS Commander is a free and open-source project maintained by CLB Engineering Corporation. For agencies and firms seeking to modernize H&H workflows with LLM Forward approaches, contact CLB to partner with the engineers who wrote the automation.