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 Node *	get_node_by_index (unsigned int index) const
	Finds a node using the node's index. More...
const Node *	get_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 fname The file name with either an absolute or relative directory path. dynetml_ns_name The 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

attributes

The 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;

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;
}

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

attribute

Name 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");
}
catch (const dynet::could_not_convert_attribute& e) {
    std::cout << "Error: " << e.string() << std::endl;
}

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,
		T	min,
		T	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

attribute	Name of the attribute that each node should have.
min	The 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.
max	The 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);
}
catch (const dynet::could_not_convert_attribute& e) {
    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

index

The 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;

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

name	The 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;

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

fname	The file name with either an absolute or relative directory path.
dynetml_ns_name	The 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

nodeset

Pointer 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

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