SyDEVS  v0.6.4
Multiscale Simulation and Systems Modeling Library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
sydevs::systems::collection_node< AgentID, Node > Class Template Referenceabstract

A base class template for all collection nodes. More...

#include <collection_node.h>

Inherits sydevs::systems::collection_node_base.

Classes

class  const_iterator
 
class  flow_port_proxy
 
class  message_port_proxy
 

Public Member Functions

 collection_node (const std::string &node_name, const node_context &external_context)
 Constructs a collection_node. More...
 
virtual ~collection_node ()=default
 Destructor. More...
 
void print_on_elapsed_duration (bool flag=true) const
 If flag is true, all elapsed durations are printed for this node. More...
 
void print_on_planned_duration (bool flag=true) const
 If flag is true, all planned durations are printed for this node. More...
 
duration handle_initialization_event ()
 Invoked at the beginning of a simulation; calls macro_initialization_event. More...
 
duration handle_unplanned_event (duration elapsed_dt)
 Invoked whenever a message is received; calls macro_unplanned_event. More...
 
duration handle_planned_event (duration elapsed_dt)
 Invoked when the planned duration elapses for either an agent or the overall collection; calls micro_planned_event or macro_planned_event. More...
 
void handle_finalization_event (duration elapsed_dt)
 Invoked at the end of a simulation; calls macro_finalization_event. More...
 
template<typename T >
collection_node< AgentID, Node >
::template flow_port_proxy< T > 
access (const port< flow, input, T > &prototype_port)
 
template<typename T >
collection_node< AgentID, Node >
::template message_port_proxy
< T > 
access (const port< message, input, T > &prototype_port)
 
- Public Member Functions inherited from sydevs::systems::collection_node_base
virtual ~collection_node_base ()=default
 Destructor. More...
 
data_mode node_dmode () const
 Returns message for all collection nodes. More...
 
- Public Member Functions inherited from sydevs::systems::system_node
 system_node (const system_node &)=delete
 No copy constructor. More...
 
system_nodeoperator= (const system_node &)=delete
 No copy assignment. More...
 
 system_node (system_node &&)=delete
 No move constructor. More...
 
system_nodeoperator= (system_node &&)=delete
 No move assignment. More...
 
virtual ~system_node ()=default
 Destructor. More...
 
const std::string & node_name () const
 Returns the name of the node. More...
 
const std::string & full_name () const
 Returns the full name of the node, including parent nodes. More...
 
int64 node_index () const
 Returns the index of the node within the parent node. More...
 
const node_interfaceexternal_interface () const
 Returns the object responsible for exchanging information between the node and its surrounding context. More...
 
template<typename T >
void print (const T &X)
 Prints X while indicating the simulation time and node. More...
 
void print (const char *raw_text)
 Prints raw_text while indicating the simulation time and node. More...
 
void print (const std::string &text)
 Prints text while indicating the simulation time and node. More...
 
void print_on_event (bool flag=true) const
 If flag is true, all event types are printed for this node. More...
 
void adopt_print_flags (const system_node &node) const
 Adopts the print flags of node. More...
 
virtual scale time_precision () const =0
 Returns the time precision associated with the node, or no_scale. More...
 
duration process_initialization_event ()
 Processes an initialization event; returns a planned duration. More...
 
duration process_unplanned_event (duration elapsed_dt)
 Processes an unplanned event after an elapsed duration elapsed_dt; returns a planned duration. More...
 
duration process_planned_event (duration elapsed_dt)
 Processes a planned event after an elapsed duration elapsed_dt; returns a planned duration. More...
 
void process_finalization_event (duration elapsed_dt)
 Processes a finalization event after an elapsed duration elapsed_dt. More...
 

Public Attributes

const Node prototype
 A node that serves as a proxy for all agent nodes. More...
 

Protected Member Functions

template<typename T >
bool transmitted (const port< message, output, T > &prototype_port)
 Returns true if a message was transmitted by an agent on the port corresponding to prototype_port. More...
 
template<typename T >
flow_port_proxy< T > access (const port< flow, input, T > &prototype_port)
 Returns a proxy of the flow input port prototype_port, allowing its value to be modified. More...
 
template<typename T >
message_port_proxy< T > access (const port< message, input, T > &prototype_port)
 Returns a proxy of the message input port prototype_port, allowing its value to be modified. More...
 
template<typename T >
const T & access (const port< message, output, T > &prototype_port)
 Returns the value transmitted by an agent on the message output port corresponding to prototype_port. More...
 
template<typename T >
const T & access (const port< flow, output, T > &prototype_port)
 Return the value output by an agent on the flow output port corresponding to prototype_port. More...
 
template<typename AgentNode >
void create_agent (const AgentID &agent_id)
 Creates a new agent of type AgentNode. More...
 
void create_agent (const AgentID &agent_id)
 Creates a new agent. More...
 
void affect_agent (const AgentID &agent_id)
 Sends a message to an agent. More...
 
void remove_agent (const AgentID &agent_id)
 Finalizes and removes an agent. More...
 
void invoke_agent (const AgentID &agent_id)
 Creates, invokes, and removes an agent. More...
 
bool agent_exists (const AgentID &agent_id)
 Returns true if an agent with ID agent_id currently exists. More...
 
int64 agent_count ()
 Returns the current number of agents. More...
 
const_iterator agent_begin ()
 Returns an iterator pointing to the oldest agent. More...
 
const_iterator agent_end ()
 Returns an iterator pointing beyond the newest agent. More...
 
- Protected Member Functions inherited from sydevs::systems::collection_node_base
 collection_node_base (const std::string &node_name, const node_context &external_context)
 Constructs a collection_node_base. More...
 
const node_contextprototype_context ()
 Returns a const reference to the prototype node's context object. More...
 
node_structureprototype_structure ()
 Returns a non-const reference to the prototype node's encompassing structure object. More...
 
- Protected Member Functions inherited from sydevs::systems::system_node
 system_node (const std::string &node_name, const node_context &external_context)
 Constructs a system_node. More...
 
node_interfaceexternal_IO () const
 Returns a non-const reference to the node's external interface. More...
 
duration scale_planned_dt (duration planned_dt) const
 Adjusts the planned duration obtained from other nodes' event handlers. More...
 

Static Protected Attributes

static const int64 macro_event_id = std::numeric_limits<int64>::max()
 The index used to schedule macro events; it must not conflict with any of the agent indices. More...
 

Additional Inherited Members

- Protected Attributes inherited from sydevs::systems::system_node
std::mt19937 & rng
 Reference to the random number generator. More...
 

Detailed Description

template<typename AgentID, typename Node>
class sydevs::systems::collection_node< AgentID, Node >

A base class template for all collection nodes.

The collection_node base class template is inherited by classes that represent system behavior using a variable-length collection of nodes of the same type. Collection nodes feature procedurally defined behavior, similar to an atomic_node, but can also have component nodes, similar to a composite_node. A collection node's component nodes are referred to as agents. Collection nodes thus support agent-based modeling.

The procedurally defined behavior is specified by overriding the following pure virtual member functions:

  • macro_initialization_event, which is invoked during initialization and returns a planned duration;
  • macro_unplanned_event, which is invoked when a message input is received and returns a planned duration.
  • micro_planned_event, which is invoked when an agent's previous planned duration elapses and returns a planned duration;
  • macro_planned_event, which is invoked when the previous planned duration elapses and returns a planned duration;
  • macro_finalization, which is invoked during finalization.

Data is exchanged between the collection node and the agents using a proxy agent node called prototype of type Node.

If agents are message nodes (prototype.node_dmode() == message), then interactions with agents are supported by the following member functions:

  • create_agent, which creates and initializes a new agent;
  • affect_agent, which sends a message to an agent;
  • remove_agent, which finalizes and removes an agent.

If agents are flow nodes (prototype.node_dmode() == flow), then interactions with agents are supported by the following member function:

  • invoke_agent, which creates, invokes and removes a new agent;

Constructor & Destructor Documentation

template<typename AgentID , typename Node >
sydevs::systems::collection_node< AgentID, Node >::collection_node ( const std::string &  node_name,
const node_context external_context 
)
inline

Constructs a collection_node.

The collection node is created along with its associated node_interface object.

Parameters
node_nameThe name of the node within the encompassing context.
external_contextThe context in which the node is constructed.
Template Parameters
AgentIDThe type representing all agent IDs.
NodeThe type of node representing all agents.
template<typename AgentID, typename Node>
virtual sydevs::systems::collection_node< AgentID, Node >::~collection_node ( )
virtualdefault

Destructor.

Member Function Documentation

template<typename AgentID, typename Node>
template<typename T >
flow_port_proxy<T> sydevs::systems::collection_node< AgentID, Node >::access ( const port< flow, input, T > &  prototype_port)
protected

Returns a proxy of the flow input port prototype_port, allowing its value to be modified.

template<typename AgentID, typename Node>
template<typename T >
message_port_proxy<T> sydevs::systems::collection_node< AgentID, Node >::access ( const port< message, input, T > &  prototype_port)
protected

Returns a proxy of the message input port prototype_port, allowing its value to be modified.

template<typename AgentID , typename Node >
template<typename T >
const T & sydevs::systems::collection_node< AgentID, Node >::access ( const port< message, output, T > &  prototype_port)
protected

Returns the value transmitted by an agent on the message output port corresponding to prototype_port.

template<typename AgentID , typename Node >
template<typename T >
const T & sydevs::systems::collection_node< AgentID, Node >::access ( const port< flow, output, T > &  prototype_port)
protected

Return the value output by an agent on the flow output port corresponding to prototype_port.

template<typename AgentID, typename Node>
template<typename T >
collection_node<AgentID, Node>::template flow_port_proxy<T> sydevs::systems::collection_node< AgentID, Node >::access ( const port< flow, input, T > &  prototype_port)
template<typename AgentID, typename Node>
template<typename T >
collection_node<AgentID, Node>::template message_port_proxy<T> sydevs::systems::collection_node< AgentID, Node >::access ( const port< message, input, T > &  prototype_port)
template<typename AgentID, typename Node >
void sydevs::systems::collection_node< AgentID, Node >::affect_agent ( const AgentID &  agent_id)
inlineprotected

Sends a message to an agent.

The collection node must be a collection of message node agents, not function node agents. In other words, prototype.node_dmode() must be message. The message sent to the indicated agent is created by accessing a message input port on the prototype. The prototype's message input port is then reset.

Parameters
agent_idThe ID of the agent to receive a message.
template<typename AgentID , typename Node >
collection_node< AgentID, Node >::const_iterator sydevs::systems::collection_node< AgentID, Node >::agent_begin ( )
inlineprotected

Returns an iterator pointing to the oldest agent.

template<typename AgentID , typename Node >
int64 sydevs::systems::collection_node< AgentID, Node >::agent_count ( )
inlineprotected

Returns the current number of agents.

template<typename AgentID , typename Node >
collection_node< AgentID, Node >::const_iterator sydevs::systems::collection_node< AgentID, Node >::agent_end ( )
inlineprotected

Returns an iterator pointing beyond the newest agent.

template<typename AgentID, typename Node >
bool sydevs::systems::collection_node< AgentID, Node >::agent_exists ( const AgentID &  agent_id)
inlineprotected

Returns true if an agent with ID agent_id currently exists.

template<typename AgentID, typename Node >
template<typename AgentNode >
void sydevs::systems::collection_node< AgentID, Node >::create_agent ( const AgentID &  agent_id)
inlineprotected

Creates a new agent of type AgentNode.

The collection node must be a collection of message node agents, not function node agents. In other words, prototype.node_dmode() must be message. The created agent is initialized with the flow input values found on the prototype. The prototype's flow input values are left unchanged.

The created agent will be of type AgentNode, which must be the same type as Node or a type derived from Node.

Parameters
agent_idThe ID of the agent to be created.
template<typename AgentID, typename Node >
void sydevs::systems::collection_node< AgentID, Node >::create_agent ( const AgentID &  agent_id)
inlineprotected

Creates a new agent.

The collection node must be a collection of message node agents, not function node agents. In other words, prototype.node_dmode() must be message. The created agent is initialized with the flow input values found on the prototype. The prototype's flow input values are left unchanged.

Parameters
agent_idThe ID of the agent to be created.
template<typename AgentID , typename Node >
void sydevs::systems::collection_node< AgentID, Node >::handle_finalization_event ( duration  elapsed_dt)
inlinevirtual

Invoked at the end of a simulation; calls macro_finalization_event.

Implements sydevs::systems::system_node.

template<typename AgentID , typename Node >
duration sydevs::systems::collection_node< AgentID, Node >::handle_initialization_event ( )
inlinevirtual

Invoked at the beginning of a simulation; calls macro_initialization_event.

Implements sydevs::systems::system_node.

template<typename AgentID , typename Node >
duration sydevs::systems::collection_node< AgentID, Node >::handle_planned_event ( duration  elapsed_dt)
inlinevirtual

Invoked when the planned duration elapses for either an agent or the overall collection; calls micro_planned_event or macro_planned_event.

Implements sydevs::systems::system_node.

template<typename AgentID , typename Node >
duration sydevs::systems::collection_node< AgentID, Node >::handle_unplanned_event ( duration  elapsed_dt)
inlinevirtual

Invoked whenever a message is received; calls macro_unplanned_event.

Implements sydevs::systems::system_node.

template<typename AgentID, typename Node >
void sydevs::systems::collection_node< AgentID, Node >::invoke_agent ( const AgentID &  agent_id)
inlineprotected

Creates, invokes, and removes an agent.

The collection node must be a collection of function node agents, not message node agents. In other words, prototype.node_dmode() must be flow. Before invocation, flow input values are copied from the prototype to the agent. After invocation, flow output values are copied agent to the prototype.

Parameters
agent_idThe ID of the agent to be created, invoked, and removed.
template<typename AgentID , typename Node >
void sydevs::systems::collection_node< AgentID, Node >::print_on_elapsed_duration ( bool  flag = true) const
inline

If flag is true, all elapsed durations are printed for this node.

template<typename AgentID , typename Node >
void sydevs::systems::collection_node< AgentID, Node >::print_on_planned_duration ( bool  flag = true) const
inline

If flag is true, all planned durations are printed for this node.

template<typename AgentID, typename Node >
void sydevs::systems::collection_node< AgentID, Node >::remove_agent ( const AgentID &  agent_id)
inlineprotected

Finalizes and removes an agent.

The collection node must be a collection of message node agents, not function node agents. In other words, prototype.node_dmode() must be message. The flow output values of the removed agent are copied to the prototype.

Parameters
agent_idThe ID of the agent to be removed.
template<typename AgentID , typename Node >
template<typename T >
bool sydevs::systems::collection_node< AgentID, Node >::transmitted ( const port< message, output, T > &  prototype_port)
protected

Returns true if a message was transmitted by an agent on the port corresponding to prototype_port.

Member Data Documentation

template<typename AgentID, typename Node>
const int64 sydevs::systems::collection_node< AgentID, Node >::macro_event_id = std::numeric_limits<int64>::max()
staticprotected

The index used to schedule macro events; it must not conflict with any of the agent indices.

template<typename AgentID, typename Node>
const Node sydevs::systems::collection_node< AgentID, Node >::prototype

A node that serves as a proxy for all agent nodes.


The documentation for this class was generated from the following file: