Graph Utilities

Provides functions which wrap common tasks for writing out data from graphs. More...

Collaboration diagram for Graph Utilities:

Functions
template<typename Graph >
std::shared_ptr< HDFGroup >	Utopia::DataIO::create_graph_group (const Graph &g, const std::shared_ptr< HDFGroup > &parent_grp, const std::string &name)
template<typename Graph >
void	Utopia::DataIO::save_graph (const Graph &g, const std::shared_ptr< HDFGroup > &grp)
	Write function for a boost::Graph.
template<typename Graph , typename PropertyMap >
void	Utopia::DataIO::save_graph (const Graph &g, const std::shared_ptr< HDFGroup > &grp, const PropertyMap vertex_ids)
	Write function for a boost::Graph.
template<IterateOver iterate_over, typename Graph , typename... Adaptors>
void	Utopia::DataIO::save_graph_entity_properties (const Graph &g, const std::shared_ptr< HDFGroup > &nw_grp, const std::string &label, const std::tuple< Adaptors... > &adaptor_tuple)
template<typename Graph , typename... Adaptors>
void	Utopia::DataIO::save_vertex_properties (Graph &&g, const std::shared_ptr< HDFGroup > &nw_grp, const std::string &label, const std::tuple< Adaptors... > &adaptor_tuple)
template<typename Graph , typename... Adaptors>
void	Utopia::DataIO::save_edge_properties (Graph &&g, const std::shared_ptr< HDFGroup > &nw_grp, const std::string &label, const std::tuple< Adaptors... > &adaptor_tuple)

Detailed Description

Provides functions which wrap common tasks for writing out data from graphs.

Graph Utilities Module

Overview

This module implements functions which wrap common tasks people face when they wish to extract data from boost::graph objects.

Implementation

The provided functions can be separated into two groups, one which saves the entire graph, i.e., its edge-vertex structure, and a second one which allows to extract data associated with either edges or vertices via user supplied functions.

Function Documentation

create_graph_group()

template<typename Graph >

std::shared_ptr< HDFGroup > Utopia::DataIO::create_graph_group	(	const Graph &	g,
		const std::shared_ptr< HDFGroup > &	parent_grp,
		const std::string &	name
	)

This function opens a HDFGroup for graph data and adds attributes.

The attributes that are set mark the newly created group as containing network data and add some graph metadata like whether the graph is directed and/or allows parallel edges.

Template Parameters

Graph

Parameters

g	The graph to save
parent_grp	The parent HDFGroup the graph data should be stored in
name	The name the newly created graph group should have

Returns

std::shared_ptr<HDFGroup> The newly created graph group

{
    // Create the group for the graph and store metadata in its attributes
    auto grp = parent_grp->open_group(name);
 
    grp->add_attribute("content", "graph");
    // Store additional metadata in the group attributes
    grp->add_attribute("is_directed", boost::is_directed(g));
    grp->add_attribute("allows_parallel", boost::allows_parallel_edges(g));
 
    // Store the information on the edge container shape
    // NOTE Here, it is assumed that the edge data is written in shape (2,N).
    //      If this is not the case, the attribute must be overwritten.
    grp->add_attribute("edge_container_is_transposed", true);
 
    // Prevent the vertex and edge dimension from being squeezed when selecting
    // graph data via the GraphGroup.
    grp->add_attribute(
        "keep_dim", std::vector<std::string>{"vertex_idx", "edge_idx"}
    );
 
    spdlog::get("data_io")->info("Opened graph group '{}'.", name);
 
    return grp;
}

save_edge_properties()

template<typename Graph , typename... Adaptors>

void Utopia::DataIO::save_edge_properties	(	Graph &&	g,
		const std::shared_ptr< HDFGroup > &	nw_grp,
		const std::string &	label,
		const std::tuple< Adaptors... > &	adaptor_tuple
	)

This function writes the results of all functions in a named tuple, applied to all edges of a boost::graph into a HDFGroup.

This function calls the general save_graph_entity_properties method using IterateOver::edges. See Utopia::DataIO::save_graph_entity_properties for more detail.

Template Parameters

Graph
Adaptors

Parameters

g	The graph from which to save edge properties.
nw_grp	The HDFGroup the data should be written to.
label	Under which label the results of the adaptors should be stored.
adaptor_tuple	Which edge-associated properties to write.

Returns

void

{
    save_graph_entity_properties<IterateOver::edges>(std::forward<Graph>(g),
                                                     nw_grp,
                                                     label,
                                                     adaptor_tuple);
}

save_graph() [1/2]

template<typename Graph >

void Utopia::DataIO::save_graph	(	const Graph &	g,
		const std::shared_ptr< HDFGroup > &	grp
	)

Write function for a boost::Graph.

This function writes a boost::graph into a HDFGroup. It assumes that the vertices and edges of the graph already supply indices.

Template Parameters

Graph

Parameters

g	The graph to save
grp	The HDFGroup the graph should be stored in

Returns

void

{
    // Create and prepare the datasets for vertices and edges
    auto [dset_vertices,
          dset_edges] = GraphUtilsHelper::setup_graph_containers(g, grp);
 
    // Save vertex list
    auto [v, v_end] = boost::vertices(g);
    dset_vertices->write(v, v_end, [&](auto vd) {
        return boost::get(boost::vertex_index_t(), g, vd);
    });
 
    // Save edges
    // NOTE Need to call write twice to achieve the desired data shape.
    auto [e, e_end] = boost::edges(g);
    dset_edges->write(e, e_end, [&](auto ed) {
        return boost::get(boost::vertex_index_t(), g, boost::source(ed, g));
    });
 
    dset_edges->write(e, e_end, [&](auto ed) {
        return boost::get(boost::vertex_index_t(), g, boost::target(ed, g));
    });
 
    spdlog::get("data_io")->debug("Graph saved.");
}

save_graph() [2/2]

template<typename Graph , typename PropertyMap >

void Utopia::DataIO::save_graph	(	const Graph &	g,
		const std::shared_ptr< HDFGroup > &	grp,
		const PropertyMap	vertex_ids
	)

Write function for a boost::Graph.

This function writes a boost::graph into a HDFGroup. By supplying custom vertex IDs, they need not be part of the graph in order for this function to operate.

Template Parameters

Graph
PropertyMap	The property map of the vertex ids

Parameters

g	The graph to save
grp	The HDFGroup the graph should be stored in
vertex_ids	A custom property map of vertex IDs to use

Returns

void

{
    // Create and prepare the datasets for vertices and edges
    auto [dset_vertices,
          dset_edges] = GraphUtilsHelper::setup_graph_containers(g, grp);
 
    // Save vertex list
    auto [v, v_end] = boost::vertices(g);
    dset_vertices->write(
        v, v_end, [&](auto vd) { return boost::get(vertex_ids, vd); });
 
    // Save edges
    // NOTE Need to call write twice to achieve the desired data shape.
    auto [e, e_end] = boost::edges(g);
    dset_edges->write(e, e_end, [&](auto ed) {
        return boost::get(vertex_ids, boost::source(ed, g));
    });
 
    dset_edges->write(e, e_end, [&](auto ed) {
        return boost::get(vertex_ids, boost::target(ed, g));
    });
 
    spdlog::get("data_io")->debug("Graph saved.");
}

save_graph_entity_properties()

template<IterateOver iterate_over, typename Graph , typename... Adaptors>

void Utopia::DataIO::save_graph_entity_properties	(	const Graph &	g,
		const std::shared_ptr< HDFGroup > &	nw_grp,
		const std::string &	label,
		const std::tuple< Adaptors... > &	adaptor_tuple
	)

This function writes the results of all functions in a named tuple, applied to all vertices/edges of a boost::graph into a HDFGroup.

For each adaptor, the data written by this function is available at the path nw_grp/adaptor_name/label, where label is a dataset of size {num_edges/vertices} in the 1d case or {num_adaptors, num_edges/vertices} if data from more than one adaptor is to be written.

Attributes are added to the datasets that determine the dimension names and the coordinates. The name of dimension -1 is set to vertex_idx/edge_idx. The respective coordinates are the trivial ones. In the case of 2d data custom dimension name and coordinates for dimension need to be given. Note that the former has to be string-like and the latter have to be of the same type.

Warning

The coordinate type is deduced from the first coordinate. All other coordinates have to be of the same type.

Template Parameters

IterateOver	The type of iterator that is used to access the graph. The entity properties can be accessed either via edge-descriptors (IterateOver::edges) or via vertex-descriptors (IterateOver::vertices).
Graph
Adaptors

Parameters

g	The graph from which to save vertex or edge properties.
nw_grp	The HDFGroup the data should be written to. This should be the previously created network group. For each tuple entry, a new group will be created, which has the name specified as first element of that tuple.
label	Under which label the results of the adaptors should be stored. This will be the name of the dataset to which the adaptors write data. If time-varying data is to be written, this can be used to specify the time step.
adaptor_tuple	Which vertex- or edge-associated properties to write. This should be a tuple of tuples, where the latter are of one of the following forms: If (adaptor_name, adaptor) then 1d data is written. If (adaptor_name, dim0_name, (coord1, adaptor1), (coord2, adaptor2), ...) then 2d data is written.

Returns

void

{
 
    static_assert(
        // assert stringlike-ness of first thing
        std::conjunction_v<Utils::is_string<
            std::tuple_element_t<0, std::decay_t<Adaptors>>>...>,
        "Error, the first entry of each entry of 'adaptor_tuple' has to be "
        "string like, to name the adaptor");
 
    static_assert(
        iterate_over == IterateOver::vertices or
        iterate_over == IterateOver::edges, "Error, unknown iterator type! "
        "Has to be either 'IterateOver::vertices' or 'IterateOver::edges'"
    );
 
    // NOTE Consider a check for literal types, which is more capable than
    //      the (now removed) std::is_literal_type ...
 
    // Get a logger
    auto log = spdlog::get("data_io");
 
    using GraphUtilsHelper::EntityKind;
    using GraphUtilsHelper::generate_write_function;
 
    // ... vertex_iterator ...
    if constexpr (iterate_over == IterateOver::vertices)
    {
        // Collect some information on the graph
        const auto num_vertices = boost::num_vertices(g);
 
        // Make vertex iterator pair
        auto it_pair = GraphUtils::iterator_pair<IterateOver::vertices>(g);
 
        // Get write function that saves data given by the adaptor(s) to new
        // dataset(s), fire-and-forget
        auto write_f = generate_write_function<EntityKind::vertex>(
                                                        g, nw_grp,
                                                        label,
                                                        it_pair,
                                                        num_vertices);
 
        boost::hana::for_each(adaptor_tuple, write_f);
 
        log->debug("Graph vertex properties saved with label '{}'.", label);
    }
 
    // ... and edge_iterator
    else {
        // Collect some information on the graph
        const auto num_edges = boost::num_edges(g);
 
        // Make edge iterator pair
        auto it_pair = GraphUtils::iterator_pair<IterateOver::edges>(g);
 
        // Get write function that saves data given by the adaptor(s) to new
        // dataset(s), fire-and-forget
        auto write_f = generate_write_function<EntityKind::edge>(
                                                        g, nw_grp,
                                                        label,
                                                        it_pair,
                                                        num_edges);
 
        boost::hana::for_each(adaptor_tuple, write_f);
 
        log->debug("Graph edge properties saved with label '{}'.", label);
    }
}

save_vertex_properties()

template<typename Graph , typename... Adaptors>

void Utopia::DataIO::save_vertex_properties	(	Graph &&	g,
		const std::shared_ptr< HDFGroup > &	nw_grp,
		const std::string &	label,
		const std::tuple< Adaptors... > &	adaptor_tuple
	)

This function writes the results of all functions in a named tuple, applied to all vertices of a boost::graph into a HDFGroup.

This function calls the general save_graph_entity_properties method using IterateOver::vertices. See Utopia::DataIO::save_graph_entity_properties for more detail.

Template Parameters

Graph
Adaptors

Parameters

g	The graph from which to save vertex properties.
nw_grp	The HDFGroup the data should be written to.
label	Under which label the results of the adaptors should be stored.
adaptor_tuple	Which vertex–associated properties to write.

Returns

void

{
    save_graph_entity_properties<IterateOver::vertices>(std::forward<Graph>(g),
                                                        nw_grp,
                                                        label,
                                                        adaptor_tuple);
}