A two-dimensional agent-based model of flocking under predation, developed to investigate the dynamics of collective turning. First presented in the paper:
Papadopoulou M, Hildenbrandt H, Hemelrijk CK (2023) Diffusion during collective turns in bird flocks under predation. Frontiers in Ecology and Evolution 11 (2023): 1198248. https://doi.org/10.3389/fevo.2023.1198248
- Operating system: Windows 10.
- Graphic card with support for OpenGL 4.4 or later.
To build the software under Linux (Debian packet system):
~$ sudo apt install libtbb-dev
~$ sudo apt install libglm-dev
~$ cd ColT
~/ColT$ make
~/ColT$ make install # creates the excecutable ./bin/Release/starlings
This model is based on self-organization and includes bird-like and predator-like agents. Agents interact with their surrounding neighbors based on the rules of attraction, alignment and avoidance. Prey-agents flock together and avoid the predator. Predator-agents chase and attack prey-agents. Catches of prey are not modelled. Each individual behaves according to the 'state' it is in, for instance normal flocking or escaping. Each state consists of a collection of specific actions that an agent follows, for instance alignment and attraction.
The model consists of 3 timelines: action, update, and integration. At each action time step, prey agents may switch to a different state for a specific duration. While being in a state, an agent collects and updates its information about its environment at each reaction time step. At the beginning of a reaction step, an agent calculates an aimed position and heading. Between 2 reaction steps, individuals move from their current positions and headings towards their aimed ones. This happens gradually across several [dt] integration time steps. Thus, an action step may include several reaction steps, and a reaction step includes several integration steps. Some states, such as normal flocking, are transient: an action step includes one reaction step; the agent might switch state at each reaction time step. Other states, such as an escape maneuver, are persistent: an action step includes several reaction steps. Their duration is controlled through the parameter file.
The switch between states depends on a transition matrix that gives a probability of each agent to switch state given its current state and its distance to predator (reflected on a [stress] value, unique for each prey agent). The closer the predator is, the highest the value of stress.
All user-defined parameters are parsed by combining a series of .json files: config.json (simulation parameters), starling.json (prey parameters, starling used as an example) and predator.json (predator parameters). Distance is measured in meters [m], time in seconds [s] and angles in degrees [deg].
Actions are the basic elements controlling the movement of each agent in the simulations. Each action represents a steering vector so that the weighted sum of all actions controls the agent's motion. Each action has each own user-defined parameters. Multiple actions are combined to create states. The majority of actions control the interactions between agents (coordination between prey-agents, escape actions of prey-agents from the predator-agents, and hunting actions of the predator-agents towards prey-agents). The model is based on topological interactions.
Prey-agents actions:
-
Avoid actions:
- avoid_n_position: the individual turns away from the position of its topo closest neighbors if they are in distance smaller than minsep. Parameters: topo (number of neighbors to take interact with), fov (field of view), maxdist, minsep, w.
-
Align actions:
- align_n: the individual turns towards the average heading of its topo closest neighbors. Parameters: topo (number of neighbors to take interact with), fov (field of view), maxdist, w.
-
Cohere actions:
- cohere_centroid_distance: the individual turns towards the center of the positions of its topo closest neighbors. The strength (w) of this action is scaled on the distance between the focal individual and the center of its neighbors. Parameters: topo (number of neighbors to take interact with), fov (field of view), maxdist, w.
-
Non-interacting actions:
- wiggle: the individuals turn by a random angle controlled by the weight of this steering force that is perpendicular to the agent's heading, sampled from the range [-w,w]_. Parameters: w.
-
Turning/Escape actions:
- relative_roosting_persistant: individuals are attracted towards a point defined by a distance and a direction relative to their position when they enter the state that includes this action. Parameters: home_dist, home_direction, w.
- random_t_turn_gamma_pred: individuals perform a turn with angular velocity defined by a random angle and duration, both sampled by a gamma distribution. Parameters: turn_mean, turn_sd, time_mean, time_sd.
- copy_escape: if one of the topo closest neighbours of an agent is in an escape state, the agent enters the same state at the next reaction step. Parameters: topo, fov, max_dist.
Predator-agents actions:
-
Avoid actions:
- avoid_closest_prey: the predator turns away from the position of its closest prey. Used in states where the predator should not hunt the prey. Parameters: w.
- set_retreat: the predator is repositioned at a given distance away from the flock and given a new speed. Parameters: distAway, speed.
-
Non-interacting actions:
- wiggle: the individuals turn by a random angle controlled by the weight of this perpendicular to the agent' heading steering force, sampled from the range [-w,w]_. Parameters: w.
- hold_current: the agents tries to hold a constant position. Parameters: w.
-
Hunting actions:
- select_flock: the predator chooses a flock as its target. Selection can be made based on the flock's size or proximity. Parameters: selection.
- shadowing: the predator follows (or tries to follow) its target flock from a given angle and distance, keeping a constant speed that scales from the speed of its target. Parameters: bearing (angle starting from the flock's heading), distance, placement (whether to automatically reposition the predator to the given shadowing position), prey_speed_scale, w.
- chase_closest_prey: the predator turns towards the closest starling-agent at every time point (target) and moves with a speed that scales from this agent's speed. Parameters: prey_speed_scale, w.
Note: The model is currently set to simulate roosting turns (referred to as circular evasion in the paper).
States in the model are defined as combinations of actions. Persistent states have a user-defined duration, whereas Transient states can change after a time-step. The transition between states is controlled by the user-defined transition matrix. Prey-agents start from a normal flocking state, and as their stress increases, they switch to an escape state. After that, they get into a persistant flocking state that works as escape penalty.
The hunting strategy of the predator is built on a chain of persistent states that makes the predator behave deterministically: follow the flock from a distance, attack, retreat and start over.
The initial conditions of the agents are controlled by the user. Prey agents are initiated in a flock formation, within a circle and with similar headings.
- PgUp: speed-up simulation
- PgDown: slow-down simulation
- Space: pause/continue simulation
- Right Arrow: run 1 simulation step
- A: darkens background
- T: shows/hides the position trail of each prey-agent
- Shift+T: shows/hides the position trail of each predator-agent
- K: kills or revives predator-agents
- 1: applies colormap of id of prey-agents
- 2: applies colormap of speed of prey-agents
- 4: applies colormap of state of prey-agents
- 5: applies colormap of flock id of prey-agents (which flock each individual belongs to)
- 6: colors the prey-agent that is the target of a predator
- Shift+1: applies colormap of id of predator-agents
- Shift+2: applies colormap of state of predator-agents
The model exports data in .csv format. It creates a unique folder within the user-defined data_folder (in the config.json), in which it saves a single .csv file for each Observer, as defined in the config file. Sampling frequency and output name of each files are also controled by the config. The config is also copied to the saving directory.
In its current state, the model exports (1) timeseries of positions, heading, speed etc for each agent, (2) diffusion-related metrics.
- Dr. Marina Papadopoulou - Contact at: m.papadopoulou.rug@gmail.com
- Dr. Hanno Hildenbrandt