Flood Modeller Logo

Flood Modeller API on a page

In a nutshell... Flood Modeller API is a Python package that provides a bridge between Flood Modeller and the Python programming language to extend the capabilities of Flood Modeller in automated workflows.

Getting started

  • Try it online with Codespaces...
    Launch a ready-to-use web-based IDE via GitHub Codespaces for one-click setup and no local installation.
  • ...or install the API locally:
    Use any Python 3.10+ environment and install with:
    pip install floodmodeller-api
  • Follow the tutorial notebook:
    A Getting Started Jupyter notebook is available in the GitHub repo and preloaded in Codespaces. It covers:
    • A basic Python primer
    • Intro to the floodmodeller_api package
  • Explore the documentation:
    Visit api.floodmodeller.com for full user docs.
  • Python knowledge needed:
    You’ll need fundamental Python skills, but even basic knowledge is enough to begin using the API.

Core classes/functionality

DAT
Work with .dat network files. Allows reading and editing unit properties (e.g., global Manning's n updates or custom changes), adding/removing units, or creating new blank networks. Includes tools for exploring connectivity between units.
IEF
Interact with .ief simulation files. Supports reading/updating simulation properties, referencing new event data, batch-generating IEFs, and running simulations either in a queue or with full subprocess control. Provides direct access to logs and results for end-to-end workflows.
IED
Handle .ied event files. Similar to the DAT class, with functionality to read, edit, update, add, or remove event units. Useful for automating scenario generation.
ZZN
Work with 1D results in .zzn format. Offers fast reading and export to CSV or directly into a pandas DataFrame for analysis. Supports efficient result filtering by variable, type, node, or timestep.
XML2D
Access and modify Flood Modeller’s 2D model .xml files. Allows reading and updating properties, adding/removing elements, and simulating 2D models. Follows the XML schema structure and validates against the Flood Modeller 2D schema.

Example use-cases

Increasing complexity

Quick & Dirty Scripts

One-off scripts written and run by the same user:
  • Adjusting values in a network
  • Extracting results
  • Creating a new suite of simulation files

Automated Tasks

Reusable scripts maintained by teams:
  • Automated reporting
  • Sensitivity run setup
  • Results analysis

Bespoke Tools

Standalone tools for non-coders:
  • Optimisation tools for parameter tuning
  • 'One-click' model builder

Wider integration

Integrating functionality into larger applications:
  • Operational dashboards
  • Live forecasting
  • Automated model generation (e.g. CAD-driven)

Find out more & get involved

Start using the API today and share it with your colleagues. You can explore the GitHub repository and read through the API documentation to get started.

Watch the mini-tutorials

Need support?

Share and collaborate

  • Join the 'Show and Tell' on section on GitHub Discussions page to showcase your code and ideas.
  • Got improvements? Open a pull request to contribute directly to the API's development.

Cheat sheet