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.
	operator const Nodeset * () const
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 &	operator[] (unsigned int index) const noexcept
	Returns the node at the specified index. More...
const Node &	operator[] (const std::string &name) const
	Returns the node with the specified name. More...
const Node *	get_node_by_index (unsigned int index) const
	Returns the node at the specified index. More...
const Node *	get_node_by_name (const std::string &name) const noexcept
	Returns the node with the specified 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	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.
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(Nodeset::iterator it = agents->begin(); it != agents->end(); ++it) {
    std::cout << it->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(Nodeset::iterator it = agents->begin(); it != agents->end(); ++it) {
    std::cout << it->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

Returns the node at the specified index.

Parameters

index

The index of the node being queried.

Returns

A reference to a Node whose index matches the specified index.

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 << agents[0] << " " << agents[2] << std::endl;

Output:

Mary Joe 

Complexity

Constant

Iterator validity

No changes

Exception Safety

An assertion is raised if the index is equal to or larger than the size of the nodeset.

get_node_by_name()

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

noexcept

Returns the node with the specified name.

Parameters

name	The name of the node being queried.

Returns

A reference to a Node whose name matches the specified name.

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 << agents["Mary"].index << " " << agents["Joe"].index << std::endl;

Output:

0 2 

Complexity

Constant

Iterator validity

No changes

Exception Safety

An exception is thrown if no node exists with the queried name.

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.

operator[]() [1/2]

const Node & Nodeset::operator[] ( const std::string &  name ) const

inline

Returns the node with the specified name.

Parameters

name	The name of the node being queried.

Returns

A reference to a Node whose name matches the specified name.

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 << agents["Mary"].index << " " << agents["Joe"].index << std::endl;

Output:

0 2 

Complexity

Constant

Iterator validity

No changes

Exception Safety

An exception is thrown if no node exists with the queried name.

operator[]() [2/2]

const Node & Nodeset::operator[] ( unsigned int  index ) const

inlinenoexcept

Returns the node at the specified index.

Parameters

index

The index of the node being queried.

Returns

A reference to a Node whose index matches the specified index.

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 << agents[0] << " " << agents[2] << std::endl;

Output:

Mary Joe 

Complexity

Constant

Iterator validity

No changes

Exception Safety

An assertion is raised if the index is equal to or larger than the size of the nodeset.

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:

Member Data Documentation

name

const std::string Nodeset::name

summary>