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.
# =============================================================================
# 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")
LOCAL SOURCE MODE
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}")
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
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¶
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"]]
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¶
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 |

Download and Inspect MRMS QPE¶
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)
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 |
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()

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.
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}")
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¶
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.")
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

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.
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 |
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 |

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.
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 |

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.
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 |
MRMS NetCDF rain-on-grid QA complete; manual HEC-RAS diagnostics remain required.