Class ModelDescription¶

Defined in File ModelDescription.h

Class Documentation¶

class flamegpu::ModelDescription¶

This class represents the hierarchy of components for a FLAMEGPU model This is the initial class that should be created by a modeller

See: ModelData The internal data store for this class

Public Functions

explicit ModelDescription(const std::string &model_name)¶

Constructor

Constructors

Parameters: model_name – Name of the model, this must be unique between models currently held by instances of CUDASimulation

ModelDescription(const ModelDescription &other_model) = delete¶: Default copy constructor, not implemented

ModelDescription(ModelDescription &&other_model) noexcept = delete¶: Default move constructor, not implemented

ModelDescription &operator=(const ModelDescription &other_model) = delete¶: Default copy assignment, not implemented

ModelDescription &operator=(ModelDescription &&other_model) noexcept = delete¶: Default move assignment, not implemented

bool operator==(const ModelDescription &rhs) const¶

Equality operator, checks whether ModelDescription hierarchies are functionally the same

Note

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

Returns: True when models are the same

bool operator!=(const ModelDescription &rhs) const¶

Equality operator, checks whether ModelDescription hierarchies are functionally different

Note

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

Returns: True when models are not the same

AgentDescription &newAgent(const std::string &agent_name)¶

Creates a new agent with the specified name

Accessors

Parameters: agent_name – Name which can be used to refer to the agent within the model description hierarchy
Throws: exception::InvalidAgentName – If an agent with the same name already exists within the model description hierarchy
Returns: A mutable reference to the specified AgentDescription

AgentDescription &Agent(const std::string &agent_name)¶

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

See: ModelDescription::getAgent(const std::string &) for the immutable version

Parameters: agent_name – Name which can be used to the refer to the desired agent within the model description hierarchy
Throws: exception::InvalidAgentName – If an agent with the name does not exist within the model description hierarchy
Returns: A mutable reference to the specified AgentDescription

template<typename MessageType> inline MessageType::Description &newMessage(const std::string &message_name)¶

Creates a new message with the specified name

Parameters: message_name – Name which can be used to refer to the message within the model description hierarchy
Throws: exception::InvalidMessageName – If a message with the same name already exists within the model description hierarchy
Returns: A mutable reference to the new MessageDescription

MessageBruteForce::Description &newMessage(const std::string &message_name)¶

template<typename MessageType> inline MessageType::Description &Message(const std::string &message_name)¶

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

See: ModelDescription::getMessage(const std::string &) for the immutable version

Parameters: message_name – Name used to refer to the desired message within the model description hierarchy
Throws: exception::InvalidMessageName – If a message with the name does not exist within the model description hierarchy
Returns: A mutable reference to the specified MessageDescription

MessageBruteForce::Description &Message(const std::string &message_name)¶

EnvironmentDescription &Environment()¶

Returns a mutable reference to the environment description for the model description hierarchy This can be used to configure environment properties

See: ModelDescription::getEnvironment() for the immutable version

SubModelDescription &newSubModel(const std::string &submodel_name, const ModelDescription &submodel_description)¶

Add a submodel to the Model Description hierarchy The return value can be used to map agent variables

Parameters

submodel_name – The name used to refer to the submodel (e.g. when adding it to the layer)
submodel_description – The actual definition of the submodel

SubModelDescription &SubModel(const std::string &submodel_name)¶

Returns a mutable reference to the named submodel

See: ModelDescription::getSubModel(const std::string &) for the immutable version

Parameters: submodel_name – Name which can be used to the refer to the desired submodel within the model description hierarchy
Throws: exception::InvalidSubModelName – If a submodel with the name does not exist within the model description hierarchy
Returns: A mutable reference to the specified SubModelDescription

LayerDescription &newLayer(const std::string &name = "")¶

Creates a new layer with the specified name

Note

Layer names are not required, passing empty string will not set a name

Parameters: name – Name which can be used to refer to the message within the model description hierarchy
Throws: exception::InvalidFuncLayerIndx – If a layer with the same name already exists within the model description hierarchy
Returns: A mutable reference to the new LayerDescription

LayerDescription &Layer(const std::string &name)¶

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

See: ModelDescription::Layer(const ModelData::size_type &)
See: ModelDescription::getLayer(const std::string &) for the immutable version

Parameters: name – Name used to refer to the desired layer within the model description hierarchy
Throws: exception::InvalidFuncLayerIndx – If a layer with the name does not exist within the model description hierarchy
Returns: A mutable reference to the specified LayerDescription

LayerDescription &Layer(const ModelData::size_type &layer_index)¶

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

See: ModelDescription::Layer(const std::string &)
See: ModelDescription::getLayer(const ModelData::size_type &) for the immutable version

Parameters: layer_index – Index of the desired layer within the model description hierarchy
Throws: exception::InvalidFuncLayerIndx – If a layer with the name does not exist within the model description hierarchy
Returns: A mutable reference to the specified LayerDescription

void addInitFunction(FLAMEGPU_INIT_FUNCTION_POINTER func_p)¶

Adds an init function to the simulation Init functions execute once before the simulation begins

Note

There is no guarantee on the order in which multiple init functions will be executed

Parameters: func_p – Pointer to the desired init function
Throws: exception::InvalidHostFunc – If the init function has already been added to this model description

void addStepFunction(FLAMEGPU_STEP_FUNCTION_POINTER func_p)¶

Adds a step function to the simulation Step functions execute once per step, after all layers have been executed, before exit conditions

Note

There is no guarantee on the order in which multiple step functions will be executed, host-layer functions can be used if order is required.

Parameters: func_p – Pointer to the desired step function
Throws: exception::InvalidHostFunc – If the step function has already been added to this model description

void addExitFunction(FLAMEGPU_EXIT_FUNCTION_POINTER func_p)¶

Adds an exit function to the simulation Exit functions execute once after all simulation steps have completed or an exit conditions has returned EXIT

Note

There is no guarantee on the order in which multiple exit functions will be executed

Parameters: func_p – Pointer to the desired exit function
Throws: exception::InvalidHostFunc – If the exit function has already been added to this model description

void addExitCondition(FLAMEGPU_EXIT_CONDITION_POINTER func_p)¶

Adds an exit condition function to the simulation Exit conditions execute once per step, after all layers and step functions have been executed If the condition returns false, the simulation exits early

Note

Exit conditions are the last functions to operate each step and can still make changes to the model

Note

The step counter is updated after exit conditions have completed

Note

There is no guarantee on the order in which multiple exit conditions will be executed

Parameters: func_p – Pointer to the desired exit condition function
Throws: exception::InvalidHostFunc – If the exit condition has already been added to this model description

std::string getName() const¶

Const Accessors

Returns: The model’s name

DependencyGraph &getDependencyGraph() const¶

Accessors

Returns: A reference to the this model’s DependencyGraph

void generateLayers()¶: Generates layers from the dependency graph

const AgentDescription &getAgent(const std::string &agent_name) const¶

Returns an immutable reference to the specified agent, which can be used to view the agent’s configuration

See: ModelDescription::Agent(const std::string &) for the mutable version

Parameters: agent_name – Name which can be used to the refer to the desired agent within the model description hierarchy
Throws: exception::InvalidAgentName – If an agent with the name does not exist within the model description hierarchy
Returns: An immutable reference to the specified AgentDescription

template<typename MessageType> inline const MessageType::Description &getMessage(const std::string &message_name) const¶

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

See: ModelDescription::Message(const std::string &) for the mutable version

Parameters: message_name – Name used to refer to the desired message within the model description hierarchy
Throws: exception::InvalidMessageName – If a message with the name does not exist within the model description hierarchy
Returns: An immutable reference to the specified MessageDescription

const MessageBruteForce::Description &getMessage(const std::string &message_name) const¶

const SubModelDescription &getSubModel(const std::string &submodel_name) const¶

Returns an immutable reference to the specified submodel, which can be used to view the submodel’s configuration

See: ModelDescription::SubModel(const std::string &) for the mutable version

Parameters: submodel_name – Name which can be used to the refer to the desired submodel within the model description hierarchy
Throws: exception::InvalidSubModelName – If a submodel with the name does not exist within the model description hierarchy
Returns: An immutable reference to the specified SubModelDescription

const EnvironmentDescription &getEnvironment() const¶

Returns a mutable reference to the environment description for the model description hierarchy This can be used to configure environment properties

See: ModelDescription::Environment() for the mutable version

const LayerDescription &getLayer(const std::string &name) const¶

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

See: ModelDescription::getLayer(const ModelData::size_type &)
See: ModelDescription::Layer(const std::string &) for the mutable version

Parameters: name – Name used to refer to the desired layer within the model description hierarchy
Throws: exception::InvalidFuncLayerIndx – If a layer with the name does not exist within the model description hierarchy
Returns: An immutable reference to the specified LayerDescription

const LayerDescription &getLayer(const ModelData::size_type &layer_index) const¶

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

See: ModelDescription::getLayer(const std::string &)
See: ModelDescription::Layer(const ModelData::size_type &) for the mutable version

Parameters: layer_index – Index of the desired layer within the model description hierarchy
Throws: exception::InvalidFuncLayerIndx – If a layer with the name does not exist within the model description hierarchy
Returns: An immutable reference to the specified LayerDescription

bool hasAgent(const std::string &agent_name) const¶

Parameters: agent_name – Name of the agent to check
Returns: True when an agent with the specified name exists within the model’s hierarchy

template<typename MessageType> inline bool hasMessage(const std::string &message_name) const¶

Parameters: message_name – Name of the message to check
Returns: True when a message with the specified name exists within the model’s hierarchy

bool hasMessage(const std::string &message_name) const¶

bool hasLayer(const std::string &name) const¶

Parameters: name – Name of the layer to check
Returns: True when a layer with the specified name exists within the model’s hierarchy

bool hasLayer(const ModelData::size_type &layer_index) const¶

Parameters: layer_index – Index of the agent to check
Returns: True when a layer with the specified index exists within the model’s hierarchy

bool hasSubModel(const std::string &submodel_name) const¶

Parameters: submodel_name – Name of the submodel to check
Returns: True when a submodel with the specified name exists within the model’s hierarchy

ModelData::size_type getAgentsCount() const¶

Returns: The number of agents within the model’s hierarchy

ModelData::size_type getMessagesCount() const¶

Returns: The number of messages within the model’s hierarchy

ModelData::size_type getLayersCount() const¶

Returns: The number of layers within the model’s hierarchy