Class AgentDescription

Defined in File AgentDescription.h

Class Documentation

class flamegpu::AgentDescription

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

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)

See: AgentData The internal data store for this class
See: ModelDescription::newAgent(const std::string&) For creating instances of this class

Public Functions

bool operator==(const AgentDescription &rhs) const

Equality operator, checks whether AgentDescription hierarchies are functionally the same

Note

Instead compare pointers if you wish to check that they are the same instance

Parameters: rhs – right hand side
Returns: True when agents are the same

bool operator!=(const AgentDescription &rhs) const

Equality operator, checks whether AgentDescription hierarchies are functionally different

Note

Instead compare pointers if you wish to check that they are not the same instance

Parameters: rhs – right hand side
Returns: True when agents are not the same

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, ModelData::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

exception::InvalidAgentVar – If a variable already exists within the agent with the same name
exception::InvalidAgentVar – If N is <= 0

template<typename T> void newVariable(const std::string &variable_name, const T &default_value = 0)

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: 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

std::string getName() const

Const Accessors

Returns: The agent’s name

ModelData::size_type getStatesCount() const

Returns: The number of possible states agents of this type can enter

std::string getInitialState() const

Returns: The state which newly created agents of this type begin in

const std::type_index &getVariableType(const std::string &variable_name) const

Parameters: variable_name – Name used to refer to the desired variable
Throws: exception::InvalidAgentVar – If a variable with the name does not exist within the agent
Returns: The type of the named variable

size_t getVariableSize(const std::string &variable_name) const

Parameters: variable_name – Name used to refer to the desired variable
Throws: exception::InvalidAgentVar – If a variable with the name does not exist within the agent
Returns: The size of the named variable’s type

ModelData::size_type getVariableLength(const std::string &variable_name) const

Parameters: variable_name – Name used to refer to the desired variable
Throws: exception::InvalidAgentVar – If a variable with the name does not exist within the agent
Returns: The number of elements in the name variable (1 if it isn’t an array)

ModelData::size_type getVariablesCount() const

Get the total number of variables this agent has

Note

This count includes internal variables used to track things such as agent ID

Returns: The total number of variables within the agent

const AgentFunctionDescription &getFunction(const std::string &function_name) const

Returns an immutable reference to the named agent function

See: AgentDescription::Function(const std::string &) for the mutable version

Parameters: function_name – Name used to refer to the desired agent function
Throws: exception::InvalidAgentFunc – If a function with the name does not exist within the agent
Returns: An immutable reference to the specified AgentFunctionDescription

ModelData::size_type getFunctionsCount() const

Get the total number of functions this agent has

Returns: The total number of functions within the agent

ModelData::size_type getAgentOutputsCount() const

The total number of agent functions, within the ModelDescription hierarchy, which create new agents of this type

See: AgentDescription::isOutputOnDevice()

Returns: The total number of agent functions within the ModelDescription hierarchy which create new agents of this type

bool hasState(const std::string &state_name) const

Parameters: state_name – Name of the state to check
Returns: True when a state with the specified name exists within the agent

bool hasVariable(const std::string &variable_name) const

Parameters: variable_name – Name of the variable to check
Returns: True when a variable with the specified name exists within the agent

bool hasFunction(const std::string &function_name) const

Parameters: function_name – Name of the function to check
Returns: True when a function with the specified name exists within the agent

bool isOutputOnDevice() const

Check whether any agent functions output agents of this type

See: AgentDescription::getAgentOutputsCount()

Returns: True if any agent functions, with the model hierarchy, create new agents of this type

const std::set<std::string> &getStates() const

Get the set of possible states for an agent of this type

Returns: An immutable reference to the set of states agents of this type can enter

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