NOAA AORC rain-on-grid: catalog, author, compute, and verify¶
This notebook runs a bounded, production-style AORC workflow on the
BaldEagleCrkMulti2D RasExamples model. It catalogs a full year of storms,
selects the largest event for qualification, downloads only that simulation
window, authors a new HEC-RAS plan, preprocesses and computes it, and compares
the completed plan-HDF precipitation to the source grid at model-cell centers.
The one-event compute is intentional: a full annual catalog remains visible, while the checked-in example avoids launching many multi-hour simulations or creating tens of gigabytes of model output.
Timing contract and QA standard¶
NOAA AORC APCP_surface is a one-hour accumulated amount in kg/m² (equivalent
to mm) ending at the UTC timestamp. A simulation beginning at 12:00 therefore
uses its first forcing frame at 13:00, covering 12:00–13:00. The authoring path
prepends a zero cumulative baseline at 12:00.
The temporary plan HDF produced by preprocessing is the pre-compute source of truth. The completed plan HDF and runtime messages are the post-compute sources of truth. Passing the automated checks does not replace manual review of HEC-RAS messages, rainfall maps, hydraulic maps, and mass balance.
from __future__ import annotations
import os
from pathlib import Path
import re
import h5py
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
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 PrecipAorc
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_900_aorc_precipitation",
)
)
RUN_ROOT.mkdir(parents=True, exist_ok=True)
PROJECT_NAME = "BaldEagleCrkMulti2D"
PROJECT_SUFFIX = "aorc_900"
RAS_VERSION = os.environ.get("RAS_COMMANDER_EXAMPLE_RAS_VERSION", "7.0")
TEMPLATE_PLAN = "06"
CATALOG_YEAR = 2020
BUFFER_HOURS = 48
AORC_RESOLUTION_METERS = 2000.0
plt.rcParams.update({"figure.dpi": 120})
print(f"Run workspace: {RUN_ROOT.name}")
print(f"HEC-RAS version: {RAS_VERSION}; AORC catalog year: {CATALOG_YEAR}")
Run workspace: example_900_aorc_precipitation
HEC-RAS version: 7.0; AORC catalog year: 2020
def mesh_variable_summary(plan_hdf: Path, variable: str) -> pd.DataFrame:
# Summarize a cell time-series variable for every 2D area.
mesh_data = HdfResultsMesh.get_mesh_cells_timeseries(plan_hdf, var=variable)
records = []
for mesh_name, dataset in mesh_data.items():
values = np.asarray(dataset[variable].values, dtype=float)
final_values = values[-1]
records.append(
{
"mesh": mesh_name,
"timesteps": int(values.shape[0]),
"cells": int(values.shape[1]),
"minimum": float(np.nanmin(values)),
"final_mean": float(np.nanmean(final_values)),
"maximum": float(np.nanmax(values)),
"positive_final_cells": int(np.count_nonzero(final_values > 0)),
}
)
return pd.DataFrame.from_records(records)
def project_file(ras, extension: str) -> Path:
return ras.project_folder / f"{ras.project_name}.{extension}"
Extract the RasExamples model and define the AORC query extent¶
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_numbers = ras.plan_df["plan_number"].astype(str).str.zfill(2)
template_rows = ras.plan_df.loc[plan_numbers.eq(TEMPLATE_PLAN)]
assert len(template_rows) == 1, f"Expected one template plan p{TEMPLATE_PLAN}"
template_row = template_rows.iloc[0]
TEMPLATE_UNSTEADY = str(template_row["unsteady_number"]).zfill(2)
GEOMETRY_NUMBER = str(template_row["geometry_number"]).zfill(2)
GEOMETRY_HDF = project_file(ras, f"g{GEOMETRY_NUMBER}.hdf")
assert GEOMETRY_HDF.exists()
BOUNDS = tuple(
float(value)
for value in HdfProject.get_project_bounds_latlon(
GEOMETRY_HDF,
buffer_percent=10.0,
include_1d=True,
include_2d=True,
include_storage=True,
)
)
mesh_areas = HdfMesh.get_mesh_areas(GEOMETRY_HDF)
plot_mesh_wgs84 = mesh_areas.to_crs("EPSG:4326") if mesh_areas.crs else mesh_areas
display(pd.DataFrame([{
"project": ras.project_name,
"template_plan": f"p{TEMPLATE_PLAN}",
"template_unsteady": f"u{TEMPLATE_UNSTEADY}",
"geometry": f"g{GEOMETRY_NUMBER}",
"mesh_areas": ", ".join(mesh_areas["mesh_name"].astype(str)),
"AORC_bounds_W_S_E_N": BOUNDS,
}]))
fig, ax = plt.subplots(figsize=(7.5, 5.2))
plot_mesh_wgs84.boundary.plot(ax=ax, color="#174A6E", linewidth=1.6, label="2D mesh")
west, south, east, north = BOUNDS
ax.plot(
[west, east, east, west, west],
[south, south, north, north, south],
"--",
color="#B64C3B",
linewidth=1.4,
label="AORC query extent",
)
ax.set_title("Bald Eagle model and buffered AORC query extent")
ax.set_xlabel("Longitude")
ax.set_ylabel("Latitude")
ax.grid(True, alpha=0.25)
ax.legend()
plt.show()
2026-10-15 03:58:12 - ras_commander.RasExamples - INFO - Successfully extracted project 'BaldEagleCrkMulti2D' to BaldEagleCrkMulti2D_aorc_900
2026-10-15 03:58:12 - 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:58:12 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk
2026-10-15 03:58:12 - ras_commander.RasPrj - INFO - Using HEC-RAS version 7.0
2026-10-15 03:58:12 - 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 | template_plan | template_unsteady | geometry | mesh_areas | AORC_bounds_W_S_E_N | |
|---|---|---|---|---|---|---|
| 0 | BaldEagleDamBrk | p06 | u03 | g09 | BaldEagleCr | (-77.78073591763562, 40.94941711291342, -77.30... |

Build the annual storm catalog and select one qualification event¶
The catalog uses the native hourly AORC grid. The largest qualifying 2020 event is selected deterministically; the other events remain visible for scenario planning but are not computed by this checked-in example.
storm_catalog = PrecipAorc.get_storm_catalog(
bounds=BOUNDS,
year=CATALOG_YEAR,
inter_event_hours=8.0,
min_depth_inches=0.75,
min_wet_hours=1,
buffer_hours=BUFFER_HOURS,
)
assert len(storm_catalog) > 0
assert storm_catalog["rank"].min() == 1
qualified_catalog = (
storm_catalog.sort_values(["rank", "start_time"])
.head(1)
.copy()
)
storm = qualified_catalog.iloc[0]
EVENT_START = pd.Timestamp(storm["start_time"])
EVENT_END = pd.Timestamp(storm["end_time"])
SIM_START = pd.Timestamp(storm["sim_start"])
SIM_END = pd.Timestamp(storm["sim_end"])
FIRST_VALID_TIME = SIM_START + pd.Timedelta(hours=1)
EXPECTED_FORCING_FRAMES = int((SIM_END - SIM_START).total_seconds() / 3600)
print(f"Catalog contains {len(storm_catalog)} significant storms")
print(
f"Qualified rank-1 event: {EVENT_START} through {EVENT_END}; "
f"catalog depth {storm['total_depth_in']:.3f} in"
)
print(f"Simulation window: {SIM_START} through {SIM_END}")
display(storm_catalog)
2026-10-15 03:58:13 - ras_commander.precip.PrecipAorc - INFO - Generating AORC storm catalog for 2020: bounds W=-77.7807, S=40.9494, E=-77.3059, N=41.1961; inter_event=8.0h, min_depth=0.75in, buffer=48h
2026-10-15 03:58:15 - ras_commander.precip.PrecipAorc - INFO - Storm catalog complete: 13 storms; depth 0.76-2.76 in; largest 2020-12-24 12:00 (2.76 in)
Catalog contains 13 significant storms
Qualified rank-1 event: 2020-12-24 12:00:00 through 2020-12-25 12:00:00; catalog depth 2.760 in
Simulation window: 2020-12-22 12:00:00 through 2020-12-27 12:00:00
| storm_id | start_time | end_time | sim_start | sim_end | total_depth_in | peak_intensity_in_hr | duration_hours | wet_hours | rank | |
|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 1 | 2020-02-07 09:00:00 | 2020-02-07 17:00:00 | 2020-02-05 09:00:00 | 2020-02-09 17:00:00 | 1.019 | 0.280 | 9 | 9 | 8 |
| 1 | 2 | 2020-03-19 01:00:00 | 2020-03-19 10:00:00 | 2020-03-17 01:00:00 | 2020-03-21 10:00:00 | 0.776 | 0.215 | 10 | 8 | 11 |
| 2 | 3 | 2020-03-28 08:00:00 | 2020-03-29 11:00:00 | 2020-03-26 08:00:00 | 2020-03-31 11:00:00 | 1.555 | 0.167 | 28 | 20 | 6 |
| 3 | 4 | 2020-04-17 17:00:00 | 2020-04-18 08:00:00 | 2020-04-15 17:00:00 | 2020-04-20 08:00:00 | 0.770 | 0.094 | 16 | 16 | 12 |
| 4 | 5 | 2020-04-26 09:00:00 | 2020-04-27 02:00:00 | 2020-04-24 09:00:00 | 2020-04-29 02:00:00 | 0.758 | 0.090 | 18 | 17 | 13 |
| 5 | 6 | 2020-04-30 04:00:00 | 2020-05-01 00:00:00 | 2020-04-28 04:00:00 | 2020-05-03 00:00:00 | 2.126 | 0.204 | 21 | 20 | 2 |
| 6 | 7 | 2020-05-28 12:00:00 | 2020-05-29 02:00:00 | 2020-05-26 12:00:00 | 2020-05-31 02:00:00 | 0.952 | 0.348 | 15 | 7 | 9 |
| 7 | 8 | 2020-06-03 06:00:00 | 2020-06-03 21:00:00 | 2020-06-01 06:00:00 | 2020-06-05 21:00:00 | 0.875 | 0.368 | 16 | 8 | 10 |
| 8 | 9 | 2020-09-29 11:00:00 | 2020-09-30 08:00:00 | 2020-09-27 11:00:00 | 2020-10-02 08:00:00 | 1.271 | 0.197 | 22 | 19 | 7 |
| 9 | 10 | 2020-10-29 07:00:00 | 2020-10-30 18:00:00 | 2020-10-27 07:00:00 | 2020-11-01 18:00:00 | 1.734 | 0.128 | 36 | 25 | 5 |
| 10 | 11 | 2020-11-11 13:00:00 | 2020-11-11 22:00:00 | 2020-11-09 13:00:00 | 2020-11-13 22:00:00 | 2.010 | 0.532 | 10 | 10 | 3 |
| 11 | 12 | 2020-12-16 17:00:00 | 2020-12-17 09:00:00 | 2020-12-14 17:00:00 | 2020-12-19 09:00:00 | 1.824 | 0.171 | 17 | 17 | 4 |
| 12 | 13 | 2020-12-24 12:00:00 | 2020-12-25 12:00:00 | 2020-12-22 12:00:00 | 2020-12-27 12:00:00 | 2.760 | 0.226 | 25 | 24 | 1 |
fig, axes = plt.subplots(1, 3, figsize=(14, 4.3), constrained_layout=True)
colors = ["#D39A2C" if rank == 1 else "#2D7FA3" for rank in storm_catalog["rank"]]
axes[0].bar(storm_catalog["storm_id"], storm_catalog["total_depth_in"], color=colors)
axes[0].set_title("Catalog event depth")
axes[0].set_xlabel("Storm ID")
axes[0].set_ylabel("Spatial-mean depth (in)")
axes[0].grid(True, axis="y", alpha=0.25)
axes[1].bar(storm_catalog["storm_id"], storm_catalog["peak_intensity_in_hr"], color=colors)
axes[1].set_title("Peak hourly intensity")
axes[1].set_xlabel("Storm ID")
axes[1].set_ylabel("Intensity (in/hr)")
axes[1].grid(True, axis="y", alpha=0.25)
axes[2].scatter(storm_catalog["start_time"], storm_catalog["total_depth_in"], c=colors, s=55)
axes[2].set_title(f"{CATALOG_YEAR} event timeline")
axes[2].set_xlabel("Event start")
axes[2].set_ylabel("Depth (in)")
axes[2].grid(True, alpha=0.25)
axes[2].tick_params(axis="x", rotation=35)
fig.suptitle("AORC storm catalog; gold marks the computed qualification event", fontweight="bold")
plt.show()

Download the exact interval-ending forcing window¶
precip_folder = ras.project_folder / "Precipitation"
precip_folder.mkdir(exist_ok=True)
date_token = EVENT_START.strftime("%Y%m%d")
precip_file = precip_folder / f"storm_{date_token}.nc"
PrecipAorc.download(
bounds=BOUNDS,
start_time=FIRST_VALID_TIME,
end_time=SIM_END,
output_path=precip_file,
target_crs="EPSG:5070",
resolution=AORC_RESOLUTION_METERS,
)
assert precip_file.exists() and precip_file.stat().st_size > 0
with xr.open_dataset(precip_file) as dataset:
forcing = dataset.load()
source_amount_mm = forcing["APCP_surface"]
forcing_times = pd.to_datetime(source_amount_mm["time"].values)
assert len(forcing_times) == EXPECTED_FORCING_FRAMES
assert forcing_times[0] == FIRST_VALID_TIME
assert forcing_times[-1] == SIM_END
assert source_amount_mm.attrs["value_type"] == "amount"
assert float(source_amount_mm.attrs["accumulation_interval_hours"]) == 1.0
assert np.isfinite(source_amount_mm.values).any()
assert float(np.nanmin(source_amount_mm.values)) >= 0.0
spatial_mean_in = source_amount_mm.mean(dim=("x", "y")) / 25.4
source_cumulative_mean_in = spatial_mean_in.cumsum("time")
event_amounts = source_amount_mm.sel(time=slice(EVENT_START, EVENT_END))
downloaded_event_mean_in = float(event_amounts.mean(dim=("x", "y")).sum() / 25.4)
catalog_delta_in = downloaded_event_mean_in - float(storm["total_depth_in"])
assert abs(catalog_delta_in) <= 0.10
display(pd.DataFrame([{
"first interval-ending frame": forcing_times[0],
"last frame": forcing_times[-1],
"frames": len(forcing_times),
"catalog event depth (in)": float(storm["total_depth_in"]),
"reprojected event depth (in)": downloaded_event_mean_in,
"difference (in)": catalog_delta_in,
"complete simulation-window mean depth (in)": float(source_cumulative_mean_in[-1]),
}]))
2026-10-15 03:58:15 - ras_commander.precip.PrecipAorc - INFO - Downloading AORC APCP_surface: 2020-12-22 13:00:00 to 2020-12-27 12:00:00, bounds W=-77.7807, S=40.9494, E=-77.3059, N=41.1961
2026-10-15 03:58:17 - ras_commander.precip.PrecipAorc - INFO - AORC download complete: storm_20201224.nc (0.1 MB, 120 timesteps)
| first interval-ending frame | last frame | frames | catalog event depth (in) | reprojected event depth (in) | difference (in) | complete simulation-window mean depth (in) | |
|---|---|---|---|---|---|---|---|
| 0 | 2020-12-22 13:00:00 | 2020-12-27 12:00:00 | 120 | 2.76 | 2.762355 | 0.002355 | 2.803767 |
source_total_mm = source_amount_mm.sum("time")
fig, (hyeto_ax, map_ax) = plt.subplots(1, 2, figsize=(13.5, 4.9), constrained_layout=True)
hyeto_ax.bar(forcing_times, spatial_mean_in.values, width=0.035, color="#2D7FA3", label="Hourly amount")
hyeto_ax.set_xlabel("AORC interval-ending time (UTC)")
hyeto_ax.set_ylabel("Spatial-mean hourly depth (in)")
hyeto_ax.grid(True, axis="y", alpha=0.25)
hyeto_ax2 = hyeto_ax.twinx()
hyeto_ax2.plot(forcing_times, source_cumulative_mean_in.values, color="#B64C3B", linewidth=2, label="Cumulative")
hyeto_ax2.set_ylabel("Cumulative depth (in)")
hyeto_ax.axvspan(EVENT_START, EVENT_END, color="#D39A2C", alpha=0.15, label="Catalog event")
h1, l1 = hyeto_ax.get_legend_handles_labels()
h2, l2 = hyeto_ax2.get_legend_handles_labels()
hyeto_ax.legend(h1 + h2, l1 + l2, loc="upper left")
hyeto_ax.set_title("Downloaded AORC forcing and 48-hour buffers")
hyeto_ax.tick_params(axis="x", rotation=25)
image = map_ax.pcolormesh(
source_total_mm["x"],
source_total_mm["y"],
source_total_mm / 25.4,
shading="auto",
cmap="Blues",
)
mesh_areas.to_crs("EPSG:5070").boundary.plot(ax=map_ax, color="#B64C3B", linewidth=1.2)
map_ax.set_title("Complete simulation-window AORC depth")
map_ax.set_xlabel("EPSG:5070 easting (m)")
map_ax.set_ylabel("EPSG:5070 northing (m)")
fig.colorbar(image, ax=map_ax, shrink=0.82, label="Cumulative precipitation (in)")
plt.show()

Author one storm plan and verify the durable imported HDF¶
plan_results = PrecipAorc.create_storm_plans(
storm_catalog=qualified_catalog,
bounds=BOUNDS,
template_plan=TEMPLATE_PLAN,
precip_folder="Precipitation",
ras_object=ras,
download_data=False,
max_storms=1,
enable_timeseries=True,
)
assert len(plan_results) == 1
assert plan_results.iloc[0]["status"] == "success", plan_results.to_dict()
PLAN_NUMBER = str(plan_results.iloc[0]["plan_number"]).zfill(2)
UNSTEADY_NUMBER = str(plan_results.iloc[0]["unsteady_number"]).zfill(2)
RasPlan.update_plan_intervals(
PLAN_NUMBER,
output_interval="1HOUR",
instantaneous_interval="1HOUR",
mapping_interval="1HOUR",
ras_object=ras,
)
precip_config = RasUnsteady.get_met_precipitation_config(UNSTEADY_NUMBER, ras_object=ras)
assert precip_config["enabled"] is True
assert precip_config["mode"] == "Gridded"
assert precip_config["source"] == "GDAL Raster File(s)"
assert precip_config["gdal_group"] == "APCP_surface"
unsteady_hdf = project_file(ras, f"u{UNSTEADY_NUMBER}.hdf")
imported_values_path = "Event Conditions/Meteorology/Precipitation/Imported Raster Data/Values"
with h5py.File(unsteady_hdf, "r") as hdf:
imported_cumulative = hdf[imported_values_path][:]
assert imported_cumulative.shape[0] == EXPECTED_FORCING_FRAMES + 1
assert np.allclose(imported_cumulative[0], 0.0)
assert float(np.nanmin(np.diff(imported_cumulative, axis=0))) >= -1e-7
assert float(np.nanmax(imported_cumulative[-1])) > 0.0
display(plan_results[["storm_id", "start_time", "total_depth_in", "plan_number", "unsteady_number", "status"]])
print(f"Authored p{PLAN_NUMBER} / u{UNSTEADY_NUMBER}; imported HDF shape: {imported_cumulative.shape}")
2026-10-15 03:58:18 - ras_commander.precip.PrecipAorc - INFO - Creating storm plans from template plan 06 (unsteady 03); processing 1 storms
2026-10-15 03:58:18 - ras_commander.RasUnsteady - INFO - Imported gridded precipitation into BaldEagleDamBrk.u04.hdf: 121 timesteps, 414 cells, range=0.0-84.0 mm
2026-10-15 03:58:18 - ras_commander.RasUnsteady - INFO - Completed required gridded meteorology modes in BaldEagleDamBrk.u04: Air Pressure
2026-10-15 03:58:18 - ras_commander.RasUnsteady - INFO - Configured gridded precipitation in BaldEagleDamBrk.u04: source=.\Precipitation\storm_20201224.nc, interpolation=Bilinear, dataset=APCP_surface
2026-10-15 03:58:19 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: BaldEagleDamBrk.p07
2026-10-15 03:58:19 - ras_commander.precip.PrecipAorc - INFO - Created storm 13: 2020-12-24 (2.76 in) -> plan 07, unsteady 04, with HDF time series
2026-10-15 03:58:19 - ras_commander.precip.PrecipAorc - INFO - Storm plan creation complete: 1/1 successful
2026-10-15 03:58:19 - ras_commander.RasPlan - INFO - Updated intervals in plan file: BaldEagleDamBrk.p07
| storm_id | start_time | total_depth_in | plan_number | unsteady_number | status | |
|---|---|---|---|---|---|---|
| 0 | 13 | 2020-12-24 12:00:00 | 2.76 | 07 | 04 | success |
Authored p07 / u04; imported HDF shape: (121, 414)
Preprocess, inspect solver-facing rainfall, and compute serially¶
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
assert solver_values.shape[0] == EXPECTED_FORCING_FRAMES + 1
assert solver_values.shape[0] == len(solver_timestamps)
assert np.isfinite(solver_values).all()
assert float(np.nanmin(solver_values)) >= 0.0
assert float(np.nanmax(solver_values)) > 0.0
assert np.allclose(solver_values[0], 0.0)
fig, ax = plt.subplots(figsize=(10, 4))
ax.plot(np.arange(solver_values.shape[0]), np.nanmean(solver_values, axis=1), color="#2D7FA3")
ax.axvspan(
int((EVENT_START - SIM_START).total_seconds() / 3600),
int((EVENT_END - SIM_START).total_seconds() / 3600),
color="#D39A2C",
alpha=0.18,
label="Catalog event",
)
ax.set_title("Temporary plan-HDF solver-facing AORC precipitation")
ax.set_xlabel("Hourly simulation frame")
ax.set_ylabel("Mean interval precipitation (project depth units)")
ax.grid(True, alpha=0.25)
ax.legend()
plt.show()
print(f"Pre-compute HDF: {PRECOMPUTE_HDF.name}; rainfall array: {solver_values.shape}")
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 = project_file(ras, f"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", "fatal"))
]
assert "Processing Precipitation data" in compute_messages
assert not precipitation_errors, precipitation_errors
print(f"Compute completed: p{PLAN_NUMBER}; final HDF: {PLAN_HDF.name}")
print("Precipitation-related runtime messages:")
print("\n".join(precipitation_messages) or " None reported")
2026-10-15 03:58:19 - ras_commander.RasPreprocess - INFO - Starting HEC-RAS preprocessing for plan 07
2026-10-15 03:58:19 - ras_commander.RasBco - INFO - Monitoring BaldEagleDamBrk.bco07 for 'Starting Unsteady Flow Computations' signal...
2026-10-15 03:58:21 - ras_commander.RasPreprocess - INFO - Waiting for exact CompletePreProcess writer(s) before stopping gridded preprocessing: 9884
2026-10-15 03:58:33 - ras_commander.RasPreprocess - INFO - No CompletePreProcess writer is active and the owned unsteady solver started; stopping before it advances
2026-10-15 03:58:33 - ras_commander.RasBco - INFO - Detected an observed CompletePreProcess writer that has exited with quiescent preprocessing artifacts
2026-10-15 03:58:33 - ras_commander.RasPreprocess - INFO - Preprocessing complete for plan 07 in 14.5s: tmp.hdf=12.2MB, b=3KB, x=5KB

2026-10-15 03:58:33 - ras_commander.RasPlan - INFO - Updated HDF write parameters in plan file: BaldEagleDamBrk.p07
2026-10-15 03:58:33 - ras_commander.RasPlan - INFO - Added HDF output variable 'Cell Hydraulic Depth' to plan file: BaldEagleDamBrk.p07
2026-10-15 03:58:33 - ras_commander.RasPlan - INFO - Added HDF output variable 'Cell Precipitation Rate' to plan file: BaldEagleDamBrk.p07
2026-10-15 03:58:33 - ras_commander.RasPlan - INFO - Added HDF output variable 'Cell Cumulative Precipitation Depth' to plan file: BaldEagleDamBrk.p07
2026-10-15 03:58:33 - ras_commander.RasCmdr - INFO - Applied 'balanced' HDF settings profile to plan: BaldEagleDamBrk.p07
Pre-compute HDF: BaldEagleDamBrk.p07.tmp.hdf; rainfall array: (121, 414)
2026-10-15 03:58:34 - ras_commander.ExecutionArtifacts - INFO - Removed plan 07 execution artifact: BaldEagleDamBrk.bco07
Compute completed: p07; final HDF: BaldEagleDamBrk.p07.hdf
Precipitation-related runtime messages:
Terrain: Terrain50
Processing Precipitation data...
Finished Processing Precipitation data (0.797s)
Compare source AORC depth to the completed plan HDF¶
precip_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, precip_dataset = next(iter(precip_data.items()))
cell_cumulative = precip_dataset["Cell Cumulative Precipitation Depth"]
cell_rate = rate_data[mesh_name]["Cell Precipitation Rate"]
result_times = pd.to_datetime(precip_dataset["time"].values)
rain_steps = np.asarray(cell_cumulative.values, dtype=float)
actual_cell_in = np.asarray(cell_cumulative.isel(time=-1).values, dtype=float)
final_rate = np.asarray(cell_rate.isel(time=-1).values, dtype=float)
assert float(np.nanmin(np.diff(rain_steps, axis=0))) >= -1e-7
assert np.isfinite(final_rate).all() and float(np.nanmin(final_rate)) >= 0.0
# 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)
expected_cell_in = (
source_total_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_by_cell_id = np.asarray(
cell_cumulative.isel(time=-1).sel(
cell_id=mesh_cell_points["cell_id"].to_numpy(dtype=int)
).values,
dtype=float,
)
# HEC-RAS exposes point records for 1,531 non-computational positions in this
# example geometry in addition to its 18,066 active mesh-cell polygons. Those
# positions remain zero and are not solver cells, so compare active raining cells.
comparison_mask = (
(actual_by_cell_id > 0.0)
& np.isfinite(expected_cell_in)
& np.isfinite(actual_by_cell_id)
)
comparison_error_in = actual_by_cell_id[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_by_cell_id > 0.0)) == len(mesh_cell_polygons)
comparison_summary = pd.DataFrame([{
"source-sampled cells compared": int(comparison_mask.sum()),
"model mesh cells": len(mesh_cell_polygons),
"raining HDF cells": int(np.count_nonzero(actual_by_cell_id > 0.0)),
"maximum source-vs-HDF error (in)": float(np.max(np.abs(comparison_error_in))),
"final HDF mean cumulative depth (in)": float(np.mean(actual_by_cell_id[comparison_mask])),
"final HDF maximum cumulative depth (in)": float(np.max(actual_by_cell_id)),
"final HDF maximum ending rate (in/hr)": float(np.max(final_rate)),
}]).round(6)
display(comparison_summary)
fig, (series_ax, map_ax) = plt.subplots(1, 2, figsize=(13.5, 4.9), constrained_layout=True)
series_ax.plot(result_times, cell_cumulative.mean("cell_id"), label="Mesh mean", color="#2D7FA3")
series_ax.plot(result_times, cell_cumulative.max("cell_id"), label="Mesh maximum", color="#B64C3B")
series_ax.axvspan(EVENT_START, EVENT_END, color="#D39A2C", alpha=0.18, label="Catalog event")
series_ax.set_title("Completed plan-HDF cumulative precipitation")
series_ax.set_xlabel("Simulation time")
series_ax.set_ylabel("Cumulative precipitation (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_by_cell_id[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="#B64C3B", linewidth=1.2)
map_ax.set_title("Solver-applied AORC precipitation")
map_ax.set_xlabel("EPSG:5070 easting (m)")
map_ax.set_ylabel("EPSG:5070 northing (m)")
plt.show()
| source-sampled cells compared | model mesh cells | 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 | 18066 | 18066 | 18066 | 0.000002 | 2.765861 | 2.925034 | 0.0 |

Review hydraulic response, runtime diagnostics, and completion checks¶
The hydraulic trace confirms that the authored plan completed and produced finite model output. It is contextual rather than a rainfall-attribution test because the template plan also contains existing hydraulic initial and boundary conditions.
depth_summary = mesh_variable_summary(PLAN_HDF, "Cell Hydraulic Depth")
assert float(depth_summary["maximum"].max()) > 0.0
display(depth_summary)
depth_data = HdfResultsMesh.get_mesh_cells_timeseries(PLAN_HDF, var="Cell Hydraulic Depth")
depth_mesh_name, depth_dataset = next(iter(depth_data.items()))
depth_values = depth_dataset["Cell Hydraulic Depth"]
depth_times = pd.to_datetime(depth_dataset["time"].values)
fig, ax = plt.subplots(figsize=(10, 4.2))
ax.plot(depth_times, depth_values.mean("cell_id"), label="Mesh mean", color="#2D7FA3")
ax.plot(depth_times, depth_values.max("cell_id"), label="Mesh maximum", color="#B64C3B")
ax.axvspan(EVENT_START, EVENT_END, color="#D39A2C", alpha=0.18, label="Catalog event")
ax.set_title(f"HEC-RAS hydraulic depth response in {depth_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()
bco_path = project_file(ras, f"bco{PLAN_NUMBER}")
assert bco_path.exists()
bco_text = bco_path.read_text(encoding="utf-8", errors="replace")
diagnostic_pattern = re.compile(
r"\b(?:warning|fatal|failed|missing)\b|"
r"\berror(?::|\s+(?:reading|opening|processing|computing|occurred|encountered))",
flags=re.IGNORECASE,
)
bco_problem_lines = [
line.strip() for line in bco_text.splitlines()
if diagnostic_pattern.search(line)
]
assert not bco_problem_lines, bco_problem_lines
print("BCO diagnostic scan: no warning/error/fatal/failed/missing messages found")
precip_excess_acft = float(re.findall(
r"Precipitation Excess \(Acre Feet\)\s+([-+0-9.]+)", bco_text
)[-1])
precip_excess_in = float(re.findall(
r"Precipitation Excess \(inches\)\s+([-+0-9.]+)", bco_text
)[-1])
volume_error_acft, volume_error_percent = [
float(value)
for value in re.findall(
r"Error\s+Percent Error\s+\*+\s+\*+\s+([-+0-9.]+)\s+([-+0-9.]+)",
bco_text,
flags=re.IGNORECASE | re.DOTALL,
)[-1]
]
display(pd.DataFrame([{
"precipitation excess (acre-ft)": precip_excess_acft,
"precipitation excess (in)": precip_excess_in,
"volume error (acre-ft)": volume_error_acft,
"volume error (%)": volume_error_percent,
}]))
completion_checks = pd.Series(
{
"annual AORC catalog is non-empty": len(storm_catalog) > 0,
"largest catalog event selected deterministically": int(storm["rank"]) == 1,
"download honors exact hourly window": len(forcing_times) == EXPECTED_FORCING_FRAMES,
"reprojected event depth agrees with catalog": abs(catalog_delta_in) <= 0.10,
"storm plan and durable import HDF authored": plan_results.iloc[0]["status"] == "success",
"temporary plan HDF contains nonzero precipitation": float(np.nanmax(solver_values)) > 0.0,
"HEC-RAS compute completed": bool(compute_result),
"completed HDF reproduces source grid": float(np.max(np.abs(comparison_error_in))) <= 1e-5,
"hydraulic output is finite and positive": float(depth_summary["maximum"].max()) > 0.0,
"runtime precipitation diagnostics are clean": not precipitation_errors,
"BCO diagnostic scan is clean": not bco_problem_lines,
},
name="passed",
).to_frame()
display(completion_checks)
assert completion_checks["passed"].all()
print("AORC rain-on-grid QA complete; manual HEC-RAS diagnostics remain required.")
| mesh | timesteps | cells | minimum | final_mean | maximum | positive_final_cells | |
|---|---|---|---|---|---|---|---|
| 0 | BaldEagleCr | 121 | 18066 | 0.0 | 5.191351 | 71.003967 | 17968 |

BCO diagnostic scan: no warning/error/fatal/failed/missing messages found
| precipitation excess (acre-ft) | precipitation excess (in) | volume error (acre-ft) | volume error (%) | |
|---|---|---|---|---|
| 0 | 1682.0 | 0.7647 | 1.263 | 0.000904 |
| passed | |
|---|---|
| annual AORC catalog is non-empty | True |
| largest catalog event selected deterministically | True |
| download honors exact hourly window | True |
| reprojected event depth agrees with catalog | True |
| storm plan and durable import HDF authored | True |
| temporary plan HDF contains nonzero precipitation | True |
| HEC-RAS compute completed | True |
| completed HDF reproduces source grid | True |
| hydraulic output is finite and positive | True |
| runtime precipitation diagnostics are clean | True |
| BCO diagnostic scan is clean | True |
AORC rain-on-grid QA complete; manual HEC-RAS diagnostics remain required.