Class AgentDescription

Class Documentation

class 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

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

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
template<typename T>
void newVariable(const std::string &variable_name, const 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
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

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 also

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 also

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 also

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