This repository contains a FLAME GPU 2 implementation of the Circles agent based model, to visualise the model benchmarked in https://github.com/FLAMEGPU/FLAMEGPU2-circles-benchmark and extract drift data for plotting.

There is a single experiment within this example which mean measures drift of the agents per time step. This gives an indication of population stability and convergence towards a stable state. The communication radius is varied to show how this effects the emergent behaviour of the populations.

If the example is built with the CMAKE FLAMEGPU_VISUALISATION option enabled then the experiment runs a single experimental configuration with a fixed communication radius.

An example visualisation can be viewed on YouTube.

The is an example of raw data in the sample/data directory with a description of the machine configurations used to generate it in each directory.

The results below are from a RTX 2080 Ti.

• Communication Radius is varied between 1.0 and 5.0 with a step of 1.0
• Population size is fixed at 64000
• Environment width is fixed at 40.0
• The number of simulation steps is 3000
• 10 simulations are completed with unique seeds for each communication radius

Detail of dependencies and the cmake build process are described in full in the FLAMEGPU2-example-template repository and are not repeated here. For visualisation purposes, this should be built with visualisation enabled (e.g. -DFLAMEGPU_VISUALISATION=ON) and seatbelts off (e.g. -DFLAMEGPU_SEATBELTS=OFF passed to the cmake configuration step) to disable additional run-time checks.

For example, to build for Volta (SM_70) GPUs under Linux:

# Configure 
cmake . -B build -DCMAKE_BUILD_TYPE=Release -DFLAMEGPU_VISUALISATION=ON -DFLAMEGPU_SEATBELTS=OFF -DCMAKE_CUDA_ARCHITECTURES=70
# Build
cmake --build build -j`nproc` 

The generated binary can then be executed to run the visualisation, which will begin paused. Press p to unpause (or re-pause) the simulation.

cd build
./bin/Release/circles-benchmark-vis

Detail of dependencies and the cmake build process are described in full in the FLAMEGPU2-example-template repository and are not repeated here. The benchmark should be built with seatbelts off (e.g. -DFLAMEGPU_SEATBELTS=OFF passed to the cmake configuration step) to disable additional run-time checks.

For example, to build for Volta (SM_70) GPUs under Linux:

# Configure 
cmake . -B build -DCMAKE_BUILD_TYPE=Release -DFLAMEGPU_SEATBELTS=OFF -DCMAKE_CUDA_ARCHITECTURES=70
# Build
cmake --build build -j`nproc` 

Running the generated executable will run the benchmark and generate output files:

cd build
./bin/Release/circles-benchmark-vis

This will produce a number of .csv files in the build directory.

Note: The FLAMEGPU2_INC_DIR environment variable may need to be set to ./_deps/flamegpu2-src/include/ for run-time compilation (RTC) to succeed if the source directory is not automatically found.

Figures can be generated from data in CSV files via a python script.

It is recommended to use python virtual environment or conda environment for plotting dependencies.

I.e. for Linux to install the dependencies into a python3 virtual environment and plot the results from all experiments output to the build directory.

# From the root of the repository
# Create the venv
python3 -m venv .venv
# Activate the venv
source .venv/bin/activate
# Install the dependencies via pip
python3 -m pip install -Ur requirements.txt
# Plot using csv files contained within the build directory
python3 plot_publication.py -i build -o build/figures
# Use -h / --help for more information on optional plotting script parameters.

The sample figures were generated from the root directory using

python3 plot_publication.py -i sample/data/2080Ti-11.4-471.41/alpha.2-2080Ti-11.4-beltsoff -o sample/figures/2080Ti-11.4-471.41/alpha.2-2080Ti-11.4-beltsoff