King Ordering :: Boost.Graph Documentation

# King Ordering

Reduces the bandwidth of a graph by reordering the indices assigned to each vertex using local minimization of i-th bandwidths.

Complexity: O(m2 log(m) |E|) where m = max { degree(v) | v in V }
Defined in: `<boost/graph/king_ordering.hpp>`

## Example

    #include <boost/graph/adjacency_list.hpp>
    #include <boost/graph/king_ordering.hpp>
    #include <iostream>
    #include <vector>

    using namespace boost;
    using Graph = adjacency_list<vecS, vecS, undirectedS>;
    using Vertex = graph_traits<Graph>::vertex_descriptor;

    int main() {
        Graph g(6);
        add_edge(0, 3, g); add_edge(0, 5, g);
        add_edge(1, 2, g); add_edge(1, 4, g);
        add_edge(2, 5, g); add_edge(3, 4, g);

        std::vector<Vertex> order;
        king_ordering(g, std::back_inserter(order));

        std::cout << "King ordering:";
        for (auto v : order)
            std::cout << " " << v;
        std::cout << "\n";
    }

    King ordering: 1 2 4 5 3 0

### (1) Single starting vertex

    template <class IncidenceGraph, class OutputIterator,
              class ColorMap, class DegreeMap, class VertexIndexMap>
    OutputIterator king_ordering(
        const IncidenceGraph& g,
        typename graph_traits<Graph>::vertex_descriptor s,
        OutputIterator inverse_permutation,
        ColorMap color, DegreeMap degree, VertexIndexMap index_map);

Direction | Parameter | Description
--- | --- | ---
IN | `const IncidenceGraph& g` | An undirected graph. The graph’s type must be a model of IncidenceGraph.
IN | `vertex_descriptor s` | The starting vertex.
OUT | `OutputIterator inverse_permutation` | The new vertex ordering. The vertices are written to the output iterator in their new order.
WORK | `ColorMap color` | Used internally to keep track of the progress of the algorithm (to avoid visiting the same vertex twice).
IN | `DegreeMap degree` | This must map vertices to their degree.
IN | `VertexIndexMap index_map` | This maps each vertex to an integer in the range `[0, num_vertices(g))`. The type `VertexIndexMap` must be a model of Readable Property Map. The value type of the map must be an integer type. The vertex descriptor type of the graph needs to be usable as the key type of the map.

### (2) Automatic starting vertex selection

    template <class IncidenceGraph, class OutputIterator>
    OutputIterator king_ordering(
        const IncidenceGraph& g,
        OutputIterator inverse_permutation);

    template <class IncidenceGraph, class OutputIterator, class VertexIndexMap>
    OutputIterator king_ordering(
        const IncidenceGraph& g,
        OutputIterator inverse_permutation,
        VertexIndexMap index_map);

    template <class VertexListGraph, class OutputIterator,
              class ColorMap, class DegreeMap, class VertexIndexMap>
    OutputIterator king_ordering(
        const VertexListGraph& G,
        OutputIterator inverse_permutation,
        ColorMap color, DegreeMap degree, VertexIndexMap index_map);

Direction | Parameter | Description
--- | --- | ---
IN | `const VertexListGraph& g` | An undirected graph. The graph’s type must be a model of VertexListGraph.
OUT | `OutputIterator inverse_permutation` | The new vertex ordering. The vertices are written to the output iterator in their new order.
WORK | `ColorMap color` | Used internally to keep track of the progress of the algorithm (to avoid visiting the same vertex twice).
IN | `DegreeMap degree` | This must map vertices to their degree.
IN | `VertexIndexMap index_map` | This maps each vertex to an integer in the range `[0, num_vertices(g))`. The type `VertexIndexMap` must be a model of Readable Property Map. The value type of the map must be an integer type. The vertex descriptor type of the graph needs to be usable as the key type of the map.

### (3) Explicit starting vertex queue

    template <class IncidenceGraph, class OutputIterator,
              class ColorMap, class DegreeMap, class VertexIndexMap>
    OutputIterator king_ordering(
        const IncidenceGraph& g,
        std::deque<typename graph_traits<Graph>::vertex_descriptor> vertex_queue,
        OutputIterator permutation,
        ColorMap color, DegreeMap degree, VertexIndexMap index_map);

Direction | Parameter | Description
--- | --- | ---
IN | `const IncidenceGraph& g` | An undirected graph. The graph’s type must be a model of IncidenceGraph.
IN | `std::deque<typename graph_traits<Graph>::vertex_descriptor> vertex_queue` | The deque containing the starting vertices for each component.
OUT | `OutputIterator permutation` | The new vertex ordering. The vertices are written to the output iterator in their new order.
WORK | `ColorMap color` | Used internally to keep track of the progress of the algorithm (to avoid visiting the same vertex twice).
IN | `DegreeMap degree` | This must map vertices to their degree.
IN | `VertexIndexMap index_map` | This maps each vertex to an integer in the range `[0, num_vertices(g))`. The type `VertexIndexMap` must be a model of Readable Property Map. The value type of the map must be an integer type. The vertex descriptor type of the graph needs to be usable as the key type of the map.

## Description

The goal of the King ordering algorithm [56] is to reduce the bandwidth of a graph by reordering the indices assigned to each vertex. The King ordering algorithm works by a local minimization of the i-th bandwidths. The vertices are basically assigned a breadth-first search order, except that at each step, the adjacent vertices are placed in the queue in order of increasing pseudo-degree, where pseudo-degree is defined as the number of outgoing edges with white endpoints (vertices yet to be examined).

Overload (1) lets the user choose the "starting vertex". Overload (2) finds a good starting vertex using the pseudo-peripheral pair heuristic (among each component). Overload (3) contains the starting nodes for each vertex in the deque. The choice of the "starting vertex" can have a significant effect on the quality of the ordering.

The output of the algorithm are the vertices in the new ordering. Storing the output into a vector gives you the permutation from the new ordering to the old ordering.

    inv_perm[new_index[u]] == u

Often times, it is the opposite permutation that you want, the permutation from the old index to the new index. This can easily be computed in the following way.

    for (size_type i = 0; i != inv_perm.size(); ++i)
        perm[old_index[inv_perm[i]]] = i;

## Returns

`OutputIterator`— the iterator past the end of the output sequence of reordered vertices.

## Notes

This algorithm was introduced in: King, I.P. "An automatic reordering scheme for simultaneous equations derived from network analysis." Int. J. Numer. Methods Engrg. 2 (1970), 523-533.