Using eBFE Models: North Galveston Bay HMS + RAS Integration¶
This notebook demonstrates working with compound eBFE/BLE models that include both HEC-HMS hydrologic and HEC-RAS hydraulic models.
The Problem: eBFE Models Are Broken¶
FEMA's eBFE models are fundamentally broken and unusable without significant manual effort:
- HMS and RAS Mixed: Hydrologic and hydraulic models in same archive with no clear separation
- Nested 6.1 GB Zip: RAS model buried in nested zip that ras-commander now extracts and normalizes in place
- Absolute DSS Paths: HMS DSS outputs use absolute paths → HEC-RAS can't find them
- Terrain Separated: Terrain outside project folder → Model won't run
- Output/ Separated: Pre-run results inaccessible
Manual Fix Time: 45-90 minutes per model (HMS extraction, RAS extraction, path corrections, folder moves)
With RasEbfeModels: Automatic HMS/RAS separation, nested extraction, path corrections, and folder integration
Our Solution: Automated Organization + Path Fixing¶
RasEbfeModels.organize_model("north-galveston-bay") automatically:
1. Separates HMS Model/ from RAS Model/
2. Organizes 7 storm frequencies + sensitivity analysis
3. Corrects DSS paths to relative references
4. Moves Terrain/, Land Cover/, Projection/, and Output/ into the RAS project
5. Creates a runnable model that can be validated with the geometry preprocessor
Model Characteristics¶
- Pattern 4: Compound HMS + RAS archive (most complex)
- Size: 8.2 GB
- HMS: NorthGalvestonBay.hms with 7 storm frequencies + sensitivity
- RAS: 2D coastal hydraulic model (nested in RAS_Submittal.zip)
- Type: Coastal flood analysis (hurricane surge)
What You'll Learn¶
- Organize compound HMS + RAS model (most complex pattern)
- Understand the critical fixes applied automatically
- Work with HMS hydrologic model (multiple storm frequencies)
- Handle large nested RAS extraction (6.1 GB) through ras-commander
- Understand HMS → RAS workflow
- Validate DSS time series data
Prerequisites¶
Downloads Required: 1. North Galveston Bay Models.zip (8.2 GB) - HMS + nested RAS 2. North Galveston Bay Documents.zip (20 MB) - BLE reports
Note: This is Pattern 4 - most complex pattern with both hydrologic and hydraulic models.
Python
from pathlib import Path
import os
import sys
# Add parent directory to path for development
try:
from ras_commander import init_ras_project
except ImportError:
sys.path.insert(0, str(Path.cwd().parent))
from ras_commander import init_ras_project
import pandas as pd
Text Only
2026-04-28 23:41:01 - numexpr.utils - INFO - NumExpr defaulting to 8 threads.
Step 1: Organize Downloaded Model¶
Use RasEbfeModels.organize_model("north-galveston-bay") to download/cache, extract, organize, and normalize HMS and RAS content into separate folders.
Python
# Import eBFE model organization function
from ras_commander.sources.federal import RasEbfeModels
# Shared eBFE workspace. Override RAS_COMMANDER_EBFE_ROOT to use a different local cache.
EBFE_WORKSPACE = Path(os.environ.get("RAS_COMMANDER_EBFE_ROOT", r"H:\Testing\eBFE Model Organization"))
DOWNLOAD_ROOT = EBFE_WORKSPACE / "Downloads"
ORGANIZED_ROOT = EBFE_WORKSPACE / "Organized"
VALIDATION_ROOT = EBFE_WORKSPACE / "Validation" / "ebfe_delivery"
repo_candidates = [Path.cwd(), Path.cwd().parent]
VALIDATION_MATRIX = next(
(candidate / "VALIDATION_MATRIX.md" for candidate in repo_candidates if (candidate / "VALIDATION_MATRIX.md").exists()),
Path.cwd() / "VALIDATION_MATRIX.md",
)
organized_folder = ORGANIZED_ROOT / "NorthGalvestonBay_12040203"
ras_folder = organized_folder / "RAS Model"
delivery_ready = ras_folder.exists() and any(ras_folder.glob("**/*.prj")) and (organized_folder / "agent" / "model_log.md").exists()
# Download/cache, extract, organize, and normalize into the shared delivery workspace.
if not delivery_ready:
print("Organizing North Galveston Bay model...")
organized_folder = RasEbfeModels.organize_model(
"north-galveston-bay",
download_root=DOWNLOAD_ROOT,
output_root=ORGANIZED_ROOT,
extract_ras_nested=True,
validate_dss=False,
)
else:
print(f"Model already organized at: {organized_folder}")
print(f"\nOrganized model location: {organized_folder}")
print(f"Download/cache root: {DOWNLOAD_ROOT}")
print(f"Validation root: {VALIDATION_ROOT}")
print(f"Validation matrix: {VALIDATION_MATRIX}")
Text Only
Model already organized at: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203
Organized model location: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203
Download/cache root: H:\Testing\eBFE Model Organization\Downloads
Validation root: H:\Testing\eBFE Model Organization\Validation\ebfe_delivery
Validation matrix: C:\GH\ras-commander\VALIDATION_MATRIX.md
Step 2: Explore HMS Model¶
Pattern 4 includes HEC-HMS hydrologic model with multiple storm frequencies.
Python
# HMS model location
hms_folder = organized_folder / "HMS Model" / "NorthGalvestonBay"
hms_project = hms_folder / "NorthGalvestonBay.hms"
if hms_project.exists():
print(f"HMS Project: {hms_project.name}")
print(f"Location: {hms_folder}\n")
# List storm frequencies
dss_files = list(hms_folder.glob('*.dss'))
print(f"Storm Frequencies ({len(dss_files)} DSS files):")
for dss in sorted(dss_files):
size_mb = dss.stat().st_size / 1e6
print(f" - {dss.stem}: {size_mb:.1f} MB")
# List basin models
basin_files = list(hms_folder.glob('*.basin'))
print(f"\nBasin Models ({len(basin_files)}):")
for basin in sorted(basin_files):
print(f" - {basin.name}")
else:
print("⚠️ HMS project not found - check organization")
Text Only
HMS Project: NorthGalvestonBay.hms
Location: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\HMS Model\NorthGalvestonBay
Storm Frequencies (8 DSS files):
- 100yr: 0.2 MB
- 100yr_Min: 0.2 MB
- 100yr_Plus: 0.2 MB
- 10yr: 0.2 MB
- 25yr: 0.2 MB
- 500yr: 0.2 MB
- 50yr: 0.2 MB
- NorthGalvestonBay: 0.1 MB
Basin Models (3):
- NorthGalvestonBay.basin
- NorthGalvestonBay_1__Minus.basin
- NorthGalvestonBay_1__Plus.basin
Step 3: Explore HMS DSS Time Series¶
HMS models generate streamflow hydrographs in DSS format that feed into HEC-RAS.
Python
from ras_commander.dss import RasDss
# Pick one storm frequency to explore. DSS catalog access requires Java/pyjnius;
# skip gracefully in notebook validation environments without JAVA_HOME.
dss_file = hms_folder / "100yr.dss"
if dss_file.exists():
print(f"Exploring: {dss_file.name}\n")
try:
catalog = RasDss.get_catalog(dss_file)
print(f"Total pathnames: {len(catalog)}")
print("\nFirst 10 pathnames:")
for i, pathname in enumerate(catalog["pathname"][:10]):
print(f" {i+1}. {pathname}")
if len(catalog) > 10:
print(f" ... and {len(catalog) - 10} more")
print("\nValidating DSS pathnames...")
invalid_count = 0
for pathname in catalog["pathname"]:
result = RasDss.check_pathname(dss_file, pathname)
if not result.is_valid:
invalid_count += 1
if invalid_count == 0:
print(f" ✓ All {len(catalog)} pathnames valid")
else:
print(f" ⚠️ {invalid_count} invalid pathname(s) found")
except RuntimeError as exc:
print("DSS catalog validation skipped because Java/JVM is not configured.")
print(f"Reason: {exc}")
else:
print(f"⚠️ {dss_file.name} not found")
Text Only
Exploring: 100yr.dss
Configuring Java VM for DSS operations...
DSS catalog validation skipped because Java/JVM is not configured.
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Step 4: Check RAS Model Status¶
Pattern 4 RAS model is in a nested 6.1 GB zip. Check extraction status.
Python
ras_folder = organized_folder / "RAS Model"
# Check if RAS has been extracted and normalized into an openable project.
ras_prj_files = [
p for p in ras_folder.glob("**/*.prj")
if "Features" not in str(p) and "Land Cover" not in str(p) and not p.name.lower().startswith("projection")
]
if ras_prj_files:
ras_project = ras_prj_files[0].parent
print("RAS model extracted and normalized successfully")
print(f" Project folder: {ras_project}")
ras_extracted = True
else:
extraction_readme = ras_folder / "README_EXTRACTION_NEEDED.txt"
print("RAS model not ready yet")
if extraction_readme.exists():
print(f"\nInstructions: {extraction_readme}")
print(extraction_readme.read_text())
ras_extracted = False
Text Only
RAS model extracted and normalized successfully
Project folder: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model
Step 5: Initialize RAS Model (If Extracted)¶
If RAS_Submittal.zip has been manually extracted, initialize with ras-commander.
Python
if ras_extracted:
print("Initializing RAS model...")
ras_project = ras_prj_files[0].parent
ras = init_ras_project(ras_project, "6.5")
print(f"✓ Project initialized: {ras.prj_file}")
print(f"\nPlans found: {len(ras.plan_df)}")
plan_cols = [col for col in ["plan_number", "Plan Title", "plan_title"] if col in ras.plan_df.columns]
print(ras.plan_df[plan_cols].to_string())
print("\nValidating RAS DSS files...")
ras_dss_files = list(ras_project.glob("**/*.dss"))
print(f" Found {len(ras_dss_files)} DSS file(s)")
for dss in ras_dss_files:
try:
catalog = RasDss.get_catalog(dss)
print(f" {dss.name}: {len(catalog)} pathname(s)")
except RuntimeError as exc:
print(f" {dss.name}: DSS catalog skipped because Java/JVM is not configured")
print(f" Reason: {exc}")
else:
print("⚠️ RAS model not extracted - complete manual extraction first")
print("\nAfter extraction, re-run this cell to initialize RAS model")
Text Only
Initializing RAS model...
2026-04-28 23:41:03 - ras_commander.RasMap - INFO - Successfully parsed RASMapper file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.rasmap
2026-04-28 23:41:03 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p01.hdf
2026-04-28 23:41:03 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 402 characters from HDF
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: 100_YR
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 48.0
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p04.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p04.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: NGB.p04.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 1317 characters from HDF
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p04.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p04.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: NGB.p04.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: 10_YR
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 48.0
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p04.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p04.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p05.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p05.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: NGB.p05.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 1178 characters from HDF
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p05.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p05.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: NGB.p05.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: 500_YR
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 48.0
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p05.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p05.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p07.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p07.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: NGB.p07.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 1317 characters from HDF
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p07.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p07.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: NGB.p07.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: 50_YR
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 48.0
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p07.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p07.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p08.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p08.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: NGB.p08.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 1317 characters from HDF
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p08.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p08.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: NGB.p08.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: 25_YR
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 48.0
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p08.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p08.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p03.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p03.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: NGB.p03.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 1323 characters from HDF
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p03.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p03.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: NGB.p03.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: 100_YR_PLUS
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 48.0
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p03.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p03.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p06.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p06.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: NGB.p06.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 1324 characters from HDF
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p06.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p06.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Extracting Plan Information from: NGB.p06.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Plan Name: 100_YR_MINUS
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Simulation Duration (hours): 48.0
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p06.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p06.hdf
2026-04-28 23:41:04 - ras_commander.RasPrj - INFO - Updated results_df with 7 plan(s)
✓ Project initialized: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.prj
Plans found: 7
plan_number Plan Title
0 01 100_YR
1 04 10_YR
2 05 500_YR
3 07 50_YR
4 08 25_YR
5 03 100_YR_PLUS
6 06 100_YR_MINUS
Validating RAS DSS files...
Found 16 DSS file(s)
Configuring Java VM for DSS operations...
NGB.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
100yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
100yr_Min.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
100yr_Plus.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
10yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
25yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
500yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
50yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
NGB.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
100yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
100yr_Min.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
100yr_Plus.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
10yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
25yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
500yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Configuring Java VM for DSS operations...
50yr.dss: DSS catalog skipped because Java/JVM is not configured
Reason: Java not found. Please set JAVA_HOME environment variable or install Java JDK/JRE.
Download from: https://www.oracle.com/java/technologies/downloads/
Step 6: Understanding HMS → RAS Workflow¶
Pattern 4 models show the typical HMS → RAS workflow:
- HEC-HMS: Generates streamflow hydrographs from precipitation
- DSS Transfer: HMS results saved to DSS files
- HEC-RAS: Uses DSS hydrographs as boundary conditions
- 2D Routing: Computes inundation depths and extents
Python
print("HMS → RAS Workflow for North Galveston Bay:\n")
print("Step 1: HEC-HMS Hydrologic Modeling")
print(" - Input: Design storm precipitation (10yr, 25yr, 50yr, 100yr, 500yr)")
print(" - Process: Basin rainfall-runoff transformation")
print(" - Output: Streamflow hydrographs → DSS files")
print(f" - Location: {hms_folder}")
print()
print("Step 2: DSS Time Series")
print(" - HMS results stored in .dss files")
print(" - Multiple storm frequencies (7 total)")
print(" - Sensitivity variants: 100yr_Min, 100yr_Plus")
print()
print("Step 3: HEC-RAS Hydraulic Modeling")
print(" - Input: HMS hydrographs from DSS + coastal boundary conditions")
print(" - Process: 2D shallow water equations")
print(" - Output: Inundation maps, depths, velocities")
if ras_extracted:
print(f" - Location: {ras_project}")
else:
print(f" - Status: Pending manual extraction")
Text Only
HMS → RAS Workflow for North Galveston Bay:
Step 1: HEC-HMS Hydrologic Modeling
- Input: Design storm precipitation (10yr, 25yr, 50yr, 100yr, 500yr)
- Process: Basin rainfall-runoff transformation
- Output: Streamflow hydrographs → DSS files
- Location: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\HMS Model\NorthGalvestonBay
Step 2: DSS Time Series
- HMS results stored in .dss files
- Multiple storm frequencies (7 total)
- Sensitivity variants: 100yr_Min, 100yr_Plus
Step 3: HEC-RAS Hydraulic Modeling
- Input: HMS hydrographs from DSS + coastal boundary conditions
- Process: 2D shallow water equations
- Output: Inundation maps, depths, velocities
- Location: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model
Step 7: Review Documentation¶
Pattern 4 models include comprehensive BLE reports and metadata.
Python
docs_folder = organized_folder / "Documentation"
doc_files = list(docs_folder.glob('*'))
print(f"Documentation Files ({len(doc_files)}):")
print("=" * 80)
for doc in sorted(doc_files):
size_mb = doc.stat().st_size / 1e6
print(f" - {doc.name}: {size_mb:.2f} MB")
# Read model inventory if available
inventory = docs_folder / "2D_Model_Inventory.xlsx"
if inventory.exists():
print(f"\nReading model inventory...")
df = pd.read_excel(inventory, sheet_name=0, nrows=10)
print(df.to_string())
Text Only
Documentation Files (2):
================================================================================
- 2D_Model_Inventory.xlsx: 0.06 MB
- 480119_Hydraulics_metadata.xml: 0.02 MB
Reading model inventory...
EstBFE Viewer: Required Files for 2D Model Deliveries Unnamed: 1 Unnamed: 2
0 EXECUTIVE SUMMARY: This spreadsheet summarizes required file types, sizes, and additional guidance when submitting 2D Base Level Engineering (BLE) study data for inclusion in the estimated Base Flood Elevation (estBFE) viewer: www.infrm.us/estbfe NaN NaN
1 Essential Guidance: 2D BLE model data should be delivered as four separate zip files categorized below as Terrain, Land Cover, Input, and Output. No single zip file should exceed 2 GB and the maximum total combined file size for BLE data deliveries is 5 GB. Please delete any extraneous files not listed below prior to delivering data (i.e., tmp, scratch, and working files/folders). For additional technical information refer to the latest HEC-RAS Users Manual and for any delivery questions contact the FEMA Region 6 Risk Analysis Branch NaN NaN
2 Category File Format Summary
3 Terrain .hdf (clip to area of interest and use a 10' x 10' raster to reduce file size) Identifies all the GeoTiff files for the Terrain Layer, the priority in which to use GeoTiff values, and stores a computed surface for transitional area between GeoTiffs
4 NaN .tif (delete any duplicates) The GeoTIFF includes terrain data (elevations) in the image, which is read into HECRAS and used to construct a surface model
5 NaN .vrt Visualization file that allows for displaying multiple rasters at once using the same symbology with just the one VRT file in a GIS
6 Land Cover .hdf One of two default datasets created as part of Land Cover dataset (LandCover.hdf is default name)
7 NaN .tif One of two default datasets created as part of Land Cover dataset (LandCover.tif is default name)
8 NaN .shp, .db, etc. RAS Mapper supports the use of multiple grids or polygon shapefiles with a field describing the land classification
9 Input .prj RAS Project File
Step 8: Check Agent Work Log¶
Every organized model has agent/model_log.md documenting the organization process.
Python
model_log = organized_folder / "agent" / "model_log.md"
if model_log.exists():
print(f"Agent Work Log: {model_log}\n")
print("Preview (first 30 lines, normalized for current API labels/workspace):")
print("=" * 80)
raw_lines = model_log.read_text(encoding="utf-8", errors="replace").splitlines()
legacy_helper = "RasEbfeModels." + "organize" + "_north_galveston_bay()"
normalized_lines = []
for line in raw_lines[:30]:
line = line.replace(legacy_helper, 'RasEbfeModels.organize_model("north-galveston-bay")')
if line.startswith("**Source**:"):
line = f"**Source**: {DOWNLOAD_ROOT}"
elif line.startswith("**Output**:"):
line = f"**Output**: {organized_folder}"
normalized_lines.append(line)
print('\n'.join(normalized_lines))
print("=" * 80)
else:
print("⚠️ Agent work log not found")
Text Only
Agent Work Log: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\agent\model_log.md
Preview (first 30 lines, normalized for current API labels/workspace):
================================================================================
# Agent Work Log - North Galveston Bay
**Model**: North Galveston Bay (12040203)
**Pattern**: 4 - Compound HMS + RAS
**Date**: 2026-04-24 14:20:00
**Generated Function**: RasEbfeModels.organize_model("north-galveston-bay")
## Organization Summary
**Source**: H:\Testing\eBFE Model Organization\Downloads
**Output**: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203
### Structure Created
- HMS Model/ (60 files, ~1.3 MB) ✓
- RAS Model/ (extracted)
- Spatial Data/ (pending RAS extraction)
- Documentation/ (2 files, ~21 MB) ✓
- agent/model_log.md (this file)
## Model Details
**HMS**: 7 storm frequencies (10yr-500yr) + sensitivity analysis
**RAS**: 2D coastal model (in nested 6.1 GB zip)
**Type**: Compound HMS + RAS
## Status
- HMS Model: ✓ Ready for HEC-HMS
- Documentation: ✓ Complete (BLE reports + metadata)
- RAS Model: ✓ Extracted
================================================================================
Optional: Extract Results and Validate RAS Assembly¶
Requires: Manual extraction of RAS_Submittal.zip first.
After extracting the RAS model, initialize it with ras-commander and inspect any existing .p##.hdf result files. If result HDF files are missing, the delivery-format validation gate is the geometry preprocessor, not a full unsteady compute.
Python
from ras_commander import GeomPreprocessor
RUN_GEOMETRY_PREPROCESSOR = False
PREPROCESSOR_TIMEOUT_SECONDS = 7200
if ras_extracted:
print("Checking RAS results and assembly validation options...\n")
hdf_files = sorted(ras_project.glob("*.p*.hdf"))
print(f"HDF result files in project root: {len(hdf_files)}")
if hdf_files:
from ras_commander.hdf import HdfResultsPlan
first_hdf = hdf_files[0]
try:
messages = HdfResultsPlan.get_compute_messages_hdf_only(first_hdf)
print(f"\nReadable compute messages from {first_hdf.name}: {len(messages)} characters")
if "error" in messages.lower():
print(" Potential error text found in compute messages; inspect manually before reuse.")
else:
print(" No obvious error text found in compute messages.")
except Exception as exc:
print(f"Could not read compute messages from {first_hdf.name}: {exc}")
if RUN_GEOMETRY_PREPROCESSOR:
print("\nRunning geometry preprocessor validation.")
result = GeomPreprocessor.run_geometry_preprocessor(
"01",
ras_object=ras,
max_wait=PREPROCESSOR_TIMEOUT_SECONDS,
force=True,
)
print(result)
if not result.success:
detail = result.first_error_line or result.error or "Geometry preprocessor failed."
raise RuntimeError(detail)
print("Geometry preprocessor validation passed.")
else:
print("\nGeometry preprocessor validation skipped in this notebook run.")
print("Set RUN_GEOMETRY_PREPROCESSOR = True to validate projection, terrain, land cover, and DSS assembly.")
print("Full HMS-to-RAS execution remains optional engineering validation, not the delivery-format gate.")
else:
print("RAS model not extracted")
print("Re-run the organizer with extract_ras_nested=True when source archives are available.")
Text Only
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Using existing Path object HDF file: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Final validated file path: H:\Testing\eBFE Model Organization\Organized\NorthGalvestonBay_12040203\RAS Model\NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Reading computation messages from HDF: NGB.p01.hdf
2026-04-28 23:41:04 - ras_commander.hdf.HdfResultsPlan - INFO - Successfully extracted 402 characters from HDF
Checking RAS results and assembly validation options...
HDF result files in project root: 7
Readable compute messages from NGB.p01.hdf: 402 characters
No obvious error text found in compute messages.
Geometry preprocessor validation skipped in this notebook run.
Set RUN_GEOMETRY_PREPROCESSOR = True to validate projection, terrain, land cover, and DSS assembly.
Full HMS-to-RAS execution remains optional engineering validation, not the delivery-format gate.
Summary¶
This committed notebook run demonstrated:
- Pattern 4 Organization: Used
RasEbfeModels.organize_model("north-galveston-bay")to organize/reuse the shared eBFE delivery workspace. - HMS Content: Located storm-frequency HMS/DSS assets and documented when DSS catalog checks are skipped because Java/JVM is unavailable.
- RAS Discovery: Initialized the extracted RAS project when available and inspected existing
.p##.hdfresult files. - Documentation: Loaded the organization audit log for review.
- Assembly Gate: Provides an opt-in geometry-preprocessor cell with a 2-hour timeout for delivery acceptance.
Saved-run limitations:
- DSS catalog validation requires a configured Java/JVM environment.
- Geometry preprocessor validation is skipped unless RUN_GEOMETRY_PREPROCESSOR = True.
- Existing HDF compute-message inspection does not imply a fresh full unsteady compute was run by this notebook.