Class AgentDescription
Defined in File AgentDescription.h
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
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 = {}) 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
-
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
- 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
- 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
-
bool operator==(const AgentDescription &rhs) const