# Chapter 17. Structural properties of graphs

These functions usually calculate some structural property of a graph, like its diameter, the degree of the nodes, etc.

## 1. Basic properties

### 1.1. `igraph_are_adjacent` — Decides whether two vertices are adjacent.

    igraph_error_t igraph_are_adjacent(const igraph_t *graph,
                             igraph_int_t v1, igraph_int_t v2,
                             igraph_bool_t *res);

Decides whether there are any edges that have `v1` and `v2` as endpoints. This function is of course symmetric for undirected graphs.

Arguments:

`graph`: | The graph object.
`v1`: | The first vertex.
`v2`: | The second vertex.
`res`: | Boolean, `true` if there is an edge from `v1` to `v2`, `false` otherwise.

Returns:

`` | The error code `IGRAPH_EINVVID` is returned if an invalid vertex ID is given.

Time complexity: O( min(log(d1), log(d2)) ), d1 is the (out-)degree of `v1` and d2 is the (in-)degree of `v2`.

## 2. Sparsifiers

### 2.1. `igraph_spanner` — Calculates a spanner of a graph with a given stretch factor.

    igraph_error_t igraph_spanner(const igraph_t *graph, igraph_vector_int_t *spanner,
            igraph_real_t stretch, const igraph_vector_t *weights);

A spanner of a graph `G = (V,E)` with a stretch `t` is a subgraph `H = (V,Es)` such that `Es` is a subset of `E` and the distance between any pair of nodes in `H` is at most `t` times the distance in `G`. The returned graph is always a spanner of the given graph with the specified stretch. For weighted graphs the number of edges in the spanner is `O(k n^(1 + 1 / k))`, where `k` is `k = (t + 1) / 2`, `m` is the number of edges and `n` is the number of nodes in `G`. For unweighted graphs the number of edges is `O(n^(1 + 1 / k) + kn)`.

This function is based on the algorithm of Baswana and Sen: "A Simple and Linear Time Randomized Algorithm for Computing Sparse Spanners in Weighted Graphs". https://doi.org/10.1002/rsa.20130

Arguments:

`graph`: | An undirected connected graph object. If the graph is directed, the directions of the edges will be ignored.
`spanner`: | An initialized vector, the IDs of the edges that constitute the calculated spanner will be returned here. Use `igraph_subgraph_from_edges()` to extract the spanner as a separate graph object.
`stretch`: | The stretch factor `t` of the spanner.
`weights`: | The edge weights or `NULL`.

Returns:

`` | Error code.

Time complexity: The algorithm is a randomized Las Vegas algorithm. The expected running time is O(km) where k is the value mentioned above and m is the number of edges.

## 3. (Shortest)-path related functions

### 3.1. `igraph_distances` — Length of the shortest paths between vertices.

    igraph_error_t igraph_distances(
            const igraph_t *graph,
            const igraph_vector_t *weights,
            igraph_matrix_t *res,
            const igraph_vs_t from, const igraph_vs_t to,
            igraph_neimode_t mode);

Arguments:

`graph`: | The graph object.
`weights`: | Optional edge weights. If `NULL`, the graph is considered unweighted, i.e. all edge weights are 1.

`res`:

The result of the calculation, a matrix. A pointer to an initialized matrix, to be more precise. The matrix will be resized if needed. It will have the same number of rows as the length of the `from` argument, and its number of columns is the number of vertices in the `to` argument. One row of the matrix shows the distances from/to a given vertex to the ones in `to`. For the unreachable vertices `IGRAPH_INFINITY` is returned.

`from`: | The source vertices.
`to`: | The target vertices. It is not allowed to include a vertex twice or more.

`mode`:

The type of shortest paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the lengths of the outgoing paths are calculated.
`IGRAPH_IN` | the lengths of the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(n(|V|+|E|)), n is the number of vertices to calculate, |V| and |E| are the number of vertices and edges in the graph.

See also:

`` | `igraph_get_shortest_paths()` to get the paths themselves, `igraph_distances_dijkstra()` for the weighted version with non-negative weights, `igraph_distances_bellman_ford()` if you also have negative weights.

Example 17.1. File `examples/simple/distances.c`

    #include <igraph.h>

    int main(void) {

        igraph_t graph;
        igraph_real_t weights_data[] = { 0, 2, 1, 0, 5, 2, 1, 1, 0, 2, 2, 8, 1, 1, 3, 1, 1, 4, 2, 1 };
        const igraph_vector_t weights =
            igraph_vector_view(weights_data, sizeof(weights_data) / sizeof(weights_data[0]));
        igraph_matrix_t res;
        igraph_real_t cutoff;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&graph, 10, IGRAPH_DIRECTED,
                     0, 1, 0, 2, 0, 3,    1, 2, 1, 4, 1, 5,
                     2, 3, 2, 6,          3, 2, 3, 6,
                     4, 5, 4, 7,          5, 6, 5, 8, 5, 9,
                     7, 5, 7, 8,          8, 9,
                     5, 2,
                     2, 1,
                     -1);

        igraph_matrix_init(&res, 0, 0);

        printf("Unweighted distances:\n\n");

        igraph_distances(&graph, NULL, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT);
        igraph_matrix_print(&res);

        cutoff = 3; /* distances longer than this will be returned as infinity */
        printf("\nUnweighted distances with a cutoff of %g:\n\n", cutoff);
        igraph_distances_cutoff(&graph, NULL, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT, cutoff);
        igraph_matrix_print(&res);

        printf("\nWeighted distances:\n\n");

        igraph_distances(&graph, &weights, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT);
        igraph_matrix_print(&res);

        cutoff = 8; /* distances longer than this will be returned as infinity */
        printf("\nWeighted distances with a cutoff of %g:\n\n", cutoff);
        igraph_distances_cutoff(&graph, &weights, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT, cutoff);
        igraph_matrix_print(&res);

        igraph_matrix_destroy(&res);
        igraph_destroy(&graph);

        return 0;
    }

### 3.2. `igraph_distances_cutoff` — Length of the shortest paths between vertices, with cutoff.

    igraph_error_t igraph_distances_cutoff(
            const igraph_t *graph,
            const igraph_vector_t *weights,
            igraph_matrix_t *res,
            const igraph_vs_t from, const igraph_vs_t to,
            igraph_neimode_t mode,
            igraph_real_t cutoff);

This function is similar to `igraph_distances()`, but paths longer than `cutoff` will not be considered.

Arguments:

`graph`: | The graph object.
`weights`: | Optional edge weights. If `NULL`, the graph is considered unweighted, i.e. all edge weights are equal to 1.

`res`:

The result of the calculation, a matrix. A pointer to an initialized matrix, to be more precise. The matrix will be resized if needed. It will have the same number of rows as the length of the `from` argument, and its number of columns is the number of vertices in the `to` argument. One row of the matrix shows the distances from/to a given vertex to the ones in `to`. For the unreachable vertices `IGRAPH_INFINITY` is returned.

`from`: | The source vertices._d
`to`: | The target vertices. It is not allowed to include a vertex twice or more.

`mode`:

The type of shortest paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the lengths of the outgoing paths are calculated.
`IGRAPH_IN` | the lengths of the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`cutoff`: | The maximal length of paths that will be considered. When the distance of two vertices is greater than this value, it will be returned as `IGRAPH_INFINITY`. Negative cutoffs and `IGRAPH_UNLIMITED` are treated as infinity.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(s |E| + |V|), where s is the number of source vertices to use, and |V| and |E| are the number of vertices and edges in the graph.

See also:

`` | `igraph_distances_dijkstra_cutoff()` for the weighted version with non-negative weights.

Example 17.2. File `examples/simple/distances.c`

    #include <igraph.h>

    int main(void) {

        igraph_t graph;
        igraph_real_t weights_data[] = { 0, 2, 1, 0, 5, 2, 1, 1, 0, 2, 2, 8, 1, 1, 3, 1, 1, 4, 2, 1 };
        const igraph_vector_t weights =
            igraph_vector_view(weights_data, sizeof(weights_data) / sizeof(weights_data[0]));
        igraph_matrix_t res;
        igraph_real_t cutoff;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&graph, 10, IGRAPH_DIRECTED,
                     0, 1, 0, 2, 0, 3,    1, 2, 1, 4, 1, 5,
                     2, 3, 2, 6,          3, 2, 3, 6,
                     4, 5, 4, 7,          5, 6, 5, 8, 5, 9,
                     7, 5, 7, 8,          8, 9,
                     5, 2,
                     2, 1,
                     -1);

        igraph_matrix_init(&res, 0, 0);

        printf("Unweighted distances:\n\n");

        igraph_distances(&graph, NULL, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT);
        igraph_matrix_print(&res);

        cutoff = 3; /* distances longer than this will be returned as infinity */
        printf("\nUnweighted distances with a cutoff of %g:\n\n", cutoff);
        igraph_distances_cutoff(&graph, NULL, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT, cutoff);
        igraph_matrix_print(&res);

        printf("\nWeighted distances:\n\n");

        igraph_distances(&graph, &weights, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT);
        igraph_matrix_print(&res);

        cutoff = 8; /* distances longer than this will be returned as infinity */
        printf("\nWeighted distances with a cutoff of %g:\n\n", cutoff);
        igraph_distances_cutoff(&graph, &weights, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT, cutoff);
        igraph_matrix_print(&res);

        igraph_matrix_destroy(&res);
        igraph_destroy(&graph);

        return 0;
    }

### 3.3. `igraph_distances_dijkstra` — Weighted shortest path lengths between vertices.

    igraph_error_t igraph_distances_dijkstra(
            const igraph_t *graph,
            igraph_matrix_t *res,
            const igraph_vs_t from,
            const igraph_vs_t to,
            const igraph_vector_t *weights,
            igraph_neimode_t mode);

This function implements Dijkstra's algorithm, which can find the weighted shortest path lengths from a source vertex to all other vertices. This function allows specifying a set of source and target vertices. The algorithm is run independently for each source and the results are retained only for the specified targets. This implementation uses a binary heap for efficiency.

Arguments:

`graph`: | The input graph, can be directed.
`res`: | The result, a matrix. A pointer to an initialized matrix should be passed here. The matrix will be resized as needed. Each row contains the distances from a single source, to the vertices given in the `to` argument. Unreachable vertices have distance `IGRAPH_INFINITY`.
`from`: | The source vertices.
`to`: | The target vertices. It is not allowed to include a vertex twice or more.
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. If this is a null pointer, then the unweighted version, `igraph_distances()` is called.
`mode`: | For directed graphs; whether to follow paths along edge directions (`IGRAPH_OUT`), or the opposite (`IGRAPH_IN`), or ignore edge directions completely (`IGRAPH_ALL`). It is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(s*|E|log|V|+|V|), where |V| is the number of vertices, |E| the number of edges and s the number of sources.

See also:

`` | `igraph_distances()` for a non-algorithm-specific interface or `igraph_distances_bellman_ford()` for a weighted variant that works in the presence of negative edge weights (but no negative loops)

Example 17.3. File `examples/simple/distances.c`

    #include <igraph.h>

    int main(void) {

        igraph_t graph;
        igraph_real_t weights_data[] = { 0, 2, 1, 0, 5, 2, 1, 1, 0, 2, 2, 8, 1, 1, 3, 1, 1, 4, 2, 1 };
        const igraph_vector_t weights =
            igraph_vector_view(weights_data, sizeof(weights_data) / sizeof(weights_data[0]));
        igraph_matrix_t res;
        igraph_real_t cutoff;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&graph, 10, IGRAPH_DIRECTED,
                     0, 1, 0, 2, 0, 3,    1, 2, 1, 4, 1, 5,
                     2, 3, 2, 6,          3, 2, 3, 6,
                     4, 5, 4, 7,          5, 6, 5, 8, 5, 9,
                     7, 5, 7, 8,          8, 9,
                     5, 2,
                     2, 1,
                     -1);

        igraph_matrix_init(&res, 0, 0);

        printf("Unweighted distances:\n\n");

        igraph_distances(&graph, NULL, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT);
        igraph_matrix_print(&res);

        cutoff = 3; /* distances longer than this will be returned as infinity */
        printf("\nUnweighted distances with a cutoff of %g:\n\n", cutoff);
        igraph_distances_cutoff(&graph, NULL, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT, cutoff);
        igraph_matrix_print(&res);

        printf("\nWeighted distances:\n\n");

        igraph_distances(&graph, &weights, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT);
        igraph_matrix_print(&res);

        cutoff = 8; /* distances longer than this will be returned as infinity */
        printf("\nWeighted distances with a cutoff of %g:\n\n", cutoff);
        igraph_distances_cutoff(&graph, &weights, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT, cutoff);
        igraph_matrix_print(&res);

        igraph_matrix_destroy(&res);
        igraph_destroy(&graph);

        return 0;
    }

### 3.4. `igraph_distances_dijkstra_cutoff` — Weighted shortest path lengths between vertices, with cutoff.

    igraph_error_t igraph_distances_dijkstra_cutoff(
            const igraph_t *graph,
            igraph_matrix_t *res,
            const igraph_vs_t from,
            const igraph_vs_t to,
            const igraph_vector_t *weights,
            igraph_neimode_t mode,
            igraph_real_t cutoff);

This function is similar to `igraph_distances_dijkstra()`, but paths longer than `cutoff` will not be considered.

Arguments:

`graph`: | The input graph, can be directed.
`res`: | The result, a matrix. A pointer to an initialized matrix should be passed here. The matrix will be resized as needed. Each row contains the distances from a single source, to the vertices given in the `to` argument. Vertices that are not reachable within distance `cutoff` will be assigned distance `IGRAPH_INFINITY`.
`from`: | The source vertices.
`to`: | The target vertices. It is not allowed to include a vertex twice or more.
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. If this is a null pointer, then the unweighted version, `igraph_distances()` is called. Edges with positive infinite weights are ignored.
`mode`: | For directed graphs; whether to follow paths along edge directions (`IGRAPH_OUT`), or the opposite (`IGRAPH_IN`), or ignore edge directions completely (`IGRAPH_ALL`). It is ignored for undirected graphs.
`cutoff`: | The maximal length of paths that will be considered. When the distance of two vertices is greater than this value, it will be returned as `IGRAPH_INFINITY`. Negative cutoffs and `IGRAPH_UNLIMITED` are treated as infinity.

Returns:

`` | Error code.

Time complexity: at most O(s |E| log|V| + |V|), where |V| is the number of vertices, |E| the number of edges and s the number of sources. The `cutoff` parameter will limit the number of edges traversed from each source vertex, which reduces the computation time.

See also:

`` | `igraph_distances_cutoff()` for a (slightly) faster unweighted version.

Example 17.4. File `examples/simple/distances.c`

    #include <igraph.h>

    int main(void) {

        igraph_t graph;
        igraph_real_t weights_data[] = { 0, 2, 1, 0, 5, 2, 1, 1, 0, 2, 2, 8, 1, 1, 3, 1, 1, 4, 2, 1 };
        const igraph_vector_t weights =
            igraph_vector_view(weights_data, sizeof(weights_data) / sizeof(weights_data[0]));
        igraph_matrix_t res;
        igraph_real_t cutoff;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&graph, 10, IGRAPH_DIRECTED,
                     0, 1, 0, 2, 0, 3,    1, 2, 1, 4, 1, 5,
                     2, 3, 2, 6,          3, 2, 3, 6,
                     4, 5, 4, 7,          5, 6, 5, 8, 5, 9,
                     7, 5, 7, 8,          8, 9,
                     5, 2,
                     2, 1,
                     -1);

        igraph_matrix_init(&res, 0, 0);

        printf("Unweighted distances:\n\n");

        igraph_distances(&graph, NULL, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT);
        igraph_matrix_print(&res);

        cutoff = 3; /* distances longer than this will be returned as infinity */
        printf("\nUnweighted distances with a cutoff of %g:\n\n", cutoff);
        igraph_distances_cutoff(&graph, NULL, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT, cutoff);
        igraph_matrix_print(&res);

        printf("\nWeighted distances:\n\n");

        igraph_distances(&graph, &weights, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT);
        igraph_matrix_print(&res);

        cutoff = 8; /* distances longer than this will be returned as infinity */
        printf("\nWeighted distances with a cutoff of %g:\n\n", cutoff);
        igraph_distances_cutoff(&graph, &weights, &res, igraph_vss_all(), igraph_vss_all(), IGRAPH_OUT, cutoff);
        igraph_matrix_print(&res);

        igraph_matrix_destroy(&res);
        igraph_destroy(&graph);

        return 0;
    }

### 3.5. `igraph_distances_bellman_ford` — Weighted shortest path lengths between vertices, allowing negative weights.

    igraph_error_t igraph_distances_bellman_ford(
            const igraph_t *graph,
            igraph_matrix_t *res,
            const igraph_vs_t from,
            const igraph_vs_t to,
            const igraph_vector_t *weights,
            igraph_neimode_t mode);

This function implements the Bellman-Ford algorithm to find the weighted shortest paths to all vertices from a single source, allowing negative weights. It is run independently for the given sources. If there are no negative weights, you are better off with `igraph_distances_dijkstra()` .

Arguments:

`graph`: | The input graph, can be directed.
`res`: | The result, a matrix. A pointer to an initialized matrix should be passed here, the matrix will be resized if needed. Each row contains the distances from a single source, to all vertices in the graph, in the order of vertex IDs. For unreachable vertices the matrix contains `IGRAPH_INFINITY`.
`from`: | The source vertices.
`to`: | The target vertices.

`weights`:

The edge weights. There must not be any cycle in the graph that has a negative total weight (since this would allow us to decrease the weight of any path containing at least a single vertex of this cycle infinitely). Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. If this is a null pointer, then the unweighted version, `igraph_distances()` is called.

`mode`: | For directed graphs; whether to follow paths along edge directions (`IGRAPH_OUT`), or the opposite (`IGRAPH_IN`), or ignore edge directions completely (`IGRAPH_ALL`). It is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(s*|E|*|V|), where |V| is the number of vertices, |E| the number of edges and s the number of sources.

See also:

`` | `igraph_distances()` for a non-algorithm-specific interface; `igraph_distances_dijkstra()` if you do not have negative edge weights.

Example 17.5. File `examples/simple/bellman_ford.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_vector_t weights;
        igraph_real_t weights_data_0[] = { 0, 2, 1, 0, 5, 2, 1, 1, 0, 2, 2, 8, 1, 1, 3, 1, 1, 4, 2, 1 };
        igraph_real_t weights_data_1[] = { 6, 7, 8, -4, -2, -3, 9, 2, 7 };
        igraph_real_t weights_data_2[] = { 6, 7, 2, -4, -2, -3, 9, 2, 7 };
        igraph_matrix_t res;

        /* Initialize the library. */
        igraph_setup();

        /* Graph with only positive weights */
        igraph_small(&g, 10, IGRAPH_DIRECTED,
                     0, 1, 0, 2, 0, 3,    1, 2, 1, 4, 1, 5,
                     2, 3, 2, 6,         3, 2, 3, 6,
                     4, 5, 4, 7,         5, 6, 5, 8, 5, 9,
                     7, 5, 7, 8,         8, 9,
                     5, 2,
                     2, 1,
                     -1);

        weights = igraph_vector_view(weights_data_0,
                           sizeof(weights_data_0) / sizeof(weights_data_0[0]));

        igraph_matrix_init(&res, 0, 0);
        igraph_distances_bellman_ford(&g, &res, igraph_vss_all(), igraph_vss_all(),
                                      &weights, IGRAPH_OUT);
        igraph_matrix_print(&res);

        igraph_matrix_destroy(&res);
        igraph_destroy(&g);

        printf("\n");

        /***************************************/

        /* Graph with negative weights */
        igraph_small(&g, 5, IGRAPH_DIRECTED,
                     0, 1, 0, 3, 1, 3, 1, 4, 2, 1, 3, 2, 3, 4, 4, 0, 4, 2, -1);

        weights = igraph_vector_view(weights_data_1,
                           sizeof(weights_data_1) / sizeof(weights_data_1[0]));

        igraph_matrix_init(&res, 0, 0);
        igraph_distances_bellman_ford(&g, &res, igraph_vss_all(),
                                      igraph_vss_all(), &weights, IGRAPH_OUT);
        igraph_matrix_print(&res);

        /***************************************/

        /* Same graph with negative cycle */
        igraph_set_error_handler(igraph_error_handler_ignore);
        weights = igraph_vector_view(weights_data_2,
                           sizeof(weights_data_2) / sizeof(weights_data_2[0]));
        if (igraph_distances_bellman_ford(&g, &res, igraph_vss_all(),
                                          igraph_vss_all(),
                                          &weights, IGRAPH_OUT) != IGRAPH_ENEGCYCLE) {
            return 1;
        }

        igraph_matrix_destroy(&res);
        igraph_destroy(&g);

        if (!IGRAPH_FINALLY_STACK_EMPTY) {
            return 1;
        }

        return 0;
    }

### 3.6. `igraph_distances_johnson` — Weighted shortest path lengths between vertices, using Johnson's algorithm.

    igraph_error_t igraph_distances_johnson(
            const igraph_t *graph,
            igraph_matrix_t *res,
            igraph_vs_t from, igraph_vs_t to,
            const igraph_vector_t *weights,
            igraph_neimode_t mode);

This algorithm supports directed graphs with negative edge weights, and performs better than the Bellman-Ford method when distances are calculated from many different sources, the typical use case being all-pairs distance calculations. It works by using a single-source Bellman-Ford run to transform all edge weights to non-negative ones, then invoking Dijkstra's algorithm with the new weights. See the Wikipedia page for more details: http://en.wikipedia.org/wiki/Johnson's_algorithm.

If no edge weights are supplied, then the unweighted version, `igraph_distances()` is called. If none of the supplied edge weights are negative, then Dijkstra's algorithm is used by calling `igraph_distances_dijkstra()`.

Note that Johnson's algorithm applies only to directed graphs. This function rejects undirected graphs with any negative edge weights, even when the `from` and `to` vertices are all in connected components that are free of negative weights.

References:

Donald B. Johnson: Efficient Algorithms for Shortest Paths in Sparse Networks. J. ACM 24, 1 (1977), 1–13. https://doi.org/10.1145/321992.321993

Arguments:

`graph`: | The input graph. If negative weights are present, it should be directed.
`res`: | Pointer to an initialized matrix, the result will be stored here, one line for each source vertex, one column for each target vertex.
`from`: | The source vertices.
`to`: | The target vertices. It is not allowed to include a vertex twice or more.
`weights`: | Optional edge weights. If it is a null-pointer, then the unweighted breadth-first search based `igraph_distances()` will be called. Edges with positive infinite weights are ignored.
`mode`: | For directed graphs; whether to follow paths along edge directions (`IGRAPH_OUT`), or the opposite (`IGRAPH_IN`), or ignore edge directions completely (`IGRAPH_ALL`). It is ignored for undirected graphs. `IGRAPH_ALL` should not be used with negative weights.

Returns:

`` | Error code.

Time complexity: O(s|V|log|V|+|V||E|), |V| and |E| are the number of vertices and edges, s is the number of source vertices.

See also:

`` | `igraph_distances()` for a faster unweighted version, `igraph_distances_dijkstra()` if you do not have negative edge weights, `igraph_distances_bellman_ford()` if you only need to calculate shortest paths from a couple of sources.

### 3.7. `igraph_distances_floyd_warshall` — Weighted all-pairs shortest path lengths with the Floyd-Warshall algorithm.

    igraph_error_t igraph_distances_floyd_warshall(
            const igraph_t *graph, igraph_matrix_t *res,
            igraph_vs_t from, igraph_vs_t to,
            const igraph_vector_t *weights, igraph_neimode_t mode,
            const igraph_floyd_warshall_algorithm_t method);

The Floyd-Warshall algorithm computes weighted shortest path lengths between all pairs of vertices at the same time. It is useful with very dense weighted graphs, as its running time is primarily determined by the vertex count, and is not sensitive to the graph density. In sparse graphs, other methods such as the Dijkstra or Bellman-Ford algorithms will perform significantly better.

In addition to the original Floyd-Warshall algorithm, igraph contains implementations of variants that offer better asymptotic complexity as well as better practical running times for most instances. See the reference below for more information.

Note that internally this function always computes the distance matrix for all pairs of vertices. The `from` and `to` parameters only serve to subset this matrix, but do not affect the time or memory taken by the calculation.

Reference:

Brodnik, A., Grgurovič, M., Požar, R.: Modifications of the Floyd-Warshall algorithm with nearly quadratic expected-time, Ars Mathematica Contemporanea, vol. 22, issue 1, p. #P1.01 (2021). https://doi.org/10.26493/1855-3974.2467.497

Arguments:

`graph`: | The graph object.
`res`: | An intialized matrix, the distances will be stored here.
`from`: | The source vertices.
`to`: | The target vertices.
`weights`: | The edge weights. If `NULL`, all weights are assumed to be 1. Negative weights are allowed, but the graph must not contain negative cycles. Edges with positive infinite weights are ignored.

`mode`:

The type of shortest paths to be use for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing paths are calculated.
`IGRAPH_IN` | the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`method`:

The type of the algorithm used.

`IGRAPH_FLOYD_WARSHALL_AUTOMATIC` | tries to select the best performing variant for the current graph; presently this option always uses the "Tree" method.
`IGRAPH_FLOYD_WARSHALL_ORIGINAL` | the basic Floyd-Warshall algorithm.
`IGRAPH_FLOYD_WARSHALL_TREE` | the "Tree" speedup of Brodnik et al., faster than the original algorithm in most cases.

Returns:

`` | Error code. `IGRAPH_ENEGCYCLE` is returned if a negative-weight cycle is found.

See also:

`` | `igraph_distances()`, `igraph_distances_dijkstra()`, `igraph_distances_bellman_ford()`, `igraph_distances_johnson()`

Time complexity: The original variant has complexity O(|V|^3 + |E|). The "Tree" variant has expected-case complexity of O(|V|^2 log^2 |V|) according to Brodnik et al., while its worst-time complexity remains O(|V|^3). Here |V| denotes the number of vertices and |E| is the number of edges.

### 3.8. `igraph_get_shortest_paths` — Shortest paths from a vertex.

    igraph_error_t igraph_get_shortest_paths(
            const igraph_t *graph,
            const igraph_vector_t *weights,
            igraph_vector_int_list_t *vertices,
            igraph_vector_int_list_t *edges,
            igraph_int_t from, const igraph_vs_t to,
            igraph_neimode_t mode,
            igraph_vector_int_t *parents,
            igraph_vector_int_t *inbound_edges);

Finds unweighted shortest paths from a single source vertex to the specified sets of target vertices. If there is more than one geodesic between two vertices, this function gives only one of them. Use `igraph_get_all_shortest_paths()` to find all shortest paths.

Arguments:

`graph`: | The graph object.
`weights`: | Optional edge weights. If `NULL`, the graph is considered unweighted, i.e. all edge weights are equal to 1.
`vertices`: | The result, the IDs of the vertices along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. The list will be resized as needed. Supply a null pointer here if you don't need these vectors.
`edges`: | The result, the IDs of the edges along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. The list will be resized as needed. Supply a null pointer here if you don't need these vectors.
`from`: | The ID of the vertex from/to which the geodesics are calculated.
`to`: | Vertex sequence with the IDs of the vertices to/from which the shortest paths will be calculated. A vertex might be given multiple times.

`mode`:

The type of shortest paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing paths are calculated.
`IGRAPH_IN` | the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`parents`:

A pointer to an initialized igraph vector or `NULL`. If not `NULL`, a vector containing the parent of each vertex in the single source shortest path tree is returned here. The parent of vertex `i` in the tree is the vertex from which vertex `i` was reached. The parent of the start vertex (in the `from` argument) is -1. If the parent is -2, it means that the given vertex was not reached from the source during the search. Note that the search terminates if all the vertices in `to` are reached.

`inbound_edges`:

A pointer to an initialized igraph vector or `NULL`. If not `NULL`, a vector containing the inbound edge of each vertex in the single source shortest path tree is returned here. The inbound edge of vertex `i` in the tree is the edge via which vertex `i` was reached. The start vertex and vertices that were not reached during the search will have -1 in the corresponding entry of the vector. Note that the search terminates if all the vertices in `to` are reached.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | `from` is invalid vertex ID
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(|V|+|E|), |V| is the number of vertices, |E| the number of edges in the graph.

See also:

`` | `igraph_distances()` if you only need the path lengths but not the paths themselves; `igraph_get_shortest_paths_dijkstra()` for the weighted version; `igraph_get_all_shortest_paths()` to return all shortest paths between (source, target) pairs.

Example 17.6. File `examples/simple/igraph_get_shortest_paths.c`

    #include <igraph.h>

    #include <stdlib.h>

    int check_evecs(const igraph_t *graph, const igraph_vector_int_list_t *vecs,
                    const igraph_vector_int_list_t *evecs, int error_code) {

        igraph_bool_t directed = igraph_is_directed(graph);
        igraph_int_t i, n = igraph_vector_int_list_size(vecs);
        if (igraph_vector_int_list_size(evecs) != n) {
            exit(error_code + 1);
        }

        for (i = 0; i < n; i++) {
            igraph_vector_int_t *vvec = igraph_vector_int_list_get_ptr(vecs, i);
            igraph_vector_int_t *evec = igraph_vector_int_list_get_ptr(evecs, i);
            igraph_int_t j, n2 = igraph_vector_int_size(evec);
            if (igraph_vector_int_size(vvec) == 0 && n2 == 0) {
                continue;
            }
            if (igraph_vector_int_size(vvec) != n2 + 1) {
                exit(error_code + 2);
            }
            for (j = 0; j < n2; j++) {
                igraph_int_t edge = VECTOR(*evec)[j];
                igraph_int_t from = VECTOR(*vvec)[j];
                igraph_int_t to = VECTOR(*vvec)[j + 1];
                if (directed) {
                    if (from != IGRAPH_FROM(graph, edge) ||
                        to   != IGRAPH_TO  (graph, edge)) {
                        exit(error_code);
                    }
                } else {
                    igraph_int_t from2 = IGRAPH_FROM(graph, edge);
                    igraph_int_t to2 = IGRAPH_TO(graph, edge);
                    igraph_int_t min1 = from < to ? from : to;
                    igraph_int_t max1 = from < to ? to : from;
                    igraph_int_t min2 = from2 < to2 ? from2 : to2;
                    igraph_int_t max2 = from2 < to2 ? to2 : from2;
                    if (min1 != min2 || max1 != max2) {
                        exit(error_code + 3);
                    }
                }
            }
        }

        return 0;
    }

    int main(void) {

        igraph_t g;
        igraph_vector_int_list_t vecs, evecs;
        igraph_vector_int_t parents, inbound;
        igraph_int_t i;
        igraph_vs_t vs;

        /* Initialize the library. */
        igraph_setup();

        igraph_ring(&g, 10, IGRAPH_DIRECTED, 0, 1);

        igraph_vector_int_list_init(&vecs, 0);
        igraph_vector_int_list_init(&evecs, 0);
        igraph_vector_int_init(&parents, 0);
        igraph_vector_int_init(&inbound, 0);

        igraph_vs_vector_small(&vs, 1, 3, 5, 2, 1,  -1);

        igraph_get_shortest_paths(&g, NULL, &vecs, &evecs, 0, vs, IGRAPH_OUT, &parents, &inbound);

        check_evecs(&g, &vecs, &evecs, 10);

        for (i = 0; i < igraph_vector_int_list_size(&vecs); i++) {
            igraph_vector_int_print(igraph_vector_int_list_get_ptr(&vecs, i));
        }

        igraph_vector_int_print(&parents);
        igraph_vector_int_print(&inbound);

        igraph_vector_int_list_destroy(&vecs);
        igraph_vector_int_list_destroy(&evecs);
        igraph_vector_int_destroy(&parents);
        igraph_vector_int_destroy(&inbound);

        igraph_vs_destroy(&vs);
        igraph_destroy(&g);

        if (!IGRAPH_FINALLY_STACK_EMPTY) {
            return 1;
        }

        return 0;
    }

### 3.9. `igraph_get_shortest_path` — Shortest path from one vertex to another one.

    igraph_error_t igraph_get_shortest_path(
            const igraph_t *graph,
            const igraph_vector_t *weights,
            igraph_vector_int_t *vertices,
            igraph_vector_int_t *edges,
            igraph_int_t from, igraph_int_t to,
            igraph_neimode_t mode);

Calculates and returns a single unweighted shortest path from a given vertex to another one. If there is more than one shortest path between the two vertices, then an arbitrary one is returned.

This function is a wrapper to `igraph_get_shortest_paths()` for the special case when only one target vertex is considered.

Arguments:

`graph`: | The input graph, it can be directed or undirected. Directed paths are considered in directed graphs.
`weights`: | Optional edge weights. If `NULL`, the graph is considered unweighted, i.e. all edge weights are equal to 1.
`vertices`: | Pointer to an initialized vector or a null pointer. If not a null pointer, then the vertex IDs along the path are stored here, including the source and target vertices.
`edges`: | Pointer to an initialized vector or a null pointer. If not a null pointer, then the edge IDs along the path are stored here.
`from`: | The ID of the source vertex.
`to`: | The ID of the target vertex.
`mode`: | A constant specifying how edge directions are considered in directed graphs. Valid modes are: `IGRAPH_OUT`, follows edge directions; `IGRAPH_IN`, follows the opposite directions; and `IGRAPH_ALL`, ignores edge directions. This argument is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), linear in the number of vertices and edges in the graph.

See also:

`` | `igraph_get_shortest_paths()` for the version with more target vertices.

### 3.10. `igraph_get_shortest_paths_dijkstra` — Weighted shortest paths from a vertex.

    igraph_error_t igraph_get_shortest_paths_dijkstra(
            const igraph_t *graph,
            igraph_vector_int_list_t *vertices,
            igraph_vector_int_list_t *edges,
            igraph_int_t from,
            igraph_vs_t to,
            const igraph_vector_t *weights,
            igraph_neimode_t mode,
            igraph_vector_int_t *parents,
            igraph_vector_int_t *inbound_edges);

Finds weighted shortest paths from a single source vertex to the specified sets of target vertices using Dijkstra's algorithm. If there is more than one path with the smallest weight between two vertices, this function gives only one of them. To find all such paths, use `igraph_get_all_shortest_paths_dijkstra()`.

Arguments:

`graph`: | The graph object.
`vertices`: | The result, the IDs of the vertices along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. The list will be resized as needed. Supply a null pointer here if you don't need these vectors.
`edges`: | The result, the IDs of the edges along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. The list will be resized as needed. Supply a null pointer here if you don't need these vectors.
`from`: | The id of the vertex from/to which the geodesics are calculated.
`to`: | Vertex sequence with the IDs of the vertices to/from which the shortest paths will be calculated. A vertex might be given multiple times. *
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. If this is a null pointer, then the unweighted version, `igraph_get_shortest_paths()` is called.

`mode`:

The type of shortest paths to be use for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing paths are calculated.
`IGRAPH_IN` | the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`parents`:

A pointer to an initialized igraph vector or null. If not null, a vector containing the parent of each vertex in the single source shortest path tree is returned here. The parent of vertex i in the tree is the vertex from which vertex i was reached. The parent of the start vertex (in the `from` argument) is -1. If the parent is -2, it means that the given vertex was not reached from the source during the search. Note that the search terminates if all the vertices in `to` are reached.

`inbound_edges`:

A pointer to an initialized igraph vector or null. If not null, a vector containing the inbound edge of each vertex in the single source shortest path tree is returned here. The inbound edge of vertex i in the tree is the edge via which vertex i was reached. The start vertex and vertices that were not reached during the search will have -1 in the corresponding entry of the vector. Note that the search terminates if all the vertices in `to` are reached.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | `from` is invalid vertex ID
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(|E|log|V|+|V|), where |V| is the number of vertices and |E| is the number of edges

See also:

`` | `igraph_distances_dijkstra()` if you only need the path lengths but not the paths themselves; `igraph_get_all_shortest_paths_dijkstra()` to find all shortest paths between (source, target) pairs; `igraph_get_shortest_paths()` for a non-algorithm-specific interface.

Example 17.7. File `examples/simple/igraph_get_shortest_paths_dijkstra.c`

    #include <igraph.h>
    #include <stdlib.h>

    int main(void) {

        igraph_t g;
        igraph_vector_int_list_t vecs, evecs;
        igraph_vector_int_t parents, inbound;
        igraph_int_t i;
        igraph_real_t weights[] = { 0, 2, 1, 0, 5, 2, 1, 1, 0, 2, 2, 8, 1, 1, 3, 1, 1, 4, 2, 1 };
        igraph_vector_t weights_vec = igraph_vector_view(weights, sizeof(weights) / sizeof(weights[0]));
        igraph_vs_t vs;

        /* Initialize the library. */
        igraph_setup();

        igraph_vector_int_list_init(&vecs, 0);
        igraph_vector_int_list_init(&evecs, 0);
        igraph_vector_int_init(&parents, 0);
        igraph_vector_int_init(&inbound, 0);

        igraph_vs_vector_small(&vs, 0, 1, 3, 5, 2, 1, -1);
        igraph_small(&g, 10, IGRAPH_DIRECTED,
                     0, 1, 0, 2, 0, 3,   1, 2, 1, 4, 1, 5,
                     2, 3, 2, 6,         3, 2, 3, 6,
                     4, 5, 4, 7,         5, 6, 5, 8, 5, 9,
                     7, 5, 7, 8,         8, 9,
                     5, 2,
                     2, 1,
                     -1);

        igraph_get_shortest_paths_dijkstra(&g, /*vertices=*/ &vecs,
                                           /*edges=*/ &evecs, /*from=*/ 0, /*to=*/ vs,
                                           &weights_vec, IGRAPH_OUT,
                                           &parents,
                                           /*inbound_edges=*/ &inbound);
        printf("Vertices:\n");
        for (i = 0; i < igraph_vector_int_list_size(&vecs); i++) {
            igraph_vector_int_print(igraph_vector_int_list_get_ptr(&vecs, i));
        }

        printf("\nEdges:\n");
        for (i = 0; i < igraph_vector_int_list_size(&evecs); i++) {
            igraph_vector_int_print(igraph_vector_int_list_get_ptr(&evecs, i));
        }

        printf("\nParents:\n");
        igraph_vector_int_print(&parents);

        printf("\nInbound:\n");
        igraph_vector_int_print(&inbound);

        igraph_vector_int_list_destroy(&vecs);
        igraph_vector_int_list_destroy(&evecs);
        igraph_vector_int_destroy(&parents);
        igraph_vector_int_destroy(&inbound);

        igraph_vs_destroy(&vs);
        igraph_destroy(&g);

        return 0;
    }

### 3.11. `igraph_get_shortest_path_dijkstra` — Weighted shortest path from one vertex to another one (Dijkstra).

    igraph_error_t igraph_get_shortest_path_dijkstra(const igraph_t *graph,
                                          igraph_vector_int_t *vertices,
                                          igraph_vector_int_t *edges,
                                          igraph_int_t from,
                                          igraph_int_t to,
                                          const igraph_vector_t *weights,
                                          igraph_neimode_t mode);

Finds a weighted shortest path from a single source vertex to a single target, using Dijkstra's algorithm. If more than one shortest path exists, an arbitrary one is returned.

This function is a special case (and a wrapper) to `igraph_get_shortest_paths_dijkstra()`.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`vertices`: | Pointer to an initialized vector or a null pointer. If not a null pointer, then the vertex IDs along the path are stored here, including the source and target vertices.
`edges`: | Pointer to an initialized vector or a null pointer. If not a null pointer, then the edge IDs along the path are stored here.
`from`: | The ID of the source vertex.
`to`: | The ID of the target vertex.
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. If this is a null pointer, then the unweighted version, `igraph_get_shortest_paths()` is called.
`mode`: | A constant specifying how edge directions are considered in directed graphs. `IGRAPH_OUT` follows edge directions, `IGRAPH_IN` follows the opposite directions, and `IGRAPH_ALL` ignores edge directions. This argument is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|E|log|V|+|V|), |V| is the number of vertices, |E| is the number of edges in the graph.

See also:

`` | `igraph_get_shortest_paths_dijkstra()` for the version with more target vertices.

### 3.12. `igraph_get_shortest_paths_bellman_ford` — Weighted shortest paths from a vertex, allowing negative weights.

    igraph_error_t igraph_get_shortest_paths_bellman_ford(
            const igraph_t *graph,
            igraph_vector_int_list_t *vertices,
            igraph_vector_int_list_t *edges,
            igraph_int_t from,
            igraph_vs_t to,
            const igraph_vector_t *weights,
            igraph_neimode_t mode,
            igraph_vector_int_t *parents,
            igraph_vector_int_t *inbound_edges);

This function calculates weighted shortest paths from or to a single vertex using the Bellman-Ford algorithm, whihc can handle negative weights. When there is more than one shortest path between two vertices, only one of them is returned. When there are no negative weights, `igraph_get_shortest_paths_dijkstra()` is likely to be faster.

Arguments:

`graph`: | The input graph, can be directed.
`vertices`: | The result, the IDs of the vertices along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. The list will be resized as needed. Supply a null pointer here if you don't need these vectors.
`edges`: | The result, the IDs of the edges along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. The list will be resized as needed. Supply a null pointer here if you don't need these vectors.
`from`: | The id of the vertex from/to which the geodesics are calculated.
`to`: | Vertex sequence with the IDs of the vertices to/from which the shortest paths will be calculated. A vertex might be given multiple times.
`weights`: | The edge weights. There must not be any cycle in the graph that has a negative total weight (since this would allow us to decrease the weight of any path containing at least a single vertex of this cycle infinitely). If this is a null pointer, then the unweighted version, `igraph_get_shortest_paths()` is called. Edges with positive infinite weights are ignored.
`mode`: | For directed graphs; whether to follow paths along edge directions (`IGRAPH_OUT`), or the opposite (`IGRAPH_IN`), or ignore edge directions completely (`IGRAPH_ALL`). It is ignored for undirected graphs.

`parents`:

A pointer to an initialized igraph vector or null. If not null, a vector containing the parent of each vertex in the single source shortest path tree is returned here. The parent of vertex i in the tree is the vertex from which vertex i was reached. The parent of the start vertex (in the `from` argument) is -1. If the parent is -2, it means that the given vertex was not reached from the source during the search. Note that the search terminates if all the vertices in `to` are reached.

`inbound_edges`:

A pointer to an initialized igraph vector or null. If not null, a vector containing the inbound edge of each vertex in the single source shortest path tree is returned here. The inbound edge of vertex i in the tree is the edge via which vertex i was reached. The start vertex and vertices that were not reached during the search will have -1 in the corresponding entry of the vector. Note that the search terminates if all the vertices in `to` are reached.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | Not enough memory for temporary data.
`IGRAPH_EINVAL` | The weight vector doesn't math the number of edges.
`IGRAPH_EINVVID` | `from` is invalid vertex ID
`IGRAPH_ENEGCYCLE` | Bellman-ford algorithm encounted a negative cycle.

Time complexity: O(|E|*|V|), where |V| is the number of vertices, |E| the number of edges.

See also:

`` | `igraph_distances_bellman_ford()` to compute only shortest path lengths, but not the paths themselves; `igraph_get_shortest_paths()` for a non-algorithm-specific interface.

### 3.13. `igraph_get_shortest_path_bellman_ford` — Weighted shortest path from one vertex to another one (Bellman-Ford).

    igraph_error_t igraph_get_shortest_path_bellman_ford(const igraph_t *graph,
                                              igraph_vector_int_t *vertices,
                                              igraph_vector_int_t *edges,
                                              igraph_int_t from,
                                              igraph_int_t to,
                                              const igraph_vector_t *weights,
                                              igraph_neimode_t mode);

Finds a weighted shortest path from a single source vertex to a single target using the Bellman-Ford algorithm.

This function is a special case (and a wrapper) to `igraph_get_shortest_paths_bellman_ford()`.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`vertices`: | Pointer to an initialized vector or a null pointer. If not a null pointer, then the vertex IDs along the path are stored here, including the source and target vertices.
`edges`: | Pointer to an initialized vector or a null pointer. If not a null pointer, then the edge IDs along the path are stored here.
`from`: | The ID of the source vertex.
`to`: | The ID of the target vertex.
`weights`: | The edge weights. There must not be any cycle in the graph that has a negative total weight (since this would allow us to decrease the weight of any path containing at least a single vertex of this cycle infinitely). If this is a null pointer, then the unweighted version is called.
`mode`: | A constant specifying how edge directions are considered in directed graphs. `IGRAPH_OUT` follows edge directions, `IGRAPH_IN` follows the opposite directions, and `IGRAPH_ALL` ignores edge directions. This argument is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|E|log|E|+|V|), |V| is the number of vertices, |E| is the number of edges in the graph.

See also:

`` | `igraph_get_shortest_paths_bellman_ford()` for the version with more target vertices.

### 3.14. `igraph_get_shortest_path_astar` — A* gives the shortest path from one vertex to another, with heuristic.

    igraph_error_t igraph_get_shortest_path_astar(const igraph_t *graph,
                                          igraph_vector_int_t *vertices,
                                          igraph_vector_int_t *edges,
                                          igraph_int_t from,
                                          igraph_int_t to,
                                          const igraph_vector_t *weights,
                                          igraph_neimode_t mode,
                                          igraph_astar_heuristic_func_t *heuristic,
                                          void *extra);

Calculates a shortest path from a single source vertex to a single target, using the A* algorithm. A* tries to find a shortest path by starting at `from` and moving to vertices that lie on a path with the lowest estimated length. This length estimate is the sum of two numbers: the distance from the source (`from`) to the intermediate vertex, and the value returned by the heuristic function. The heuristic function provides an estimate the distance between intermediate candidate vertices and the target vertex `to`. The A* algorithm is guaranteed to give the correct shortest path (if one exists) only if the heuristic does not overestimate distances, i.e. if the heuristic function is admissible.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`vertices`: | Pointer to an initialized vector or the `NULL` pointer. If not `NULL`, then the vertex IDs along the path are stored here, including the source and target vertices.
`edges`: | Pointer to an initialized vector or the `NULL` pointer. If not `NULL`, then the edge IDs along the path are stored here.
`from`: | The ID of the source vertex.
`to`: | The ID of the target vertex.
`weights`: | Optional edge weights. Supply `NULL` for unweighted graphs. All edge weights must be non-negative. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. Edges with positive infinite weights are ignored.
`mode`: | A constant specifying how edge directions are considered in directed graphs. `IGRAPH_OUT` follows edge directions, `IGRAPH_IN` follows the opposite directions, and `IGRAPH_ALL` ignores edge directions. This argument is ignored for undirected graphs.
`heuristic`: | A function that provides distance estimates to the target vertex. See `igraph_astar_heuristic_func_t` for more information.
`extra`: | This is passed on to the heuristic function.

Returns:

`` | Error code.

Time complexity: In the worst case, O(|E|log|V|+|V|), where |V| is the number of vertices and |E| is the number of edges in the graph. The running time depends on the accuracy of the distance estimates returned by the heuristic function. Assuming that the heuristic is admissible, the better the estimates, the shortert the running time.

### 3.15. `igraph_astar_heuristic_func_t` — Distance estimator for A* algorithm.

    typedef igraph_error_t igraph_astar_heuristic_func_t(
                igraph_real_t *result,
                igraph_int_t from, igraph_int_t to,
                void *extra);

`igraph_get_shortest_path_astar()` uses a heuristic based on a distance estimate to the target vertex to guide its search, and determine which vertex to try next. The heuristic function is expected to compute an estimate of the distance between `from` and `to`. In order for `igraph_get_shortest_path_astar()` to find an exact shortest path, the distance must not be overestimated, i.e. the heuristic function must be admissible.

Arguments:

`result`: | The result of the heuristic, i.e. the estimated distance. A lower value will mean this vertex will be a better candidate for exploration.
`from`: | The vertex ID of the candidate vertex will be passed here.
`to`: | The vertex ID of the endpoint of the path, i.e. the `to` parameter given to `igraph_get_shortest_path_astar()`, will be passed here.
`extra`: | The `extra` argument that was passed to `igraph_get_shortest_path_astar()`.

Returns:

`` | Error code. Must return `IGRAPH_SUCCESS` if there were no errors. This can be used to break off the algorithm if something unexpected happens, like a failed memory allocation (`IGRAPH_ENOMEM`).

See also:

`` | `igraph_get_shortest_path_astar()`

### 3.16. `igraph_get_all_shortest_paths` — All shortest paths (geodesics) from a vertex.

    igraph_error_t igraph_get_all_shortest_paths(
            const igraph_t *graph,
            const igraph_vector_t *weights,
            igraph_vector_int_list_t *vertices,
            igraph_vector_int_list_t *edges,
            igraph_vector_int_t *nrgeo,
            igraph_int_t from, const igraph_vs_t to,
            igraph_neimode_t mode);

When there is more than one shortest path between two vertices, all of them will be returned. Every edge is considered separately, therefore in graphs with multi-edges, this function may produce a very large number of results.

Arguments:

`graph`: | The graph object.

`vertices`:

The result, the IDs of the vertices along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. Each vector object contains the vertices along a shortest path from `from` to another vertex. The vectors are ordered according to their target vertex: first the shortest paths to vertex 0, then to vertex 1, etc. No data is included for unreachable vertices. The list will be resized as needed. Supply a null pointer here if you don't need these vectors.

`edges`:

The result, the IDs of the edges along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. Each vector object contains the edges along a shortest path from `from` to another vertex. The vectors are ordered according to their target vertex: first the shortest paths to vertex 0, then to vertex 1, etc. No data is included for unreachable vertices. The list will be resized as needed. Supply a null pointer here if you don't need these vectors.

`nrgeo`: | Pointer to an initialized `igraph_vector_int_t` object or `NULL`. If not `NULL` the number of shortest paths from `from` are stored here for every vertex in the graph. Note that the values will be accurate only for those vertices that are in the target vertex sequence (see `to`), since the search terminates as soon as all the target vertices have been found.
`from`: | The id of the vertex from/to which the geodesics are calculated.
`to`: | Vertex sequence with the IDs of the vertices to/from which the shortest paths will be calculated. A vertex might be given multiple times.

`mode`:

The type of shortest paths to be use for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the lengths of the outgoing paths are calculated.
`IGRAPH_IN` | the lengths of the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | `from` is invalid vertex ID.
`IGRAPH_EINVMODE` | invalid mode argument.

Added in version 0.2.

Time complexity: O(|V|+|E|) for most graphs, O(|V|^2) in the worst case.

### 3.17. `igraph_get_all_shortest_paths_dijkstra` — All weighted shortest paths (geodesics) from a vertex.

    igraph_error_t igraph_get_all_shortest_paths_dijkstra(const igraph_t *graph,
            igraph_vector_int_list_t *vertices,
            igraph_vector_int_list_t *edges,
            igraph_vector_int_t *nrgeo,
            igraph_int_t from, igraph_vs_t to,
            const igraph_vector_t *weights,
            igraph_neimode_t mode);

Arguments:

`graph`: | The graph object.
`vertices`: | Pointer to an initialized integer vector list or NULL. If not NULL, then each vector object contains the vertices along a shortest path from `from` to another vertex. The vectors are ordered according to their target vertex: first the shortest paths to vertex 0, then to vertex 1, etc. No data is included for unreachable vertices.
`edges`: | Pointer to an initialized integer vector list or NULL. If not NULL, then each vector object contains the edges along a shortest path from `from` to another vertex. The vectors are ordered according to their target vertex: first the shortest paths to vertex 0, then to vertex 1, etc. No data is included for unreachable vertices.
`nrgeo`: | Pointer to an initialized igraph_vector_int_t object or NULL. If not NULL the number of shortest paths from `from` are stored here for every vertex in the graph. Note that the values will be accurate only for those vertices that are in the target vertex sequence (see `to`), since the search terminates as soon as all the target vertices have been found.
`from`: | The id of the vertex from/to which the geodesics are calculated.
`to`: | Vertex sequence with the IDs of the vertices to/from which the shortest paths will be calculated. A vertex might be given multiple times.
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. If this is a null pointer, then the unweighted version, `igraph_get_all_shortest_paths()` is called.

`mode`:

The type of shortest paths to be use for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing paths are calculated.
`IGRAPH_IN` | the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | `from` is an invalid vertex ID
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(|E|log|V|+|V|), where |V| is the number of vertices and |E| is the number of edges

See also:

`` | `igraph_distances_dijkstra()` if you only need the path lengths but not the paths themselves, `igraph_get_all_shortest_paths()` if all edge weights are equal.

Example 17.8. File `examples/simple/igraph_get_all_shortest_paths_dijkstra.c`

    #include <igraph.h>
    #include <stdlib.h>

    void print_and_destroy_items(igraph_vector_int_list_t* vec) {
        igraph_int_t i;

        /* Sort the paths in a deterministic manner to avoid problems with
         * different qsort() implementations on different platforms */
        igraph_vector_int_list_sort(vec, igraph_vector_int_colex_cmp);
        for (i = 0; i < igraph_vector_int_list_size(vec); i++) {
            igraph_vector_int_print(igraph_vector_int_list_get_ptr(vec, i));
        }

        igraph_vector_int_list_destroy(vec);
    }

    int main(void) {

        igraph_t g;
        igraph_vector_int_list_t vertices, edges;

        igraph_real_t weights[] = { 0, 2, 1, 0, 5, 2, 1, 1, 0, 2, 2, 8, 1, 1, 3, 1, 1, 4, 2, 1 };
        const igraph_vector_t weights_vec = igraph_vector_view(weights, sizeof(weights) / sizeof(weights[0]));
        igraph_vector_int_t nrgeo;
        igraph_vs_t vs;

        /* Initialize the library. */
        igraph_setup();

        igraph_vector_int_list_init(&vertices, 0);
        igraph_vector_int_list_init(&edges, 0);
        igraph_vs_vector_small(&vs, 1, 3, 4, 5, 2, 1, -1);
        igraph_vector_int_init(&nrgeo, 0);
        igraph_small(&g, 10, IGRAPH_DIRECTED,
                     0, 1, 0, 2, 0, 3,   1, 2, 1, 4, 1, 5,
                     2, 3, 2, 6,         3, 2, 3, 6,
                     4, 5, 4, 7,         5, 6, 5, 8, 5, 9,
                     7, 5, 7, 8,         8, 9,
                     5, 2,
                     2, 1,
                     -1);

        igraph_get_all_shortest_paths_dijkstra(
                    &g,
                    /*vertices=*/ &vertices, /*edges=*/ &edges, /*nrgeo=*/ &nrgeo,
                    /*from=*/ 0, /*to=*/ vs,
                    /*weights=*/ &weights_vec, /*mode=*/ IGRAPH_OUT);

        printf("Vertices:\n");
        print_and_destroy_items(&vertices);
        printf("\nEdges:\n");
        print_and_destroy_items(&edges);
        printf("\nNumber of geodesics:\n");
        igraph_vector_int_print(&nrgeo);

        igraph_vector_int_destroy(&nrgeo);
        igraph_vs_destroy(&vs);
        igraph_destroy(&g);

        return 0;
    }

### 3.18. `igraph_get_k_shortest_paths` — k shortest paths between two vertices.

    igraph_error_t igraph_get_k_shortest_paths(
        const igraph_t *graph, const igraph_vector_t *weights,
        igraph_vector_int_list_t *vertex_paths,
        igraph_vector_int_list_t *edge_paths,
        igraph_int_t k, igraph_int_t from, igraph_int_t to,
        igraph_neimode_t mode
    );

This function returns the `k` shortest paths between two vertices, in order of increasing lengths.

Reference:

Yen, Jin Y.: An algorithm for finding shortest routes from all source nodes to a given destination in general networks. Quarterly of Applied Mathematics. 27 (4): 526–530. (1970) https://doi.org/10.1090/qam/253822

Arguments:

`graph`: | The graph object.
`weights`: | The edge weights of the graph. Can be `NULL` for an unweighted graph. Infinite weights will be treated as missing edges.
`vertex_paths`: | Pointer to an initialized list of integer vectors, the result will be stored here in `igraph_vector_int_t` objects. Each vector object contains the vertex IDs along the `k`th shortest path between `from` and `to`, where `k` is the vector list index. May be `NULL` if the vertex paths are not needed.
`edge_paths`: | Pointer to an initialized list of integer vectors, the result will be stored here in `igraph_vector_int_t` objects. Each vector object contains the edge IDs along the `k`th shortest path between `from` and `to`, where `k` is the vector list index. May be `NULL` if the edge paths are not needed.
`k`: | The number of paths.
`from`: | The ID of the vertex from which the paths are calculated.
`to`: | The ID of the vertex to which the paths are calculated.

`mode`:

The type of paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | The outgoing paths of `from` are calculated.
`IGRAPH_IN` | The incoming paths of `from` are calculated.
`IGRAPH_ALL` | The directed graph is considered as an undirected one for the computation.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | Not enough memory for temporary data.
`IGRAPH_EINVVID` | `from` or `to` is an invalid vertex id.
`IGRAPH_EINVMODE` | Invalid mode argument.
`IGRAPH_EINVAL` | Invalid argument.

Time complexity: k |V| (|V| log|V| + |E|), where |V| is the number of vertices, and |E| is the number of edges.

See also:

`` | `igraph_get_all_simple_paths()`, `igraph_get_shortest_paths()`, `igraph_get_shortest_paths_dijkstra()`

### 3.19. `igraph_get_all_simple_paths` — List all simple paths from one source.

    igraph_error_t igraph_get_all_simple_paths(
            const igraph_t *graph,
            igraph_vector_int_list_t *res,
            igraph_int_t from, const igraph_vs_t to,
            igraph_neimode_t mode,
            igraph_int_t minlen, igraph_int_t maxlen,
            igraph_int_t max_results);

A path is simple if its vertices are unique, i.e. no vertex is visited more than once. This function returns paths in terms of their vertices and ignores multi-edges.

Note that potentially there are exponentially many paths between two vertices of a graph, and you may run out of memory when using this function when the graph has many cycles. Consider using the `minlen` and `maxlen` parameters to restrict the paths that are returned.

Arguments:

`graph`: | The input graph.
`res`: | Initialized integer vector list. The paths are returned here in terms of their vertices. The paths are included in arbitrary order, as they are found.
`from`: | The start vertex.
`to`: | The target vertices.

`mode`:

The type of paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | outgoing paths are calculated.
`IGRAPH_IN` | incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`minlen`: | Minimum length of paths that is considered. If negative or `IGRAPH_UNLIMITED`, no lower bound is used on the path lengths.
`maxlen`: | Maximum length of paths that is considered. If negative or `IGRAPH_UNLIMITED`, no upper bound is used on the path lengths.
`max_results`: | At most this many paths will be recorded. If negative, or `IGRAPH_UNLIMITED`, no limit is applied.

Returns:

`` | Error code.

See also:

`` | `igraph_get_k_shortest_paths()`

Time complexity: O(n!) in the worst case, n is the number of vertices.

### 3.20. `igraph_average_path_length` — The average shortest path length between all vertex pairs.

    igraph_error_t igraph_average_path_length(
        const igraph_t *graph, const igraph_vector_t *weights, igraph_real_t *res,
        igraph_real_t *unconn_pairs, igraph_bool_t directed, igraph_bool_t unconn
    );

If no vertex pairs can be included in the calculation, for example because the graph has fewer than two vertices, or if the graph has no edges and `unconn` is set to `true`, NaN is returned.

All distinct ordered vertex pairs are taken into account.

Arguments:

`graph`: | The graph object.
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. Passa a null pointer here if the graph is unweighted. Edges with positive infinite weight are ignored.
`res`: | Pointer to a real number, this will contain the result.
`unconn_pairs`: | Pointer to a real number. If not a null pointer, the number of ordered vertex pairs where the second vertex is unreachable from the first one will be stored here.
`directed`: | Boolean, whether to consider directed paths. Ignored for undirected graphs.
`unconn`: | If `true`, only those pairs are considered for the calculation between which there is a path. If `false`, `IGRAPH_INFINITY` is returned for disconnected graphs.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for data structures
`IGRAPH_EINVAL` | invalid weight vector

Time complexity: O(|V| |E| log|E| + |V|), where |V| is the number of vertices and |E| is the number of edges.

Example 17.9. File `examples/simple/igraph_grg_game.c`

    #include <igraph.h>
    #include <math.h>

    int main(void) {
        igraph_t graph;
        igraph_vector_t x, y;
        igraph_vector_t weights;
        igraph_eit_t eit;
        igraph_real_t avg_dist;

        /* Initialize the library. */
        igraph_setup();

        /* Set random seed for reproducible results */

        igraph_rng_seed(igraph_rng_default(), 42);

        /* Create a random geometric graph and retrieve vertex coordinates */

        igraph_vector_init(&x, 0);
        igraph_vector_init(&y, 0);

        igraph_grg_game(&graph, 200, 0.1, /* torus */ false, &x, &y);

        /* Compute edge weights as geometric distance */

        igraph_vector_init(&weights, igraph_ecount(&graph));
        igraph_eit_create(&graph, igraph_ess_all(IGRAPH_EDGEORDER_ID), &eit);
        for (; ! IGRAPH_EIT_END(eit); IGRAPH_EIT_NEXT(eit)) {
            igraph_int_t e = IGRAPH_EIT_GET(eit);
            igraph_int_t u = IGRAPH_FROM(&graph, e);
            igraph_int_t v = IGRAPH_TO(&graph, e);

            VECTOR(weights)[e] = hypot(VECTOR(x)[u] - VECTOR(x)[v], VECTOR(y)[u] - VECTOR(y)[v]);
        }
        igraph_eit_destroy(&eit);

        /* Compute average path length */

        igraph_average_path_length(&graph, &weights, &avg_dist, NULL, IGRAPH_UNDIRECTED, /* unconn */ true);

        printf("Average distance in the geometric graph: %g.\n", avg_dist);

        /* Destroy data structures when no longer needed */

        igraph_vector_destroy(&weights);
        igraph_destroy(&graph);
        igraph_vector_destroy(&x);
        igraph_vector_destroy(&y);

        return 0;
    }

### 3.21. `igraph_path_length_hist` — Create a histogram of all shortest path lengths.

    igraph_error_t igraph_path_length_hist(const igraph_t *graph, igraph_vector_t *res,
                                igraph_real_t *unconnected, igraph_bool_t directed);

This function calculates a histogram by calculating the shortest path length between all pairs of vertices. In directed graphs, both directions are considered, meaning that each vertex pair appears twice in the histogram.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an initialized vector, the result is stored here. The first (i.e. index 0) element contains the number of shortest paths of length 1, the second of length 2, etc. The supplied vector is resized as needed.
`unconnected`: | Pointer to a real number, the number of vertex pairs for which the second vertex is not reachable from the first is stored here.
`directed`: | Whether to consider directed paths in a directed graph. This argument is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|V||E|), the number of vertices times the number of edges.

See also:

`` | `igraph_average_path_length()` and `igraph_distances()`

### 3.22. `igraph_diameter` — Calculates the weighted diameter of a graph using Dijkstra's algorithm.

    igraph_error_t igraph_diameter(
        const igraph_t *graph, const igraph_vector_t *weights, igraph_real_t *res,
        igraph_int_t *from, igraph_int_t *to, igraph_vector_int_t *vertex_path,
        igraph_vector_int_t *edge_path, igraph_bool_t directed, igraph_bool_t unconn
    );

This function computes the weighted diameter of a graph, defined as the longest weighted shortest path, or the maximum weighted eccentricity of the graph's vertices. A corresponding shortest path, as well as its endpoints, can also be optionally computed.

If the graph has no vertices, `IGRAPH_NAN` is returned.

Arguments:

`graph`: | The input graph, can be directed or undirected.
`weights`: | The edge weights of the graph. Can be `NULL` for an unweighted graph. Edges with positive infinite weight are ignored.
`res`: | Pointer to a real number, if not `NULL` then it will contain the diameter (the actual distance).
`from`: | Pointer to an integer, if not `NULL` it will be set to the source vertex of the diameter path. If the graph has no diameter path, it will be set to -1.
`to`: | Pointer to an integer, if not `NULL` it will be set to the target vertex of the diameter path. If the graph has no diameter path, it will be set to -1.
`vertex_path`: | Pointer to an initialized vector. If not `NULL` the actual longest geodesic path in terms of vertices will be stored here. The vector will be resized as needed.
`edge_path`: | Pointer to an initialized vector. If not `NULL` the actual longest geodesic path in terms of edges will be stored here. The vector will be resized as needed.
`directed`: | Boolean, whether to consider directed paths. Ignored for undirected graphs.
`unconn`: | What to do if the graph is not connected. If `true` the longest geodesic within a component will be returned, otherwise `IGRAPH_INFINITY` is returned.

Returns:

`` | Error code.

Time complexity: O(|V||E|*log|E|), |V| is the number of vertices, |E| is the number of edges.

See also:

`` | `igraph_radius()` for the minimum eccentricity.

Example 17.10. File `examples/simple/igraph_diameter.c`

    #include <igraph.h>

    int main(void) {

        igraph_t graph;
        igraph_real_t result;
        igraph_int_t from, to;
        igraph_vector_int_t path, path_edge;

        /* Initialize the library. */
        igraph_setup();

        igraph_barabasi_game(&graph, 30, /*power=*/ 1, 30, 0, 0, /*A=*/ 1,
                             IGRAPH_DIRECTED, IGRAPH_BARABASI_BAG,
                             /*start_from=*/ NULL);
        igraph_diameter(&graph, NULL, &result, NULL, NULL, NULL, NULL, IGRAPH_UNDIRECTED, 1);

        /* printf("diameter: %g\n", result); */

        igraph_destroy(&graph);

        igraph_ring(&graph, 10, IGRAPH_DIRECTED, 0, 0);
        igraph_vector_int_init(&path, 0);
        igraph_vector_int_init(&path_edge, 0);
        igraph_diameter(&graph, NULL, &result, &from, &to, &path, &path_edge, IGRAPH_DIRECTED, 1);
        printf(
            "diameter: %g, from %" IGRAPH_PRId " to %" IGRAPH_PRId "\n",
            result, from, to
        );
        igraph_vector_int_print(&path);
        igraph_vector_int_print(&path_edge);

        igraph_vector_int_destroy(&path);
        igraph_vector_int_destroy(&path_edge);
        igraph_destroy(&graph);

        return 0;
    }

### 3.23. `igraph_girth` — The girth of a graph is the length of the shortest cycle in it.

    igraph_error_t igraph_girth(const igraph_t *graph,
                                igraph_real_t *girth,
                                igraph_vector_int_t *cycle);

The current implementation works for undirected graphs only, directed graphs are treated as undirected graphs. Self-loops and multiple edges are ignored, i.e. cycles of length 1 or 2 are not considered.

For graphs that contain no cycles, and only for such graphs, infinity is returned.

The first implementation of this function was done by Keith Briggs, thanks Keith.

Reference:

Alon Itai and Michael Rodeh: Finding a minimum circuit in a graph Proceedings of the ninth annual ACM symposium on Theory of computing , 1-10, 1977. https://doi.org/10.1145/800105.803390

Arguments:

`graph`: | The input graph. Edge directions will be ignored.
`girth`: | Pointer to an `igraph_real_t`, if not `NULL` then the result will be stored here.
`cycle`: | Pointer to an initialized vector, the vertex IDs in the shortest cycle of length at least 3 will be stored here. If `NULL` then it is ignored.

Returns:

`` | Error code.

Time complexity: O((|V|+|E|)^2), |V| is the number of vertices, |E| is the number of edges in the general case. If the graph has no cycles at all then the function needs O(|V|+|E|) time to realize this and then it stops.

Example 17.11. File `examples/simple/igraph_girth.c`

    #include <igraph.h>

    int main(void) {
        igraph_t g;
        igraph_real_t girth;
        igraph_vector_int_t circle;
        igraph_int_t chord[] = { 0, 50 };
        const igraph_vector_int_t v = igraph_vector_int_view(chord, sizeof(chord) / sizeof(chord[0]));

        /* Initialize the library. */
        igraph_setup();

        igraph_ring(&g, 100, IGRAPH_UNDIRECTED, 0, 1);

        igraph_add_edges(&g, &v, 0);
        igraph_girth(&g, &girth, 0);
        if (girth != 51) {
            return 1;
        }

        igraph_destroy(&g);

        /* Special case: null graph */
        igraph_ring(&g, 0, IGRAPH_UNDIRECTED, 0, 1);
        igraph_vector_int_init(&circle, 1);
        VECTOR(circle)[0] = 2;
        igraph_girth(&g, &girth, &circle);
        if (girth != IGRAPH_INFINITY) {
            return 2;
        }
        if (igraph_vector_int_size(&circle) != 0) {
            return 3;
        }
        igraph_vector_int_destroy(&circle);
        igraph_destroy(&g);

        return 0;
    }

### 3.24. `igraph_eccentricity` — Eccentricity of some vertices.

    igraph_error_t igraph_eccentricity(
        const igraph_t *graph, const igraph_vector_t *weights, igraph_vector_t *res,
        igraph_vs_t vids, igraph_neimode_t mode
    );

The eccentricity of a vertex is calculated by measuring the shortest distance from (or to) the vertex, to (or from) all vertices in the graph, and taking the maximum.

This implementation ignores vertex pairs that are in different components. Isolated vertices have eccentricity zero.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. Use a null pointer to calculate the unweighted eccentricities. Edges with positive infinite weights are ignored.
`res`: | Pointer to an initialized vector, the result is stored here.
`vids`: | The vertices for which the eccentricity is calculated.
`mode`: | What kind of paths to consider for the calculation: `IGRAPH_OUT`, paths that follow edge directions; `IGRAPH_IN`, paths that follow the opposite directions; and `IGRAPH_ALL`, paths that ignore edge directions. This argument is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|V| |E| log|V| + |V|), where |V| is the number of vertices, |E| the number of edges.

Example 17.12. File `examples/simple/igraph_eccentricity.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_vector_t ecc;

        /* Initialize the library. */
        igraph_setup();

        igraph_vector_init(&ecc, 0);

        igraph_star(&g, 10, IGRAPH_STAR_UNDIRECTED, 0);
        igraph_eccentricity(&g, NULL, &ecc, igraph_vss_all(), IGRAPH_OUT);
        igraph_vector_print(&ecc);
        igraph_destroy(&g);

        igraph_star(&g, 10, IGRAPH_STAR_OUT, 0);
        igraph_eccentricity(&g, NULL, &ecc, igraph_vss_all(), IGRAPH_ALL);
        igraph_vector_print(&ecc);
        igraph_destroy(&g);

        igraph_star(&g, 10, IGRAPH_STAR_OUT, 0);
        igraph_eccentricity(&g, NULL, &ecc, igraph_vss_all(), IGRAPH_OUT);
        igraph_vector_print(&ecc);
        igraph_destroy(&g);

        igraph_vector_destroy(&ecc);

        return 0;
    }

### 3.25. `igraph_radius` — Radius of a graph, using weighted edges.

    igraph_error_t igraph_radius(
        const igraph_t *graph, const igraph_vector_t *weights,
        igraph_real_t *radius, igraph_neimode_t mode
    );

The radius of a graph is the defined as the minimum eccentricity of its vertices, see `igraph_eccentricity()`.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. If this is a null pointer, then the unweighted version, `igraph_radius()` is called. Edges with positive infinite weights are ignored.
`radius`: | Pointer to a real variable, the result is stored here.
`mode`: | What kind of paths to consider for the calculation: `IGRAPH_OUT`, paths that follow edge directions; `IGRAPH_IN`, paths that follow the opposite directions; and `IGRAPH_ALL`, paths that ignore edge directions. This argument is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|V| |E| log|V| + |V|), where |V| is the number of vertices, |E| the number of edges.

See also:

`` | `igraph_diameter()` for the maximum eccentricity, `igraph_eccentricity()` for eccentricities of all vertices.

### 3.26. `igraph_graph_center` — Central vertices of a graph.

    igraph_error_t igraph_graph_center(
        const igraph_t *graph, const igraph_vector_t *weights, igraph_vector_int_t *res,
        igraph_neimode_t mode
    );

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

The central vertices of a graph are calculated by finding the vertices with the minimum eccentricity. The concept of the graph center is typically applied to (strongly) connected graphs. In disconnected graphs, the smallest eccentricity is taken across all components.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. Pass a null pointer here if all edges have equal weight. Edges with positive infinite weights are ignored.
`res`: | Pointer to an initialized vector, the result is stored here.
`mode`: | What kind of paths to consider for the calculation: `IGRAPH_OUT`, paths that follow edge directions; `IGRAPH_IN`, paths that follow the opposite directions; and `IGRAPH_ALL`, paths that ignore edge directions. This argument is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|V| |E| log|V| + |V|), where |V| is the number of vertices, |E| the number of edges.

See also:

`` | `igraph_graph_center()`, `igraph_eccentricity()`, `igraph_radius()`

### 3.27. `igraph_pseudo_diameter` — Approximation and lower bound of the diameter of a graph.

    igraph_error_t igraph_pseudo_diameter(
        const igraph_t *graph, const igraph_vector_t *weights,
        igraph_real_t *diameter, igraph_int_t vid_start,
        igraph_int_t *from, igraph_int_t *to,
        igraph_bool_t directed, igraph_bool_t unconn
    );

This algorithm finds a pseudo-peripheral vertex and returns its eccentricity. This value can be used as an approximation and lower bound of the diameter of a graph.

A pseudo-peripheral vertex is a vertex v, such that for every vertex u which is as far away from v as possible, v is also as far away from u as possible. The process of finding one depends on where the search starts, and for a disconnected graph the maximum diameter found will be that of the component `vid_start` is in.

If the graph has no vertices, `IGRAPH_NAN` is returned.

Arguments:

`graph`: | The input graph, can be directed or undirected.
`weights`: | The edge weights of the graph. Can be `NULL` for an unweighted graph. All weights should be non-negative. Edges with positive infinite weights are ignored.
`diameter`: | This will contain the pseudo-diameter.
`vid_start`: | Id of the starting vertex. If this is negative, a random starting vertex is chosen.
`from`: | If not `NULL` this will be set to the source vertex of the diameter path. If the graph has no diameter path, it will be set to -1.
`to`: | If not `NULL` this will be set to the target vertex of the diameter path. If the graph has no diameter path, it will be set to -1.
`directed`: | Boolean, whether to consider directed paths. Ignored for undirected graphs.
`unconn`: | What to do if the graph is not connected. If `true` the longest geodesic within a component will be returned, otherwise `IGRAPH_INFINITY` is returned.

Returns:

`` | Error code.

Time complexity: O(|V| |E| log|E|), |V| is the number of vertices, |E| is the number of edges.

See also:

`` | `igraph_diameter()`

### 3.28. `igraph_voronoi` — Voronoi partitioning of a graph.

    igraph_error_t igraph_voronoi(
            const igraph_t *graph,
            igraph_vector_int_t *membership,
            igraph_vector_t *distances,
            const igraph_vector_int_t *generators,
            const igraph_vector_t *weights,
            igraph_neimode_t mode,
            igraph_voronoi_tiebreaker_t tiebreaker);

To obtain a Voronoi partitioning of a graph, we start with a set of generator vertices, which will define the partitions. Each vertex is assigned to the generator vertex from (or to) which it is closest.

This function uses a BFS search for unweighted graphs and Dijkstra's algorithm for weights ones.

Arguments:

`graph`: | The graph to partition.
`membership`: | If not `NULL`, the Voronoi partition of each vertex will be stored here. `membership[v]` will be set to the index in `generators` of the generator vertex that `v` belongs to. For vertices that are not reachable from any generator, `-1` is returned.
`distances`: | If not `NULL`, the distance of each vertex to its respective generator will be stored here. For vertices which are not reachable from any generator, `IGRAPH_INFINITY` is returned.
`generators`: | Vertex IDs of the generator vertices.
`weights`: | The edge weights, interpreted as lengths in the shortest path calculation. All weights must be non-negative.
`mode`: | In directed graphs, whether to compute distances from generator vertices to other vertices (`IGRAPH_OUT`), to generator vertices from other vertices (`IGRAPH_IN`), or ignore edge directions entirely (`IGRAPH_ALL`).

`tiebreaker`:

Controls which generator vertex to assign a vertex to when it is at equal distance from/to multiple generator vertices.

`IGRAPH_VORONOI_FIRST assign the vertex to the first generator vertex.` |
`IGRAPH_VORONOI_LAST assign the vertex to the last generator vertex.` |
`IGRAPH_VORONOI_RANDOM assign the vertex to a random generator vertex.` |

Note that `IGRAPH_VORONOI_RANDOM` does not guarantee that all partitions will be contiguous. For example, if 1 and 2 are chosen as generators for the graph `1-3, 2-3, 3-4`, then 3 and 4 are at equal distance from both generators. If 3 is assigned to 2 but 4 is assigned to 1, then the partition {1, 4} will not induce a connected subgraph.

Returns:

`` | Error code.

Time complexity: In weighted graphs, O((log |S|) |E| (log |V|) + |V|), and in unweighted graphs O((log |S|) |E| + |V|), where |S| is the number of generator vertices, and |V| and |E| are the number of vertices and edges in the graph.

See also:

`` | `igraph_distances()`, `igraph_distances_dijkstra()`.

### 3.29. `igraph_vertex_path_from_edge_path` — Converts a walk of edge IDs to the traversed vertex IDs.

    igraph_error_t igraph_vertex_path_from_edge_path(
       const igraph_t *graph, igraph_int_t start,
       const igraph_vector_int_t *edge_path, igraph_vector_int_t *vertex_path,
       igraph_neimode_t mode
    );

This function is useful when you have a sequence of edge IDs representing a continuous walk in a graph and you would like to obtain the vertex IDs that the walk traverses. The function is used implicitly by several shortest path related functions to convert a path of edge IDs to the corresponding representation that describes the path in terms of vertex IDs instead.

The result will always contain one more vertex than the number of provided edges. If no edges are given, the output will contain only the start vertex.

The walk is allowed to traverse the same vertex more than once. It is suitable for use on paths, cycles, or arbitrary walks.

Arguments:

`graph`: | The graph that the edge IDs refer to.
`start`: | The start vertex of the path. If negative, it is determined automatically. This is only possible if the walk contains at least one edge. If only one edge is present in an undirected walk, one of its endpoints will be selected arbitrarily.
`edge_path`: | The sequence of edge IDs that describe the path.
`vertex_path`: | The sequence of vertex IDs traversed will be returned here.
`mode`: | A constant specifying how edge directions are considered in directed graphs. `IGRAPH_OUT` follows edge directions, `IGRAPH_IN` follows the opposite directions, and `IGRAPH_ALL` ignores edge directions. This argument is ignored for undirected graphs.

Returns:

`` | Error code: `IGRAPH_ENOMEM` if there is not enough memory, `IGRAPH_EINVVID` if the start vertex is invalid, `IGRAPH_EINVAL` if the edge walk does not start at the given vertex or if there is at least one edge whose start vertex does not match the end vertex of the previous edge.

Time complexity: O(n) where n is the length of the walk.

## 4. Widest-path related functions

### 4.1. `igraph_get_widest_path` — Widest path from one vertex to another one.

    igraph_error_t igraph_get_widest_path(const igraph_t *graph,
                                          igraph_vector_int_t *vertices,
                                          igraph_vector_int_t *edges,
                                          igraph_int_t from,
                                          igraph_int_t to,
                                          const igraph_vector_t *weights,
                                          igraph_neimode_t mode);

Calculates a single widest path from a single vertex to another one, using Dijkstra's algorithm.

This function is a special case (and a wrapper) to `igraph_get_widest_paths()`.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`vertices`: | Pointer to an initialized vector or `NULL`. If not `NULL`, then the vertex IDs along the path are stored here, including the source and target vertices.
`edges`: | Pointer to an initialized vector or `NULL`. If not `NULL`, then the edge IDs along the path are stored here.
`from`: | The ID of the source vertex.
`to`: | The ID of the target vertex.
`weights`: | The edge weights, interpreted as widths. Edge weights can be negative, but must not be NaN. Edges with negative infinite weight are ignored. The weight vector is required: if `NULL` is passed, an error is raised.

`mode`:

The type of widest paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing paths are calculated.
`IGRAPH_IN` | the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

Returns:

`` | Error code.

Time complexity: O(|E|log|E|+|V|), |V| is the number of vertices, |E| is the number of edges in the graph.

See also:

`` | `igraph_get_widest_paths()` for the version with more target vertices.

### 4.2. `igraph_get_widest_paths` — Widest paths from a single vertex.

    igraph_error_t igraph_get_widest_paths(const igraph_t *graph,
                                           igraph_vector_int_list_t *vertices,
                                           igraph_vector_int_list_t *edges,
                                           igraph_int_t from,
                                           igraph_vs_t to,
                                           const igraph_vector_t *weights,
                                           igraph_neimode_t mode,
                                           igraph_vector_int_t *parents,
                                           igraph_vector_int_t *inbound_edges);

Calculates the widest paths from a single vertex to all other specified vertices, using a modified Dijkstra's algorithm. The width of a path is defined as the width of the narrowest edge in the path.If there is more than one path with the largest width between two vertices, this function gives only one of them.

Arguments:

`graph`: | The graph object.
`vertices`: | The result, the IDs of the vertices along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. The list will be resized as needed. Supply a null pointer here if you don't need these vectors.
`edges`: | The result, the IDs of the edges along the paths. This is a list of integer vectors where each element is an `igraph_vector_int_t` object. The vector list will be resized as needed. Supply a null pointer here if you don't need these vectors.
`from`: | The ID of the vertex from/to which the widest paths are calculated.
`to`: | Vertex sequence with the IDs of the vertices to/from which the widest paths will be calculated. A vertex may be given multiple times.
`weights`: | The edge weights, interpreted as widths. Edge weights can be negative, but must not be NaN. Edges with negative infinite weight are ignored. The weight vector is required: if `NULL` is passed, an error is raised.

`mode`:

The type of widest paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing paths are calculated.
`IGRAPH_IN` | the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`parents`:

A pointer to an initialized igraph vector or null. If not null, a vector containing the parent of each vertex in the single source widest path tree is returned here. The parent of vertex `i` in the tree is the vertex from which vertex `i` was reached. The parent of the start vertex (in the `from` argument) is -1. If the parent is -2, it means that the given vertex was not reached from the source during the search. The search terminates when all the vertices in `to` have been reached.

`inbound_edges`:

A pointer to an initialized igraph vector or `NULL`. If not `NULL`, a vector containing the inbound edge of each vertex in the single source widest path tree is returned here. The inbound edge of vertex `i` in the tree is the edge via which vertex `i` was reached. The start vertex and vertices that were not reached during the search will have -1 in the corresponding entry of the vector. The search terminates when all the vertices in `to` have been reached.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | `from` is invalid vertex ID
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(|E|log|E|+|V|), where |V| is the number of vertices in the graph and |E| is the number of edges

See also:

`` | `igraph_widest_path_widths_dijkstra()` or `igraph_widest_path_widths_floyd_warshall()` if you only need the widths of the paths but not the paths themselves.

### 4.3. `igraph_widest_path_widths_dijkstra` — Widths of widest paths between vertices.

    igraph_error_t igraph_widest_path_widths_dijkstra(const igraph_t *graph,
                                       igraph_matrix_t *res,
                                       const igraph_vs_t from,
                                       const igraph_vs_t to,
                                       const igraph_vector_t *weights,
                                       igraph_neimode_t mode);

This function implements a modified Dijkstra's algorithm, which can find the widest path widths from a source vertex to all other vertices. The width of a path is defined as the width of the narrowest edge in the path.

This function allows specifying a set of source and target vertices. The algorithm is run independently for each source and the results are retained only for the specified targets. This implementation uses a binary heap for efficiency.

Arguments:

`graph`: | The input graph, can be directed.
`res`: | An initialized matrix, the result will be written here. The matrix will be resized as needed. Each row will contain the widths from a single source to the vertices given in the `to` argument. Unreachable vertices have width `-IGRAPH_INFINITY`, and vertices have a width of `IGRAPH_INFINITY` to themselves.
`from`: | The source vertices.
`to`: | The target vertices. It is not allowed to include a vertex twice or more.
`weights`: | The edge weights, interpreted as widths. Edge weights can be negative, but must not be NaN. Edges with negative infinite weight are ignored. The weight vector is required: if `NULL` is passed, an error is raised.
`mode`: | For directed graphs; whether to follow paths along edge directions (`IGRAPH_OUT`), or the opposite (`IGRAPH_IN`), or ignore edge directions completely (`IGRAPH_ALL`). It is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(s*(|E|log|E|+|V|)), where |V| is the number of vertices in the graph, |E| the number of edges and s the number of sources.

See also:

`` | `igraph_widest_path_widths_floyd_warshall()` for a variant that runs faster on dense graphs.

### 4.4. `igraph_widest_path_widths_floyd_warshall` — Widths of widest paths between vertices.

    igraph_error_t igraph_widest_path_widths_floyd_warshall(const igraph_t *graph,
                                       igraph_matrix_t *res,
                                       const igraph_vs_t from,
                                       const igraph_vs_t to,
                                       const igraph_vector_t *weights,
                                       igraph_neimode_t mode);

This function implements a modified Floyd-Warshall algorithm, to find the widest path widths between a set of source and target vertices. The width of a path is defined as the width of the narrowest edge in the path.

This algorithm is primarily useful for all-pairs path widths in very dense graphs, as its running time is manily determined by the vertex count, and is not sensitive to the graph density. In sparse graphs, other methods such as Dijkstra's algorithm, implemented in `igraph_widest_path_widths_dijkstra()` will perform better.

Note that internally this function always computes the path width matrix for all pairs of vertices. The `from` and `to` parameters only serve to subset this matrix, but do not affect the time taken by the calculation.

Arguments:

`graph`: | The input graph, can be directed.
`res`: | An initialized matrix, the result will be written here. The matrix will be resized as needed. Each row will contain the widths from a single source to the vertices given in the `to` argument. Unreachable vertices have width `-IGRAPH_INFINITY`, and vertices have a width of `IGRAPH_INFINITY` to themselves.
`from`: | The source vertices.
`to`: | The target vertices.
`weights`: | The edge weights, interpreted as widths. Edge weights can be negative, but must not be NaN. Edges with negative infinite weight are ignored. The weight vector is required: if `NULL` is passed, an error is raised.
`mode`: | For directed graphs; whether to follow paths along edge directions (`IGRAPH_OUT`), or the opposite (`IGRAPH_IN`), or ignore edge directions completely (`IGRAPH_ALL`). It is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|V|^3), where |V| is the number of vertices in the graph.

See also:

`` | `igraph_widest_path_widths_dijkstra()` for a variant that runs faster on sparse graphs.

## 5. Efficiency measures

### 5.1. `igraph_global_efficiency` — Calculates the global efficiency of a network.

    igraph_error_t igraph_global_efficiency(
        const igraph_t *graph, const igraph_vector_t *weights,
        igraph_real_t *res, igraph_bool_t directed
    );

The global efficiency of a network is defined as the average of inverse distances between all pairs of vertices: `E_g = 1/(N*(N-1)) sum_{i!=j} 1/d_ij`, where `N` is the number of vertices. The inverse distance between pairs that are not reachable from each other is considered to be zero. For graphs with fewer than 2 vertices, NaN is returned.

Reference:

V. Latora and M. Marchiori, Efficient Behavior of Small-World Networks, Phys. Rev. Lett. 87, 198701 (2001). https://dx.doi.org/10.1103/PhysRevLett.87.198701

Arguments:

`graph`: | The graph object.
`weights`: | The edge weights. All edge weights must be non-negative for Dijkstra's algorithm to work. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. If this is a null pointer, then the unweighted version, `igraph_average_path_length()` is used in calculating the global efficiency. Edges with positive infinite weights are ignored.
`res`: | Pointer to a real number, this will contain the result.
`directed`: | Boolean, whether to consider directed paths. Ignored for undirected graphs.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for data structures
`IGRAPH_EINVAL` | invalid weight vector

Time complexity: O(|V| |E| log|E| + |V|) for weighted graphs and O(|V| |E|) for unweighted ones. |V| denotes the number of vertices and |E| denotes the number of edges.

See also:

`` | `igraph_local_efficiency()`, `igraph_average_local_efficiency()`

### 5.2. `igraph_local_efficiency` — Calculates the local efficiency around each vertex in a network.

    igraph_error_t igraph_local_efficiency(
        const igraph_t *graph, const igraph_vector_t *weights, igraph_vector_t *res,
        const igraph_vs_t vids, igraph_bool_t directed, igraph_neimode_t mode
    );

The local efficiency of a network around a vertex is defined as follows: We remove the vertex and compute the distances (shortest path lengths) between its neighbours through the rest of the network. The local efficiency around the removed vertex is the average of the inverse of these distances.

The inverse distance between two vertices which are not reachable from each other is considered to be zero. The local efficiency around a vertex with fewer than two neighbours is taken to be zero by convention.

Reference:

I. Vragović, E. Louis, and A. Díaz-Guilera, Efficiency of informational transfer in regular and complex networks, Phys. Rev. E 71, 1 (2005). http://dx.doi.org/10.1103/PhysRevE.71.036122

Arguments:

`graph`: | The graph object.
`weights`: | The edge weights. All edge weights must be non-negative. Additionally, no edge weight may be NaN. If either case does not hold, an error is returned. If this is a null pointer, then the unweighted version, `igraph_average_path_length()` is called. Edges with positive infinite weights are ignored.
`res`: | Pointer to an initialized vector, this will contain the result.
`vids`: | The vertices around which the local efficiency will be calculated.
`directed`: | Boolean, whether to consider directed paths. Ignored for undirected graphs.

`mode`:

How to determine the local neighborhood of each vertex in directed graphs. Ignored in undirected graphs.

`IGRAPH_ALL` | take both in- and out-neighbours; this is a reasonable default for high-level interfaces.
`IGRAPH_OUT` | take only out-neighbours
`IGRAPH_IN` | take only in-neighbours

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for data structures
`IGRAPH_EINVAL` | invalid weight vector

Time complexity: O(|E|^2 log|E|) for weighted graphs and O(|E|^2) for unweighted ones. |E| denotes the number of edges.

See also:

`` | `igraph_average_local_efficiency()`, `igraph_global_efficiency()`

### 5.3. `igraph_average_local_efficiency` — Calculates the average local efficiency in a network.

    igraph_error_t igraph_average_local_efficiency(
        const igraph_t *graph, const igraph_vector_t *weights, igraph_real_t *res,
        igraph_bool_t directed, igraph_neimode_t mode
    );

For the null graph, zero is returned by convention.

Arguments:

`graph`: | The graph object.
`weights`: | The edge weights. They must be all non-negative. If a null pointer is given, all weights are assumed to be 1. Edges with positive infinite weight are ignored.
`res`: | Pointer to a real number, this will contain the result.
`directed`: | Boolean, whether to consider directed paths. Ignored for undirected graphs.

`mode`:

How to determine the local neighborhood of each vertex in directed graphs. Ignored in undirected graphs.

`IGRAPH_ALL` | take both in- and out-neighbours; this is a reasonable default for high-level interfaces.
`IGRAPH_OUT` | take only out-neighbours
`IGRAPH_IN` | take only in-neighbours

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for data structures
`IGRAPH_EINVAL` | invalid weight vector

Time complexity: O(|E|^2 log|E|) for weighted graphs and O(|E|^2) for unweighted ones. |E| denotes the number of edges.

See also:

`` | `igraph_local_efficiency()`

## 6. Neighborhood of a vertex

### 6.1. `igraph_neighborhood_size` — Calculates the size of the neighborhood of a given vertex.

    igraph_error_t igraph_neighborhood_size(const igraph_t *graph, igraph_vector_int_t *res,
                                 igraph_vs_t vids, igraph_int_t order,
                                 igraph_neimode_t mode,
                                 igraph_int_t mindist);

The neighborhood of a given order of a vertex includes all vertices which are closer to the vertex than the order. I.e., order 0 is always the vertex itself, order 1 is the vertex plus its immediate neighbors, order 2 is order 1 plus the immediate neighbors of the vertices in order 1, etc.

This function calculates the size of the neighborhood of the given order for the given vertices.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an initialized vector, the result will be stored here. It will be resized as needed.
`vids`: | The vertices for which the calculation is performed.
`order`: | Integer giving the order of the neighborhood. Negative values are treated as infinity.

`mode`:

Specifies how to use the direction of the edges if a directed graph is analyzed. For `IGRAPH_OUT` only the outgoing edges are followed, so all vertices reachable from the source vertex in at most `order` steps are counted. For `IGRAPH_IN` all vertices from which the source vertex is reachable in at most `order` steps are counted. `IGRAPH_ALL` ignores the direction of the edges. This argument is ignored for undirected graphs.

`mindist`: | The minimum distance to include a vertex in the counting. Vertices reachable with a path shorter than this value are excluded. If this is one, then the starting vertex is not counted. If this is two, then its neighbors are not counted either, etc.

Returns:

`` | Error code.

See also:

`` | `igraph_neighborhood()` for calculating the actual neighborhood; `igraph_neighborhood_graphs()` for creating separate graphs from the neighborhoods.

Time complexity: O(n*d*o), where n is the number vertices for which the calculation is performed, d is the average degree, o is the order.

### 6.2. `igraph_neighborhood` — Calculate the neighborhood of vertices.

    igraph_error_t igraph_neighborhood(const igraph_t *graph, igraph_vector_int_list_t *res,
                            igraph_vs_t vids, igraph_int_t order,
                            igraph_neimode_t mode, igraph_int_t mindist);

The neighborhood of a given order of a vertex includes all vertices which are closer to the vertex than the order. I.e., order 0 is always the vertex itself, order 1 is the vertex plus its immediate neighbors, order 2 is order 1 plus the immediate neighbors of the vertices in order 1, etc.

This function calculates the vertices within the neighborhood of the specified vertices.

Arguments:

`graph`: | The input graph.
`res`: | An initialized list of integer vectors. The result of the calculation will be stored here. The list will be resized as needed.
`vids`: | The vertices for which the calculation is performed.
`order`: | Integer giving the order of the neighborhood. Negative values are treated as infinity.

`mode`:

Specifies how to use the direction of the edges if a directed graph is analyzed. For `IGRAPH_OUT` only the outgoing edges are followed, so all vertices reachable from the source vertex in at most `order` steps are included. For `IGRAPH_IN` all vertices from which the source vertex is reachable in at most `order` steps are included. `IGRAPH_ALL` ignores the direction of the edges. This argument is ignored for undirected graphs.

`mindist`: | The minimum distance to include a vertex in the counting. Vertices reachable with a path shorter than this value are excluded. If this is one, then the starting vertex is not counted. If this is two, then its neighbors are not counted either, etc.

Returns:

`` | Error code.

See also:

`` | `igraph_neighborhood_size()` to calculate the size of the neighborhood; `igraph_neighborhood_graphs()` for creating graphs from the neighborhoods; `igraph_subcomponent()` to find vertices reachable from a single vertex.

Time complexity: O(n*d*o), n is the number of vertices for which the calculation is performed, d is the average degree, o is the order.

### 6.3. `igraph_neighborhood_graphs` — Create graphs from the neighborhood(s) of some vertex/vertices.

    igraph_error_t igraph_neighborhood_graphs(const igraph_t *graph, igraph_graph_list_t *res,
                                   igraph_vs_t vids, igraph_int_t order,
                                   igraph_neimode_t mode,
                                   igraph_int_t mindist);

The neighborhood of a given order of a vertex includes all vertices which are closer to the vertex than the order. Ie. order 0 is always the vertex itself, order 1 is the vertex plus its immediate neighbors, order 2 is order 1 plus the immediate neighbors of the vertices in order 1, etc.

This function finds every vertex in the neighborhood of a given parameter vertex and creates the induced subgraph from these vertices.

The first version of this function was written by Vincent Matossian, thanks Vincent.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to a list of graphs, the result will be stored here. Each item in the list is an igraph_t object. The list will be resized as needed.
`vids`: | The vertices for which the calculation is performed.
`order`: | Integer giving the order of the neighborhood. Negative values are treated as infinity.

`mode`:

Specifies how to use the direction of the edges if a directed graph is analyzed. For `IGRAPH_OUT` only the outgoing edges are followed, so all vertices reachable from the source vertex in at most `order` steps are counted. For `IGRAPH_IN` all vertices from which the source vertex is reachable in at most `order` steps are counted. `IGRAPH_ALL` ignores the direction of the edges. This argument is ignored for undirected graphs.

`mindist`: | The minimum distance to include a vertex in the counting. Vertices reachable with a path shorter than this value are excluded. If this is one, then the starting vertex is not counted. If this is two, then its neighbors are not counted either, etc.

Returns:

`` | Error code.

See also:

`` | `igraph_neighborhood_size()` for calculating the neighborhood sizes only; `igraph_neighborhood()` for calculating the neighborhoods (but not creating graphs).

Time complexity: O(n*(|V|+|E|)), where n is the number vertices for which the calculation is performed, |V| and |E| are the number of vertices and edges in the original input graph.

## 7. Local scan statistics

The scan statistic is a summary of the locality statistics that is computed from the local neighborhood of each vertex. For details, see Priebe, C. E., Conroy, J. M., Marchette, D. J., Park, Y. (2005). Scan Statistics on Enron Graphs. Computational and Mathematical Organization Theory.

### 7.1. "Us" statistics

#### 7.1.1. `igraph_local_scan_0` — Local scan-statistics, k=0

    igraph_error_t igraph_local_scan_0(const igraph_t *graph, igraph_vector_t *res,
                            const igraph_vector_t *weights,
                            igraph_neimode_t mode);

K=0 scan-statistics is arbitrarily defined as the vertex degree for unweighted, and the vertex strength for weighted graphs. See `igraph_degree()` and `igraph_strength()`.

Arguments:

`graph`: | The input graph
`res`: | An initialized vector, the results are stored here.
`weights`: | Weight vector for weighted graphs, null pointer for unweighted graphs.
`mode`: | Type of the neighborhood, `IGRAPH_OUT` means outgoing, `IGRAPH_IN` means incoming and `IGRAPH_ALL` means all edges.

Returns:

`` | Error code.

#### 7.1.2. `igraph_local_scan_1_ecount` — Local scan-statistics, k=1, edge count and sum of weights

    igraph_error_t igraph_local_scan_1_ecount(const igraph_t *graph, igraph_vector_t *res,
                                   const igraph_vector_t *weights,
                                   igraph_neimode_t mode);

Count the number of edges or the sum the edge weights in the 1-neighborhood of vertices.

Arguments:

`graph`: | The input graph
`res`: | An initialized vector, the results are stored here.
`weights`: | Weight vector for weighted graphs, null pointer for unweighted graphs.
`mode`: | Type of the neighborhood, `IGRAPH_OUT` means outgoing, `IGRAPH_IN` means incoming and `IGRAPH_ALL` means all edges.

Returns:

`` | Error code.

#### 7.1.3. `igraph_local_scan_k_ecount` — Sum the number of edges or the weights in k-neighborhood of every vertex.

    igraph_error_t igraph_local_scan_k_ecount(const igraph_t *graph, igraph_int_t k,
                                   igraph_vector_t *res,
                                   const igraph_vector_t *weights,
                                   igraph_neimode_t mode);

Arguments:

`graph`: | The input graph.
`k`: | The size of the neighborhood, non-negative integer. The k=0 case is special, see `igraph_local_scan_0()`.
`res`: | An initialized vector, the results are stored here.
`weights`: | Weight vector for weighted graphs, null pointer for unweighted graphs.
`mode`: | Type of the neighborhood, `IGRAPH_OUT` means outgoing, `IGRAPH_IN` means incoming and `IGRAPH_ALL` means all edges.

Returns:

`` | Error code.

### 7.2. "Them" statistics

#### 7.2.1. `igraph_local_scan_0_them` — Local THEM scan-statistics, k=0

    igraph_error_t igraph_local_scan_0_them(const igraph_t *us, const igraph_t *them,
                                 igraph_vector_t *res,
                                 const igraph_vector_t *weights_them,
                                 igraph_neimode_t mode);

K=0 scan-statistics is arbitrarily defined as the vertex degree for unweighted, and the vertex strength for weighted graphs. See `igraph_degree()` and `igraph_strength()`.

Arguments:

`us`: | The input graph, to use to extract the neighborhoods.
`them`: | The input graph to use for the actually counting.
`res`: | An initialized vector, the results are stored here.
`weights_them`: | Weight vector for weighted graphs, null pointer for unweighted graphs.
`mode`: | Type of the neighborhood, `IGRAPH_OUT` means outgoing, `IGRAPH_IN` means incoming and `IGRAPH_ALL` means all edges.

Returns:

`` | Error code.

#### 7.2.2. `igraph_local_scan_1_ecount_them` — Local THEM scan-statistics, k=1, edge count and sum of weights

    igraph_error_t igraph_local_scan_1_ecount_them(const igraph_t *us, const igraph_t *them,
                                        igraph_vector_t *res,
                                        const igraph_vector_t *weights_them,
                                        igraph_neimode_t mode);

Count the number of edges or the sum the edge weights in the 1-neighborhood of vertices.

Arguments:

`us`: | The input graph to extract the neighborhoods.
`them`: | The input graph to perform the counting.
`weights_them`: | Weight vector for weighted graphs, null pointer for unweighted graphs.
`mode`: | Type of the neighborhood, `IGRAPH_OUT` means outgoing, `IGRAPH_IN` means incoming and `IGRAPH_ALL` means all edges.

Returns:

`` | Error code.

See also:

`` | `igraph_local_scan_1_ecount()` for the US statistics.

#### 7.2.3. `igraph_local_scan_k_ecount_them` — Local THEM scan-statistics, edge count or sum of weights.

    igraph_error_t igraph_local_scan_k_ecount_them(const igraph_t *us, const igraph_t *them,
                                        igraph_int_t k, igraph_vector_t *res,
                                        const igraph_vector_t *weights_them,
                                        igraph_neimode_t mode);

Count the number of edges or the sum the edge weights in the k-neighborhood of vertices.

Arguments:

`us`: | The input graph to extract the neighborhoods.
`them`: | The input graph to perform the counting.
`k`: | The size of the neighborhood, non-negative integer. The k=0 case is special, see `igraph_local_scan_0_them()`.
`res`: | An initialized vector, the results are stored here.
`weights_them`: | Weight vector for weighted graphs, null pointer for unweighted graphs.
`mode`: | Type of the neighborhood, `IGRAPH_OUT` means outgoing, `IGRAPH_IN` means incoming and `IGRAPH_ALL` means all edges.

Returns:

`` | Error code.

See also:

`` | `igraph_local_scan_1_ecount()` for the US statistics.

### 7.3. Pre-calculated subsets

#### 7.3.1. `igraph_local_scan_neighborhood_ecount` — Local scan-statistics with pre-calculated neighborhoods

    igraph_error_t igraph_local_scan_neighborhood_ecount(const igraph_t *graph,
            igraph_vector_t *res,
            const igraph_vector_t *weights,
            const igraph_vector_int_list_t *neighborhoods);

Count the number of edges, or sum the edge weights in neighborhoods given as a parameter.

### Warning

Deprecated since version 0.10.0. Please do not use this function in new code; use `igraph_local_scan_subset_ecount()` instead.

Arguments:

`graph`: | The graph to perform the counting/summing in.
`res`: | Initialized vector, the result is stored here.
`weights`: | Weight vector for weighted graphs, null pointer for unweighted graphs.
`neighborhoods`: | List of igraph_vector_int_t objects, the neighborhoods, one for each vertex in the graph.

Returns:

`` | Error code.

#### 7.3.2. `igraph_local_scan_subset_ecount` — Local scan-statistics of subgraphs induced by subsets of vertices.

    igraph_error_t igraph_local_scan_subset_ecount(const igraph_t *graph,
            igraph_vector_t *res,
            const igraph_vector_t *weights,
            const igraph_vector_int_list_t *subsets);

Count the number of edges, or sum the edge weights in induced subgraphs from vertices given as a parameter.

Arguments:

`graph`: | The graph to perform the counting/summing in.
`res`: | Initialized vector, the result is stored here.
`weights`: | Weight vector for weighted graphs, null pointer for unweighted graphs.
`subsets`: | List of igraph_vector_int_t objects, the vertex subsets.

Returns:

`` | Error code.

## 8. Graph components

### 8.1. `igraph_subcomponent` — The vertices reachable from a given vertex.

    igraph_error_t igraph_subcomponent(
        const igraph_t *graph, igraph_vector_int_t *res, igraph_int_t vertex,
        igraph_neimode_t mode
    );

This function returns the set of vertices reachable from a specified vertex. In undirected graphs, this is simple the set of vertices within the same component.

Arguments:

`graph`: | The graph object.
`res`: | The result, vector with the IDs of the vertices reachable from `vertex`.
`vertex`: | The id of the vertex of which the component is searched.

`mode`:

Type of the component for directed graphs, possible values:

`IGRAPH_OUT` | the set of vertices reachable from the `vertex`,
`IGRAPH_IN` | the set of vertices from which the `vertex` is reachable.
`IGRAPH_ALL` | the graph is considered as an undirected graph. Note that this is not the same as the union of the previous two.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | `vertex` is an invalid vertex ID
`IGRAPH_EINVMODE` | invalid mode argument passed.

Time complexity: O(|V|+|E|), |V| and |E| are the number of vertices and edges in the graph.

See also:

`` | `igraph_induced_subgraph()` if you want a graph object consisting only a given set of vertices and the edges between them; `igraph_reachability()` to efficiently compute the reachable set from all vertices; `igraph_neighborhood()` to find vertices within a given distance.

### 8.2. `igraph_connected_components` — Calculates the (weakly or strongly) connected components in a graph.

    igraph_error_t igraph_connected_components(
        const igraph_t *graph, igraph_vector_int_t *membership,
        igraph_vector_int_t *csize, igraph_int_t *no, igraph_connectedness_t mode
    );

When computing strongly connected components, the components will be indexed in topological order. In other words, vertex `v` is reachable from vertex `u` precisely when `membership[u] <= membership[v]`.

Arguments:

`graph`: | The graph object to analyze.
`membership`: | For every vertex the ID of its component is given. The vector has to be preinitialized and will be resized as needed. Alternatively this argument can be `NULL`, in which case it is ignored.
`csize`: | For every component it gives its size, the order being defined by the component IDs. The vector must be preinitialized and will be resized as needed. Alternatively this argument can be `NULL`, in which case it is ignored.
`no`: | Pointer to an integer, if not `NULL` then the number of components will be stored here.

`mode`:

For directed graph this specifies whether to calculate weakly or strongly connected components. Possible values:

`IGRAPH_WEAK` | Compute weakly connected components, i.e. ignore edge directions.
`IGRAPH_STRONG` | Compute strongly connnected components, i.e. consider edge directions.

This parameter is ignored for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), where |V| and |E| are the number of vertices and edges in the graph.

Example 17.13. File `examples/simple/igraph_contract_vertices.c`

    #include <igraph.h>

    /* Create the condensation of a directed graph.
     * See https://en.wikipedia.org/wiki/Strongly_connected_component#Definitions
     * This example demonstrates how to write a basic igraph function, complete
     * with error handling. */
    igraph_error_t condensation(const igraph_t *graph, igraph_t *cond) {
        igraph_vector_int_t membership;

        /* Data structures such as vector must be initialized in igraph before use. */
        IGRAPH_CHECK(igraph_vector_int_init(&membership, 0));

        /* Adding the initialized vector to the "finally" stack ensures that it will
         * be automatically destroyed if an error occurs. */
        IGRAPH_FINALLY(igraph_vector_int_destroy, &membership);

        /* Functions that return an error code can be wrapped in IGRAPH_CHECK to pass that error
         * up to the caller. */
        IGRAPH_CHECK(igraph_connected_components(graph, &membership, /* csize */ NULL, /* no */ NULL, IGRAPH_STRONG));

        /* To compute the condensation, we simply contract strongly connected components.
         * Since igraph_contract_vertices() modifies graphs in-place, we make a copy first. */
        IGRAPH_CHECK(igraph_copy(cond, graph));

        /* Since we are not done creating the condensation yet, we add 'cond' to the
         * "finally" stack, so that it will be destroyed if an error occurs. */
        IGRAPH_FINALLY(igraph_destroy, cond);

        /* Contract strongly connected components. */
        IGRAPH_CHECK(igraph_contract_vertices(cond, &membership, NULL));

        /* igraph_contract_vertices() preserves all edges, some of which become
         * parallel edges or self-loops after the contraction. We simplify these. */
        IGRAPH_CHECK(igraph_simplify(cond, /* remove_multiple */ true, /* remove_loops */ true, NULL));

        /* Data structures that are no longer needed must be explicitly destroyed.
         * If they were added to the "finally" stack, they must be removed explicitly,
         * in the opposite order to how they were added. IGRAPH_FINALLY_CLEAN removes
         * the indicated number of entries from the "finally" stack. We remove
         * 'membership' because it was destroyed, and 'cond' because the responsibility
         * to destroy it is now with the caller. */
        igraph_vector_int_destroy(&membership);
        IGRAPH_FINALLY_CLEAN(2);

        return IGRAPH_SUCCESS; /* return with no error */
    }

    int main(void) {
        igraph_t graph, cond;

        /* Initialize the library. */
        igraph_setup();

        /* Create a random directed graph with mean degree 2 and compute its condensation. */
        igraph_erdos_renyi_game_gnm(&graph, 100, 200, IGRAPH_DIRECTED, IGRAPH_SIMPLE_SW, IGRAPH_EDGE_UNLABELED);
        condensation(&graph, &cond);

        printf("Number of vertices in the condensation: %" IGRAPH_PRId "\n", igraph_vcount(&cond));
        igraph_write_graph_edgelist(&cond, stdout);

        /* Destroy data structures that are no longer needed. */
        igraph_destroy(&graph);
        igraph_destroy(&cond);

        return 0;
    }

### 8.3. `igraph_is_connected` — Decides whether the graph is (weakly or strongly) connected.

    igraph_error_t igraph_is_connected(const igraph_t *graph, igraph_bool_t *res,
                            igraph_connectedness_t mode);

A graph is considered connected when any of its vertices is reachable from any other. A directed graph with this property is called strongly connected. A directed graph that would be connected when ignoring the directions of its edges is called weakly connected.

A graph with zero vertices (i.e. the null graph) is not connected by definition. This behaviour changed in igraph 0.9; earlier versions assumed that the null graph is connected. See the following issue on Github for the argument that led us to change the definition: https://github.com/igraph/igraph/issues/1539

The return value of this function is cached in the graph itself, separately for weak and strong connectivity. Calling the function multiple times with no modifications to the graph in between will return a cached value in O(1) time.

Arguments:

`graph`: | The graph object to analyze.
`res`: | Pointer to a Boolean variable, the result will be stored here.
`mode`: | For a directed graph this specifies whether to calculate weak or strong connectedness. Possible values: `IGRAPH_WEAK`, `IGRAPH_STRONG`. This argument is ignored for undirected graphs.

Returns:

`` | Error code: `IGRAPH_EINVAL`: invalid mode argument.

See also:

`` | `igraph_connected_components()` to find the connected components, `igraph_is_biconnected()` to check if the graph is 2-vertex-connected.

Time complexity: O(|V|+|E|), the number of vertices plus the number of edges in the graph.

### 8.4. `igraph_decompose` — Decomposes a graph into connected components.

    igraph_error_t igraph_decompose(const igraph_t *graph, igraph_graph_list_t *components,
                         igraph_connectedness_t mode,
                         igraph_int_t maxcompno, igraph_int_t minelements);

Creates a separate graph for each component of a graph. Note that the vertex IDs in the new graphs will be different than in the original graph, except when there is only a single component in the original graph.

Arguments:

`graph`: | The original graph.
`components`: | This list of graphs will contain the individual components. It should be initialized before calling this function and will be resized to hold the graphs.
`mode`: | Either `IGRAPH_WEAK` or `IGRAPH_STRONG` for weakly and strongly connected components respectively.
`maxcompno`: | The maximum number of components to return. The first `maxcompno` components will be returned (which hold at least `minelements` vertices, see the next parameter), the others will be ignored. Supply `-1` here if you don't want to limit the number of components.
`minelements`: | The minimum number of vertices a component should contain in order to place it in the `components` vector. For example, supplying 2 here ignores isolated vertices.

Returns:

`` | Error code, `IGRAPH_ENOMEM` if there is not enough memory to perform the operation.

Added in version 0.2.

Time complexity: O(|V|+|E|), the number of vertices plus the number of edges.

Example 17.14. File `examples/simple/igraph_decompose.c`

    #include <igraph.h>
    #include <stdlib.h>

    int main(void) {

        igraph_t ring, g, *component;
        igraph_graph_list_t complist;
        igraph_int_t i;

        /* Initialize the library. */
        igraph_setup();

        igraph_graph_list_init(&complist, 0);

        /* A ring, a single component */
        igraph_ring(&ring, 10, IGRAPH_UNDIRECTED, 0, 1);

        igraph_decompose(&ring, &complist, IGRAPH_WEAK, -1, 0);
        component = igraph_graph_list_get_ptr(&complist, 0);
        igraph_write_graph_edgelist(component, stdout);
        igraph_destroy(&ring);
        igraph_graph_list_clear(&complist);

        /* Random graph with a giant component */
        igraph_erdos_renyi_game_gnp(&g, 100, 4.0 / 100, IGRAPH_UNDIRECTED, IGRAPH_SIMPLE_SW, IGRAPH_EDGE_UNLABELED);
        igraph_decompose(&g, &complist, IGRAPH_WEAK, -1, 20);
        if (igraph_graph_list_size(&complist) != 1) {
            return 1;
        }
        igraph_destroy(&g);
        igraph_graph_list_clear(&complist);

        /* A toy graph, three components maximum, with at least 2 vertices each */
        igraph_small(&g, 0, IGRAPH_DIRECTED,
                     0, 1, 1, 2, 2, 0,
                     3, 4, 4, 5, 5, 6,
                     8, 9, 9, 10,
                     -1);
        igraph_decompose(&g, &complist, IGRAPH_WEAK, 3, 2);
        for (i = 0; i < igraph_graph_list_size(&complist); i++) {
            component = igraph_graph_list_get_ptr(&complist, i);
            igraph_write_graph_edgelist(component, stdout);
        }
        igraph_destroy(&g);

        igraph_graph_list_destroy(&complist);

        return 0;
    }

### 8.5. `igraph_reachability` — Calculates which vertices are reachable from each vertex in the graph.

    igraph_error_t igraph_reachability(
            const igraph_t *graph,
            igraph_vector_int_t *membership,
            igraph_vector_int_t *csize,
            igraph_int_t *no_of_components,
            igraph_bitset_list_t *reach,
            igraph_neimode_t mode);

The resulting list will contain one bitset for each strongly connected component. The bitset for component i will have its j-th bit set, if vertex j is reachable from some vertex in component i in 0 or more steps. In particular, a vertex is always reachable from itself.

Arguments:

`graph`: | The graph object to analyze.
`membership`: | Pointer to an integer vector. For every vertex, the ID of its component is given. The vector will be resized as needed. This parameter must not be `NULL`.
`csize`: | Pointer to an integer vector or `NULL`. For every component, it gives its size (vertex count), the order being defined by the component IDs. The vector will be resized as needed.
`no_of_components`: | Pointer to an integer or `NULL`. The number of components will be stored here.
`reach`: | A list of bitsets representing the result. It will be resized as needed. `reach[membership[u]][v]` is set to `true` if vertex `v` is reachable from vertex `u`.
`mode`: | In directed graphs, controls the treatment of edge directions. Ignored in undirected graphs. With `IGRAPH_OUT`, reachability is computed by traversing edges along their direction. With `IGRAPH_IN`, edges are traversed opposite to their direction. With `IGRAPH_ALL`, edge directions are ignored and the graph is treated as undirected.

Returns:

`` | Error code: `IGRAPH_ENOMEM` if there is not enough memory to perform the operation.

See also:

`` | `igraph_connected_components()` to find the connnected components of a graph; `igraph_count_reachable()` to count how many vertices are reachable from each vertex; `igraph_subcomponent()` to find which vertices are rechable from a single vertex.

Time complexity: O(|C||V|/w + |V| + |E|), where |C| is the number of strongly connected components (at most |V|), |V| is the number of vertices, and |E| is the number of edges respectively, and w is the bit width of igraph_int_t, typically the word size of the machine (32 or 64).

### 8.6. `igraph_count_reachable` — The number of vertices reachable from each vertex in the graph.

    igraph_error_t igraph_count_reachable(const igraph_t *graph,
                                          igraph_vector_int_t *counts,
                                          igraph_neimode_t mode);

Arguments:

`graph`: | The graph object to analyze.
`counts`: | Integer vector. `counts[v]` will store the number of vertices reachable from vertex `v`, including `v` itself.
`mode`: | In directed graphs, controls the treatment of edge directions. Ignored in undirected graphs. With `IGRAPH_OUT`, reachability is computed by traversing edges along their direction. With `IGRAPH_IN`, edges are traversed opposite to their direction. With `IGRAPH_ALL`, edge directions are ignored and the graph is treated as undirected.

Returns:

`` | Error code: `IGRAPH_ENOMEM` if there is not enough memory to perform the operation.

See also:

`` | `igraph_connected_components()`, `igraph_transitive_closure()`

Time complexity: O(|C||V|/w + |V| + |E|), where |C| is the number of strongly connected components (at most |V|), |V| is the number of vertices, and |E| is the number of edges respectively, and w is the bit width of igraph_int_t, typically the word size of the machine (32 or 64).

### 8.7. `igraph_transitive_closure` — Computes the transitive closure of a graph.

    igraph_error_t igraph_transitive_closure(const igraph_t *graph, igraph_t *closure);

The resulting graph will have an edge from vertex `i` to vertex `j` if `j` is reachable from `i`.

Arguments:

`graph`: | The graph object to analyze.
`closure`: | The resulting graph representing the transitive closure.

Returns:

`` | Error code: `IGRAPH_ENOMEM` if there is not enough memory to perform the operation.

See also:

`` | `igraph_connected_components()`, `igraph_count_reachable()`

Time complexity: O(|V|^2 + |E|), where |V| is the number of vertices, and |E| is the number of edges, respectively.

### 8.8. `igraph_biconnected_components` — Calculates biconnected components.

    igraph_error_t igraph_biconnected_components(const igraph_t *graph,
                                      igraph_int_t *no,
                                      igraph_vector_int_list_t *tree_edges,
                                      igraph_vector_int_list_t *component_edges,
                                      igraph_vector_int_list_t *components,
                                      igraph_vector_int_t *articulation_points);

A graph is biconnected if the removal of any single vertex (and its incident edges) does not disconnect it.

A biconnected component of a graph is a maximal biconnected subgraph of it. The biconnected components of a graph can be given by a partition of its edges: every edge is a member of exactly one biconnected component. Note that this is not true for vertices: the same vertex can be part of many biconnected components, while isolated vertices are part of none at all.

Note that some authors do not consider the graph consisting of two connected vertices as biconnected, however, igraph does.

igraph does not consider components containing a single vertex only as being biconnected. Isolated vertices will not be part of any of the biconnected components. This means that checking whether there is a single biconnected component is not sufficient for determining if a graph is biconnected. Use `igraph_is_biconnected()` for this purpose.

Arguments:

`graph`: | The input graph. It will be treated as undirected.
`no`: | If not a `NULL` pointer, the number of biconnected components will be stored here.
`tree_edges`: | If not a `NULL` pointer, then the found components are stored here, in a list of vectors. Every vector in the list is a biconnected component, represented by its edges. More precisely, a spanning tree of the biconnected component is returned.
`component_edges`: | If not a `NULL` pointer, then the edges of the biconnected components are stored here, in the same form as for `tree_edges`.
`components`: | If not a `NULL` pointer, then the vertices of the biconnected components are stored here, in the same format as for the previous two arguments.
`articulation_points`: | If not a NULL pointer, then the articulation points of the graph are stored in this vector. A vertex is an articulation point if its removal increases the number of (weakly) connected components in the graph.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), linear in the number of vertices and edges, but only if you do not calculate `components` and `component_edges`. If you calculate `components`, then it is quadratic in the number of vertices. If you calculate `component_edges` as well, then it is cubic in the number of vertices.

See also:

`` | `igraph_articulation_points()`, `igraph_is_biconnected()`, `igraph_connected_components()`.

Example 17.15. File `examples/simple/igraph_biconnected_components.c`

    #include <igraph.h>

    /* Prints a vector of edge IDs as u--v vertex pairs. */
    void print_edge_vector(const igraph_t *graph, const igraph_vector_int_t *edges) {
        const igraph_int_t n = igraph_vector_int_size(edges);
        for (igraph_int_t i=0; i < n; i++) {
            igraph_int_t edge = VECTOR(*edges)[i];
            printf("%" IGRAPH_PRId "--%" IGRAPH_PRId " ", IGRAPH_FROM(graph, edge), IGRAPH_TO(graph, edge));
        }
        printf("\n");
    }

    int main(void) {
        igraph_t graph;
        igraph_vector_int_list_t component_vertices, component_edges;
        igraph_int_t no;

        /* Initialize the library. */
        igraph_setup();

        /* Create an example graph. */
        igraph_small(&graph, 7, IGRAPH_UNDIRECTED,
                     0,1, 1,2, 2,3, 3,0,
                     2,4, 4,5, 5,2,
                     0,6,
                     0,7,
                     -1);

        /* The data structures that the result will be written to must be initialized first. */
        igraph_vector_int_list_init(&component_vertices, 0);
        igraph_vector_int_list_init(&component_edges, 0);

        igraph_biconnected_components(&graph, &no, NULL, &component_edges, &component_vertices, NULL);

        printf("Number of components: %" IGRAPH_PRId "\n", no);
        for (igraph_int_t i=0; i < no; i++) {
            printf("\n");
            printf("Component %" IGRAPH_PRId ":\n", i);
            printf("Vertices: ");
            igraph_vector_int_print(igraph_vector_int_list_get_ptr(&component_vertices, i));
            printf("Edges: ");
            print_edge_vector(&graph, igraph_vector_int_list_get_ptr(&component_edges, i));
        }

        /* Destroy data structures after we no longer need them. */

        igraph_vector_int_list_destroy(&component_edges);
        igraph_vector_int_list_destroy(&component_vertices);

        igraph_destroy(&graph);

        return 0;
    }

### 8.9. `igraph_articulation_points` — Finds the articulation points in a graph.

    igraph_error_t igraph_articulation_points(const igraph_t *graph, igraph_vector_int_t *res);

A vertex is an articulation point if its removal increases the number of (weakly) connected components in the graph.

Note that a graph without any articulation points is not necessarily biconnected. Counterexamples are the two-vertex complete graph as well as empty graphs. Use `igraph_is_biconnected()` to check whether a graph is biconnected.

Arguments:

`graph`: | The input graph. It will be treated as undirected.
`res`: | Pointer to an initialized vector, the articulation points will be stored here.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), linear in the number of vertices and edges.

See also:

`` | `igraph_biconnected_components()`, `igraph_is_bipartite()`, `igraph_connected_components()`, `igraph_bridges()`

### 8.10. `igraph_bridges` — Finds all bridges in a graph.

    igraph_error_t igraph_bridges(const igraph_t *graph, igraph_vector_int_t *bridges);

An edge is a bridge if its removal increases the number of (weakly) connected components in the graph.

Arguments:

`graph`: | The input graph. It will be treated as undirected.
`bridges`: | Pointer to an initialized vector, the bridges will be stored here as edge indices.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), linear in the number of vertices and edges.

See also:

`` | `igraph_articulation_points()`, `igraph_biconnected_components()`, `igraph_connected_components()`

### 8.11. `igraph_is_biconnected` — Checks whether a graph is biconnected.

    igraph_error_t igraph_is_biconnected(const igraph_t *graph, igraph_bool_t *res);

A graph is biconnected if the removal of any single vertex (and its incident edges) does not disconnect it.

igraph does not consider single-vertex graphs biconnected.

Note that some authors do not consider the graph consisting of two connected vertices as biconnected, however, igraph does.

Arguments:

`graph`: | The input graph. It will be treated as undirected.
`res`: | If not a `NULL` pointer, the result will be returned here.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), linear in the number of vertices and edges.

See also:

`` | `igraph_articulation_points()`, `igraph_biconnected_components()`.

Example 17.16. File `examples/simple/igraph_is_biconnected.c`

    #include <igraph.h>
    #include <stdio.h>

    int main(void) {

        igraph_t g;
        igraph_bool_t result;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&g, 7, 0, 0, 1, 1, 2, 2, 3, 3, 0, 2, 4, 4, 5, 2, 5, -1);
        igraph_is_biconnected(&g, &result);
        printf("Graph is%sbiconnected.\n", result ? " " : " not ");
        igraph_destroy(&g);

        return 0;
    }

## 9. Percolation

### 9.1. `igraph_site_percolation` — The size of the largest component as vertices are added to a graph.

    igraph_error_t igraph_site_percolation(
            const igraph_t *graph,
            igraph_vector_int_t *giant_size,
            igraph_vector_int_t *edge_count,
            const igraph_vector_int_t *vertex_order);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

Calculates the site percolation curve, i.e. the size of the largest connected component as vertices are added in the given order. If both `giant_size` and `vertex_order` are reversed, it is the size of the largest component as vertices are removed from the graph. If no vertex order is given, a random one will be used.

Arguments:

`graph`: | The graph that vertices are assumed to be in. Edge directions are ignored.
`giant_size`: | `giant_size[i]` will contain the size of the largest component after having added the vertex with index `vertex_order[i]`.
`edge_count`: | `edge_count[i]` will contain the numer of edges in the graph having added the vertex with index `vertex_order[i]`.
`vertex_order`: | The order the vertices are added in. Must not contain duplicates. If `NULL`, a random order will be used.

Returns:

`` | Error code.

See also:

`` | `igraph_bond_percolation()` to compute the edge percolation curve; `igraph_connected_components()` to find the size of connected components.

Time complexity: O(|V| + |E| a(|E|)) where a is the inverse Ackermann function, for all practical purposes it is not above 5.

### 9.2. `igraph_bond_percolation` — The size of the largest component as edges are added to a graph.

    igraph_error_t igraph_bond_percolation(
            const igraph_t *graph,
            igraph_vector_int_t *giant_size,
            igraph_vector_int_t *vertex_count,
            const igraph_vector_int_t *edge_order);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

Calculates the bond percolation curve, i.e. the size of the largest connected component as edges are added to the graph in the order given. If both `giant_size` and `edge_order` are reversed, it is the size of the largest component as edges are removed from the graph. If no edge order is given, a random one will be used.

Arguments:

`graph`: | The graph that edges are assumed to be in. Edge directions are ignored.
`giant_size`: | `giant_size[i]` will contain the size of the largest component after having added the edge with index `edge_order[i]`.
`vertex_count`: | `vertex_count[i]` will contain the number of vertices that have at least one incident edge after adding the edge with index `edge_order[i]`.
`edge_order`: | The order the edges are added in. Must not contain duplicates. If `NULL`, a random order will be used.

Returns:

`` | Error code.

See also:

`` | `igraph_edgelist_percolation()` to specify the edges to be added by their endpoints; `igraph_site_percolation()` to compute the vertex percolation curve; `igraph_connected_components()` to find the size of connected components.

Time complexity: O(|V| + |E| a(|E|)) where a is the inverse Ackermann function, for all practical purposes it is not above 5.

### 9.3. `igraph_edgelist_percolation` — The size of the largest component as vertex pairs are connected.

    igraph_error_t igraph_edgelist_percolation(
            const igraph_vector_int_t *edges,
            igraph_vector_int_t *giant_size,
            igraph_vector_int_t *vertex_count);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

Calculates the size of the largest connected component as edges are added to a graph in the given order. This function differs from `igraph_bond_percolation()` in that it take a list of vertex pairs as input.

Arguments:

`edges`: | Vector of edges, where the i-th edge has endpoints `edges[2i]` and `edges[2i+1]`.
`giant_size`: | `giant_size[i]` will contain the size of the largest connected component after edge `i` is added.
`vertex_count`: | `vertex_count[i]` will contain the number of vertices with at least one edge after edge `i` is added.

Returns:

`` | Error code.

See also:

`` | `igraph_bond_percolation()` to specify edges by their ID in a graph object.

Time complexity: O(|E| a(|E|)) where a is the inverse Ackermann function, for all practical purposes it is not above 5.

## 10. Degree sequences

### 10.1. `igraph_is_graphical` — Is there a graph with the given degree sequence?

    igraph_error_t igraph_is_graphical(const igraph_vector_int_t *out_degrees,
                            const igraph_vector_int_t *in_degrees,
                            const igraph_edge_type_sw_t allowed_edge_types,
                            igraph_bool_t *res);

Determines whether a sequence of integers can be the degree sequence of some graph. The classical concept of graphicality assumes simple graphs. This function can perform the check also when either self-loops, multi-edge, or both are allowed in the graph.

For simple undirected graphs, the Erdős-Gallai conditions are checked using the linear-time algorithm of Cloteaux. If both self-loops and multi-edges are allowed, it is sufficient to chek that that sum of degrees is even. If only multi-edges are allowed, but not self-loops, there is an additional condition that the sum of degrees be no smaller than twice the maximum degree. If at most one self-loop is allowed per vertex, but no multi-edges, a modified version of the Erdős-Gallai conditions are used (see Cairns & Mendan).

For simple directed graphs, the Fulkerson-Chen-Anstee theorem is used with the relaxation by Berger. If both self-loops and multi-edges are allowed, then it is sufficient to check that the sum of in- and out-degrees is the same. If only multi-edges are allowed, but not self loops, there is an additional condition that the sum of out-degrees (or equivalently, in-degrees) is no smaller than the maximum total degree. If single self-loops are allowed, but not multi-edges, the problem is equivalent to realizability as a simple bipartite graph, thus the Gale-Ryser theorem can be used; see `igraph_is_bigraphical()` for more information.

References:

P. Erdős and T. Gallai, Gráfok előírt fokú pontokkal, Matematikai Lapok 11, pp. 264–274 (1960). https://users.renyi.hu/~p_erdos/1961-05.pdf

Z. Király, Recognizing graphic degree sequences and generating all realizations. TR-2011-11, Egerváry Research Group, H-1117, Budapest, Hungary. ISSN 1587-4451 (2012). https://egres.elte.hu/tr/egres-11-11.pdf

B. Cloteaux, Is This for Real? Fast Graphicality Testing, Comput. Sci. Eng. 17, 91 (2015). https://dx.doi.org/10.1109/MCSE.2015.125

A. Berger, A note on the characterization of digraphic sequences, Discrete Math. 314, 38 (2014). https://dx.doi.org/10.1016/j.disc.2013.09.010

G. Cairns and S. Mendan, Degree Sequence for Graphs with Loops (2013). https://arxiv.org/abs/1303.2145v1

Arguments:

`out_degrees`: | A vector of integers specifying the degree sequence for undirected graphs or the out-degree sequence for directed graphs.
`in_degrees`: | A vector of integers specifying the in-degree sequence for directed graphs. For undirected graphs, it must be `NULL`.

`allowed_edge_types`:

The types of edges to allow in the graph. See `igraph_edge_type_sw_t` for details.

`IGRAPH_SIMPLE_SW` | simple graphs (i.e. no self-loops or multi-edges allowed).
`IGRAPH_LOOPS_SW` | single self-loops are allowed, but not multi-edges.
`IGRAPH_MULTI_SW` | multi-edges are allowed, but not self-loops.
`IGRAPH_LOOPS_SW | IGRAPH_MULTI_SW` | both self-loops and multi-edges are allowed.

`res`: | Pointer to a Boolean. The result will be stored here.

Returns:

`` | Error code.

See also:

`` | `igraph_is_bigraphical()` to check if a bi-degree-sequence can be realized as a bipartite graph; `igraph_realize_degree_sequence()` to construct a graph with a given degree sequence.

Time complexity: O(n), where n is the length of the degree sequence(s).

### 10.2. `igraph_is_bigraphical` — Is there a bipartite graph with the given bi-degree-sequence?

    igraph_error_t igraph_is_bigraphical(const igraph_vector_int_t *degrees1,
                              const igraph_vector_int_t *degrees2,
                              const igraph_edge_type_sw_t allowed_edge_types,
                              igraph_bool_t *res);

Determines whether two sequences of integers can be the degree sequences of a bipartite graph. Such a pair of degree sequence is called bigraphical.

When multi-edges are allowed, it is sufficient to check that the sum of degrees is the same in the two partitions. For simple graphs, the Gale-Ryser theorem is used with Berger's relaxation.

References:

H. J. Ryser, Combinatorial Properties of Matrices of Zeros and Ones, Can. J. Math. 9, 371 (1957). https://dx.doi.org/10.4153/cjm-1957-044-3

D. Gale, A theorem on flows in networks, Pacific J. Math. 7, 1073 (1957). https://dx.doi.org/10.2140/pjm.1957.7.1073

A. Berger, A note on the characterization of digraphic sequences, Discrete Math. 314, 38 (2014). https://dx.doi.org/10.1016/j.disc.2013.09.010

Arguments:

`degrees1`: | A vector of integers specifying the degrees in the first partition
`degrees2`: | A vector of integers specifying the degrees in the second partition

`allowed_edge_types`:

The types of edges to allow in the graph:

`IGRAPH_SIMPLE_SW` | simple graphs (i.e. no multi-edges allowed).
`IGRAPH_MULTI_SW` | multi-edges are allowed.

`res`: | Pointer to a Boolean. The result will be stored here.

Returns:

`` | Error code.

See also:

`` | `igraph_is_graphical()`

Time complexity: O(n), where n is the length of the larger degree sequence.

## 11. Centrality measures

### 11.1. `igraph_closeness` — Closeness centrality calculations for some vertices.

    igraph_error_t igraph_closeness(const igraph_t *graph, igraph_vector_t *res,
                         igraph_vector_int_t *reachable_count, igraph_bool_t *all_reachable,
                         const igraph_vs_t vids, igraph_neimode_t mode,
                         const igraph_vector_t *weights,
                         igraph_bool_t normalized);

The closeness centrality of a vertex measures how easily other vertices can be reached from it (or the other way: how easily it can be reached from the other vertices). It is defined as the inverse of the mean distance to (or from) all other vertices.

Closeness centrality is meaningful only for connected graphs. If the graph is not connected, igraph computes the inverse of the mean distance to (or from) all reachable vertices. In undirected graphs, this is equivalent to computing the closeness separately in each connected component. The optional `all_reachable` output parameter is provided to help detect when the graph is disconnected.

While there is no universally adopted definition of closeness centrality for disconnected graphs, there have been some attempts for generalizing the concept to the disconnected case. One type of approach considers the mean distance only to reachable vertices, then re-scales the obtained certrality score by a factor that depends on the number of reachable vertices (i.e. the size of the component in the undirected case). To facilitate computing these generalizations of closeness centrality, the number of reachable vertices (not including the starting vertex) is returned in `reachable_count`.

In disconnected graphs, consider using the harmonic centrality, computable using `igraph_harmonic_centrality()`.

For isolated vertices, i.e. those having no associated paths, NaN is returned.

Arguments:

`graph`: | The graph object.
`res`: | The result of the computation, a vector containing the closeness centrality scores for the given vertices.
`reachable_count`: | If not `NULL`, this vector will contain the number of vertices reachable from each vertex for which the closeness is calculated (not including that vertex).
`all_reachable`: | Pointer to a Boolean. If not `NULL`, it indicates if all vertices of the graph were reachable from each vertex in `vids`. If false, the graph is non-connected. If true, and the graph is undirected, or if the graph is directed and `vids` contains all vertices, then the graph is connected.
`vids`: | The vertices for which the closeness centrality will be computed.

`mode`:

The type of shortest paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the lengths of the outgoing paths are calculated.
`IGRAPH_IN` | the lengths of the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`weights`: | An optional vector containing edge weights for weighted closeness. NaN values re not allowed as weights. Supply a null pointer here for traditional, unweighted closeness.
`normalized`: | If true, the inverse of the mean distance to reachable vertices is returned. If false, the inverse of the sum of distances is returned.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(n|E|) for the unweighted case and O(n|E|log|V|+|V|) for the weighted case, where n is the number of vertices for which the calculation is done, |V| is the number of vertices and |E| is the number of edges in the graph.

See also:

`` | Other centrality types: `igraph_degree()`, `igraph_betweenness()`, `igraph_harmonic_centrality()`. See `igraph_closeness_cutoff()` for the range-limited closeness centrality.

### 11.2. `igraph_harmonic_centrality` — Harmonic centrality for some vertices.

    igraph_error_t igraph_harmonic_centrality(const igraph_t *graph, igraph_vector_t *res,
                                   const igraph_vs_t vids, igraph_neimode_t mode,
                                   const igraph_vector_t *weights,
                                   igraph_bool_t normalized);

The harmonic centrality of a vertex is the mean inverse distance to all other vertices. The inverse distance to an unreachable vertex is considered to be zero.

References:

M. Marchiori and V. Latora, Harmony in the small-world, Physica A 285, pp. 539-546 (2000). https://doi.org/10.1016/S0378-4371%2800%2900311-3

Y. Rochat, Closeness Centrality Extended to Unconnected Graphs: the Harmonic Centrality Index, ASNA 2009. https://infoscience.epfl.ch/record/200525

S. Vigna and P. Boldi, Axioms for Centrality, Internet Mathematics 10, (2014). https://doi.org/10.1080/15427951.2013.865686

Arguments:

`graph`: | The graph object.
`res`: | The result of the computation, a vector containing the harmonic centrality scores for the given vertices.
`vids`: | The vertices for which the harmonic centrality will be computed.

`mode`:

The type of shortest paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the lengths of the outgoing paths are calculated.
`IGRAPH_IN` | the lengths of the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`weights`: | An optional vector containing edge weights for weighted harmonic centrality. No edge weight may be NaN. If `NULL`, all weights are considered to be one.
`normalized`: | Boolean, whether to normalize the result. If true, the result is the mean inverse path length to other vertices, i.e. it is normalized by the number of vertices minus one. If false, the result is the sum of inverse path lengths to other vertices.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(n|E|) for the unweighted case and O(n*|E|log|V|+|V|) for the weighted case, where n is the number of vertices for which the calculation is done, |V| is the number of vertices and |E| is the number of edges in the graph.

See also:

`` | Other centrality types: `igraph_closeness()`, `igraph_degree()`, `igraph_betweenness()`.

### 11.3. `igraph_betweenness` — Betweenness centrality of some vertices.

    igraph_error_t igraph_betweenness(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *res, igraph_vs_t vids,
            igraph_bool_t directed, igraph_bool_t normalized);

The betweenness centrality of a vertex `v` is the number of shortest paths passing through it. If there is more than one shortest path between two vertices, the fraction of these passing through `v` is counted.

Reference:

Ulrik Brandes: A faster algorithm for betweenness centrality. The Journal of Mathematical Sociology, 25(2), 163–177 (2001). https://doi.org/10.1080/0022250X.2001.9990249

Arguments:

`graph`: | The graph object.
`weights`: | An optional vector containing edge weights for calculating weighted betweenness. No edge weight may be NaN. Supply a null pointer here for unweighted betweenness.
`res`: | The result of the computation, a vector containing the betweenness scores for the specified vertices.
`vids`: | The vertices for which the range-limited betweenness centrality scores will be returned. This paramerer is for convenience only and does not affect performance. Internally, the betewenness of all vertices is calculated.
`directed`: | If true directed paths will be considered for directed graphs. It is ignored for undirected graphs.
`normalized`: | Whether to normalize betweenness scores by the number of vertex pairs. In directed graphs, the number of ordered vertex pairs, in undirected graphs the number of unordered vertex pairs is used.

Returns:

`` | Error code: `IGRAPH_ENOMEM`, not enough memory for temporary data. `IGRAPH_EINVVID`, invalid vertex ID passed in `vids`.

Time complexity: O(|V||E|), |V| and |E| are the number of vertices and edges in the graph. Note that the time complexity is independent of the number of vertices for which the score is calculated.

See also:

`` | `igraph_edge_betweenness()` for calculating the betweenness score of the edges in a graph; `igraph_betweenness_cutoff()` to calculate the range-limited betweenness of the vertices in a graph; `igraph_betweenness_subset()` to consider shortest paths only between two vertex subsets for calculating betweenness.

### 11.4. `igraph_edge_betweenness` — Betweenness centrality of the edges.

    igraph_error_t igraph_edge_betweenness(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *res, igraph_es_t eids,
            igraph_bool_t directed, igraph_bool_t normalized);

The betweenness centrality of an edge `e` is the number of shortest paths passing through it. If there is more than one shortest path between two vertices, the fraction of these passing through `e` is counted.

Reference:

Ulrik Brandes: A faster algorithm for betweenness centrality. The Journal of Mathematical Sociology, 25(2), 163–177 (2001). https://doi.org/10.1080/0022250X.2001.9990249

Arguments:

`graph`: | The graph object.
`weights`: | An optional weight vector for weighted edge betweenness. No edge weight may be NaN. Supply a null pointer here for the unweighted version.
`res`: | The result of the computation, vector containing the betweenness scores for the edges.
`eids`: | The edges for which the betweenness centrality will be returned. This parameter is for convenience only, and does not affect performance. Internally, the betweenness is be calculated for all edges.
`directed`: | If true directed paths will be considered for directed graphs. It is ignored for undirected graphs.
`normalized`: | Whether to normalize betweenness scores by the number of vertex pairs. In directed graphs, the number of ordered vertex pairs, in undirected graphs the number of unordered vertex pairs is used.

Returns:

`` | Error code: `IGRAPH_ENOMEM`, not enough memory for temporary data.

Time complexity: O(|V||E|), |V| and |E| are the number of vertices and edges in the graph.

See also:

`` | `igraph_betweenness()` for calculating the betweenness score of the vertices in a graph; `igraph_edge_betweenness_cutoff()` to compute the range-limited betweenness score of the edges in a graph; `igraph_edge_betweenness_subset()` to consider shortest paths only between two vertex subsets for calculating betweenness.

### 11.5. `igraph_pagerank_algo_t` — PageRank algorithm implementation.

    typedef enum {
        IGRAPH_PAGERANK_ALGO_ARPACK = 1,
        IGRAPH_PAGERANK_ALGO_PRPACK = 2
    } igraph_pagerank_algo_t;

Algorithms to calculate PageRank.

Values:

`IGRAPH_PAGERANK_ALGO_ARPACK`: | Use the ARPACK library, this was the PageRank implementation in igraph from version 0.5, until version 0.7.
`IGRAPH_PAGERANK_ALGO_PRPACK`: | Use the PRPACK library. Currently this implementation is recommended.

### 11.6. `igraph_pagerank` — Calculates the Google PageRank for the specified vertices.

    igraph_error_t igraph_pagerank(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *vector, igraph_real_t *value,
            igraph_real_t damping, igraph_bool_t directed,
            igraph_vs_t vids,
            igraph_pagerank_algo_t algo,
            igraph_arpack_options_t *options);

The PageRank centrality of a vertex is the fraction of time a random walker traversing the graph would spend on that vertex. The walker follows the out-edges with probabilities proportional to their weights. Additionally, in each step, it restarts the walk from a random vertex with probability `1 - damping`. If the random walker gets stuck in a sink vertex, it will also restart from a random vertex.

The PageRank centrality is mainly useful for directed graphs. In undirected graphs it converges to trivial values proportional to degrees as the damping factor approaches 1.

Starting from version 0.9, igraph has two PageRank implementations, and the user can choose between them. The first implementation is `IGRAPH_PAGERANK_ALGO_ARPACK`, which phrases the PageRank calculation as an eigenvalue problem, which is then solved using the ARPACK library. This was the default before igraph version 0.7. The second and recommended implementation is `IGRAPH_PAGERANK_ALGO_PRPACK`. This is using the PRPACK package, see https://github.com/dgleich/prpack. PRPACK uses an algebraic method, i.e. solves a linear system to obtain the PageRank scores.

Note that the PageRank of a given vertex depends on the PageRank of all other vertices, so even if you want to calculate the PageRank for only some of the vertices, all of them must be calculated. Requesting the PageRank for only some of the vertices does not result in any performance increase at all.

References:

Sergey Brin and Larry Page: The Anatomy of a Large-Scale Hypertextual Web Search Engine. Proceedings of the 7th World-Wide Web Conference, Brisbane, Australia, April 1998. https://doi.org/10.1016/S0169-7552(98)00110-X

Arguments:

`graph`: | The graph object.
`weights`: | Optional edge weights. May be a `NULL` pointer, meaning unweighted edges, or a vector of non-negative values of the same length as the number of edges.
`vector`: | Pointer to an initialized vector, the result is stored here. It is resized as needed.
`value`: | Pointer to a real variable. When using `IGRAPH_PAGERANK_ALGO_ARPACK`, the eigenvalue corresponding to the PageRank vector is stored here. It is expected to be exactly one. Checking this value can be used to diagnose cases when ARPACK failed to converge to the leading eigenvector. When using `IGRAPH_PAGERANK_ALGO_PRPACK`, this is always set to 1.0.
`damping`: | The damping factor ("d" in the original paper). Must be a probability in the range [0, 1]. A commonly used value is 0.85.
`directed`: | Boolean, whether to consider the directedness of the edges. This is ignored for undirected graphs.
`vids`: | The vertex IDs for which the PageRank is returned. This parameter is only for convenience. Computing PageRank for fewer than all vertices will not speed up the calculation.
`algo`: | The PageRank implementation to use. Possible values: `IGRAPH_PAGERANK_ALGO_ARPACK`, `IGRAPH_PAGERANK_ALGO_PRPACK`.
`options`: | Options for the ARPACK method. See `igraph_arpack_options_t` for details. Supply `NULL` here to use the defaults. Note that the function overwrites the `n` (number of vertices), `nev` (1), `ncv` (3) and `which` (LM) parameters and it always starts the calculation from a non-random vector calculated based on the degree of the vertices.

Returns:

`` | Error code: `IGRAPH_ENOMEM`, not enough memory for temporary data. `IGRAPH_EINVVID`, invalid vertex ID in `vids`.

Time complexity: depends on the input graph, usually it is O(|E|), the number of edges.

See also:

`` | `igraph_personalized_pagerank()` and `igraph_personalized_pagerank_vs()` for the personalized PageRank measure. See `igraph_arpack_rssolve()` and `igraph_arpack_rnsolve()` for the underlying machinery used by `IGRAPH_PAGERANK_ALGO_ARPACK`.

Example 17.17. File `examples/simple/igraph_pagerank.c`

    #include <igraph.h>
    #include <float.h>

    int main(void) {
        igraph_t graph;
        igraph_vector_t pagerank;
        igraph_real_t value;

        /* Initialize the library. */
        igraph_setup();

        /* Create a directed graph */
        igraph_kautz(&graph, 2, 3);

        /* Initialize the vector where the results will be stored */
        igraph_vector_init(&pagerank, 0);

        igraph_pagerank(&graph, /* weights */ NULL,
                        &pagerank, &value,
                /* damping */ 0.85, IGRAPH_DIRECTED,
                        igraph_vss_all(), IGRAPH_PAGERANK_ALGO_PRPACK,
                        NULL /* not needed with PRPACK method */);

        /* Check that the eigenvalue is 1, as expected. */
        if (fabs(value - 1.0) > 32*DBL_EPSILON) {
            fprintf(stderr, "PageRank failed to converge.\n");
            return 1;
        }

        /* Output the result */
        igraph_vector_print(&pagerank);

        /* Destroy data structure when no longer needed */
        igraph_vector_destroy(&pagerank);
        igraph_destroy(&graph);

        return 0;
    }

### 11.7. `igraph_personalized_pagerank` — Calculates the personalized Google PageRank for the specified vertices.

    igraph_error_t igraph_personalized_pagerank(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *vector, igraph_real_t *value,
            const igraph_vector_t *reset,
            igraph_real_t damping, igraph_bool_t directed,
            igraph_vs_t vids,
            igraph_pagerank_algo_t algo,
            igraph_arpack_options_t *options);

The personalized PageRank is similar to the original PageRank measure, but when the random walk is restarted, a new starting vertex is chosen non-uniformly, according to the distribution specified in `reset` (instead of the uniform distribution in the original PageRank measure). The `reset` distribution is used both when restarting randomly with probability `1 - damping`, and when the walker is forced to restart due to being stuck in a sink vertex (a vertex with no outgoing edges).

Note that the personalized PageRank of a given vertex depends on the personalized PageRank of all other vertices, so even if you want to calculate the personalized PageRank for only some of the vertices, all of them must be calculated. Requesting the personalized PageRank for only some of the vertices does not result in any performance increase at all.

Arguments:

`graph`: | The graph object.
`weights`: | Optional edge weights. May be a `NULL` pointer, meaning unweighted edges, or a vector of non-negative values of the same length as the number of edges.
`vector`: | Pointer to an initialized vector, the result is stored here. It is resized as needed.
`value`: | Pointer to a real variable. When using `IGRAPH_PAGERANK_ALGO_ARPACK`, the eigenvalue corresponding to the PageRank vector is stored here. It is expected to be exactly one. Checking this value can be used to diagnose cases when ARPACK failed to converge to the leading eigenvector. When using `IGRAPH_PAGERANK_ALGO_PRPACK`, this is always set to 1.0.
`reset`: | The probability distribution over the vertices used when resetting the random walk. It is either a `NULL` pointer (denoting a uniform choice that results in the original PageRank measure) or a vector of the same length as the number of vertices.
`damping`: | The damping factor ("d" in the original paper). Must be a probability in the range [0, 1]. A commonly used value is 0.85.
`directed`: | Boolean, whether to consider the directedness of the edges. This is ignored for undirected graphs.
`vids`: | The vertex IDs for which the PageRank is returned. This parameter is only for convenience. Computing PageRank for fewer than all vertices will not speed up the calculation.
`algo`: | The PageRank implementation to use. Possible values: `IGRAPH_PAGERANK_ALGO_ARPACK`, `IGRAPH_PAGERANK_ALGO_PRPACK`.
`options`: | Options for the ARPACK method. See `igraph_arpack_options_t` for details. Supply `NULL` here to use the defaults. Note that the function overwrites the `n` (number of vertices), `nev` (1), `ncv` (3) and `which` (LM) parameters and it always starts the calculation from a non-random vector calculated based on the degree of the vertices.

Returns:

`` | Error code: `IGRAPH_ENOMEM`, not enough memory for temporary data. `IGRAPH_EINVVID`, invalid vertex ID in `vids` or an invalid reset vector in `reset`.

Time complexity: depends on the input graph, usually it is O(|E|), the number of edges.

See also:

`` | `igraph_pagerank()` for the non-personalized implementation, `igraph_personalized_pagerank_vs()` for a personalized implementation with resetting to specific vertices.

### 11.8. `igraph_personalized_pagerank_vs` — Calculates the personalized Google PageRank for the specified vertices.

    igraph_error_t igraph_personalized_pagerank_vs(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *vector, igraph_real_t *value,
            igraph_vs_t reset_vids,
            igraph_real_t damping, igraph_bool_t directed,
            igraph_vs_t vids,
            igraph_pagerank_algo_t algo,
            igraph_arpack_options_t *options);

The personalized PageRank is similar to the original PageRank measure, but when the random walk is restarted, a new starting vertex is chosen according to a specified distribution. This distribution is used both when restarting randomly with probability `1 - damping`, and when the walker is forced to restart due to being stuck in a sink vertex (a vertex with no outgoing edges).

This simplified interface takes a vertex sequence and resets the random walk to one of the vertices in the specified vertex sequence, chosen uniformly. A typical application of personalized PageRank is when the random walk is reset to the same vertex every time: this can easily be achieved using `igraph_vss_1()` which generates a vertex sequence containing only a single vertex.

Note that the personalized PageRank of a given vertex depends on the personalized PageRank of all other vertices, so even if you want to calculate the personalized PageRank for only some of the vertices, all of them must be calculated. Requesting the personalized PageRank for only some of the vertices does not result in any performance increase at all.

Arguments:

`graph`: | The graph object.
`weights`: | Optional edge weights, it is either a null pointer, then the edges are not weighted, or a vector of the same length as the number of edges.
`vector`: | Pointer to an initialized vector, the result is stored here. It is resized as needed.
`value`: | Pointer to a real variable. When using `IGRAPH_PAGERANK_ALGO_ARPACK`, the eigenvalue corresponding to the PageRank vector is stored here. It is expected to be exactly one. Checking this value can be used to diagnose cases when ARPACK failed to converge to the leading eigenvector. When using `IGRAPH_PAGERANK_ALGO_PRPACK`, this is always set to 1.0.
`reset_vids`: | IDs of the vertices used when resetting the random walk. The walk will be restarted from a vertex in this set, chosen uniformly at random. Duplicate vertices are allowed.
`damping`: | The damping factor ("d" in the original paper). Must be a probability in the range [0, 1]. A commonly used value is 0.85.
`directed`: | Boolean, whether to consider the directedness of the edges. This is ignored for undirected graphs.
`vids`: | The vertex IDs for which the PageRank is returned. This parameter is only for convenience. Computing PageRank for fewer than all vertices will not speed up the calculation.
`algo`: | The PageRank implementation to use. Possible values: `IGRAPH_PAGERANK_ALGO_ARPACK`, `IGRAPH_PAGERANK_ALGO_PRPACK`.
`options`: | Options for the ARPACK method. See `igraph_arpack_options_t` for details. Supply `NULL` here to use the defaults. Note that the function overwrites the `n` (number of vertices), `nev` (1), `ncv` (3) and `which` (LM) parameters and it always starts the calculation from a non-random vector calculated based on the degree of the vertices.

Returns:

`` | Error code: `IGRAPH_ENOMEM`, not enough memory for temporary data. `IGRAPH_EINVVID`, invalid vertex ID in `vids` or an empty reset vertex sequence in `vids_reset`.

Time complexity: depends on the input graph, usually it is O(|E|), the number of edges.

See also:

`` | `igraph_pagerank()` for the non-personalized implementation.

### 11.9. `igraph_constraint` — Burt's constraint scores.

    igraph_error_t igraph_constraint(const igraph_t *graph, igraph_vector_t *res,
                          igraph_vs_t vids, const igraph_vector_t *weights);

This function calculates Burt's constraint scores for the given vertices, also known as structural holes.

Burt's constraint is higher if ego has less, or mutually stronger related (i.e. more redundant) contacts. Burt's measure of constraint, C[i], of vertex i's ego network V[i], is defined for directed and valued graphs,

> C[i] = sum( sum( (p[i,q] p[q,j])^2, q in V[i], q != i,j ), j in V[], j != i)

for a graph of order (i.e. number of vertices) N, where proportional tie strengths are defined as

> p[i,j]=(a[i,j]+a[j,i]) / sum(a[i,k]+a[k,i], k in V[i], k != i),

a[i,j] are elements of A and the latter being the graph adjacency matrix. For isolated vertices, constraint is undefined.

Burt, R.S. (2004). Structural holes and good ideas. American Journal of Sociology 110, 349-399.

The first R version of this function was contributed by Jeroen Bruggeman.

Arguments:

`graph`: | A graph object.
`res`: | Pointer to an initialized vector, the result will be stored here. The vector will be resized to have the appropriate size for holding the result.
`vids`: | Vertex selector containing the vertices for which the constraint should be calculated.
`weights`: | Vector giving the weights of the edges. If it is `NULL` then each edge is supposed to have the same weight.

Returns:

`` | Error code.

Time complexity: O(|V|+E|+n*d^2), n is the number of vertices for which the constraint is calculated and d is the average degree, |V| is the number of vertices, |E| the number of edges in the graph. If the weights argument is `NULL` then the time complexity is O(|V|+n*d^2).

### 11.10. `igraph_maxdegree` — The maximum degree in a graph (or set of vertices).

    igraph_error_t igraph_maxdegree(
        const igraph_t *graph, igraph_int_t *res, igraph_vs_t vids,
        igraph_neimode_t mode, igraph_loops_t loops
    );

The largest in-, out- or total degree of the specified vertices is calculated. If the graph has no vertices, or `vids` is empty, 0 is returned, as this is the smallest possible value for degrees.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an integer (`igraph_int_t`), the result will be stored here.
`vids`: | Vector giving the vertex IDs for which the maximum degree will be calculated.
`mode`: | Defines the type of the degree. `IGRAPH_OUT`, out-degree, `IGRAPH_IN`, in-degree, `IGRAPH_ALL`, total degree (sum of the in- and out-degree). This parameter is ignored for undirected graphs.
`loops`: | Specifies how to treat loop edges when calculating the degree. `IGRAPH_NO_LOOPS` ignores loop edges; `IGRAPH_LOOPS_ONCE` counts each loop edge only once; `IGRAPH_LOOPS_TWICE` counts each loop edge twice in undirected graphs and once in directed graphs.

Returns:

`` | Error code: `IGRAPH_EINVVID`: invalid vertex ID. `IGRAPH_EINVMODE`: invalid mode argument.

Time complexity: O(v) if `loops` is `true`, and O(v*d) otherwise. v is the number of vertices for which the degree will be calculated, and d is their (average) degree.

See also:

`` | `igraph_degree()` to retrieve the degrees for several vertices.

### 11.11. `igraph_strength` — Strength of the vertices, also called weighted vertex degree.

    igraph_error_t igraph_strength(
        const igraph_t *graph, igraph_vector_t *res, const igraph_vs_t vids,
        igraph_neimode_t mode, igraph_loops_t loops, const igraph_vector_t *weights
    );

In a weighted network the strength of a vertex is the sum of the weights of all incident edges. In a non-weighted network this is exactly the vertex degree.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an initialized vector, the result is stored here. It will be resized as needed.
`vids`: | The vertices for which the calculation is performed.
`mode`: | Gives whether to count only outgoing (`IGRAPH_OUT`), incoming (`IGRAPH_IN`) edges or both (`IGRAPH_ALL`). This parameter is ignored for undirected graphs.
`loops`: | Constant of type `igraph_loops_t`. Specifies how to treat loop edges when calculating the strength. `IGRAPH_NO_LOOPS` ignores loop edges; `IGRAPH_LOOPS_ONCE` counts each loop edge only once; `IGRAPH_LOOPS_TWICE` counts each loop edge twice in undirected graphs and once in directed graphs.
`weights`: | A vector giving the edge weights. If this is a `NULL` pointer, then `igraph_degree()` is called to perform the calculation.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), linear in the number vertices and edges.

See also:

`` | `igraph_degree()` for the traditional, non-weighted version.

### 11.12. `igraph_eigenvector_centrality` — Eigenvector centrality of the vertices.

    igraph_error_t igraph_eigenvector_centrality(const igraph_t *graph,
                                      igraph_vector_t *vector,
                                      igraph_real_t *value,
                                      igraph_neimode_t mode,
                                      const igraph_vector_t *weights,
                                      igraph_arpack_options_t *options);

Eigenvector centrality is a measure of the importance of a node in a network. It assigns relative scores to all nodes in the network based on the principle that connections from high-scoring nodes contribute more to the score of the node in question than equal connections from low-scoring nodes. Specifically, the eigenvector centrality of each vertex is proportional to the sum of eigenvector centralities of its neighbors. In practice, the centralities are determined by calculating the eigenvector corresponding to the largest positive eigenvalue of the adjacency matrix. This is motivated by the fact that the principal eigenvector is guaranteed to be non-negative, assuming that edge weights are also non-negative. In fact, in connected undirected graphs, this is the only non-negative eigenvector.

In the undirected case, this function considers the diagonal entries of the adjacency matrix to be twice the number of self-loops on the corresponding vertex.

In the weighted case, the eigenvector centrality of a vertex is proportional to the weighted sum of centralities of its neighbours, i.e. `c_j = sum_i w_ij c_i`, where `w_ij` is the weight of the edge connecting vertex `i` to `j`. The weights of parallel edges are added up.

The centrality scores returned by igraph are normalized such that the largest eigenvector centrality score is 1, unless all scores are zeros.

Eigenvector centrality is meaningful only for (strongly) connected graphs. Undirected graphs that are not connected should be decomposed into connected components, and the eigenvector centrality calculated for each separately. This function does not directly verify that the graph is connected. If it is not, in the undirected case the scores of all but one component will typically be zeros. When zeros are detected, a warning is issued.

Also note that the adjacency matrix of a directed acyclic graph or the adjacency matrix of an empty graph does not possess positive eigenvalues, therefore the eigenvector centrality is not meaningful for these graphs. igraph will return an eigenvalue of zero in such cases. The returned eigenvector centralities will all be equal for vertices with zero out-degree or zero in-degrees (depending on whether `mode` is `IGRAPH_OUT` or `IGRAPH_IN`) and zeros for other vertices. Such pathological cases can be detected by asking igraph to calculate the eigenvalue as well (using the `value` parameter, see below) and checking whether the eigenvalue is very close to zero.

Eigenvector centrality was developed for networks with non-negative edge weights. While igraph does not refuse to carry out the calculation with negative weights, it will issue a warning.

When working with directed graphs, consider using hub and authority scores instead, see `igraph_hub_and_authority_scores()`.

Arguments:

`graph`: | The input graph. It may be directed.
`vector`: | Pointer to an initialized vector, it will be resized as needed. The result of the computation is stored here. It can be a null pointer, then it is ignored.
`value`: | If not a null pointer, then the eigenvalue corresponding to the found eigenvector is stored here.

`mode`:

How to consider edge directions in directed graphs. It is ignored for undirected graphs. Possible values:

`IGRAPH_OUT` | the left eigenvector of the adjacency matrix is calculated, i.e. the centrality of a vertex is proportional to the sum of centralities of vertices pointing to it. This is the standard eigenvector centrality.
`IGRAPH_IN` | the right eigenvector of the adjacency matrix is calculated, i.e. the centrality of a vertex is proportional to the sum of centralities of vertices it points to.
`IGRAPH_ALL` | edge directions are ignored, and the unweighted eigenvector centrality is calculated.

`weights`: | A null pointer (indicating no edge weights), or a vector giving the weights of the edges. Weights should be positive to guarantee a meaningful result. The algorithm might produce complex numbers when some weights are negative and the graph is directed. In this case only the real part is reported.
`options`: | Options to ARPACK. See `igraph_arpack_options_t` for details. Supply `NULL` here to use the defaults. Note that the function overwrites the `n` (number of vertices) parameter and it always starts the calculation from a non-random vector calculated based on the degree of the vertices.

Returns:

`` | Error code.

Time complexity: depends on the input graph, usually it is O(|V|+|E|).

See also:

`` | `igraph_pagerank` and `igraph_personalized_pagerank` for modifications of eigenvector centrality. `igraph_hub_and_authority_scores()` for a similar pair of measures intended for directed graphs.

Example 17.18. File `examples/simple/eigenvector_centrality.c`

    #include <igraph.h>

    int main(void) {

        igraph_t graph;
        igraph_vector_t vector, weights;
        igraph_real_t value;

        /* Initialize the library. */
        igraph_setup();

        /* Create a star graph, with vertex 0 at the center, and associated edge weights. */
        igraph_star(&graph, 10, IGRAPH_STAR_UNDIRECTED, 0);
        igraph_vector_init_range(&weights, 1, igraph_ecount(&graph)+1);

        /* Initialize the vector where the result will be stored. */
        igraph_vector_init(&vector, 0);

        /* Compute eigenvector centrality. */
        igraph_eigenvector_centrality(&graph, &vector, &value, IGRAPH_OUT,
                                      &weights, /*options=*/ NULL);

        /* Print results. */
        printf("eigenvalue: %g\n", value);
        printf("eigenvector:\n");
        igraph_vector_print(&vector);

        /* Free allocated data structures. */
        igraph_vector_destroy(&vector);
        igraph_vector_destroy(&weights);
        igraph_destroy(&graph);

        return 0;
    }

### 11.13. `igraph_hub_and_authority_scores` — Kleinberg's hub and authority scores (HITS).

    igraph_error_t igraph_hub_and_authority_scores(const igraph_t *graph,
            igraph_vector_t *hub_vector, igraph_vector_t *authority_vector,
            igraph_real_t *value,
            const igraph_vector_t *weights, igraph_arpack_options_t *options);

Hub and authority scores are a generalization of the ideas behind eigenvector centrality to directed graphs. The authority score of a vertex is proportional to the sum of the hub scores of vertices that point to it. Conversely, the hub score of a vertex is proportional to the sum of authority scores of vertices that it points to. These concepts are also known under the name Hyperlink-Induced Topic Search (HITS).

The hub and authority scores of the vertices are defined as the principal eigenvectors of `A A^T` and `A^T A`, respectively, where `A` is the adjacency matrix of the graph and `A^T` is its transpose. The motivation for choosing the principal eigenvector is that it is guaranteed to be non-negative when edge weights are also non-negative.

If vectors `h` and `a` contain hub and authority scores, then the two scores are related by `h = A a` and `a = A^T h`. When the principal eigenvalue of `A A^T` is degenerate, there is no unique solution to the hub- and authority-score problem. igraph guarantees that the scores that are returned are matching, i.e. are related by these formulas, even in this situation.

Note that hub and authority scores are not well behaved in extremely sparse graphs where no single connected component dominates the undirected graphs corresponding to `A A^T` and `A^T A`. In these cases, there are many different non-negative eigenvectors, all reasonable solutions to the HITS equations. The symptom of such a situation is that a large fraction of the scores are zeros. igraph issues a warning when this is detected.

Results are scaled so that the largest hub and authority scores are both 1.

The concept of hub and authority scores were developed for directed graphs. In undirected graphs, both the hub and authority scores are equal to the eigenvector centrality, which can be computed using `igraph_eigenvector_centrality()`.

HITS scores were developed for networks with non-negative edge weights. While igraph does not refuse to carry out the calculation with negative weights, it will issue a warning.

See the following reference on the meaning of this score: J. Kleinberg. Authoritative sources in a hyperlinked environment. Proc. 9th ACM-SIAM Symposium on Discrete Algorithms, 1998. Extended version in Journal of the ACM 46 (1999). https://doi.org/10.1145/324133.324140 Also appears as IBM Research Report RJ 10076, May 1997.

Arguments:

`graph`: | The input graph. Can be directed and undirected.
`hub_vector`: | Pointer to an initialized vector, the hub scores are stored here. If a null pointer then it is ignored.
`authority_vector`: | Pointer to an initialized vector, the authority scores are stored here. If a null pointer then it is ignored.
`value`: | If not a null pointer then the eigenvalue corresponding to the calculated eigenvectors is stored here.
`weights`: | A null pointer (meaning no edge weights), or a vector giving the weights of the edges.
`options`: | Options to ARPACK. See `igraph_arpack_options_t` for details. Supply `NULL` here to use the defaults. Note that the function overwrites the `n` (number of vertices) parameter and it always starts the calculation from a vector calculated based on the degree of the vertices.

Returns:

`` | Error code.

Time complexity: depends on the input graph, usually it is O(|V|), the number of vertices.

See also:

`` | `igraph_pagerank()`, `igraph_personalized_pagerank()`; `igraph_eigenvector_centrality()` for a similar measure intended for undirected graphs.

### 11.14. `igraph_convergence_degree` — Calculates the convergence degree of each edge in a graph.

    igraph_error_t igraph_convergence_degree(const igraph_t *graph, igraph_vector_t *result,
                                  igraph_vector_t *ins, igraph_vector_t *outs);

Let us define the input set of an edge (i, j) as the set of vertices where the shortest paths passing through (i, j) originate, and similarly, let us defined the output set of an edge (i, j) as the set of vertices where the shortest paths passing through (i, j) terminate. The convergence degree of an edge is defined as the normalized value of the difference between the size of the input set and the output set, i.e. the difference of them divided by the sum of them. Convergence degrees are in the range (-1, 1); a positive value indicates that the edge is convergent since the shortest paths passing through it originate from a larger set and terminate in a smaller set, while a negative value indicates that the edge is divergent since the paths originate from a small set and terminate in a larger set.

Note that the convergence degree as defined above does not make sense in undirected graphs as there is no distinction between the input and output set. Therefore, for undirected graphs, the input and output sets of an edge are determined by orienting the edge arbitrarily while keeping the remaining edges undirected, and then taking the absolute value of the convergence degree.

Arguments:

`graph`: | The input graph, it can be either directed or undirected.
`result`: | Pointer to an initialized vector; the convergence degrees of each edge will be stored here. May be `NULL` if we are not interested in the exact convergence degrees.
`ins`: | Pointer to an initialized vector; the size of the input set of each edge will be stored here. May be `NULL` if we are not interested in the sizes of the input sets.
`outs`: | Pointer to an initialized vector; the size of the output set of each edge will be stored here. May be `NULL` if we are not interested in the sizes of the output sets.

Returns:

`` | Error code.

Time complexity: O(|V||E|), the number of vertices times the number of edges.

## 12. Range-limited centrality measures

### 12.1. `igraph_closeness_cutoff` — Range limited closeness centrality.

    igraph_error_t igraph_closeness_cutoff(const igraph_t *graph, igraph_vector_t *res,
                                igraph_vector_int_t *reachable_count, igraph_bool_t *all_reachable,
                                const igraph_vs_t vids, igraph_neimode_t mode,
                                const igraph_vector_t *weights,
                                igraph_bool_t normalized,
                                igraph_real_t cutoff);

This function computes a range-limited version of closeness centrality by considering only those shortest paths whose length is no greater then the given cutoff value.

Arguments:

`graph`: | The graph object.
`res`: | The result of the computation, a vector containing the range-limited closeness centrality scores for the given vertices.
`reachable_count`: | If not `NULL`, this vector will contain the number of vertices reachable within the cutoff distance from each vertex for which the range-limited closeness is calculated (not including that vertex).
`all_reachable`: | Pointer to a Boolean. If not `NULL`, it indicates if all vertices of the graph were reachable from each vertex in `vids` within the given cutoff distance.
`vids`: | The vertices for which the range limited closeness centrality will be computed.

`mode`:

The type of shortest paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the lengths of the outgoing paths are calculated.
`IGRAPH_IN` | the lengths of the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`weights`: | An optional vector containing edge weights for weighted closeness. No edge weight may be NaN. Supply a null pointer here for traditional, unweighted closeness.
`normalized`: | If true, the inverse of the mean distance to vertices reachable within the cutoff is returned. If false, the inverse of the sum of distances is returned.
`cutoff`: | The maximal length of paths that will be considered. If negative or `IGRAPH_UNLIMITED`, the exact closeness will be calculated (no upper limit on path lengths).

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: At most O(n|E|) for the unweighted case and O(n|E|log|V|+|V|) for the weighted case, where n is the number of vertices for which the calculation is done, |V| is the number of vertices and |E| is the number of edges in the graph. The timing decreases with smaller cutoffs in a way that depends on the graph structure.

See also:

`` | `igraph_closeness()` to calculate the exact closeness centrality.

### 12.2. `igraph_harmonic_centrality_cutoff` — Range limited harmonic centrality.

    igraph_error_t igraph_harmonic_centrality_cutoff(const igraph_t *graph, igraph_vector_t *res,
                                          const igraph_vs_t vids, igraph_neimode_t mode,
                                          const igraph_vector_t *weights,
                                          igraph_bool_t normalized,
                                          igraph_real_t cutoff);

This function computes the range limited version of harmonic centrality: only those shortest paths are considered whose length is not above the given cutoff. The inverse distance to vertices not reachable within the cutoff is considered to be zero.

Arguments:

`graph`: | The graph object.
`res`: | The result of the computation, a vector containing the range limited harmonic centrality scores for the given vertices.
`vids`: | The vertices for which the harmonic centrality will be computed.

`mode`:

The type of shortest paths to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the lengths of the outgoing paths are calculated.
`IGRAPH_IN` | the lengths of the incoming paths are calculated.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`weights`: | An optional vector containing edge weights for weighted harmonic centrality. No edge weight may be NaN. If `NULL`, all weights are considered to be one.
`normalized`: | Boolean, whether to normalize the result. If true, the result is the mean inverse path length to other vertices. i.e. it is normalized by the number of vertices minus one. If false, the result is the sum of inverse path lengths to other vertices.
`cutoff`: | The maximal length of paths that will be considered. The inverse distance to vertices that are not reachable within the cutoff path length is considered to be zero. Supply a negative value to compute the exact harmonic centrality, without any upper limit on the length of paths.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: At most O(n|E|) for the unweighted case and O(n|E|log|V|+|V|) for the weighted case, where n is the number of vertices for which the calculation is done, |V| is the number of vertices and |E| is the number of edges in the graph. The timing decreases with smaller cutoffs in a way that depends on the graph structure.

See also:

`` | `igraph_harmonic_centrality()` to calculate the exact harmonic centrality. Other centrality types: `igraph_closeness()`, `igraph_betweenness()`.

### 12.3. `igraph_betweenness_cutoff` — Range-limited betweenness centrality.

    igraph_error_t igraph_betweenness_cutoff(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *res,
            igraph_vs_t vids,
            igraph_bool_t directed, igraph_bool_t normalized,
            igraph_real_t cutoff);

This function computes a range-limited version of betweenness centrality by considering only those shortest paths whose length is no greater then the given cutoff value.

Arguments:

`graph`: | The graph object.
`weights`: | An optional vector containing edge weights for calculating weighted betweenness. No edge weight may be NaN. Supply a null pointer here for unweighted betweenness.
`res`: | The result of the computation, a vector containing the range-limited betweenness scores for the specified vertices.
`vids`: | The vertices for which the range-limited betweenness centrality scores will be returned. This paramerer is for convenience only and does not affect performance. Internally, the betewenness of all vertices is calculated.
`directed`: | If true directed paths will be considered for directed graphs. It is ignored for undirected graphs.
`normalized`: | Whether to normalize betweenness scores by the number of vertex pairs. In directed graphs, the number of ordered vertex pairs, in undirected graphs the number of unordered vertex pairs is used.
`cutoff`: | The maximal length of paths that will be considered. If negative or `IGRAPH_UNLIMITED`, the exact betweenness will be calculated, and there will be no upper limit on path lengths.

Returns:

`` | Error code: `IGRAPH_ENOMEM`, not enough memory for temporary data. `IGRAPH_EINVVID`, invalid vertex ID passed in `vids`.

Time complexity: O(|V||E|), |V| and |E| are the number of vertices and edges in the graph. Note that the time complexity is independent of the number of vertices for which the score is calculated.

See also:

`` | `igraph_betweenness()` to calculate the exact betweenness and `igraph_edge_betweenness_cutoff()` to calculate the range-limited edge betweenness.

### 12.4. `igraph_edge_betweenness_cutoff` — Range-limited betweenness centrality of the edges.

    igraph_error_t igraph_edge_betweenness_cutoff(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *res,
            igraph_es_t eids,
            igraph_bool_t directed, igraph_bool_t normalized,
            igraph_real_t cutoff);

This function computes a range-limited version of edge betweenness centrality by considering only those shortest paths whose length is no greater then the given cutoff value.

Arguments:

`graph`: | The graph object.
`weights`: | An optional weight vector for weighted betweenness. No edge weight may be NaN. Supply a null pointer here for unweighted betweenness.
`res`: | The result of the computation, vector containing the betweenness scores for the edges.
`eids`: | The edges for which the betweenness centrality will be returned. This parameter is for convenience only, and does not affect performance. Internally, the betweenness is be calculated for all edges.
`directed`: | If true directed paths will be considered for directed graphs. It is ignored for undirected graphs.
`normalized`: | Whether to normalize betweenness scores by the number of vertex pairs. In directed graphs, the number of ordered vertex pairs, in undirected graphs the number of unordered vertex pairs is used.
`cutoff`: | The maximal length of paths that will be considered. If negative of `IGRAPH_UNLIMITED`, the exact betweenness will be calculated (no upper limit on path lengths).

Returns:

`` | Error code: `IGRAPH_ENOMEM`, not enough memory for temporary data.

Time complexity: O(|V||E|), |V| and |E| are the number of vertices and edges in the graph.

See also:

`` | `igraph_edge_betweenness()` to compute the exact edge betweenness and `igraph_betweenness_cutoff()` to compute the range-limited vertex betweenness.

## 13. Subset-limited centrality measures

### 13.1. `igraph_betweenness_subset` — Betweenness centrality for a subset of source and target vertices.

    igraph_error_t igraph_betweenness_subset(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *res,
            igraph_vs_t sources, igraph_vs_t targets,
            igraph_vs_t vids,
            igraph_bool_t directed, igraph_bool_t normalized);

This function computes the subset-limited version of betweenness centrality by considering only those shortest paths that lie between vertices in a given source and target subset.

Arguments:

`graph`: | The graph object.
`weights`: | An optional vector containing edge weights for calculating weighted betweenness. No edge weight may be NaN. Supply a null pointer here for unweighted betweenness.
`res`: | The result of the computation, a vector containing the betweenness score for the subset of vertices.
`sources`: | A vertex selector for the sources of the shortest paths taken into considuration in the betweenness calculation.
`targets`: | A vertex selector for the targets of the shortest paths taken into considuration in the betweenness calculation.
`vids`: | The vertices for which the subset-limited betweenness centrality scores will be computed.
`directed`: | If true directed paths will be considered for directed graphs. It is ignored for undirected graphs.
`normalized`: | Whether to normalize betweenness scores. Normalization is currently unimplemented, and setting this to `true` raises an error.

Returns:

`` | Error code: `IGRAPH_ENOMEM`, not enough memory for temporary data. `IGRAPH_EINVVID`, invalid vertex ID passed in `vids`, `sources` or `targets`

Time complexity: O(|S||E|), where |S| is the number of vertices in the subset and |E| is the number of edges in the graph.

See also:

`` | `igraph_betweenness()` to calculate the exact vertex betweenness and `igraph_betweenness_cutoff()` to calculate the range-limited vertex betweenness.

### 13.2. `igraph_edge_betweenness_subset` — Edge betweenness centrality for a subset of source and target vertices.

    igraph_error_t igraph_edge_betweenness_subset(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *res,
            igraph_vs_t sources, igraph_vs_t targets,
            igraph_es_t eids,
            igraph_bool_t directed, igraph_bool_t normalized);

This function computes the subset-limited version of edge betweenness centrality by considering only those shortest paths that lie between vertices in a given source and target subset.

Arguments:

`graph`: | The graph object.
`weights`: | An optional weight vector for weighted betweenness. No edge weight may be NaN. Supply a null pointer here for unweighted betweenness.
`res`: | The result of the computation, vector containing the betweenness scores for the edges.
`sources`: | A vertex selector for the sources of the shortest paths taken into considuration in the betweenness calculation.
`targets`: | A vertex selector for the targets of the shortest paths taken into considuration in the betweenness calculation.
`eids`: | The edges for which the subset-limited betweenness centrality scores will be returned. This parameter is for convenience only. Internally, the betweenness will be calculated for all edges.
`directed`: | If true directed paths will be considered for directed graphs. It is ignored for undirected graphs.
`normalized`: | Whether to normalize betweenness scores. Normalization is currently unimplemented, and setting this to `true` raises an error.

Returns:

`` | Error code: `IGRAPH_ENOMEM`, not enough memory for temporary data. `IGRAPH_EINVVID`, invalid vertex ID passed in `sources` or `targets`

Time complexity: O(|S||E|), where |S| is the number of vertices in the subset and |E| is the number of edges in the graph.

See also:

`` | `igraph_edge_betweenness()` to compute the exact edge betweenness and `igraph_edge_betweenness_cutoff()` to compute the range-limited edge betweenness.

## 14. Centralization

### 14.1. `igraph_centralization` — Calculate the centralization score from the node level scores.

    igraph_real_t igraph_centralization(const igraph_vector_t *scores,
                                        igraph_real_t theoretical_max,
                                        igraph_bool_t normalized);

For a centrality score defined on the vertices of a graph, it is possible to define a graph level centralization index, by calculating the sum of the deviations from the maximum centrality score. Consequently, the higher the centralization index of the graph, the more centralized the structure is.

In order to make graphs of different sizes comparable, the centralization index is usually normalized to a number between zero and one, by dividing the (unnormalized) centralization score of the most centralized structure with the same number of vertices.

For most centrality indices, the most centralized structure is the star graph, a single center connected to all other nodes in the network. There is some variation depending on whether the graph is directed or not, whether loop edges are allowed, etc.

This function simply calculates the graph level index, if the node level scores and the theoretical maximum are given. It is called by all the measure-specific centralization functions. It uses the calculation

`C = sum_v ((max_u c_u) - c_v)`

where `c` are the centrality scores passed in `scores`. If `normalized` is `true`, then `C/theoretical_max` is returned.

Arguments:

`scores`: | A vector containing the node-level centrality scores.
`theoretical_max`: | The graph level centrality score of the most centralized graph with the same number of vertices. Only used if `normalized` set to true.
`normalized`: | Boolean, whether to normalize the centralization by dividing the supplied theoretical maximum.

Returns:

`` | The graph level index.

See also:

`` | `igraph_centralization_degree()`, `igraph_centralization_betweenness()`, `igraph_centralization_closeness()`, and `igraph_centralization_eigenvector_centrality()` for specific centralization functions.

Time complexity: O(n), the length of the score vector.

Example 17.19. File `examples/simple/centralization.c`

    #include <igraph.h>

    int main(void) {

        igraph_t graph;
        igraph_real_t cent;

        /* Initialize the library. */
        igraph_setup();

        /* Create an undirected star graph, which is the most centralized graph
         * with several common centrality scores. */
        printf("undirected star graph:\n");
        igraph_star(&graph, 10, IGRAPH_STAR_UNDIRECTED, /*center=*/ 0);

        igraph_centralization_degree(&graph, /*res=*/ NULL,
                                     /*mode=*/ IGRAPH_ALL, IGRAPH_NO_LOOPS,
                                     &cent, /*theoretical_max=*/ NULL,
                                     /*normalized=*/ true);
        printf("degree centralization: %g\n", cent);

        igraph_centralization_betweenness(&graph, /*res=*/ NULL,
                                          IGRAPH_UNDIRECTED, &cent,
                                          /*theoretical_max=*/ NULL,
                                          /*normalized=*/ true);
        printf("betweenness centralization: %g\n", cent);

        igraph_centralization_closeness(&graph, /*res=*/ NULL,
                                        IGRAPH_ALL, &cent,
                                        /*theoretical_max=*/ NULL,
                                        /*normalized=*/ true);
        printf("closeness centralization: %g\n", cent);

        igraph_destroy(&graph);

        /* With eigenvector centrality, the most centralized structure is
         * a graph containing a single edge. */
        printf("\ngraph with single edge:\n");
        igraph_small(&graph, /*n=*/ 10, IGRAPH_UNDIRECTED,
                     0,1, -1);

        igraph_centralization_eigenvector_centrality(
                    &graph,
                    /*vector=*/ NULL,
                    /*value=*/ NULL,
                    /*mode=*/ IGRAPH_ALL,
                    /*options=*/ NULL,
                    &cent,
                    /*theoretical_max=*/ NULL,
                    /*normalized=*/ true);
        printf("eigenvector centralization: %g\n", cent);

        igraph_destroy(&graph);

        return 0;
    }

### 14.2. `igraph_centralization_degree` — Calculate vertex degree and graph centralization.

    igraph_error_t igraph_centralization_degree(
        const igraph_t *graph, igraph_vector_t *res, igraph_neimode_t mode,
        igraph_loops_t loops, igraph_real_t *centralization,
        igraph_real_t *theoretical_max, igraph_bool_t normalized
    );

This function calculates the degree of the vertices by passing its arguments to `igraph_degree()`; and it calculates the graph level centralization index based on the results by calling `igraph_centralization()`.

Arguments:

`graph`: | The input graph.
`res`: | A vector if you need the node-level degree scores, or a null pointer otherwise.
`mode`: | Constant the specifies the type of degree for directed graphs. Possible values: `IGRAPH_IN`, `IGRAPH_OUT` and `IGRAPH_ALL`. This argument is ignored for undirected graphs.
`loops`: | Specifies how to treat loop edges when calculating the degree (and the centralization). `IGRAPH_NO_LOOPS` ignores loop edges; `IGRAPH_LOOPS_ONCE` counts each loop edge only once; `IGRAPH_LOOPS_TWICE` counts each loop edge twice in undirected graphs and once in directed graphs.
`centralization`: | Pointer to a real number, the centralization score is placed here.
`theoretical_max`: | Pointer to real number or a null pointer. If not a null pointer, then the theoretical maximum graph centrality score for a graph with the same number vertices is stored here.
`normalized`: | Boolean, whether to calculate a normalized centralization score. See `igraph_centralization()` for how the normalization is done.

Returns:

`` | Error code.

See also:

`` | `igraph_centralization()`, `igraph_degree()`.

Time complexity: the complexity of `igraph_degree()` plus O(n), the number of vertices queried, for calculating the centralization score.

### 14.3. `igraph_centralization_betweenness` — Calculate vertex betweenness and graph centralization.

    igraph_error_t igraph_centralization_betweenness(const igraph_t *graph,
                                          igraph_vector_t *res,
                                          igraph_bool_t directed,
                                          igraph_real_t *centralization,
                                          igraph_real_t *theoretical_max,
                                          igraph_bool_t normalized);

This function calculates the betweenness centrality of the vertices by passing its arguments to `igraph_betweenness()`; and it calculates the graph level centralization index based on the results by calling `igraph_centralization()`.

Arguments:

`graph`: | The input graph.
`res`: | A vector if you need the node-level betweenness scores, or a null pointer otherwise.
`directed`: | Boolean, whether to consider directed paths when calculating betweenness.
`centralization`: | Pointer to a real number, the centralization score is placed here.
`theoretical_max`: | Pointer to real number or a null pointer. If not a null pointer, then the theoretical maximum graph centrality score for a graph with the same number vertices is stored here.
`normalized`: | Boolean, whether to calculate a normalized centralization score. See `igraph_centralization()` for how the normalization is done.

Returns:

`` | Error code.

See also:

`` | `igraph_centralization()`, `igraph_betweenness()`.

Time complexity: the complexity of `igraph_betweenness()` plus O(n), the number of vertices queried, for calculating the centralization score.

### 14.4. `igraph_centralization_closeness` — Calculate vertex closeness and graph centralization.

    igraph_error_t igraph_centralization_closeness(const igraph_t *graph,
                                        igraph_vector_t *res,
                                        igraph_neimode_t mode,
                                        igraph_real_t *centralization,
                                        igraph_real_t *theoretical_max,
                                        igraph_bool_t normalized);

This function calculates the closeness centrality of the vertices by passing its arguments to `igraph_closeness()`; and it calculates the graph level centralization index based on the results by calling `igraph_centralization()`.

Arguments:

`graph`: | The input graph.
`res`: | A vector if you need the node-level closeness scores, or a null pointer otherwise.
`mode`: | Constant the specifies the type of closeness for directed graphs. Possible values: `IGRAPH_IN`, `IGRAPH_OUT` and `IGRAPH_ALL`. This argument is ignored for undirected graphs. See `igraph_closeness()` argument with the same name for more.
`centralization`: | Pointer to a real number, the centralization score is placed here.
`theoretical_max`: | Pointer to real number or a null pointer. If not a null pointer, then the theoretical maximum graph centrality score for a graph with the same number vertices is stored here.
`normalized`: | Boolean, whether to calculate a normalized centralization score. See `igraph_centralization()` for how the normalization is done.

Returns:

`` | Error code.

See also:

`` | `igraph_centralization()`, `igraph_closeness()`.

Time complexity: the complexity of `igraph_closeness()` plus O(n), the number of vertices queried, for calculating the centralization score.

### 14.5. `igraph_centralization_eigenvector_centrality` — Calculate eigenvector centrality scores and graph centralization.

    igraph_error_t igraph_centralization_eigenvector_centrality(
        const igraph_t *graph,
        igraph_vector_t *vector,
        igraph_real_t *value,
        igraph_neimode_t mode,
        igraph_arpack_options_t *options,
        igraph_real_t *centralization,
        igraph_real_t *theoretical_max,
        igraph_bool_t normalized);

This function calculates the eigenvector centrality of the vertices by passing its arguments to `igraph_eigenvector_centrality()`; and it calculates the graph level centralization index based on the results by calling `igraph_centralization()`.

Note that vertex-level eigenvector centrality scores do not have a natural scale. As with any eigenvector, their interpretation is invariant to scaling by a constant factor. However, due to how graph-level centralization is defined, its value depends on the specific scale/normalization used for vertex-level scores. Which of two graphs will have a higher eigenvector centralization depends on the choice of normalization for centralities. This function makes the specific choice of scaling vertex-level centrality scores by their maximum (i.e. it uses the ∞-norm). Other normalization choices, such as the 1-norm or 2-norm are not currently implemented.

Arguments:

`graph`: | The input graph.
`vector`: | A vector if you need the node-level eigenvector centrality scores, or a null pointer otherwise.
`value`: | If not a null pointer, then the leading eigenvalue is stored here.
`mode`: | How to consider edge directions in directed graphs. See `igraph_eigenvector_centrality()` for details. Ignored for directed graphs.
`options`: | Options to ARPACK. See `igraph_arpack_options_t` for details. Note that the function overwrites the `n` (number of vertices) parameter and it always starts the calculation from a non-random vector calculated based on the degree of the vertices.
`centralization`: | Pointer to a real number, the centralization score is placed here.
`theoretical_max`: | Pointer to real number or a null pointer. If not a null pointer, then the theoretical maximum graph centrality score for a graph with the same number vertices is stored here.
`normalized`: | Boolean, whether to calculate a normalized centralization score. See `igraph_centralization()` for how the normalization is done.

Returns:

`` | Error code.

See also:

`` | `igraph_centralization()`, `igraph_eigenvector_centrality()`.

Time complexity: the complexity of `igraph_eigenvector_centrality()` plus O(|V|), the number of vertices for the calculating the centralization.

### 14.6. `igraph_centralization_degree_tmax` — Theoretical maximum for graph centralization based on degree.

    igraph_error_t igraph_centralization_degree_tmax(
        const igraph_t *graph, igraph_int_t nodes, igraph_neimode_t mode,
        igraph_loops_t loops, igraph_real_t *res
    );

This function returns the theoretical maximum graph centrality based on vertex degree.

There are two ways to call this function, the first is to supply a graph as the `graph` argument, and then the number of vertices is taken from this object, and its directedness is considered as well. The `nodes` argument is ignored in this case. The `mode` argument is also ignored if the supplied graph is undirected.

The other way is to supply a null pointer as the `graph` argument. In this case the `nodes` and `mode` arguments are considered.

The most centralized structure is the star. More specifically, for undirected graphs it is the star, for directed graphs it is the in-star or the out-star.

Arguments:

`graph`: | A graph object or a null pointer, see the description above.
`nodes`: | The number of nodes. This is ignored if the `graph` argument is not a null pointer.
`mode`: | Constant, whether the calculation is based on in-degree (`IGRAPH_IN`), out-degree (`IGRAPH_OUT`) or total degree (`IGRAPH_ALL`). This is ignored if the `graph` argument is not a null pointer and the given graph is undirected.
`loops`: | Specifies how to treat loop edges when calculating the degree (and the centralization). `IGRAPH_NO_LOOPS` ignores loop edges; `IGRAPH_LOOPS_ONCE` counts each loop edge only once; `IGRAPH_LOOPS_TWICE` counts each loop edge twice in undirected graphs and once in directed graphs.
`res`: | Pointer to a real variable, the result is stored here.

Returns:

`` | Error code.

Time complexity: O(1).

See also:

`` | `igraph_centralization_degree()` and `igraph_centralization()`.

### 14.7. `igraph_centralization_betweenness_tmax` — Theoretical maximum for graph centralization based on betweenness.

    igraph_error_t igraph_centralization_betweenness_tmax(const igraph_t *graph,
            igraph_int_t nodes,
            igraph_bool_t directed,
            igraph_real_t *res);

This function returns the theoretical maximum graph centrality based on vertex betweenness.

There are two ways to call this function, the first is to supply a graph as the `graph` argument, and then the number of vertices is taken from this object, and its directedness is considered as well. The `nodes` argument is ignored in this case. The `directed` argument is also ignored if the supplied graph is undirected.

The other way is to supply a null pointer as the `graph` argument. In this case the `nodes` and `directed` arguments are considered.

The most centralized structure is the star.

Arguments:

`graph`: | A graph object or a null pointer, see the description above.
`nodes`: | The number of nodes. This is ignored if the `graph` argument is not a null pointer.
`directed`: | Boolean, whether to use directed paths in the betweenness calculation. This argument is ignored if `graph` is not a null pointer and it is undirected.
`res`: | Pointer to a real variable, the result is stored here.

Returns:

`` | Error code.

Time complexity: O(1).

See also:

`` | `igraph_centralization_betweenness()` and `igraph_centralization()`.

### 14.8. `igraph_centralization_closeness_tmax` — Theoretical maximum for graph centralization based on closeness.

    igraph_error_t igraph_centralization_closeness_tmax(const igraph_t *graph,
            igraph_int_t nodes,
            igraph_neimode_t mode,
            igraph_real_t *res);

This function returns the theoretical maximum graph centrality based on vertex closeness.

There are two ways to call this function, the first is to supply a graph as the `graph` argument, and then the number of vertices is taken from this object, and its directedness is considered as well. The `nodes` argument is ignored in this case. The `mode` argument is also ignored if the supplied graph is undirected.

The other way is to supply a null pointer as the `graph` argument. In this case the `nodes` and `mode` arguments are considered.

The most centralized structure is the star.

Arguments:

`graph`: | A graph object or a null pointer, see the description above.
`nodes`: | The number of nodes. This is ignored if the `graph` argument is not a null pointer.
`mode`: | Constant, specifies what kind of distances to consider to calculate closeness. See the `mode` argument of `igraph_closeness()` for details. This argument is ignored if `graph` is not a null pointer and it is undirected.
`res`: | Pointer to a real variable, the result is stored here.

Returns:

`` | Error code.

Time complexity: O(1).

See also:

`` | `igraph_centralization_closeness()` and `igraph_centralization()`.

### 14.9. `igraph_centralization_eigenvector_centrality_tmax` — Theoretical maximum centralization for eigenvector centrality.

    igraph_error_t igraph_centralization_eigenvector_centrality_tmax(
        const igraph_t *graph,
        igraph_int_t nodes,
        igraph_neimode_t mode,
        igraph_real_t *res);

This function returns the theoretical maximum graph centrality based on vertex eigenvector centrality.

There are two ways to call this function, the first is to supply a graph as the `graph` argument, and then the number of vertices is taken from this object, and its directedness is considered as well. The `nodes` argument is ignored in this case. The `mode` argument is also ignored if the supplied graph is undirected.

The other way is to supply a null pointer as the `graph`. argument. In this case the `nodes` and `mode` arguments are considered.

The most centralized directed structure is the in-star with `mode` set to `IGRAPH_OUT`, and the out-star with `mode` set to `IGRAPH_IN`. The most centralized undirected structure is the graph with a single edge.

Arguments:

`graph`: | A graph object or a null pointer, see the description above.
`nodes`: | The number of nodes. This is ignored if the `graph` argument is not a null pointer.
`mode`: | How to consider edge directions in directed graphs. See `igraph_eigenvector_centrality()` for details. This argument is ignored if `graph` is not a null pointer and it is undirected.
`res`: | Pointer to a real variable, the result is stored here.

Returns:

`` | Error code.

Time complexity: O(1).

See also:

`` | `igraph_centralization_closeness()` and `igraph_centralization()`.

## 15. Similarity measures

### 15.1. `igraph_bibcoupling` — Bibliographic coupling.

    igraph_error_t igraph_bibcoupling(const igraph_t *graph, igraph_matrix_t *res,
                           const igraph_vs_t vids);

The bibliographic coupling of two vertices is the number of other vertices they both cite, `igraph_bibcoupling()` calculates this. The bibliographic coupling score for each given vertex and all other vertices in the graph will be calculated.

Arguments:

`graph`: | The graph object to analyze.
`res`: | Pointer to a matrix, the result of the calculation will be stored here. The number of its rows is the same as the number of vertex IDs in `vids`, the number of columns is the number of vertices in the graph.
`vids`: | The vertex IDs of the vertices for which the calculation will be done.

Returns:

`` | Error code: `IGRAPH_EINVVID`: invalid vertex ID.

Time complexity: O(|V|d^2), |V| is the number of vertices in the graph, d is the (maximum) degree of the vertices in the graph.

See also:

`` | `igraph_cocitation()`

Example 17.20. File `examples/simple/igraph_cocitation.c`

    #include <igraph.h>
    #include <stdio.h>

    int main(void) {
        igraph_t graph;
        igraph_matrix_t matrix;

        /* Initialize the library. */
        igraph_setup();

        /* Create a small test graph. */
        igraph_small(&graph, 0, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 0, 3, 0,
                     -1);

        /* As usual with igraph functions, the data structure in which the result
           will be returned must be initialized in advance. */
        igraph_matrix_init(&matrix, 0, 0);
        igraph_bibcoupling(&graph, &matrix, igraph_vss_all());
        printf("Bibliographic coupling matrix:\n");
        igraph_matrix_print(&matrix);

        igraph_cocitation(&graph, &matrix, igraph_vss_all());
        printf("\nCocitation matrix:\n");
        igraph_matrix_print(&matrix);

        /* Destroy data structures when we are done with them. */
        igraph_matrix_destroy(&matrix);
        igraph_destroy(&graph);

        return 0;
    }

### 15.2. `igraph_cocitation` — Cocitation coupling.

    igraph_error_t igraph_cocitation(const igraph_t *graph, igraph_matrix_t *res,
                          const igraph_vs_t vids);

Two vertices are cocited if there is another vertex citing both of them. `igraph_cocitation()` simply counts how many times two vertices are cocited. The cocitation score for each given vertex and all other vertices in the graph will be calculated.

Arguments:

`graph`: | The graph object to analyze.
`res`: | Pointer to a matrix, the result of the calculation will be stored here. The number of its rows is the same as the number of vertex IDs in `vids`, the number of columns is the number of vertices in the graph.
`vids`: | The vertex IDs of the vertices for which the calculation will be done.

Returns:

`` | Error code: `IGRAPH_EINVVID`: invalid vertex ID.

Time complexity: O(|V|d^2), |V| is the number of vertices in the graph, d is the (maximum) degree of the vertices in the graph.

See also:

`` | `igraph_bibcoupling()`

Example 17.21. File `examples/simple/igraph_cocitation.c`

    #include <igraph.h>
    #include <stdio.h>

    int main(void) {
        igraph_t graph;
        igraph_matrix_t matrix;

        /* Initialize the library. */
        igraph_setup();

        /* Create a small test graph. */
        igraph_small(&graph, 0, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 0, 3, 0,
                     -1);

        /* As usual with igraph functions, the data structure in which the result
           will be returned must be initialized in advance. */
        igraph_matrix_init(&matrix, 0, 0);
        igraph_bibcoupling(&graph, &matrix, igraph_vss_all());
        printf("Bibliographic coupling matrix:\n");
        igraph_matrix_print(&matrix);

        igraph_cocitation(&graph, &matrix, igraph_vss_all());
        printf("\nCocitation matrix:\n");
        igraph_matrix_print(&matrix);

        /* Destroy data structures when we are done with them. */
        igraph_matrix_destroy(&matrix);
        igraph_destroy(&graph);

        return 0;
    }

### 15.3. `igraph_similarity_jaccard` — Jaccard similarity coefficient for the given vertices.

    igraph_error_t igraph_similarity_jaccard(const igraph_t *graph, igraph_matrix_t *res,
                                  const igraph_vs_t from, const igraph_vs_t to, igraph_neimode_t mode, igraph_bool_t loops);

The Jaccard similarity coefficient of two vertices is the number of common neighbors divided by the number of vertices that are neighbors of at least one of the two vertices being considered. This function calculates the pairwise Jaccard similarities for some (or all) of the vertices.

Arguments:

`graph`: | The graph object to analyze
`res`: | Pointer to a matrix, the result of the calculation will be stored here. The number of its rows and columns is the same as the number of vertex IDs in `from` and `to`, respectively.
`from`: | The vertex IDs of the first set of vertices of the pairs for which the calculation will be done.
`to`: | The vertex IDs of the second set of vertices of the pairs for which the calculation will be done.

`mode`:

The type of neighbors to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing edges will be considered for each node.
`IGRAPH_IN` | the incoming edges will be considered for each node.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`loops`: | Whether to include the vertices themselves in the neighbor sets.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(|V|^2 d), |V| is the number of vertices in the vertex iterator given, d is the (maximum) degree of the vertices in the graph.

See also:

`` | `igraph_similarity_dice()`, a measure very similar to the Jaccard coefficient

Example 17.22. File `examples/simple/igraph_similarity.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_matrix_t m;
        igraph_vector_int_t pairs;
        igraph_vector_t res;
        igraph_int_t i, j, n;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&g, 0, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 0, 3, 0,
                     -1);

        igraph_matrix_init(&m, 0, 0);
        igraph_vector_init(&res, 0);
        igraph_vector_int_init(&pairs, 0);

        n = igraph_vcount(&g);
        for (i = 0; i < n; i++) {
            for (j = n - 1; j >= 0; j--) {
                igraph_vector_int_push_back(&pairs, i);
                igraph_vector_int_push_back(&pairs, j);
            }
        }

        printf("Jaccard similarity:\n");
        igraph_similarity_jaccard(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nJaccard similarity, pairs:\n");
        igraph_similarity_jaccard_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nJaccard similarity with edge selector:\n");
        igraph_similarity_jaccard_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity:\n");
        igraph_similarity_dice(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nDice similarity, pairs:\n");
        igraph_similarity_dice_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity with edge selector:\n");
        igraph_similarity_dice_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nWeighted inverse log similarity:\n");
        igraph_similarity_inverse_log_weighted(&g, &m, igraph_vss_all(), IGRAPH_ALL);
        igraph_matrix_printf(&m, "%.2f");

        igraph_matrix_destroy(&m);
        igraph_destroy(&g);
        igraph_vector_destroy(&res);
        igraph_vector_int_destroy(&pairs);

        return 0;
    }

### 15.4. `igraph_similarity_jaccard_pairs` — Jaccard similarity coefficient for given vertex pairs.

    igraph_error_t igraph_similarity_jaccard_pairs(const igraph_t *graph, igraph_vector_t *res,
                                        const igraph_vector_int_t *pairs, igraph_neimode_t mode, igraph_bool_t loops);

The Jaccard similarity coefficient of two vertices is the number of common neighbors divided by the number of vertices that are neighbors of at least one of the two vertices being considered. This function calculates the pairwise Jaccard similarities for a list of vertex pairs.

Arguments:

`graph`: | The graph object to analyze
`res`: | Pointer to a vector, the result of the calculation will be stored here. The number of elements is the same as the number of pairs in `pairs`.
`pairs`: | A vector that contains the pairs for which the similarity will be calculated. Each pair is defined by two consecutive elements, i.e. the first and second element of the vector specifies the first pair, the third and fourth element specifies the second pair and so on.

`mode`:

The type of neighbors to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing edges will be considered for each node.
`IGRAPH_IN` | the incoming edges will be considered for each node.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`loops`: | Whether to include the vertices themselves in the neighbor sets.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(nd), n is the number of pairs in the given vector, d is the (maximum) degree of the vertices in the graph.

See also:

`` | `igraph_similarity_jaccard()` to calculate the Jaccard similarity between all pairs of a vertex set, or `igraph_similarity_dice()` and `igraph_similarity_dice_pairs()` for a measure very similar to the Jaccard coefficient

Example 17.23. File `examples/simple/igraph_similarity.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_matrix_t m;
        igraph_vector_int_t pairs;
        igraph_vector_t res;
        igraph_int_t i, j, n;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&g, 0, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 0, 3, 0,
                     -1);

        igraph_matrix_init(&m, 0, 0);
        igraph_vector_init(&res, 0);
        igraph_vector_int_init(&pairs, 0);

        n = igraph_vcount(&g);
        for (i = 0; i < n; i++) {
            for (j = n - 1; j >= 0; j--) {
                igraph_vector_int_push_back(&pairs, i);
                igraph_vector_int_push_back(&pairs, j);
            }
        }

        printf("Jaccard similarity:\n");
        igraph_similarity_jaccard(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nJaccard similarity, pairs:\n");
        igraph_similarity_jaccard_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nJaccard similarity with edge selector:\n");
        igraph_similarity_jaccard_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity:\n");
        igraph_similarity_dice(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nDice similarity, pairs:\n");
        igraph_similarity_dice_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity with edge selector:\n");
        igraph_similarity_dice_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nWeighted inverse log similarity:\n");
        igraph_similarity_inverse_log_weighted(&g, &m, igraph_vss_all(), IGRAPH_ALL);
        igraph_matrix_printf(&m, "%.2f");

        igraph_matrix_destroy(&m);
        igraph_destroy(&g);
        igraph_vector_destroy(&res);
        igraph_vector_int_destroy(&pairs);

        return 0;
    }

### 15.5. `igraph_similarity_jaccard_es` — Jaccard similarity coefficient for a given edge selector.

    igraph_error_t igraph_similarity_jaccard_es(const igraph_t *graph, igraph_vector_t *res,
                                     const igraph_es_t es, igraph_neimode_t mode, igraph_bool_t loops);

The Jaccard similarity coefficient of two vertices is the number of common neighbors divided by the number of vertices that are neighbors of at least one of the two vertices being considered. This function calculates the pairwise Jaccard similarities for the endpoints of edges in a given edge selector.

Arguments:

`graph`: | The graph object to analyze
`res`: | Pointer to a vector, the result of the calculation will be stored here. The number of elements is the same as the number of edges in `es`.
`es`: | An edge selector that specifies the edges to be included in the result.

`mode`:

The type of neighbors to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing edges will be considered for each node.
`IGRAPH_IN` | the incoming edges will be considered for each node.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`loops`: | Whether to include the vertices themselves in the neighbor sets.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(nd), n is the number of edges in the edge selector, d is the (maximum) degree of the vertices in the graph.

See also:

`` | `igraph_similarity_jaccard()` and `igraph_similarity_jaccard_pairs()` to calculate the Jaccard similarity between all pairs of a vertex set or some selected vertex pairs, or `igraph_similarity_dice()`, `igraph_similarity_dice_pairs()` and `igraph_similarity_dice_es()` for a measure very similar to the Jaccard coefficient

Example 17.24. File `examples/simple/igraph_similarity.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_matrix_t m;
        igraph_vector_int_t pairs;
        igraph_vector_t res;
        igraph_int_t i, j, n;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&g, 0, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 0, 3, 0,
                     -1);

        igraph_matrix_init(&m, 0, 0);
        igraph_vector_init(&res, 0);
        igraph_vector_int_init(&pairs, 0);

        n = igraph_vcount(&g);
        for (i = 0; i < n; i++) {
            for (j = n - 1; j >= 0; j--) {
                igraph_vector_int_push_back(&pairs, i);
                igraph_vector_int_push_back(&pairs, j);
            }
        }

        printf("Jaccard similarity:\n");
        igraph_similarity_jaccard(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nJaccard similarity, pairs:\n");
        igraph_similarity_jaccard_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nJaccard similarity with edge selector:\n");
        igraph_similarity_jaccard_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity:\n");
        igraph_similarity_dice(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nDice similarity, pairs:\n");
        igraph_similarity_dice_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity with edge selector:\n");
        igraph_similarity_dice_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nWeighted inverse log similarity:\n");
        igraph_similarity_inverse_log_weighted(&g, &m, igraph_vss_all(), IGRAPH_ALL);
        igraph_matrix_printf(&m, "%.2f");

        igraph_matrix_destroy(&m);
        igraph_destroy(&g);
        igraph_vector_destroy(&res);
        igraph_vector_int_destroy(&pairs);

        return 0;
    }

### 15.6. `igraph_similarity_dice` — Dice similarity coefficient.

    igraph_error_t igraph_similarity_dice(const igraph_t *graph, igraph_matrix_t *res,
                                          const igraph_vs_t from, const igraph_vs_t to,
                                          igraph_neimode_t mode, igraph_bool_t loops);

The Dice similarity coefficient of two vertices is twice the number of common neighbors divided by the sum of the degrees of the vertices. This function calculates the pairwise Dice similarities for some (or all) of the vertices.

Arguments:

`graph`: | The graph object to analyze.
`res`: | Pointer to a matrix, the result of the calculation will be stored here. The number of its rows and columns is the same as the number of vertex IDs in `from` and `to`, respectively.
`from`: | The vertex IDs of the first vertices of the pairs for which the calculation will be done.
`to`: | The vertex IDs of the second vertices of the pairs for which the calculation will be done.

`mode`:

The type of neighbors to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing edges will be considered for each node.
`IGRAPH_IN` | the incoming edges will be considered for each node.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`loops`: | Whether to include the vertices themselves as their own neighbors.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(|V|^2 d), where |V| is the number of vertices in the vertex iterator given, and d is the (maximum) degree of the vertices in the graph.

See also:

`` | `igraph_similarity_jaccard()`, a measure very similar to the Dice coefficient

Example 17.25. File `examples/simple/igraph_similarity.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_matrix_t m;
        igraph_vector_int_t pairs;
        igraph_vector_t res;
        igraph_int_t i, j, n;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&g, 0, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 0, 3, 0,
                     -1);

        igraph_matrix_init(&m, 0, 0);
        igraph_vector_init(&res, 0);
        igraph_vector_int_init(&pairs, 0);

        n = igraph_vcount(&g);
        for (i = 0; i < n; i++) {
            for (j = n - 1; j >= 0; j--) {
                igraph_vector_int_push_back(&pairs, i);
                igraph_vector_int_push_back(&pairs, j);
            }
        }

        printf("Jaccard similarity:\n");
        igraph_similarity_jaccard(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nJaccard similarity, pairs:\n");
        igraph_similarity_jaccard_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nJaccard similarity with edge selector:\n");
        igraph_similarity_jaccard_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity:\n");
        igraph_similarity_dice(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nDice similarity, pairs:\n");
        igraph_similarity_dice_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity with edge selector:\n");
        igraph_similarity_dice_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nWeighted inverse log similarity:\n");
        igraph_similarity_inverse_log_weighted(&g, &m, igraph_vss_all(), IGRAPH_ALL);
        igraph_matrix_printf(&m, "%.2f");

        igraph_matrix_destroy(&m);
        igraph_destroy(&g);
        igraph_vector_destroy(&res);
        igraph_vector_int_destroy(&pairs);

        return 0;
    }

### 15.7. `igraph_similarity_dice_pairs` — Dice similarity coefficient for given vertex pairs.

    igraph_error_t igraph_similarity_dice_pairs(const igraph_t *graph, igraph_vector_t *res,
                                     const igraph_vector_int_t *pairs, igraph_neimode_t mode, igraph_bool_t loops);

The Dice similarity coefficient of two vertices is twice the number of common neighbors divided by the sum of the degrees of the vertices. This function calculates the pairwise Dice similarities for a list of vertex pairs.

Arguments:

`graph`: | The graph object to analyze
`res`: | Pointer to a vector, the result of the calculation will be stored here. The number of elements is the same as the number of pairs in `pairs`.
`pairs`: | A vector that contains the pairs for which the similarity will be calculated. Each pair is defined by two consecutive elements, i.e. the first and second element of the vector specifies the first pair, the third and fourth element specifies the second pair and so on.

`mode`:

The type of neighbors to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing edges will be considered for each node.
`IGRAPH_IN` | the incoming edges will be considered for each node.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`loops`: | Whether to include the vertices themselves as their own neighbors.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(nd), n is the number of pairs in the given vector, d is the (maximum) degree of the vertices in the graph.

See also:

`` | `igraph_similarity_dice()` to calculate the Dice similarity between all pairs of a vertex set, or `igraph_similarity_jaccard()`, `igraph_similarity_jaccard_pairs()` and `igraph_similarity_jaccard_es()` for a measure very similar to the Dice coefficient

Example 17.26. File `examples/simple/igraph_similarity.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_matrix_t m;
        igraph_vector_int_t pairs;
        igraph_vector_t res;
        igraph_int_t i, j, n;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&g, 0, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 0, 3, 0,
                     -1);

        igraph_matrix_init(&m, 0, 0);
        igraph_vector_init(&res, 0);
        igraph_vector_int_init(&pairs, 0);

        n = igraph_vcount(&g);
        for (i = 0; i < n; i++) {
            for (j = n - 1; j >= 0; j--) {
                igraph_vector_int_push_back(&pairs, i);
                igraph_vector_int_push_back(&pairs, j);
            }
        }

        printf("Jaccard similarity:\n");
        igraph_similarity_jaccard(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nJaccard similarity, pairs:\n");
        igraph_similarity_jaccard_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nJaccard similarity with edge selector:\n");
        igraph_similarity_jaccard_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity:\n");
        igraph_similarity_dice(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nDice similarity, pairs:\n");
        igraph_similarity_dice_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity with edge selector:\n");
        igraph_similarity_dice_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nWeighted inverse log similarity:\n");
        igraph_similarity_inverse_log_weighted(&g, &m, igraph_vss_all(), IGRAPH_ALL);
        igraph_matrix_printf(&m, "%.2f");

        igraph_matrix_destroy(&m);
        igraph_destroy(&g);
        igraph_vector_destroy(&res);
        igraph_vector_int_destroy(&pairs);

        return 0;
    }

### 15.8. `igraph_similarity_dice_es` — Dice similarity coefficient for a given edge selector.

    igraph_error_t igraph_similarity_dice_es(const igraph_t *graph, igraph_vector_t *res,
                                  const igraph_es_t es, igraph_neimode_t mode, igraph_bool_t loops);

The Dice similarity coefficient of two vertices is twice the number of common neighbors divided by the sum of the degrees of the vertices. This function calculates the pairwise Dice similarities for the endpoints of edges in a given edge selector.

Arguments:

`graph`: | The graph object to analyze
`res`: | Pointer to a vector, the result of the calculation will be stored here. The number of elements is the same as the number of edges in `es`.
`es`: | An edge selector that specifies the edges to be included in the result.

`mode`:

The type of neighbors to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing edges will be considered for each node.
`IGRAPH_IN` | the incoming edges will be considered for each node.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation.

`loops`: | Whether to include the vertices themselves as their own neighbors.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | not enough memory for temporary data.
`IGRAPH_EINVVID` | invalid vertex ID passed.
`IGRAPH_EINVMODE` | invalid mode argument.

Time complexity: O(nd), n is the number of pairs in the given vector, d is the (maximum) degree of the vertices in the graph.

See also:

`` | `igraph_similarity_dice()` and `igraph_similarity_dice_pairs()` to calculate the Dice similarity between all pairs of a vertex set or some selected vertex pairs, or `igraph_similarity_jaccard()`, `igraph_similarity_jaccard_pairs()` and `igraph_similarity_jaccard_es()` for a measure very similar to the Dice coefficient

Example 17.27. File `examples/simple/igraph_similarity.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_matrix_t m;
        igraph_vector_int_t pairs;
        igraph_vector_t res;
        igraph_int_t i, j, n;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&g, 0, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 0, 3, 0,
                     -1);

        igraph_matrix_init(&m, 0, 0);
        igraph_vector_init(&res, 0);
        igraph_vector_int_init(&pairs, 0);

        n = igraph_vcount(&g);
        for (i = 0; i < n; i++) {
            for (j = n - 1; j >= 0; j--) {
                igraph_vector_int_push_back(&pairs, i);
                igraph_vector_int_push_back(&pairs, j);
            }
        }

        printf("Jaccard similarity:\n");
        igraph_similarity_jaccard(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nJaccard similarity, pairs:\n");
        igraph_similarity_jaccard_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nJaccard similarity with edge selector:\n");
        igraph_similarity_jaccard_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity:\n");
        igraph_similarity_dice(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nDice similarity, pairs:\n");
        igraph_similarity_dice_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity with edge selector:\n");
        igraph_similarity_dice_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nWeighted inverse log similarity:\n");
        igraph_similarity_inverse_log_weighted(&g, &m, igraph_vss_all(), IGRAPH_ALL);
        igraph_matrix_printf(&m, "%.2f");

        igraph_matrix_destroy(&m);
        igraph_destroy(&g);
        igraph_vector_destroy(&res);
        igraph_vector_int_destroy(&pairs);

        return 0;
    }

### 15.9. `igraph_similarity_inverse_log_weighted` — Vertex similarity based on the inverse logarithm of vertex degrees.

    igraph_error_t igraph_similarity_inverse_log_weighted(const igraph_t *graph,
            igraph_matrix_t *res, const igraph_vs_t vids, igraph_neimode_t mode);

The inverse log-weighted similarity of two vertices is the number of their common neighbors, weighted by the inverse logarithm of their degrees. It is based on the assumption that two vertices should be considered more similar if they share a low-degree common neighbor, since high-degree common neighbors are more likely to appear even by pure chance.

Isolated vertices will have zero similarity to any other vertex. Self-similarities are not calculated.

Note that the presence of loop edges may yield counter-intuitive results. A node with a loop edge is considered to be a neighbor of itself twice (because there are two edge stems incident on the node). Adding a loop edge to a node may decrease its similarity to other nodes, but it may also increase it. For instance, if nodes A and B are connected but share no common neighbors, their similarity is zero. However, if a loop edge is added to B, then B itself becomes a common neighbor of A and B and thus the similarity of A and B will be increased. Consider removing loop edges explicitly before invoking this function using `igraph_simplify()`.

See the following paper for more details: Lada A. Adamic and Eytan Adar: Friends and neighbors on the Web. Social Networks, 25(3):211-230, 2003. https://doi.org/10.1016/S0378-8733(03)00009-1

Arguments:

`graph`: | The graph object to analyze.
`res`: | Pointer to a matrix, the result of the calculation will be stored here. The number of its rows is the same as the number of vertex IDs in `vids`, the number of columns is the number of vertices in the graph.
`vids`: | The vertex IDs of the vertices for which the calculation will be done.

`mode`:

The type of neighbors to be used for the calculation in directed graphs. Possible values:

`IGRAPH_OUT` | the outgoing edges will be considered for each node. Nodes will be weighted according to their in-degree.
`IGRAPH_IN` | the incoming edges will be considered for each node. Nodes will be weighted according to their out-degree.
`IGRAPH_ALL` | the directed graph is considered as an undirected one for the computation. Every node is weighted according to its undirected degree.

Returns:

`` | Error code: `IGRAPH_EINVVID`: invalid vertex ID.

Time complexity: O(|V|d^2), |V| is the number of vertices in the graph, d is the (maximum) degree of the vertices in the graph.

Example 17.28. File `examples/simple/igraph_similarity.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_matrix_t m;
        igraph_vector_int_t pairs;
        igraph_vector_t res;
        igraph_int_t i, j, n;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&g, 0, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 0, 3, 0,
                     -1);

        igraph_matrix_init(&m, 0, 0);
        igraph_vector_init(&res, 0);
        igraph_vector_int_init(&pairs, 0);

        n = igraph_vcount(&g);
        for (i = 0; i < n; i++) {
            for (j = n - 1; j >= 0; j--) {
                igraph_vector_int_push_back(&pairs, i);
                igraph_vector_int_push_back(&pairs, j);
            }
        }

        printf("Jaccard similarity:\n");
        igraph_similarity_jaccard(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nJaccard similarity, pairs:\n");
        igraph_similarity_jaccard_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nJaccard similarity with edge selector:\n");
        igraph_similarity_jaccard_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity:\n");
        igraph_similarity_dice(&g, &m, igraph_vss_range(1, 3), igraph_vss_range(1, 3), IGRAPH_ALL, IGRAPH_NO_LOOPS);
        igraph_matrix_printf(&m, "%.2f");

        printf("\nDice similarity, pairs:\n");
        igraph_similarity_dice_pairs(&g, &res, &pairs, IGRAPH_ALL, 0);
        igraph_vector_print(&res);

        printf("\nDice similarity with edge selector:\n");
        igraph_similarity_dice_es(&g, &res, igraph_ess_all(IGRAPH_EDGEORDER_FROM), IGRAPH_IN, 0);
        igraph_vector_print(&res);

        printf("\nWeighted inverse log similarity:\n");
        igraph_similarity_inverse_log_weighted(&g, &m, igraph_vss_all(), IGRAPH_ALL);
        igraph_matrix_printf(&m, "%.2f");

        igraph_matrix_destroy(&m);
        igraph_destroy(&g);
        igraph_vector_destroy(&res);
        igraph_vector_int_destroy(&pairs);

        return 0;
    }

## 16. Trees and forests

### 16.1. `igraph_minimum_spanning_tree` — Calculates a minimum spanning tree of a graph.

    igraph_error_t igraph_minimum_spanning_tree(
        const igraph_t *graph, igraph_vector_int_t *res,
        const igraph_vector_t *weights, igraph_mst_algorithm_t method);

Finds a minimum weight spanning tree of the graph. If the graph is not connected then its minimum spanning forest is returned, i.e. the set of the minimum spanning trees of each component.

Directed graphs are treated as undirected for this computation.

This function is deterministic, i.e. it always returns the same spanning tree. See `igraph_random_spanning_tree()` for the uniform random sampling of spanning trees of a graph.

References:

Prim, R.C.: Shortest connection networks and some generalizations, Bell System Technical Journal, Vol. 36, 1957, 1389--1401. https://doi.org/10.1002/j.1538-7305.1957.tb01515.x

Kruskal, J. B.: On the shortest spanning subtree of a graph and the traveling salesman problem, Proc. Amer. Math. Soc. 7 (1956), 48-50 https://doi.org/10.1090%2FS0002-9939-1956-0078686-7

Arguments:

`graph`: | The graph object. Edge directions will be ignored.
`res`: | An initialized vector, the IDs of the edges that constitute a spanning tree will be returned here. Use `igraph_subgraph_from_edges()` to extract the spanning tree as a separate graph object.
`weights`: | A vector containing the weights of the edges in the order of edge IDs. Weights must not be NaN. Supply `NULL` to treat all edges as having the same weight.

`method`:

The type of the algorithm used.

`IGRAPH_MST_AUTOMATIC` | tries to select the best performing algorithm for the current graph.
`IGRAPH_MST_UNWEIGHTED` | ignores edge weights and produces an arbitrary spanning tree.
`IGRAPH_MST_PRIM` | uses Prim's algorithm.
`IGRAPH_MST_KRUSKAL` | uses Kruskal's algorithm.

Returns:

`` | Error code.

Time complexity: See the functions implementing the specific algorithms.

See also:

`` | `igraph_random_spanning_tree()` to compute a random spanning tree instead of a minimum one.

Example 17.29. File `examples/simple/igraph_minimum_spanning_tree.c`

    #include <igraph.h>

    int main(void) {
        igraph_t graph;
        igraph_vector_t eb;
        igraph_vector_int_t edges;

        /* Initialize the library. */
        igraph_setup();

        /* Create the vector where the tree edges will be stored. */
        igraph_vector_int_init(&edges, 0);

        /* Create the Frucht graph */
        igraph_famous(&graph, "Frucht");

        /* Compute the edge betweenness. */
        igraph_vector_init(&eb, igraph_ecount(&graph));
        igraph_edge_betweenness(&graph, /*weights=*/ NULL, &eb, igraph_ess_all(IGRAPH_EDGEORDER_ID), IGRAPH_UNDIRECTED, false);

        /* Use Prim's algorithm to compute the edges that belong to the minimum weight
         * spanning tree, using edge betweenness values as edge weights. */
        igraph_minimum_spanning_tree(&graph, &edges, &eb, IGRAPH_MST_PRIM);
        printf("Minimum spanning tree edges:\n");
        igraph_vector_int_print(&edges);

        /* A maximum spanning tree can be computed by first negating the weights. */
        igraph_vector_scale(&eb, -1);

        /* Compute and output the edges that belong to the maximum weight spanning tree,
         * letting igraph automatically select the most suitable algorithm. */
        igraph_minimum_spanning_tree(&graph, &edges, &eb, IGRAPH_MST_AUTOMATIC);
        printf("\nMaximum spanning tree edges:\n");
        igraph_vector_int_print(&edges);

        igraph_real_t total_tree_weight = 0;
        igraph_int_t n = igraph_vector_int_size(&edges);
        for (igraph_int_t i=0; i < n; i++) {
            total_tree_weight += -VECTOR(eb)[ VECTOR(edges)[i] ];
        }
        printf("\nTotal maximum spanning tree weight: %g\n", total_tree_weight);

        /* Clean up */
        igraph_destroy(&graph);
        igraph_vector_destroy(&eb);
        igraph_vector_int_destroy(&edges);

        return 0;
    }

### 16.2. `igraph_random_spanning_tree` — Uniformly samples the spanning trees of a graph.

    igraph_error_t igraph_random_spanning_tree(const igraph_t *graph, igraph_vector_int_t *res, igraph_int_t vid);

Performs a loop-erased random walk on the graph to uniformly sample its spanning trees. Edge directions are ignored.

Multi-graphs are supported, and edge multiplicities will affect the sampling frequency. For example, consider the 3-cycle graph `1=2-3-1`, with two edges between vertices 1 and 2. Due to these parallel edges, the trees `1-2-3` and `3-1-2` will be sampled with multiplicity 2, while the tree `2-3-1` will be sampled with multiplicity 1.

Arguments:

`graph`: | The input graph. Edge directions are ignored.
`res`: | An initialized vector, the IDs of the edges that constitute a spanning tree will be returned here. Use `igraph_subgraph_from_edges()` to extract the spanning tree as a separate graph object.
`vid`: | This parameter is relevant if the graph is not connected. If negative, a random spanning forest of all components will be generated. Otherwise, it should be the ID of a vertex. A random spanning tree of the component containing the vertex will be generated.

Returns:

`` | Error code.

See also:

`` | `igraph_minimum_spanning_tree()`, `igraph_random_walk()`

### 16.3. `igraph_is_tree` — Decides whether the graph is a tree.

    igraph_error_t igraph_is_tree(const igraph_t *graph, igraph_bool_t *res, igraph_int_t *root, igraph_neimode_t mode);

An undirected graph is a tree if it is connected and has no cycles.

In the directed case, an additional requirement is that all edges are oriented away from a root (out-tree or arborescence) or all edges are oriented towards a root (in-tree or anti-arborescence). This test can be controlled using the `mode` parameter.

By convention, the null graph (i.e. the graph with no vertices) is considered not to be connected, and therefore not a tree.

Arguments:

`graph`: | The graph object to analyze.
`res`: | Pointer to a Boolean variable, the result will be stored here.
`root`: | If not `NULL`, the root node will be stored here. When `mode` is `IGRAPH_ALL` or the graph is undirected, any vertex can be the root and `root` is set to 0 (the first vertex). When `mode` is `IGRAPH_OUT` or `IGRAPH_IN`, the root is set to the vertex with zero in- or out-degree, respectively.
`mode`: | For a directed graph this specifies whether to test for an out-tree, an in-tree or ignore edge directions. The respective possible values are: `IGRAPH_OUT`, `IGRAPH_IN`, `IGRAPH_ALL`. This argument is ignored for undirected graphs.

Returns:

`` | Error code: `IGRAPH_EINVAL`: invalid mode argument.

Time complexity: At most O(|V|+|E|), the number of vertices plus the number of edges in the graph.

See also:

`` | `igraph_is_forest()` to check if all components are trees, which is equivalent to the graph lacking undirected cycles; `igraph_is_connected()`, `igraph_is_acyclic()`

Example 17.30. File `examples/simple/igraph_kary_tree.c`

    #include <igraph.h>

    int main(void) {
        igraph_t graph;
        igraph_bool_t res;

        /* Initialize the library. */
        igraph_setup();

        /* Create a directed binary tree on 15 nodes,
           with edges pointing towards the root. */
        igraph_kary_tree(&graph, 15, 2, IGRAPH_TREE_IN);

        igraph_is_tree(&graph, &res, NULL, IGRAPH_IN);
        printf("Is it an in-tree? %s\n", res ? "Yes" : "No");

        igraph_is_tree(&graph, &res, NULL, IGRAPH_OUT);
        printf("Is it an out-tree? %s\n", res ? "Yes" : "No");

        igraph_destroy(&graph);

        return 0;
    }

### 16.4. `igraph_is_forest` — Decides whether the graph is a forest.

    igraph_error_t igraph_is_forest(const igraph_t *graph, igraph_bool_t *res,
                                    igraph_vector_int_t *roots, igraph_neimode_t mode);

An undirected graph is a forest if it has no cycles. Equivalently, a graph is a forest if all connected components are trees.

In the directed case, an additional requirement is that edges in each tree are oriented away from the root (out-trees or arborescences) or all edges are oriented towards the root (in-trees or anti-arborescences). This test can be controlled using the `mode` parameter.

By convention, the null graph (i.e. the graph with no vertices) is considered to be a forest.

The `res` return value of this function is cached in the graph itself if `mode` is set to `IGRAPH_ALL` or if the graph is undirected. Calling the function multiple times with no modifications to the graph in between will return a cached value in O(1) time if the roots are not requested.

Arguments:

`graph`: | The graph object to analyze.
`res`: | Pointer to a Boolean variable. If not `NULL`, then the result will be stored here.
`roots`: | If not `NULL`, the root nodes will be stored here. When `mode` is `IGRAPH_ALL` or the graph is undirected, any one vertex from each component can be the root. When `mode` is `IGRAPH_OUT` or `IGRAPH_IN`, all the vertices with zero in- or out-degree, respectively are considered as root nodes.
`mode`: | For a directed graph this specifies whether to test for an out-forest, an in-forest or ignore edge directions. The respective possible values are: `IGRAPH_OUT`, `IGRAPH_IN`, `IGRAPH_ALL`. This argument is ignored for undirected graphs.

Returns:

`` | Error code: `IGRAPH_EINVMODE`: invalid mode argument.

Time complexity: At most O(|V|+|E|), the number of vertices plus the number of edges in the graph.

See also:

`` | `igraph_is_tree()` to check if a graph is a tree, i.e. a forest with a single component; `igraph_is_acyclic()` to check if a graph lacks (undirected or directed) cycles.

### 16.5. `igraph_to_prufer` — Converts a tree to its Prüfer sequence.

    igraph_error_t igraph_to_prufer(const igraph_t *graph, igraph_vector_int_t* prufer);

A Prüfer sequence is a unique sequence of integers associated with a labelled tree. A tree on n >= 2 vertices can be represented by a sequence of n-2 integers, each between 0 and n-1 (inclusive).

Arguments:

`graph`: | Pointer to an initialized graph object which must be a tree on n >= 2 vertices.
`prufer`: | A pointer to the integer vector that should hold the Prüfer sequence; the vector must be initialized and will be resized to n - 2.

Returns:

``

Error code:

`IGRAPH_ENOMEM` | there is not enough memory to perform the operation.
`IGRAPH_EINVAL` | the graph is not a tree or it is has less than vertices

See also:

`` | `igraph_from_prufer()`

## 17. Transitivity or clustering coefficient

### 17.1. `igraph_transitivity_undirected` — Calculates the transitivity (clustering coefficient) of a graph.

    igraph_error_t igraph_transitivity_undirected(const igraph_t *graph,
                                       igraph_real_t *res,
                                       igraph_transitivity_mode_t mode);

The transitivity measures the probability that two neighbors of a vertex are connected. More precisely, this is the ratio of the triangles and connected triples in the graph, the result is a single real number. Directed graphs are considered as undirected ones and multi-edges are ignored.

Note that this measure is different from the local transitivity measure (see `igraph_transitivity_local_undirected()` ) as it calculates a single value for the whole graph.

Clustering coefficient is an alternative name for transitivity.

References:

S. Wasserman and K. Faust: Social Network Analysis: Methods and Applications. Cambridge: Cambridge University Press, 1994.

Arguments:

`graph`: | The graph object. Edge directions and multiplicites are ignored.
`res`: | Pointer to a real variable, the result will be stored here.
`mode`: | Defines how to treat graphs with no connected triples. `IGRAPH_TRANSITIVITY_NAN` returns `NaN` in this case, `IGRAPH_TRANSITIVITY_ZERO` returns zero.

Returns:

`` | Error code: `IGRAPH_ENOMEM`: not enough memory for temporary data.

See also:

`` | `igraph_transitivity_local_undirected()`, `igraph_transitivity_avglocal_undirected()`.

Time complexity: O(|V|*d^2), |V| is the number of vertices in the graph, d is the average node degree.

Example 17.31. File `examples/simple/igraph_transitivity.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_real_t res;

        /* Initialize the library. */
        igraph_setup();

        /* Trivial cases */

        igraph_ring(&g, 100, IGRAPH_UNDIRECTED, 0, 0);
        igraph_transitivity_undirected(&g, &res, IGRAPH_TRANSITIVITY_NAN);
        igraph_destroy(&g);

        if (res != 0) {
            return 1;
        }

        igraph_full(&g, 20, IGRAPH_UNDIRECTED, IGRAPH_NO_LOOPS);
        igraph_transitivity_undirected(&g, &res, IGRAPH_TRANSITIVITY_NAN);
        igraph_destroy(&g);

        if (res != 1) {
            return 2;
        }

        /* Degenerate cases */
        igraph_small(&g, 0, IGRAPH_UNDIRECTED,
                     0,  1,  2,  3,  4,  5, -1);
        igraph_transitivity_undirected(&g, &res, IGRAPH_TRANSITIVITY_NAN);
        /* res should be NaN here, any comparison must return false */
        if (res == 0 || res > 0 || res < 0) {
            return 4;
        }
        igraph_transitivity_undirected(&g, &res, IGRAPH_TRANSITIVITY_ZERO);
        /* res should be zero here */
        if (res) {
            return 5;
        }
        igraph_destroy(&g);

        /* Zachary Karate club */

        igraph_small(&g, 0, IGRAPH_UNDIRECTED,
                     0,  1,  0,  2,  0,  3,  0,  4,  0,  5,
                     0,  6,  0,  7,  0,  8,  0, 10,  0, 11,
                     0, 12,  0, 13,  0, 17,  0, 19,  0, 21,
                     0, 31,  1,  2,  1,  3,  1,  7,  1, 13,
                     1, 17,  1, 19,  1, 21,  1, 30,  2,  3,
                     2,  7,  2,  8,  2,  9,  2, 13,  2, 27,
                     2, 28,  2, 32,  3,  7,  3, 12,  3, 13,
                     4,  6,  4, 10,  5,  6,  5, 10,  5, 16,
                     6, 16,  8, 30,  8, 32,  8, 33,  9, 33,
                     13, 33, 14, 32, 14, 33, 15, 32, 15, 33,
                     18, 32, 18, 33, 19, 33, 20, 32, 20, 33,
                     22, 32, 22, 33, 23, 25, 23, 27, 23, 29,
                     23, 32, 23, 33, 24, 25, 24, 27, 24, 31,
                     25, 31, 26, 29, 26, 33, 27, 33, 28, 31,
                     28, 33, 29, 32, 29, 33, 30, 32, 30, 33,
                     31, 32, 31, 33, 32, 33,
                     -1);

        igraph_transitivity_undirected(&g, &res, IGRAPH_TRANSITIVITY_NAN);
        igraph_destroy(&g);

        if (res != 0.2556818181818181767717) {
            fprintf(stderr, "%f != %f\n", res, 0.2556818181818181767717);
            return 3;
        }

        return 0;
    }

### 17.2. `igraph_transitivity_local_undirected` — The local transitivity (clustering coefficient) of some vertices.

    igraph_error_t igraph_transitivity_local_undirected(const igraph_t *graph,
            igraph_vector_t *res,
            const igraph_vs_t vids,
            igraph_transitivity_mode_t mode);

The transitivity measures the probability that two neighbors of a vertex are connected. In case of the local transitivity, this probability is calculated separately for each vertex.

Note that this measure is different from the global transitivity measure (see `igraph_transitivity_undirected()` ) as it calculates a transitivity value for each vertex individually.

Clustering coefficient is an alternative name for transitivity.

References:

D. J. Watts and S. Strogatz: Collective dynamics of small-world networks. Nature 393(6684):440-442 (1998).

Arguments:

`graph`: | The input graph. Edge directions and multiplicities are ignored.
`res`: | Pointer to an initialized vector, the result will be stored here. It will be resized as needed.
`vids`: | Vertex set, the vertices for which the local transitivity will be calculated.
`mode`: | Defines how to treat vertices with degree less than two. `IGRAPH_TRANSITIVITY_NAN` returns `NaN` for these vertices, `IGRAPH_TRANSITIVITY_ZERO` returns zero.

Returns:

`` | Error code.

See also:

`` | `igraph_transitivity_undirected()`, `igraph_transitivity_avglocal_undirected()`.

Time complexity: O(n*d^2), n is the number of vertices for which the transitivity is calculated, d is the average vertex degree.

### 17.3. `igraph_transitivity_avglocal_undirected` — Average local transitivity (clustering coefficient).

    igraph_error_t igraph_transitivity_avglocal_undirected(const igraph_t *graph,
            igraph_real_t *res,
            igraph_transitivity_mode_t mode);

The transitivity measures the probability that two neighbors of a vertex are connected. In case of the average local transitivity, this probability is calculated for each vertex and then the average is taken. Vertices with less than two neighbors require special treatment, they will either be left out from the calculation or they will be considered as having zero transitivity, depending on the `mode` argument. Edge directions and edge multiplicities are ignored.

Note that this measure is different from the global transitivity measure (see `igraph_transitivity_undirected()` ) as it simply takes the average local transitivity across the whole network.

Clustering coefficient is an alternative name for transitivity.

References:

D. J. Watts and S. Strogatz: Collective dynamics of small-world networks. Nature 393(6684):440-442 (1998).

Arguments:

`graph`: | The input graph. Edge directions and multiplicites are ignored.
`res`: | Pointer to a real variable, the result will be stored here.
`mode`: | Defines how to treat vertices with degree less than two. `IGRAPH_TRANSITIVITY_NAN` leaves them out from averaging, `IGRAPH_TRANSITIVITY_ZERO` includes them with zero transitivity. The result will be `NaN` if the mode is `IGRAPH_TRANSITIVITY_NAN` and there are no vertices with more than one neighbor.

Returns:

`` | Error code.

See also:

`` | `igraph_transitivity_undirected()`, `igraph_transitivity_local_undirected()`.

Time complexity: O(|V|*d^2), |V| is the number of vertices in the graph and d is the average degree.

### 17.4. `igraph_transitivity_barrat` — Weighted local transitivity of some vertices, as defined by A. Barrat.

    igraph_error_t igraph_transitivity_barrat(const igraph_t *graph,
                                   igraph_vector_t *res,
                                   const igraph_vs_t vids,
                                   const igraph_vector_t *weights,
                                   igraph_transitivity_mode_t mode);

This is a local transitivity, i.e. a vertex-level index. For a given vertex `i`, from all triangles in which it participates we consider the weight of the edges incident on `i`. The transitivity is the sum of these weights divided by twice the strength of the vertex (see `igraph_strength()`) and the degree of the vertex minus one. See equation (5) in Alain Barrat, Marc Barthelemy, Romualdo Pastor-Satorras, Alessandro Vespignani: The architecture of complex weighted networks, Proc. Natl. Acad. Sci. USA 101, 3747 (2004) at https://doi.org/10.1073/pnas.0400087101 for the exact formula.

Arguments:

`graph`: | The input graph. Edge directions are ignored for directed graphs. Note that the function does not work for non-simple graphs.
`res`: | Pointer to an initialized vector, the result will be stored here. It will be resized as needed.
`vids`: | The vertices for which the calculation is performed.
`weights`: | Edge weights. If this is a null pointer, then a warning is given and `igraph_transitivity_local_undirected()` is called.
`mode`: | Defines how to treat vertices with zero strength. `IGRAPH_TRANSITIVITY_NAN` says that the transitivity of these vertices is `NaN`, `IGRAPH_TRANSITIVITY_ZERO` says it is zero.

Returns:

`` | Error code.

Time complexity: O(|V|*d^2), |V| is the number of vertices in the graph, d is the average node degree.

See also:

`` | `igraph_transitivity_undirected()`, `igraph_transitivity_local_undirected()` and `igraph_transitivity_avglocal_undirected()` for other kinds of (non-weighted) transitivity.

### 17.5. `igraph_ecc` — Edge clustering coefficient of some edges.

    igraph_error_t igraph_ecc(const igraph_t *graph, igraph_vector_t *res,
                              const igraph_es_t eids, igraph_int_t k,
                              igraph_bool_t offset, igraph_bool_t normalize);

The edge clustering coefficient `C^(k)_ij` of an edge (i, j) is defined based on the number of k-cycles the edge participates in, `z^(k)_ij`, and the largest number of such cycles it could participate in given the degrees of its endpoints, `s^(k)_ij`. The original definition given in the reference below is:

`C^(k)_ij = (z^(k)_ij + 1) / s^(k)_ij`

For `k=3`, `s^(k)_ij = min(d_i - 1, d_j - 1)`, where `d_i` and `d_j` are the edge endpoint degrees. For `k=4`, `s^(k)_ij = (d_i - 1) (d_j - 1)`.

The `normalize` and `offset` parameters allow for skipping normalization by `s^(k)` and offsetting the cycle count `z^(k)` by one in the numerator of `C^(k)`. Set both to `true` to compute the original definition of this metric.

This function ignores edge multiplicities when listing k-cycles (i.e. `z^(k)`), but not when computing the maximum number of cycles an edge can participate in (`s^(k)`).

Reference:

F. Radicchi, C. Castellano, F. Cecconi, V. Loreto, and D. Parisi, PNAS 101, 2658 (2004). https://doi.org/10.1073/pnas.0400054101

Arguments:

`graph`: | The input graph.
`res`: | Initialized vector, the result will be stored here.
`eids`: | The edges for which the edge clustering coefficient will be computed.
`k`: | Size of cycles to use in calculation. Must be at least 3. Currently only values of 3 and 4 are supported.
`offset`: | Boolean, whether to add one to cycle counts. When `false`, `z^(k)` is used instead of `z^(k) + 1`. In this case the maximum value of the normalized metric is 1. For `k=3` this is achieved for all edges in a complete graph.
`normalize`: | Boolean, whether to normalize cycle counts by the maximum possible count `s^(k)` given the degrees.

Returns:

`` | Error code.

Time complexity: When `k` is 3, O(|V| d log d + |E| d). When `k` is 4, O(|V| d log d + |E| d^2). d denotes the degree of vertices.

## 18. Directedness conversion

### 18.1. `igraph_to_directed` — Convert an undirected graph to a directed one.

    igraph_error_t igraph_to_directed(igraph_t *graph,
                           igraph_to_directed_t mode);

If the supplied graph is directed, this function does nothing.

Arguments:

`graph`: | The graph object to convert.

`mode`:

Constant, specifies the details of how exactly the conversion is done. Possible values:

`IGRAPH_TO_DIRECTED_ARBITRARY` | The number of edges in the graph stays the same, an arbitrarily directed edge is created for each undirected edge.
`IGRAPH_TO_DIRECTED_MUTUAL` | Two directed edges are created for each undirected edge, one in each direction.
`IGRAPH_TO_DIRECTED_RANDOM` | Each undirected edge is converted to a randomly oriented directed one.
`IGRAPH_TO_DIRECTED_ACYCLIC` | Each undirected edge is converted to a directed edge oriented from a lower index vertex to a higher index one. If no self-loops were present, then the result is a directed acyclic graph.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), the number of vertices plus the number of edges.

### 18.2. `igraph_to_undirected` — Convert a directed graph to an undirected one.

    igraph_error_t igraph_to_undirected(igraph_t *graph,
                             igraph_to_undirected_t mode,
                             const igraph_attribute_combination_t *edge_comb);

If the supplied graph is undirected, this function does nothing.

Arguments:

`graph`: | The graph object to convert.

`mode`:

Constant, specifies the details of how exactly the conversion is done. Possible values: `IGRAPH_TO_UNDIRECTED_EACH`: the number of edges remains constant, an undirected edge is created for each directed one, this version might create graphs with multiple edges; `IGRAPH_TO_UNDIRECTED_COLLAPSE`: one undirected edge will be created for each pair of vertices that are connected with at least one directed edge, no multiple edges will be created. `IGRAPH_TO_UNDIRECTED_MUTUAL` creates an undirected edge for each pair of mutual edges in the directed graph. Non-mutual edges are lost; loop edges are kept unconditionally. This mode might create multiple edges.

`edge_comb`: | What to do with the edge attributes. See the igraph manual section about attributes for details. `NULL` means that the edge attributes are lost during the conversion, except when `mode` is `IGRAPH_TO_UNDIRECTED_EACH`, in which case the edge attributes are kept intact.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), the number of vertices plus the number of edges.

Example 17.32. File `examples/simple/igraph_to_undirected.c`

    #include <igraph.h>

    int main(void) {

        igraph_vector_int_t v;
        igraph_t g;

        /* Initialize the library. */
        igraph_setup();

        igraph_vector_int_init_int(&v, 2, 5, 5);
        igraph_square_lattice(&g, &v, 1, IGRAPH_DIRECTED, 1 /*mutual*/, 0 /*periodic*/);
        igraph_to_undirected(&g, IGRAPH_TO_UNDIRECTED_COLLAPSE,
                             /*edge_comb=*/ 0);
        igraph_write_graph_edgelist(&g, stdout);

        igraph_destroy(&g);
        igraph_vector_int_destroy(&v);

        printf("---\n");

        igraph_small(&g, 10, IGRAPH_DIRECTED,
                     0, 1, 2, 1, 2, 3, 2, 3, 4, 3, 4, 3,
                     5, 6, 6, 5, 6, 7, 6, 7, 7, 6, 7, 8, 7, 8, 8, 7, 8, 7, 8, 8, 9, 9, 9, 9,
                     -1);
        igraph_to_undirected(&g, IGRAPH_TO_UNDIRECTED_MUTUAL,
                             /*edge_comb=*/ 0);
        igraph_write_graph_edgelist(&g, stdout);
        igraph_destroy(&g);

        return 0;
    }

## 19. Spectral properties

### 19.1. `igraph_get_laplacian` — Returns the Laplacian matrix of a graph.

    igraph_error_t igraph_get_laplacian(
        const igraph_t *graph, igraph_matrix_t *res, igraph_neimode_t mode,
        igraph_laplacian_normalization_t normalization,
        const igraph_vector_t *weights
    );

The Laplacian matrix `L` of a graph is defined as `L_ij = - A_ij` when `i != j` and `L_ii = d_i - A_ii`. Here `A` denotes the (possibly weighted) adjacency matrix and `d_i` is the degree (or strength, if weighted) of vertex `i`. In directed graphs, the `mode` parameter controls whether to use out- or in-degrees. Correspondingly, the rows or columns will sum to zero. In undirected graphs, `A_ii` is taken to be twice the number (or total weight) of self-loops, ensuring that `d_i = \sum_j A_ij`. Thus, the Laplacian of an undirected graph is the same as the Laplacian of a directed one obtained by replacing each undirected edge with two reciprocal directed ones.

More compactly, `L = D - A` where the `D` is a diagonal matrix containing the degrees. The Laplacian matrix can also be normalized, with several conventional normalization methods. See `igraph_laplacian_normalization_t` for the methods available in igraph.

The first version of this function was written by Vincent Matossian.

Arguments:

`graph`: | Pointer to the graph to convert.
`res`: | Pointer to an initialized matrix object, the result is stored here. It will be resized if needed.
`mode`: | Controls whether to use out- or in-degrees in directed graphs. If set to `IGRAPH_ALL`, edge directions will be ignored.
`normalization`: | The normalization method to use when calculating the Laplacian matrix. See `igraph_laplacian_normalization_t` for possible values.
`weights`: | An optional vector containing non-negative edge weights, to calculate the weighted Laplacian matrix. Set it to a null pointer to calculate the unweighted Laplacian.

Returns:

`` | Error code.

Time complexity: O(|V|^2), |V| is the number of vertices in the graph.

Example 17.33. File `examples/simple/igraph_get_laplacian.c`

    #include <igraph.h>

    int main(void) {
        igraph_t graph;
        igraph_vector_t weights;
        igraph_matrix_t L;

        /* Initialize the library. */
        igraph_setup();

        igraph_matrix_init(&L, 1, 1);
        igraph_vector_init_int(&weights, 5, 1, 2, 3, 4, 5);

        igraph_ring(&graph, 5, IGRAPH_DIRECTED, 0, 1);
        igraph_get_laplacian(&graph, &L, IGRAPH_OUT, IGRAPH_LAPLACIAN_SYMMETRIC, &weights);
        igraph_matrix_print(&L);

        igraph_vector_destroy(&weights);
        igraph_matrix_destroy(&L);
        igraph_destroy(&graph);

        return 0;
    }

### 19.2. `igraph_get_laplacian_sparse` — Returns the Laplacian of a graph in a sparse matrix format.

    igraph_error_t igraph_get_laplacian_sparse(
        const igraph_t *graph, igraph_sparsemat_t *sparseres, igraph_neimode_t mode,
        igraph_laplacian_normalization_t normalization,
        const igraph_vector_t *weights
    );

See `igraph_get_laplacian()` for the definition of the Laplacian matrix.

The first version of this function was written by Vincent Matossian.

Arguments:

`graph`: | Pointer to the graph to convert.
`sparseres`: | Pointer to an initialized sparse matrix object, the result is stored here.
`mode`: | Controls whether to use out- or in-degrees in directed graphs. If set to `IGRAPH_ALL`, edge directions will be ignored.
`normalization`: | The normalization method to use when calculating the Laplacian matrix. See `igraph_laplacian_normalization_t` for possible values.
`weights`: | An optional vector containing non-negative edge weights, to calculate the weighted Laplacian matrix. Set it to a null pointer to calculate the unweighted Laplacian.

Returns:

`` | Error code.

Time complexity: O(|E|), |E| is the number of edges in the graph.

Example 17.34. File `examples/simple/igraph_get_laplacian_sparse.c`

    #include <igraph.h>

    int test_laplacian(const igraph_vector_t *w, igraph_bool_t dir, igraph_laplacian_normalization_t normalization) {
        igraph_t g;
        igraph_matrix_t m;
        igraph_sparsemat_t sm;
        igraph_vector_int_t vec;
        igraph_vector_t *weights = 0;
        igraph_neimode_t mode = IGRAPH_OUT;

        igraph_sparsemat_init(&sm, 0, 0, 0);

        if (w) {
            weights = (igraph_vector_t*) calloc(1, sizeof(igraph_vector_t));
            igraph_vector_init_copy(weights, w);
        }

        /* Base graph, no loop or multiple edges */
        igraph_ring(&g, 5, dir, 0, 1);
        igraph_get_laplacian_sparse(&g, &sm, mode, normalization, weights);
        igraph_matrix_init(&m, 0, 0);
        igraph_sparsemat_as_matrix(&m, &sm);
        igraph_matrix_print(&m);
        igraph_matrix_destroy(&m);
        printf("===\n");

        /* Add some loop edges */
        igraph_vector_int_init_int(&vec, 4, 1, 1, 2, 2);
        igraph_add_edges(&g, &vec, 0);
        igraph_vector_int_destroy(&vec);
        if (weights) {
            igraph_vector_push_back(weights, 2);
            igraph_vector_push_back(weights, 2);
        }

        igraph_get_laplacian_sparse(&g, &sm, mode, normalization, weights);
        igraph_matrix_init(&m, 0, 0);
        igraph_sparsemat_as_matrix(&m, &sm);
        igraph_matrix_print(&m);
        igraph_matrix_destroy(&m);
        printf("===\n");

        /* Duplicate some edges */
        igraph_vector_int_init_int(&vec, 4, 1, 2, 3, 4);
        igraph_add_edges(&g, &vec, 0);
        igraph_vector_int_destroy(&vec);
        if (weights) {
            igraph_vector_push_back(weights, 3);
            igraph_vector_push_back(weights, 3);
        }

        igraph_get_laplacian_sparse(&g, &sm, mode, normalization, weights);
        igraph_matrix_init(&m, 0, 0);
        igraph_sparsemat_as_matrix(&m, &sm);
        igraph_matrix_print(&m);
        igraph_matrix_destroy(&m);
        printf("===\n");

        /* Add an isolated vertex */
        igraph_add_vertices(&g, 1, NULL);

        igraph_get_laplacian_sparse(&g, &sm, mode, normalization, weights);
        igraph_matrix_init(&m, 0, 0);
        igraph_sparsemat_as_matrix(&m, &sm);
        igraph_matrix_print(&m);
        igraph_matrix_destroy(&m);

        igraph_destroy(&g);

        if (weights) {
            igraph_vector_destroy(weights);
            free(weights);
        }

        igraph_sparsemat_destroy(&sm);

        return 0;
    }

    int main(void) {
        int res;
        int i;
        igraph_vector_t weights;

        /* Initialize the library. */
        igraph_setup();

        igraph_vector_init_int(&weights, 5, 1, 2, 3, 4, 5);

        for (i = 0; i < 8; i++) {
            igraph_bool_t is_normalized = i / 4;
            igraph_vector_t* v = ((i & 2) / 2 ? &weights : 0);
            igraph_bool_t dir = (i % 2 ? IGRAPH_DIRECTED : IGRAPH_UNDIRECTED);

            printf("=== %sormalized, %sweighted, %sdirected\n",
                   (is_normalized ? "N" : "Unn"),
                   (v != 0 ? "" : "un"),
                   (dir == IGRAPH_DIRECTED ? "" : "un")
                  );

            res = test_laplacian(v, dir, is_normalized ? IGRAPH_LAPLACIAN_SYMMETRIC : IGRAPH_LAPLACIAN_UNNORMALIZED);

            if (res) {
                return i + 1;
            }
        }

        igraph_vector_destroy(&weights);

        return 0;
    }

### 19.3. `igraph_laplacian_normalization_t` — Normalization methods for a Laplacian matrix.

    typedef enum {
        IGRAPH_LAPLACIAN_UNNORMALIZED = 0,
        IGRAPH_LAPLACIAN_SYMMETRIC = 1,
        IGRAPH_LAPLACIAN_LEFT = 2,
        IGRAPH_LAPLACIAN_RIGHT = 3
    } igraph_laplacian_normalization_t;

Normalization methods for `igraph_get_laplacian()` and `igraph_get_laplacian_sparse()`. In the following, `A` refers to the (possibly weighted) adjacency matrix and `D` is a diagonal matrix containing degrees (unweighted case) or strengths (weighted case). Out-, in- or total degrees are used according to the `mode` parameter.

Values:

`IGRAPH_LAPLACIAN_UNNORMALIZED`: | Unnormalized Laplacian, `L = D - A`.
`IGRAPH_LAPLACIAN_SYMMETRIC`: | Symmetrically normalized Laplacian, `L = I - D^(-1/2) A D^(-1/2)`.
`IGRAPH_LAPLACIAN_LEFT`: | Left-stochastic normalized Laplacian, `L = I - D^-1 A`.
`IGRAPH_LAPLACIAN_RIGHT`: | Right-stochastic normalized Laplacian, `L = I - A D^-1`.

## 20. Non-simple graphs: Multiple and loop edges

### 20.1. `igraph_is_simple` — Decides whether the input graph is a simple graph.

    igraph_error_t igraph_is_simple(const igraph_t *graph, igraph_bool_t *res, igraph_bool_t directed);

A graph is a simple graph if it does not contain loop edges and multiple edges.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to a boolean constant, the result is stored here.
`directed`: | Whether to consider the directions of edges. `IGRAPH_UNDIRECTED` means that edge directions will be ignored and a directed graph with at least one mutual edge pair will be considered non-simple. `IGRAPH_DIRECTED` means that edge directions will be considered. Ignored for undirected graphs.

Returns:

`` | Error code.

See also:

`` | `igraph_is_loop()` and `igraph_is_multiple()` to find the loops and multiple edges, `igraph_simplify()` to get rid of them, or `igraph_has_multiple()` to decide whether there is at least one multiple edge.

Time complexity: O(|V|+|E|).

### 20.2. `igraph_is_loop` — Find the loop edges in a graph.

    igraph_error_t igraph_is_loop(const igraph_t *graph, igraph_vector_bool_t *res,
                                  igraph_es_t es);

A loop edge, also called a self-loop, is an edge from a vertex to itself.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an initialized boolean vector for storing the result, it will be resized as needed.
`es`: | The edges to check, for all edges supply `igraph_ess_all()` here.

Returns:

`` | Error code.

See also:

`` | `igraph_simplify()` to get rid of loop edges.

Time complexity: O(e), the number of edges to check.

Example 17.35. File `examples/simple/igraph_is_loop.c`

    #include <igraph.h>

    void analyze_loops(const igraph_t *graph) {
        igraph_vector_bool_t is_loop;
        igraph_bool_t has_loop;
        igraph_int_t loop_count;

        igraph_has_loop(graph, &has_loop);
        printf("Has loops? %s\n", has_loop ? "Yes" : "No");

        igraph_count_loops(graph, &loop_count);
        printf("How many? %" IGRAPH_PRId "\n", loop_count);

        igraph_vector_bool_init(&is_loop, 0);
        igraph_is_loop(graph, &is_loop, igraph_ess_all(IGRAPH_EDGEORDER_ID));
        printf("Loop positions: "); igraph_vector_bool_print(&is_loop);
        igraph_vector_bool_destroy(&is_loop);

        printf("\n");
    }

    int main(void) {
        igraph_t graph;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&graph, 0, IGRAPH_DIRECTED,
                     0,1, 1,2, 2,1, 0,1, 1,0, 3,4, 11,10, -1);
        analyze_loops(&graph);
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_UNDIRECTED,
                     0,0, 1,1, 2,2, 2,3, 2,4, 2,5, 2,6, 2,2, 0,0, -1);
        analyze_loops(&graph);
        igraph_destroy(&graph);

        return 0;
    }

### 20.3. `igraph_has_loop` — Returns whether the graph has at least one loop edge.

    igraph_error_t igraph_has_loop(const igraph_t *graph, igraph_bool_t *res);

A loop edge is an edge from a vertex to itself.

The return value of this function is cached in the graph itself; calling the function multiple times with no modifications to the graph in between will return a cached value in O(1) time.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an initialized boolean vector for storing the result.

Returns:

`` | Error code.

See also:

`` | `igraph_simplify()` to get rid of loop edges.

Time complexity: O(e), the number of edges to check.

Example 17.36. File `examples/simple/igraph_is_loop.c`

    #include <igraph.h>

    void analyze_loops(const igraph_t *graph) {
        igraph_vector_bool_t is_loop;
        igraph_bool_t has_loop;
        igraph_int_t loop_count;

        igraph_has_loop(graph, &has_loop);
        printf("Has loops? %s\n", has_loop ? "Yes" : "No");

        igraph_count_loops(graph, &loop_count);
        printf("How many? %" IGRAPH_PRId "\n", loop_count);

        igraph_vector_bool_init(&is_loop, 0);
        igraph_is_loop(graph, &is_loop, igraph_ess_all(IGRAPH_EDGEORDER_ID));
        printf("Loop positions: "); igraph_vector_bool_print(&is_loop);
        igraph_vector_bool_destroy(&is_loop);

        printf("\n");
    }

    int main(void) {
        igraph_t graph;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&graph, 0, IGRAPH_DIRECTED,
                     0,1, 1,2, 2,1, 0,1, 1,0, 3,4, 11,10, -1);
        analyze_loops(&graph);
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_UNDIRECTED,
                     0,0, 1,1, 2,2, 2,3, 2,4, 2,5, 2,6, 2,2, 0,0, -1);
        analyze_loops(&graph);
        igraph_destroy(&graph);

        return 0;
    }

### 20.4. `igraph_count_loops` — Counts the self-loops in the graph.

    igraph_error_t igraph_count_loops(const igraph_t *graph, igraph_int_t *loop_count);

Counts loop edges, i.e. edges whose two endpoints coincide.

Arguments:

`graph`: | The input graph.
`loop_count`: | Pointer to an integer, the number of self-loops will be stored here.

Returns:

`` | Error code.

Time complexity: O(|E|), linear in the number of edges.

Example 17.37. File `examples/simple/igraph_is_loop.c`

    #include <igraph.h>

    void analyze_loops(const igraph_t *graph) {
        igraph_vector_bool_t is_loop;
        igraph_bool_t has_loop;
        igraph_int_t loop_count;

        igraph_has_loop(graph, &has_loop);
        printf("Has loops? %s\n", has_loop ? "Yes" : "No");

        igraph_count_loops(graph, &loop_count);
        printf("How many? %" IGRAPH_PRId "\n", loop_count);

        igraph_vector_bool_init(&is_loop, 0);
        igraph_is_loop(graph, &is_loop, igraph_ess_all(IGRAPH_EDGEORDER_ID));
        printf("Loop positions: "); igraph_vector_bool_print(&is_loop);
        igraph_vector_bool_destroy(&is_loop);

        printf("\n");
    }

    int main(void) {
        igraph_t graph;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&graph, 0, IGRAPH_DIRECTED,
                     0,1, 1,2, 2,1, 0,1, 1,0, 3,4, 11,10, -1);
        analyze_loops(&graph);
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_UNDIRECTED,
                     0,0, 1,1, 2,2, 2,3, 2,4, 2,5, 2,6, 2,2, 0,0, -1);
        analyze_loops(&graph);
        igraph_destroy(&graph);

        return 0;
    }

### 20.5. `igraph_is_multiple` — Find the multiple edges in a graph.

    igraph_error_t igraph_is_multiple(const igraph_t *graph, igraph_vector_bool_t *res,
                                      igraph_es_t es);

An edge is a multiple edge if there is another edge with the same head and tail vertices in the graph.

Note that this function returns true only for the second or more appearances of the multiple edges.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to a boolean vector, the result will be stored here. It will be resized as needed.
`es`: | The edges to check. Supply `igraph_ess_all()` if you want to check all edges.

Returns:

`` | Error code.

See also:

`` | `igraph_count_multiple()`, `igraph_count_multiple_1()`, `igraph_has_multiple()` and `igraph_simplify()`.

Time complexity: O(e*d), e is the number of edges to check and d is the average degree (out-degree in directed graphs) of the vertices at the tail of the edges.

Example 17.38. File `examples/simple/igraph_is_multiple.c`

    #include <igraph.h>

    void print_vector(igraph_vector_bool_t *v, FILE *f) {
        igraph_int_t i;
        for (i = 0; i < igraph_vector_bool_size(v); i++) {
            fprintf(f, " %i", VECTOR(*v)[i] ? 1 : 0);
        }
        fprintf(f, "\n");
    }

    int main(void) {

        igraph_t graph;
        igraph_vector_bool_t v;

        /* Initialize the library. */
        igraph_setup();

        igraph_vector_bool_init(&v, 0);

        igraph_small(&graph, 0, IGRAPH_DIRECTED, 0, 1, 1, 2, 2, 1, 0, 1, 1, 0, 3, 4, 11, 10, -1);
        igraph_is_multiple(&graph, &v, igraph_ess_all(IGRAPH_EDGEORDER_ID));
        print_vector(&v, stdout);
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_UNDIRECTED,
                     0, 0, 1, 2, 1, 1, 2, 2, 2, 1, 2, 3, 2, 4,
                     2, 5, 2, 6, 2, 2, 3, 2, 0, 0, 6, 2, 2, 2, 0, 0, -1);
        igraph_is_multiple(&graph, &v, igraph_ess_all(IGRAPH_EDGEORDER_ID));
        print_vector(&v, stdout);
        igraph_destroy(&graph);

        igraph_vector_bool_destroy(&v);

        return 0;
    }

### 20.6. `igraph_has_multiple` — Check whether the graph has at least one multiple edge.

    igraph_error_t igraph_has_multiple(const igraph_t *graph, igraph_bool_t *res);

An edge is a multiple edge if there is another edge with the same head and tail vertices in the graph.

The return value of this function is cached in the graph itself; calling the function multiple times with no modifications to the graph in between will return a cached value in O(1) time.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to a boolean variable, the result will be stored here.

Returns:

`` | Error code.

See also:

`` | `igraph_count_multiple()`, `igraph_is_multiple()` and `igraph_simplify()`.

Time complexity: O(e*d), e is the number of edges to check and d is the average degree (out-degree in directed graphs) of the vertices at the tail of the edges.

Example 17.39. File `examples/simple/igraph_has_multiple.c`

    #include <igraph.h>

    int main(void) {

        igraph_t graph;
        igraph_bool_t res;

        /* Initialize the library. */
        igraph_setup();

        igraph_small(&graph, 0, IGRAPH_DIRECTED, 0, 1, 1, 2, 2, 1, 0, 1, 1, 0, 3, 4, 11, 10, -1);
        igraph_has_multiple(&graph, &res);
        if (!res) {
            return 1;
        }
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_UNDIRECTED,
                     0, 0, 1, 2, 1, 1, 2, 2, 2, 1, 2, 3, 2, 4,
                     2, 5, 2, 6, 2, 2, 3, 2, 0, 0, 6, 2, 2, 2, 0, 0, -1);
        igraph_has_multiple(&graph, &res);
        if (!res) {
            return 2;
        }
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_DIRECTED, 0, 1, 1, 2, 2, 1, 1, 0, 3, 4, 11, 10, -1);
        igraph_has_multiple(&graph, &res);
        if (res) {
            return 3;
        }
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_UNDIRECTED,
                     0, 0, 1, 2, 1, 1, 2, 2, 2, 3, 2, 4, 2, 5, 2, 6, 2, 2, -1);
        igraph_has_multiple(&graph, &res);
        if (!res) {
            return 4;
        }
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_UNDIRECTED,
                     0, 0, 1, 2, 1, 1, 2, 2, 2, 3, 2, 4, 2, 5, 2, 6, -1);
        igraph_has_multiple(&graph, &res);
        if (res) {
            return 5;
        }
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_UNDIRECTED, 0, 1, 0, 1, 1, 2, -1);
        igraph_has_multiple(&graph, &res);
        if (!res) {
            return 6;
        }
        igraph_destroy(&graph);

        igraph_small(&graph, 0, IGRAPH_UNDIRECTED, 0, 0, 0, 0, -1);
        igraph_has_multiple(&graph, &res);
        if (!res) {
            return 7;
        }
        igraph_destroy(&graph);

        return 0;
    }

### 20.7. `igraph_count_multiple` — The multiplicity of some edges in a graph.

    igraph_error_t igraph_count_multiple(const igraph_t *graph, igraph_vector_int_t *res,
                                         igraph_es_t es);

An edge is called a multiple edge when there is one or more other edge between the same two vertices. The multiplicity of an edge is the number of edges between its endpoints.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to a vector, the result will be stored here. It will be resized as needed.
`es`: | The edges to check. Supply `igraph_ess_all()` if you want to check all edges.

Returns:

`` | Error code.

See also:

`` | `igraph_count_multiple_1()` if you only need the multiplicity of a single edge; `igraph_is_multiple()` if you are only interested in whether the graph has at least one edge with multiplicity greater than one; `igraph_simplify()` to ensure that the graph has no multiple edges.

Time complexity: O(E d), E is the number of edges to check and d is the average degree (out-degree in directed graphs) of the vertices at the tail of the edges.

### 20.8. `igraph_count_multiple_1` — The multiplicity of a single edge in a graph.

    igraph_error_t igraph_count_multiple_1(const igraph_t *graph, igraph_int_t *res,
                                           igraph_int_t eid);

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an iteger, the result will be stored here.
`eid`: | The ID of the edge to check.

Returns:

`` | Error code.

See also:

`` | `igraph_count_multiple()` if you need the multiplicity of multiple edges; `igraph_is_multiple()` if you are only interested in whether the graph has at least one edge with multiplicity greater than one; `igraph_simplify()` to ensure that the graph has no multiple edges.

Time complexity: O(d), where d is the out-degree of the tail of the edge.

## 21. Mixing patterns and degree correlations

### 21.1. `igraph_assortativity_nominal` — Assortativity of a graph based on vertex categories.

    igraph_error_t igraph_assortativity_nominal(
            const igraph_t *graph, const igraph_vector_t *weights,
            const igraph_vector_int_t *types,
            igraph_real_t *res,
            igraph_bool_t directed, igraph_bool_t normalized);

Assuming the vertices of the input graph belong to different categories, this function calculates the assortativity coefficient of the graph. The assortativity coefficient is between minus one and one and it is one if all connections stay within categories, it is minus one, if the network is perfectly disassortative. For a randomly connected network it is (asymptotically) zero.

The unnormalized version, computed when `normalized` is set to false, is identical to the modularity, and is defined as follows for directed networks:

`1/m sum_ij (A_ij - k^out_i k^in_j / m) d(i,j)`,

where `m` denotes the number of edges, `A_ij` is the adjacency matrix, `k^out` and `k^in` are the out- and in-degrees, and `d(i,j)` is one if vertices `i` and `j` are in the same category and zero otherwise.

The normalized assortativity coefficient is obtained by dividing the previous expression by

`1/m sum_ij (m - k^out_i k^in_j d(i,j) / m)`.

It can take any value within the interval [-1, 1].

Undirected graphs are effectively treated as directed ones with all-reciprocal edges. Thus, self-loops are taken into account twice in undirected graphs.

References:

M. E. J. Newman: Mixing patterns in networks, Phys. Rev. E 67, 026126 (2003) https://doi.org/10.1103/PhysRevE.67.026126. See section II and equation (2) for the definition of the concept.

For an educational overview of assortativity, see M. E. J. Newman, Networks: An Introduction, Oxford University Press (2010). https://doi.org/10.1093/acprof%3Aoso/9780199206650.001.0001.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`weights`: | Weighted nominal assortativity is not currently implemented. Pass `NULL` to ignore.
`types`: | Integer vector giving the vertex categories. The types are represented by integers starting at zero.
`res`: | Pointer to a real variable, the result is stored here.
`directed`: | Boolean, it gives whether to consider edge directions in a directed graph. It is ignored for undirected graphs.
`normalized`: | Boolean, whether to compute the usual normalized assortativity. The unnormalized version is identical to modularity. Supply true here to compute the standard assortativity.

Returns:

`` | Error code.

Time complexity: O(|E|+t), |E| is the number of edges, t is the number of vertex types.

See also:

`` | `igraph_assortativity()` for computing the assortativity based on continuous vertex values instead of discrete categories. `igraph_modularity()` to compute generalized modularity. `igraph_joint_type_distribution()` to obtain the mixing matrix.

Example 17.40. File `examples/simple/igraph_assortativity_nominal.c`

    #include <igraph.h>
    #include <stdio.h>

    int main(void) {
        igraph_int_t nodes = 120, types = 4;
        igraph_matrix_t pref_matrix;

        /* Initialize the library. */
        igraph_setup();

        igraph_matrix_init(&pref_matrix, types, types);

        igraph_rng_seed(igraph_rng_default(), 42);
        printf("Randomly generated graph with %" IGRAPH_PRId " nodes and %" IGRAPH_PRId " vertex types\n\n", nodes, types);

        /* Generate preference matrix giving connection probabilities for different vertex types */
        for (igraph_int_t i = 0; i < types; i++) {
            for (igraph_int_t j = 0; j < types; j++) {
                MATRIX(pref_matrix, i, j) = (i == j ? 0.1: 0.01);
            }
        }

        igraph_vector_int_t node_type_vec;
        igraph_vector_int_init(&node_type_vec, nodes);

        for (int i = 0; i < 5; i++) {
            igraph_real_t assortativity;
            igraph_t g;

            /* Generate undirected graph with 1000 nodes and 50 vertex types */
            igraph_preference_game(&g, nodes, types, /* type_dist= */ NULL, /* fixed_sizes= */ 1, &pref_matrix, &node_type_vec, IGRAPH_UNDIRECTED, IGRAPH_NO_LOOPS);

            igraph_assortativity_nominal(&g, NULL, &node_type_vec, &assortativity, IGRAPH_UNDIRECTED, 1);
            printf("Assortativity before rewiring = %g\n", assortativity);

            /* Rewire graph */
            igraph_rewire(&g, 10 * igraph_ecount(&g), IGRAPH_SIMPLE_SW, NULL);

            igraph_assortativity_nominal(&g, NULL, &node_type_vec, &assortativity, IGRAPH_UNDIRECTED, 1);
            printf("Assortativity after rewiring = %g\n\n", assortativity);

            igraph_destroy(&g);
        }
        igraph_vector_int_destroy(&node_type_vec);
        igraph_matrix_destroy(&pref_matrix);
    }

### 21.2. `igraph_assortativity` — Assortativity based on numeric properties of vertices.

    igraph_error_t igraph_assortativity(
            const igraph_t *graph, const igraph_vector_t *weights,
            const igraph_vector_t *values, const igraph_vector_t *values_in,
            igraph_real_t *res,
            igraph_bool_t directed, igraph_bool_t normalized);

This function calculates the assortativity coefficient of a graph based on given values `x_i` for each vertex `i`. This type of assortativity coefficient equals the Pearson correlation of the values at the two ends of the edges.

The unnormalized covariance of values, computed when `normalized` is set to false, is defined as follows in a directed graph:

`cov(x_out, x_in) = 1/m sum_ij (A_ij - k^out_i k^in_j / m) x_i x_j`,

where `m` denotes the number of edges, `A_ij` is the adjacency matrix, and `k^out` and `k^in` are the out- and in-degrees. `x_out` and `x_in` refer to the sets of vertex values at the start and end of the directed edges.

The normalized covariance, i.e. Pearson correlation, is obtained by dividing the previous expression by `sqrt(var(x_out)) sqrt(var(x_in))`, where

`var(x_out) = 1/m sum_i k^out_i x_i^2 - (1/m sum_i k^out_i x_i^2)^2`

`var(x_in) = 1/m sum_j k^in_j x_j^2 - (1/m sum_j k^in_j x_j^2)^2`

Undirected graphs are effectively treated as directed graphs where all edges are reciprocal. Therefore, self-loops are effectively considered twice in undirected graphs.

When edge weights are given, they are effectively treated as edge multiplicities. The above formulas are valid for weighted graph as well when `m` is interpreted as the total edge weight (instead of the edge count) and `k` as vertex strengths (instead of degrees).

References:

M. E. J. Newman: Mixing patterns in networks, Phys. Rev. E 67, 026126 (2003) https://doi.org/10.1103/PhysRevE.67.026126. See section III and equation (21) for the definition, and equation (26) for performing the calculation in directed graphs with the degrees as values.

M. E. J. Newman: Assortative mixing in networks, Phys. Rev. Lett. 89, 208701 (2002) https://doi.org/10.1103/PhysRevLett.89.208701. See equation (4) for performing the calculation in undirected graphs with the degrees as values.

For an educational overview of the concept of assortativity, see M. E. J. Newman, Networks: An Introduction, Oxford University Press (2010). https://doi.org/10.1093/acprof%3Aoso/9780199206650.001.0001.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`weights`: | The edge weights. Pass `NULL` to compute unweighed assortativity, which in effect assumes all weights to be 1.
`values`: | The vertex values, these can be arbitrary numeric values.
`values_in`: | A second value vector to be used for the incoming edges when calculating assortativity for a directed graph. Supply `NULL` here if you want to use the same values for outgoing and incoming edges. This argument is ignored (with a warning) if it is not a null pointer and the undirected assortativity coefficient is being calculated.
`res`: | Pointer to a real variable, the result is stored here.
`directed`: | Boolean, whether to consider edge directions for directed graphs. It is ignored for undirected graphs.
`normalized`: | Boolean, whether to compute the normalized covariance, i.e. Pearson correlation. Supply true here to compute the standard assortativity.

Returns:

`` | Error code.

Time complexity: O(|E|), linear in the number of edges of the graph.

See also:

`` | `igraph_assortativity_nominal()` if you have discrete vertex categories instead of numeric labels, and `igraph_assortativity_degree()` for the special case of assortativity based on vertex degrees.

### 21.3. `igraph_assortativity_degree` — Assortativity of a graph based on vertex degree.

    igraph_error_t igraph_assortativity_degree(const igraph_t *graph,
                                    igraph_real_t *res,
                                    igraph_bool_t directed);

Assortativity based on vertex degree, please see the discussion at the documentation of `igraph_assortativity()` for details. This function simply calls `igraph_assortativity()` with the degrees as the vertex values and normalization enabled. In the directed case, it uses out-degrees as out-values and in-degrees as in-values.

For regular graphs, i.e. graphs in which all vertices have the same degree, computing degree correlations is not meaningful, and this function returns NaN.

Arguments:

`graph`: | The input graph, it can be directed or undirected.
`res`: | Pointer to a real variable, the result is stored here.
`directed`: | Boolean, whether to consider edge directions for directed graphs. This argument is ignored for undirected graphs. Supply true here to do the natural thing, i.e. use directed version of the measure for directed graphs and the undirected version for undirected graphs.

Returns:

`` | Error code.

Time complexity: O(|E|+|V|), |E| is the number of edges, |V| is the number of vertices.

See also:

`` | `igraph_assortativity()` for the general function calculating assortativity for any kind of numeric vertex values, and `igraph_joint_degree_distribution()` to get the complete joint degree distribution.

Example 17.41. File `examples/simple/igraph_assortativity_degree.c`

    #include <igraph.h>
    #include <stdio.h>

    int main(void){
        igraph_t g;
        igraph_int_t vcount = 1000;
        igraph_real_t pf = 0.2;

        /* Initialize the library. */
        igraph_setup();

        /* Seed random number generator to ensure reproducibility. */
        igraph_rng_seed(igraph_rng_default(), 42);

        printf("Forest fire model network with %" IGRAPH_PRId " vertices and %g forward burning probability.\n\n",
               vcount, pf);

        for (int i = 0; i < 5; i++) {
            igraph_real_t assortativity;

            /* Generate graph from the forest fire model. */
            igraph_forest_fire_game(&g, vcount, pf, 1.0, 1, IGRAPH_UNDIRECTED);

            /* Compute assortativity. */
            igraph_assortativity_degree(&g, &assortativity, /* ignore edge directions */ IGRAPH_UNDIRECTED);
            printf("Assortativity before rewiring = %g\n", assortativity);

            /* Randomize the graph while preserving the degrees. */
            igraph_rewire(&g, 20 * igraph_ecount(&g), IGRAPH_SIMPLE_SW, NULL);

            /* Re-compute assortativity. Did it change? */
            igraph_assortativity_degree(&g, &assortativity, /* ignore edge directions */ IGRAPH_UNDIRECTED);
            printf("Assortativity after rewiring = %g\n\n", assortativity);

            igraph_destroy(&g);
        }
    }

### 21.4. `igraph_avg_nearest_neighbor_degree` — Average neighbor degree.

    igraph_error_t igraph_avg_nearest_neighbor_degree(const igraph_t *graph,
                                           igraph_vs_t vids,
                                           igraph_neimode_t mode,
                                           igraph_neimode_t neighbor_degree_mode,
                                           igraph_vector_t *knn,
                                           igraph_vector_t *knnk,
                                           const igraph_vector_t *weights);

Calculates the average degree of the neighbors for each vertex (`knn`), and optionally, the same quantity as a function of the vertex degree (`knnk`).

For isolated vertices `knn` is set to NaN. The same is done in `knnk` for vertex degrees that don't appear in the graph.

The weighted version computes a weighted average of the neighbor degrees as

`k_nn_u = 1/s_u sum_v w_uv k_v`,

where `s_u = sum_v w_uv` is the sum of the incident edge weights of vertex `u`, i.e. its strength. The sum runs over the neighbors `v` of vertex `u` as indicated by `mode`. `w_uv` denotes the weighted adjacency matrix and `k_v` is the neighbors' degree, specified by `neighbor_degree_mode`. This is equation (6) in the reference below.

When only the `k_nn(k)` degree correlation function is needed, `igraph_degree_correlation_vector()` can be used as well. This function provides more flexible control over how degree at each end of directed edges are computed.

Reference:

A. Barrat, M. Barthélemy, R. Pastor-Satorras, and A. Vespignani, The architecture of complex weighted networks, Proc. Natl. Acad. Sci. USA 101, 3747 (2004). https://dx.doi.org/10.1073/pnas.0400087101

Arguments:

`graph`: | The input graph. It may be directed.
`vids`: | The vertices for which the calculation is performed.
`mode`: | The type of neighbors to consider in directed graphs. `IGRAPH_OUT` considers out-neighbors, `IGRAPH_IN` in-neighbors and `IGRAPH_ALL` ignores edge directions.
`neighbor_degree_mode`: | The type of degree to average in directed graphs. `IGRAPH_OUT` averages out-degrees, `IGRAPH_IN` averages in-degrees and `IGRAPH_ALL` ignores edge directions for the degree calculation.
`knn`: | Pointer to an initialized vector, the result will be stored here. It will be resized as needed. Supply a `NULL` pointer here if you only want to calculate `knnk`.
`knnk`: | Pointer to an initialized vector, the average neighbor degree as a function of the vertex degree is stored here. This is sometimes referred to as the `k_nn(k)` degree correlation function. The first (zeroth) element is for degree one vertices, etc. The calculation is done based only on the vertices `vids`. Supply a `NULL` pointer here if you don't want to calculate this.
`weights`: | Optional edge weights. Supply a null pointer here for the non-weighted version.

Returns:

`` | Error code.

See also:

`` | `igraph_degree_correlation_vector()` for computing only the degree correlation function, with more flexible control over degree computations.

Time complexity: O(|V|+|E|), linear in the number of vertices and edges.

Example 17.42. File `examples/simple/igraph_avg_nearest_neighbor_degree.c`

    #include <igraph.h>

    int main(void) {
        igraph_t graph;
        igraph_vector_t knn, knnk;
        igraph_vector_t weights;

        /* Initialize the library. */
        igraph_setup();

        igraph_famous(&graph, "Zachary");

        igraph_vector_init(&knn, 0);
        igraph_vector_init(&knnk, 0);

        igraph_avg_nearest_neighbor_degree(&graph, igraph_vss_all(),
                                           IGRAPH_ALL, IGRAPH_ALL,
                                           &knn, &knnk, /*weights=*/ NULL);

        printf("knn: ");
        igraph_vector_print(&knn);
        printf("knn(k): ");
        igraph_vector_print(&knnk);

        igraph_vector_init_range(&weights, 0, igraph_ecount(&graph));

        igraph_avg_nearest_neighbor_degree(&graph, igraph_vss_all(),
                                           IGRAPH_ALL, IGRAPH_ALL,
                                           &knn, &knnk, &weights);
        igraph_vector_destroy(&weights);

        printf("knn: ");
        igraph_vector_print(&knn);
        printf("knn(k): ");
        igraph_vector_print(&knnk);

        igraph_vector_destroy(&knn);
        igraph_vector_destroy(&knnk);

        igraph_destroy(&graph);

        return 0;
    }

### 21.5. `igraph_degree_correlation_vector` — Degree correlation function.

    igraph_error_t igraph_degree_correlation_vector(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *knnk,
            igraph_neimode_t from_mode, igraph_neimode_t to_mode,
            igraph_bool_t directed_neighbors);

Computes the degree correlation function `k_nn(k)`, defined as the mean degree of the targets of directed edges whose source has degree `k`. The averaging is done over all directed edges. The `from_mode` and `to_mode` parameters control how the source and target vertex degrees are computed. This way the out-in, out-out, in-in and in-out degree correlation functions can all be computed.

In undirected graphs, edges are treated as if they were a pair of reciprocal directed ones.

If P_ij is the joint degree distribution of the graph, computable with `igraph_joint_degree_distribution()`, then `k_nn(k) = (sum_j j P_kj) / (sum_j P_kj)`.

The function `igraph_avg_nearest_neighbor_degree()`, whose main purpose is to calculate the average neighbor degree for each vertex separately, can also compute `k_nn(k)`. It differs from this function in that it can take a subset of vertices to base the calculation on, but it does not allow the same fine-grained control over how degrees are computed.

References:

R. Pastor-Satorras, A. Vazquez, A. Vespignani: Dynamical and Correlation Properties of the Internet, Phys. Rev. Lett., vol. 87, pp. 258701 (2001). https://doi.org/10.1103/PhysRevLett.87.258701

A. Vazquez, R. Pastor-Satorras, A. Vespignani: Large-scale topological and dynamical properties of the Internet, Phys. Rev. E, vol. 65, pp. 066130 (2002). https://doi.org/10.1103/PhysRevE.65.066130

A. Barrat, M. Barthélemy, R. Pastor-Satorras, and A. Vespignani, The architecture of complex weighted networks, Proc. Natl. Acad. Sci. USA 101, 3747 (2004). https://dx.doi.org/10.1073/pnas.0400087101

Arguments:

`graph`: | The input graph.
`weights`: | An optional weight vector. If not `NULL`, weighted averages will be computed.
`knnk`: | An initialized vector, the result will be written here. `knnk[d]` will contain the mean degree of vertices connected to by vertices of degree `d`. Note that in contrast to `igraph_avg_nearest_neighbor_degree()`, `d=0` is also included.
`from_mode`: | How to compute the degree of sources? Can be `IGRAPH_OUT` for out-degree, `IGRAPH_IN` for in-degree, or `IGRAPH_ALL` for total degree. Ignored in undirected graphs.
`to_mode`: | How to compute the degree of sources? Can be `IGRAPH_OUT` for out-degree, `IGRAPH_IN` for in-degree, or `IGRAPH_ALL` for total degree. Ignored in undirected graphs.
`directed_neighbors`: | Whether to consider `u -> v` connections to be directed. Undirected connections are treated as reciprocal directed ones, i.e. both `u -> v` and `v -> u` will be considered. Ignored in undirected graphs.

Returns:

`` | Error code.

See also:

`` | `igraph_avg_nearest_neighbor_degree()` for computing the average neighbour degree of a set of vertices, `igraph_joint_degree_distribution()` to get the complete joint degree distribution, and `igraph_assortativity_degree()` to compute the degree assortativity.

Time complexity: O(|E| + |V|)

### 21.6. `igraph_joint_type_distribution` — Mixing matrix for vertex categories.

    igraph_error_t igraph_joint_type_distribution(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_matrix_t *p,
            const igraph_vector_int_t *from_types, const igraph_vector_int_t *to_types,
            igraph_bool_t directed, igraph_bool_t normalized);

Computes the mixing matrix M_ij, i.e. the joint distribution of vertex types at the endpoints directed of edges. Categories are represented by non-negative integer indices, passed in `from_types` and `to_types`. The row and column counts of `m` will be one larger than the largest source and target type, respectively. Re-index type vectors using `igraph_reindex_membership()` if they are not contiguous integers, to avoid producing a very large matrix.

M_ij is proportional to the probability that a randomly chosen ordered pair of vertices have types `i` and `j`.

When there is a single categorization of vertices, i.e. `from_types` and `to_types` are the same, M_ij is related to the modularity (`igraph_modularity()`) and nominal assortativity (`igraph_assortativity_nominal()`). Let `a_i = sum_j M_ij` and `b_j = sum_i M_ij`. If M_ij is normalized, i.e. `sum_ij M_ij = 1`, and the types represent membership in vertex partitions, then the modularity of the partitioning can be computed as

`Q = sum_ii M_ii - sum_i a_i b_i`

The normalized nominal assortativity is

`Q / (1 - sum_i a_i b_i)`

`igraph_joint_degree_distribution()` is a special case of this function, with categories consisting vertices of the same degree.

References:

M. E. J. Newman: Mixing patterns in networks, Phys. Rev. E 67, 026126 (2003) https://doi.org/10.1103/PhysRevE.67.026126.

Arguments:

`graph`: | The input graph.
`weights`: | A vector containing the weights of the edges. If passing a `NULL` pointer, edges will be assumed to have unit weights.
`p`: | The mixing matrix `M_ij` will be stored here.
`from_types`: | Vertex types for source vertices. These must be non-negative integers.
`to_types`: | Vertex types for target vertices. These must be non-negative integers. If `NULL`, it is assumed to be the same as `from_types`.
`directed`: | Whether to treat edges are directed. Ignored for undirected graphs.
`normalized`: | Whether to normalize the matrix so that entries sum to 1.0. If false, matrix entries will be connection counts. Normalization is not meaningful if some edge weights are negative.

Returns:

`` | Error code.

See also:

`` | `igraph_joint_degree_distribution()` to compute the joint distribution of vertex degrees; `igraph_modularity()` to compute the modularity of a vertex partitioning; `igraph_assortativity_nominal()` to compute assortativity based on vertex categories.

Time complexity: O(E), where E is the number of edges in the input graph.

### 21.7. `igraph_joint_degree_distribution` — The joint degree distribution of a graph.

    igraph_error_t igraph_joint_degree_distribution(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_matrix_t *p,
            igraph_neimode_t from_mode, igraph_neimode_t to_mode,
            igraph_bool_t directed_neighbors,
            igraph_bool_t normalized,
            igraph_int_t max_from_degree, igraph_int_t max_to_degree);

Computes the joint degree distribution `P_ij` of a graph, used in the study of degree correlations. `P_ij` is the probability that a randomly chosen ordered pair of connected vertices have degrees `i` and `j`.

In directed graphs, directionally connected `u -> v` pairs are considered. The joint degree distribution of an undirected graph is the same as that of the corresponding directed graph in which all connection are bidirectional, assuming that `from_mode` is `IGRAPH_OUT`, `to_mode` is `IGRAPH_IN` and `directed_neighbors` is true.

When `normalized` is false, `sum_ij P_ij` gives the total number of connections in a directed graph, or twice that value in an undirected graph. The sum is taken over ordered `(i,j)` degree pairs.

The joint degree distribution relates to other concepts used in the study of degree correlations. If `P_ij` is normalized then the degree correlation function `k_nn(k)` is obtained as

`k_nn(k) = (sum_j j P_kj) / (sum_j P_kj)`.

The non-normalized degree assortativity is obtained as

`a = sum_ij i j (P_ij - q_i r_j)`,

where `q_i = sum_k P_ik` and `r_j = sum_k P_kj`.

Note that the joint degree distribution `P_ij` is similar, but not identical to the joint degree matrix `J_ij` computed by `igraph_joint_degree_matrix()`. If the graph is undirected, then the diagonal entries of an unnormalized `P_ij` are double that of `J_ij`, as any undirected connection between same-degree vertices is counted in both directions. In contrast to `igraph_joint_degree_matrix()`, this function returns matrices which include the row and column corresponding to zero degrees. In directed graphs, this row and column is not necessarily zero when `from_mode` is different from `IGRAPH_OUT` or `to_mode` is different from `IGRAPH_IN`.

References:

M. E. J. Newman: Mixing patterns in networks, Phys. Rev. E 67, 026126 (2003) https://doi.org/10.1103/PhysRevE.67.026126.

Arguments:

`graph`: | A pointer to an initialized graph object.
`weights`: | A vector containing the weights of the edges. If passing a `NULL` pointer, edges will be assumed to have unit weights.
`p`: | A pointer to an initialized matrix that will be resized. The `P_ij` value will be written into `p[i,j]`.
`from_mode`: | How to compute the degree of sources? Can be `IGRAPH_OUT` for out-degree, `IGRAPH_IN` for in-degree, or `IGRAPH_ALL` for total degree. Ignored in undirected graphs.
`to_mode`: | How to compute the degree of targets? Can be `IGRAPH_OUT` for out-degree, `IGRAPH_IN` for in-degree, or `IGRAPH_ALL` for total degree. Ignored in undirected graphs.
`directed_neighbors`: | Whether to consider `u -> v` connections to be directed. Undirected connections are treated as reciprocal directed ones, i.e. both `u -> v` and `v -> u` will be considered. Ignored in undirected graphs.
`normalized`: | Whether to normalize the matrix so that entries sum to 1.0. If false, matrix entries will be connection counts. Normalization is not meaningful if some edge weights are negative.
`max_from_degree`: | The largest source vertex degree to consider. If negative or `IGRAPH_UNLIMITED`, the largest source degree will be used. The row count of the result matrix is one larger than this value.
`max_to_degree`: | The largest target vertex degree to consider. If negative or `IGRAPH_UNLIMITED`, the largest target degree will be used. The column count of the result matrix is one larger than this value.

Returns:

`` | Error code.

See also:

`` | `igraph_joint_degree_matrix()` for computing the joint degree matrix; `igraph_assortativity_degree()` and `igraph_assortativity()` for degree correlations coefficients, and `igraph_degree_correlation_vector()` for the degree correlation function.

Time complexity: O(E), where E is the number of edges in the input graph.

### 21.8. `igraph_joint_degree_matrix` — The joint degree matrix of a graph.

    igraph_error_t igraph_joint_degree_matrix(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_matrix_t *jdm,
            igraph_int_t max_out_degree, igraph_int_t max_in_degree);

In graph theory, the joint degree matrix `J_ij` of a graph gives the number of edges, or sum of edge weights, between vertices of degree `i` and degree `j`. This function stores `J_ij` into `jdm[i-1, j-1]`. Each edge, including self-loops, is counted precisely once, both in undirected and directed graphs.

`sum_(i,j) J_ij` is the total number of edges (or total edge weight) `m` in the graph, where `(i,j)` refers to ordered or unordered pairs in directed and undirected graphs, respectively. Thus `J_ij / m` is the probability that an edge chosen at random (with probability proportional to its weight) connects vertices with degrees `i` and `j`.

Note that `J_ij` is similar, but not identical to the joint degree distribution, computed by `igraph_joint_degree_distribution()`, which is defined for ordered `(i, j)` degree pairs even in the undirected case. When considering undirected graphs, the diagonal of the joint degree distribution is twice that of the joint degree matrix.

References:

Isabelle Stanton and Ali Pinar: Constructing and sampling graphs with a prescribed joint degree distribution. ACM J. Exp. Algorithmics 17, Article 3.5 (2012). https://doi.org/10.1145/2133803.2330086

Arguments:

`graph`: | A pointer to an initialized graph object.
`weights`: | A vector containing the weights of the edges. If passing a `NULL` pointer, edges will be assumed to have unit weights, i.e. the matrix entries will be connection counts.
`jdm`: | A pointer to an initialized matrix that will be resized. The values will be written here.
`max_out_degree`: | Number of rows in the result, i.e. the largest (out-)degree to consider. If negative or `IGRAPH_UNLIMITED`, the largest (out-)degree of the graph will be used.
`max_in_degree`: | Number of columns in the result, i.e. the largest (in-)degree to consider. If negative or `IGRAPH_UNLIMITED`, the largest (in-)degree of the graph will be used.

Returns:

`` | Error code.

See also:

`` | `igraph_joint_degree_distribution()` to count ordered vertex pairs instead of edges, or to obtain a normalized matrix.

Time complexity: O(E), where E is the number of edges in input graph.

### 21.9. `igraph_rich_club_sequence` — Density sequence of subgraphs formed by sequential vertex removal.

    igraph_error_t igraph_rich_club_sequence(
            const igraph_t *graph, const igraph_vector_t *weights,
            igraph_vector_t *res,
            const igraph_vector_int_t *vertex_order,
            igraph_bool_t normalized,
            igraph_bool_t loops, igraph_bool_t directed);

### Warning

This function is experimental and its signature is not considered final yet. We reserve the right to change the function signature without changing the major version of igraph. Use it at your own risk.

This function takes a graph and a vertex ordering as input, sequentially removes the vertices in the given order, and calculates the density of the remaining subgraph after each removal.

Density is calculated as the ratio of the number of edges (or total edge weight, if weighted) to the number of total possible edges in the graph. The latter is dependent on whether the graph is directed and whether self-loops are assumed to be possible: for undirected graphs without self-loops, this total is given by `n(n-1)/2`, and for directed graphs by `n(n-1)`. When self-loops are allowed, these are adjusted to `n(n+1)/2` for undirected and `n^2` for directed graphs.

Vertex order can be sorted by degree so that the resulting density sequence helps reveal how interconnected a graph is across different degree levels, or the presence of a "rich-club" effect.

Arguments:

`graph`: | The graph object to analyze.
`weights`: | Vector of edge weights. If `NULL` all weights are assumed to be 1.
`res`: | Initialized vector, the result will be written here. `res[i]` contain the density of the remaining graph after `i` vertices have been removed. If `normalized` is set to `false`, it contains the remaining edge count (or remaining total edge weights if weights were given).
`vertex_order`: | Vector giving the order in which vertices are removed.
`normalized`: | If `false`, return edge counts (or total edge weights). If `true`, divide by the largest possible edge count to obtain densities.
`loops`: | Whether self-loops are assumed to be possible. Ignored when normalized is not requested.
`directed`: | If false, directed graphs will be treated as undirected. Ignored with undirected graphs.

Returns:

`` | Error code: `IGRAPH_EINVAL`: invalid vertex_order vector and/or weight vector lengths

Time complexity: O(|V| + |E|) where |V| is the number of vertices and |E| the number of edges in the graph given.

See also:

`` | `igraph_density()`, which uses the same calculation of total possible edges.

## 22. K-cores and k-trusses

### 22.1. `igraph_coreness` — The coreness of the vertices in a graph.

    igraph_error_t igraph_coreness(const igraph_t *graph,
            igraph_vector_int_t *cores, igraph_neimode_t mode);

The k-core of a graph is a maximal subgraph in which each vertex has at least degree k. (Degree here means the degree in the subgraph of course.). The coreness of a vertex is the highest order of a k-core containing the vertex.

This function implements the algorithm presented in Vladimir Batagelj, Matjaz Zaversnik: An O(m) Algorithm for Cores Decomposition of Networks. https://arxiv.org/abs/cs/0310049

Arguments:

`graph`: | The input graph.
`cores`: | Pointer to an initialized vector, the result of the computation will be stored here. It will be resized as needed. For each vertex it contains the highest order of a core containing the vertex.
`mode`: | For directed graph it specifies whether to calculate in-cores, out-cores or the undirected version. It is ignored for undirected graphs. Possible values: `IGRAPH_ALL` undirected version, `IGRAPH_IN` in-cores, `IGRAPH_OUT` out-cores.

Returns:

`` | Error code.

Time complexity: O(|E|), the number of edges.

### 22.2. `igraph_trussness` — Finding the "trussness" of the edges in a network.

    igraph_error_t igraph_trussness(const igraph_t* graph, igraph_vector_int_t* trussness);

A k-truss is a subgraph in which every edge occurs in at least `k-2` triangles in the subgraph. The trussness of an edge indicates the highest k-truss that the edge occurs in.

This function returns the highest `k` for each edge. If you are interested in a particular k-truss subgraph, you can subset the graph to those edges which are `>= k` because each k-truss is a subgraph of a `(k–1)`-truss Thus, to get all 4-trusses, take `k >= 4` because the 5-trusses, 6-trusses, etc. need to be included.

The current implementation of this function iteratively decrements support of each edge using O(|E|) space and O(|E|^1.5) time. The implementation does not support multigraphs; use `igraph_simplify()` to collapse edges before calling this function.

Reference:

See Algorithm 2 in: Wang, Jia, and James Cheng. "Truss decomposition in massive networks." Proceedings of the VLDB Endowment 5.9 (2012): 812-823. https://doi.org/10.14778/2311906.2311909

Arguments:

`graph`: | The input graph. Loop edges are allowed; multigraphs are not.
`truss`: | Pointer to initialized vector of truss values that will indicate the highest k-truss each edge occurs in. It will be resized as needed.

Returns:

`` | Error code.

Time complexity: It should be O(|E|^1.5) according to the reference.

## 23. Maximum cardinality search and chordal graphs

### 23.1. `igraph_maximum_cardinality_search` — Maximum cardinality search.

    igraph_error_t igraph_maximum_cardinality_search(const igraph_t *graph,
                                          igraph_vector_int_t *alpha,
                                          igraph_vector_int_t *alpham1);

This function implements the maximum cardinality search algorithm. It computes a rank `alpha` for each vertex, such that visiting vertices in decreasing rank order corresponds to always choosing the vertex with the most already visited neighbors as the next one to visit.

Maximum cardinality search is useful in deciding the chordality of a graph. A graph is chordal if and only if any two neighbors of a vertex which are higher in rank than it are connected to each other.

References:

Robert E Tarjan and Mihalis Yannakakis: Simple linear-time algorithms to test chordality of graphs, test acyclicity of hypergraphs, and selectively reduce acyclic hypergraphs. SIAM Journal of Computation 13, 566--579, 1984. https://doi.org/10.1137/0213035

Arguments:

`graph`: | The input graph. Edge directions will be ignored.
`alpha`: | Pointer to an initialized vector, the result is stored here. It will be resized, as needed. Upon return it contains the rank of the each vertex in the range 0 to `n - 1`, where `n` is the number of vertices.
`alpham1`: | Pointer to an initialized vector or a `NULL` pointer. If not `NULL`, then the inverse of `alpha` is stored here. In other words, the elements of `alpham1` are vertex IDs in reverse maximum cardinality search order.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), linear in terms of the number of vertices and edges.

See also:

`` | `igraph_is_chordal()`.

### 23.2. `igraph_is_chordal` — Decides whether a graph is chordal.

    igraph_error_t igraph_is_chordal(const igraph_t *graph,
                          const igraph_vector_int_t *alpha,
                          const igraph_vector_int_t *alpham1,
                          igraph_bool_t *chordal,
                          igraph_vector_int_t *fill_in,
                          igraph_t *newgraph);

A graph is chordal if each of its cycles of four or more nodes has a chord, i.e. an edge joining two nodes that are not adjacent in the cycle. An equivalent definition is that any chordless cycles have at most three nodes. If either `alpha` or `alpham1` is given, then the other is calculated by taking simply the inverse. If neither are given, then `igraph_maximum_cardinality_search()` is called to calculate them.

Arguments:

`graph`: | The input graph. Edge directions will be ignored.
`alpha`: | Either an alpha vector coming from `igraph_maximum_cardinality_search()` (on the same graph), or a `NULL` pointer.
`alpham1`: | Either an inverse alpha vector coming from `igraph_maximum_cardinality_search()` (on the same graph) or a `NULL` pointer.
`chordal`: | Pointer to a boolean. If not NULL the result is stored here.

`fill_in`:

Pointer to an initialized vector, or a `NULL` pointer. If not a `NULL` pointer, then the fill-in, also called the chordal completion of the graph is stored here. The chordal completion is a set of edges that are needed to make the graph chordal. The vector is resized as needed. Note that the chordal completion returned by this function may not be minimal, i.e. some of the returned fill-in edges may not be needed to make the graph chordal.

`newgraph`: | Pointer to an uninitialized graph, or a `NULL` pointer. If not a null pointer, then a new triangulated graph is created here. This essentially means adding the fill-in edges to the original graph.

Returns:

`` | Error code.

Time complexity: O(n).

See also:

`` | `igraph_maximum_cardinality_search()`.

## 24. Matchings

### 24.1. `igraph_is_matching` — Checks whether the given matching is valid for the given graph.

    igraph_error_t igraph_is_matching(const igraph_t *graph,
                           const igraph_vector_bool_t *types, const igraph_vector_int_t *matching,
                           igraph_bool_t *result);

This function checks a matching vector and verifies whether its length matches the number of vertices in the given graph, its values are between -1 (inclusive) and the number of vertices (exclusive), and whether there exists a corresponding edge in the graph for every matched vertex pair. For bipartite graphs, it also verifies whether the matched vertices are in different parts of the graph.

Arguments:

`graph`: | The input graph. It can be directed but the edge directions will be ignored.
`types`: | If the graph is bipartite and you are interested in bipartite matchings only, pass the vertex types here. If the graph is non-bipartite, simply pass `NULL`.
`matching`: | The matching itself. It must be a vector where element i contains the ID of the vertex that vertex i is matched to, or -1 if vertex i is unmatched.
`result`: | Pointer to a boolean variable, the result will be returned here.

See also:

`` | `igraph_is_maximal_matching()` if you are also interested in whether the matching is maximal (i.e. non-extendable).

Time complexity: O(|V|+|E|) where |V| is the number of vertices and |E| is the number of edges.

Example 17.43. File `examples/simple/igraph_maximum_bipartite_matching.c`

    #include <igraph.h>
    #include <stdio.h>

    int main(void) {
        /* Test graph from the LEDA tutorial:
         * http://www.leda-tutorial.org/en/unofficial/ch05s03s05.html
         */
        igraph_t graph;
        igraph_vector_bool_t types;
        igraph_vector_int_t matching;
        igraph_int_t matching_size;
        igraph_real_t matching_weight;
        igraph_bool_t is_matching;
        int i;

        igraph_small(&graph, 0, 0,
                     0, 8, 0, 12, 0, 14,
                     1, 9, 1, 10, 1, 13,
                     2, 8, 2, 9,
                     3, 10, 3, 11, 3, 13,
                     4, 9, 4, 14,
                     5, 14,
                     6, 9, 6, 14,
                     7, 8, 7, 12, 7, 14
                     , -1);
        igraph_vector_bool_init(&types, 15);
        for (i = 0; i < 15; i++) {
            VECTOR(types)[i] = (i >= 8);
        }
        igraph_vector_int_init(&matching, 0);

        igraph_maximum_bipartite_matching(&graph, &types, &matching_size,
                                          &matching_weight, &matching, 0, 0);
        if (matching_size != 6) {
            printf("matching_size is %" IGRAPH_PRId ", expected: 6\n", matching_size);
            return 1;
        }
        if (matching_weight != 6) {
            printf("matching_weight is %" IGRAPH_PRId ", expected: 6\n", (igraph_int_t) matching_weight);
            return 2;
        }
        igraph_is_maximal_matching(&graph, &types, &matching, &is_matching);
        if (!is_matching) {
            printf("not a matching: ");
            igraph_vector_int_print(&matching);
            return 3;
        }

        igraph_vector_int_destroy(&matching);
        igraph_vector_bool_destroy(&types);
        igraph_destroy(&graph);

        return 0;
    }

### 24.2. `igraph_is_maximal_matching` — Checks whether a matching in a graph is maximal.

    igraph_error_t igraph_is_maximal_matching(const igraph_t *graph,
                                   const igraph_vector_bool_t *types, const igraph_vector_int_t *matching,
                                   igraph_bool_t *result);

A matching is maximal if and only if there exists no unmatched vertex in a graph such that one of its neighbors is also unmatched.

Arguments:

`graph`: | The input graph. It can be directed but the edge directions will be ignored.
`types`: | If the graph is bipartite and you are interested in bipartite matchings only, pass the vertex types here. If the graph is non-bipartite, simply pass `NULL`.
`matching`: | The matching itself. It must be a vector where element i contains the ID of the vertex that vertex i is matched to, or -1 if vertex i is unmatched.
`result`: | Pointer to a boolean variable, the result will be returned here.

Returns:

`` | Error code.

See also:

`` | `igraph_is_matching()` if you are only interested in whether a matching vector is valid for a given graph.

Time complexity: O(|V|+|E|) where |V| is the number of vertices and |E| is the number of edges.

Example 17.44. File `examples/simple/igraph_maximum_bipartite_matching.c`

    #include <igraph.h>
    #include <stdio.h>

    int main(void) {
        /* Test graph from the LEDA tutorial:
         * http://www.leda-tutorial.org/en/unofficial/ch05s03s05.html
         */
        igraph_t graph;
        igraph_vector_bool_t types;
        igraph_vector_int_t matching;
        igraph_int_t matching_size;
        igraph_real_t matching_weight;
        igraph_bool_t is_matching;
        int i;

        igraph_small(&graph, 0, 0,
                     0, 8, 0, 12, 0, 14,
                     1, 9, 1, 10, 1, 13,
                     2, 8, 2, 9,
                     3, 10, 3, 11, 3, 13,
                     4, 9, 4, 14,
                     5, 14,
                     6, 9, 6, 14,
                     7, 8, 7, 12, 7, 14
                     , -1);
        igraph_vector_bool_init(&types, 15);
        for (i = 0; i < 15; i++) {
            VECTOR(types)[i] = (i >= 8);
        }
        igraph_vector_int_init(&matching, 0);

        igraph_maximum_bipartite_matching(&graph, &types, &matching_size,
                                          &matching_weight, &matching, 0, 0);
        if (matching_size != 6) {
            printf("matching_size is %" IGRAPH_PRId ", expected: 6\n", matching_size);
            return 1;
        }
        if (matching_weight != 6) {
            printf("matching_weight is %" IGRAPH_PRId ", expected: 6\n", (igraph_int_t) matching_weight);
            return 2;
        }
        igraph_is_maximal_matching(&graph, &types, &matching, &is_matching);
        if (!is_matching) {
            printf("not a matching: ");
            igraph_vector_int_print(&matching);
            return 3;
        }

        igraph_vector_int_destroy(&matching);
        igraph_vector_bool_destroy(&types);
        igraph_destroy(&graph);

        return 0;
    }

### 24.3. `igraph_maximum_bipartite_matching` — Calculates a maximum matching in a bipartite graph.

    igraph_error_t igraph_maximum_bipartite_matching(const igraph_t *graph,
                                          const igraph_vector_bool_t *types, igraph_int_t *matching_size,
                                          igraph_real_t *matching_weight, igraph_vector_int_t *matching,
                                          const igraph_vector_t *weights, igraph_real_t eps);

A matching in a bipartite graph is a partial assignment of vertices of the first kind to vertices of the second kind such that each vertex of the first kind is matched to at most one vertex of the second kind and vice versa, and matched vertices must be connected by an edge in the graph. The size (or cardinality) of a matching is the number of edges. A matching is a maximum matching if there exists no other matching with larger cardinality. For weighted graphs, a maximum matching is a matching whose edges have the largest possible total weight among all possible matchings.

Maximum matchings in bipartite graphs are found by the push-relabel algorithm with greedy initialization and a global relabeling after every n/2 steps where n is the number of vertices in the graph.

References: Cherkassky BV, Goldberg AV, Martin P, Setubal JC and Stolfi J: Augment or push: A computational study of bipartite matching and unit-capacity flow algorithms. ACM Journal of Experimental Algorithmics 3, 1998.

Kaya K, Langguth J, Manne F and Ucar B: Experiments on push-relabel-based maximum cardinality matching algorithms for bipartite graphs. Technical Report TR/PA/11/33 of the Centre Europeen de Recherche et de Formation Avancee en Calcul Scientifique, 2011.

Arguments:

`graph`: | The input graph. It can be directed but the edge directions will be ignored.
`types`: | Boolean vector giving the vertex types of the graph.
`matching_size`: | The size of the matching (i.e. the number of matched vertex pairs will be returned here). It may be `NULL` if you don't need this.
`matching_weight`: | The weight of the matching if the edges are weighted, or the size of the matching again if the edges are unweighted. It may be `NULL` if you don't need this.
`matching`: | The matching itself. It must be a vector where element i contains the ID of the vertex that vertex i is matched to, or -1 if vertex i is unmatched.
`weights`: | A null pointer (=no edge weights), or a vector giving the weights of the edges. Note that the algorithm is stable only for integer weights.

`eps`:

A small real number used in equality tests in the weighted bipartite matching algorithm. Two real numbers are considered equal in the algorithm if their difference is smaller than `eps`. This is required to avoid the accumulation of numerical errors. It is advised to pass a value derived from the `DBL_EPSILON` constant in `float`.h here. If you are running the algorithm with no `weights` vector, this argument is ignored.

Returns:

`` | Error code.

Time complexity: O(sqrt(|V|) |E|) for unweighted graphs (according to the technical report referenced above), O(|V||E|) for weighted graphs.

Example 17.45. File `examples/simple/igraph_maximum_bipartite_matching.c`

    #include <igraph.h>
    #include <stdio.h>

    int main(void) {
        /* Test graph from the LEDA tutorial:
         * http://www.leda-tutorial.org/en/unofficial/ch05s03s05.html
         */
        igraph_t graph;
        igraph_vector_bool_t types;
        igraph_vector_int_t matching;
        igraph_int_t matching_size;
        igraph_real_t matching_weight;
        igraph_bool_t is_matching;
        int i;

        igraph_small(&graph, 0, 0,
                     0, 8, 0, 12, 0, 14,
                     1, 9, 1, 10, 1, 13,
                     2, 8, 2, 9,
                     3, 10, 3, 11, 3, 13,
                     4, 9, 4, 14,
                     5, 14,
                     6, 9, 6, 14,
                     7, 8, 7, 12, 7, 14
                     , -1);
        igraph_vector_bool_init(&types, 15);
        for (i = 0; i < 15; i++) {
            VECTOR(types)[i] = (i >= 8);
        }
        igraph_vector_int_init(&matching, 0);

        igraph_maximum_bipartite_matching(&graph, &types, &matching_size,
                                          &matching_weight, &matching, 0, 0);
        if (matching_size != 6) {
            printf("matching_size is %" IGRAPH_PRId ", expected: 6\n", matching_size);
            return 1;
        }
        if (matching_weight != 6) {
            printf("matching_weight is %" IGRAPH_PRId ", expected: 6\n", (igraph_int_t) matching_weight);
            return 2;
        }
        igraph_is_maximal_matching(&graph, &types, &matching, &is_matching);
        if (!is_matching) {
            printf("not a matching: ");
            igraph_vector_int_print(&matching);
            return 3;
        }

        igraph_vector_int_destroy(&matching);
        igraph_vector_bool_destroy(&types);
        igraph_destroy(&graph);

        return 0;
    }

## 25. Unfolding a graph into a tree

### 25.1. `igraph_unfold_tree` — Unfolding a graph into a tree, by possibly multiplicating its vertices.

    igraph_error_t igraph_unfold_tree(const igraph_t *graph, igraph_t *tree,
                           igraph_neimode_t mode, const igraph_vector_int_t *roots,
                           igraph_vector_int_t *vertex_index);

A graph is converted into a tree (or forest, if it is unconnected), by performing a breadth-first search on it, and replicating vertices that were found a second, third, etc. time.

Arguments:

`graph`: | The input graph, it can be either directed or undirected.
`tree`: | Pointer to an uninitialized graph object, the result is stored here.
`mode`: | For directed graphs; whether to follow paths along edge directions (`IGRAPH_OUT`), or the opposite (`IGRAPH_IN`), or ignore edge directions completely (`IGRAPH_ALL`). It is ignored for undirected graphs.
`roots`: | A numeric vector giving the root vertex, or vertices (if the graph is not connected), to start from.
`vertex_index`: | Pointer to an initialized vector, or a null pointer. If not a null pointer, then a mapping from the vertices in the new graph to the ones in the original is created here.

Returns:

`` | Error code.

Time complexity: O(n+m), linear in the number vertices and edges.

## 26. Other operations

### 26.1. `igraph_density` — Calculate the density of a graph.

    igraph_error_t igraph_density(
            const igraph_t *graph,
            const igraph_vector_t *weights,
            igraph_real_t *res,
            igraph_bool_t loops);

The density of a graph is simply the ratio of the actual number of its edges and the largest possible number of edges it could have. The maximum number of edges depends on interpretation: are vertices allowed to have a connection to themselves? This is controlled by the `loops` parameter.

The classic definition of the density is formulated for unweighted graphs without multi-edges. This function allows multigraphs and weighted graphs as well. In this case, it computes the ratio of the total edge weight to the largest possible number of adjacent vertex pairs the graph could have. This value may be larger than 1.

If you need the density concept for simple graphs, make sure to eliminate any multi-edges appropriately. This can be done using `igraph_simplify()`.

Arguments:

`graph`: | The input graph object. It must not have parallel edges.
`res`: | Pointer to a real number, the result will be stored here.
`weights`: | Vector of edge weights. Pass `NULL` to to perform an unweighted density calculation.
`loops`: | Boolean constant, whether to include self-loops in the calculation. If this constant is `true` then loop edges are thought to be possible in the graph (this does not necessarily mean that the graph really contains any loops). If this is `false` then the result is only correct if the graph does not contain loops. This function does not check if loops are actually present.

Returns:

`` | Error code.

Time complexity: O(1).

### 26.2. `igraph_mean_degree` — The mean degree of a graph.

    igraph_error_t igraph_mean_degree(const igraph_t *graph, igraph_real_t *res,
                                      igraph_bool_t loops);

This is a convenience function that computes the average of all vertex degrees. In directed graphs, the average of out-degrees and in-degrees is the same; this is the number that is returned. For the null graph, which has no vertices, NaN is returned.

Arguments:

`graph`: | The input graph object.
`res`: | Pointer to a real number, the result will be stored here.
`loops`: | Whether to consider self-loops during the calculation.

Returns:

`` | Error code.

Time complexity: O(1) if self-loops are considered, O(|E|) where |E| is the number of edges if self-loops are ignored.

### 26.3. `igraph_reciprocity` — Calculates the reciprocity of a directed graph.

    igraph_error_t igraph_reciprocity(const igraph_t *graph, igraph_real_t *res,
                           igraph_bool_t ignore_loops,
                           igraph_reciprocity_t mode);

In a directed graph, the measure of reciprocity defines the proportion of mutual connections. It is most commonly defined as the probability that the opposite counterpart of a randomly chosen directed edge is also included in the graph. In adjacency matrix notation: `1 - (sum_ij |A_ij - A_ji|) / (2 sum_ij A_ij)`. In multigraphs, each parallel edge between two vertices must have its own separate reciprocal edge, in accordance with the above formula. This measure is calculated if the `mode` argument is `IGRAPH_RECIPROCITY_DEFAULT`.

For directed graphs with no edges, NaN is returned. For undirected graphs, 1 is returned unconditionally.

Prior to igraph version 0.6, another measure was implemented, defined as the probability of having mutual connections between a vertex pair if we know that there is a (possibly non-mutual) connection between them. In other words, (unordered) vertex pairs are classified into three groups: (1) disconnected, (2) non-reciprocally connected, (3) reciprocally connected. The result is the size of group (3), divided by the sum of group sizes (2)+(3). This measure is calculated if `mode` is `IGRAPH_RECIPROCITY_RATIO`.

Arguments:

`graph`: | The graph object.
`res`: | Pointer to an `igraph_real_t` which will contain the result.
`ignore_loops`: | Whether to ignore self-loops when counting edges. Self-loops are considered as a mutual connection.
`mode`: | Type of reciprocity to calculate, possible values are `IGRAPH_RECIPROCITY_DEFAULT` and `IGRAPH_RECIPROCITY_RATIO`, please see their description above.

Returns:

`` | Error code: `IGRAPH_EINVAL`: graph has no edges `IGRAPH_ENOMEM`: not enough memory for temporary data.

Time complexity: O(|V|+|E|), |V| is the number of vertices, |E| is the number of edges.

Example 17.46. File `examples/simple/igraph_reciprocity.c`

    #include <igraph.h>
    #include <math.h>

    int main(void) {

        igraph_t g;
        igraph_real_t res;

        /* Initialize the library. */
        igraph_setup();

        /* Trivial cases */

        igraph_ring(&g, 100, IGRAPH_UNDIRECTED, 0, 0);
        igraph_reciprocity(&g, &res, 0, IGRAPH_RECIPROCITY_DEFAULT);
        igraph_destroy(&g);

        if (res != 1) {
            return 1;
        }

        /* Small test graph */

        igraph_small(&g, 0, IGRAPH_DIRECTED,
                     0,  1,  0,  2,  0,  3,  1,  0,  2,  3,  3,  2, -1);

        igraph_reciprocity(&g, &res, 0, IGRAPH_RECIPROCITY_RATIO);
        igraph_destroy(&g);

        if (res != 0.5) {
            fprintf(stderr, "%f != %f\n", res, 0.5);
            return 2;
        }

        igraph_small(&g, 0, IGRAPH_DIRECTED, 0, 1, 1, 2, 2, 1, -1);
        igraph_reciprocity(&g, &res, 0, IGRAPH_RECIPROCITY_DEFAULT);
        igraph_destroy(&g);

        if (fabs(res - 2.0 / 3.0) > 1e-15) {
            fprintf(stderr, "%f != %f\n", res, 2.0 / 3.0);
            return 3;
        }

        return 0;
    }

### 26.4. `igraph_diversity` — Structural diversity index of the vertices.

    igraph_error_t igraph_diversity(const igraph_t *graph, const igraph_vector_t *weights,
                         igraph_vector_t *res, const igraph_vs_t vids);

This measure was defined in Nathan Eagle, Michael Macy and Rob Claxton: Network Diversity and Economic Development, Science 328, 1029--1031, 2010.

It is simply the (normalized) Shannon entropy of the incident edges' weights. `D(i) = H(i) / log(k[i])`, and `H(i) = -sum(p[i,j] log(p[i,j]), j=1..k[i])`, where `p[i,j] = w[i,j] / sum(w[i,l], l=1..k[i])`, `k[i]` is the (total) degree of vertex `i`, and `w[i,j]` is the weight of the edge(s) between vertex `i` and `j`. The diversity of isolated vertices will be NaN (not-a-number), while that of vertices with a single connection will be zero.

The measure works only if the graph is undirected and has no multiple edges. If the graph has multiple edges, simplify it first using `igraph_simplify()`. If the graph is directed, convert it into an undirected graph with `igraph_to_undirected()` .

Arguments:

`graph`: | The undirected input graph.
`weights`: | The edge weights, in the order of the edge IDs, must have appropriate length. Weights must be non-negative.
`res`: | An initialized vector, the results are stored here.
`vids`: | Vertex selector that specifies the vertices which to calculate the measure.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), linear.

### 26.5. `igraph_is_mutual` — Check whether some edges of a directed graph are mutual.

    igraph_error_t igraph_is_mutual(const igraph_t *graph, igraph_vector_bool_t *res,
                                    igraph_es_t es, igraph_bool_t loops);

An (A,B) non-loop directed edge is mutual if the graph contains the (B,A) edge too. Whether directed self-loops are considered mutual is controlled by the `loops` parameter.

An undirected graph only has mutual edges, by definition.

Edge multiplicity is not considered here, e.g. if there are two (A,B) edges and one (B,A) edge, then all three are considered to be mutual.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an initialized vector, the result is stored here.
`es`: | The sequence of edges to check. Supply `igraph_ess_all()` to check all edges.
`loops`: | Boolean, whether to consider directed self-loops to be mutual.

Returns:

`` | Error code.

Time complexity: O(n log(d)), n is the number of edges supplied, d is the maximum in-degree of the vertices that are targets of the supplied edges. An upper limit of the time complexity is O(n log(|E|)), |E| is the number of edges in the graph.

### 26.6. `igraph_has_mutual` — Check whether a directed graph has any mutual edges.

    igraph_error_t igraph_has_mutual(const igraph_t *graph, igraph_bool_t *res,
                                     igraph_bool_t loops);

An (A,B) non-loop directed edge is mutual if the graph contains the (B,A) edge too. Whether directed self-loops are considered mutual is controlled by the `loops` parameter.

In undirected graphs, all edges are considered mutual by definition. Thus for undirected graph, this function returns false only when there are no edges.

To check whether a graph is an oriented graph, use this function in conjunction with `igraph_is_directed()`.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to a boolean, the result will be stored here.
`loops`: | Boolean, whether to consider directed self-loops to be mutual.

Returns:

`` | Error code.

Time complexity: O(|E| log(d)) where d is the maximum in-degree.

### 26.7. `igraph_get_adjacency` — The adjacency matrix of a graph.

    igraph_error_t igraph_get_adjacency(
        const igraph_t *graph, igraph_matrix_t *res, igraph_get_adjacency_t type,
        const igraph_vector_t *weights, igraph_loops_t loops
    );

The result is an adjacency matrix. Entry i, j of the matrix contains the number of edges connecting vertex i to vertex j in the unweighted case, or the total weight of edges connecting vertex i to vertex j in the weighted case.

Arguments:

`graph`: | Pointer to the graph to convert
`res`: | Pointer to an initialized matrix object, it will be resized if needed.

`type`:

Constant specifying the type of the adjacency matrix to create for undirected graphs. It is ignored for directed graphs. Possible values:

`IGRAPH_GET_ADJACENCY_UPPER` | the upper right triangle of the matrix is used.
`IGRAPH_GET_ADJACENCY_LOWER` | the lower left triangle of the matrix is used.
`IGRAPH_GET_ADJACENCY_BOTH` | the whole matrix is used, a symmetric matrix is returned if the graph is undirected.

`weights`: | An optional vector containing the weight of each edge in the graph. Supply a null pointer here to make all edges have the same weight of 1.

`loops`:

Constant specifying how loop edges should be handled. Possible values:

`IGRAPH_NO_LOOPS` | loop edges are ignored and the diagonal of the matrix will contain zeros only
`IGRAPH_LOOPS_ONCE` | loop edges are counted once, i.e. a vertex with a single unweighted loop edge will have 1 in the corresponding diagonal entry

`IGRAPH_LOOPS_TWICE`

loop edges are counted twice in undirected graphs, i.e. a vertex with a single unweighted loop edge in an undirected graph will have 2 in the corresponding diagonal entry. Loop edges in directed graphs are still counted as 1. Essentially, this means that the function is counting the incident edge stems , which makes more sense when using the adjacency matrix in linear algebra.

Returns:

`` | Error code: `IGRAPH_EINVAL` invalid type argument.

See also:

`` | `igraph_get_adjacency_sparse()` if you want a sparse matrix representation

Time complexity: O(|V||V|), |V| is the number of vertices in the graph.

### 26.8. `igraph_get_adjacency_sparse` — Returns the adjacency matrix of a graph in a sparse matrix format.

    igraph_error_t igraph_get_adjacency_sparse(
        const igraph_t *graph, igraph_sparsemat_t *res, igraph_get_adjacency_t type,
        const igraph_vector_t *weights, igraph_loops_t loops
    );

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an initialized sparse matrix. The result will be stored here. The matrix will be resized as needed.

`type`:

Constant specifying the type of the adjacency matrix to create for undirected graphs. It is ignored for directed graphs. Possible values:

`IGRAPH_GET_ADJACENCY_UPPER` | the upper right triangle of the matrix is used.
`IGRAPH_GET_ADJACENCY_LOWER` | the lower left triangle of the matrix is used.
`IGRAPH_GET_ADJACENCY_BOTH` | the whole matrix is used, a symmetric matrix is returned if the graph is undirected.

`weights`: | An optional vector containing the weight of each edge in the graph. Supply a null pointer here to make all edges have the same weight of 1.

`loops`:

Constant specifying how loop edges should be handled. Possible values:

`IGRAPH_NO_LOOPS` | loop edges are ignored and the diagonal of the matrix will contain zeros only
`IGRAPH_LOOPS_ONCE` | loop edges are counted once, i.e. a vertex with a single unweighted loop edge will have 1 in the corresponding diagonal entry

`IGRAPH_LOOPS_TWICE`

loop edges are counted twice in undirected graphs, i.e. a vertex with a single unweighted loop edge in an undirected graph will have 2 in the corresponding diagonal entry. Loop edges in directed graphs are still counted as 1. Essentially, this means that the function is counting the incident edge stems , which makes more sense when using the adjacency matrix in linear algebra.

Returns:

`` | Error code: `IGRAPH_EINVAL` invalid type argument.

See also:

`` | `igraph_get_adjacency()`, the dense version of this function.

Time complexity: TODO.

### 26.9. `igraph_get_stochastic` — Stochastic adjacency matrix of a graph.

    igraph_error_t igraph_get_stochastic(
        const igraph_t *graph, igraph_matrix_t *res, igraph_bool_t column_wise,
        const igraph_vector_t *weights
    );

Stochastic matrix of a graph. The stochastic matrix of a graph is its adjacency matrix, normalized row-wise (or column-wise), such that the sum of each row (or column) is one. The row-wise normalized matrix is also called a right-stochastic and contains the transition probabilities of a random walk that follows edge directions in a directed graph. The column-wise normalized matrix is called left-stochastic and is related to random walks moving against edge directions.

When the out-degree (or in-degree) of a vertex is zero, the corresponding row (or column) of the row-wise (or column-wise) normalized stochastic matrix will be zero.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an initialized matrix, the result is stored here. It will be resized as needed.
`column_wise`: | If `false`, row-wise normalization is used. If `true`, column-wise normalization is used.
`weights`: | An optional vector containing the weight of each edge in the graph. Supply a null pointer here to make all edges have the same weight of 1.

Returns:

`` | Error code.

Time complexity: O(|V|^2), |V| is the number of vertices in the graph.

See also:

`` | `igraph_get_stochastic_sparse()`, the sparse version of this function.

### 26.10. `igraph_get_stochastic_sparse` — The stochastic adjacency matrix of a graph.

    igraph_error_t igraph_get_stochastic_sparse(
        const igraph_t *graph, igraph_sparsemat_t *res, igraph_bool_t column_wise,
        const igraph_vector_t *weights
    );

Stochastic matrix of a graph in sparse format. See `igraph_get_stochastic()` for the information on stochastic matrices.

Arguments:

`graph`: | The input graph.
`res`: | Pointer to an initialized sparse matrix, the result is stored here. The matrix will be resized as needed.
`column_wise`: | If `false`, row-wise normalization is used. If `true`, column-wise normalization is used.
`weights`: | An optional vector containing the weight of each edge in the graph. Supply a null pointer here to make all edges have the same weight of 1.

Returns:

`` | Error code.

Time complexity: O(|V|+|E|), linear in the number of vertices and edges.

See also:

`` | `igraph_get_stochastic()`, the dense version of this function.

### 26.11. `igraph_get_edgelist` — The list of edges in a graph.

    igraph_error_t igraph_get_edgelist(const igraph_t *graph, igraph_vector_int_t *res, igraph_bool_t bycol);

The order of the edges is given by the edge IDs.

Arguments:

`graph`: | Pointer to the graph object
`res`: | Pointer to an initialized vector object, it will be resized.
`bycol`: | Boolean constant. If true, the edges will be returned columnwise, e.g. the first edge is `res[0]->res[|E|]`, the second is `res[1]->res[|E|+1]`, etc. Supply false to get the edge list in a format compatible with `igraph_add_edges()`.

Returns:

`` | Error code.

See also:

`` | `igraph_edges()` to return the result only for some edge IDs.

Time complexity: O(|E|), the number of edges in the graph.

## 27. Common types and constants

### 27.1. `igraph_loops_t` — How to interpret self-loops in undirected graphs?

    typedef enum {
        IGRAPH_NO_LOOPS = 0,
        IGRAPH_LOOPS_TWICE = 1,
        IGRAPH_LOOPS_ONCE = 2,
        IGRAPH_LOOPS = IGRAPH_LOOPS_TWICE
    } igraph_loops_t;

Controls the interpretation of self-loops in undirected graphs, typically in the context of adjacency matrices or degrees.

These constants are also used to improve readability in boolean contexts, with `IGRAPH_NO_LOOPS`, equivalent to `false`, signifying that loops should be ignored and `IGRAPH_LOOPS`, equivalent to `true`, that loops should be considered.

Values:

`IGRAPH_NO_LOOPS`: | Self-loops are ignored.
`IGRAPH_LOOPS_TWICE`: | Self-loops are considered, and counted twice in undirected graphs. For example, a self-loop contributes two to the degree of a vertex and to diagonal entries of adjacency matrices. This is the standard interpretation in graph theory, thus `IGRAPH_LOOPS` serves as an alias for this option.
`IGRAPH_LOOPS_ONCE`: | Self-loops are considered, and counted only once in undirected graphs.

### 27.2. `igraph_neimode_t` — How to interpret edge directions in directed graphs?

    typedef enum {
        IGRAPH_OUT = 1,
        IGRAPH_IN = 2,
        IGRAPH_ALL = 3
    } igraph_neimode_t;

These "neighbor mode" constants are typically used to specify the treatment of edge directions in directed graphs, or which vertices to consider as adjacent to (i.e. neighbor of) a vertex. It is typically ignored in undirected graphs.

Values:

`IGRAPH_OUT`: | Follow edge directions in directed graphs, or consider out-neighbors of vertices.
`IGRAPH_IN`: | Follow edges in the reverse direction in directed graphs, or consider in-neighbors of vertices.
`IGRAPH_ALL`: | Ignore edge directions in directed graphs, or consider all neighbours (both out and in-neighbors) of vertices.