Defining Agents

Agents are the central component of FLAME GPU simulations, and are directly equivalent to agent-based modelling agents. However, they can also be used to represent other things such as scalar fields across the environment. Agents are represented by an AgentDescription object.

Defining a New Agent Type

FLAME GPU 2 agents are associated with a particular model. As such they are created via a ModelDescription object and are initialised with a name:

// Create a new agent called 'predator' associated the model 'model'
flamegpu::AgentDescription predator = model.newAgent("predator");

# Create a new agent called 'predator' associated the model 'model'
predator = model.newAgent("predator")

Agent Variables

Agent variables should be used to store data which is unique to each instance of an agent, for example, each individual predator in a predator-prey simulation would have its own position and hunger level. Each variable has a name, type, default value and may take the form of a scalar or array.

For a full list of supported types, see Supported Types.

Agent ID

All agents have a built in ID variable. This is a number which uniquely identifies this agent. Each agent will automatically be assigned an ID when the simulation starts or the agent is birthed. The ID is value for every agent is unique among agents of all types. There is currently no way to change the ID of an agent. The agent ID variable is of type flamegpu::id_t (Python: ID) which is an unsigned int by default, but can be redefined if more IDs are required, e.g. a model with extremely high rates of agent birth/death.

User Defined Variables

Bespoke agent variables are declared using the newVariable() methods.

The type and name the variables must be specified, array variables additionally require the length of the array to be specified. Optionally, a default value for the variables may also be specified

// Declare an integer variable 'foo', with a default value 12
predator.newVariable<int>("foo", 12);
// Declare a float variable 'bar', without a default value
predator.newVariable<int>("bar", 12);
// Declare a float array variable of length 3 named 'foobar', with a default value [4.0, 5.0, 6.0]
predator.newVariable<float, 3>("foobar", {4.0f, 5.0f, 6.0f});

# Declare an integer variable 'foo', with a default value 12
predator.newVariableInt("foo", 12)
# Declare a float variable 'bar', without a default value
predator.newVariableFloat("bar")
# Declare a float array variable of length 3 named 'bar', with a default value [4.0, 5.0, 6.0]
predator.newVariableArrayFloat("foobar", 3, [4.0, 5.0, 6.0])

Note

Variable names must not begin with _, this is reserved for internal variables.

Agent States

Agent states are usually used to group sets of behaviours. For example, a predator in a predator-prey simulation may have a resting state and a hunting state. All newly defined agent types will have a default state, but you can add additional states if you wish to. Agent functions can then utilise agent function conditions to perform state transitions.

States can be defined through the AgentDescription object:

// Create two new states, resting and hunting
predator.newState("resting");
predator.newState("hunting");

# Create two new states, resting and hunting
predator.newState("resting")
predator.newState("hunting")

Agent State Transitions are then used to transfer agents between states.