Network structure and algorithms. More...

#include <network_kernel.hpp>

Collaboration diagram for pops::Network< RasterIndex >:

[legend]

Classes
class	ConstEitherWayIterator
	A const iterator which encapsulates either forward or reverse iterator. More...

class	SegmentView
	A const view of a Segment which can be iterated. More...

Public Types
using	NodeId = int
	Type for node IDs. More...

using	Statistics = std::map< std::string, int >
	Type for summary statistics. More...

Public Member Functions
	Network (BBox< double > bbox, double ew_res, double ns_res, double speed)
	Construct empty network. More...

std::pair< RasterIndex, RasterIndex >	xy_to_row_col (double x, double y) const
	Convert real world coordinates to row and column in the raster grid. More...

std::pair< RasterIndex, RasterIndex >	xy_to_row_col (const std::string &x, const std::string &y) const
	Coverts coordinates as xy_to_row_col(double, double) but converts from strings. More...

bool	out_of_bbox (double x, double y) const
	Test if coordinates XY are in the bounding box. More...

template<typename InputStream >
void	load (InputStream &node_stream, InputStream &segment_stream, bool allow_empty=false)
	Load nodes and segments from input streams. More...

const std::set< NodeId > &	get_nodes_at (RasterIndex row, RasterIndex col) const
	Get a list of nodes at a given cell. More...

template<typename Generator >
NodeId	get_random_node_at (RasterIndex row, RasterIndex col, Generator &generator) const
	Get a randomly selected node at a given cell. More...

bool	has_node_at (RasterIndex row, RasterIndex col) const
	Test if the network has a node at a given row and column. More...

std::pair< RasterIndex, RasterIndex >	get_node_row_col (NodeId node) const
	Get row and column for a node. More...

template<typename Generator >
std::tuple< int, int >	travel (RasterIndex row, RasterIndex col, double time, Generator &generator) const
	Travel in the network from given row and column for a given time. More...

std::vector< std::pair< NodeId, std::pair< RasterIndex, RasterIndex > > >	get_all_nodes () const
	Get all nodes as vector of all ids with their row and column. More...

Statistics	collect_statistics () const
	Collect statistics about the network. More...

template<typename OutputStream >
void	dump_yaml (OutputStream &stream) const
	Output network to a stream. More...

Static Public Member Functions
static Network	null_network ()
	Create an empty network not meant for futher use. More...

Protected Types
using	NodeMatrix = std::map< NodeId, std::vector< NodeId > >
	Node connections (edges) More...

using	Segment = std::vector< std::pair< RasterIndex, RasterIndex > >
	Cells connecting two nodes (segment between nodes) More...

using	SegmentsByNodes = std::map< std::pair< NodeId, NodeId >, Segment >
	Segments by nodes (edges) More...

Protected Member Functions
template<typename InputStream >
void	load_nodes (InputStream &stream, std::set< NodeId > &node_ids)
	Read nodes from a stream. More...

template<typename InputStream >
void	load_segments (InputStream &stream, const std::set< NodeId > &node_ids)
	Read segments from a stream. More...

SegmentView	get_segment (NodeId start, NodeId end) const
	Get a segment between the two given nodes. More...

const std::vector< NodeId > &	nodes_connected_to (NodeId node) const
	Get nodes connected by an edge to a given node. More...

template<typename Generator >
NodeId	next_node (NodeId node, const std::set< NodeId > &ignore, Generator &generator) const
	Pick a next node from the given node. More...

Static Protected Member Functions
static NodeId	node_id_from_text (const std::string &text)
	Convert string to node ID. More...

template<typename Container , typename Generator >
static NodeId	pick_random_node (const Container &nodes, Generator &generator)
	Select a random node from a list of nodes. More...

Protected Attributes
BBox< double >	bbox_
	Bounding box of the network grid in real world coordinates. More...

double	ew_res_
	East-west resolution of the grid. More...

double	ns_res_
	North-south resolution of the grid. More...

double	cell_travel_time_
	Time to travel through one cell. More...

std::map< std::pair< RasterIndex, RasterIndex >, std::set< NodeId > >	nodes_by_row_col_
	Node IDs stored by row and column (multiple nodes per cell) More...

NodeMatrix	node_matrix_
	List of node neighbors by node ID (edges) More...

SegmentsByNodes	segments_by_nodes_
	Lists of cells connecting nodes. More...

Detailed Description

template<typename RasterIndex>
class pops::Network< RasterIndex >

Network structure and algorithms.

The general workflow is contructing the object (with the constructor) and loading the data (with the load() function). Then the network is ready to be used for simulating trips over the network (with the travel() function).

When the travel() function is used from a kernel, user of the network directly calls only the setup functions.

The class exposes number of functions as public which are meant for testing or other special workflows.

RasterIndex template parameter is an integral type used for indexing in the grid, specifically used as a type for rows and columns.

Definition at line 51 of file network_kernel.hpp.

Member Typedef Documentation

◆ NodeId

template<typename RasterIndex >

using pops::Network< RasterIndex >::NodeId = int

Type for node IDs.

Definition at line 54 of file network_kernel.hpp.

◆ NodeMatrix

template<typename RasterIndex >

using pops::Network< RasterIndex >::NodeMatrix = std::map<NodeId, std::vector<NodeId> >

protected

Node connections (edges)

Definition at line 412 of file network_kernel.hpp.

◆ Segment

template<typename RasterIndex >

using pops::Network< RasterIndex >::Segment = std::vector<std::pair<RasterIndex, RasterIndex> >

protected

Cells connecting two nodes (segment between nodes)

Definition at line 414 of file network_kernel.hpp.

◆ SegmentsByNodes

template<typename RasterIndex >

using pops::Network< RasterIndex >::SegmentsByNodes = std::map<std::pair<NodeId, NodeId>, Segment>

protected

Segments by nodes (edges)

Definition at line 416 of file network_kernel.hpp.

◆ Statistics

template<typename RasterIndex >

using pops::Network< RasterIndex >::Statistics = std::map<std::string, int>

Type for summary statistics.

Definition at line 55 of file network_kernel.hpp.

Constructor & Destructor Documentation

◆ Network()

template<typename RasterIndex >

pops::Network< RasterIndex >::Network	(	BBox< double >	bbox,
		double	ew_res,
		double	ns_res,
		double	speed
	)

inline

Construct empty network.

Parameters

bbox	Bounding box of the raster grid (in real world coordinates)
ew_res	East-west resolution of the raster grid
ns_res	North-south resolution of the raster grid
speed	Speed of travel in the same units as coordinates

Definition at line 65 of file network_kernel.hpp.

Here is the caller graph for this function:

Member Function Documentation

◆ collect_statistics()

template<typename RasterIndex >

Statistics pops::Network< RasterIndex >::collect_statistics ( ) const

inline

Collect statistics about the network.

Computes statistics such as number of nodes and segments.

Returns: Associative array with statistics

Definition at line 305 of file network_kernel.hpp.

Here is the caller graph for this function:

◆ dump_yaml()

template<typename RasterIndex >

template<typename OutputStream >

void pops::Network< RasterIndex >::dump_yaml ( OutputStream & stream ) const

inline

Output network to a stream.

Writes statistics and different views of the network as a YAML file.

Definition at line 345 of file network_kernel.hpp.

Here is the call graph for this function:

◆ get_all_nodes()

template<typename RasterIndex >

std::vector<std::pair<NodeId, std::pair<RasterIndex, RasterIndex> > > pops::Network< RasterIndex >::get_all_nodes ( ) const

inline

Get all nodes as vector of all ids with their row and column.

If there is more than one node at a given cell (row and column), each of these nodes is returned as a separate item in the list.

This translates the internal representation and returns a new object.

Returns: A vector of pairs of id and row and col pair.

Definition at line 284 of file network_kernel.hpp.

◆ get_node_row_col()

template<typename RasterIndex >

std::pair<RasterIndex, RasterIndex> pops::Network< RasterIndex >::get_node_row_col ( NodeId node ) const

inline

Get row and column for a node.

Parameters

node	Node id to get the coordinates for

Returns: Row and column pair

Definition at line 226 of file network_kernel.hpp.

Here is the call graph for this function:

◆ get_nodes_at()

template<typename RasterIndex >

const std::set<NodeId>& pops::Network< RasterIndex >::get_nodes_at	(	RasterIndex	row,
		RasterIndex	col
	)		const

inline

Get a list of nodes at a given cell.

Returns a const reference to an internally stored set. If there are no nodes at a given cell, a reference to an empty set is returned.

Parameters

row	Row in the raster grid
col	Column in the raster grid

Returns: List of node IDs as a set

Definition at line 166 of file network_kernel.hpp.

Here is the caller graph for this function:

◆ get_random_node_at()

template<typename RasterIndex >

template<typename Generator >

NodeId pops::Network< RasterIndex >::get_random_node_at	(	RasterIndex	row,
		RasterIndex	col,
		Generator &	generator
	)		const

inline

Get a randomly selected node at a given cell.

There can be more than one node at a given cell. This function selects one of these nodes randomly.

Parameters

row	Row in the raster grid
col	Column in the raster grid
generator	Random number generator

Returns: Node ID

Exceptions

std::invalid_argument if there is no node at a given cell

Definition at line 190 of file network_kernel.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_segment()

template<typename RasterIndex >

SegmentView pops::Network< RasterIndex >::get_segment	(	NodeId	start,
		NodeId	end
	)		const

inlineprotected

Get a segment between the two given nodes.

For a given pair of nodes, the function finds the connecting segment and returns a view of the segment oriented according to the order of the nodes.

Parameters

start	Start node id
end	End node id

Returns: View of the segment oriented from start to end

Exceptions

std::invalid_argument if there is no segment connecting the nodes

Definition at line 624 of file network_kernel.hpp.

Here is the caller graph for this function:

◆ has_node_at()

template<typename RasterIndex >

bool pops::Network< RasterIndex >::has_node_at	(	RasterIndex	row,
		RasterIndex	col
	)		const

inline

Test if the network has a node at a given row and column.

Parameters

row	Row
col	Column

Returns: True if there is at least one node, false otherwise

Definition at line 211 of file network_kernel.hpp.

◆ load()

template<typename RasterIndex >

template<typename InputStream >

void pops::Network< RasterIndex >::load	(	InputStream &	node_stream,
		InputStream &	segment_stream,
		bool	allow_empty = `false`
	)

inline

Load nodes and segments from input streams.

Parameters

node_stream	Input stream with records for nodes
segment_stream	Input stream with records for segments
allow_empty	True if the loaded network can be empty (no nodes)

The function can take any input stream which behaves like std::ifstream or std::istringstream. These are also the two expected streams to be used (for reading from a file and reading from a string, respectively).

A simple code for reading from files without any checking may look like this:

Network network(...);
std::string node_filename = "nodes.txt";
std::string segment_filename = "segments.txt"
std::ifstream node_stream{node_filename};
std::ifstream segment_stream{segment_filename};
network.load(node_stream, segment_stream);

Definition at line 142 of file network_kernel.hpp.

Here is the call graph for this function:

◆ load_nodes()

template<typename RasterIndex >

template<typename InputStream >

void pops::Network< RasterIndex >::load_nodes	(	InputStream &	stream,
		std::set< NodeId > &	node_ids
	)

inlineprotected

Read nodes from a stream.

Parameters

	stream	Input stream with nodes and their coordinates
[out]	node_ids	Container to store node IDs in

Definition at line 515 of file network_kernel.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ load_segments()

template<typename RasterIndex >

template<typename InputStream >

void pops::Network< RasterIndex >::load_segments	(	InputStream &	stream,
		const std::set< NodeId > &	node_ids
	)

inlineprotected

Read segments from a stream.

Parameters

stream	Input stream with segments
node_ids	Container with node IDs to use

Definition at line 551 of file network_kernel.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ next_node()

template<typename RasterIndex >

template<typename Generator >

NodeId pops::Network< RasterIndex >::next_node	(	NodeId	node,
		const std::set< NodeId > &	ignore,
		Generator &	generator
	)		const

inlineprotected

Pick a next node from the given node.

If there is more than one edge leading from the given node, a random node is picked. If there are no edges leading from the given node, the node is returned.

The random node is picked from candidate nodes which are nodes connected to a given node. The candidate nodes which are in the ignore list are excluded from the random selection. If all candiate nodes are in the ignore list, the ignore list is ignored and all candidate nodes are used.

The function always returns a node to go to even if it means going to an ignored node or returning the value of the node parameter.

Definition at line 664 of file network_kernel.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ node_id_from_text()

template<typename RasterIndex >

static NodeId pops::Network< RasterIndex >::node_id_from_text ( const std::string & text )

inlinestaticprotected

Convert string to node ID.

Parameters

text	String with node ID

Returns: Node ID

Definition at line 424 of file network_kernel.hpp.

Here is the caller graph for this function:

◆ nodes_connected_to()

template<typename RasterIndex >

const std::vector<NodeId>& pops::Network< RasterIndex >::nodes_connected_to ( NodeId node ) const

inlineprotected

Get nodes connected by an edge to a given node.

Parameters

node	Node to get connections from

Returns: List of connected nodes

Definition at line 643 of file network_kernel.hpp.

Here is the caller graph for this function:

◆ null_network()

template<typename RasterIndex >

static Network pops::Network< RasterIndex >::null_network ( )

inlinestatic

Create an empty network not meant for futher use.

This is useful when a network object is needed to contruct a kernel, but it will not be used in runtime.

Returns: New Network object

Definition at line 80 of file network_kernel.hpp.

Here is the call graph for this function:

◆ out_of_bbox()

template<typename RasterIndex >

bool pops::Network< RasterIndex >::out_of_bbox	(	double	x,
		double	y
	)		const

inline

Test if coordinates XY are in the bounding box.

Parameters

x	Real world coordinate X
y	Real world coordinate Y

Returns: True if XY is in the bounding box, false otherwise.

Definition at line 114 of file network_kernel.hpp.

Here is the caller graph for this function:

◆ pick_random_node()

template<typename RasterIndex >

template<typename Container , typename Generator >

static NodeId pops::Network< RasterIndex >::pick_random_node	(	const Container &	nodes,
		Generator &	generator
	)

inlinestaticprotected

Select a random node from a list of nodes.

Definition at line 697 of file network_kernel.hpp.

Here is the caller graph for this function:

◆ travel()

template<typename RasterIndex >

template<typename Generator >

std::tuple<int, int> pops::Network< RasterIndex >::travel	(	RasterIndex	row,
		RasterIndex	col,
		double	time,
		Generator &	generator
	)		const

inline

Travel in the network from given row and column for a given time.

All previously visited nodes are tracked and, if possible, excluded from further traveling.

Returns: Final row and column pair

Definition at line 245 of file network_kernel.hpp.

Here is the call graph for this function:

◆ xy_to_row_col() [1/2]

template<typename RasterIndex >

std::pair<RasterIndex, RasterIndex> pops::Network< RasterIndex >::xy_to_row_col	(	const std::string &	x,
		const std::string &	y
	)		const

inline

Coverts coordinates as xy_to_row_col(double, double) but converts from strings.

Definition at line 103 of file network_kernel.hpp.

Here is the call graph for this function:

◆ xy_to_row_col() [2/2]

template<typename RasterIndex >

std::pair<RasterIndex, RasterIndex> pops::Network< RasterIndex >::xy_to_row_col	(	double	x,
		double	y
	)		const

inline

Convert real world coordinates to row and column in the raster grid.

Parameters

x	The X coordinate (east-west or column direction)
y	The Y coordinate (north-south or row direction)

Returns: Row and column

Definition at line 92 of file network_kernel.hpp.

Here is the caller graph for this function:

Member Data Documentation

◆ bbox_

template<typename RasterIndex >

BBox<double> pops::Network< RasterIndex >::bbox_

protected

Bounding box of the network grid in real world coordinates.

Definition at line 707 of file network_kernel.hpp.

◆ cell_travel_time_

template<typename RasterIndex >

double pops::Network< RasterIndex >::cell_travel_time_

protected

Time to travel through one cell.

Definition at line 710 of file network_kernel.hpp.

◆ ew_res_

template<typename RasterIndex >

double pops::Network< RasterIndex >::ew_res_

protected

East-west resolution of the grid.

Definition at line 708 of file network_kernel.hpp.

◆ node_matrix_

template<typename RasterIndex >

NodeMatrix pops::Network< RasterIndex >::node_matrix_

protected

List of node neighbors by node ID (edges)

Definition at line 713 of file network_kernel.hpp.

◆ nodes_by_row_col_

template<typename RasterIndex >

std::map<std::pair<RasterIndex, RasterIndex>, std::set<NodeId> > pops::Network< RasterIndex >::nodes_by_row_col_

protected

Node IDs stored by row and column (multiple nodes per cell)

Definition at line 712 of file network_kernel.hpp.

◆ ns_res_

template<typename RasterIndex >

double pops::Network< RasterIndex >::ns_res_

protected

North-south resolution of the grid.

Definition at line 709 of file network_kernel.hpp.

◆ segments_by_nodes_

template<typename RasterIndex >

SegmentsByNodes pops::Network< RasterIndex >::segments_by_nodes_

protected

Lists of cells connecting nodes.

Definition at line 714 of file network_kernel.hpp.

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

include/pops/network_kernel.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

template<typename RasterIndex> class pops::Network< RasterIndex >

Member Typedef Documentation

◆ NodeId

◆ NodeMatrix

◆ Segment

◆ SegmentsByNodes

◆ Statistics

Constructor & Destructor Documentation

◆ Network()

Member Function Documentation

◆ collect_statistics()

◆ dump_yaml()

◆ get_all_nodes()

◆ get_node_row_col()

◆ get_nodes_at()

◆ get_random_node_at()

◆ get_segment()

◆ has_node_at()

◆ load()

◆ load_nodes()

◆ load_segments()

◆ next_node()

◆ node_id_from_text()

◆ nodes_connected_to()

◆ null_network()

◆ out_of_bbox()

◆ pick_random_node()

◆ travel()

◆ xy_to_row_col() [1/2]

◆ xy_to_row_col() [2/2]

Member Data Documentation

◆ bbox_

◆ cell_travel_time_

◆ ew_res_

◆ node_matrix_

◆ nodes_by_row_col_

◆ ns_res_

◆ segments_by_nodes_

template<typename RasterIndex>
class pops::Network< RasterIndex >