Skip to content

Austin Bayou SH 35: 2D breakout, NextGen conflation, boundary authoring, and validation

Reproduce a compact Austin Bayou “firehose” model at USGS 08078400. The example uses the public FEMA Austin–Oyster eBFE model and demonstrates four distinct tasks:

  1. qualify a contained 2D breakout from the FEMA parent;
  2. conflate the child domain against NextGen v2.2 flowpaths;
  3. author the two domain-restricted boundaries in an isolated copy; and
  4. validate the completed child against the parent model at the gauge.

The 4.6-square-mile child follows the connected 0.2% annual-chance floodplain plus 500 ft, cut about 0.5 mile upstream and 1 mile downstream of the gauge. It is a constant-flow diagnostic model—not a substitute for the watershed-preserving rain-on-mesh breakout. Tributaries inside the compact domain receive no inflow.

Reproducibility and engineering boundary

RasExamples downloads the completed 30 MB child model. Set RAS_COMMANDER_AUSTIN_OYSTER_PARENT to the organized parent Input folder to run the parent preflight and direct parent/child WSE comparison. The public parent can be organized with RasEbfeModels.organize_model("austin-oyster"), but that delivery is approximately 24 GB and is intentionally not downloaded automatically here.

The committed notebook is an engineering demonstration. Always review the geometry, boundary placement, HEC-RAS computation messages, continuity, hydrographs, and spatial results manually before using a breakout for analysis.

Python
from __future__ import annotations

import os
import shutil
import sys
from datetime import datetime, timedelta
from pathlib import Path

import geopandas as gpd
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import requests
from IPython.display import Markdown, display
from shapely.geometry import LineString, Point
from shapely.ops import substring, unary_union

REPO_ROOT = Path.cwd() if (Path.cwd() / "examples").is_dir() else Path.cwd().parent
sys.path.insert(0, str(REPO_ROOT))

from ras_commander import (
    Breakout2DSpec,
    GeomBcLines,
    HdfBndry,
    HdfMesh,
    HdfResultsMesh,
    RasBreakout2D,
    RasCmdr,
    RasExamples,
    RasNetworkConflation,
    RasPlan,
    RasPrj,
    RasUnsteady,
    init_ras_project,
    stage_project,
)

WORKING_DIR = REPO_ROOT / "working" / "example_959_austin_bayou"
WORKING_DIR.mkdir(parents=True, exist_ok=True)
plt.rcParams.update({"figure.dpi": 120, "axes.titlesize": 12})
pd.set_option("display.max_colwidth", 100)

GAUGE_ID = "08078400"
PARENT_VALUE = os.getenv("RAS_COMMANDER_AUSTIN_OYSTER_PARENT", "").strip()
PARENT_PROJECT = Path(PARENT_VALUE) if PARENT_VALUE else None

Load the completed RasExamples child

Python
override = os.getenv("RAS_COMMANDER_SH35_FIREHOSE_PROJECT", "").strip()
if override:
    CHILD_PROJECT = Path(override)
else:
    extracted = RasExamples.extract_project(
        "AustinBayouSH35Firehose",
        output_path=WORKING_DIR,
        suffix="959",
    )
    CHILD_PROJECT = (
        extracted / "AustinBayou_SH35_Firehose" / "RAS Model" / "Input"
    )

assert (CHILD_PROJECT / "AustinOyster.prj").is_file(), CHILD_PROJECT
child_ras = RasPrj()
init_ras_project(
    CHILD_PROJECT,
    "6.6",
    ras_object=child_ras,
    load_results_summary=False,
    hide_intro=True,
)

child_geometry_hdf = CHILD_PROJECT / "AustinOyster.g01.hdf"
child_plan_hdf = CHILD_PROJECT / "AustinOyster.p01.hdf"
child_unsteady = CHILD_PROJECT / "AustinOyster.u01"
child_mesh = HdfMesh.get_mesh_areas(child_geometry_hdf)
gauge = gpd.read_file(CHILD_PROJECT / "Features" / "USGS_08078400.shp").to_crs(
    child_mesh.crs
)
assert gauge.iloc[0]["site_no"] == GAUGE_ID

NEXTGEN_URL = (
    "https://ciroh-community-ngen-datastream.s3.amazonaws.com/"
    "resources/v2.2_hydrofabric/geopackages/VPU_12/nextgen_VPU_12.gpkg"
)
NEXTGEN_BYTES = 200_265_728
nextgen_path = Path(os.getenv(
    "RAS_COMMANDER_NEXTGEN_VPU12",
    WORKING_DIR / "nextgen_VPU_12_v2.2.gpkg",
))
if not nextgen_path.exists() or nextgen_path.stat().st_size != NEXTGEN_BYTES:
    partial = nextgen_path.with_suffix(".gpkg.part")
    with requests.get(NEXTGEN_URL, stream=True, timeout=120) as response:
        response.raise_for_status()
        with partial.open("wb") as stream:
            for chunk in response.iter_content(1024 * 1024):
                if chunk:
                    stream.write(chunk)
    if partial.stat().st_size != NEXTGEN_BYTES:
        raise OSError("Unexpected NextGen VPU 12 download size")
    partial.replace(nextgen_path)

query_bounds = child_mesh.to_crs(5070).buffer(5000).total_bounds
flowpaths = gpd.read_file(nextgen_path, layer="flowpaths", bbox=tuple(query_bounds))
divides = gpd.read_file(nextgen_path, layer="divides", bbox=tuple(query_bounds))
coverage = RasNetworkConflation.classify_edges(
    child_mesh.assign(geometry_id="AustinBayou-SH35"),
    flowpaths,
    adapter="nextgen",
    geometry_id_col="geometry_id",
    analysis_crs=child_mesh.crs,
    include_outside=False,
)

child_summary = pd.DataFrame(
    [{
        "plan": "p01 — SH35_FIREHOSE",
        "mesh": child_mesh.iloc[0]["mesh_name"],
        "domain_sq_mi": child_mesh.geometry.iloc[0].area / 5280**2,
        "cells": int(child_ras.plan_df.loc[0, "mesh_cell_count"]),
        "forcing": "inline constant-flow ramp; no precipitation",
        "result_hdf": child_plan_hdf.name,
    }]
)
display(child_summary.style.format({"domain_sq_mi": "{:.2f}"}))
  plan mesh domain_sq_mi cells forcing result_hdf
0 p01 — SH35_FIREHOSE Perimeter 1 4.58 3311 inline constant-flow ramp; no precipitation AustinOyster.p01.hdf

Inspect the completed mesh and result

The child uses FEMA’s retained cell centers and refinement. The maximum-depth result provides immediate visual confirmation that the downloaded example is a computed hydraulic model rather than a geometry-only fixture.

Python
max_depth = HdfResultsMesh.get_mesh_max_depth(child_plan_hdf)
bc_lines = HdfBndry.get_bc_lines(child_geometry_hdf)

fig, ax = plt.subplots(figsize=(10, 8))
wet = max_depth.loc[max_depth["maximum_depth"] > 0.05]
wet.plot(
    ax=ax,
    column="maximum_depth",
    cmap="Blues",
    markersize=5,
    legend=True,
    legend_kwds={"label": "Maximum depth (ft)", "shrink": 0.75},
)
child_mesh.boundary.plot(ax=ax, color="#111827", linewidth=1.8, label="child perimeter")
bc_lines.loc[bc_lines["Type"] == "External"].plot(
    ax=ax,
    color="#db2777",
    linewidth=3.0,
)
gauge.plot(ax=ax, color="#facc15", edgecolor="black", marker="*", markersize=180, zorder=5)
ax.set_title("Computed SH 35 firehose breakout — maximum depth and boundary lines", loc="left", weight="bold")
ax.set_axis_off()
plt.tight_layout()
plt.show()
Text Only
2026-09-26 14:29:15 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'Perimeter 1' in 'AustinOyster.p01.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.

png

Verify HEC-RAS native boundary-face ownership

HdfBndry.get_bc_external_faces() reads HEC-RAS’s own External Faces table. It is the authoritative check for which perimeter faces a BC line owns; geometric proximity to a drawn line is not sufficient. The completed source run has native ownership only for its downstream outlet. The recommended reach-level revision below replaces the source run’s interior inflow location with a wide upstream perimeter boundary.

Python
owned_faces = HdfBndry.get_bc_external_faces(
    child_geometry_hdf,
    include_geometry=True,
    validate_unique_faces=True,
)
face_summary = (
    owned_faces.groupby(["mesh_name", "bc_line_name"], dropna=False)
    .agg(face_count=("face_id", "size"), first_face=("face_id", "min"), last_face=("face_id", "max"))
    .reset_index()
)
assert owned_faces["face_id"].is_unique
assert set(face_summary["bc_line_name"]) == {"Outlet_DS"}
display(face_summary)

fig, ax = plt.subplots(figsize=(9, 7))
child_mesh.boundary.plot(ax=ax, color="#9ca3af", linewidth=1.0)
owned_faces.plot(ax=ax, color="#db2777", linewidth=4.0, label="Outlet_DS native faces")
gauge.plot(ax=ax, color="#facc15", edgecolor="black", marker="*", markersize=160)
ax.legend(loc="best")
ax.set_title("Native external-face ownership is unique and domain-restricted", loc="left", weight="bold")
ax.set_axis_off()
plt.tight_layout()
plt.show()
Text Only
2026-09-26 14:29:15 - ras_commander.hdf.HdfBndry - WARNING - Using native External Faces endpoints for 51 of 57 BC faces in mesh 'Perimeter 1' because their face IDs do not match current mesh topology in AustinOyster.g01.hdf.
mesh_name bc_line_name face_count first_face last_face
0 Perimeter 1 Outlet_DS 57 6242 7312

png

Build a wide upstream external boundary

For a reach-level breakout, inflow belongs on a wide external cut—not on an internal emitter. The highest-drainage-area NextGen edge identifies the principal channel. The modeled reach is explicitly selected from that longer network edge: 0.5 mile upstream and 1 mile downstream of the gauge. The complete selected reach must be contained by the 2D domain; plotting the entire network edge would incorrectly imply that off-domain upstream and downstream routing belongs in this child.

The principal edge's upstream intersection with the implemented child perimeter anchors a 3,000-foot boundary arc, wide enough to cover the active floodplain at the cut while remaining on the exterior ring.

The original project remains unchanged. The following cells delete its interior inflow line from an isolated geometry copy, add the new perimeter line, and attach the inflow hydrograph to that external boundary.

Python
coverage_ranked = coverage.coverage_df.sort_values(
    ["drainage_area", "inside_fraction"], ascending=False
)
main_edge_id = str(coverage_ranked.iloc[0]["edge_id"])
flowpaths_model = flowpaths.to_crs(child_mesh.crs)
main_edge = flowpaths_model.loc[
    flowpaths_model["id"].astype(str) == main_edge_id
].geometry.iloc[0]
gauge_station = main_edge.project(gauge.geometry.iloc[0])
selected_reach = substring(
    main_edge,
    max(0.0, gauge_station - 2640.0),
    min(main_edge.length, gauge_station + 5280.0),
)
assert child_mesh.geometry.iloc[0].buffer(1.0).contains(selected_reach)
outlet_line = bc_lines.loc[bc_lines["Name"] == "Outlet_DS"].geometry.iloc[0]
crossings = main_edge.intersection(child_mesh.boundary.iloc[0])
crossing_points = list(crossings.geoms) if hasattr(crossings, "geoms") else [crossings]
upstream_crossing = max(crossing_points, key=lambda point: point.distance(outlet_line))

perimeter = LineString(child_mesh.geometry.iloc[0].exterior.coords)
upstream_station = perimeter.project(upstream_crossing)
half_width = 1500.0
assert half_width < upstream_station < perimeter.length - half_width
upstream_external = substring(
    perimeter,
    upstream_station - half_width,
    upstream_station + half_width,
)
assert upstream_external.distance(child_mesh.boundary.iloc[0]) < 1e-6

recommended_bc_lines = gpd.GeoDataFrame(
    {"bc_line": ["Inflow_US", "Outlet_DS"], "role": ["inflow", "outflow"]},
    geometry=[upstream_external, outlet_line],
    crs=child_mesh.crs,
)

fig, ax = plt.subplots(figsize=(9, 7))
child_mesh.boundary.plot(ax=ax, color="#9ca3af", linewidth=1.0)
recommended_bc_lines.plot(
    ax=ax,
    color=["#2563eb", "#db2777"],
    linewidth=4.0,
)
gpd.GeoSeries([selected_reach], crs=child_mesh.crs).plot(
    ax=ax, color="#0f766e", linewidth=3.0
)
gauge.plot(ax=ax, color="#facc15", edgecolor="black", marker="*", markersize=160)
ax.set_title("Implemented 2D domain contains the selected NextGen reach", loc="left", weight="bold")
ax.set_axis_off()
plt.tight_layout()
plt.show()

png

Python
authoring_dir = WORKING_DIR / "boundary_authoring"
authoring_dir.mkdir(parents=True, exist_ok=True)
geometry_copy = authoring_dir / "AustinOyster.g01"
unsteady_copy = authoring_dir / "AustinOyster.u01"
shutil.copy2(CHILD_PROJECT / "AustinOyster.g01", geometry_copy)
shutil.copy2(child_unsteady, unsteady_copy)

GeomBcLines.delete_bc_line(geometry_copy, "Emitter1")
GeomBcLines.add_bc_lines(
    geometry_copy,
    lines=[{
        "name": "Inflow_US",
        "storage_area": "Perimeter 1",
        "coordinates": list(upstream_external.coords),
    }],
)

reset = RasUnsteady.replace_2d_boundary_locations(
    unsteady_copy,
    geometry_copy,
    [
        {"area_2d": "Perimeter 1", "bc_line": "Inflow_US"},
        {"area_2d": "Perimeter 1", "bc_line": "Outlet_DS"},
    ],
)
hydrograph = pd.DataFrame(
    {
        "hour": np.arange(14, dtype=float),
        "value": [0, 1440, 2880, 4320, 5760, 7200, 8640, 8640, 8640, 8640, 8640, 8640, 8640, 8640],
    }
)
assert RasUnsteady.set_boundary_inline_hydrograph(
    unsteady_copy,
    hydrograph,
    bc_type="Flow Hydrograph",
    area_2d="Perimeter 1",
    bc_line="Inflow_US",
)
flow_slope = RasUnsteady.set_flow_hydrograph_slope(
    unsteady_copy,
    eg_slope=0.000362,
    area_2d="Perimeter 1",
    bc_line="Inflow_US",
)
normal_depth = RasUnsteady.set_normal_depth_boundary(
    unsteady_copy,
    0.000362,
    area_2d="Perimeter 1",
    bc_line="Outlet_DS",
)
authored = RasUnsteady.extract_boundary_and_tables(
    unsteady_copy,
    ras_object=child_ras,
)
boundary_review = authored[["Storage Area Name", "Blank 1", "Tables"]].rename(
    columns={"Storage Area Name": "area_2d", "Blank 1": "bc_line"}
)
boundary_review["boundary_type"] = ["Flow Hydrograph", "Normal Depth"]
boundary_review["setting"] = ["peak = 8,640 cfs", "slope = 0.000362"]
display(boundary_review.drop(columns="Tables"))
assert set(boundary_review["bc_line"]) == {"Inflow_US", "Outlet_DS"}
assert len(boundary_review.iloc[0]["Tables"]["Flow Hydrograph"]) == 14
assert normal_depth["new_friction_slope"] == 0.000362
assert flow_slope["new_eg_slope"] == 0.000362
Text Only
2026-09-26 14:29:16 - ras_commander.geom.GeomBcLines - INFO - Deleted BC line Emitter1 from AustinOyster.g01 (8 lines)


2026-09-26 14:29:16 - ras_commander.geom.GeomBcLines - INFO - Added 1 BC line(s) to AustinOyster.g01 (replaced=0)


2026-09-26 14:29:16 - ras_commander.RasUnsteady - INFO - Replaced 2 2D boundary block(s) with 2 geometry-backed location(s) in AustinOyster.u01


2026-09-26 14:29:16 - ras_commander.RasUnsteady - INFO - Updated Flow Hydrograph inline hydrograph in AustinOyster.u01: 14 values, interval=1HOUR, peak=8640.00


2026-09-26 14:29:16 - ras_commander.RasUnsteady - INFO - Set Flow Hydrograph Slope in AustinOyster.u01: matched=,                ,        ,        ,                ,Perimeter 1     ,                ,Inflow_US, slope=0.000362, updated_in_place=False, anchor=Use DSS=


2026-09-26 14:29:16 - ras_commander.RasUnsteady - INFO - Set Normal Depth boundary in AustinOyster.u01: matched=,                ,        ,        ,                ,Perimeter 1     ,                ,Outlet_DS, slope=0.000362, flag=omitted, removed=0, inserted=1, updated_in_place=False


2026-09-26 14:29:16 - ras_commander.RasUnsteady - INFO - Successfully extracted boundaries and tables from C:\Users\bill\.config\superpowers\worktrees\ras-commander\pr388-austin-bayou\working\example_959_austin_bayou\boundary_authoring\AustinOyster.u01
area_2d bc_line boundary_type setting
0 Perimeter 1 Inflow_US Flow Hydrograph peak = 8,640 cfs
1 Perimeter 1 Outlet_DS Normal Depth slope = 0.000362

Conflate the 2D domain to NextGen v2.2

A pure 2D model has no authoritative HEC-RAS river centerline or cross sections. For that case, classify_edges() is the correct extent-first conflation API: it reports every NextGen edge inside or crossing the child, without pretending there is a single exact reach match. The gauge remains an independent review point.

Python
display(
    coverage.coverage_df[
        ["edge_id", "extent_status", "inside_fraction", "stream_order", "drainage_area"]
    ].sort_values(["extent_status", "inside_fraction"], ascending=[True, False])
)
edge_id extent_status inside_fraction stream_order drainage_area
0 wb-2414043 partial 0.655512 2.0 113.377948
1 wb-2414058 partial 0.441944 1.0 11.585700
2 wb-2414059 partial 0.296596 1.0 4.982401
3 wb-2414057 partial 0.008324 1.0 9.015750
Python
divides_model = divides.to_crs(child_mesh.crs)
accepted_ids = set(coverage.coverage_df["edge_id"].astype(str))
accepted = flowpaths_model.loc[flowpaths_model["id"].astype(str).isin(accepted_ids)]

fig, ax = plt.subplots(figsize=(10, 8))
divides_model.boundary.plot(ax=ax, color="#c7d2fe", linewidth=0.5, alpha=0.7)
flowpaths_model.plot(ax=ax, color="#bfdbfe", linewidth=1.0)
accepted.plot(ax=ax, color="#2563eb", linewidth=3.0, label="inside/partial NextGen edge")
child_mesh.boundary.plot(ax=ax, color="#111827", linewidth=2.0, label="SH 35 child domain")
recommended_bc_lines.plot(ax=ax, color=["#2563eb", "#db2777"], linewidth=3.0)
gauge.plot(ax=ax, color="#facc15", edgecolor="black", marker="*", markersize=180, zorder=6)
xmin, ymin, xmax, ymax = child_mesh.total_bounds
pad = 1000
ax.set(xlim=(xmin - pad, xmax + pad), ylim=(ymin - pad, ymax + pad), aspect="equal")
ax.legend(loc="best")
ax.set_title("NextGen coverage of the domain-restricted SH 35 breakout", loc="left", weight="bold")
ax.set_axis_off()
plt.tight_layout()
plt.show()

png

Optional parent breakout preflight

When the organized parent is available, this cell proves that the exact child perimeter is contained, that the parent is a pure 2D unsteady plan, and that its unrelated 2D connection is safely classified for removal because it lies wholly outside the child. Connections touching the child—or connections with gates, culverts, or unverified extents—remain blocking.

Python
parent_ras = None
preflight = None
if PARENT_PROJECT is None:
    display(Markdown(
        "Parent preflight skipped. Set `RAS_COMMANDER_AUSTIN_OYSTER_PARENT` "
        "to the organized Austin–Oyster `Input` folder to enable it."
    ))
else:
    parent_ras = RasPrj()
    init_ras_project(
        PARENT_PROJECT,
        "5.0.7",
        ras_object=parent_ras,
        load_results_summary=False,
        hide_intro=True,
    )
    preflight = RasBreakout2D.preflight(
        Breakout2DSpec(
            source_plan="08",
            source_2d_area="Perimeter 1",
            child_boundary=child_mesh,
            breakout_id="AustinBayou-SH35-firehose",
        ),
        ras_object=parent_ras,
    )
    assert preflight.is_ready, preflight.blocking_issues
    display(preflight.checks[["check_id", "passed", "blocking", "message"]])
    display(
        preflight.feature_actions.groupby(["feature_type", "action"])
        .size().rename("count").reset_index()
    )
Text Only
2026-09-26 14:29:17 - ras_commander.RasPrj - WARNING - HEC-RAS 5.0.7 Terms & Conditions for Use have NOT been accepted for the current Windows user. The first headless/COM launch will block on a modal "Terms and Conditions for Use" dialog. Open HEC-RAS 5.0.7 in the GUI and click "I Agree" for that exact installed release. Terms: https://www.hec.usace.army.mil/software/hec-ras/


2026-09-26 14:29:25 - ras_commander.RasBreakout2D - INFO - 2D breakout preflight AustinBayou-SH35-firehose: ready=True, features=1533
check_id passed blocking message
0 pure_2d_plan True True Source plan must be classified as valid unsteady pure 2D
1 single_2d_flow_area True True Initial breakout preparation requires exactly one 2D flow area
2 unsupported_structures_absent True True Child must exclude all structures; only verified external plain 2D connections may be dropped
3 child_within_parent True True Child boundary must be contained by the parent 2D area
4 boundary_partition_closes True True Inherited and artificial segments must close the child perimeter
5 reference_points_do_not_require_trim True True Reference points requiring trim are outside the initial implementation
feature_type action count
0 bc_line preserve 60
1 breakline clip 9
2 breakline drop 1347
3 breakline keep 4
4 mesh_area replace 1
5 refinement_region drop 44
6 sa_2d_connection drop 1
7 unsteady_boundary preserve 67

Establish the 2D domain from the reach and parent inundation

Domain design begins with the selected NextGen reach—not with a pre-existing child polygon. Parent plan 08 supplies the hydraulic envelope. Wet parent cells (maximum depth > 0.1 ft) within a flat-ended 1,000-ft reach corridor are converted to connected 200-ft cell-support areas. The minimum evidence envelope is the union of that connected parent inundation and a flat-ended 500-ft reach corridor, expanded by 100 ft. The completed domain deliberately exceeds that minimum.

The completed example domain is then checked against that evidence. It must contain the entire selected reach and the minimum parent-result envelope. These are transparent screening distances for the example; production values should reflect terrain, expected flow range, tributary treatment, and mesh-transition needs.

Python
if preflight is None:
    raise RuntimeError(
        "Domain establishment requires RAS_COMMANDER_AUSTIN_OYSTER_PARENT "
        "so the parent inundation result can define the hydraulic envelope."
    )

parent_plan_hdf = PARENT_PROJECT / "AustinOyster.p08.hdf"
parent_depth = HdfResultsMesh.get_mesh_max_depth(parent_plan_hdf).to_crs(child_mesh.crs)
reach_search = selected_reach.buffer(1000.0, cap_style="flat")
xmin, ymin, xmax, ymax = reach_search.bounds
parent_near = parent_depth.cx[xmin:xmax, ymin:ymax]
parent_near = parent_near.loc[
    (parent_near["maximum_depth"] > 0.1)
    & parent_near.geometry.within(reach_search)
].copy()

wet_support = unary_union(parent_near.geometry.buffer(100.0))
wet_components = list(wet_support.geoms) if hasattr(wet_support, "geoms") else [wet_support]
connected_floodplain = unary_union([
    component for component in wet_components
    if component.intersects(selected_reach.buffer(300.0, cap_style="flat"))
])
minimum_domain = unary_union([
    connected_floodplain,
    selected_reach.buffer(500.0, cap_style="flat"),
]).buffer(100.0).simplify(25.0)

implemented_domain = child_mesh.geometry.iloc[0]
assert implemented_domain.buffer(1.0).contains(selected_reach)
assert implemented_domain.buffer(1.0).contains(minimum_domain)
domain_evidence = pd.DataFrame([{
    "selected_reach_miles": selected_reach.length / 5280.0,
    "parent_wet_samples": len(parent_near),
    "minimum_envelope_sq_mi": minimum_domain.area / 5280**2,
    "implemented_domain_sq_mi": implemented_domain.area / 5280**2,
    "reach_fully_contained": implemented_domain.buffer(1.0).contains(selected_reach),
    "parent_envelope_contained": implemented_domain.buffer(1.0).contains(minimum_domain),
}])
display(domain_evidence.style.format(precision=2))

fig, axes = plt.subplots(1, 2, figsize=(15, 7))
parent_near.plot(
    ax=axes[0], column="maximum_depth", cmap="Blues", markersize=7,
    legend=True, legend_kwds={"label": "Parent maximum depth (ft)", "shrink": 0.72},
)
gpd.GeoSeries([selected_reach.buffer(500.0, cap_style="flat")], crs=child_mesh.crs).boundary.plot(
    ax=axes[0], color="#f59e0b", linewidth=2.0, linestyle="--",
)
gpd.GeoSeries([selected_reach], crs=child_mesh.crs).plot(
    ax=axes[0], color="#0f766e", linewidth=3.0,
)
axes[0].set_title("Inputs: selected reach, corridor, and parent inundation", loc="left", weight="bold")

gpd.GeoSeries([implemented_domain], crs=child_mesh.crs).boundary.plot(
    ax=axes[1], color="#111827", linewidth=2.2, label="implemented 2D domain",
)
gpd.GeoSeries([minimum_domain], crs=child_mesh.crs).boundary.plot(
    ax=axes[1], color="#7c3aed", linewidth=2.5, linestyle="--", label="minimum parent-result envelope",
)
gpd.GeoSeries([selected_reach], crs=child_mesh.crs).plot(
    ax=axes[1], color="#0f766e", linewidth=3.5, label="selected NextGen reach",
)
gpd.GeoSeries([Point(selected_reach.coords[0]), Point(selected_reach.coords[-1])], crs=child_mesh.crs).plot(
    ax=axes[1], color=["#2563eb", "#db2777"], markersize=90, zorder=6,
)
axes[1].legend(loc="best")
axes[1].set_title("Result: domain is larger than the complete selected reach", loc="left", weight="bold")

sxmin, symin, sxmax, symax = reach_search.bounds
axes[0].set(xlim=(sxmin - 300, sxmax + 300), ylim=(symin - 300, symax + 300), aspect="equal")
rxmin, rymin, rxmax, rymax = implemented_domain.bounds
axes[1].set(xlim=(rxmin - 500, rxmax + 500), ylim=(rymin - 500, rymax + 500), aspect="equal")
for ax in axes:
    ax.set_axis_off()
plt.tight_layout()
plt.show()
Text Only
2026-09-26 14:29:29 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'Perimeter 1' in 'AustinOyster.p08.hdf': stored HEC-RAS HDF 'Depth' time series (read only).
  selected_reach_miles parent_wet_samples minimum_envelope_sq_mi implemented_domain_sq_mi reach_fully_contained parent_envelope_contained
0 1.50 551 0.41 4.58 True True

png

Derive a boundary flow envelope and preliminary stage relationship

The parent result supplies the hydraulic context at both child cuts. Native parent-face fluxes within 50 ft of each proposed boundary are summed with the correct outward-flow sign. The upstream series defines the tested flow envelope. At the outlet, the paired parent discharge and water surface are binned into a preliminary monotonic stage–flow relationship for the child runs.

This is a screening relationship, not a surveyed or calibrated rating curve. Review boundary orientation, selected faces, extrapolation, and tailwater sensitivity before relying on it.

Python
if preflight is None:
    raise RuntimeError(
        "This executed workflow requires RAS_COMMANDER_AUSTIN_OYSTER_PARENT "
        "so its boundary fluxes can define the flow ladder."
    )

flux_review = RasBreakout2D.review_parent_boundary_flux(
    preflight,
    minimum_peak_flow=0,
    minimum_volume_fraction=0,
)

def boundary_face_selection(line, tolerance=50.0):
    selected = flux_review.faces.loc[
        flux_review.faces.geometry.distance(line) <= tolerance
    ].copy()
    if selected.empty:
        raise ValueError("No parent faces were found at the proposed child boundary")
    return selected

upstream_faces = boundary_face_selection(upstream_external)
outlet_faces = boundary_face_selection(outlet_line)
upstream_signed = flux_review.face_flow_outward[
    upstream_faces["face_id"].tolist()
].sum(axis=1)
upstream_flow = (
    -upstream_signed if abs(upstream_signed.min()) >= abs(upstream_signed.max())
    else upstream_signed
).clip(lower=0)
outlet_flow = flux_review.face_flow_outward[
    outlet_faces["face_id"].tolist()
].sum(axis=1).clip(lower=0)

parent_plan_hdf = PARENT_PROJECT / "AustinOyster.p08.hdf"
outlet_midpoint = outlet_line.interpolate(0.5, normalized=True)
outlet_cell = int(
    outlet_faces.loc[
        outlet_faces.geometry.distance(outlet_midpoint).idxmin(), "inside_cell"
    ]
)
outlet_stage_values = HdfResultsMesh.get_mesh_timeseries(
    parent_plan_hdf,
    "Perimeter 1",
    "Water Surface",
    truncate=False,
    spatial_selection=outlet_cell,
).to_numpy().squeeze()
outlet_stage = pd.Series(outlet_stage_values, index=outlet_flow.index, name="stage_ft")

upstream_peak_time = upstream_flow.idxmax()
outlet_peak_time = outlet_flow.idxmax()
upstream_faces["face_flux_cfs"] = flux_review.face_flow_outward.loc[
    upstream_peak_time, upstream_faces["face_id"]
].abs().to_numpy()
outlet_faces["face_flux_cfs"] = flux_review.face_flow_outward.loc[
    outlet_peak_time, outlet_faces["face_id"]
].abs().to_numpy()

paired = pd.DataFrame({"flow_cfs": outlet_flow, "stage_ft": outlet_stage}).dropna()
paired = paired.loc[paired["flow_cfs"] > 10].sort_values("flow_cfs")
paired["flow_bin"] = pd.cut(paired["flow_cfs"], bins=8, duplicates="drop")
rating_curve = (
    paired.groupby("flow_bin", observed=True)
    .agg(flow_cfs=("flow_cfs", "median"), stage_ft=("stage_ft", "median"))
    .dropna()
    .sort_values("flow_cfs")
    .reset_index(drop=True)
)
rating_curve["stage_ft"] = rating_curve["stage_ft"].cummax()

envelope_ceiling = int(np.ceil(upstream_flow.max() / 1000.0) * 1000)
flow_ladder = np.arange(1000, envelope_ceiling + 1, 1000, dtype=int)
ladder = pd.DataFrame({"flow_cfs": flow_ladder})
ladder["tailwater_stage_ft"] = np.interp(
    ladder["flow_cfs"],
    rating_curve["flow_cfs"],
    rating_curve["stage_ft"],
)

boundary_summary = pd.DataFrame([
    {
        "boundary": "Inflow_US",
        "parent_faces": len(upstream_faces),
        "peak_parent_flow_cfs": upstream_flow.max(),
        "flow_ladder_min_cfs": flow_ladder.min(),
        "flow_ladder_max_cfs": flow_ladder.max(),
    },
    {
        "boundary": "Outlet_DS",
        "parent_faces": len(outlet_faces),
        "peak_parent_flow_cfs": outlet_flow.max(),
        "flow_ladder_min_cfs": np.nan,
        "flow_ladder_max_cfs": np.nan,
    },
])
display(boundary_summary.style.format(precision=1))
display(ladder.style.format({"tailwater_stage_ft": "{:.3f}"}))

fig, axes = plt.subplots(1, 2, figsize=(14, 6))
for ax, selected, boundary, title, direction in [
    (axes[0], upstream_faces, upstream_external, "Upstream cut — parent flux enters child", "in"),
    (axes[1], outlet_faces, outlet_line, "Downstream cut — parent flux leaves child", "out"),
]:
    child_mesh.boundary.plot(ax=ax, color="#94a3b8", linewidth=1.2)
    selected.plot(
        ax=ax,
        column="face_flux_cfs",
        cmap="viridis",
        linewidth=5,
        legend=True,
        legend_kwds={"label": "Absolute face flux at boundary peak (cfs)", "shrink": 0.72},
    )
    gpd.GeoSeries([boundary], crs=child_mesh.crs).plot(
        ax=ax, color="#f43f5e", linewidth=2.2, linestyle="--"
    )
    center = child_mesh.geometry.iloc[0].centroid
    arrow_faces = selected.iloc[np.linspace(0, len(selected) - 1, min(6, len(selected))).astype(int)]
    for face in arrow_faces.geometry:
        point = face.interpolate(0.5, normalized=True)
        dx, dy = center.x - point.x, center.y - point.y
        length = np.hypot(dx, dy)
        dx, dy = dx / length * 250, dy / length * 250
        if direction == "out":
            dx, dy = -dx, -dy
        ax.arrow(point.x, point.y, dx, dy, width=14, head_width=75, color="#111827", zorder=6)
    xmin, ymin, xmax, ymax = selected.total_bounds
    pad = 600
    ax.set(xlim=(xmin - pad, xmax + pad), ylim=(ymin - pad, ymax + pad), aspect="equal")
    ax.set_title(title, loc="left", weight="bold")
    ax.set_axis_off()
fig.suptitle("Proposed child boundaries and contributing parent-model faces", fontsize=15, weight="bold")
plt.tight_layout()
plt.show()

fig, axes = plt.subplots(1, 2, figsize=(12, 4.5))
axes[0].plot(upstream_flow.index, upstream_flow, color="#2563eb", linewidth=2)
for flow in flow_ladder:
    axes[0].axhline(flow, color="#93c5fd", linewidth=0.7, alpha=0.8)
axes[0].set(title="Parent inflow envelope and selected ladder", ylabel="Flow (cfs)", xlabel="Time")
axes[0].grid(alpha=0.2)

axes[1].scatter(paired["flow_cfs"], paired["stage_ft"], s=18, alpha=0.35, color="#64748b", label="parent samples")
axes[1].plot(rating_curve["flow_cfs"], rating_curve["stage_ft"], "o-", color="#db2777", linewidth=2, label="preliminary curve")
axes[1].scatter(ladder["flow_cfs"], ladder["tailwater_stage_ft"], marker="s", color="#111827", label="ladder stages")
axes[1].set(title="Outlet stage–flow relationship", xlabel="Flow (cfs)", ylabel="Water surface (ft)")
axes[1].legend()
axes[1].grid(alpha=0.2)
plt.tight_layout()
plt.show()
  boundary parent_faces peak_parent_flow_cfs flow_ladder_min_cfs flow_ladder_max_cfs
0 Inflow_US 22 6829.2 1000.0 7000.0
1 Outlet_DS 77 8122.3 nan nan
  flow_cfs tailwater_stage_ft
0 1000 21.379
1 2000 21.379
2 3000 21.455
3 4000 21.712
4 5000 22.033
5 6000 22.341
6 7000 22.633

png

png

Build and compute one plan per flow

The completed fixture is staged into a disposable project. Its internal inflow line is removed, the wide external boundary is authored, and HEC-RAS regenerates the geometry HDF from the edited geometry text. Each flow gets a separate 48-hour plan. The inflow ramps over four hours and then remains at its target for a 44-hour plateau; the outlet receives the stage interpolated from the preliminary parent relationship. The long plateau allows the compact domain to approach a quasi-steady response before the final map is evaluated.

Python
ladder_root = WORKING_DIR / "flow_ladder_model"
if ladder_root.exists():
    shutil.rmtree(ladder_root)
ladder_root.mkdir(parents=True)
stage_project(CHILD_PROJECT, ladder_root / "Input")
ladder_project = ladder_root / "Input"
terrain_source = CHILD_PROJECT.parent / "Terrain"
if terrain_source.is_dir():
    shutil.copytree(terrain_source, ladder_root / "Terrain")

ladder_ras = RasPrj()
init_ras_project(
    ladder_project,
    "6.6",
    ras_object=ladder_ras,
    load_results_summary=False,
    hide_intro=True,
)
ladder_geom = ladder_project / "AustinOyster.g01"
GeomBcLines.delete_bc_line(ladder_geom, "Emitter1")
GeomBcLines.add_bc_lines(
    ladder_geom,
    lines=[{
        "name": "Inflow_US",
        "storage_area": "Perimeter 1",
        "coordinates": list(upstream_external.coords),
    }],
)

plan_rows = []
for index, row in ladder.iterrows():
    flow = int(row["flow_cfs"])
    stage = float(row["tailwater_stage_ft"])
    if index == 0:
        unsteady_number = "01"
        plan_number = "01"
    else:
        unsteady_number = RasPlan.clone_unsteady(
            "01", new_title=f"Flow {flow} cfs", ras_object=ladder_ras
        )
        plan_number = RasPlan.clone_plan(
            "01",
            new_plan_shortid=f"Q{flow}",
            new_title=f"Flow {flow} cfs",
            geometry="01",
            unsteady_flow=unsteady_number,
            ras_object=ladder_ras,
        )

    simulation_start = datetime(2000, 1, 1, 0, 0)
    RasPlan.update_simulation_date(
        plan_number,
        simulation_start,
        simulation_start + timedelta(hours=48),
        ras_object=ladder_ras,
    )

    unsteady_path = ladder_project / f"AustinOyster.u{unsteady_number}"
    RasUnsteady.replace_2d_boundary_locations(
        unsteady_path,
        ladder_geom,
        [
            {"area_2d": "Perimeter 1", "bc_line": "Inflow_US"},
            {"area_2d": "Perimeter 1", "bc_line": "Outlet_DS"},
        ],
    )
    hours = np.arange(49, dtype=float)
    inflow_values = np.r_[np.linspace(0, flow, 5), np.repeat(flow, 44)]
    RasUnsteady.set_boundary_inline_hydrograph(
        unsteady_path,
        pd.DataFrame({"hour": hours, "value": inflow_values}),
        bc_type="Flow Hydrograph",
        area_2d="Perimeter 1",
        bc_line="Inflow_US",
    )
    RasUnsteady.set_flow_hydrograph_slope(
        unsteady_path,
        eg_slope=0.000362,
        area_2d="Perimeter 1",
        bc_line="Inflow_US",
    )
    RasUnsteady.set_boundary_inline_hydrograph(
        unsteady_path,
        pd.DataFrame({"hour": hours, "value": np.repeat(stage, len(hours))}),
        bc_type="Stage Hydrograph",
        area_2d="Perimeter 1",
        bc_line="Outlet_DS",
    )
    plan_rows.append({
        "plan_number": plan_number,
        "unsteady_number": unsteady_number,
        "flow_cfs": flow,
        "tailwater_stage_ft": stage,
    })

plan_manifest = pd.DataFrame(plan_rows)
source_geometry_hdf = ladder_project / "AustinOyster.g01.hdf"
if source_geometry_hdf.exists():
    source_geometry_hdf.rename(ladder_project / "AustinOyster.g01.source.hdf")
display(plan_manifest.style.format({"tailwater_stage_ft": "{:.3f}"}))

fig, ax_flow = plt.subplots(figsize=(11, 5))
for flow in plan_manifest["flow_cfs"]:
    imposed = np.r_[np.linspace(0, flow, 5), np.repeat(flow, 44)]
    ax_flow.plot(hours, imposed, linewidth=1.7, label=f"{flow:,} cfs")
ax_flow.axvspan(4, 48, color="#dbeafe", alpha=0.45, label="44-hour plateau")
ax_flow.set(xlabel="Simulation hour", ylabel="External inflow (cfs)", title="Imposed flow ladder hydrographs")
ax_flow.grid(alpha=0.2)
ax_flow.legend(ncol=4, loc="lower right")
plt.tight_layout()
plt.show()
Text Only
2026-09-26 14:30:00 - ras_commander.RasPrj - WARNING - HEC-RAS 5.07 Terms & Conditions for Use have NOT been accepted for the current Windows user. The first headless/COM launch will block on a modal "Terms and Conditions for Use" dialog. Open HEC-RAS 5.07 in the GUI and click "I Agree" for that exact installed release. Terms: https://www.hec.usace.army.mil/software/hec-ras/


2026-09-26 14:30:00 - ras_commander.RasProject - INFO - Project stage 55664f74-4912-4483-a5f7-017cf1494f85 published AustinOyster.prj: files=30 bytes=4606470 source=6605fc4dc435 copy=6605fc4dc435 readiness=ready states={'available': 39, 'missing': 10}


2026-09-26 14:30:00 - ras_commander.geom.GeomBcLines - INFO - Deleted BC line Emitter1 from AustinOyster.g01 (8 lines)


2026-09-26 14:30:00 - ras_commander.geom.GeomBcLines - INFO - Added 1 BC line(s) to AustinOyster.g01 (replaced=0)


2026-09-26 14:30:01 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: AustinOyster.p01


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Replaced 2 2D boundary block(s) with 2 geometry-backed location(s) in AustinOyster.u01


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Updated Flow Hydrograph inline hydrograph in AustinOyster.u01: 49 values, interval=1HOUR, peak=1000.00


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Set Flow Hydrograph Slope in AustinOyster.u01: matched=,                ,        ,        ,                ,Perimeter 1     ,                ,Inflow_US, slope=0.000362, updated_in_place=False, anchor=Use DSS=


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Updated Stage Hydrograph inline hydrograph in AustinOyster.u01: 49 values, interval=1HOUR, peak=21.38


2026-09-26 14:30:01 - ras_commander.RasPlan - INFO - Set geometry for plan p02 to g01


2026-09-26 14:30:01 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: AustinOyster.p02


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Replaced 2 2D boundary block(s) with 2 geometry-backed location(s) in AustinOyster.u02


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Updated Flow Hydrograph inline hydrograph in AustinOyster.u02: 49 values, interval=1HOUR, peak=2000.00


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Set Flow Hydrograph Slope in AustinOyster.u02: matched=,                ,        ,        ,                ,Perimeter 1     ,                ,Inflow_US, slope=0.000362, updated_in_place=False, anchor=Use DSS=


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Updated Stage Hydrograph inline hydrograph in AustinOyster.u02: 49 values, interval=1HOUR, peak=21.38


2026-09-26 14:30:01 - ras_commander.RasPlan - INFO - Set geometry for plan p03 to g01


2026-09-26 14:30:01 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: AustinOyster.p03


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Replaced 2 2D boundary block(s) with 2 geometry-backed location(s) in AustinOyster.u03


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Updated Flow Hydrograph inline hydrograph in AustinOyster.u03: 49 values, interval=1HOUR, peak=3000.00


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Set Flow Hydrograph Slope in AustinOyster.u03: matched=,                ,        ,        ,                ,Perimeter 1     ,                ,Inflow_US, slope=0.000362, updated_in_place=False, anchor=Use DSS=


2026-09-26 14:30:01 - ras_commander.RasUnsteady - INFO - Updated Stage Hydrograph inline hydrograph in AustinOyster.u03: 49 values, interval=1HOUR, peak=21.46


2026-09-26 14:30:02 - ras_commander.RasPlan - INFO - Set geometry for plan p04 to g01


2026-09-26 14:30:02 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: AustinOyster.p04


2026-09-26 14:30:02 - ras_commander.RasUnsteady - INFO - Replaced 2 2D boundary block(s) with 2 geometry-backed location(s) in AustinOyster.u04


2026-09-26 14:30:02 - ras_commander.RasUnsteady - INFO - Updated Flow Hydrograph inline hydrograph in AustinOyster.u04: 49 values, interval=1HOUR, peak=4000.00


2026-09-26 14:30:02 - ras_commander.RasUnsteady - INFO - Set Flow Hydrograph Slope in AustinOyster.u04: matched=,                ,        ,        ,                ,Perimeter 1     ,                ,Inflow_US, slope=0.000362, updated_in_place=False, anchor=Use DSS=


2026-09-26 14:30:02 - ras_commander.RasUnsteady - INFO - Updated Stage Hydrograph inline hydrograph in AustinOyster.u04: 49 values, interval=1HOUR, peak=21.71


2026-09-26 14:30:02 - ras_commander.RasPlan - INFO - Set geometry for plan p05 to g01


2026-09-26 14:30:02 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: AustinOyster.p05


2026-09-26 14:30:02 - ras_commander.RasUnsteady - INFO - Replaced 2 2D boundary block(s) with 2 geometry-backed location(s) in AustinOyster.u05


2026-09-26 14:30:02 - ras_commander.RasUnsteady - INFO - Updated Flow Hydrograph inline hydrograph in AustinOyster.u05: 49 values, interval=1HOUR, peak=5000.00


2026-09-26 14:30:02 - ras_commander.RasUnsteady - INFO - Set Flow Hydrograph Slope in AustinOyster.u05: matched=,                ,        ,        ,                ,Perimeter 1     ,                ,Inflow_US, slope=0.000362, updated_in_place=False, anchor=Use DSS=


2026-09-26 14:30:02 - ras_commander.RasUnsteady - INFO - Updated Stage Hydrograph inline hydrograph in AustinOyster.u05: 49 values, interval=1HOUR, peak=22.03


2026-09-26 14:30:03 - ras_commander.RasPlan - INFO - Set geometry for plan p06 to g01


2026-09-26 14:30:03 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: AustinOyster.p06


2026-09-26 14:30:03 - ras_commander.RasUnsteady - INFO - Replaced 2 2D boundary block(s) with 2 geometry-backed location(s) in AustinOyster.u06


2026-09-26 14:30:03 - ras_commander.RasUnsteady - INFO - Updated Flow Hydrograph inline hydrograph in AustinOyster.u06: 49 values, interval=1HOUR, peak=6000.00


2026-09-26 14:30:03 - ras_commander.RasUnsteady - INFO - Set Flow Hydrograph Slope in AustinOyster.u06: matched=,                ,        ,        ,                ,Perimeter 1     ,                ,Inflow_US, slope=0.000362, updated_in_place=False, anchor=Use DSS=


2026-09-26 14:30:03 - ras_commander.RasUnsteady - INFO - Updated Stage Hydrograph inline hydrograph in AustinOyster.u06: 49 values, interval=1HOUR, peak=22.34


2026-09-26 14:30:03 - ras_commander.RasPlan - INFO - Set geometry for plan p07 to g01


2026-09-26 14:30:03 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: AustinOyster.p07


2026-09-26 14:30:03 - ras_commander.RasUnsteady - INFO - Replaced 2 2D boundary block(s) with 2 geometry-backed location(s) in AustinOyster.u07


2026-09-26 14:30:03 - ras_commander.RasUnsteady - INFO - Updated Flow Hydrograph inline hydrograph in AustinOyster.u07: 49 values, interval=1HOUR, peak=7000.00


2026-09-26 14:30:03 - ras_commander.RasUnsteady - INFO - Set Flow Hydrograph Slope in AustinOyster.u07: matched=,                ,        ,        ,                ,Perimeter 1     ,                ,Inflow_US, slope=0.000362, updated_in_place=False, anchor=Use DSS=


2026-09-26 14:30:03 - ras_commander.RasUnsteady - INFO - Updated Stage Hydrograph inline hydrograph in AustinOyster.u07: 49 values, interval=1HOUR, peak=22.63
  plan_number unsteady_number flow_cfs tailwater_stage_ft
0 01 01 1000 21.379
1 02 02 2000 21.379
2 03 03 3000 21.455
3 04 04 4000 21.712
4 05 05 5000 22.033
5 06 06 6000 22.341
6 07 07 7000 22.633

png

Python
compute_rows = []
depth_results = {}
for index, row in plan_manifest.iterrows():
    plan_number = str(row["plan_number"])
    result = RasCmdr.compute_plan(
        plan_number,
        ras_object=ladder_ras,
        clear_geompre=(index == 0),
        force_rerun=True,
        verify=True,
        max_runtime=900,
    )
    plan_hdf = ladder_project / f"AustinOyster.p{plan_number}.hdf"
    depth = HdfResultsMesh.get_mesh_max_depth(plan_hdf)
    wet = depth.loc[depth["maximum_depth"] > 0.05].copy()
    gauge_point = gauge.to_crs(depth.crs).geometry.iloc[0]
    gauge_cell = int(depth.loc[depth.geometry.distance(gauge_point).idxmin(), "cell_id"])
    gauge_ws = HdfResultsMesh.get_mesh_timeseries(
        plan_hdf,
        "Perimeter 1",
        "Water Surface",
        truncate=False,
        spatial_selection=gauge_cell,
    ).to_numpy().squeeze()
    final_window = gauge_ws[np.isfinite(gauge_ws)][-13:]
    depth_results[int(row["flow_cfs"])] = wet
    compute_rows.append({
        "plan": f"p{plan_number}",
        "flow_cfs": int(row["flow_cfs"]),
        "completed": bool(result.success),
        "verified": bool(result.completion_verified),
        "wet_cells": len(wet),
        "maximum_depth_ft": float(depth["maximum_depth"].max()),
        "final_12h_ws_range_ft": float(np.ptp(final_window)),
        "final_1h_ws_change_ft": float(abs(final_window[-1] - final_window[-2])),
    })

compute_summary = pd.DataFrame(compute_rows)
assert compute_summary["completed"].all()
assert compute_summary["verified"].all()
assert compute_summary["wet_cells"].is_monotonic_increasing
assert (compute_summary["final_1h_ws_change_ft"] < 0.01).all()
display(compute_summary.style.format({
    "maximum_depth_ft": "{:.2f}",
    "final_12h_ws_range_ft": "{:.3f}",
    "final_1h_ws_change_ft": "{:.4f}",
}))
Text Only
2026-09-26 14:30:22 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'Perimeter 1' in 'AustinOyster.p01.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.


2026-09-26 14:30:37 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'Perimeter 1' in 'AustinOyster.p02.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.


2026-09-26 14:30:55 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'Perimeter 1' in 'AustinOyster.p03.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.


2026-09-26 14:31:13 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'Perimeter 1' in 'AustinOyster.p04.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.


2026-09-26 14:31:29 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'Perimeter 1' in 'AustinOyster.p05.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.


2026-09-26 14:31:51 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'Perimeter 1' in 'AustinOyster.p06.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.


2026-09-26 14:32:07 - ras_commander.hdf.HdfResultsMesh - INFO - Maximum-depth source for mesh 'Perimeter 1' in 'AustinOyster.p07.hdf': derived in memory by ras-commander from HEC-RAS HDF 'Water Surface' minus 'Cells Minimum Elevation'; no 'Depth' dataset was created or written.
  plan flow_cfs completed verified wet_cells maximum_depth_ft final_12h_ws_range_ft final_1h_ws_change_ft
0 p01 1000 True True 652 13.93 0.000 0.0000
1 p02 2000 True True 962 14.73 0.000 0.0000
2 p03 3000 True True 1380 15.69 0.000 0.0000
3 p04 4000 True True 1774 16.19 0.000 0.0000
4 p05 5000 True True 2143 16.54 0.002 0.0000
5 p06 6000 True True 2351 16.80 0.000 0.0000
6 p07 7000 True True 2543 17.02 0.000 0.0000

Review every computed inundation result

All panels use the same depth scale and map extent, so changes between successive flows are directly comparable. The wet-cell count provides a compact monotonicity check; the maps remain the essential spatial review.

Python
columns = 3
rows = int(np.ceil(len(depth_results) / columns))
fig, axes = plt.subplots(rows, columns, figsize=(15, 4.8 * rows), squeeze=False)
positive_depths = [
    frame["maximum_depth"].to_numpy()
    for frame in depth_results.values()
    if not frame.empty
]
shared_max = float(np.nanpercentile(np.concatenate(positive_depths), 99))

for ax, (flow, wet) in zip(axes.flat, depth_results.items()):
    child_mesh.boundary.plot(ax=ax, color="#111827", linewidth=0.8)
    wet.plot(
        ax=ax,
        column="maximum_depth",
        cmap="Blues",
        markersize=3,
        vmin=0,
        vmax=shared_max,
    )
    recommended_bc_lines.plot(ax=ax, color=["#2563eb", "#db2777"], linewidth=2)
    ax.set_title(f"{flow:,} cfs")
    ax.set_axis_off()
for ax in axes.flat[len(depth_results):]:
    ax.set_visible(False)

normalizer = plt.Normalize(vmin=0, vmax=shared_max)
scalar = plt.cm.ScalarMappable(norm=normalizer, cmap="Blues")
scalar.set_array([])
fig.colorbar(scalar, ax=axes.ravel().tolist(), shrink=0.65, label="Maximum depth (ft)")
fig.suptitle("Computed maximum inundation depth for each flow plan", fontsize=15, weight="bold")
plt.show()

png

Parent/child hydraulic validation at USGS 08078400

The completed constant-flow child is compared with the parent 1% rain-on-mesh result at the nearest mesh cell to the gauge. This is a focused reproduction check, not a complete validation. The full review also includes hydrograph shape, volume continuity, spatial WSE differences, sensitivity to the downstream slope, computation messages, and manual inspection in RAS Mapper.

Python
child_ws = HdfResultsMesh.get_mesh_max_ws(child_plan_hdf)
child_gauge = gauge.to_crs(child_ws.crs).geometry.iloc[0]
child_index = child_ws.geometry.distance(child_gauge).idxmin()
child_row = child_ws.loc[child_index]

validation = {
    "USGS site": GAUGE_ID,
    "child maximum WSE (ft)": float(child_row["maximum_water_surface"]),
    "child cell offset (ft)": float(child_row.geometry.distance(child_gauge)),
    "parent maximum WSE (ft)": np.nan,
    "child minus parent (ft)": np.nan,
}
if parent_ras is not None:
    parent_plan_hdf = PARENT_PROJECT / "AustinOyster.p08.hdf"
    parent_ws = HdfResultsMesh.get_mesh_max_ws(parent_plan_hdf)
    parent_gauge = gauge.to_crs(parent_ws.crs).geometry.iloc[0]
    parent_index = parent_ws.geometry.distance(parent_gauge).idxmin()
    parent_row = parent_ws.loc[parent_index]
    validation["parent maximum WSE (ft)"] = float(parent_row["maximum_water_surface"])
    validation["child minus parent (ft)"] = (
        validation["child maximum WSE (ft)"] - validation["parent maximum WSE (ft)"]
    )
    assert abs(validation["child minus parent (ft)"]) <= 0.15

display(pd.DataFrame([validation]).style.format(precision=3))
  USGS site child maximum WSE (ft) child cell offset (ft) parent maximum WSE (ft) child minus parent (ft)
0 08078400 26.637 41.039 26.699 -0.063

Review checklist

  • Confirm the small firehose domain is appropriate for the question; it does not retain upstream rain-on-mesh runoff.
  • Review every clipped breakline and verify the dropped connection truly lies outside the child.
  • Confirm Inflow_US and Outlet_DS attach to the intended perimeter faces after geometry preprocessing; reject any reach-level inflow that remains internal.
  • Inspect solver messages and continuity; the original check run reported 0.013% continuity error.
  • Review WSE and velocity spatially, not only at the gauge.
  • Repeat the downstream-slope sensitivity when the domain, terrain, mesh, or design flow changes.
  • Open the resulting project in RAS Mapper for manual diagnostics. A programmatic pass is evidence, not a substitute for engineering review.