Activity 4: A Reproducible CyberWater Workflow for Compound-Flood Mapping in Mobile Bay, Alabama

Author: Ehsan Kahrizi
Activity: CyberWater2 Training — Activity 4 Conceptual Proposal
Document type: Conceptual implementation plan (not a completed workflow)
Date: September 25, 2026

1. Research Question or Modeling Problem

Broad scientific question

How do river discharge, coastal water levels, storm surge, tides, and rainfall interact to produce compound flooding in Mobile Bay, Alabama?

Operational research question

For selected historical or forecast events in Mobile Bay, how can National Water Model river discharge, coastal water-level information, precipitation, and watershed/coastal characteristics be connected to a hydrodynamic model to estimate the timing, depth, extent, duration, and velocity of compound flooding in a reproducible CyberWater workflow?

Scientific motivation

Flooding around Mobile Bay can result from more than one driver. High river discharge can move water toward the bay while tides, storm surge, and elevated coastal water levels can restrict drainage and create backwater effects. Local rainfall can add additional runoff. Evaluating these drivers independently may underestimate flooding where they occur simultaneously or in close succession.

The proposed workflow would connect riverine and coastal information, execute a two-dimensional hydrodynamic model, and preserve the data, parameters, model configuration, execution history, and outputs needed to reproduce the analysis. The initial implementation would focus on a limited pilot area and a small number of events rather than the entire Mobile Bay system.

2. Desired Workflow Outcome

The desired CyberWater workflow should be able to:

1. Define a study area and simulation period.
2. Retrieve or ingest river discharge from the National Water Model (NWM).
3. Retrieve or ingest coastal water-level boundary conditions from NOAA observations, STOFS output, or another suitable coastal product.
4. Retrieve precipitation and, when needed, wind and atmospheric-pressure forcing.
5. Prepare terrain, bathymetry, land-cover, roughness, and hydraulic-structure inputs.
6. Harmonize coordinate systems, units, spatial resolution, temporal resolution, time zones, and vertical datums.
7. Configure and execute a two-dimensional hydrodynamic solver.
8. Produce water-surface elevation, flood depth, extent, velocity, arrival time, and duration.
9. Compare modeled results with available water-level observations, high-water marks, flood reports, or remote-sensing products.
10. Preserve the workflow configuration, provenance, inputs, outputs, and evaluation results for reuse in another event or nearby coastal watershed.

The workflow is intended to support both retrospective event analysis and, after further development, forecast applications.

3. Initial Scope and Success Criteria

Initial scope

• Location: A pilot subregion of Mobile Bay and its connected river/floodplain system, Alabama.
• Time period: One or more well-documented historical compound-flood events. The final dates will be selected based on the availability of river, coastal, meteorological, and validation data.
• Hydrodynamic solver: HEC-RAS 2D is proposed for the first implementation because it can represent unsteady 1D/2D river and floodplain hydraulics and aligns with the author's existing experience. ADCIRC or SCHISM could be evaluated later for more complete bay-scale coastal circulation and surge simulation.
• Primary coupling: NWM upstream/lateral river inflows plus a downstream coastal water-level boundary.
• Initial outputs: Maximum flood depth, maximum water-surface elevation, maximum velocity, flood extent, arrival time, and inundation duration.

Success criteria

The conceptual workflow will be considered successfully implemented when it can:

• run a selected Mobile Bay event without manual transfer of intermediate data between major workflow stages;
• record the input dataset versions, model configuration, and execution provenance;
• reproduce the same outputs from the documented inputs and settings;
• produce georeferenced flood-depth and flood-extent layers;
• compare modeled water levels or inundation against at least one independent observational dataset; and
• be rerun for a second event by changing documented time, forcing, and boundary-condition inputs rather than rebuilding the entire workflow.

4. Required Inputs

5. Models and Computational Tools

Proposed initial hydrodynamic model: HEC-RAS 2D

HEC-RAS 2D would receive river discharge hydrographs at upstream or lateral boundaries and a time-varying coastal stage hydrograph at the downstream boundary. Rainfall may be applied directly if appropriate. The model would simulate unsteady hydraulic interactions, including floodplain storage, backwater effects, and overland flow.

The HEC-RAS integration would require a CyberWater Model Agent or Generic Model Agent configuration that can:

• create an isolated working directory;
• copy a validated HEC-RAS project and geometry;
• update boundary-condition and simulation-period files;
• execute the compatible HEC-RAS computational engine;
• monitor completion and capture logs;
• read the HDF output; and
• convert selected results to CyberWater msmDataSet objects and standard geospatial files.

Future alternative: ADCIRC or SCHISM

ADCIRC may be preferable when hurricane surge, wind-driven circulation, tides, and bay-scale coastal inundation are the primary focus. SCHISM may be preferable for a seamless river-estuary-shelf-ocean representation and more advanced coupling of hydrologic inflows with coastal circulation. These alternatives would require their own Model Agents, meshes, forcing preparation, and likely HPC execution.

6. Major Scientific Workflow

1. Define study: Select event, simulation period, pilot domain, output resolution, and validation targets.
2. Acquire data: Retrieve NWM discharge, coastal water level, precipitation, terrain, bathymetry, and observations.
3. Inspect and validate inputs: Check coverage, units, timestamps, coordinate systems, datums, quality flags, and gaps.
4. Subset and transform: Clip data to the domain; resample time series; convert units; reconcile horizontal and vertical references.
5. Map NWM reaches to hydraulic boundaries: Match NWM reaches to HEC-RAS inflow locations and aggregate or distribute flows according to documented rules.
6. Prepare coastal boundary: Convert the selected NOAA/STOFS water-level series to the model's vertical datum and time step.
7. Prepare hydrodynamic model: Supply geometry, roughness, structures, initial conditions, and numerical settings.
8. Execute solver: Run HEC-RAS 2D locally or through a remote/HPC execution component.
9. Postprocess outputs: Extract maximum and time-varying depth, water-surface elevation, velocity, extent, arrival time, and duration.
10. Evaluate: Compare model output with gauges, high-water marks, observed flood extent, or other available evidence.
11. Publish and preserve: Save inputs or persistent references, workflow, parameters, logs, outputs, figures, metadata, and limitations in HydroShare.

7. Proposed CyberWater Workflow

mermaid flowchart TD A["TimeRange and SpaceRange"] --> B["NWM and coastal Data Agents"] B --> C["Quality control, datum, units and resampling"] D["DEM, bathymetry, roughness and structures"] --> E["HEC-RAS 2D Model Agent"] C --> E E --> F["Flood depth, extent, velocity and duration"] F --> G["Validation and visualization"] G --> H["Provenance and HydroShare publication"]

Conceptual module sequence

TimeRange + SpaceRange
→ NWMDataAgent
→ CoastalWaterLevelAgent
→ optional Precipitation/Wind Agent
→ quality-control and preprocessing modules
→ BoundaryConditionGenerator
→ HECRAS2DModelAgent
→ HECRASHDFOutputReader
→ flood-map and time-series visualization
→ validation metrics
→ HydroShare resource and provenance record.

8. CyberWater Components Already Available or Reusable

The following assessment is preliminary and should be confirmed with the CyberWater development team.

9. Components Missing or Requiring Development

The most important minimum development path is the combination of an NWM Data Agent, a coastal-water-level Data Agent, boundary-condition generation, a HEC-RAS 2D Model Agent, and an HDF output reader.

10. Outputs and Evaluation

Required outputs

• Model-ready river and coastal boundary-condition time series
• Execution configuration and solver logs
• Maximum water-surface elevation raster
• Maximum flood-depth raster
• Maximum velocity raster
• Flood-extent polygon or raster
• Arrival-time and inundation-duration rasters
• Water-level hydrographs at observation and impact locations
• Event summary table
• Validation statistics and comparison figures
• Complete provenance record and README

Evaluation approach

Evaluation will depend on available observations. Potential measures include:

• bias, RMSE, MAE, correlation, and timing error for water-level hydrographs;
• peak-stage and peak-time error;
• critical success index, probability of detection, false-alarm ratio, and F-score for observed versus modeled inundation extent;
• depth error at high-water marks;
• sensitivity of results to coastal boundary level, river inflow, roughness, DEM/bathymetry, and structure representation; and
• comparison of river-only, coastal-only, and combined simulations to quantify interaction and compound effects.

At minimum, three scenarios should be compared for a selected event:

1. River-only: NWM inflows with a baseline coastal boundary.
2. Coastal-only: Elevated coastal water level with baseline river flow.
3. Combined: Time-varying river and coastal forcing together.

The nonlinear compound contribution can then be examined by comparing the combined result with the two single-driver simulations.

11. Risks, Uncertainties, and Limitations

• Vertical datum inconsistency: NOAA water levels, DEMs, bathymetry, and model elevations may use different datums. An incorrect conversion could dominate the flood-depth error.
• NWM boundary uncertainty: NWM discharge may have bias, timing error, or reach-to-boundary mapping uncertainty.
• Coastal-boundary uncertainty: Gauge observations may not represent spatially varying conditions across Mobile Bay; model products may introduce their own errors.
• Topographic and bathymetric uncertainty: Resolution, age, hydro-enforcement, shoreline representation, and channel geometry affect connectivity and depth.
• Hydraulic structures: Missing or simplified bridges, culverts, levees, roads, gates, and drainage systems may alter inundation pathways.
• Model calibration: Roughness and other hydraulic parameters require calibration or defensible literature-based ranges.
• Numerical stability and scale: Grid resolution and time step influence stability, accuracy, and computation time.
• Model-version dependence: HEC-RAS project and output formats may differ by version; automated execution must record the version used.
• Data licensing and access: Some existing models or datasets may not permit unrestricted redistribution.
• Computational demand: Bay-scale, high-resolution simulations may require HPC resources and storage beyond a desktop workflow.
• Compound-event definition: Results depend on thresholds, coincidence windows, lag assumptions, and whether dependence is defined statistically or dynamically.
• Forecast use: Operational forecasting would require reliable, automated, low-latency data access and uncertainty communication beyond the initial research implementation.

12. Reproducibility and Data Management

The workflow should preserve:

• dataset source, version, retrieval date, variable names, spatial/temporal coverage, and checksums when possible;
• horizontal coordinate system and vertical datum;
• all transformations, resampling, unit conversions, and missing-data rules;
• model geometry/version, parameters, numerical settings, and executable version;
• workflow version, execution logs, warnings, failures, and runtime environment;
• validation observations and metric definitions; and
• final figures, maps, tabular outputs, and limitations.

The HydroShare resource should contain the implementation plan, CyberWater workflow file, lightweight configuration and parameter files, figures, logs, and links or instructions for large or restricted datasets. Large datasets should not be duplicated when a stable, documented service or persistent reference is available.

13. Phased Implementation Plan

Phase 1 — Event identification without a new hydrodynamic simulation

Connect NWM discharge, NOAA/STOFS water level, and precipitation; harmonize their timestamps and units; identify joint threshold exceedances; and create a catalog of candidate compound events.

Phase 2 — Pilot HEC-RAS 2D event simulation

Select one event and a limited pilot domain, prepare river and coastal boundaries, execute an existing or newly developed HEC-RAS 2D model, and generate flood maps.

Phase 3 — Validation and sensitivity analysis

Compare modeled water levels and inundation with observations and test sensitivity to boundary conditions, roughness, and terrain/bathymetry.

Phase 4 — Reusable CyberWater components

Generalize the Data Agents, boundary mapper, Model Agent, output reader, and validation tools so the workflow can be transferred to another event or coastal watershed.

Phase 5 — Forecast and communication extension

Connect forecast NWM and coastal products, incorporate uncertainty, and publish outputs through a decision-support interface such as HECinBOX.

14. Questions for the CyberWater Team

1. Is there an existing or planned NWM Data Agent, NOAA water-level agent, or STOFS connector that can be reused?
2. Can the current msmDataSet representation efficiently store time-varying raster and unstructured-grid flood outputs?
3. What is the recommended pattern for wrapping a Windows-based external model such as HEC-RAS?
4. Can RunModuleAgent invoke the HEC-RAS computation engine non-interactively, or is a dedicated Model Agent preferred?
5. What is the recommended way to expose HDF output variables as CyberWater datasets?
6. Are there existing modules for vertical-datum conversion, NWM reach mapping, or coastal boundary preparation?
7. Which CyberWater HPC mechanism would be appropriate for larger HEC-RAS, ADCIRC, or SCHISM simulations?
8. How should large inputs and outputs be referenced in HydroShare without unnecessary duplication?
9. What licensing requirements apply to modifying and distributing CyberWater agents based on the current source code?
10. Would the team consider NWM, coastal-water-level, HEC-RAS, and flood-mapping agents useful community contributions?

15. Feedback and Planned Revisions

This section will be completed after the required discussion with a CyberWater team member.

• Reviewer/facilitator: To be determined
• Date: To be determined
• Main feedback: To be added
• Changes made after feedback: To be added
• Remaining unresolved questions: To be added

16. Expected Contribution

The proposed project would extend CyberWater from watershed-scale data and hydrologic-model workflows toward reproducible river-coastal compound-flood mapping. Its main contribution would not be only one Mobile Bay simulation. The intended contribution is a reusable set of interfaces connecting national hydrologic data, coastal boundary data, a hydrodynamic solver, validation observations, and flood-map communication tools while preserving the provenance required to reproduce and evaluate the analysis.