Class ModelDescription

• Defined in File ModelDescription.h

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 also

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 also

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 also

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 also

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 also

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 also

ModelDescription::Layer(const flamegpu::size_type &)

See also

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 flamegpu::size_type &layer_index)

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

See also

ModelDescription::Layer(const std::string &)

See also

ModelDescription::getLayer(const flamegpu::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

Init functions are executed in the order they were added to the model

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

Step functions are executed in the order they were added to the model

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

Exit functions are executed in the order they were added to the model

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

Exit conditions are executed in the order they were added to the model

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

void addExecutionRoot(DependencyNode &root)

Sets root as an execution root of the model. Multiple roots can be used which represent independent chains of dependencies.

Parameters:

root – The DependencyNode which will be used as an execution root

void generateLayers()

Generates layers from the dependency graph

void generateDependencyGraphDOTDiagram(std::string outputFileName) const

Generates a .gv file containing the DOT representation of the dependencies specified

Parameters:

outputFileName – The name of the output file

std::string getConstructedLayersString() const

Returns a string representation of the constructed layers

Returns:

A string representation of the constructed layers

CAgentDescription 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 also

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 MessageType::CDescription getMessage(const std::string &message_name) const

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

See also

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

MessageBruteForce::CDescription getMessage(const std::string &message_name) const

CSubModelDescription 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 also

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

CEnvironmentDescription getEnvironment() const

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

See also

ModelDescription::Environment() for the mutable version

CLayerDescription getLayer(const std::string &name) const

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

See also

ModelDescription::getLayer(const flamegpu::size_type &)

See also

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

CLayerDescription getLayer(const flamegpu::size_type &layer_index) const

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

See also

ModelDescription::getLayer(const std::string &)

See also

ModelDescription::Layer(const flamegpu::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 flamegpu::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

flamegpu::size_type getAgentsCount() const

Returns:

The number of agents within the model’s hierarchy

flamegpu::size_type getMessagesCount() const

Returns:

The number of messages within the model’s hierarchy

flamegpu::size_type getLayersCount() const

Returns:

The number of layers within the model’s hierarchy