Class ModelDescription

Class Documentation

class 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

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

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

InvalidMessageName – If a message with the same name already exists within the model description hierarchy

Returns

A mutable reference to the new MessageDescription

MsgBruteForce::Description &newMessage(const std::string &message_name)
template<typename MsgType>
inline MsgType::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

InvalidMessageName – If a message with the name does not exist within the model description hierarchy

Returns

A mutable reference to the specified MessageDescription

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

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

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

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

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

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

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

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

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

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 MsgType>
inline const MsgType::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

InvalidMessageName – If a message with the name does not exist within the model description hierarchy

Returns

An immutable reference to the specified MessageDescription

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

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

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

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