Atlas 14 Gridded Precipitation: Compatibility and Forcing QA¶
This executable example retrieves NOAA Atlas 14 precipitation-frequency grids for the Bald Eagle Creek RasExamples model, constructs a spatial 100-year, 24-hour Alternating Block Method (ABM) storm, and exports the GDAL NetCDF contract consumed by HEC-RAS rain-on-grid.
The notebook is intentionally a forcing-preparation and compatibility example rather than a second long hydraulic simulation. It verifies the input data numerically and visually. For temporary plan-HDF preprocessing, completed HEC-RAS computations, final plan-HDF rainfall, and hydraulic comparisons, continue with 727. Direct GeoTIFF translation and a shorter solver run are demonstrated in 729.
Engineering control: automated checks are necessary but not sufficient. Review the full HEC-RAS runtime messages, forcing maps, temporal plots, boundary conditions, and model configuration before relying on a simulation.
1. Reproducible setup¶
Set USE_LOCAL_SOURCE = False to run against an installed release. Generated model and precipitation files are written beneath the ignored working directory unless RAS_COMMANDER_EXAMPLE_RUN_ROOT is set.
# True uses this checkout; False uses the installed 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 IPython.display import display
import matplotlib.pyplot as plt
from matplotlib.colors import BoundaryNorm, ListedColormap
import numpy as np
import pandas as pd
import xarray as xr
from ras_commander import RasExamples, RasUnsteady, init_ras_project
from ras_commander.hdf import HdfMesh
from ras_commander.precip import AbmHyetographGrid, Atlas14Grid
RUN_ROOT = Path(
os.environ.get(
"RAS_COMMANDER_EXAMPLE_RUN_ROOT",
REPO_ROOT / "working" / "example_722_atlas14_forcing_qa",
)
)
RUN_ROOT.mkdir(parents=True, exist_ok=True)
PROJECT_NAME = "BaldEagleCrkMulti2D"
PROJECT_SUFFIX = "atlas14_722"
RAS_VERSION = "6.6"
SOURCE_PLAN = "06"
ARI_YEARS = 100
STORM_DURATION_HOURS = 24.0
TIMESTEP_MINUTES = 15
PEAK_POSITION_PERCENT = 50.0
ATLAS_BUFFER_PERCENT = 10.0
DDF_DURATIONS = [1, 2, 3, 6, 12, 24]
OUTPUT_VARIABLE = "APCP_surface"
COLORS = {
"navy": "#174A6E",
"blue": "#2D7FA3",
"gold": "#D39A2C",
"red": "#B64C3B",
"green": "#477A5B",
"gray": "#5C6670",
}
plt.rcParams.update({"figure.dpi": 120, "axes.grid": False})
print(f"Run workspace: {RUN_ROOT.name}")
Run workspace: 722_20260926b
2. Version and input-format compatibility¶
Global gridded meteorology starts in HEC-RAS 6.0. HEC-RAS 5.x uniform-per-area precipitation is a different mechanism; converting a raster to DSS does not add global gridded support.
The table and matrix below are generated from the same capability policy used by the authoring API. “Qualified” means an executable route was verified in the project qualification matrix; “documented” means the route is supported by HEC documentation but has not received the same host-specific end-to-end qualification. GeoTIFF is a ras-commander translation route to durable HEC-compatible NetCDF/HDF, not a claim of native HEC-RAS GeoTIFF ingestion.
VERSIONS = ["5.0.7", "6.0", "6.1", "6.2", "6.3", "6.3.1", "6.4", "6.4.1", "6.5", "6.6", "7.0", "7.0.1"]
capability_records = []
capability_objects = {}
for version in VERSIONS:
cap = RasUnsteady.get_gridded_precipitation_capabilities(version)
capability_objects[version] = cap
capability_records.append(
{
"version": version,
"global gridded": cap.global_gridded_supported,
"native sources": ", ".join(cap.native_sources) or "none",
"ras-commander inputs": ", ".join(cap.ras_commander_inputs) or "none",
"ratio applied": cap.ratio_applied,
"period-average timing": cap.period_average_timing,
"DSS qualification": cap.native_dss_qualification,
"NetCDF/HDF qualification": cap.netcdf_hdf_qualification,
"GeoTIFF translation": cap.geotiff_translation_qualification,
"WMIC compatibility": cap.requires_wmic_compatibility,
}
)
capability_df = pd.DataFrame(capability_records).set_index("version")
display(capability_df)
def qualification_score(value: str) -> int:
if value == "unsupported":
return 0
if value in {"documented", "inconclusive"}:
return 1
return 2
matrix_rows = {
"Global gridded API": [2 if capability_objects[v].global_gridded_supported else 0 for v in VERSIONS],
"Precipitation ratio": [2 if capability_objects[v].ratio_applied else 0 for v in VERSIONS],
"Period-average timing": [
2 if capability_objects[v].period_average_timing == "corrected"
else 1 if capability_objects[v].period_average_timing == "shifted"
else 0
for v in VERSIONS
],
"Native DSS": [qualification_score(capability_objects[v].native_dss_qualification) for v in VERSIONS],
"NetCDF/HDF route": [qualification_score(capability_objects[v].netcdf_hdf_qualification) for v in VERSIONS],
"GeoTIFF adapter": [qualification_score(capability_objects[v].geotiff_translation_qualification) for v in VERSIONS],
"Wine evidence": [
2 if any(
"wine" in value
for value in (
capability_objects[v].native_dss_qualification,
capability_objects[v].netcdf_hdf_qualification,
capability_objects[v].geotiff_translation_qualification,
)
) else 0
for v in VERSIONS
],
}
matrix = np.asarray(list(matrix_rows.values()), dtype=int)
cmap = ListedColormap(["#D9DEE3", "#E7C66A", "#477A5B"])
norm = BoundaryNorm([-0.5, 0.5, 1.5, 2.5], cmap.N)
fig, ax = plt.subplots(figsize=(13, 5.1))
image = ax.imshow(matrix, cmap=cmap, norm=norm, aspect="auto")
ax.set_xticks(range(len(VERSIONS)), VERSIONS, rotation=45, ha="right")
ax.set_yticks(range(len(matrix_rows)), list(matrix_rows))
for row in range(matrix.shape[0]):
for col in range(matrix.shape[1]):
ax.text(col, row, str(matrix[row, col]), ha="center", va="center", color="white" if matrix[row, col] == 2 else "#263238", fontweight="bold")
ax.set_title("HEC-RAS gridded-precipitation compatibility and qualification")
colorbar = fig.colorbar(image, ax=ax, ticks=[0, 1, 2], shrink=0.85, pad=0.02)
colorbar.ax.set_yticklabels(["Unsupported / absent", "Documented or limited", "Qualified / corrected"])
fig.tight_layout()
plt.show()
assert not capability_objects["5.0.7"].global_gridded_supported
assert all(capability_objects[v].global_gridded_supported for v in VERSIONS if not v.startswith("5."))
assert all(capability_objects[v].period_average_timing == "shifted" for v in ["6.0", "6.1", "6.2", "6.3", "6.3.1"])
assert all(capability_objects[v].period_average_timing == "corrected" for v in ["6.4", "6.4.1", "6.5", "6.6", "7.0", "7.0.1"])
| global gridded | native sources | ras-commander inputs | ratio applied | period-average timing | DSS qualification | NetCDF/HDF qualification | GeoTIFF translation | WMIC compatibility | |
|---|---|---|---|---|---|---|---|---|---|
| version | |||||||||
| 5.0.7 | False | none | none | False | unsupported | unsupported | unsupported | unsupported | False |
| 6.0 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | False | shifted | documented | documented | documented | False |
| 6.1 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | False | shifted | qualified_windows_with_host_shim | documented | documented | True |
| 6.2 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | True | shifted | qualified_windows_with_host_shim | documented | documented | True |
| 6.3 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | True | shifted | qualified_windows | documented | documented | True |
| 6.3.1 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | True | shifted | qualified_windows | documented | documented | True |
| 6.4 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | True | corrected | documented | documented | documented | False |
| 6.4.1 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | True | corrected | documented | documented | documented | False |
| 6.5 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | True | corrected | inconclusive | documented | documented | False |
| 6.6 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | True | corrected | qualified_windows_and_wine | qualified_windows_and_wine | qualified_windows_and_wine | False |
| 7.0 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | True | corrected | qualified_windows | qualified_windows | documented | False |
| 7.0.1 | True | dss, netcdf, grib | dss, netcdf, grib, geotiff | True | corrected | qualified_windows | documented | documented | False |

Version-specific operating guidance¶
- 5.x: global gridded precipitation is unsupported; use the separate uniform-per-area mechanism if it is suitable for the model.
- 6.0–6.1: the optional precipitation ratio is not applied, so ras-commander rejects non-unit ratios.
- 6.0–6.3.1: native period-average precipitation may shift by one interval; prefer cumulative materialization.
- 6.1–6.3.1: some hosts require the process-local WMIC compatibility path.
- 6.5: the available qualification host exited before precipitation preprocessing, so executable format qualification remains inconclusive even though the formats are documented.
- 6.6: DSS and the NetCDF/HDF and GeoTIFF-translation routes are qualified on native Windows and CLB07/Wine with the required Wine runtime present.
- WPC QPF GRIB2: its compression is not accepted natively through HEC-RAS 7.0.1; translate it to DSS with HEC-Vortex or HEC-MetVue.
3. Select the RasExamples model and mesh¶
The project and plan are selected through ras-commander DataFrames. The geometry HDF supplies the actual 2D flow-area extent used for the Atlas 14 subset.
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,
load_hdf_metadata=False,
)
plan_number = ras.plan_df["plan_number"].astype(str).str.zfill(2)
source_rows = ras.plan_df.loc[plan_number.eq(SOURCE_PLAN)]
assert len(source_rows) == 1, "Expected exactly one source Plan 06"
source_plan = source_rows.iloc[0]
GEOMETRY_HDF = Path(f"{source_plan['Geom Path']}.hdf")
assert GEOMETRY_HDF.exists()
date_parts = str(source_plan["Simulation Date"]).split(",")
SIM_START = datetime.strptime(f"{date_parts[0]} {date_parts[1]}", "%d%b%Y %H%M")
SIM_END = datetime.strptime(f"{date_parts[2]} {date_parts[3]}", "%d%b%Y %H%M")
SIMULATION_HOURS = (SIM_END - SIM_START).total_seconds() / 3600.0
mesh_areas = HdfMesh.get_mesh_areas(GEOMETRY_HDF)
mesh_cells = HdfMesh.get_mesh_cell_polygons(GEOMETRY_HDF)
assert len(mesh_areas) == 1 and not mesh_cells.empty
assert mesh_areas.crs is not None and mesh_cells.crs is not None
model_summary = pd.DataFrame(
[{
"project": ras.project_name,
"source plan": f"p{SOURCE_PLAN}",
"geometry": f"g{str(source_plan['geometry_number']).zfill(2)}",
"2D area": mesh_areas.iloc[0]["mesh_name"],
"mesh cells": len(mesh_cells),
"simulation start": SIM_START,
"simulation end": SIM_END,
"simulation duration (hr)": SIMULATION_HOURS,
}]
)
display(model_summary)
2026-09-26 00:17:41 - ras_commander.RasExamples - INFO - Successfully extracted project 'BaldEagleCrkMulti2D' to BaldEagleCrkMulti2D_atlas14_722
2026-09-26 00:17:42 - ras_commander.RasPrj - INFO - ras-commander v0.102.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-09-26 00:17:42 - ras_commander.RasPrj - INFO - Project initialized: BaldEagleDamBrk
2026-09-26 00:17:42 - ras_commander.RasPrj - INFO - Using HEC-RAS version 6.6
2026-09-26 00:17:42 - 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.102.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 | source plan | geometry | 2D area | mesh cells | simulation start | simulation end | simulation duration (hr) | |
|---|---|---|---|---|---|---|---|---|
| 0 | BaldEagleDamBrk | p06 | g09 | BaldEagleCr | 18066 | 2018-09-09 | 2018-09-14 | 120.0 |
4. Retrieve Atlas 14 depths and verify the depth-duration relationship¶
Atlas14Grid requests only the project subset required for the 2D area plus a 10% buffer. Six durations are retained so the depth-duration-frequency curve can be checked at minimum-, median-, and maximum-depth pixels.
atlas = Atlas14Grid.get_pfe_from_project(
GEOMETRY_HDF,
extent_source="2d_flow_area",
durations=DDF_DURATIONS,
return_periods=[ARI_YEARS],
buffer_percent=ATLAS_BUFFER_PERCENT,
)
assert atlas["units"] == "inches"
assert atlas["extent_source"] == "2d_flow_area"
assert atlas["mesh_area_names"] == mesh_areas["mesh_name"].astype(str).tolist()
ari_values = np.asarray(atlas["ari"], dtype=float)
ari_matches = np.flatnonzero(np.isclose(ari_values, ARI_YEARS))
assert len(ari_matches) == 1
ari_index = int(ari_matches[0])
depth_grids = {
duration: np.asarray(atlas[f"pfe_{duration}hr"])[:, :, ari_index]
for duration in DDF_DURATIONS
}
depth_24hr = depth_grids[24]
assert np.isfinite(depth_24hr).all()
assert float(np.nanmin(depth_24hr)) > 0.0
flat_24hr = depth_24hr.ravel()
median_flat_index = int(np.nanargmin(np.abs(flat_24hr - np.nanmedian(flat_24hr))))
representative_indices = {
"Minimum-depth pixel": np.unravel_index(np.nanargmin(flat_24hr), depth_24hr.shape),
"Median-depth pixel": np.unravel_index(median_flat_index, depth_24hr.shape),
"Maximum-depth pixel": np.unravel_index(np.nanargmax(flat_24hr), depth_24hr.shape),
}
atlas_summary = pd.DataFrame(
[{
"return period (yr)": ARI_YEARS,
"duration (hr)": STORM_DURATION_HOURS,
"grid rows": depth_24hr.shape[0],
"grid columns": depth_24hr.shape[1],
"minimum depth (in)": float(np.nanmin(depth_24hr)),
"mean depth (in)": float(np.nanmean(depth_24hr)),
"maximum depth (in)": float(np.nanmax(depth_24hr)),
"max/min ratio": float(np.nanmax(depth_24hr) / np.nanmin(depth_24hr)),
}]
)
display(atlas_summary.round(3))
2026-09-26 00:17:43 - ras_commander.precip.Atlas14Grid - INFO - Extracting Atlas 14 extent from BaldEagleDamBrk.g09.hdf using 2d_flow_area
2026-09-26 00:17:43 - ras_commander.precip.Atlas14Grid - INFO - 2D flow area bounds: W=-77.7591, S=40.9614, E=-77.3275, N=41.1842
2026-09-26 00:17:43 - ras_commander.precip.Atlas14Grid - INFO - Loading Atlas 14 coordinate arrays from remote file...
2026-09-26 00:18:00 - ras_commander.precip.Atlas14Grid - INFO - Loaded coordinates: lat=3121, lon=7081, ari=9
2026-09-26 00:18:00 - ras_commander.precip.Atlas14Grid - INFO - Extracting Atlas 14 data for bounds (-77.8023, 40.9392, -77.2844, 41.2064): lat[2033:2065], lon[5664:5726]
2026-09-26 00:18:17 - ras_commander.precip.Atlas14Grid - INFO - Atlas 14 subset: 209.2 KB of 2276.2 MB estimated full-grid payload (32x62 cells, 6 durations, 0.00898% of full grid)
| return period (yr) | duration (hr) | grid rows | grid columns | minimum depth (in) | mean depth (in) | maximum depth (in) | max/min ratio | |
|---|---|---|---|---|---|---|---|---|
| 0 | 100 | 24.0 | 32 | 62 | 5.6 | 6.005 | 7.43 | 1.327 |
mesh_lonlat = mesh_areas.to_crs("EPSG:4326")
lat = np.asarray(atlas["lat"], dtype=float)
lon = np.asarray(atlas["lon"], dtype=float)
fig, (map_ax, ddf_ax) = plt.subplots(1, 2, figsize=(13, 5.2))
depth_image = map_ax.pcolormesh(lon, lat, depth_24hr, shading="auto", cmap="viridis")
mesh_lonlat.boundary.plot(ax=map_ax, color="white", linewidth=1.8, label="2D perimeter")
map_ax.set_title("Atlas 14 100-year, 24-hour depth")
map_ax.set_xlabel("Longitude")
map_ax.set_ylabel("Latitude")
map_ax.legend(loc="lower left")
map_colorbar = fig.colorbar(depth_image, ax=map_ax, shrink=0.86)
map_colorbar.set_label("Precipitation depth (in)")
for label, (row, col) in representative_indices.items():
values = [depth_grids[duration][row, col] for duration in DDF_DURATIONS]
assert np.all(np.diff(values) > 0.0)
ddf_ax.plot(DDF_DURATIONS, values, marker="o", linewidth=2, label=label)
ddf_ax.set_xscale("log", base=2)
ddf_ax.set_xticks(DDF_DURATIONS, labels=[str(value) for value in DDF_DURATIONS])
ddf_ax.set_title("100-year depth-duration-frequency checks")
ddf_ax.set_xlabel("Duration (hr)")
ddf_ax.set_ylabel("Precipitation depth (in)")
ddf_ax.grid(True, alpha=0.25)
ddf_ax.legend(loc="upper left")
fig.tight_layout()
plt.show()

5. Construct the spatial ABM storm and prove depth conservation¶
The ABM rearranges each pixel's incremental duration-curve depths into a centered 15-minute hyetograph. It must preserve the 24-hour Atlas 14 depth at every grid cell.
precipitation_dir = ras.project_folder / "Precipitation" / "atlas14_722"
precipitation_dir.mkdir(parents=True, exist_ok=True)
RAW_ABM = precipitation_dir / "atlas14_100yr_24hr_abm_raw.nc"
RAS_NETCDF = precipitation_dir / "atlas14_100yr_24hr_abm_ras.nc"
raw_abm_path = AbmHyetographGrid.generate(
bounds=atlas["bounds"],
ari_years=ARI_YEARS,
storm_duration_hours=STORM_DURATION_HOURS,
timestep_minutes=TIMESTEP_MINUTES,
peak_position_percent=PEAK_POSITION_PERCENT,
output_netcdf=RAW_ABM,
buffer_percent=0.0,
include_subhourly=True,
)
assert raw_abm_path.exists()
with xr.open_dataset(raw_abm_path, engine="netcdf4", decode_timedelta=False) as raw_source:
raw_abm = raw_source.load()
increments_in = raw_abm["precip_incremental"]
cumulative_in = raw_abm["precip_cumulative"]
assert increments_in.dims == ("time", "lat", "lon")
assert increments_in.sizes["time"] == 96
assert increments_in.attrs["units"] == "inches"
assert np.allclose(np.diff(raw_abm["time"].values), TIMESTEP_MINUTES / 60.0)
abm_total_in = increments_in.sum("time")
atlas_total_on_abm_grid = xr.DataArray(
depth_24hr,
dims=("lat", "lon"),
coords={"lat": atlas["lat"], "lon": atlas["lon"]},
).sel(lat=abm_total_in["lat"], lon=abm_total_in["lon"])
abm_depth_error_in = np.abs(abm_total_in - atlas_total_on_abm_grid)
assert float(abm_depth_error_in.max()) <= 1e-5
abm_qc = pd.DataFrame(
[{
"intervals": increments_in.sizes["time"],
"interval (min)": TIMESTEP_MINUTES,
"storm duration (hr)": increments_in.sizes["time"] * TIMESTEP_MINUTES / 60.0,
"peak position (%)": PEAK_POSITION_PERCENT,
"minimum total (in)": float(abm_total_in.min()),
"mean total (in)": float(abm_total_in.mean()),
"maximum total (in)": float(abm_total_in.max()),
"max Atlas-vs-ABM error (in)": float(abm_depth_error_in.max()),
}]
)
display(abm_qc.round(6))
2026-09-26 00:18:18 - ras_commander.precip.AbmHyetographGrid - INFO - Generating ABM grid: ARI=100yr, duration=24.0hr, dt=15min, [email protected]%, bounds=(np.float64(-77.80227796999864), np.float64(40.939176433913076), np.float64(-77.28436563242954), np.float64(41.20644561999805))
2026-09-26 00:18:18 - ras_commander.precip.Atlas14Grid - INFO - Extracting Atlas 14 data for bounds (-77.8023, 40.9392, -77.2844, 41.2064): lat[2033:2065], lon[5664:5726]
2026-09-26 00:18:40 - ras_commander.precip.Atlas14Grid - INFO - Atlas 14 subset: 244.1 KB of 2655.6 MB estimated full-grid payload (32x62 cells, 7 durations, 0.00898% of full grid)
2026-09-26 00:18:40 - ras_commander.precip.StormGenerator - INFO - Downloading Atlas 14 data for (41.07281102695556, -77.54332180121409)...
2026-09-26 00:18:41 - ras_commander.precip.StormGenerator - INFO - Downloaded Atlas 14 data for region: Ohio River Basin
2026-09-26 00:18:41 - ras_commander.precip.AbmHyetographGrid - INFO - ABM grid complete → atlas14_100yr_24hr_abm_raw.nc
| intervals | interval (min) | storm duration (hr) | peak position (%) | minimum total (in) | mean total (in) | maximum total (in) | max Atlas-vs-ABM error (in) | |
|---|---|---|---|---|---|---|---|---|
| 0 | 96 | 15 | 24.0 | 50.0 | 5.599998 | 6.005237 | 7.429999 | 0.000003 |
interval_end_hours = np.asarray(raw_abm["time"].values, dtype=float) + TIMESTEP_MINUTES / 60.0
fig, (increment_ax, cumulative_ax) = plt.subplots(2, 1, figsize=(11, 7), sharex=True)
for label, (row, col) in representative_indices.items():
increment_ax.step(
interval_end_hours,
increments_in.isel(lat=row, lon=col).values,
where="post",
linewidth=1.8,
label=label,
)
cumulative_ax.plot(
interval_end_hours,
cumulative_in.isel(lat=row, lon=col).values,
linewidth=2,
label=label,
)
increment_ax.set_title("Spatial ABM incremental precipitation")
increment_ax.set_ylabel("15-minute depth (in)")
increment_ax.grid(True, alpha=0.25)
increment_ax.legend(loc="upper right")
cumulative_ax.set_title("Cumulative depth conservation at representative pixels")
cumulative_ax.set_xlabel("Hours from storm start")
cumulative_ax.set_ylabel("Cumulative depth (in)")
cumulative_ax.grid(True, alpha=0.25)
cumulative_ax.legend(loc="upper left")
fig.tight_layout()
plt.show()

6. Export and validate the HEC-RAS GDAL NetCDF contract¶
The converter changes representation, not rainfall depth. It projects the grid to EPSG:5070, stores period-average rates in mm/hr, adds the required zero-rate initial frame, and extends the forcing through the full five-day plan with an explicit zero-rate tail.
ras_netcdf_path = AbmHyetographGrid.to_ras_netcdf(
raw_abm_path,
RAS_NETCDF,
start_time=SIM_START,
target_crs="EPSG:5070",
output_variable=OUTPUT_VARIABLE,
end_time=SIM_END,
)
assert ras_netcdf_path.exists()
with xr.open_dataset(ras_netcdf_path) as ras_source:
forcing = ras_source.load()
rate = forcing[OUTPUT_VARIABLE]
times = pd.to_datetime(rate["time"].values)
interval_hours = float(forcing.attrs["interval_minutes"]) / 60.0
STORM_END = pd.Timestamp(SIM_START) + pd.Timedelta(hours=STORM_DURATION_HOURS)
storm_end_index = int(times.get_loc(STORM_END))
tail_start_index = storm_end_index + 1
storm_total_mm = rate.isel(time=slice(1, tail_start_index)).sum("time", skipna=False) * interval_hours
forcing_total_mm = rate.isel(time=slice(1, None)).sum("time", skipna=False) * interval_hours
forcing_total_in = forcing_total_mm / 25.4
assert times[0] == pd.Timestamp(SIM_START)
assert times[storm_end_index] == STORM_END
assert times[-1] == pd.Timestamp(SIM_END)
assert np.allclose(rate.isel(time=0).values[np.isfinite(rate.isel(time=0).values)], 0.0)
post_storm_rate = rate.isel(time=slice(tail_start_index, None)).values
assert np.all(post_storm_rate[np.isfinite(post_storm_rate)] == 0.0)
xr.testing.assert_allclose(forcing_total_mm, storm_total_mm)
assert rate.attrs["units"] == "mm/hr"
assert rate.attrs["grid_mapping"] == "spatial_ref"
assert forcing.attrs["target_crs"] == "EPSG:5070"
assert forcing.attrs["depth_conservation_max_error_mm"] <= 1e-4
mesh_5070 = mesh_areas.to_crs("EPSG:5070")
cells_5070 = mesh_cells.to_crs("EPSG:5070")
cell_centers = cells_5070.geometry.representative_point()
sample_x = xr.DataArray(cell_centers.x.to_numpy(), dims="cell")
sample_y = xr.DataArray(cell_centers.y.to_numpy(), dims="cell")
sampled_total_in = forcing_total_in.sel(x=sample_x, y=sample_y, method="nearest")
assert np.isfinite(sampled_total_in.values).all()
assert float(sampled_total_in.min()) > 0.0
forcing_qc = pd.DataFrame(
[{
"variable": OUTPUT_VARIABLE,
"rate units": rate.attrs["units"],
"CRS": forcing.attrs["target_crs"],
"frames": rate.sizes["time"],
"storm end": times[storm_end_index],
"forcing end": times[-1],
"zero-tail frames": int(forcing.attrs["zero_tail_frames"]),
"valid grid fraction (%)": 100 * forcing.attrs["valid_coverage_fraction"],
"mesh cells covered": int(np.isfinite(sampled_total_in.values).sum()),
"mesh cells total": len(mesh_cells),
"mesh minimum total (in)": float(sampled_total_in.min()),
"mesh mean total (in)": float(sampled_total_in.mean()),
"mesh maximum total (in)": float(sampled_total_in.max()),
"max conversion error (mm)": forcing.attrs["depth_conservation_max_error_mm"],
}]
)
display(forcing_qc.round({column: 6 for column in forcing_qc.select_dtypes(include="number").columns}))
2026-09-26 00:18:42 - ras_commander.precip.AbmHyetographGrid - INFO - Prepared HEC-RAS Atlas 14 forcing atlas14_100yr_24hr_abm_ras.nc: 96 storm intervals, 384 zero-tail frames (96 hr), 50x64 cells, 71.3% valid coverage, max depth error 0.000003 mm
| variable | rate units | CRS | frames | storm end | forcing end | zero-tail frames | valid grid fraction (%) | mesh cells covered | mesh cells total | mesh minimum total (in) | mesh mean total (in) | mesh maximum total (in) | max conversion error (mm) | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | APCP_surface | mm/hr | EPSG:5070 | 481 | 2018-09-10 | 2018-09-14 | 384 | 71.28125 | 18066 | 18066 | 5.600401 | 5.782384 | 5.963356 | 0.000003 |
fig, (forcing_ax, timing_ax) = plt.subplots(1, 2, figsize=(13, 5.2), gridspec_kw={"width_ratios": [1.25, 1]})
forcing_image = forcing_ax.pcolormesh(
forcing_total_in["x"],
forcing_total_in["y"],
forcing_total_in,
shading="auto",
cmap="viridis",
)
mesh_5070.boundary.plot(ax=forcing_ax, color="white", linewidth=1.8, label="2D perimeter")
forcing_ax.set_title("Projected Atlas 14 depth supplied to HEC-RAS")
forcing_ax.set_xlabel("EPSG:5070 easting (m)")
forcing_ax.set_ylabel("EPSG:5070 northing (m)")
forcing_ax.legend(loc="lower left")
forcing_colorbar = fig.colorbar(forcing_image, ax=forcing_ax, shrink=0.86)
forcing_colorbar.set_label("Integrated depth (in)")
timing_ax.barh(
["HEC-RAS plan", "Forcing file", "Nonzero storm"],
[SIMULATION_HOURS, SIMULATION_HOURS, STORM_DURATION_HOURS],
color=[COLORS["gray"], COLORS["blue"], COLORS["gold"]],
)
timing_ax.axvline(STORM_DURATION_HOURS, color=COLORS["red"], linestyle="--", linewidth=1.5)
timing_ax.set_xlim(0, SIMULATION_HOURS)
timing_ax.set_title("Five-day coverage with explicit zero-rate tail")
timing_ax.set_xlabel("Hours after simulation start")
timing_ax.grid(True, axis="x", alpha=0.25)
timing_ax.text(STORM_DURATION_HOURS + 2, 1.0, "96-hour zero-rate tail", color=COLORS["red"], va="center")
fig.tight_layout()
plt.show()

7. QA/QC disposition and next step¶
This notebook establishes that the selected Atlas 14 depths are positive and spatially variable, depth increases with duration, the ABM preserves every grid-cell total, and the projected HEC-RAS forcing covers every mesh cell without changing storm depth. It does not prove that a particular plan consumed the data.
The pre-compute gold standard is a successfully created temporary plan HDF containing the expected rainfall arrays. The post-compute gold standard is the completed final plan HDF, supported by complete runtime-message review and visual inspection. Notebook 727 demonstrates both; notebook 729 provides a shorter GeoTIFF-to-solver example.
completion_checks = pd.Series(
{
"all stable 6.x releases expose global gridded precipitation": all(
capability_objects[v].global_gridded_supported for v in VERSIONS if v.startswith("6.")
),
"Atlas 14 subset is finite and positive": bool(np.isfinite(depth_24hr).all() and np.nanmin(depth_24hr) > 0.0),
"DDF depth increases at representative pixels": all(
np.all(np.diff([depth_grids[d][row, col] for d in DDF_DURATIONS]) > 0.0)
for row, col in representative_indices.values()
),
"ABM preserves Atlas 14 depth": float(abm_depth_error_in.max()) <= 1e-5,
"HEC-RAS conversion preserves depth": forcing.attrs["depth_conservation_max_error_mm"] <= 1e-4,
"forcing covers every mesh cell": int(np.isfinite(sampled_total_in.values).sum()) == len(mesh_cells),
"forcing covers the full plan window": times[0] == pd.Timestamp(SIM_START) and times[-1] == pd.Timestamp(SIM_END),
"post-storm forcing is zero": bool(np.all(post_storm_rate[np.isfinite(post_storm_rate)] == 0.0)),
},
name="passed",
).to_frame()
display(completion_checks)
assert completion_checks["passed"].all()
print("Atlas 14 forcing QA complete. Continue to notebook 727 for solver-facing validation.")
| passed | |
|---|---|
| all stable 6.x releases expose global gridded precipitation | True |
| Atlas 14 subset is finite and positive | True |
| DDF depth increases at representative pixels | True |
| ABM preserves Atlas 14 depth | True |
| HEC-RAS conversion preserves depth | True |
| forcing covers every mesh cell | True |
| forcing covers the full plan window | True |
| post-storm forcing is zero | True |
Atlas 14 forcing QA complete. Continue to notebook 727 for solver-facing validation.