Skip to content

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.

Python
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}")
Text Only
Run workspace: example_900_aorc_precipitation
HEC-RAS version: 7.0; AORC catalog year: 2020
Python
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

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_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()
Text Only
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...

png

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.

Python
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)
Text Only
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
Python
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()

png

Download the exact interval-ending forcing window

Python
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]),
}]))
Text Only
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
Python
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()

png

Author one storm plan and verify the durable imported HDF

Python
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}")
Text Only
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
Text Only
Authored p07 / u04; imported HDF shape: (121, 414)

Preprocess, inspect solver-facing rainfall, and compute serially

Python
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")
Text Only
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

png

Text Only
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

Python
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

png

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.

Python
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

png

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