Leveraging The Flood Modeller API For Efficient Model Review

Jack Brooks, Senior Flood Modeller at AtkinsRéalis

---

Introduction

One of the most time-consuming parts of model Quality Assurance (QA) is checking the model configuration, health, and result outputs. As computing power has grown so too has the scale of modelling studies, with more scenarios and design events now expected to meet client requirements. With that, manual review is no longer practical. At AtkinsRéalis, we’ve developed a suite of Python scripts that use the Flood Modeller API to automate these checks and give modellers rapid, actionable insights. In addition, we’ve produced scripts that leverage the consistent structure of Flood Modeller output files to programmatically parse and interrogate their contents.

Flood Modeller API script examples

Oscillation detection for flow and stage

Oscillations often signal instability. These scripts use the Flood Modeller API to parse results through result data (by calling the ZZN class or via the IEF class) to identify and plot spikes in the time series results based on a user-defined tolerance. Modellers can incrementally adjust the defined value to filter out minor fluctuations and focus on significant oscillations. Scripts for flow and stage outputs apply the same logic, offering a complementary perspective on model stability that can provide greater analysis in review to understand where time is best spend on helping to answer the clients study objectives (Figure 1, Figure 2). 

Automation allows for greater customisation in review: Flexibility in the script design or producing multiple variants of a script allow for a more tailored review process. Scripts can be written to assess the full suite of model results or to target specific reaches of the model.

User generated text files (i.e. Flood Modeller LNG files, typically produced to review multiple time series graphs or long section result outputs via the FM GUI) can be used to interrogate specific reaches of the model. This is particularly valuable for large catchments where tidal effects can distort axis ranges, making visual checks impractical.

Figure 1 - Time-Series With Detected Oscillations

*Left panel: Flow time-series with detected oscillation in a specified urban reach. Right panel: Equivalent stage time-series with detected oscillation. Results show limited warnings for the defined filtered stage oscillation threshold.

Figure 2 - Targeted review of model nodes within a time series where oscillations have been detected

Inspecting geometry at the speed

Accurate representation of the river profile is critical for hydraulic modelling. A focused set of DAT file plotting scripts that leverage the Flood Modeller API (DAT class) to pull geometry into view quickly allow for: verification of survey sections, scenario comparison and identification of erroneous inputs or unintended edits that could impact modelling results.

The need for comparison of the same cross‑sections across multiple DAT files is commonplace in hydraulic modelling. A simple script that can step through a user‑defined list of sections (called from an LNG file), to plot the same locations from several DATs, and advance to the next section allows for rapid review of the model (Figure 3). In essence the surveyor supplied DAT files can be compared to the final model in review and any scenario DAT files compared to the baseline model, to understand the modelled changes in geometry. The script can be customised to show shading and vertical dashed lines to distinguish inactive parts of a section. This can be useful in model review to understanding the decisions made in modelling and for model reporting.

Sometimes you don’t need multi‑file comparisons; you need a river reach perspective, several sections in series from a single network to understand the change in river geometry over distance. This helps to more easily visualise any hydraulic constrictions to flow in the channel or help make sense of river levels through a reach. A script has been set up to select a single DAT file and specify a list of sections (from a LNG text file) and then presents the river profiles on a single plot so you can scan consistency along a reach. Python code offers the flexibility to quickly create variants of a script to optimise the viewing experience. This option has been deployed to standardise bed marker to the central x-axis point (x = 0) for easier visual alignment across section geometries. It’s a pragmatic fix for a common plotting pain point (Figure 3).

Figure 3 - Channel geometry plots

*Left panel: Multiple DAT section plots comparing the same cross section between survey and model scenarios. Right panel: Cross section plots for a watercourse reach with channel bed positions standardised along the x‑axis.

Non API scripts examples

Diagnostic file (ZZD) summary extraction

Before diving into modelling results, it is prudent we verify the run itself. To help originators and reviewers in QA, a python script has been produced to extract key information from diagnostic log files across a directory. Instead of opening individual diagnostic logs, this script collates essential simulation details (such as the Flood Modeller version, simulation start time, event data files, model conversion issues, and mass balance errors) and presents them in a single summary. Collating the output in a simple pop-out text window or CSV file (Figure 4), allows the user to quickly eyeball any nonconformities or user input error to simulation (IEF) files, which is common in large projects. This global approach means you can review the full suite of scenario runs in one go, forgoing the need for random spot checks. In addition, the collated nature of the output means you can share the findings more succinctly with the wider team or format the information for final deliverables, such as Model Passport naming convention and simulation input tables.

Figure 4 - Simple pop-out text window summary of ZZD results

Diagnostic file (EXY) summary outputs - convergence checks where it matters

Convergence problems can be noisy over a full hydrograph, but what matters most is their proximity to peak conditions. This script reviews EXY result files and identifies 1D nodes with poor model convergence, providing both a count and the time range over which issues occur. (Figure 5) This is particularly useful for sense-checking model stability around peak events, where convergence problems can have the greatest impact on results for flood risk studies. The script also returns a total count for the entire model, giving modellers a quick indication of overall performance. This script provides the user rapid high-level insights into whether the identified instability in relation to timing in the events is a concern for further investigation. Caution should however be employed where flood risk in the catchment is volume driven. Flexibility in the script allows for single event reporting or assessment of the full suite of design events in a scenario.

Figure 5 - Simple pop-out text window summary of EXY results

Common Themes In Scripts

Across all AtkinsRéalis scripts and tools a few principles stand out. Scripts leverage an integrated GUI (Tkinter) interfaces for file selection, user‑defined settings and pop-out text windows, making the tools flexible and accessible, replacing hard‑coding where possible.

Multiple variants of scripts exist to suit different project demand, whether that’s batch processing, interactive plotting, or reach‑specific checks. Therefore, the workflow can scale from quick sense‑checks to full scenario reviews. Together, these themes reflect a focus on automation, adaptability, and usability without compromising technical rigour.

Closing Thoughts

Together, these scripts optimise the way we approach model review. Instead of sifting through logs and graphs manually, modellers can now run targeted checks that highlight potential issues in minutes. This not only accelerates the QA process but also improves confidence in model outputs by ensuring that convergence and oscillation problems are identified early.

By embedding these tools into our modelling practice, we’re reducing review times, improving consistency, and freeing up time for interpreting results and delivering robust solutions for our clients.

AtkinsRéalis is constantly finding smarter, more innovative ways to streamline modelling workflows and deliver clearer insights into flood risk for our clients. With artificial intelligence breaking down many of the traditional barriers to writing effective code, the real differentiator is no longer technical capability, it’s creativity.

---

Jack Brooks

Jack is Senior Flood Modeller in the Water Management Consultancy team at AtkinsRéalis with over 8 years’ experience in flood risk and hydraulic modelling.

Jack is a technical specialist delivering fluvial modelling studies through the NGSA Collaborative Delivery Framework and Modelling & Mapping Framework. He combines strong expertise in flood risk modelling with Python-based automation to improve efficiency and consistency in model build and analysis. As an active contributor to AtkinsRéalis’ flood risk technical network, Jack shapes modelling methodologies and provides guidance on best practice and innovation.