A Data-Inspired Framework to Simulate Collective Behaviour of Predator-Prey Systems

Abstract

The collective escape of prey from predators is a classic example of adaptive behavior in animal groups. Across species, individual prey have evolved a large repertoire of evasive maneuvers to evade predators, and predators have evolved a series of hunting strategies to overcome them. With recent technological advances, empirical data on collective escape and cooperative hunting are increasingly becoming available, and large variation in the collective dynamics of different predator-prey systems is apparent. Computational models to link rules of individual behavior and collective patterns through self-organization are needed to understand this variation, but system-specific characteristics are rarely included in agent-based models of collective behavior. To tackle this challenge, we introduce a framework named DaNCES, that uses individual-based state machines to model spatiotemporal dynamics of collective predator-prey interactions. We implement it in a highly optimized software and pair it with an R package to facilitate its use. A synthetic agent in our framework can switch its behavior between continuous and discrete reactions through a dynamic Markov chain, depending on its local information. The flexibility and structure of our software allow substantial changes in a model with minimal code alterations, supporting the link between empirical data and theory. Overall, DaNCES is a valuable tool toward a standardized methodology to identify the underlying mechanisms of collective escape and cooperative hunting across species, enabling the link between individual behavior and eco-evolutionary dynamics, and offering bio-inspired solutions for autonomous artificial swarms.

Introduction

Protection against predators is considered a main driver of animal aggregations. Complex spatiotemporal patterns often emerge by self-organization (Couzin & Krause, 2003) when groups of prey are coordinating while trying to avoid one (Storms et al., 2019) or several approaching predators (Hansen et al., 2022; Licht et al., 2024; Handegard et al., 2012; Thiebault et al., 2016). The difficulty in collecting empirical data on these systems has led to many gaps in our understanding of collective behavior in predator-prey interactions in nature (referred to as collective escape).

Although the first model that reproduced patterns of collective escape in fish schools was published more than 20 years ago (Inada & Kawachi, 2002), only few studies have attempted to model patterns of collective escape or hunting since (e.g., Bartashevich et al., 2024; Couzin & Krause, 2003; Hemelrijk et al., 2015; Herbert-Read et al., 2015; Zheng et al., 2005). These models have usually been generic, even though escape reactions (Cheng et al., 2016; Hedenstrom & Rosen, 2001; Papadopoulou et al., 2022a) and hunting strategies (Buchanan et al., 1988; Mills et al., 2019; Zoratto et al., 2010) differ among and even within species (e.g., context-specific evasive maneuvers; Domenici, 2010; Domenici et al., 2011). With technological advances (e.g., unmanned aerial vehicles and underwater cameras; Papadopoulou, Ball et al., 2025) enabling the collection of empirical data of predator-prey interactions across many systems (Hansen et al., 2023; Handegard et al., 2012; Sankey et al., 2021; Licht et al., 2024), we should establish a better link between data and theory. However, species-specific adjustments (Gyllingberg et al., 2023; Hildenbrandt et al., 2010; Papadopoulou et al., 2022b) in an existing computational model of collective behavior can be time-consuming and challenging, given that it increases the complexity of the model. Simultaneously, overfitting a model to data may compromise the identification of self-organized mechanisms or restrict the value of a model to a ‘single-use’ validation of empirical observations, delaying advances in the field and limiting model comparisons (Grimm et al., 2005).

Most agent-based models of collective animal behavior are based on the rules of attraction, alignment, and avoidance (Couzin & Krause, 2003; Reynolds, 1987). Given that species differ in their dynamics of collective motion (e.g., the shape and density of a group; Papadopoulou, Fürtbauer et al., 2023), mere changes in a model’s parameters are often not enough to realistically simulate a group of a specific species. Adjustments in the interaction rules according to empirical findings may be necessary (Papadopoulou et al., 2022b; Pettit et al., 2013; Sankey et al., 2019). There are several ways in which collision avoidance in a flock may be modeled; for instance, an individual may avoid collisions by turning away from the position of its neighbor, by aligning with the heading of its neighbor, or by decelerating. How these modeling decisions affect the emerging spatiotemporal dynamics of a group has rarely been systematically investigated. Additionally, most computational models of collective behavior assume that individuals are identical, even though individual variation in specific traits within a group has been identified in many species (Jolles et al., 2020; Sankey et al., 2019).

To develop a model of collective escape based on an empirical system, the specifics of reaction of individual prey to the predator should be empirically known or theoretically derived. Most models represent the escape of prey from the predator by a single behavioral rule with which the prey avoids a predator haphazardly. This rule is either ‘continuous’, such as a tendency to turn away from the predator’s position (Inada & Kawachi, 2002; Zheng et al., 2005) while it also interacts with other group members, or ‘discrete’ (also referred to as ‘fixed’), such as an instantaneous turn that ‘interrupts’ the regular coordinated motion of the group (usually applied to study wave propagation, e.g., Herbert-Read et al., 2015; Hemelrijk et al., 2015). The escape reactions we see in nature may be based on both continuous and discrete cognitive rules; which type of escape reaction individuals perform when their group is under attack is hard to detect in empirical data. Additionally, more complex escape maneuvers (e.g., protean motion, Herbert-Read, Ward et al., 2017; Jones et al., 2011; Mills et al., 2018) are rarely modeled in the context of collective behavior since our understanding of coordination during them is lacking. Similarly, empirically-driven hunting maneuvers (Mills et al., 2018) are rarely studied in a collective behavior context (Bartashevich et al., 2024). Thus, in order to improve our modeling of collective escape, both continuous and discrete escape reactions and hunting strategies should be implemented.

Here, we recognize the necessity for a new software structure that can overcome the aforementioned barriers and support the community in studying the diversity of predator-prey interactions in animal collectives we see in nature (Figure 1). Such software should be flexible and easily adjustable to different species and ecological contexts. It should accommodate several types of individual motion, from continuous coordination to sudden escape reactions of prey or sequences of diverse attack strategies of predators. To achieve this, we have developed a modeling framework named DaNCES (Data-iNspired Collective Escape Simulations; Papadopoulou, Hildenbrandt, & Hemelrijk, 2024) for mixed-species systems of collective behavior through individual-based state-machines. We implement it in an optimized C++ software with a building-blocks structure (Berger et al., 2024), real-time visualization and data analysis, and highlight its potential to study collective escape. Extending on Papadopoulou, Hildenbrandt, & Hemelrijk (2024), we also expand on the collective escape from several predators (cooperative hunting) and provide details about the existing behavioral library, visualization and output of a model, and the analysis of simulated data. We also present an R package for running simulations across the parameter space of a model developed with DaNCES through R, the most used programming language in behavioral ecology (Lai et al., 2019). We use three agent-based models of bird flocks (Papadopoulou et al., 2022a; Papadopoulou, Hildenbrandt, & Hemelrijk, 2023; Papadopoulou, Hildenbrandt, Storms et al., 2024) to demonstrate the technical details and functionality that our framework offers.

Figure 1.

Examples of Predator-Prey Systems in Collective Behavior. Red Arrows Indicate Predators. (A) Aerial Displays of Flock of Dunlins (Calidris alpina) Reacting to the Attack of a Peregrine Falcon (Falco peregrinus). Screenshots Taken From the Video ‘Dance of the Dunlins’ (2013) by Ray Hamlyn. (B) A Flock of Corvids Turning away From a Robotic Falcon (Storms et al., 2022, Image Copyright Marina Papadopoulou). (C) Propagation of a ‘Diving’ Escape Wave in Schools of Sulphur Mollies (Poecilia sulphuraria) as a Response to the Attack of a Great Kiskadee (Pitangus sulphuratus). Screenshots Taken From Video by Doran et al. (2022). (D and E) Examples of Multi-Predator Aggregations (Licht et al., 2024; Hansen et al., 2023; Thiebault et al., 2016). (D) Terns (Onychoprion sp.) and Indo-Pacific Sailfish (Istiophorus platypterus) (Licht et al., 2024, Image Copyright Max Licht). (E) A Sea Lion (Zalophus californianus, Left) and a Stripped Marlin (Kajikia audax, Right) Attacking the Same School of Fish. Screenshot Taken From Video by Hansen et al. (2023) (Image Copyright Matthew Hansen)

The DaNCES Framework

Our framework is implemented in C++, using OpenGL for visualization and Dear ImGui (Cornut, 2024) for user interface, and can be accessed in our GitHub repo (Papadopoulou & Hildenbrandt, 2024). We further provide custom R code that enables users to run simulations across the parameter space of a model and load the model’s output into an R object for further analysis. It can be accessed at: https://github.com/marinapapa/DaNCES_simulator.

Internal States & Social Interactions

An agent in our framework is represented by its ‘internal state’. In the context of collective escape, this internal state consists primarily of the agent’s position and velocity in a global coordinate system. Since agents in computational models of collective behavior move in space based on their interactions with one another, we conceptualize an individual-level ‘rule’ in our model that can alter the internal state of an agent (and thus control its motion), as a stand-alone ‘internal-state control unit’ (referred to as an ISC-unit). Examples of such units are an alignment interaction (that makes the individual align its heading with its neighbors), a roosting behavior (that makes it turn towards its roost), or a noisy motion (that adds a random error to its heading). Each ISC-unit owns a set of parameters (e.g., the number of interacting neighbors or the position of the roost). We treat each internal-state control unit as a building block; the modeler combines the pieces of interest according to their study system. Thus, all available ISC-units can be simply used to build a new model or examine alternative interaction rules in existing models, while modeling new units is facilitated (by copying the main structure of an existing unit) and does not risk interfering with other functionalities of the software.

All social ISC-units need information about the social environment of the agent at each time point. To provide that, a set of neighbors’ information (neighbor_info) is defined and can be accessed by an agent (currently the id, state and stress of another agent, as well as the distance between them). An ISC-unit can access this information and indicate a set of neighbors for the agent to ‘sense’ (while_topo.hpp). For instance, at its current state, the framework supports metric and topological interactions along with the definition of a simple visual field: ‘neighbors’ are defined by a given number of agents (parameter topo), positioned within a given radius (parameter maxView), and within a field of view (an angle, parameter foV, e.g., prohibiting the sensing of individuals in the back). By parameterizing topo to be equal to the total population size and restricting the maxView one can have a ‘traditional’ metric model, and by setting maxView to a large value and restricting topo, a topological. These settings are ISC-unit specific, meaning that an agent can use different social information per behavioral rule (e.g., avoid collision with only a single neighbor but copy an escape maneuver from any surrounding neighbor). The list of all ISC-units currently available in the framework is given in Table 1, and we expect it to expand as new models are developed using this framework.

Table 1.

The ISC-Units Currently Included in DaNCES. Each Unit is Standalone and Could be Combined With Others to Create States. ISC-Units are called ‘actions’ in the Software and the Details of Their Parameterization are Given in the README File of the DaNCES Framework. We Aim for the Community-Driven Expansion of This List

ISC-unit	Function
Movement
wiggle	Turn by a random angle (noise).
altitude_attraction	Pitch towards a given global altitude; if further than a given distance to it, according to a smootherstep function.
level_attraction	Pitch to return to level flight (upwards or downwards).
roost_attraction	Move towards a given global position on the plane, if outside of a given radius around it.
roosting	Move towards a given global position (3D).
relative_roosting_transient	Move towards a global direction at a given angle relative to the flock’s heading at the time of the state’s entry.
relative_roosting_persistant	Move towards a global position at a given angle and distance relative to the flock’s centroid at the time of the state’s entry.
waypoint	Reach and stay close to a given global position with a set ‘tolerated’ distance from it.
r_turn	Perform a turn of a given radius.
set	Re-assign the position, speed and heading of the agent.
set_retreat	Re-assign the position and speed of the agent at a given distance away from its current position.
hold	Circle around a given global position.
hold_current	Circle around its own position at the state’s entry.
Social
align_n	Align with a number of closest neighbors.
align_direction	Align with own past heading at the beginning of the state.
cohere_centroid	Turn towards the average position of a number of closest neighbors.
cohere_centroid_distance	Turn towards the average position of a number of closest neighbors depending on the agent’s distance from it, following a smootherstep function (the closer the average position the weaker the attraction).
cohere_accel_n_front	Accelerate, depending on the average distance to a number of closest neighbors within a frontal field of view (the further away, the higher the acceleration). Decelerate if no neighbors are within the field of view.
avoid_n_position	Turn away from the average position of a number of closest neighbors if it is within a radius of minimum separation.
avoid_n_direction	Turn parallel to the average heading of a number of closest neighbors if the future collision point with them is within a radius of minimum separation.
avoid_pos_or_cohere_all	Avoid as in avoid_n_position if a neighbor is within the radius of minimum separation. If not, cohere as in cohere_centroid.
avoid_dir_or_cohere_all	Avoid as in avoid_n_direction if a neighbor is within the radius of minimum separation. If not, cohere as in cohere_centroid.
Escape
avoid_p_direction	Turn left or right, away from the relative heading of a close-by predator, if it is within a radius of minimum separation.
avoid_p_position	Turn left or right, away from the relative position of a close-by predator, if it is within a radius of minimum separation.
move_away_from_predator	Turn away from the position of a close-by predator, if it is within a radius of minimum separation.
t_turn_pred	Complete a turn of a given radius within a given time window away from the nearest predator.
random_t_turn_pred	Turn with an angular velocity sampled from a gamma distribution, in the direction away from the predator.
random_t_turn_gamma_pred	Turn with an angular velocity sampled from a uniform distribution, in the direction away from the predator.
dive	Pitch downwards (dive) away from a close-by predator (3D).
zig_zag	Perform a zig-zag turn (half to the left, half to the right) for a given time window.
scatter	Turn away (perpendicular to own heading) from the position of the nearest predator, if it is within a radius of minimum separation (3D).
copy_escape	Copy the state of a close-by neighbor, if possible (for states defined as ‘copyable’).
Hunt
select_flock	Choose a group as a target. If more than one, choose the nearest, smallest, largest, or a random one.
position_to_attack	Position at a given distance and bearing angle in the horizontal and vertical plane from the target (3D).
shadowing	Follow the target group from a given bearing angle and distance, with a speed scaling from the target’s speed.
chase_closest_prey	Move towards the closest prey (at every instance) with a speed scaling from the target’s speed.
lock_on_closest_prey	Move towards a targeted prey (constant during the state) with a speed scaling from the target’s speed.
avoid_closest_prey	Turn away from the position of the closest prey.

Individual-Based State Machines

A set of ISC-units defines a ‘state’, that controls an agent’s behavior (similar to a Markov-Chain, Wilson et al., 2014). For example, a state that represents a ‘flocking’ behavior may consist of four ISC-units that affect the agent’s behavior: alignment, centroid-attraction, avoidance, and noise. Thus, a state is designed around the nature of its effect on individual motion. At its current state, our framework implements social interactions and individual motion through a ‘social’ force that is applied to the internal state of each individual. Each ISC-unit adds a steering vector (glm::vec3 type) to the main social force that ultimately controls the motion of each agent (see the OODD protocol of the HoPE model in Papadopoulou et al., 2022a). However, using such steering vector is not enforced by our framework; one can choose a different variable to be changed and control the agent’s motion.

Apart from the parameters of each ISC-unit of a state, a state also has its own parameterization. This can include, for instance, the frequency with which the steering vector is updated (recalculating the effect of each ISC-unit, also known as ‘reaction frequency’; Bode et al., 2010; Hildenbrandt et al., 2010). A description of example states in existing models based on our framework is given in Section Use Cases. Overall, a model with a single state in our framework is the equivalent of a classic model of collective behavior, in which a constant set of rules at the individual level affects the motion of all agents identically.

To model discrete reactions and switches between different behaviors (related to the predator or ecological context), our framework enables several states to be included in a model. An agent is thus defined by not only its internal state, but also a finite-state machine that controls its behavior. Each state can comprise a different combination of ISC-units or the same ISC-units with different parameterization. For instance, a state of ‘flocking’ can be followed by an ‘escape’ state, during which an agent flocks while also avoiding a predator. An example of the definition of a state machine of a prey agent is given in Listing 1.

Listing 1. Example of a definition of a state machine of a ‘prey’ agent with several states. The ISC-units listed here represent alignment, cohesion, repulsion (by turning away from the position of its neighbors), roosting (attraction to a global point in space), random noise in the direction of motion (wiggle), and escape by a level turn or diving. To change the behaviour of an agent, the user needs to change the functions included in the defined ‘package’ (e.g., remove roost_attraction or replace avoid_n_position with avoid_n_direction: avoid collision points by turning parallel to the neighbour), and the parameters relating to each ISC-unit in the . json parameter file.

State Transitions

Transitions between states are controlled by a transition machine, owned by each agent. Each state has a duration that ranges from a single reaction step to any parameterized duration. For conceptual differentiation, a state is defined as ‘transient’ (effective duration of a single update cycle, an individual can switch state at any point) or ‘persistent’, with a user-define duration (only after a given period is passed the agent may switch state). At the exit of a state, the transition machine assigns the next state as a function of the current state and a set of probabilities, i.e., a transition matrix. This matrix can be dynamic or constant, and is predefined by parameterization. For instance, deterministic transitions are used in our existing models for the predator so its behavior follows a closed loop (Papadopoulou et al., 2022a, Papadopoulou, Garnier, & King, 2025; Papadopoulou, Hildenbrandt, & Hemelrijk, 2023): the predator has a probability of one to transition between its ‘pursuit’, ‘attack’ and ‘retreat’ states that all have a pre-defined duration.

Dynamic transition matrices are modeled for transitions that may depend on specific conditions during a simulation. For instance, an individual may switch to an escape state only if the predator is approaching. To account for this, each transition machine also owns a variable that can alter the probability of switching to a specific state. In the current version of the framework, such transition-altering mechanism is modeled through a ‘stress’ variable that is affected by a set of ‘stress source’ functions, namely neighbors (neighbors_stress) or predator (predator_distance): the closer the predator or the higher the stress of the neighbors of an agent, the more stress is accumulated in each agent, and the higher its probability to perform an escape maneuver is. A decay rate parameter is used to stabilize this accumulating value, so that in the absence of a predator, the probability of escaping returns to 0. Thus, the exact transition matrix at a given update time step is calculated by the transition machine through a piecewise linear interpolator that uses the stress value and a number of user-defined transition matrices and interpolation edges.

Overall, depending on the characteristics of the empirical systems, the transition probabilities between states for each agent can vary through time or be constant. Based on the probabilities of each current state, an agent selects its next state. Algorithm 1 presents a simplified version of the processes mentioned above.

In a real system, an individual may choose to react with an escape maneuver to a predator, but the exact maneuver may depend on the relative position of the prey to the predator (Domenici, 2010). Translated in our framework, to account for cases where the state selection should be performed by a specific ISC-unit and not the transition machine, we further included ‘multi-states’. A multi-state is a mere collection of states. The states of a multi-state (sub-states) have a conceptual connection that affects their selection during a simulation. The transition machine may decide that an individual should perform an escape maneuver, but the probability of selecting each one can be altered by each ISC-unit during the simulation (for instance if the predator attacks from above, a diving maneuver may be evaluated as more effective than a turning one), or from the parameterization of the multi-state (for instance, empirical data may show that the frequency of turning is higher than the frequency of diving). An example of the definition of a multi-state is given in Listing 1 (‘flee_state’). This allows a model to be improved as new empirical data on individual escape reactions are becoming available, facilitating the link between observations and theory.

Multi-Level Parameterization

Parameters in a model on our framework can be at the level of a state (for instance, a state-specific speed), at the level of an ISC-unit within a specific state (such as the number of topological neighbors for alignment), and at the level of the agent (such as its mass). To control all these, a configuration file with all the necessary parameters should be given as input in the model (at run-time). We implemented this as a JSON file given its nested nature that allows for parameterization of very complex state-machines. We can thus control every detail of a model, making conscious assumptions and allowing simulations of long sequences of collective escape seen in nature. This is particularly helpful when running a large set of simulations with different parameterization: ISC-units can be activated or deactivated and thus completely change the model between runs.

Our implementation of the parameterization of the transition machine is inspired by behavioral chains found in bird flocks (Storms et al., 2019), so that the transition probabilities can be directly informed by empirical data. We define a Markov chain through a transition matrix in our configuration file. Given that these probabilities may need to be adjusted during a simulation, depending on external conditions such as the proximity of an individual to the predator, we implemented an interpolator between several transition matrices. In detail, by giving the model several matrices (3 by default, for low, medium, and high threat) for some extreme conditions, the exact transition matrix is created at every state-switching step based on the parameter of the transition machine (stress). For instance, the interpolator could be used when the probability of an individual to perform an extreme escape maneuver should be 0 when the predator is not present and only increase when the predator gets very close.

It is important to note that ISC-units are not specific to a type of agent in a model. They can be used by any agent as long as all its necessary variables (parameters) are there. For instance, predator and prey can use the same ISC units to move around, but to use the ISC-unit that allows an agent to select a target from a group (conceptually a predatory behavior), the agent needs to own a ‘target’ variable. This flexibility allows for all of the ISC-units in our framework to be reusable, even when introducing a completely new type of agent.

Customizable Locomotion Type

The type of motion of grouping individuals (e.g., flying, swimming, or walking) is crucial to the emerging collective behavior (Gyllingberg et al., 2023; Hemelrijk & Hildenbrandt, 2012). Currently, our framework has been used to model bird flocks, and thus the locomotion module resembles flying (following Newton’s second law). For our framework to be extendable to non-flying species or easily adjusted to different research questions, we separate the ‘physics’ of motion from the main simulation loop. In detail, a stand-alone motion integrator controls how a steering vector affects the motion of an agent. This integrator functions independently of the specifics of a model (the structure of the agents, their ISC-units or their states). For instance, one can include elaborate flight aerodynamics (Hildenbrandt et al., 2010) or model the burst-and-glide motion of fish using neuronal equations (Gyllingberg et al., 2023). Furthermore, the integrator can be adjusted to a specific Reynolds regime (Chen et al., 2025), for example, for low numbers where the drag force is proportional to the agent’s velocity rather than its squared velocity (Hayashi et al., 2013) to model collective cell hunting (Rombouts et al., 2023).

Real-Time Visualization & Data Analysis

To incorporate analysis and visualization in our simulations we use the concept of ‘observers’ (a software design pattern mainly used in event-driven computing; Gamma et al., 1995). Observers access variables of a simulation in real time without interfering with the model. They enable the real-time visualization of a simulation for visual debugging and calibration (Figure 2(A)–(E)). By changing the representation of an agent, effects of body coloration that affect the observed patterns of collective escape can also be studied (e.g., Figure 1(A)). A ‘headless’ version (without visualization and GUI) can also be turned on (through the imgui configuration file) in order to speed up the simulation, for instance, when running a large number of simulations during data collection. Finally, a graphic user interface (GUI) allows the real-time plotting and visualization of several variables in the model, such as the current speed or state of each agent (Figure 2(F)).

Figure 2.

Real-Time Visualization (in OpenGL) of 3D Simulations Based on DaNCES. (A and B) Screenshot of a Group of 50 Prey Agents Turning away From the Closest of three Predators With the Trails of the Prey Enabled (A) or Not (B). The Color of Each Trail Here Indicates the State of Each Agent, With Purple Indicating Flocking, Blue Escaping, and Green Being in a Refraction Period. (C–E) Screenshot of the Group before the Attack, With Background Being Dark (C), Light (D), or Portraying a Scene (E). (F) Screenshot of the Complete GUI (Created in Dear ImGui) of a Model Using the Bird Shape for Visualizing Prey Agents. Information From the Simulation is Collected Through Observers and Thus the Visualization and Data Analysis do Not Interfere With the Model Itself

Based on a chain of specialized observers, we can also perform data analysis on the simulated trajectories in real time, for instance, identifying emergent subflocks (Figure 3(A) and (B)), extracting timeseries of polarization and diffusion (Cavagna et al., 2013; Papadopoulou, Hildenbrandt, & Hemelrijk, 2023), and calculating the relative position of nearest neighbors (Figure 3(C)) or the distance of each individual from the center of their flock (Figure 3(D)). With a specific observer per analysis type, our simulations can output analyzed data along with raw trajectories in ‘.csv’ format. All exported files are stored within a unique folder, along with a copy of the configuration file used. The folder is created at the beginning of each simulation, within a user-defined folder (parameter data_folder) in the project’s directory (by default “bin/sim_data”). This is extremely valuable for pairwise measurements, such as neighbor stability, that are computationally very demanding (Papadopoulou, Hildenbrandt, & Hemelrijk, 2023). Running many simulations across the parameter space and loading simulation outputs for further analysis is supported by our R package; see Section The rDaNCES.

Figure 3.

Monitoring Dynamics of Collective Motion and Escape. (A) Screenshot of a Simulation With a Group Split in Half After a Predator Attack. (B) Trajectories of a Splitting Flock on the Plane (X and Z Coordinates), With a 10 m (User-Defined Parameter) Threshold for Flock Identification at Run Time. (C) Density Plot of the Relative Position of Nearest Neighbors in the X-Z and Y-Z Planes, and (D) Timeseries of the Median Distance to the Centroid of a Flock as Outputted by three Simulations With 10, 50, and 100 Individuals

The observers enable the real-time visualization of a simulation (for visual debugging and calibration). By changing the representation of an agent, effects of body coloration that affect the observed patterns of collective escape can also be studied (e.g., Figure 1(A)). A ‘headless’ version (without visualization and GUI) can also be turned on (through the imgui configuration file) in order to speed up the simulation, for instance, when running a large number of simulations during data collection. Finally, a graphic user interface (GUI) allows the real-time plotting and visualization of several variables in the model, such as the current speed or state of each agent (Figure 2A).

An overview of a state machine and its connection with other elements of our framework is given in Figure 4.

Figure 4.

(A) Schematic Representation of a State Machine and Its Connection With the Other Elements of Our Framework. The Transition Machine Selects a State Depending on the Agent’s Internal (e.g., Its Position, the Previously Selected State), and External State (e.g., Its Distance to the Predator). States can be Composed of a Different Combination of ICS-Units and Have Their Own Parameterization. The Different Border Colors Represent Different Parameter Values. State one and two are Identical in Their ISC-Units but Differ in Their State-Level Parameter Values (for Instance in Their Duration or the Agent’s Reaction Frequency). The Output of the ISC-Units Changes the Internal State of an Agent Depending on the Specifics of the Motion Module. Observers Have Access to an Agent’s External and Internal State. Several Observers With Different Functions (e.g., to Export, Analyze or Visualize the Simulated Data) can be Added in a Model. (B) An Example of the States and ISC-Units Similar to the Ones Used for the Extended HoPE Model (Papadopoulou et al., 2022a). Red Borders indicate Escape-Related Blocks. (C) An Example of three User-Defined Transition Matrices for a Model With three States (1: Flocking, 2: Escape, 3: Refraction). As Stress Increases, the Probability to Escape (Transition From State 1 to 2) Should Also Increase. The Transition Machine Will Interpolate Across the Given Values Depending on the Value of Stress and the Input Edges of the Interpolation

Use Cases

To date, our framework has been used for three models of bird flocks (Papadopoulou et al., 2022a, Papadopoulou, Garnier, & King, 2025; Papadopoulou, Hildenbrandt, & Hemelrijk, 2023; Papadopoulou, Hildenbrandt, Storms et al., 2024). HoPE, a model adjusted to the collective escape of pigeons, consisted of a single state with 5 ISC-units: alignment, centroid-attraction, speed attraction, noise, and predator avoidance (Papadopoulou et al., 2022b). Since predator avoidance is modeled as a continuous tendency to turn away from the predator while coordinating, similar to many models of collective escape (Inada & Kawachi, 2002; Zheng et al., 2005), an extra state was not needed to model escape. Given that this model could not capture all patterns of collective escape seen in pigeons, an extension of the model was created to study the propagation of escape maneuvers (Papadopoulou et al., 2022a). Patterns of collective escape were conceptualized to be initialized by an individual that stops coordinating with its neighbors and maneuvers to escape the predator for a specific time period. Additionally, a refractory time period is added after an escape maneuver, during which an individual does not coordinate with its neighbors to ensure that the emergence of splitting and collective turning is the effect of the group’s ‘decision’. Thus, the extended HoPE model (Figure 5(A)) consists of three states: a flocking state (the one from its previous version, Papadopoulou et al., 2022b), an escaping state (with two ISC-units, an escape maneuver and noise), and a refraction state (with a single ISC-unit that adds noise to the straight heading of the initiator).

Figure 5.

Screenshots of Existing Models Presented in Our Use Cases. (A) A Simulation of Eight Individuals in the HoPE Model, With One Individual Splitting From the Flock while Performing a Discrete Turning Maneuver Away From the Predator. Screenshot Taken From Video by Papadopoulou et al. (2022a). (B) A Flock of 50 Individuals Performing a Collective Turn in the ColT Model. Screenshot Taken From Video by Papadopoulou, Hildenbrandt, & Hemelrijk (2023). (C) A Flock of 2000 Individuals Escaping by Diving in the StarEscape Model (Papadopoulou, Hildenbrandt, Storms et al., 2024)

Reflecting on the exact rule that makes prey agents perform collective turns in the model, the ColT model (Figure 5(B)) was developed to investigate alternative ISC-units that may represent turning tendencies in nature (Papadopoulou, Hildenbrandt, & Hemelrijk, 2023). Specifically, two alternative continuous turning tendencies were tested: a ‘homogeneous’ and a ‘heterogeneous’ one. In the former, all prey agents were repulsed identically away from an approaching predator (a steering vector perpendicular to each prey’s heading). In the latter, individuals had a common point in space (referred to as ‘roost’) toward which they were attracted while turning. Thus, the turning tendency varied across group members depending on each one’s relative position to the roost. Based on this conceptualization, two models, one for each alternative ISC-unit, were compared. The emergent characteristics of collective motion of the simulated flocks while turning, such as their internal structure and diffusion, differed significantly between models (Papadopoulou, Hildenbrandt, & Hemelrijk, 2023).

A model of higher complexity based on our framework is the 3-dimensional model of starlings (Sturnus vulgaris), StarEscape (Papadopoulou, Hildenbrandt, Storms et al., 2024). Aiming to reproduce their aerial displays (Carere et al., 2009), the model includes four states: flocking, alarmed flocking, escape (which as mentioned earlier is a multi-state), and refraction. Flocking in StarEscape (Figure 5(C)) includes the following 6 ISC-units: alignment, centroid-attraction (distance biased, ensuring sharp edges of the flock similar to real starlings, Hildenbrandt et al., 2010), avoidance, noise, roost attraction, and altitude attraction. The last two ISC-units constrain the movement of the flock within the 3-dimensional ‘infinite’ space: they ensure that individuals will stay within a given radius and fly at a preferred altitude. The alarmed flocking state is structurally identical with the flocking state, apart from being parameterized with a higher reaction frequency (imitating more vigilant individuals when the predator is pursuing the flock; Bode et al., 2010; Herbert-Read, Rosén et al., 2017) and having an extra ISC-unit that affects the transition machine: a ‘copy-escape’ behavior. This ISC-unit checks whether any neighbor is in the escape state. If so, it sets the future state in the transition machine to be the same as its neighbors. The escape multi-state has two states that include the coordination-related ISC-units of the flocking states, and an additional maneuvering ISC-unit, one for a diving maneuver and one for a turning maneuver. Finally, the refraction state has the coordination-related ISC-units of the flocking states but a predefined duration. Separating these states ensures that individuals will not keep reacting to the predator in an unrealistic manner.

The rDaNCES

We developed an R package that offers a pipeline to produce many configuration files, run simulations, and import the simulations’ output into R, to promote the reproducibility of simulation experiments, help modify the configuration file of a complex model, and support the use of our framework by the biological community. In detail, the package uses a complete configuration file as a template (composed from the prey, predator, simulation, and imgui configuration files) and runs a compiled model built in DaNCES through the command-line interface. Changes in the actual simulation structure (states, ISC-units) cannot be done through the package; the produced configuration files should thus fit the structure of the model. After completing the adjustment of an agent-based model in C++ (Figure 6(A) and (B)), the user can combine its .exe file in R with many configuration files to examine the parameter space of the model and produce results (Figure 6(C)). This further enables the link of our framework with other existing tools for the analysis of collective motion data, such as the swaRmverse package (Papadopoulou, Garnier, & King, 2025), producing complete reproducible pipelines from the setup of simulation experiments to the production of results (Figures 3(C), (D), and 6).

Figure 6.

Overview of DaNCES Pipeline to Study a New System. (A) Define the Agents Based on Their ISC-Units, States, and Behavioural Sequence During a Simulation. (B) Decide on the Metrics Needed as Output (Set up the Analysis Observers) and Calibrate the Model Through the GUI (Figure 2) and by Comparing the Simulated to Empirical Data, Overall Creating a Default configuration File. (C) Set up a Parameter Space and Run Simulation Using the rDaNCES Package, saving all Output in an R List (See Papadopoulou, 2025)

The package is available on GitHub and can be downloaded and installed through our repository: https://github.com/marinapapa/rDaNCES. Any issues should be reported on: https://github.com/marinapapa/rDaNCES/issues. Details on the structure of the package and a step-by-step guide to get started are included in our repository (Papadopoulou, 2025).

Summary and Potential

In our new framework, a model is composable, flexible, and reusable. By changing a few lines of code in the definition of an agent’s state machine and the configuration file, a new model can be created. New ISC-units can be easily developed from the ones available based on the characteristics of an empirical system, being a prey’s reaction or a predator’s attack or interaction with other predators. Given their stand-alone nature of ISC-units, adding a new one does not interfere with the chain of the model itself. Apart from adding new rules, the user can also quickly remove elements of a model to compare simulations of decreasing complexity. This is extremely valuable when searching for a simple self-organized process to explain the emergence of a collective pattern.

Following the example of the ‘Medawar’ zone of pattern-oriented models (Grimm et al., 2005), we should emphasize that the increasing complexity of models that our framework supports should be used with caution: a very large parameter space can limit the explanatory power of the model and constrain our understanding of the underlying mechanisms of the complex system. Finding the balance between minimal models and models derived from complex empirical data is challenging and should be reached while keeping the study’s research question in mind. We hope that DaNCES supports modelers while seeking this balance, trains students in the modeling of animal behavior, and promotes clear (and conscious) assumptions and modeling decisions.

Apart from the flexibility of our models, our framework’s structure enables the modeling of different behaviors that are crucial to collective escape and cooperative hunting, for instance, the interplay between continuous and instantaneous reactions. Because of its ‘building-blocks’, we can develop complex models that reproduce long sequences of predator-prey interactions similar to the ones seen in nature without increasing the complexity of the code itself. This reduced code complexity also includes the avoidance of long series of nested conditional blocks (if-statements) which, as a model grows, become error prone, difficult to work with, and introduce optimization issues (code that is rarely used increases the computation time). Every block in our framework (being an ISC-unit, a state, a transition machine, or a motion interpolator) is a pure function that owns a set of parameters and effectively alters the state of an agent. Because of their simplicity, they are reusable and can be more easily optimized while providing code clarity and debugging efficiency. Thus, the extension and growth of a model based on our framework is less error-prone and less time-consuming. The value of such a structure has also recently been highlighted for agent-based modeling in general (Berger et al., 2024).

To conclude, our simulation framework provides a skeleton to build a new agent-based model rather than being just a function library. Its building block structure and detailed parameterization allow for a model to be informed with any available empirical data, increasing its biological relevance. Programming-wise, it does not impose our implementation, allowing a more experienced user to work in their own modeling style. Overall, if one can conceptualize a set of rules and actions that agents should follow, along with the interconnection (time sequence) of these actions, it can be modeled in our framework (Figure 6). We hope that it will enable the modeling of many systems for which our theoretical understanding is currently lacking, such as collective escape from multiple predators (Licht et al., 2024) or with highly complex displays (Storms et al., 2019) (Figure 1(A) and (D)). Despite our focus on collective escape and cooperative hunting, our framework can be used for spatially explicit modeling of collectives across contexts, especially to simulate large group sizes.