Class AgentDescription

Inheritance Relationships

Base Type

Class Documentation

class AgentDescription : public flamegpu::CAgentDescription

Within the model hierarchy, this class represents the definition of an agent for a FLAMEGPU model This class is used to configure external elements of agents, such as variables and functions

See also

AgentData The internal data store for this class

See also

ModelDescription::newAgent(const std::string&) For creating instances of this class

Note

To set an agent’s id, the agent must be part of a model which has begun (id’s are automatically assigned before initialisation functions and can not be manually set by users)

Public Functions

explicit AgentDescription(std::shared_ptr<AgentData> data)

Constructor, creates an interface to the AgentData Constructors

Parameters:

data – Data store of this agent’s data

AgentDescription(const AgentDescription &other_agent) = default

Copy constructor Creates a new interface to the same AgentData/ModelData

AgentDescription(AgentDescription &&other_agent) = default
AgentDescription &operator=(const AgentDescription &other_agent) = default

Assignment operator Assigns this interface to the same AgentData/ModelData

AgentDescription &operator=(AgentDescription &&other_agent) = default
void newState(const std::string &state_name)

Adds a new state to the possible states this agent can enter State’s only exist as strings and have no additional configuration

Accessors

Parameters:

state_name – Name of the state

Throws:

exception::InvalidStateName – If the agent already has a state with the same name

void setInitialState(const std::string &initial_state)

Sets the initial state which new agents begin in

Parameters:

initial_state – Name of the desired state

Throws:

exception::InvalidStateName – If the named state is not found within the agent

template<typename T, flamegpu::size_type N>
void newVariable(const std::string &variable_name, const std::array<T, N> &default_value = {})

Adds a new variable array to the agent

Template implementation

Parameters:

  • variable_name – Name of the variable array

  • default_value – Default value of variable for new agents if unset, defaults to each element set 0

Template Parameters:

  • T – Type of the agent variable, this must be an arithmetic type

  • N – The length of the variable array (1 if not an array, must be greater than 0)

Throws:
template<typename T>
void newVariable(const std::string &variable_name, T default_value = {})

Adds a new variable to the agent

Parameters:

  • variable_name – Name of the variable

  • default_value – Default value of variable for new agents if unset, defaults to 0

Template Parameters:

T – Type of the agent variable, this must be an arithmetic type

Throws:

exception::InvalidAgentVar – If a variable already exists within the agent with the same name

template<typename AgentFunction>
AgentFunctionDescription newFunction(const std::string &function_name, AgentFunction a = AgentFunction())

Adds a new (device) function to the agent

Note

The same agent function can be passed to the same agent twice

Parameters:

  • function_name – Name of the functions

  • a – Instance of the agent function, used to implicitly set the template arg Should be declared using FLAMEGPU_AGENT_FUNCTION notation

Template Parameters:

AgentFunction – The agent function’s containing struct type

Throws:

exception::InvalidAgentFunc – If a variable already exists within the agent with the same name

Returns:

A mutable reference to the new AgentFunctionDescription

AgentFunctionDescription newRTCFunction(const std::string &function_name, const std::string &func_src)

Adds a new runtime (device) function to the agent from a string containing the source code

Note

The same agent function can be passed to the same agent twice

Parameters:

  • function_name – Name of the functions

  • func_src – representation of an agent function Should be declared using FLAMEGPU_AGENT_FUNCTION notation

Throws:

exception::InvalidAgentFunc – If a variable already exists within the agent with the same name

Returns:

A mutable reference to the new AgentFunctionDescription

AgentFunctionDescription newRTCFunctionFile(const std::string &function_name, const std::string &file_path)

Adds a new runtime (device) function to the agent from a file containing the source code

Note

The same agent function can be passed to the same agent twice

Parameters:

  • function_name – Name of the functions

  • file_path – File path to file containing source for the agent function Should be declared using FLAMEGPU_AGENT_FUNCTION notation

Throws:

  • exception::InvalidFilePath – If file_path cannot be read

  • exception::InvalidAgentFunc – If a variable already exists within the agent with the same name

Returns:

A mutable reference to the new AgentFunctionDescription

AgentFunctionDescription Function(const std::string &function_name)

Returns a mutable reference to the named agent function, which can be used to configure the function

See also

AgentDescription::getFunction(const std::string &) for the immutable version

Parameters:

function_name – Name used to refer to the desired agent function

Throws:

exception::InvalidAgentFunc – If a functions with the name does not exist within the agent

Returns:

A mutable reference to the specified AgentFunctionDescription

void setSortPeriod(const unsigned int sortPeriod)

Set how often this agent is sorted. Default value is 1.

Parameters:

sortPeriod – Sort this agent every sortPeriod steps. A value of 0 means no sorting will take place