Skip to content

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.

Python
# 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")
Text Only
LOCAL SOURCE MODE
Python
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}")
Text Only
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.

Python
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

png

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.

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

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

png

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.

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

png

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.

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

png

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.

Python
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
Text Only
Atlas 14 forcing QA complete. Continue to notebook 727 for solver-facing validation.