Construct version 5.4.1
An agent based modeling framework
Nodeset Class Reference

A container for nodes. More...

Public Types

using iterator = std::vector< Node >::const_iterator
 

Public Member Functions

 Nodeset (const std::string &_name)
 
 ~Nodeset ()
 Deallocates the attribute pointers of all nodes it contains.
 
iterator begin (void) const
 Returns an iterator pointing the beginning of the vector of nodes. More...
 
iterator end (void) const
 Returns an iterator pointing the beyond the last node in the vector of nodes. More...
 
unsigned int size (void) const
 Returns the number of nodes in the nodeset More...
 
void add_node (const dynet::ParameterMap &attributes)
 Adds a node to the Nodeset. More...
 
void add_node (const std::string &node_name, const dynet::ParameterMap &attributes, bool verbose_initialization=false)
 Similar to Nodeset::add_node(const dynet::ParameterMap), but allows for the specification of the node's name.
 
void add_nodes (unsigned int count, const dynet::ParameterMap &attributes, bool verbose_initialization=false)
 Calls Nodeset::add_node(const dynet::ParameterMap) a number of times equal to count.
 
const Nodeget_node_by_index (unsigned int index) const
 Finds a node using the node's index. More...
 
const Nodeget_node_by_name (const std::string &name) const noexcept
 Finds a node using the node's name. More...
 
template<typename T >
void check_attributes (std::string attribute, T min, T max) const
 Checks that all nodes in the nodeset for the specified attribute. More...
 
template<typename T >
void check_attributes (std::string attribute) const
 Checks that all nodes in the nodeset for the specified attribute. More...
 
void turn_to_const () noexcept
 Modifies the nodeset such that is findable by the NodesetManager and can no longer have nodes added to it. More...
 
void import_dynetml (const std::string &fname, const std::string &dynetml_ns_name)
 Imports information from a DyNetML style xml file into the nodeset.

Parameters
fnameThe file name with either an absolute or relative directory path.
dynetml_ns_nameThe name of nodeset stored in the DyNetML file that is to be imported.

Exception Safety More...

 
void import_csv (const std::string &fname)
 Imports information from a CSV files. The header should contain the names of all attributes with the first element being blank. Each row should start with the node's name and the contents of that row corresponding to attribute values.
 
bool is_const () const noexcept
 Returns true if the nodeset can no longer be modified.
 
template<>
void check_attributes (std::string attribute) const
 
template<>
void check_attributes (std::string attribute) const
 
template<>
void check_attributes (std::string attribute) const
 
template<>
void check_attributes (std::string attribute) const
 

Public Attributes

const std::string name
 

Detailed Description

A container for nodes.

A nodeset is a container for Nodes. This includes basic functions for accessing and interacting with the nodes in the nodeset.

Nodesets are created by the NodesetManager. It is not expected that other classes in Construct would create a nodeset. Rather a pointer to an existing nodeset to find a node is the primary way a nodeset is used.

Member Function Documentation

◆ add_node()

void Nodeset::add_node ( const dynet::ParameterMap attributes)

Adds a node to the Nodeset.

Nodes are added to the nodeset with index equal to the previous nodeset size. The nodes name is created using the nodeset's name plus the node's index.

Parameters
attributesThe attributes to be saved to the new node. The values in "attributes" are copied into the new node.

Example

Nodeset& my_nodeset = *construct->ns_manager->create_nodeset("my_nodeset");
dynet::ParameterMap my_attributes {{"my att1 name", "my att1 value"}};
my_nodeset.add_node(my_attributes);
my_nodeset.add_node(my_attributes);
if (my_nodeset.get_node_by_index(0).attributes == my_nodeset.get_node_by_index(1).attributes) {
std::cout << "node 0 and node 1 use the same attributes pointer" << std::endl;
if (my_nodeset.get_node_by_index(0) != &my_attributes)
std::cout << "node 0 does not have the same attributes pointer as my_attributes" << std::endl;
}
//If two nodes use the same attributes, they will share a pointer and only store one copy of the attributes.
dynet::ParameterMap my_attributes2 = {{"my att1 name", "my att1 value"}};
my_nodeset.add_node(my_attributes2);
//Even though a different ParamterMap is used, the new node will use the same pointer
//as the previous two nodes, because their attributes content are identical
if (my_nodeset.get_node_by_index(2).attributes == my_nodeset.get_node_by_index(0).attributes)
std::cout << "node 0 and node 2 have the same attributes pointer" << std::endl;
dynet::ParameterMap my_attributes3 = {{"my att3 name", "my att3 value"}};
my_nodeset.add_node(my_attributes3);
//Adding a node with unique attributes behaves as exepcted.
if (my_nodeset.get_node_by_index(3).attributes != my_nodeset.get_node_by_index(0).attributes)
std::cout << "node 0 and node 3 do not have the same attributes pointer" << std::endl;
dynet::ParameterMap my_attributes4 = {{"my att1 name", "my att1 value"}};
my_nodeset.add_node(my_attributes4);
//Because add_node only checks the last pointer and not the entire set,
//node 4 will not have the same attributes pointer as the first two nodes even though their contents are identical.
if (my_nodeset.get_node_by_index(4).attributes != my_nodeset.get_node_by_index(0).attributes)
std::cout << "node 0 and node 4 do not have the same attributes pointer" << std::endl;
A container for nodes.
Definition: NodesetManager.h:147
void add_node(const dynet::ParameterMap &attributes)
Adds a node to the Nodeset.
Definition: NodesetManager.cpp:16
const Node * get_node_by_index(unsigned int index) const
Finds a node using the node's index.
Definition: NodesetManager.cpp:70
const dynet::ParameterMap *const attributes
Each attribute value is stored in the parameter map at the appropriate attribute key.
Definition: NodesetManager.h:78
Definition: utils.h:86

Output:

node 0 and node 1 use the same attributes pointer
node 0 does not have the same attributes pointer as my_attributes
node 0 and node 2 have the same attributes pointer
node 0 and node 3 do not have the same attributes pointer

Complexity

Constant

Iterator validity

If a reallocation happens, all iterators, pointers and references related to the container are invalidated. Otherwise, only the end iterator is invalidated, and all iterators, pointers and references to elements are guaranteed to keep referring to the same elements they were referring to before the call.

Exception Safety

An assertion is raised if the nodeset has been turned to a constant nodeset. A dynet::already_exists is thrown if the created node name (nodeset name + "_" + index) matches any previous node name.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ begin()

Nodeset::iterator Nodeset::begin ( void  ) const

Returns an iterator pointing the beginning of the vector of nodes.

Returns
A random access iterator pointing to the first node in the nodeset.

Example

//nodeset has been preloaded with some agents; Mary, John, and Joe.
const Nodeset* agents = construct->ns_manager.get_nodeset(nodeset_names::agent);
std::cout << "This nodeset conatins:" << std::endl;
for(const Node& node : *agents) {
std::cout << node.name << std::endl;
}
Nodes are any type of entity with or without attributes.
Definition: NodesetManager.h:69

Output:

This nodeset contains:
Mary
John
Joe

Complexity

Constant

Iterator validity

No changes

Exception Safety

No-throw guarantee: this member function never throws exceptions.

Here is the caller graph for this function:

◆ check_attributes() [1/2]

template<typename T >
void Nodeset::check_attributes ( std::string  attribute) const

Checks that all nodes in the nodeset for the specified attribute.

The attribute values are converted to the data type dictated the explicit instantiation of the template.

Parameters
attributeName of the attribute that each node should have.

Example

const Nodeset* ns = _construct->ns_manager.get_nodeset("ns");
// following node has been loaded into the nodeset "ns" with the following attributes
// <node name="node1">
// <attribute name="attribute1" value="0.5"/>
// <attribute name="attribute2" value="-2"/>
// </node>
try {
ns->check_attributes<float>("attribute1");
ns->check_attributes<unsigned int>("attribute2");
}
std::cout << "Error: " << e.string() << std::endl;
}
void check_attributes(std::string attribute, T min, T max) const
Checks that all nodes in the nodeset for the specified attribute.
Definition: NodesetManager.cpp:186
Exception meant to add attribute information based on a could_not_convert exception.
Definition: utils.h:192

Output:

Error: Could not convert value to unsigned int for attribute "attribute2" for node "node1". 

Complexity

Linear in number of nodes in the specified nodeset.

Iterator validity

No changes.

Exception Safety

A dynet::missing_node_attribute is thrown if a node is missing the attribute. A dynet::could_not_convert_attribute is thrown if the attribute could not be converted to the data type of the template instantiation.

◆ check_attributes() [2/2]

template<typename T >
void Nodeset::check_attributes ( std::string  attribute,
min,
max 
) const

Checks that all nodes in the nodeset for the specified attribute.

These attributes are converted to the type determined by the submitted parameters. The converted values are then checked to ensure the it lies between the submitted bounds for that attribute. The only template instantiations available are int, unsigned int, float.

Parameters
attributeName of the attribute that each node should have.
minThe minimum value the attribute can have. Any attribute value that is smaller than min will cause a dynet::out_of_range exception to be thrown.
maxThe maximum value the attribute can have. Any attribute value that is greater than max will cause a dynet::out_of_range exception to be thrown.

Example

const Nodeset* ns = _construct->ns_manager.get_nodeset("ns");
// following node has been loaded into the nodeset "ns" with the following attributes
// <node name="node1">
// <attribute name="attribute1" value="0.5"/>
// <attribute name="attribute2" value="2"/>
// </node>
try {
ns->check_attributes("attribute1", 0.0f, 1.0f);
ns->check_attributes("attribute2", 0, 1);
}
std::cout << "Error: " << e.what() << std::endl;
}

Output:

Error: "attribute2" for node "node1" is out of range [0,1]. 

Complexity

Linear in number of nodes in the specified nodeset.

Iterator validity

No changes.

Exception Safety

A dynet::missing_node_attribute is thrown if a node is missing the attribute. A dynet::could_not_convert_attribute is thrown if the attribute could not be converted to the template specialization. A dynet::out_of_range is thrown if the converted attribute value is greater than max or less than min.

Here is the caller graph for this function:

◆ end()

Nodeset::iterator Nodeset::end ( void  ) const

Returns an iterator pointing the beyond the last node in the vector of nodes.

Returns
An iterator pointing to the beyond the last node in the nodeset.

Example

//nodeset has been preloaded with some agents; Mary, John, and Joe.
const Nodeset* agents = construct->ns_manager.get_nodeset(nodeset_names::agent);
std::cout << "This nodeset conatins:" << std::endl;
for(const Node& node : *agents) {
std::cout << node.name << std::endl;
}

Output:

This nodeset contains:
Mary
John
Joe

Complexity

Constant

Iterator validity

No changes

Exception Safety

No-throw guarantee: this member function never throws exceptions.

Here is the caller graph for this function:

◆ get_node_by_index()

const Node * Nodeset::get_node_by_index ( unsigned int  index) const

Finds a node using the node's index.

This function provides drastic speed up compared to get_node_by_name as this function references a vector while the former references a binary tree.

Parameters
indexThe node's index in the nodeset.
Returns
A constant pointer to the node with index matching the parameter index. Only constant functions of a class pointed to by a constant pointer can be called.

Example

//nodeset has been preloaded with some agents; Mary, John, and Joe.
const Nodeset* agents = construct->ns_manager.get_nodeset(nodeset_names::agent);
const Node* agent = agents->get_node_by_index(0);
std::cout << "Node at index 0 is " << agent->name << std::endl;
const std::string name
Name of the node
Definition: NodesetManager.h:81

Output:

Node at index 0 is Mary 

Complexity

Constant

Iterator validity

No changes

Exception Safety

An assertion is raised if index is out of bounds for the nodeset.

Here is the caller graph for this function:

◆ get_node_by_name()

const Node * Nodeset::get_node_by_name ( const std::string &  name) const
noexcept

Finds a node using the node's name.

This function uses a binary tree to find a node, making its speed slower than get_node_by_index.

Parameters
nameThe node's name in the nodeset.
Returns
A constant pointer to the node with name matching the parameter name. Only constant functions of a class pointed to by a constant pointer can be called. If a node with the matching name is not found, a null pointer is returned instead.

Example

//nodeset has been preloaded with some agents; Mary, John, and Joe.
const Nodeset* agents = construct->ns_manager.get_nodeset(nodeset_names::agent);
const Node* agent = agents->get_node_by_name("Mary");
std::cout << "Node Mary is at index " << agent->index << std::endl;
const unsigned int index
Node index of the node
Definition: NodesetManager.h:84

Output:

Node Mary is at index 0 

Complexity

Logarithmic in size of nodeset. Underlying function uses map::find

Iterator validity

No changes

Exception Safety

No-throw guarantee: this member function never throws exceptions. If the node was not found, a null pointer is returned.

Here is the caller graph for this function:

◆ import_dynetml()

void Nodeset::import_dynetml ( const std::string &  fname,
const std::string &  dynetml_ns_name 
)

Imports information from a DyNetML style xml file into the nodeset.

Parameters
fnameThe file name with either an absolute or relative directory path.
dynetml_ns_nameThe name of nodeset stored in the DyNetML file that is to be imported.

Exception Safety

Various exceptions can be raised if the DyNetML file is not formatted correctly or if information is missing.

◆ size()

unsigned int Nodeset::size ( void  ) const

Returns the number of nodes in the nodeset

Returns
A count of how many nodes are in the nodeset as an unsigned int.

Example

//nodeset has been preloaded with some agents; Mary, John, and Joe.
const Nodeset* agents = construct->ns_manager.get_nodeset(nodeset_names::agent);
std::cout << "The number of nodes in this nodeset: " << agents->size() << std::endl;

Output:

The number of nodes in this nodeset: 3 

Complexity

Constant

Iterator validity

No changes

Exception Safety

No-throw guarantee: this member function never throws exceptions.

Here is the caller graph for this function:

◆ turn_to_const()

void Nodeset::turn_to_const ( )
noexcept

Modifies the nodeset such that is findable by the NodesetManager and can no longer have nodes added to it.

Once a nodeset has all the nodes that one wishes to add to this nodeset, this function should be called. If this function has been called, Nodeset::add_node will raise an assertion when called. If this function has not been called, a dynet::could_not_find_nodeset exception will be thrown when querying the NodesetManager for this nodeset.

Parameters
nodesetPointer to the nodeset that should be converted.

Example

Nodeset& my_nodeset = *construct->ns_manager.create_nodeset("my_nodeset");
dynet::ParameterMap my_attributes{{"my att1 name", "my att1 value"}, {"my att2 name", "my att2 value"}}
my_nodeset.add_node("Mary", my_attributes);
my_nodeset.add_node("Joe", my_attributes);
my_nodeset.add_node("John", my_attributes);
my_nodeset.turn_to_const();
if (construct->ns_manager.does_nodeset_exist("my_nodeset"))
std::cout << "my_nodeset was loaded" << std::endl;
my_nodeset.add_node("Sam", my_attributes); // raises an assertion
void turn_to_const() noexcept
Modifies the nodeset such that is findable by the NodesetManager and can no longer have nodes added t...
Definition: NodesetManager.cpp:125

Output:

my_nodeset was loaded

Complexity

Constant

Exception Safety

No-throw guarantee: this member function never throws exceptions.

Member Data Documentation

◆ name

const std::string Nodeset::name