A reimplementation of the agent-based flood incident management (https://github.com/nclwater/FIRM) model in Java for DAFNI (https://www.dafni.ac.uk/).
The FIRM2 project re-implements the NetLogo-based FIRM agent-based flood simulation model in Java, and embeds it in a Docker image for running on DAFNI.
The model consists of roads, buildings, vehicles, defences, terrain and water, all of which are modelled as agents. Agents are defined as probabilistic finite state machines with the probability of being in a given state. Vehicle agents are parameterised using data from the National Travel Survey (ONS and DfT 2008) which gives sample diaries of travel patterns for households, defining the travel patterns and responses during flooding events. Defences have probabilities of being destroyed during flooding, and buildings may enter a "flooded" state.
Floodplain flows are described in terms of continuity and momentum equations, discretised over a raster grid of square cells, which allows the model to represent 2-D dynamic flow fields on the floodplain. Flow between two cells is a function of the free surface height difference between those cells. Traffic is simulated using an implementation of the Nagel-Scheckenberg model which describes a 1-D cellular automaton governing the behaviour of vehicles in a road network.
The model coordinates the agent behaviour in a time-stepped simulation, producing patterns of flooding, traffic movement, and agent responses to blocked and flooded parts of the road network.
The original implementation of the model was made in NetLogo to investigate risk-based flood incident management approaches. This implementation was a conversion of the original to Java to run in a Docker container on DAFNI, with configuration and model data re-implemented in JSON. The new implementation will run faster, be available to a wider community, be expandable with other flooding models and agent behaviour, and the conversion to Java offers a more accessible language for further development.
The FIRM2 model is inteded to be used to conduct scenario-based flooding simulations to study the behaviour of traffic populations during flood incidents. The model can explore the impact of a flood event, in terms of number of people exposed to floodwater, according to the time of day, different storm surges and defence failures. Water levels, traffic movement and barrier breaches can be examined. The benefits of issuing flood warnings can be tested, whilst the benefits of different evacuation shelters for saving lives and managing traffic congestion can be explored. The FIRM2 model is standalone and does not require any other models in a workflow.
The model is supplied with a sample simulation of an area around Towyn, Wales, UK, with the data being derived from the following sources.
| Data | Source | Use |
|---|---|---|
| Flood defence location | Environment Agency’s National Flood and Coastal Defence Database | Defining flood defence location and breach locations |
| Flood defence fragility | Dawson and Hall (2006) using data from Conwy County Borough Council | Flood defence performance under different storm surge conditions |
| Digital Elevation Map | Interferometric Synthetic Aperture Radar (IfSAR) data and Local Authority manhole surveys from Conwy County Borough Council | Topography |
| Transport network | OS MasterMap | Location, connectivity, capacity |
| Property type | Environment Agency’s National Property Database | Type of property: whether residential or the type of non-residential property use |
| Property location | Environment Agency’s National Property Database | Eastings and northings co-ordinates of each property |
| Depth-damage function | Multicoloured manual | Damage functions, conditional on flood depth for each property type |
| Vulnerability function | DEFRA | Conservative estimate of exposure was used here. A more detailed function integrating over depth and velocity could be established |
| Population profile | UK census | Number of residents in Towyn. Age profile and employment profile were used to classify transport groups. More detailed studies could use the information on population age and other demographic data to improve the vulnerability assessment |
| National Travel Survey 2008 | Department for transport | Travel patterns for different age, employment and genders |
| Web Interface to Census Interaction Data | The Centre for Interaction Data Estimation and Research | Number of journeys from residence ward to employment ward from census data |
| 1990 Flood outline | Conwy County Borough Council | Validation of flood spreading model |
The model produces log files using the Java slf4j library with the Java native logging functionality (java.utility.logging) which records the results of the simulation. The log files are created in the /data/outputs subdirectory which can be saved as a DAFNI data set using a "Publish" Workflow element. The log files structures can be defined in the logging.properties file. Presently the model records "finest" and "info" logs. The "finest" level includes all simulation events such as state changes, car movements, car strandings, path recalculation events etc. This is the level of output recording that most users will be interested in. The "info" level records lesser activity such as file loading and data processing. Users can configure the level of recording as necessary.
Typical log output will look similar to the following:
Car car4754 loaded, shortest path start: 4000000012473527 end: 4000000012843869 [Fri Oct 10 14:41:44 BST 2025]
Car car4852 loaded, shortest path start: 4000000012472924 end: 4000000012843759 [Fri Oct 10 14:41:44 BST 2025]
Car car4951 loaded, shortest path start: 4000000012862319 end: 4000000012862564 [Fri Oct 10 14:41:44 BST 2025]
Ouch the road is flooded, car car407 reroute from 4000000012862303 distance 0.0 [Fri Oct 10 14:41:44 BST 2025]
Error: Out of bounds for 249 179. x=-4 y=176 [Fri Oct 10 14:41:44 BST 2025]
Ouch the road is flooded, car car2017 reroute from 4000000012536903 distance 0.0 [Fri Oct 10 14:41:44 BST 2025]
Ouch the road is flooded, car car1082 reroute from 4000000012863129 distance 60.0 [Fri Oct 10 14:41:45 BST 2025]
The DAFNI model does not produce any visualisation output, however an example visualisation tool is built into the code and can be run locally. This produces a raster output with the terrain, road network and traffic.
To run the simulation locally on Linux with the visualisation on the X11 display needs to be exported from the docker container.
- Add the directive
ENV DISPLAY=:0to theDockerfile - Change the
run:target in the use the recipe$(DOCKER) run -d --rm -v "${PWD}/data:/data" -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=${DISPLAY} --name $(image_name) $(image_tag) - Set
VISUALISE=truein.firm2.properties
These options have no meaning when running the simulation on DAFNI so are excluded from the model by default.
The project is funded by the UKRI "Building a secure and Resilient World strategic theme.
Links:
DAFNI resources:
Contacts:
- Project: Richard Dawson (PI) <richard.dawson@newcastle.ac.uk>
- RSE: Jannetta Steyn <jannetta.steyn@newcastle.ac.uk>
- Richard Dawson <richard.dawson@newcastle.ac.uk>
- Olivia Butters <olivia.butters@newcastle.ac.uk>
- Jannetta Steyn <jannetta.steyn@newcastle.ac.uk>
- Robin Wardle <robin.wardle@newcastle.ac.uk>
Java JDK 17
Apache Maven
Docker
Unix make
- Any platform with a Java Runtime Engine (JRE) suitable to run JDK 17 compiled Java code.
- An up-to-date installation of Docker.
- Apache Maven for building the Docker image. Apache Maven installation instructions can be found at https://maven.apache.org/install.html
For running on DAFNI you will need a [DAFNI account[(https://www.dafni.ac.uk/dafnilogin/).
There is a Makefile with directives for building, running, saving and stopping the container:
make build: Thebuildcommand compiles the code using Maven and creates a.jarfile. It then builds a Docker image callednclwater/firm2:x.xxx, where x.xxx is the version. There is arun.shfile which will be copied into the image and will be executed when the container runs.make run: Theruncommand will create and run a container calledFIRM2.make save: Thesavecommand will save the container to a.tarfile and thengzipit. A file calledfirm2.tar.gzshould be created that can be uploaded to DAFNI.make stop: Thestopcommand will stop a docker container with the nameFIRM2.
The program does not need installation as such. It is packaged as a .jar file with all dependencies included, which can be copied to a directory and executed from there.
The program's configuration files need to be modified to establish paths to relevant data files. For both running locally and within a Docker container, the two configurations files .firm2.properties and logger.properties have to be in the user directory. That is the same directory from which the program is being run. Edit these two files with the appropriate values before running or Dockerising the application.
Important: the following VM option must be added to the command line:
--add-opens java.desktop/java.awt=ALL-UNNAMED --add-opens java.desktop/java.awt.color=ALL-UNNAMED
The program is packaged in a .jar file and can be run either from the command line or by double-clicking on the .jar file in a file system GUI, as long as the JRE is installed on the system. If a JRE is required, the download and installation instructions can be found on Oracle's website.
On Linux, assuming a suitable runtime environment is installed, one can run the program from the command line using the run.sh script. For testing the program DAFNITest is executed which creates a file in /data/inputs and another in /data/outputs. To run the actual Firm2 model line 2, in the run.sh file should be uncommented and line 3 should be commented.
To run the model inside a Docker container, use make run as explained above.
The application is intended for Dockerisation to run on DAFNI. However, it can be run locally using a JRE of the correct version.
FIRM2.jar is a java executable that is packaged in a docker container for upload into DAFNI. The creation in the GitHub repository of a new release will execute a GitHub Action that will:
- use Maven to compile and create the
FIRM2.jarfile - create, save and zip a docker image
- upload the image along with the DAFNI model definition file to DAFNI using the DAFNI model uploader
The model can be configured with a number of parameters. Local builds read the file .firm2.properties, which DAFNI models read parameters from a parameter set defined in model-definition.yml. The configurable parameters are:
| Parameter Name | Display Name | Type | Description |
|---|---|---|---|
| TOROIDAL | Toroidal wrap | boolean |
Defines the map boundary conditions. If True, connects the upper map edge to the lower map edge, and the left map edge to the right map edge. |
| TICKS | Ticks | integer |
The number of simulation steps (ticks) to run. If this is zero, the simulation will run forever. |
| VISUALISE | Visualisation | boolean |
Specifies whether the simulation should be run through the visualisation display. Not available on DAFNI. |
| CELL_SIZE | Cell size in metres | integer |
The size of the simulation cell size. Smaller cell sizes result in a higher resolution map but take longer to simulate. |
| CHANCE | Chance | float |
Model-specific event triggering threshold. Currently only used in the Nagel-Schreckenberg example. |
| APPLICATION_TITLE | Application title | string |
The name of the application to display in windows or logs. |
| INPUT_DATA | Input data | string |
Full path to the simulation input data in the FIRM2 model. |
| OUTPUT_DATA | Output data | string |
Full path to the simulation output data in the FIRM2 model. |
| TERRAIN_DATA | Terrain data filename | string |
Name of the JSON file containing FIRM2 terrain data. On DAFNI this will be in a dataset referenced by the model. |
| ROADS_DATA | Road data filename | string |
Name of the JSON file containing FIRM2 road data. On DAFNI this will be in a dataset referenced by the model. |
| ROAD_TYPES | Road types filename | string |
Name of the JSON file containing FIRM2 road types data. On DAFNI this will be in a dataset referenced by the model. |
| BUILDINGS_DATA | Building data filename | string |
Name of the JSON file containing FIRM2 building data. On DAFNI this will be in a dataset referenced by the model. |
| DEFENCES_DATA | Sea defences data filename | string |
Name of the JSON file containing FIRM2 defences data. On DAFNI this will be in a dataset referenced by the model. |
| MODEL_PARAMETERS | Global parameters data filename | string |
Name of the JSON file containing FIRM2 global parameters data. On DAFNI this will be in a dataset referenced by the model. |
| VEHICLES_DATA | Vehicle data filename | string |
Name of the JSON file containing FIRM2 vehicle data. On DAFNI this will be in a dataset referenced by the model. |
| TIMELINE | Timeline data filename | string |
Name of the JSON file containing a FIRM2 events timeline. On DAFNI this will be in a dataset referenced by the model. |
| VEHICLE_FLOOD_DEPTH | Vehicle flood threshold in metres | number |
The depth of water at which inundated vehicles will be immobilised. |
| SLOWDONW | Slowdown | float |
Number of seconds to wait after each simulation "tick". Primarily for slowing down the simulation when VISUALISE=True. |
| TIME_STAMP | Time stamp | integer |
Unix time stamp of the initial simulation step |
| TICK_TIME_VALUE | Tick time value | integer |
Duration of a simulation tick (step) time in seconds. |
| OCEAN_DEPTH | Ocean depth in metres | integer |
Depth of the ocean in metres. |
| RUN_ON_STARTUP | Run on startup | boolean |
Indicate whether the simulation should launch immediately on run, or whether user intervention is required. Not available on DAFNI. |
make build will compile a secondary application that will generate data for testing purposes. This application can be run as
java -cp ./target/FIRM2.jar TimeLineGenerator
It uses the timelinelogger.properties file for logging configuration.
The parameters that can be entered are:
| Option | Description |
|---|---|
| Time | Starting timestamp for |
| Sea Level | Depth of sea in metres |
| Number of Defence Breaches | Number of barriers breached at this time stamp. The IDs are specified in a secondary input box |
| Defence IDs | Unique IDs of the defences |
| Number of cars | Integer, how many cars are in the simulation |
| Car Id start | Integer, id number of the first car |
| Itinerary Legs | Number of trips each car makes (random destinations) |
When complete for this Time Stamp, select "Write to Timeline". When a Timeline is complete, it can be written to a file with the "Write timline to file" option.
- Select development environment
- Develop basic agent modelling framework
- Create docker environment for model to run on DAFNI
- Implement FIRM model
The main branch should be considered stable and a representation of production code. The main branch is protected and requires a reviewer. Please complete the submission form with details of the pull request including linked Issues (see below) and tests that have been performed.
Contributions should be linked to an Issue in the repository issues list.
This repository does not use a "dev branch". Contributions must be produced in feature branches and you should follow the "branch early and often" maxim. Branches should generally contain a small enough contribution to the project that a branch's lifespan is measured in days, rather than weeks or longer. Branches should be named after the feature being added, preferably with the contributor's initials and ideally containing the Issue ID that is being addressed.
An exception to the branch-pull request workflow is minor changes to README.md files and other documentation to correct spelling and formatting errors and suchlike - these changes can be performed in the GitHub editor.
Further reading on branches, and versioning.
Towyn dataset on DAFNI is CC BY-NC-SA.
This code is licenced under the terms of the GNU Affero General Public License as published by the Free Software Foundation. See LICENCE.txt and COPYING.md for further details.
Please cite the associated papers for this work if you use this model.
- Dawson, R.J., Peppe, R. & Wang, M. An agent-based model for risk-based flood incident management. Nat Hazards 59, 167–189 (2011). https://doi.org/10.1007/s11069-011-9745-4
- Butters, O., & Dawson, R. J. (2025). Flood Evacuation in Informal Settlements: Application of an Agent-Based Model to Kibera Using Open Data. Urban Science, 9(1), 12. https://doi.org/10.3390/urbansci9010012
This work was funded under the UKRI / STFC "Building a Secure and Resilient World" strategic theme, project reference ST/Y003799/1.