Skip to content

MRMS NetCDF Rain-on-Grid Validation

This notebook validates the direct MRMS gridded-precipitation path end to end on a RasExamples project: NOAA MRMS GRIB2 download, cumulative HEC-RAS NetCDF export, native HDF authoring, temporary plan-HDF preprocessing checks, HEC-RAS compute, final plan-HDF source-to-solver comparison, and hydraulic-response review.

MRMS QPE timestamps are interval-ending. The NetCDF writer prepends a zero cumulative frame so HEC-RAS does not discard the first precipitation amount, then extends a flat cumulative tail through the plan end. The notebook proves the completed plan HDF reproduces the complete four-frame input event.

Engineering control: manual review of the complete HEC-RAS runtime messages, rainfall/results maps, boundary conditions, and model configuration remains required.

Python
# =============================================================================
# DEVELOPMENT MODE TOGGLE
# =============================================================================
# True uses the local checkout; False uses the installed ras-commander package.

USE_LOCAL_SOURCE = True

import sys
from pathlib import Path

REPO_ROOT = Path.cwd()
if REPO_ROOT.name.lower() == "examples":
    REPO_ROOT = REPO_ROOT.parent

if USE_LOCAL_SOURCE:
    local_path = str(REPO_ROOT)
    if local_path not in sys.path:
        sys.path.insert(0, local_path)
    print("LOCAL SOURCE MODE")
else:
    print("PIP PACKAGE MODE")
Text Only
LOCAL SOURCE MODE
Python
from __future__ import annotations

from datetime import datetime
import os
from pathlib import Path

import h5py
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import xarray as xr
import xarray as xr
import xarray as xr
import xarray as xr
import xarray as xr
import xarray as xr
import xarray as xr

from ras_commander import (
    RasCmdr,
    RasExamples,
    RasPlan,
    RasPreprocess,
    RasUnsteady,
    init_ras_project,
)
from ras_commander.hdf import HdfMesh, HdfProject, HdfResultsMesh, HdfResultsPlan
from ras_commander.precip import PrecipMrms

REPO_ROOT = Path.cwd()
if REPO_ROOT.name.lower() == "examples":
    REPO_ROOT = REPO_ROOT.parent

RUN_ROOT = Path(
    os.environ.get(
        "RAS_COMMANDER_EXAMPLE_RUN_ROOT",
        REPO_ROOT / "working" / "example_924_mrms_netcdf_rain_on_grid",
    )
)
RUN_ROOT.mkdir(parents=True, exist_ok=True)

PROJECT_NAME = "BaldEagleCrkMulti2D"
PROJECT_SUFFIX = "mrms_netcdf_924"
RAS_VERSION = os.environ.get("RAS_COMMANDER_EXAMPLE_RAS_VERSION", "7.0")
QPE_FIRST_VALID = datetime(2024, 8, 9, 10)
SIM_START = QPE_FIRST_VALID - pd.Timedelta(hours=1)
EVENT_LAST_QPE = datetime(2024, 8, 9, 13)
SIM_END = datetime(2024, 8, 9, 16)
MRMS_RESOLUTION_METERS = 8000.0

print(f"Run workspace: {RUN_ROOT.name}")
print(f"MRMS QPE valid times: {QPE_FIRST_VALID} through {EVENT_LAST_QPE}")
print(f"HEC-RAS simulation: {SIM_START} through {SIM_END}")
Text Only
Run workspace: example_924_mrms_netcdf_rain_on_grid
MRMS QPE valid times: 2024-08-09 10:00:00 through 2024-08-09 13:00:00
HEC-RAS simulation: 2024-08-09 09:00:00 through 2024-08-09 16:00:00
Python
def find_gridded_precipitation_plan(ras):
    """Return the first plan already configured for gridded precipitation."""
    for _, row in ras.plan_df.iterrows():
        unsteady_number = str(row["unsteady_number"]).zfill(2)
        config = RasUnsteady.get_met_precipitation_config(unsteady_number, ras_object=ras)
        if config.get("enabled") and config.get("mode") == "Gridded":
            return row, config
    raise RuntimeError("No enabled gridded precipitation plan found in RasExamples project")


def get_plan_geometry_hdf(ras, plan_row: pd.Series) -> Path:
    geometry_number = str(plan_row["geometry_number"]).zfill(2)
    geom_hdf = ras.project_folder / f"{ras.project_name}.g{geometry_number}.hdf"
    if not geom_hdf.exists():
        raise FileNotFoundError(f"Geometry HDF not found: {geom_hdf}")
    return geom_hdf


def mesh_precip_summary(plan_hdf: Path, variable: str) -> pd.DataFrame:
    mesh_data = HdfResultsMesh.get_mesh_cells_timeseries(plan_hdf, var=variable)
    records = []
    for mesh_name, dataset in mesh_data.items():
        values = dataset[variable].values
        final_values = values[-1]
        records.append(
            {
                "mesh": mesh_name,
                "timesteps": int(values.shape[0]),
                "cells": int(values.shape[1]),
                "min": float(np.nanmin(values)),
                "mean_final": float(np.nanmean(final_values)),
                "max": float(np.nanmax(values)),
                "positive_final_cells": int(np.count_nonzero(final_values > 0)),
            }
        )
    return pd.DataFrame.from_records(records)

Extract the Example Project

Python
project_path = RasExamples.extract_project(
    PROJECT_NAME,
    output_path=RUN_ROOT,
    suffix=PROJECT_SUFFIX,
)
ras = init_ras_project(
    project_path,
    ras_version=RAS_VERSION,
    load_results_summary=False,
)

plan_row, starting_precip_config = find_gridded_precipitation_plan(ras)
PLAN_NUMBER = str(plan_row["plan_number"]).zfill(2)
UNSTEADY_NUMBER = str(plan_row["unsteady_number"]).zfill(2)
GEOMETRY_NUMBER = str(plan_row["geometry_number"]).zfill(2)
GEOMETRY_HDF = get_plan_geometry_hdf(ras, plan_row)
BOUNDS = tuple(
    float(value)
    for value in HdfProject.get_project_bounds_latlon(GEOMETRY_HDF, buffer_percent=10.0)
)

print(f"Project folder: {ras.project_folder.name}")
print(f"Selected plan: p{PLAN_NUMBER}; unsteady file: u{UNSTEADY_NUMBER}; geometry: g{GEOMETRY_NUMBER}")
print(f"Starting precipitation source: {starting_precip_config.get('source')}")
print(f"Project bounds with 10% buffer: {BOUNDS}")
ras.plan_df[["plan_number", "geometry_number", "unsteady_number"]]
Text Only
2026-10-15 04:06:43 - ras_commander.RasExamples - INFO - Successfully extracted project 'BaldEagleCrkMulti2D' to BaldEagleCrkMulti2D_mrms_netcdf_924


2026-10-15 04:06:44 - 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 04:06:44 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk


2026-10-15 04:06:44 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0


2026-10-15 04:06:44 - 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).
═══════════════════════════════════════════════════════════════════════


Project folder: BaldEagleCrkMulti2D_mrms_netcdf_924
Selected plan: p06; unsteady file: u03; geometry: g09
Starting precipitation source: DSS
Project bounds with 10% buffer: (-77.78073591763562, 40.94941711291342, -77.30585839622871, 41.19611495254569)
plan_number geometry_number unsteady_number
0 13 06 07
1 15 08 12
2 17 10 09
3 18 11 10
4 19 12 11
5 03 09 13
6 04 13 01
7 02 01 01
8 01 01 01
9 05 03 02
10 06 09 03

Model Context

Python
mesh_areas = HdfMesh.get_mesh_areas(GEOMETRY_HDF)
mesh_summary = pd.DataFrame(
    {
        "project": [PROJECT_NAME],
        "plan": [f"p{PLAN_NUMBER}"],
        "geometry": [f"g{GEOMETRY_NUMBER}"],
        "unsteady": [f"u{UNSTEADY_NUMBER}"],
        "starting_precip_source": [starting_precip_config.get("source")],
        "mesh_areas": [", ".join(mesh_areas["mesh_name"].astype(str).tolist())],
        "simulation_start": [SIM_START],
        "simulation_end": [SIM_END],
    }
)
display(mesh_summary)

fig, ax = plt.subplots(figsize=(7, 5))
plot_mesh = mesh_areas.to_crs("EPSG:4326") if mesh_areas.crs else mesh_areas
plot_mesh.boundary.plot(ax=ax, color="#1f4e79", linewidth=1.5, label="2D mesh boundary")
west, south, east, north = BOUNDS
ax.plot(
    [west, east, east, west, west],
    [south, south, north, north, south],
    color="#b84a39",
    linewidth=1.4,
    linestyle="--",
    label="MRMS download bounds",
)
ax.set_title("Bald Eagle RasExamples model and MRMS query extent")
ax.set_xlabel("Longitude")
ax.set_ylabel("Latitude")
ax.grid(True, alpha=0.25)
ax.legend(loc="best")
plt.show()
project plan geometry unsteady starting_precip_source mesh_areas simulation_start simulation_end
0 BaldEagleCrkMulti2D p06 g09 u03 DSS BaldEagleCr 2024-08-09 09:00:00 2024-08-09 16:00:00

png

Download and Inspect MRMS QPE

Python
catalog = PrecipMrms.catalog(
    bounds=BOUNDS,
    start_date=QPE_FIRST_VALID,
    end_date=EVENT_LAST_QPE,
    source="noaa_s3",
)
expected_files = int((EVENT_LAST_QPE - QPE_FIRST_VALID).total_seconds() // 3600) + 1
assert len(catalog) >= expected_files, f"Expected {expected_files} MRMS frames, found {len(catalog)}"

mrms_files = PrecipMrms.download(
    bounds=BOUNDS,
    start_time=QPE_FIRST_VALID,
    end_time=EVENT_LAST_QPE,
    output_dir=ras.project_folder / "P" / "mrms" / "grib2",
    source="noaa_s3",
)
assert len(mrms_files) >= expected_files

mrms_stack = PrecipMrms.load_grib2_stack(mrms_files, bounds=BOUNDS)
hyetograph = PrecipMrms.to_hyetograph(mrms_stack)
assert float(hyetograph["cumulative_depth"].iloc[-1]) > 0.0

print(f"Downloaded {len(mrms_files)} MRMS GRIB2 files")
print(f"MRMS stack shape: {mrms_stack.shape}")
print(f"Spatial-average event depth: {hyetograph['cumulative_depth'].iloc[-1]:.3f} inches")
display(catalog[["valid_time", "archive_product", "filename", "compressed"]])
display(hyetograph)
Text Only
Downloaded 4 MRMS GRIB2 files
MRMS stack shape: (4, 25, 47)
Spatial-average event depth: 0.768 inches
valid_time archive_product filename compressed
0 2024-08-09 10:00:00 MultiSensor_QPE_01H_Pass2_00.00 MRMS_MultiSensor_QPE_01H_Pass2_00.00_20240809-... True
1 2024-08-09 11:00:00 MultiSensor_QPE_01H_Pass2_00.00 MRMS_MultiSensor_QPE_01H_Pass2_00.00_20240809-... True
2 2024-08-09 12:00:00 MultiSensor_QPE_01H_Pass2_00.00 MRMS_MultiSensor_QPE_01H_Pass2_00.00_20240809-... True
3 2024-08-09 13:00:00 MultiSensor_QPE_01H_Pass2_00.00 MRMS_MultiSensor_QPE_01H_Pass2_00.00_20240809-... True
time hour incremental_depth cumulative_depth
0 2024-08-09 10:00:00 1.0 0.110863 0.110863
1 2024-08-09 11:00:00 2.0 0.016639 0.127502
2 2024-08-09 12:00:00 3.0 0.272505 0.400007
3 2024-08-09 13:00:00 4.0 0.368062 0.768068
Python
event_total_in = mrms_stack.sum("time") / 25.4
assert str(mrms_stack.attrs.get("units", "")).lower() == "mm"
assert float(event_total_in.max()) > 0.0

fig, (hyeto_ax, map_ax) = plt.subplots(1, 2, figsize=(13, 4.8), constrained_layout=True)
hyeto_ax.bar(
    hyetograph["time"],
    hyetograph["incremental_depth"],
    width=0.03,
    color="#2f6f9f",
    label="Incremental depth",
)
hyeto_ax.set_ylabel("Spatial-mean incremental depth (in)")
hyeto_ax.set_xlabel("MRMS valid time")
hyeto_ax.grid(True, axis="y", alpha=0.25)
hyeto_ax2 = hyeto_ax.twinx()
hyeto_ax2.plot(
    hyetograph["time"],
    hyetograph["cumulative_depth"],
    color="#b84a39",
    marker="o",
    linewidth=2,
    label="Cumulative depth",
)
hyeto_ax2.set_ylabel("Spatial-mean cumulative depth (in)")
handles1, labels1 = hyeto_ax.get_legend_handles_labels()
handles2, labels2 = hyeto_ax2.get_legend_handles_labels()
hyeto_ax.legend(handles1 + handles2, labels1 + labels2, loc="upper left")
hyeto_ax.set_title("MRMS QPE hyetograph")
hyeto_ax.tick_params(axis="x", rotation=25)

lon_name = "longitude" if "longitude" in event_total_in.coords else "lon"
lat_name = "latitude" if "latitude" in event_total_in.coords else "lat"
source_image = map_ax.pcolormesh(
    event_total_in[lon_name],
    event_total_in[lat_name],
    event_total_in,
    shading="auto",
    cmap="Blues",
)
plot_mesh.boundary.plot(ax=map_ax, color="#b84a39", linewidth=1.6, label="2D mesh boundary")
map_ax.set_title("Complete four-frame MRMS event")
map_ax.set_xlabel("Longitude")
map_ax.set_ylabel("Latitude")
map_ax.legend(loc="lower left")
colorbar = fig.colorbar(source_image, ax=map_ax, shrink=0.86)
colorbar.set_label("Cumulative precipitation (in)")
plt.show()

png

Export cumulative NetCDF and configure HEC-RAS gridded precipitation

PrecipMrms.to_ras_netcdf() converts the four interval-ending QPE amounts to cumulative depth, prepends the required zero datum one interval before the first valid time, and repeats the final cumulative surface through the simulation end. This durable file is both the HEC-RAS input and the source of truth for the final-HDF comparison.

The gridded setter completes the HEC-RAS-required evapotranspiration, air-density, and air-pressure modes while preserving explicit nonblank choices. Runtime messages and the temporary/final HDF checks remain authoritative.

Python
mrms_netcdf = PrecipMrms.to_ras_netcdf(
    mrms_stack,
    ras.project_folder / "P" / "mrms" / "mrms_qpe.nc",
    resolution=MRMS_RESOLUTION_METERS,
    first_timestep_hours=1.0,
    end_time=SIM_END,
)
assert mrms_netcdf.exists() and mrms_netcdf.stat().st_size > 0

with xr.open_dataset(mrms_netcdf) as source_dataset:
    forcing = source_dataset.load()
source_cumulative_mm = forcing["APCP_surface"]
forcing_times = pd.to_datetime(source_cumulative_mm["time"].values)
assert source_cumulative_mm.attrs["value_type"] == "cumulative"
assert forcing_times[0] == pd.Timestamp(SIM_START)
assert forcing_times[-1] == pd.Timestamp(SIM_END)
initial_values = source_cumulative_mm.isel(time=0).values
assert np.allclose(initial_values[np.isfinite(initial_values)], 0.0)
assert int(forcing.attrs["zero_tail_frames"]) == 3
tail_difference = (
    source_cumulative_mm.isel(time=slice(-4, None)).values
    - source_cumulative_mm.isel(time=-1).values
)
assert float(np.nanmax(np.abs(tail_difference))) == 0.0

RasUnsteady.set_gridded_precipitation(
    UNSTEADY_NUMBER,
    mrms_netcdf,
    interpolation="Bilinear",
    ras_object=ras,
    dataset_name="APCP_surface",
    units="mm",
    value_type="cumulative",
    historic=True,
)
updated_precip_config = RasUnsteady.get_met_precipitation_config(
    UNSTEADY_NUMBER,
    ras_object=ras,
)
assert updated_precip_config["enabled"] is True
assert updated_precip_config["source"] == "GDAL Raster File(s)"
assert updated_precip_config["gdal_group"] == "APCP_surface"

print(f"NetCDF: {mrms_netcdf.name}")
print("Updated precipitation configuration:")
for key in ["enabled", "mode", "source", "gdal_filename", "gdal_group"]:
    print(f"  {key}: {updated_precip_config.get(key)}")
sidecar = Path(str(ras.project_folder / f"{ras.project_name}.u{UNSTEADY_NUMBER}") + ".hdf")
print(f"Unsteady HDF sidecar: {sidecar.name}")
Text Only
2026-10-15 04:06:55 - ras_commander.RasUnsteady - INFO - Imported gridded precipitation into BaldEagleDamBrk.u03.hdf: 8 timesteps, 30 cells, range=0.0-25.1 mm


2026-10-15 04:06:55 - ras_commander.RasUnsteady - INFO - Completed required gridded meteorology modes in BaldEagleDamBrk.u03: Air Pressure


2026-10-15 04:06:55 - ras_commander.RasUnsteady - INFO - Configured gridded precipitation in BaldEagleDamBrk.u03: source=.\P\mrms\mrms_qpe.nc, interpolation=Bilinear, dataset=APCP_surface


NetCDF: mrms_qpe.nc
Updated precipitation configuration:
  enabled: True
  mode: Gridded
  source: GDAL Raster File(s)
  gdal_filename: .\P\mrms\mrms_qpe.nc
  gdal_group: APCP_surface
Unsteady HDF sidecar: BaldEagleDamBrk.u03.hdf

Preprocess and Compute the Plan

Python
RasPlan.update_simulation_date(
    PLAN_NUMBER,
    SIM_START,
    SIM_END,
    ras_object=ras,
)
RasPlan.update_plan_intervals(
    PLAN_NUMBER,
    output_interval="1HOUR",
    instantaneous_interval="1HOUR",
    mapping_interval="1HOUR",
    ras_object=ras,
)

preprocess_result = RasPreprocess.preprocess_plan(
    PLAN_NUMBER,
    ras_object=ras,
    max_wait=600,
)
assert bool(preprocess_result), preprocess_result.error
PRECOMPUTE_HDF = Path(preprocess_result.tmp_hdf_path)
values_path = "Event Conditions/Meteorology/Precipitation/Values"
timestamp_path = "Event Conditions/Meteorology/Precipitation/Timestamp"
with h5py.File(PRECOMPUTE_HDF, "r") as hdf:
    solver_values = hdf[values_path][:]
    solver_timestamps = hdf[timestamp_path][:]

assert solver_values.ndim == 2 and solver_values.shape == (8, 30)
assert solver_timestamps.ndim == 1
assert solver_values.shape[0] == solver_timestamps.shape[0]
assert float(np.nanmax(solver_values)) > 0.0
assert float(np.nanmin(solver_values)) >= 0.0
assert np.allclose(solver_values[0], 0.0)
precompute_tail = solver_values[-3:]
assert np.allclose(precompute_tail[np.isfinite(precompute_tail)], 0.0)

fig, ax = plt.subplots(figsize=(9, 4))
ax.plot(
    np.arange(solver_values.shape[0]),
    np.nanmean(solver_values, axis=1),
    marker="o",
)
ax.set_title("Preprocessed solver-facing MRMS precipitation")
ax.set_xlabel("Precipitation frame")
ax.set_ylabel("Mean interval precipitation (project depth units)")
ax.grid(True, alpha=0.25)
plt.show()

print(f"Preprocess result: {preprocess_result}")
print(f"Solver-facing rainfall: {solver_values.shape} in {PRECOMPUTE_HDF.name}")

compute_result = RasCmdr.compute_plan(
    PLAN_NUMBER,
    ras_object=ras,
    force_rerun=True,
    verify=True,
    use_optimal_hdf_settings=True,
    hdf_output_variables=[
        "Cell Hydraulic Depth",
        "Cell Precipitation Rate",
        "Cell Cumulative Precipitation Depth",
    ],
)
assert bool(compute_result), "HEC-RAS compute failed"

PLAN_HDF = ras.project_folder / f"{ras.project_name}.p{PLAN_NUMBER}.hdf"
assert PLAN_HDF.exists() and PLAN_HDF.stat().st_size > 0
compute_messages = HdfResultsPlan.get_compute_messages_hdf_only(PLAN_HDF)
precipitation_messages = [
    line
    for line in compute_messages.splitlines()
    if any(term in line.casefold() for term in ("precip", "rain", "raster"))
]
precipitation_errors = [
    line
    for line in precipitation_messages
    if any(term in line.casefold() for term in ("error", "failed", "missing"))
]
assert "Processing Precipitation data" in compute_messages
assert not precipitation_errors, precipitation_errors
print(f"Compute result: {compute_result}")
print(f"Plan HDF: {PLAN_HDF.name}")
print("Precipitation-related HEC-RAS runtime messages:")
print("\n".join(precipitation_messages) or "  None reported")
print("Manual review of the full runtime messages and rainfall/results maps is still required.")
Text Only
2026-10-15 04:06:55 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: BaldEagleDamBrk.p06


2026-10-15 04:06:55 - ras_commander.RasPlan - INFO - Updated intervals in plan file: BaldEagleDamBrk.p06


2026-10-15 04:06:55 - ras_commander.RasPreprocess - INFO - Starting HEC-RAS preprocessing for plan 06


2026-10-15 04:06:55 - ras_commander.RasBco - INFO - Monitoring BaldEagleDamBrk.bco06 for 'Starting Unsteady Flow Computations' signal...


2026-10-15 04:06:58 - ras_commander.RasPreprocess - INFO - Waiting for exact CompletePreProcess writer(s) before stopping gridded preprocessing: 4504


2026-10-15 04:07:09 - ras_commander.RasPreprocess - INFO - No CompletePreProcess writer is active and the owned unsteady solver started; stopping before it advances


2026-10-15 04:07:09 - ras_commander.RasBco - INFO - Detected an observed CompletePreProcess writer that has exited with quiescent preprocessing artifacts


2026-10-15 04:07:09 - ras_commander.RasPreprocess - INFO - Preprocessing complete for plan 06 in 13.5s: tmp.hdf=12.1MB, b=3KB, x=5KB

png

Text Only
2026-10-15 04:07:09 - ras_commander.RasPlan - INFO - Updated HDF write parameters in plan file: BaldEagleDamBrk.p06


2026-10-15 04:07:09 - ras_commander.RasPlan - INFO - Added HDF output variable 'Cell Hydraulic Depth' to plan file: BaldEagleDamBrk.p06


2026-10-15 04:07:09 - ras_commander.RasPlan - INFO - Added HDF output variable 'Cell Precipitation Rate' to plan file: BaldEagleDamBrk.p06


2026-10-15 04:07:09 - ras_commander.RasPlan - INFO - Added HDF output variable 'Cell Cumulative Precipitation Depth' to plan file: BaldEagleDamBrk.p06


2026-10-15 04:07:09 - ras_commander.RasCmdr - INFO - Applied 'balanced' HDF settings profile to plan: BaldEagleDamBrk.p06


Preprocess result: PreprocessResult(SUCCESS, plan=06, geom=09, time=13.5s)
Solver-facing rainfall: (8, 30) in BaldEagleDamBrk.p06.tmp.hdf


2026-10-15 04:07:09 - ras_commander.ExecutionArtifacts - INFO - Removed plan 06 execution artifact: BaldEagleDamBrk.bco06


Compute result: ComputeResult(SUCCESS, completion_verified=True, results_df_row=available)
Plan HDF: BaldEagleDamBrk.p06.hdf
Precipitation-related HEC-RAS runtime messages:
Plan: 'Gridded Precip - Infiltration' (BaldEagleDamBrk.p06)
  Terrain: Terrain50
  Processing Precipitation data...
  Finished Processing Precipitation data (0.217s)
Manual review of the full runtime messages and rainfall/results maps is still required.

Validate completed model-output precipitation against the input

Positive rainfall alone is not adequate QA. The completed plan HDF must be cumulative and monotonic, end with zero precipitation rate, cover the real mesh cells, and reproduce the final cumulative NetCDF surface at the HEC-RAS mesh-cell points within interpolation tolerance.

Python
cumulative_summary = mesh_precip_summary(
    PLAN_HDF,
    "Cell Cumulative Precipitation Depth",
)
rate_summary = mesh_precip_summary(
    PLAN_HDF,
    "Cell Precipitation Rate",
)
assert int(cumulative_summary["positive_final_cells"].sum()) > 0
assert float(cumulative_summary["max"].max()) > 0.0
assert float(rate_summary["max"].max()) > 0.0

display(cumulative_summary)
display(rate_summary)
mesh timesteps cells min mean_final max positive_final_cells
0 BaldEagleCr 8 18066 0.0 0.725438 0.970716 18066
mesh timesteps cells min mean_final max positive_final_cells
0 BaldEagleCr 8 18066 0.0 0.0 0.37409 0
Python
mesh_data = HdfResultsMesh.get_mesh_cells_timeseries(
    PLAN_HDF,
    var="Cell Cumulative Precipitation Depth",
)
rate_data = HdfResultsMesh.get_mesh_cells_timeseries(
    PLAN_HDF,
    var="Cell Precipitation Rate",
)
mesh_name, dataset = next(iter(mesh_data.items()))
cell_values = dataset["Cell Cumulative Precipitation Depth"]
rate_values = rate_data[mesh_name]["Cell Precipitation Rate"]
time_index = pd.to_datetime(dataset["time"].values)

rain_steps = np.asarray(cell_values.values, dtype=float)
final_rain = np.asarray(cell_values.isel(time=-1).values, dtype=float)
final_rate = np.asarray(rate_values.isel(time=-1).values, dtype=float)
assert float(np.nanmin(np.diff(rain_steps, axis=0))) >= -1e-7
assert np.allclose(final_rate, 0.0, atol=1e-7)

# Physical cells only, matching the ghost-free cell results above.
mesh_cell_points = HdfMesh.get_mesh_cell_points(
    GEOMETRY_HDF, include_ghost_cells=False
).to_crs("EPSG:5070")
mesh_cell_polygons = HdfMesh.get_mesh_cell_polygons(GEOMETRY_HDF)
source_final_mm = source_cumulative_mm.isel(time=-1)
expected_cell_in = (
    source_final_mm.interp(
        x=xr.DataArray(mesh_cell_points.geometry.x.to_numpy(), dims="cell_id"),
        y=xr.DataArray(mesh_cell_points.geometry.y.to_numpy(), dims="cell_id"),
        method="linear",
    ).values
    / 25.4
)
actual_cell_in = np.asarray(
    cell_values.isel(time=-1).sel(
        cell_id=mesh_cell_points["cell_id"].to_numpy(dtype=int)
    ).values,
    dtype=float,
)
comparison_mask = (actual_cell_in > 0.0) & np.isfinite(expected_cell_in)
comparison_error_in = actual_cell_in[comparison_mask] - expected_cell_in[comparison_mask]
assert int(comparison_mask.sum()) >= int(0.85 * len(mesh_cell_polygons))
assert float(np.max(np.abs(comparison_error_in))) <= 1e-5
assert int(np.count_nonzero(actual_cell_in > 0.0)) == len(mesh_cell_polygons)

display(pd.DataFrame([{
    "source-sampled cells compared": int(comparison_mask.sum()),
    "raining HDF cells": int(np.count_nonzero(actual_cell_in > 0.0)),
    "maximum source-vs-HDF error (in)": float(np.max(np.abs(comparison_error_in))),
    "final HDF mean cumulative depth (in)": float(actual_cell_in[actual_cell_in > 0.0].mean()),
    "final HDF maximum cumulative depth (in)": float(actual_cell_in.max()),
    "final HDF maximum ending rate (in/hr)": float(final_rate.max()),
}]).round(6))

mean_cumulative = cell_values.mean(dim="cell_id").values
max_cumulative = cell_values.max(dim="cell_id").values
fig, (series_ax, map_ax) = plt.subplots(1, 2, figsize=(13, 4.8), constrained_layout=True)
series_ax.plot(time_index, mean_cumulative, marker="o", label="HDF mesh mean")
series_ax.plot(time_index, max_cumulative, marker="o", label="HDF mesh max")
series_ax.axvline(EVENT_LAST_QPE, color="#b84a39", linestyle="--", label="Last QPE frame")
series_ax.set_title("Completed plan-HDF cumulative precipitation")
series_ax.set_xlabel("Simulation time")
series_ax.set_ylabel("Cumulative precipitation depth (in)")
series_ax.grid(True, alpha=0.25)
series_ax.legend()
series_ax.tick_params(axis="x", rotation=25)

plot_points = mesh_cell_points.loc[comparison_mask].copy()
plot_points["hdf_cumulative_in"] = actual_cell_in[comparison_mask]
plot_points.plot(
    ax=map_ax,
    column="hdf_cumulative_in",
    markersize=2.0,
    cmap="Blues",
    legend=True,
    legend_kwds={"label": "Final HDF cumulative depth (in)", "shrink": 0.82},
)
mesh_areas.to_crs("EPSG:5070").boundary.plot(ax=map_ax, color="#b84a39", linewidth=1.2)
map_ax.set_title("Solver-applied MRMS precipitation")
map_ax.set_xlabel("EPSG:5070 easting (m)")
map_ax.set_ylabel("EPSG:5070 northing (m)")
plt.show()

print(
    f"Final raining-cell mean: {actual_cell_in[actual_cell_in > 0.0].mean():.3f} in; "
    f"final maximum: {actual_cell_in.max():.3f} in"
)
source-sampled cells compared raining HDF cells maximum source-vs-HDF error (in) final HDF mean cumulative depth (in) final HDF maximum cumulative depth (in) final HDF maximum ending rate (in/hr)
0 15453 18066 0.000001 0.725438 0.970716 0.0

png

Text Only
Final raining-cell mean: 0.725 in; final maximum: 0.971 in

Validate hydraulic response and close the QA loop

The rainfall check above proves input-to-solver fidelity. Hydraulic depth is then checked for a positive, finite response. This does not replace engineering review of the reasonableness of inundation, structures, boundary conditions, mass balance, and runtime messages.

Python
depth_summary = mesh_precip_summary(
    PLAN_HDF,
    "Cell Hydraulic Depth",
).rename(
    columns={
        "mean_final": "mean_final_depth",
        "max": "max_depth",
        "positive_final_cells": "wet_final_cells",
    }
)
assert float(depth_summary["max_depth"].max()) > 0.0
assert int(depth_summary["wet_final_cells"].sum()) > 0

display(depth_summary)

depth_data = HdfResultsMesh.get_mesh_cells_timeseries(
    PLAN_HDF,
    var="Cell Hydraulic Depth",
)
mesh_name, depth_dataset = next(iter(depth_data.items()))
depth_values = depth_dataset["Cell Hydraulic Depth"]
depth_time = pd.to_datetime(depth_dataset["time"].values)
mean_depth = depth_values.mean(dim="cell_id").values
max_depth = depth_values.max(dim="cell_id").values

fig, ax = plt.subplots(figsize=(9, 4))
ax.plot(depth_time, mean_depth, marker="o", label="Mesh mean depth")
ax.plot(depth_time, max_depth, marker="o", label="Mesh max depth")
ax.set_title(f"HEC-RAS hydraulic depth response in {mesh_name}")
ax.set_xlabel("Simulation time")
ax.set_ylabel("Hydraulic depth (ft)")
ax.grid(True, alpha=0.25)
ax.legend()
fig.autofmt_xdate()
plt.show()

print(
    f"Final mesh mean depth: {mean_depth[-1]:.3f} ft; "
    f"peak mesh max depth: {max_depth.max():.3f} ft"
)
mesh timesteps cells min mean_final_depth max_depth wet_final_cells
0 BaldEagleCr 8 18066 0.0 0.255718 8.538345 14935

png

Text Only
Final mesh mean depth: 0.256 ft; peak mesh max depth: 8.538 ft

QA/QC disposition

The completion checklist below records the minimum production-example evidence. A green checklist means this notebook reproduced the input forcing and completed the selected model; it is not an approval of the source QPE or the model for another engineering purpose.

Python
completion_checks = pd.Series(
    {
        "four NOAA MRMS frames downloaded": len(mrms_files) == expected_files,
        "source event depth is positive": float(hyetograph["cumulative_depth"].iloc[-1]) > 0.0,
        "cumulative forcing begins at zero": bool(np.allclose(initial_values[np.isfinite(initial_values)], 0.0)),
        "forcing extends flat through plan end": forcing_times[-1] == pd.Timestamp(SIM_END),
        "temporary plan HDF preserves the zero tail": bool(np.allclose(precompute_tail[np.isfinite(precompute_tail)], 0.0)),
        "HEC-RAS compute completed": bool(compute_result),
        "final HDF reproduces source": float(np.max(np.abs(comparison_error_in))) <= 1e-5,
        "final precipitation rate is zero": bool(np.allclose(final_rate, 0.0, atol=1e-7)),
        "hydraulic response is positive": float(depth_summary["max_depth"].max()) > 0.0,
    },
    name="passed",
).to_frame()
display(completion_checks)
assert completion_checks["passed"].all()
print("MRMS NetCDF rain-on-grid QA complete; manual HEC-RAS diagnostics remain required.")
passed
four NOAA MRMS frames downloaded True
source event depth is positive True
cumulative forcing begins at zero True
forcing extends flat through plan end True
temporary plan HDF preserves the zero tail True
HEC-RAS compute completed True
final HDF reproduces source True
final precipitation rate is zero True
hydraulic response is positive True
Text Only
MRMS NetCDF rain-on-grid QA complete; manual HEC-RAS diagnostics remain required.