Dissertation manuscript draft
Scaling Hydraulic Models for National Flood Inundation Mapping
!DRAFT!
By: James Matthew Coll © 2026
M.S., University of Kansas, 2016
B.S., Plymouth State University, 2014
Submitted to the graduate degree program in Department of Geography and Atmospheric Science and the Graduate Faculty of the University of Kansas in partial fulfillment of the requirements for the degree of Doctor of Philosophy.
Chair: Dr. Xingong Li
Dr. Nathan Brunsell
Dr. Jude Kastens
Dr. Stephen Egbert
Dr. Josh Roundy
Date Defended: Click to choose date
The dissertation committee for James Matthew Coll certifies that this is the approved version of the following dissertation: Scaling Hydraulic Models for National Flood Inundation Mapping
Chair: Dr. Xingong Li
Date Accepted: Click to choose date
Abstract
This dissertation addresses the technical friction associated with executing and communicating HEC-RAS based Flood Inundation Modeling (FIM) at scale. It focuses on the challenges of transitioning from reach-scale hydraulic modeling efforts to national-scale flood inundation mapping through harmonized inundation libraries. While the last decade has seen a near-exponential increase in FIM methodologies ranging from geospatial approximations such as the Height Above Nearest Drainage (HAND) implementations to multi-model hydraulic ensembles, these efforts remain isolated due to specialized data formats and model-specific terminologies. This work presents utilities and advances that provide an interoperable framework that aids in bridging those scales and domains while directly capitalizing on and re-using existing HEC-RAS models. It introduces RRASSLER, a tool for spatializing legacy models to align with FAIR data principles, and RAS2FIM, a framework for automating the generation of inundation libraries that uses the National Water Model (NWM) forecast for flood inundation mapping. Using these utilities, we quantify the deviations in predictions caused by segmenting large hydraulic models for reach-scale forecasting, demonstrating that monolithic processing significantly improves hydraulic accuracy over physical subsetting. Furthermore, we demonstrate that by decoupling the hydrologic, hydraulic, and geospatial drivers from the map creation process, we can harmonize otherwise independent libraries into a unified operating picture. This approach shifts the focus from the mechanics of modeling and forecasting to the communication of map generation, enhancing the utility of flood mapping for a more informed emergency response.
Acknowledgments
This dissertation was made possible in part due to the numerous co-authors and funding sources listed in each chapter. I am eternally grateful for the support of my advisor, Dr. Xingong Li, who saw enough in me to accept me into graduate school and found the fortitude to keep pushing me to a finish line. Among my innumerable inspirations I would like to thank my family: Lord Dragon, for his shelter and continuous reminders to ground myself; Brendan, for spending late nights coaxing nesting hexcopters out from high places; to Katie, for staying with me while this journey was all-consuming; and my parents and their unconventional methods of ‘dog-sitting’. While I’ll always wonder if there could have been an Olympic snowboarding career or a Firebird, it is thanks to you and many others that I’ve made it to this point at all.
Table of Contents
List of Figures
Chapter 1: Background
Abstract
The last decade has seen a near-exponential increase in the complexity and availability of Flood Inundation Modeling (FIM) methodologies. As the community transitions from reach-scale hydraulic modeling to national-scale geospatial forecasting, significant technical friction has emerged due to disparate data formats, model-specific driver requirements, and conflicting terminology used across the different efforts. This chapter traces the evolution of CONUS-scale FIM, from early Height Above Nearest Drainage (HAND) implementations to current multi-model ensembles. We identify a persistent “silo” effect where best-in-series models and the established standards take default precedent but remain operationally isolated.
Introduction
Flood inundation mapping, or the act of delineating the area under water, is a complex topic that probes deep gaps in our collective knowledge of physical laws governing reality, wrestles us with the technical friction of implementing that theory into operations, and antagonizes us with the need for decisive action in situations where every (in)decision has some degree of negative consequence to it. Of these pain points, the technical friction, or the time and effort needed to go from conceptual request to tangible product, a user experiences when generating a flood inundation map, has recently received a near exponential level-up in difficulty over the last decade with the small renaissance of geospatial flood modeling methods, timelined out in Figure 1. Geospatial Flood Modeling, as opposed to hydraulic flood modeling, utilizes local, focal, and zonal operations commonly introduced in map algebra curriculum, whereas hydraulic flood modeling typically solves some form of the shallow water flow equations in open channels and can be found in many engineering programs. Although once reserved for large scale analysis, with the trailblazer of the NWM - HAND - Synthetic Rating Curve demonstrations from the NOAA Office of Water Prediction lead to a dramatic increase in research efforts which formalized and published a number of methods to map a flood (Afshari et al. (2018); Rebolho et al. (2018); Jafarzadegan and Merwade (2019); Schumann et al. (2013); Bhatt et al. (2017)). These methods may occasionally emerge from the same organization, but are more commonly created for slightly different use cases, use slightly different terminology, take different pathways towards technical realization, and perhaps most frustratingly, all deploy their drivers in different forms. It is this last point in particular, that each method currently requires its own dedicated input stream, that makes intercomparing models particularly challenging. To overcome that friction, we propose a framework for interoperable flood mapping efforts which unify these into a set of common input choices which can be easily parsed and passed between methods.
The Historical Trajectory of FIM: NFIE to FIM4
The national flood interoperability experiment (NFIE) was a collaborative partnership across federal, state, and academic partners to explore how broad scale inundation mapping might be executed within the federal river forecasting enterprise (Maidment (2017)). In 2015, a “summer school” was convened in conjunction with the newly constructed National Water Center on the University of Alabama Campus in Tuscaloosa, Alabama. Alongside federal staff and a cadre of professors and practitioners, a cohort of graduate students was able to demonstrate a potential pathway towards performant, street scale inundation predictions with a demonstration that with a Height Above Nearest Drainage surface and associated basin, a synthetic rating curve could be constructed relating the hydraulic relationships with the geospatial model of terrain height (Rennó et al. (2008); Nobre et al. (2011)).
After those initial successes, the Office of Water Prediction, academics, and private sector developers took ownership over flood inundation prediction and began operationalizing those research efforts into a more modern codebase. That saw the program evolve from notebook and prototype code to a hardened and documented orchestration pipeline using ESRI ArcPy software to generate predictions. At the same time, academic efforts largely driven by OakRidge began exploring more performant ways to generate CONUS scale predictions using open source geospatial utilities within the context of the High Performance Computing environment OakRidge develops as shown in Figure 2 (Liu et al. (2018)).
Between the development of FIM2 and FIM3, the use of the services gained more widespread adoption and the academic publication train caught up to the state of the science and several of the most critical gaps in the approach became more prominent. Many correctly identified poor rating curve predictions as a large source of error (Scriven et al. (2021); Ghanghas et al. (2022)), but evaluations typically failed to account for the complex forecasting chain and conflated the prediction of discharge with the skill of the FIM library. Visually, it also became apparent that the HAND domains were easily susceptible to “glass walling” as shown in Figure 3 (Garousi-Nejad et al. (2019)). This results because HAND domains are defined by watershed bounds, and so when the predicted height of the water meets those areas, the calculation and resulting maps can only expand upwards. When this glass walling occurs, it creates large visual anomalies and artifacts that immediately detract from the perceived trustworthiness of the map. To address this, new drainage paths were calculated so that a more consistent drainage source would be represented in a prediction, shown in Figure 4.
<SpatRaster> resampled to 500364 cells.
|---------|---------|---------|---------|
=========================================
The next major iteration of the HAND repository saw more hardening and formalizing, including rebranding to the current day FIM4 repo. It also saw a full expansion and generalization off that “mainstems” concept to each stream order in the network subset. Those (Strahler) stream orders were isolated into “branches”, and each branch could now comprise a holistic flood library. This “Generalized Mainstems” - or GMS, provided improved skill at critical evaluation sites but saw the relative size of the national flood inundation library grow far larger than the visualization systems and operating costs could permit. These findings prompted the removal of that “Full Resolution” (now called “branch 0”) library, in addition to all stream order 1-2 branches, drastically cutting down on library size while still maintaining explicit predictions for the major river network of the unit as shown in Figure 5.
|---------|---------|---------|---------|
=========================================
The Automation of Tradition: Advances in Automated Hydraulic Modeling
At the same time the advances in the geospatial baseline were being developed, automation of hydraulic model FIM generation was also undertaken. The hydraulic modeling community maintains their own domain concerns, and the “gold standard” for accuracy codifies HEC-RAS as the de facto platform through which modeling activities take place. Traditionally, these models were manually intensive and reach-specific. However, the need for national coverage has resulted in several options that automate the construction of FIM from these traditional engineering scale efforts.
The RAS2FIM system emerged to bridge this gap, automatically formatting and executing HEC-RAS 1D models using densified boundary conditions to generate standardized depth grids. Parallel efforts, such as the open-sourcing of ripple1d (Dewberry 2024), exposed deeper model parameters, allowing for more defensible inundation libraries. Simultaneously, in the coastal domain, SCHISM (Semi-implicit Cross-scale Hydroscience Integrated System Model) transitioned from research to operations, utilizing unstructured meshes with over 10 million nodes, shown in Figure 6, to provide explicit Total Water Level (TWL) forecasts (Leijnse et al. (2021)).
A Harmonious View of the Future
These rapid advancements in the tooling and techniques raise the ceiling in terms of capabilities, but by the same hand also increase the needed technical skill and further push the implementations towards specialized formats and domain specific silos. We have reached a state where the various domains have favored models that are used as the gold standard benchmark against which other efforts are measured. These might provide the “best” (most true to our shared spatial reality) prediction of their system but without an interoperable layer or shared representation of the landscape, and an accessible means of executing, interpreting, and communicating those predictions we silo those advances and waste time, money, and talent that actively hinder forward progress on working our wicked problem.
The hydrofabric and the national water model provide a meaningful step forward towards harmonizing the prediction space, but only variations in pre-canned snapshots of mapping those predictions have been undertaken. It’s standard practice to use bulk mosaics and spatial priority lists to create a final inundation map, but this shared representation of landscape features presents an opportunity to more intelligently couple data, domains, and concerns
Conclusion: Painting the Future Landscape
The “Painting the Landscape” metaphor serves as a useful framework for future FIM operations. In this view, traditional career roles once drew hard lines between domain expertise and technical workflows. However, national-scale forecasting transcends these boundaries. It is no longer appropriate to isolate a “bad discharge forecast” from a “poor map”; the map consumer perceives only a single product. By harmonizing forecasts with HAND-shaped FIM libraries, it provides a bridge between research-grade modeling and the rapid cadence required for emergency response. As we move from an era of “model vs. model” to one of “model ensemble integration,” the focus shifts from the mechanics of map generation to the utility of the information in moments of crisis.
Chapter 2: RRASSLER
Abstract
HEC-RAS models are the benchmark for hydraulic modeling applications but, due to the way the data is passed to the application, format billions of dollars’ worth of data collection and analysis in forms not amenable to utilization outside the direct usage of a HEC application. Additionally, modeling efforts even up to today utilize legacy formats but in doing so lock those efforts behind technical walls as the evolution of computational sciences leads to new data and more efficient formats and processing architectures to store, distribute, consume, and archive the data that are critical to model execution. These advances often lead to new use cases for those data, which have a rich legacy and can be costly to collect, collate, and archive; but the form of that initial deployment sometimes makes integrating those original data into newer use case workflows difficult. Those conflicting values create a need to make those model data more accessible and reusable, and a need to increase their findability and accessibility, a manifestation of the FAIR data principles. This paper will demonstrate how legacy HEC-RAS one-dimensional model datasets are transformed and made more FAIR for uses in workflows across the NOAA flood inundation mapping efforts and in the development of a nationwide 3D hydrofabric dataset that provides channel geometry between deep channel and its floodplain.
Graphical Abstract
Introduction
With the evolution of computation and scientific advances, it’s inevitable that the data and tools deployed at one point in time will eventually be depreciated in favor of more performant workflows, new data formats, and updated representations of the world. However, there’s still a huge amount of value, both direct and indirect, in reusing some of that data within the newer workflows. One example of this evolution can be found in the hydraulic modeling application and artifacts of HEC-RAS. Since its first release in 1995, users have created models using public and private data and countless hours of engineering scrutinization in order to generate the best possible purpose-built representation of the world (Brunner 1995). Like any model, some level of input manipulation is necessary in order to get the data into the specified mathematical format a model requires. Like most domain specific software, that manipulation results in data that modern geospatial data readers (such as GDAL) are unable to handle. This adds a great deal of overhead, both conceptually and technically, particularly when you take the standpoint of a model consumer.
F.A.I.R., or Findable, Accessible, Interoperable, and Reusable, are a series of adjectives describing principles and requirements for data users that, while broadly applicable to the entire life cycle of an analysis, are primarily aimed at enhancing how users programmatically interact with a data set (Wilkinson et al. 2016). Like any adjective, there are varying intensities of FAIRness, and application specific requirements modify how FAIR a particular representation might be. Our intended data models are applications which use HEC-RAS data to automate FIM generation (RAS2FIM), and for natural cross section representations within the hydrofabric representations (Blodgett et al. 2021). This places extra emphasis on the Findability and Accessibility of those principles, while the extraction to point form facilitates reuse of that core data across other efforts.
HEC-RAS data is unique in that although it encodes spatial information, it is neither a standard spatial data format or strictly representative of space. This makes using and accounting that data quite difficult. Additionally, archives of HEC-RAS models are rarely similarly formatted, with “value add” being specific to the archivist. There’s also no means of identifying whether a provided HEC-RAS model is already available, identical to our existing formats, or is compliant for a given use case. Imagine a case where you have an algorithm you’d like to use that needs some piece of data that a HEC-RAS model provides. In theory, this could encompass all the different facets of a valid HEC-RAS model, but since models are typically engineering and reach scale, where they fall in space is quite important. Archives such as the FEMA region 6 Base Level Engineering dataset serve models out in units that match HUC8 scales, although they also serve them out by political boundaries (counties) in some instances. For each unit, they provide 3 zipped archives. The most relevant for our task is the model data itself, sorted by reach name and model. The second, separate zip archive, includes model outputs in the form of rasters and geodatabases of spatial data (model cross sections and footprints), and the last separate zip archive includes documentation on the model development itself. While all three of these archives are valuable, one would need to download all three datasets and perform manual interrogations and develop crosswalks if you’d like to use spatial queries or attribute filters if you’d like to identify and access the relevant HEC-RAS model artifacts. Facilitating this sort of interaction is what we call “spatializing” a model.
Example uses of these models and the data include HEC-RAS itself, which needs all associated input files in order to rerun simulations and use that data as it was developed. Of course, one of the key pieces of data in a HEC-RAS model is channel geometry which could be reused across channel routing applications like T-ROUTE. Additionally, precipitation data and upstream discharge boundary conditions are stored in the rainfall files and would be invaluable in return period and design storm specifications. Our goal therefore is to more efficiently utilize that data across the different workflows that might be deployed. Although there are other resources that might accomplish pieces of this workflow, such as data readers as found in USACE/mcat-ras, fema-ffrd/ras-stac, and psu-efd/pyHMT2D, and versioning tools such as GitHub, none of these create a trackable artifact, transform the legacy data into a modern spatial format, or allow for seamless identification of the models spatial extent in a seamless manner. Therefore, the primary objective of this work is to prototype an approach that facilitates more FAIR patterns within and across the HEC-RAS data format. To do this, we develop and present an algorithm and workflow that ingests raw HEC-RAS models into a standard geospatial data format and anchors them to the National Reference Hydrofabric schema (Blodgett et al. (2021)). This is provided in a documented R-based software package, RRASSLER. The remainder of this article will describe this algorithm in greater detail, demonstrate how the tool is deployed over a model, and the resulting data structure and use cases this facilitates.
Methods (Software Design and Delivery)
Ingest logic
This section outlines the algorithm used to spatialize and account for a given model, elaborating on the package documentation. While it may be common to only have a single model that you’d like to interact with, it’s incredibly common to be given a zipped folder from a 3rd party that has many other vestigial data pieces and may be illogically organized or unsorted. Therefore, to start the program will recursively identify all files below the parent folder to identify the ones with a “.prj” extension. For each of those found files, we use the base name on that file to identify all files with a file extension that matches a “.g##” or “.g##.hdf”. The full list of files we identify is shown in Table 1.
| File grep Pattern (# denotes single numeric wildcard) | HEC-RAS Model Use |
|---|---|
| .g## | Geometry definitions |
| .prj | Projection (can be non-standard proj4 string defined file) |
| .prj | Project (same extension, defines how RAS models are wired) |
| .p## | Plan file, used to drive the model |
| .f## | Steady Flow file. Profile information, flow data and boundary conditions |
| .h## | Hydraulic Design data file |
| .v## | Velocity file |
| .o## | Output file |
| .r## | Run file for steady flow |
| .u## | unsteady Flow file. Profile information, flow data and boundary conditions |
| .x## | Run file for unsteady flow |
| .dss | Data files |
| .rasmap | Output plan |
If those files do not exist, the file we found is not part of a HEC-RAS model, and we move to the next file to process. If we do find a geometry (.g##/.g##.hdf) file, we parse out all .prj files with that base name to find the model units, which will always be found in a valid HEC-RAS project file, and projection files, which are rarely found. If there is no projection file and no default projection provided, there is not enough information present to attempt to spatialize that model without an excessive amount of assumptions on our part. Because we do not want to use a model we are uncertain about, our workflow stops here and so the model files are placed in “unprocessed” for future investigation and manual intervention. If we found all the information we need, we attempt to convert those files into a table with columns for cross section number, station, x, y, z, and n. If that conversation fails, that model is likewise placed in unprocessed. If it was successful and both the “.g##” and “.g##.hdf” files were found and converted, we select the table which has a lower normalized distance. Once we have the converted table, we attempt to create a footprint around the model bounds. If creating a footprint errors, we append the model name with a 3. If the footprint is generated, we attempt to join the model to a hydrofabric and select the first ID from the largest stream order. This workflow is diagrammed in Figure 7.
Note that this process and several of the other functions which take a path_to_ras_dbase argument are location agnostic. Therefore, although you will be operating over local files you may RRASSLE those into either a local directory or an S3 bucket using the same commands. RRASSLER also handles all “folder structure” differences between S3 protocols and disk representations, so the “bucket” argument can look just like a folder path or can be the “root” folder in an S3 URL and both are parsed out appropriately.
Results and Case Study
This section will describe the format of that RRASSLE’d directory and expand on several common use cases across CONUS scale applications. Additional resources on how these results are obtained and used are available in the package documentation. The RRASSLER catalog generates spatial data that includes the footprint of each record that contains pertinent, model level attributes as well as the name of the record that can be joined with the tracker sheet, shown in Figure 8. This gives us the accountability needed to deploy these HEC-RAS models in other workflows. Having constructed this, we’ll demonstrate two use cases where the RRASSLER database catalyzes those downstream workflows.
The first is a RAS2FIM run. RAS2FIM can iterate over multiple models but requires a homogeneous projection across the input data in order to generate the correct results and validating those inputs is beyond the scope of the tool. Without this RRASSLER catalog, users would have to parse the projection files in each database and remove the relevant files to their own directory for further processing. With a RRASSLER catalog, users can load the catalog and filter the records to the models within the domain of interest and grouped by projection and model unit. As one of the most common use cases for this data, RRASSLER also includes a wrapper, append_catalog_fields.R that can be used to construct the “OWP_ras_models_catalog.csv” that is used in that workflow.
Another common use case is the reuse of the channel geometry cross sections as transect for channel shape characterizations. The HEC-RAS and Hydrofabric data are complimentary but not immediately compatible and one of the most critical attributes needed for a hydrofabric transect is the stationing of that transect relative to the hydrofabric. However, HEC-RAS cross sections are relative to the models stationing and so they need to be cross walked to the new representation and renumerated so that each is uniquely indexed and addressable. RRASSLER facilitates this by allowing users to subset the cross sections to the desired streamlines and reindexed with the make_xs_hyfab_comp.R. function.
Discussion and Conclusions
Archives are only useful if the artifacts they collate are of value to end users. That value is diminished as end users experience technical friction integrating and interoperating between different databases into their applications. By spatially normalizing these models with accessible pointers back to source data, explicitly versioning different versions of the same model, and conflating that space into a CONUS scale framework, this work makes both individual archives and collections of archives more Findable, Interoperable, Accessible, and Reusable within native spatial applications like QGIS.
There are several aspects of this approach that are needed to harden and improve this approach. Aligning the different model realizations is hard. Although every effort was made to account for standard edge cases and unit cohesion, you will, more often than not, find that a surface you use and a model do not align. That is not particularly surprising, but it is often disconcerting. 3DEP timestamps, resolutions, and even order of reprojection operations may alter the surfaces slightly, even if they are stated to have come from the same input database. This effort spatializes and exposes the data used in the HEC-RAS model, but does not attempt to either validate or otherwise compare that to alternatives as a sanity check. Finally, although many of the functions of RRASSLER capitalize on cloud computing advances, one of the most problematic stages is the preprocessing and model data acquisition. It is impossible to identify if a model in a cloud repository is accessible or specialized without first downloading and (potentially re)processing it. A more efficient approach would involve location agnostic location processing, and avoid the need to scrape and locally provision all ingested data. At this point in time, the vast majority of publicly accessible HEC-RAS archives are formatted in these legacy forms, and only derivative outputs are typically provided in cloud accessible formats. Having cloud native alternatives to some of these operations, such as the ready extraction of arbitrary cross sections from a model archive. Although this facet by itself is not critical (or even counterproductive, you need the entirety of a HEC-RAS model if you want to run a RAS simulation and so a cloud-centric approach would still require this added data). Finally, this was developed, tested, and deployed over primarily 1D data and 2D models should not expect to be processed correctly.
Software availability
Name of software: RRASSLER Developer: National Oceanic and Atmospheric Administration (NOAA) Office of Water Prediction (OWP) Repository: https://github.com/NOAA-OWP/RRASSLER
Programming language: R License: Public Domain (US Government Work) Software prerequisites: R Core Team (2024). R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing, Vienna, Austria. URL https://www.R-project.org/.
Chapter 3: RAS2FIM: A Python-based Framework for Automating Flood Inundation Map
Abstract
HEC-RAS Base Level Engineering (BLE) models serve as a foundational resource for flood risk assessment across the United States. However, these models are typically disseminated with a limited range of flows representing specific return periods. These discrete flow increments create significant gaps in rating curves, making the deployment of a Flood Inundation Map from that model difficult for operational and real-time contexts. This paper presents RAS2FIM, a framework and tool used to generate flood inundation maps suitable for deployment using National Water Model (NWM) hourly operational streamflow forecasts. By automating the densification and extraction of flood depth rasters, RAS2FIM provides a programmatic means of tying legacy hydraulic engineering models to operational river forecasts.
Graphical Abstract
Introduction
Hydraulic models, specifically the Hydrologic Engineering Center’s River Analysis System (HEC-RAS), provide an authoritative means of creating a Flood Inundation Map (FIM). One of the most common forms of these models are Base Level Engineering (BLE) models, which form the baseline for flood insurance studies and risk assessments. These models are typically provided using a range of discharges representing specific return periods. Because HEC-RAS is a hydraulic solver, the process of creating a map takes time and it’s common to separate the map and the model, and deliver both as separate archives so that users who are only interested in the map do not have to perform the computationally expensive step of running the model.
Another common method of creating a FIM comes from the National Water Model (NWM). The NWM is a continental scale model that provides reach scale forecasts of discharge at operational cadences. One of the primary uses of that model prediction is a Flood Inundation Map. This map is constructed by taking that discharge and calculating a stage that is used to create a water surface elevation prediction, and mapping that prediction to the landscape. This map is used to aid emergency response efforts and forecast impacts for alerts and to help save lives and property. In order to do so, that map needs to be provided quickly and relevant to the resolution of the prediction.
These two techniques for creating a flood map are not immediately compatible. Flood maps from BLE models are typically provided using a range of discharges representing specific return periods. While effective for regulatory planning, the discrete flows they model create large gaps in the resulting rating curves. This makes utilizing the model outputs difficult in that operational flood mapping context, which typically aim to resolve flood stages to half a meter. Furthermore, competent mapping and scaling of these models are often limited to manual interactions and small (watershed scale) domain sizes. This individualistic model access pattern, combined with the relative computational intensity that hydraulic solvers implement, results in an overly complex and intensive process that greatly increases the amount of investment needed to use these models as Flood Inundation Maps (FIM).
With no off-the-shelf solution for integrating these efforts, these challenges almost universally result in the disuse of these models and the underutilization of the billions of dollars of investment that went into the creation of them. To address this shortcoming, we propose a framework to help bridge the gap between these distinct modeling paradigms, the hydraulic engineering scale and the continental hydrologic scale. To address this shortcoming, we present a framework and software solution, RAS2FIM, with the goal of demonstrating how these efforts can be reused and made interoperable within this operational mapping context. The software functions as an automated, open source HEC-RAS mapper that runs models to densify boundary conditions, creating FIM libraries tailored to NWM access patterns. The remainder of this paper describes the framework RAS2FIM implements and examples of the outputs.
Methodology and System Architecture
The RAS2FIM framework utilizes HEC-RAS in a one-dimensional steady-state hydraulic analysis to determine a reach-averaged depth and inundation map library. The workflow is orchestrated via a series of Python scripts that execute seven sequential steps to transform raw HEC-RAS models into flood inundation libraries usable by the National Water Model. That sequence is diagramed in Figure 9 below, and includes the major steps and conceptual choices a user can make.
Geometric Extraction and Hydrofabric Conflation
The RAS2FIM pipeline starts by scraping the input directory to identify relevant HEC-RAS projects. The system determines the geometry set in the active plan as defined by the HEC-RAS model and, if necessary, computes the plan to generate the required Hierarchical Data Format (HDF) files needed by more modern versions of the HEC-RAS utility. From that transformation, stream centerlines and cross-section vector geometry are extracted and merged into shapefiles to establish the spatial footprint of the hydraulic models. To identify the portions of the HEC-RAS model that are relevant to the NWM forecast, the NWM streamlines that intersect the HEC-RAS model footprint are selected and points are placed along it at 150-foot intervals along both lines. Points from the NWM streamlines are snapped to the HEC-RAS river points and the model which has the greatest count of snapped points becomes the conflated feature to use, as shown in Figure 10. This process also identifies what cross sections of the parent HEC-RAS model are most up- and downstream of the conflated reach so that excessively long models can be appropriately trimmed. This subset of the parent HEC-RAS model now forms the definition for the child HEC-RAS model we will use to create our inundation models.
Terrain Acquisition and Processing
If a user does not supply a terrain file, RAS2FIM automatically acquires bare-earth DEMs via the United States Geological Survey (USGS) 3DEP service as shown in Figure 11. The data is retrieved for relevant HUC-12 watersheds, reprojected to the coordinate reference system of the HEC-RAS model, and converted to the requisite HDF5 compliant form for HEC-RAS terrain files.
Synthetic Rating Curve Generation
In order to generate a “synthetic rating curve” critical to the definition of a flood inundation library, we simulate the model across a densified range of discharges. The “parent” HEC-RAS model is treated as a monolith, where input model boundary conditions are densified to create tighter increments of flow. The system takes the maximum flow from the conflated model, multiplies it by a factor of 1.2, and divides the result into 75 evenly intervaled flow values to run the model, visualized in Figure 12. For the analysis, all flow is considered sub-critical, and downstream boundary conditions are set assuming a normal depth with an energy slope of 0.5%. From each run, a reach-averaged depth is calculated for each discharge. This data results in a first-pass rating curve.
Inundation Mapping and Simplification Using those first pass rating curves, the flow needed to create the more evenly intervaled FIM access patterns is calculated and a second HEC-RAS simulation is executed using the interpolated flow rates. The RAS Mapper engine is utilized to generate inundation boundaries for those equal-interval stages. To ensure the resulting data is suitable for web-based dissemination, the output rasters undergo a simplification process compliant with Interagency Flood Risk Management (InFRM) standards. The depth grids are re-projected to WGS84 Web Mercator (EPSG:3857), resampled to a 3-meter cell size, and converted to 16-bit unsigned integers. In this format, the integer values represent decimeters of depth (metric) or tenths of a foot (SI), significantly reducing file size while maintaining vertical precision Wallace (2022).
Map Quality Assessment
The framework includes a module to calculate terrain statistics, addressing potential discrepancies between the terrain used in the mapping process (either user supplied or USGS 3DEP terrain, step 3A&B) and the terrain used to develop the HEC-RAS geometry as extracted from the cross section. The script compares those elevations to calculate the vertical error. If the median, mean, or standard deviation of the error exceeds a defined threshold, the resulting FIM library could be flagged for potential exclusion.
Results
The results of a sample RAS2FIM run are included in the repository and demonstrate how the single model used in this test example is conflated and generates the described data. These models cover areas in both Texas and Iowa and include mixed units and projections to enable testing of various common HEC-RAS formats and BLE configurations. A full HUC8 process output is shown in Figure 13, where HUC 12090301 was processed from end-to-end.
Discussion
The RAS2FIM implementation is one of many ways to conflate model and map space, and the conflation of those is made with several critical assumptions regarding both model structure and methodology. Specific to the model structure, the program limits itself to running only steady-state, one-dimensional models; unsteady flows and two-dimensional models are not currently supported. Additionally, while it will respect bridge, culvert, and inline structures in the hydraulic calculations, storage areas and lateral structures are not represented in the child models. To facilitate bulk programmatic processing the utility also expects all inputs to be in the same projection.
The utility also makes several assumptions in the methodologies used to conflate model and map space. The utility will attempt to best conflate each provided HEC-RAS model with the appropriate NWM feature, but it will do so even for models with low snap counts, including areas with poor model-to-model alignments, confluence areas. It will also arbitrarily chose the first model in a process run if two models tie with a forecast feature. Finally, parent HEC-RAS models that are very long relative to the length of the NWM forecast feature or those which have a significant lateral inflow represented may under-parameterize discharge, resulting in maps which underestimate the inundation extent or the range of discharges intended in the HEC-RAS calculated rating curve.
Only steady-state one-dimensional models can be evaluated; unsteady and two-dimensional flow areas are not currently supported. While the system accommodates bridges, culverts, and inline structures, it ignores storage areas and lateral structures. Additionally, all input models for a given pipeline run must share the same geographic projection.
In creating the crosswalk to conflate the hydraulic scales of the parent HEC-RAS model and the NWM forecast feature, the process may return an incorrect HEC-RAS model match in areas with low counts of snapped points, such as confluences, or arbitrarily select a single model when two models “split” a forecast feature. Finally, long length models and models which have significant inflows represented in the parent model may under parameterize discharge, resulting in maps that do not inundate far enough up the rating curve or that underpredict for upstream conditions.
Conclusion
RAS2FIM demonstrates a programmatic means of using compliant HEC-RAS 1D models to generate flood inundation maps suitable for deployment with NWM operational discharge forecasts. By automating the translation of steady-state hydraulic engineering models into pre-computed inundation libraries, the framework allows for the scaling of high-fidelity flood mapping beyond the limitations of manual, point-and-click interactions. RAS2FIM demonstrates a free and open, programmatic means of reusing compliant HEC-RAS 1D models as flood inundation maps suitable for deployment within the NWM operational flood inundation workflows. By automating the translation and execution of engineering scale hydraulic models to a CONUS scale prediction framework, compatible Flood inundation libraries can capitalize on the high-fidelity flood knowledge of these efforts without the tedious and error prone processes of the HEC-RAS point-and-click interface.
Software Availability: Name of software: RAS2FIM Developer: National Oceanic and Atmospheric Administration (NOAA) Office of Water Prediction (OWP) Repository: https://github.com/NOAA-OWP/ras2fim Programming language: Python License: Public Domain (US Government Work)
Software prerequisites:
- HEC-RAS: The software relies on the HEC-RAS computational engine (Version 5.0.7 or later) developed by the U.S. Army Corps of Engineers (USACE).
- OS: Windows 10/Server (required for HEC-RAS COM automation).
Data Availability:
The datasets generated during and/or analyzed during the current study are available from the following sources:
- HEC-RAS Models: The local hydraulic models used as input were sourced from FEMA Region 6 and the Iowa Flood Center.
- Hydrography: The National Water Model (NWM) stream network data is available through the NOAA Office of Water Prediction.
- Terrain Data: Bare-earth digital elevation models (DEMs) were accessed via the USGS 3DEP Web Coverage Service (https://elevation.nationalmap.gov/arcgis/services/3DEPElevation/ImageServer/WCSServer).
- Generated Inundation Maps: The final processed flood inundation depth grids and synthetic rating curves generated by the RAS2FIM workflow are available at
Chapter 4: Model Breakup Strategies Evaluation in RAS2FIM
Abstract
The integration of legacy HEC-RAS hydraulic models for use in National Water Model (NWM) Flood Inundation Mapping (FIM) workflows provides a scalable pathway to capitalize on these Hydraulic scale models at the Continental United States (CONUS) scale. However, the methodology used to “break” large, complex hydraulic models into segments aligned with NWM reach IDs introduces potential errors. This paper evaluates two distinct strategies developed within the RAS2FIM framework: Version 1 (Physical Subsetting), which creates standalone “child” models, and Version 2 (Monolithic Processing), which extracts data from full model simulations. We analyze the error introduced in this process by executing these two approaches over the same parent model and evaluate the differences in stage from the resulting reach averaged synthetic rating curves (SRCs). Results show that the physical subsetting offers improvements in computational efficiency and increases in potential inundation map coverage but introduces artifacts at high discharges, particularly within the lowest stations of the model due to truncated boundary conditions and loss of downstream controls.
Introduction
Historically, Flood Inundation Mapping (FIM) has been a localized, gage-dependent endeavor. The advent of the National Oceanic and Atmospheric Administration (NOAA) National Water Model (NWM) has shifted this paradigm by providing hourly streamflow forecasts for over 2.7 million reaches across the United States, greatly increasing the predictive potential and enable stream level access to critical inputs needed to execute and access flood inundation libraries. To translate these flows into actionable depth maps, the RAS2FIM framework was developed to automate the conversion of existing HEC-RAS models into NWM-compatible flood libraries. A primary challenge in this automation is the spatial mismatch between the hydrofabric used by the NWM and the river stationing of legacy HEC-RAS models. This requires a strategy to associate specific model reaches with specific NWM reach IDs.
However, conflating these hydraulic models, which are typically constructed for local consumption, is not a direct process. HEC-RAS models are typically a higher resolution than the CONUS scale framework used in the national water model, and conflating them to this coarser resolution is not a standardized or straightforward process. This paper investigates the hydraulic implications of two conflation strategies, quantifying the error introduced when a continuous hydraulic model is segmented prior to its use.
Methods
The RAS2FIM Framework
RAS2FIM utilizes Python-based automation and the HEC-RAS API to process potentially thousands of models. Version 1 of the workflow involves conflating parent HEC-RAS models to the NWM forecast features, generating subset children models relative to that feature, and running the model across a range of discharges before averaging out the resulting model to a reach average rating curve and generating the resulting inundation maps shown in Figure 14. Version 2 (Figure 15) treats each model independently and attempts to apply reach averaging during execution.
Version 1: Physical Subsetting (Child Models)
In V1, the system identifies the “parent” HEC-RAS model most representative of an NWM reach. It then performs a physical “slice” of the geometry, extracting the relevant reach plus a buffer of two cross-sections upstream and downstream. These slices are saved as independent HEC-RAS projects. In that process, a normal energy grade line is used to set the downstream boundary condition.
Version 2: Monolithic Processing
Version 2 maintains the integrity of the original “parent” model. The entire model is simulated as a single monolith. Post-simulation, the depth rasters and rating curves are clipped and indexed to the NWM hydrofabric. This approach preserves the longitudinal hydraulic connectivity and any backwater effects present in the original engineering study.
Metrics
To quantify the deviations this process introduced, we compared V1 and V2 outputs using the National Water Model feature-based access patterns, comparing the residual (∆WSE = V2wse - V1wse) and generate visualizations to identify where and how these approaches vary, both spatially and hydraulically.
Results
Plotting the surface differences between V1 and V2 as shown in Figure 16 indicate a consistent positive bias, where the monolithic V2 approach generally predicts higher water surface elevations than the subsetted V1 approach but is flow-dependent; while the models remain relatively aligned at lower discharges where flow is contained within the primary channel, the error magnitude increases as discharge approaches the upper limits of the model as seen in Figure 17. Spatially, these deviations are concentrated at the downstream-most stations of the models.
Discussion
This comparison reveals distinct hydraulic deviations driven by the choices in model conflation and processing. While all models are unique, the variations found in this model indicate meaningful variations in the different ways hydraulic models are constructed and executed. Plotting the surface differences between the two versions indicates a positive bias across this model where the monolithic V2 approach predicted higher water surface elevations than the subsetted V1 approach and was discharge dependent. This bias was not spatially uniform but increased as the model length increased and were concentrated at the downstream-most stations. The V1 workflow, by virtue of its smaller, independent “child” models, required less memory and processing time per simulation (01 mins 42 secs vs 04 mins 30 secs). However, the loss of longitudinal connectivity and the resulting 1–2 foot elevation errors suggest that these efficiencies come at the cost of significant accuracy given the half-foot intervals that the resulting Flood Inundation Library aims to represent. This is perhaps unsurprising given the control downstream boundaries have on subcritical flow calculations.
Conclusion
The transition from Physical Subsetting (V1) to Monolithic Processing (V2) represents a significant methodological in the accuracy of large-scale FIM. While V1 is computationally cheaper for localized updates, the “breakup error” introduced by physical segmentation can exceed 1-2 feet in elevation at peak discharges, particularly in areas with complex backwater conditions. For national-scale implementation, we recommend the V2 monolithic approach as the standard for generating Synthetic Rating Curves. V1 should be reserved for high-gradient, headwater reaches where downstream boundary conditions have minimal impact on upstream profiles, or when more complete coverage of the domain is a primary objective.
Chapter 5: Assessment on the Impact of Access Patterns on Categorical Flood Mapping
Abstract
The libraries of predictions made from a Flood Inundation Model are only as useful as the access patterns they expose. Traditional accuracy assessments tend to favor large geographic processing aggregations and a handful of well cited metrics to assign the skill. This favors libraries and assessments which cater to the entirety of the modeling pipeline or models which have well-aligned drivers and favorable locations. This glosses over a skillful mapping workflow that incorrectly penalizes libraries that would otherwise perform well by decoupling the hydrologic, hydraulic, and geospatial drivers from the map creation process. By being more intentional about how we use these libraries, we can harmonize disparate Flood Inundation Mapping efforts into a unified operating picture. This approach shifts the focus from the mechanics of modeling and forecasting to the communication of map generation.
Introduction
With the operational deployment of the National Water model, Flood Inundation Mapping has evolved to provide predictive coverage for 100% of the COntinental United States (CONUS). For a map to be useful it should reflect spatial reality and one of the ways that reflection of reality is reported is an accuracy assessment, comparing the generated map to a known ground truth or measurement. However, most assessments gloss over or conflate the model prediction pipeline and aggregate many different flood maps into a singular score (e.g.: (Aristizabal et al. (2023); Baruah et al. (2025))).
This standard practice in assigning a single value loses the ability to distinguish skill across space and flow regimes, and risk discarding otherwise very skillful maps or placing too much trust in maps which perform well but fail to capture the system for the current set of conditions. One of the ways we can address this shortcoming is to better communicate the “access pattern” used to create the map from the flood inundation library. Furthermore, with a more nuanced access pattern we can greatly increase the accuracy of a map and circumvent the cascading errors and uncertainties associated with integrated hydrologic/hydraulic modeling. To demonstrate this, we will assess the accuracy of 2 novel categorical flood libraries against a more established and traditional source of categorical flood inundation.
To perform this assessment, we use 3 different forms of a stage based flood inundation library. The first, a gage based library from the Partner FIM repository provided by NOAA . These libraries are commissioned by regional, state, and local partners; typically generated specifically for the site which also hosts a river monitoring gage, and receive special attention and QA/QC as they are more limited in scope than automated alternatives such as base level engineering models. Because these are extensively validated and frequently consulted during events, practitioners place a lot of weight in the predictions they make. The objective of this analysis is to quantify the performance of several categorical FIM libraries against the AHPS ground truth and demonstrate how an informed use of library access helps improve the skill of the prediction.
Our second form of categorical flood maps are generated from FLDPLN libraries. FLDPLN is a library that only provides a stage based prediction (Kastens (2008)). To transform that into a categorical prediction the stage of the gage is used to calculate a stage/volume rating and that value is interpolated up and downstream from the target gage to generate layers of stage. These are cropped and indexed to the network much like the Partner FIM. The most widely available form of categorical flood map is derived from the office of water prediction HAND libraries. These libraries provide predictions of both a discharge and a stage and are scoped for the national water model forecast elements. The objective of this analysis is to quantify the performance of HAND and FLDPLN against the AHPS ground truth using the MNTK1 gage site as a case study. These various categorical FIM libraries are shown in Figure 18.
Access patterns Flood forecasting is a complex workflow even at the site-specific level. Correct geodesic measurements, unit conversions, precision, projections, and feature indexing all require intentional handling to ensure a correctly executed workflow and the potential for missteps only increases as we expand the boundaries of our analysis. These cascading concerns are critical to the modeling efforts but end up confounding the process of mapping and introduce their own errors as we attempt to qualify the skill of a prediction. This is particularly frustrating as the end user of maps only cares about how true to their spatial reality the predicted map is and will quickly dismiss the entire pipeline regardless of the methods used to generate it if that expectation is not met. To isolate the impacts of these access patterns, the categorical flood maps will be compared using both a direct numerical access pattern and a mapped stage access pattern.
Methods
To compare how the different access patterns impact the accuracy of prediction using the different forms of categorical flood predictions, we apply two separate access patterns. The first, and most traditionally deployed method is a direct numerical stage access pattern, where the value of the gage is used to access and then compare binary flood maps. The second is a mapped stage access, where that stage is transformed to a water surface elevation, and that water surface elevation is mapped to the rest of the flood library. This ensures that library specific variations are circumvented and we can select the most appropriate library for the shared space these inundation maps represent.
Results and Discussion
Direct numerical stage access
Comparisons using the gage read stages are processed for every elevation and plotted in Figure 19 (FLDPLN) and Figure 20 (HAND).
Mapped stage access
Figure 21 shows the spatial distribution of the confusion matrix for FLDPLN CATFIM and Figure 22 shows the same process for the HAND categories.
Finally, we compare the accuracy of these different approaches across the full range of shared values in Figure 23
Conclusion
The HAND accuracy is notably lower at the top of these ratings as it intentionally masks out the leveed areas for operational deployment and also extends far above the established maximums of the other categorical inundation libraries. This validation highlights that while terrain-based models like HAND offer a scalable alternative to gage-based FIMs, systematic biases in low-flow stages remain a challenge. Future work should focus on integrating these methodologies to create a hybrid, ensemble-based FIM.
Chapter 6: Conclusions and Next Steps
This dissertation addresses some of the systemic “technical friction” that historically isolated localized hydraulic engineering from national-scale geospatial forecasting. The transition from reach-scale modeling to a National Water Model framework required more than just increased computing power; it required a paradigm shift in how model data is stored, processed, and communicated. In chapter 2, the development of RRASSLER demonstrated that legacy HEC-RAS data still has substantial value for flood inundation modeling efforts at the national scale and could be made more accessible and reusable. By “spatializing” these models and anchoring them to a common hydrofabric, we established that findability and interoperability are critical for operational deployments. In chapter 3 we introduced RAS2FIM, a framework that extends engineering scale hydraulic models and makes them amenable to flood mapping efforts and automated deployments within a national flood modeling framework. In chapter 4, we quantify the loss in accuracy caused by moving from the initial hydraulic scale to the national water model scale, finding that downstream boundary conditions can greatly impact the generated operational flood library relative to the hydraulics represented in the larger hydraulic model. In Chapter 5 we show that flood map accuracy is a function of the access pattern used and not merely a library-to-library aggregation, and more sophisticated and intentional mapping choices can improve statistical scores.