From trickle to torrent: Unlocking the power of flood simulation

REANNZ is helping advance river modelling approaches with faster scripts, live monitoring tools, and reducing hours of processing into minutes.

Research background

Water underpins nearly every aspect of life — from transport and irrigation to energy, cooling, recreation, and ecosystem health.

Associate Professor Jon Tunnicliffe studies how rivers behave under pressure: predicting flood events, tracking pollutant spread, and understanding how environmental change reshapes gravel-bed river morphology.

His research combines fieldwork, laboratory experiments, and numerical simulation, with Delft3D-FM as his modelling tool of choice — a powerful, open-source suite used by researchers, consultants, regulators, and government agencies to manage riverine resources.

Image provided by Jon Tunnicliffe.

Project challenges

Delft3D-FM (Flexible Mesh) is an open-source hydrodynamic modeling suite that relies on a flexible, triangulated mesh to apply fine resolution only where needed. The code supports MPI parallelism for large-scale simulations.

Each simulation generates 10-100 NetCDF files, each containing data for one subdomain. Loading all the files in memory to produce summary graphics or a movie is time consuming and requires 100GB of memory or more. Jon contacted REANNZ to seek help with streamlining his postprocessing tasks so he could do more research in less time.

What was done

  • Architecting an asynchronous, event-driven framework:
    REANNZ transformed a series of linear Matlab post-processing scripts into a sophisticated, multithreaded Python application. A core achievement was the implementation of a decoupled "Watcher/Worker" architecture. This allows the application to perform heavy data-polling of the Mahuika filesystem in the background while keeping the user interface perfectly responsive. By managing asynchronous I/O, the team solved the persistent issue of "file-locking," allowing the researcher to monitor a live simulation without risk of interrupting the Delft3D-FM engine or causing system crashes.
  • Engineering in-situ reassembly of distributed data:
    A significant technical hurdle in Flexible Mesh (FM) modeling is the fragmentation of data; a 32-way partitioned simulation creates a dataset spread across dozens of NetCDF files. REANNZ developed a specialized engine to dynamically "stitch" these partitions together in-situ on the Mahuika cluster. This logic performs real-time spatial remapping, translating local sub-domain indices into a unified global mesh. This allows the researcher to query multi-million cell domains as a single, coherent object without moving data off the cluster, effectively eliminating the heavy download/transfer requirements and the hours previously spent on manual reassembly.
  • Memory Ooptimization via lazy loading and geometric processing:
    To address the "memory greed" of the previous workflow, the team moved away from memory-intensive rasterized images and instead leveraged the native triangular mesh geometry across all processing steps. By implementing "lazy loading" (smart indexing via the netCDF4 library), the tool now "peeks" at the results as they are written. This architectural shift reduced the memory footprint from over 100GB to mere megabytes, allowing high-resolution diagnostics that once required a supercomputer to be performed on a standard laptop.
  • Implementation of advanced mathematical diagnostics: 
    The consultancy went beyond simple visualization to implement production-grade mathematical kernels. These include automated volume and mass estimates and flux evaluations. Fluxes are computed by expanding edge velocities in terms of "Whitney forms," ensuring that the diagnostics are mathematically consistent with the Delft3D-FM solver’s internal physics. This allows the researcher to extract high-fidelity insights such as bedload transport rates and morphological changes with greater precision than was possible in the legacy Matlab environment.
  • Professionalisation and software rigor:
    REANNZ transitioned the project from a collection of private research scripts into a professional, open-source Python package. The consultancy implemented a robust software lifecycle, including a CI/CD (Continuous Integration/Continuous Deployment) pipeline. Every code change is now automatically tested against a suite of unit tests and examples. This ensures long-term maintainability and gives the research group a stable platform that can be easily shared with international collaborators and expanded with novel diagnostic features..

A graph showing water depth comparisons.

Image provided by Jon Tunnicliffe.

 

Main outcomes

A set of performance optimised Python scripts that are easy to maintain, can be shared with collaborators, and can be expanded to add novel diagnostics. At the onset of the project, supercomputer was required to postprocess the simulation data – now postprocessing can run on a laptop.

Researcher feedback

The support provided by the REANNZ Consulting team has been transformative for my research workflow. In the past, I was running large-scale morphodynamic models blindly; I would submit a job to the cluster and wait hours or even days to see if it had succeeded, only to often find a numerical instability had ruined the run in the first minutes. The RunMonitor tool has now changed this paradigm.

By providing a real-time, transparent window into the simulation, I now have the confidence to monitor a model’s health as it evolves on the Mahuika cluster. One of the most immediate impacts has been the elimination of the data bottleneck. Traditionally, downloading results from a multi-million cell domain partitioned 32 ways was a grueling process. Now, being able to query and visualize the results stack 'in-place' on the cluster is a game-changer. It allows for a 'fail-fast' workflow: I can observe the morphological changes and bedload transport rates in real-time, making the decision to cancel and adjust parameters on the fly, which will potentially save me hundreds of hours of HPC compute time.

Beyond the software itself, the pedagogical value of this consultancy has been immense. The REANNZ team integrated me into the development process, teaching me how to interact with complex data objects and manage distributed datasets in an HPC environment. This has significantly upskilled me (and my research group), moving us from simply managing data to driving our simulations with greater technical precision. The scripts are 24 times faster and require a fraction of the memory. What used to take hours of post-processing on a supercomputer now happens in minutes on my laptop.

This project has optimized my entire creative cycle of discovery, and I hope we can continue this valuable partnership to push the boundaries of riverine modeling even further. The professionalism, technical depth, and responsiveness of the REANNZ team have exceeded all expectations.

- Associate Professor. Jon Tunnicliffe, Faculty of Science, Environment, University of Auckland

 


 

This case study shares some of the technical details and outcomes provided through our Consultancy Service. This service supports projects across a range of domains, with an aim to lift researchers’ productivity, efficiency, and skills in research computing. Get in touch to discuss how our Research Software Engineers and specialist support could help advance your project.

Find anything about our products, services, and more. Enter a query in the search input above.