# Chapter 11. Deterministic graph generators

## 1. About generators

Most functions that create graphs in a deterministic manner are documented here. See also stochastic generators, spatial graph generators, bipartite graph generators, and operators that transform graphs.

## 2. Basic graph creation

### 2.1. `igraph_create` — Creates a graph with the specified edges.

    igraph_error_t igraph_create(igraph_t *graph, const igraph_vector_int_t *edges,
                                 igraph_int_t n, igraph_bool_t directed);

Arguments:

`graph`: | An uninitialized graph object.
`edges`: | The edges to add, the first two elements are the first edge, etc.
`n`: | The number of vertices in the graph, if smaller or equal to the highest vertex ID in the `edges` vector it will be increased automatically. So it is safe to give 0 here.
`directed`: | Boolean, whether to create a directed graph or not. If yes, then the first edge points from the first vertex ID in `edges` to the second, etc.

Returns:

`` | Error code: `IGRAPH_EINVAL`: invalid edges vector (odd number of vertices). `IGRAPH_EINVVID`: invalid (negative) vertex ID.

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

Example 11.1. File `examples/simple/igraph_create.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;
        igraph_vector_int_t v1, v2;

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

        /* simple use */
        igraph_vector_int_init(&v1, 8);
        VECTOR(v1)[0] = 0;
        VECTOR(v1)[1] = 1;
        VECTOR(v1)[2] = 1;
        VECTOR(v1)[3] = 2;
        VECTOR(v1)[4] = 2;
        VECTOR(v1)[5] = 3;
        VECTOR(v1)[6] = 2;
        VECTOR(v1)[7] = 2;
        igraph_create(&g, &v1, 0, 0);
        if (igraph_vcount(&g) != 4) {
            return 1;
        }
        igraph_vector_int_init(&v2, 0);
        igraph_get_edgelist(&g, &v2, 0);
        igraph_vector_int_sort(&v1);
        igraph_vector_int_sort(&v2);
        if (!igraph_vector_int_all_e(&v1, &v2)) {
            return 2;
        }
        igraph_destroy(&g);

        /* higher number of vertices */
        igraph_create(&g, &v1, 10, 0);
        if (igraph_vcount(&g) != 10) {
            return 1;
        }
        igraph_get_edgelist(&g, &v2, 0);
        igraph_vector_int_sort(&v1);
        igraph_vector_int_sort(&v2);
        if (!igraph_vector_int_all_e(&v1, &v2)) {
            return 3;
        }
        igraph_destroy(&g);
        igraph_vector_int_destroy(&v1);
        igraph_vector_int_destroy(&v2);

        return 0;
    }

### 2.2. `igraph_small` — Shorthand to create a small graph, giving the edges as arguments.

    igraph_error_t igraph_small(igraph_t *graph, igraph_int_t n, igraph_bool_t directed,
                                int first, ...);

This function is handy when a relatively small graph needs to be created. Instead of giving the edges as a vector, they are given simply as arguments and a `-1` needs to be given after the last meaningful edge argument.

This function is intended to be used with vertex IDs that are entered as literal integers. If you use a variable instead of a literal, make sure that it is of type int, as this is the type that this function assumes for all variadic arguments. Using a different integer type is undefined behaviour and likely to cause platform-specific issues.

Arguments:

`graph`: | Pointer to an uninitialized graph object. The result will be stored here.
`n`: | The number of vertices in the graph; a non-negative integer.
`directed`: | Boolean constant; gives whether the graph should be directed. Supported values are:
`IGRAPH_DIRECTED` | The graph to be created will be directed.
`IGRAPH_UNDIRECTED` | The graph to be created will be undirected.
`...`: | The additional arguments giving the edges of the graph, and must be of type int. Don't forget to supply an additional `-1` after the last (meaningful) argument. The `first` parameter is present for technical reasons and represents the first variadic argument.

Returns:

`` | Error code.

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

Example 11.2. File `examples/simple/igraph_small.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g;

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

        igraph_small(&g, 0, IGRAPH_DIRECTED, 0, 1, 1, 2, 2, 3, 3, 4, 6, 1, -1);
        igraph_write_graph_edgelist(&g, stdout);
        igraph_destroy(&g);

        return 0;
    }

## 3. Graphs from adjacency matrices and adjacency lists

These functions create graphs from weighted or unweighted adjacency matrices, or an adjacency list.

### 3.1. `igraph_adjacency` — Creates a graph from an adjacency matrix.

    igraph_error_t igraph_adjacency(
        igraph_t *graph, const igraph_matrix_t *adjmatrix, igraph_adjacency_t mode,
        igraph_loops_t loops
    );

The order of the vertices in the matrix is preserved, i.e. the vertex corresponding to the first row/column will be vertex with id 0, the next row is for vertex 1, etc. No guarantees are given about the ordering of edges.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`adjmatrix`: | The adjacency matrix. How it is interpreted depends on the `mode` argument.
`mode`: | Constant to specify how the given matrix is interpreted as an adjacency matrix. Possible values (A(i,j) is the element in row i and column j in the adjacency matrix `adjmatrix`):
`IGRAPH_ADJ_DIRECTED` | The graph will be directed and an element gives the number of edges between two vertices.
`IGRAPH_ADJ_UNDIRECTED` | The graph will be undirected and an element gives the number of edges between two vertices. If the input matrix is not symmetric, an error is thrown.
`IGRAPH_ADJ_MAX` | An undirected graph will be created and the number of edges between vertices i and j is max(A(i,j), A(j,i)).
`IGRAPH_ADJ_MIN` | An undirected graph will be created with min(A(i,j), A(j,i)) edges between vertices i and j.
`IGRAPH_ADJ_PLUS` | An undirected graph will be created with A(i,j)+A(j,i) edges between vertices i and j.
`IGRAPH_ADJ_UPPER` | An undirected graph will be created. Only the upper right triangle (including the diagonal) is used for the number of edges.
`IGRAPH_ADJ_LOWER` | An undirected graph will be created. Only the lower left triangle (including the diagonal) is used for the number of edges.
`loops`: | Constant of type `igraph_loops_t` to specify how the diagonal of the matrix should be treated when creating loop edges. Ignored for modes `IGRAPH_ADJ_DIRECTED`, `IGRAPH_ADJ_UPPER` and `IGRAPH_ADJ_LOWER`.
`IGRAPH_NO_LOOPS` | Ignore the diagonal of the input matrix and do not create loops.
`IGRAPH_LOOPS_ONCE` | Treat the diagonal entries as the number of loop edges incident on the corresponding vertex.
`IGRAPH_LOOPS_TWICE` | Treat the diagonal entries as twice the number of loop edges incident on the corresponding vertex. Odd numbers in the diagonal will return an error code.

Returns:

`` | Error code, `IGRAPH_EINVAL`: Non-square adjacency matrix, negative entry in adjacency matrix, or an odd number was found in the diagonal with `IGRAPH_LOOPS_TWICE`

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

### 3.2. `igraph_weighted_adjacency` — Creates a graph from a weighted adjacency matrix.

    igraph_error_t igraph_weighted_adjacency(
        igraph_t *graph, const igraph_matrix_t *adjmatrix, igraph_adjacency_t mode,
        igraph_vector_t *weights, igraph_loops_t loops
    );

The order of the vertices in the matrix is preserved, i.e. the vertex corresponding to the first row/column will be vertex with id 0, the next row is for vertex 1, etc. No guarantees are given for the ordering of edges.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`adjmatrix`: | The weighted adjacency matrix. How it is interpreted depends on the `mode` argument. The common feature is that edges with zero weights are considered nonexistent (however, negative weights are permitted).
`mode`: | Constant to specify how the given matrix is interpreted as an adjacency matrix. Possible values (A(i,j) is the element in row i and column j in the adjacency matrix `adjmatrix`):
`IGRAPH_ADJ_DIRECTED` | The graph will be directed and an element specifies the weight of the edge between two vertices.
`IGRAPH_ADJ_UNDIRECTED` | This is the same as `IGRAPH_ADJ_MAX`, for convenience.
`IGRAPH_ADJ_MAX` | An undirected graph will be created and the weight of the edge between vertices i and j is max(A(i,j), A(j,i)).
`IGRAPH_ADJ_MIN` | An undirected graph will be created and the weight of the edge between vertices i and j is min(A(i,j), A(j,i)).
`IGRAPH_ADJ_PLUS` | An undirected graph will be created and the weight of the edge between vertices i and j is A(i,j)+A(j,i).
`IGRAPH_ADJ_UPPER` | An undirected graph will be created. Only the upper right triangle (including the diagonal) is used for the edge weights.
`IGRAPH_ADJ_LOWER` | An undirected graph will be created. Only the lower left triangle (including the diagonal) is used for the edge weights.
`weights`: | Pointer to an initialized vector, the weights will be stored here.
`loops`: | Constant to specify how the diagonal of the matrix should be treated when creating loop edges. Ignored for modes `IGRAPH_ADJ_DIRECTED`, `IGRAPH_ADJ_UPPER` and `IGRAPH_ADJ_LOWER`.
`IGRAPH_NO_LOOPS` | Ignore the diagonal of the input matrix and do not create loops.
`IGRAPH_LOOPS_ONCE` | Treat the diagonal entries as the weight of the loop edge incident on the corresponding vertex.
`IGRAPH_LOOPS_TWICE` | Treat the diagonal entries as twice the weight of the loop edge incident on the corresponding vertex.

Returns:

`` | Error code, `IGRAPH_EINVAL`: non-square matrix.

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

Example 11.3. File `examples/simple/igraph_weighted_adjacency.c`

    #include <igraph.h>

    int main(void) {
        igraph_t graph;
        igraph_real_t data[4][4] = { {   0, 1.2, 2.3,   0 },
                                     { 2.0,   0,   0, 1.0 },
                                     {   0,   0, 1.5,   0 },
                                     {   0, 1.0,   0,   0 } };

        /* C arrays use row-major storage, while igraph's matrix uses column-major.
         * The matrix 'mat' will be the transpose of 'data'. */
        const igraph_matrix_t mat =
            igraph_matrix_view(*data, sizeof(data[0]) / sizeof(data[0][0]),
                                      sizeof(data) / sizeof(data[0]));
        igraph_vector_t weights;
        igraph_vector_int_t edges;
        igraph_int_t n;

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

        /* Initialize vector into which weights will be written. */
        igraph_vector_init(&weights, 0);

        igraph_weighted_adjacency(&graph, &mat, IGRAPH_ADJ_DIRECTED, &weights, IGRAPH_LOOPS_ONCE);

        /* When igraph_weighted_adjacency() returns, 'weights' will typically have
         * more capacity allocated than what it uses. We may optionally free any
         * unused capacity to save memory, although in most applications this
         * is not necessary. */
        igraph_vector_resize_min(&weights);

        /* Get the edge list of the graph and output it, along with the weights. */

        igraph_vector_int_init(&edges, 0);
        igraph_get_edgelist(&graph, &edges, 0);
        n = igraph_ecount(&graph);

        for (igraph_int_t i = 0; i < n; i++) {
            printf("%" IGRAPH_PRId " --> %" IGRAPH_PRId ": %g\n",
                   VECTOR(edges)[2*i], VECTOR(edges)[2*i + 1], VECTOR(weights)[i]);
        }

        /* Free all allocated storage. */
        igraph_vector_int_destroy(&edges);
        igraph_destroy(&graph);
        igraph_vector_destroy(&weights);

        return 0;
    }

### 3.3. `igraph_sparse_adjacency` — Creates a graph from a sparse adjacency matrix.

    igraph_error_t igraph_sparse_adjacency(igraph_t *graph, igraph_sparsemat_t *adjmatrix,
            igraph_adjacency_t mode, igraph_loops_t loops);

This has the same functionality as `igraph_adjacency()`, but uses a column-compressed adjacency matrix.

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

### 3.4. `igraph_sparse_weighted_adjacency` — Creates a graph from a weighted sparse adjacency matrix.

    igraph_error_t igraph_sparse_weighted_adjacency(
        igraph_t *graph, igraph_sparsemat_t *adjmatrix, igraph_adjacency_t mode,
        igraph_vector_t *weights, igraph_loops_t loops
    );

This has the same functionality as `igraph_weighted_adjacency()`, but uses a column-compressed adjacency matrix.

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

### 3.5. `igraph_adjlist` — Creates a graph from an adjacency list.

    igraph_error_t igraph_adjlist(igraph_t *graph, const igraph_adjlist_t *adjlist,
                       igraph_neimode_t mode, igraph_bool_t duplicate);

An adjacency list is a list of vectors, containing the neighbors of all vertices. For operations that involve many changes to the graph structure, it is recommended that you convert the graph into an adjacency list via `igraph_adjlist_init()`, perform the modifications (these are cheap for an adjacency list) and then recreate the igraph graph via this function.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`adjlist`: | The adjacency list.
`mode`: | Whether or not to create a directed graph. `IGRAPH_ALL` means an undirected graph, `IGRAPH_OUT` means a directed graph from an out-adjacency list (i.e. each list contains the successors of the corresponding vertices), `IGRAPH_IN` means a directed graph from an in-adjacency list
`duplicate`: | Boolean constant. For undirected graphs this specifies whether each edge is included twice, in the vectors of both adjacent vertices. If this is `false`, then it is assumed that every edge is included only once. This argument is ignored for directed graphs.

Returns:

`` | Error code.

See also:

`` | `igraph_adjlist_init()` for the opposite operation.

Time complexity: O(|V|+|E|).

## 4. Regular structures

These functions produce various basic regular graph structures, such as paths, cycles or lattices.

### 4.1. `igraph_star` — Creates a star graph, every vertex connects only to the center.

    igraph_error_t igraph_star(igraph_t *graph, igraph_int_t n, igraph_star_mode_t mode,
                    igraph_int_t center);

Arguments:

`graph`: | Pointer to an uninitialized graph object, this will be the result.
`n`: | Integer constant, the number of vertices in the graph.
`mode`: | Constant, gives the type of the star graph to create. Possible values:
`IGRAPH_STAR_OUT` | directed star graph, edges point from the center to the other vertices.
`IGRAPH_STAR_IN` | directed star graph, edges point to the center from the other vertices.
`IGRAPH_STAR_MUTUAL` | directed star graph with mutual edges.
`IGRAPH_STAR_UNDIRECTED` | an undirected star graph is created.
`center`: | Id of the vertex which will be the center of the graph.

Returns:

`` | Error code:
`IGRAPH_EINVVID` | invalid number of vertices.
`IGRAPH_EINVAL` | invalid center vertex.
`IGRAPH_EINVMODE` | invalid mode argument.

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

See also:

`` | `igraph_wheel()`, `igraph_square_lattice()`, `igraph_ring()`, `igraph_kary_tree()` for creating other regular structures.

Example 11.4. File `examples/simple/igraph_star.c`

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

    int main(void) {
        igraph_t graph;

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

        /* Create an undirected 6-star, with the 0th node as the centre. */
        igraph_star(&graph, 7, IGRAPH_STAR_UNDIRECTED, 0);

        /* Output the edge list of the graph. */
        igraph_write_graph_edgelist(&graph, stdout);

        /* Destroy the graph when we are done using it. */
        igraph_destroy(&graph);

        return 0;
    }

### 4.2. `igraph_wheel` — Creates a wheel graph, a union of a star and a cycle graph.

    igraph_error_t igraph_wheel(igraph_t *graph, igraph_int_t n, igraph_wheel_mode_t mode,
                    igraph_int_t center);

A wheel graph on `n` vertices can be thought of as a wheel with `n - 1` spokes. The cycle graph part makes up the rim, while the star graph part adds the spokes.

Note that the two and three-vertex wheel graphs are non-simple: The two-vertex wheel graph contains a self-loop, while the three-vertex wheel graph contains parallel edges (a 1-cycle and a 2-cycle, respectively).

Arguments:

`graph`: | Pointer to an uninitialized graph object, this will be the result.
`n`: | Integer constant, the number of vertices in the graph.
`mode`: | Constant, gives the type of the star graph to create. Possible values:
`IGRAPH_WHEEL_OUT` | directed wheel graph, edges point from the center to the other vertices.
`IGRAPH_WHEEL_IN` | directed wheel graph, edges point to the center from the other vertices.
`IGRAPH_WHEEL_MUTUAL` | directed wheel graph with mutual edges.
`IGRAPH_WHEEL_UNDIRECTED` | an undirected wheel graph is created.
`center`: | Id of the vertex which will be the center of the graph.

Returns:

`` | Error code:
`IGRAPH_EINVVID` | invalid number of vertices.
`IGRAPH_EINVAL` | invalid center vertex.
`IGRAPH_EINVMODE` | invalid mode argument.

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

See also:

`` | `igraph_square_lattice()`, `igraph_ring()`, `igraph_star()`, `igraph_kary_tree()` for creating other regular structures.

### 4.3. `igraph_hypercube` — The n-dimensional hypercube graph.

    igraph_error_t igraph_hypercube(igraph_t *graph,
                                    igraph_int_t n, igraph_bool_t directed);

The hypercube graph `Q_n` has `2^n` vertices and `2^(n-1) n` edges. Two vertices are connected when the binary representations of their zero-based vertex IDs differs in precisely one bit.

Arguments:

`graph`: | An uninitialized graph object.
`n`: | The dimension of the hypercube graph.
`directed`: | Whether the graph should be directed. Edges will point from lower index vertices towards higher index ones.

Returns:

`` | Error code.

See also:

`` | `igraph_square_lattice()`

Time complexity: O(2^n)

### 4.4. `igraph_square_lattice` — Arbitrary dimensional square lattices.

    igraph_error_t igraph_square_lattice(
        igraph_t *graph, const igraph_vector_int_t *dimvector, igraph_int_t nei,
        igraph_bool_t directed, igraph_bool_t mutual, const igraph_vector_bool_t *periodic
    );

Creates d-dimensional square lattices of the given size. Optionally, the lattice can be made periodic, and the neighbors within a given graph distance can be connected.

In the zero-dimensional case, the singleton graph is returned.

The vertices of the resulting graph are ordered such that the index of the vertex at position `(i_1, i_2, i_3, ..., i_d)` in a lattice of size `(n_1, n_2, ..., n_d)` will be `i_1 + n_1 * i_2 + n_1 * n_2 * i_3 + ...`.

Arguments:

`graph`: | An uninitialized graph object.
`dimvector`: | Vector giving the sizes of the lattice in each of its dimensions. The dimension of the lattice will be the same as the length of this vector.
`nei`: | Integer value giving the distance (number of steps) within which two vertices will be connected.
`directed`: | Boolean, whether to create a directed graph. If the `mutual` and `circular` arguments are not set to true, edges will be directed from lower-index vertices towards higher-index ones.
`mutual`: | Boolean, if the graph is directed this gives whether to create all connections as mutual.
`periodic`: | Boolean vector, defines whether the generated lattice is periodic along each dimension. The length of this vector must match the length of `dimvector`. This parameter may also be `NULL`, which implies that the lattice will not be periodic.

Returns:

`` | Error code: `IGRAPH_EINVAL`: invalid (negative) dimension vector or mismatch between the length of the dimension vector and the periodicity vector.

See also:

`` | `igraph_hypercube()` to create a hypercube graph; `igraph_ring()` to create a cycle graph or path graph; `igraph_triangular_lattice()` and `igraph_hexagonal_lattice()` to create other types of lattices; `igraph_regular_tree()` to create a Bethe lattice.

Time complexity: If `nei` is less than two then it is O(|V|+|E|) (as far as I remember), |V| and |E| are the number of vertices and edges in the generated graph. Otherwise it is O(|V|*d^k+|E|), d is the average degree of the graph, k is the `nei` argument.

### 4.5. `igraph_triangular_lattice` — A triangular lattice with the given shape.

    igraph_error_t igraph_triangular_lattice(
            igraph_t *graph, const igraph_vector_int_t *dims,
            igraph_bool_t directed, igraph_bool_t mutual);

Creates a triangular lattice whose vertices have the form (i, j) for non-negative integers i and j and (i, j) is generally connected with (i + 1, j), (i, j + 1), and (i - 1, j + 1). The function constructs a planar dual of the graph constructed by `igraph_hexagonal_lattice()`. In particular, there a one-to-one correspondence between the vertices in the constructed graph and the cycles of length 6 in the graph constructed by `igraph_hexagonal_lattice()` with the same `dims` parameter.

The vertices of the resulting graph are ordered lexicographically with the 2nd coordinate being more significant, e.g., (i, j) < (i + 1, j) and (i + 1, j) < (i, j + 1)

Arguments:

`graph`: | An uninitialized graph object.
`dims`: | Integer vector, defines the shape of the lattice. If `dims` is of length 1, the resulting lattice has a triangular shape where each side of the triangle contains `dims[0]` vertices. If `dims` is of length 2, the resulting lattice has a "quasi rectangular" shape with the sides containing `dims[0]` and `dims[1]` vertices, respectively. If `dims` is of length 3, the resulting lattice has a hexagonal shape where the sides of the hexagon contain `dims[0]`, `dims[1]` and `dims[2]` vertices. All dimensions must be non-negative.
`directed`: | Boolean, whether to create a directed graph. If the `mutual` argument is not set to true, edges will be directed from lower-index vertices towards higher-index ones.
`mutual`: | Boolean, if the graph is directed this gives whether to create all connections as mutual.

Returns:

`` | Error code: `IGRAPH_EINVAL`: The size of `dims` must be either 1, 2, or 3 with all the components at least 1.

See also:

`` | `igraph_hexagonal_lattice()` and `igraph_square_lattice()` for creating other types of lattices; `igraph_regular_tree()` to create a Bethe lattice.

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

### 4.6. `igraph_hexagonal_lattice` — A hexagonal lattice with the given shape.

    igraph_error_t igraph_hexagonal_lattice(
            igraph_t *graph, const igraph_vector_int_t *dims,
            igraph_bool_t directed, igraph_bool_t mutual);

Creates a hexagonal lattice whose vertices have the form (i, j) for non-negative integers i and j and (i, j) is generally connected with (i + 1, j), and if i is odd also with (i - 1, j + 1). The function constructs a planar dual of the graph constructed by `igraph_triangular_lattice()`. In particular, there a one-to-one correspondence between the cycles of length 6 in the constructed graph and the vertices of the graph constructed by `igraph_triangular_lattice()` function with the same `dims` parameter.

The vertices of the resulting graph are ordered lexicographically with the 2nd coordinate being more significant, e.g., (i, j) < (i + 1, j) and (i + 1, j) < (i, j + 1)

Arguments:

`graph`: | An uninitialized graph object.
`dims`: | Integer vector, defines the shape of the lattice. If `dims` is of length 1, the resulting lattice has a triangular shape where each side of the triangle contains `dims[0]` vertices. If `dims` is of length 2, the resulting lattice has a "quasi rectangular" shape with the sides containing `dims[0]` and `dims[1]` vertices, respectively. If `dims` is of length 3, the resulting lattice has a hexagonal shape where the sides of the hexagon contain `dims[0]`, `dims[1]` and `dims[2]` vertices. All coordinates must be non-negative.
`directed`: | Boolean, whether to create a directed graph. If the `mutual` argument is not set to true, edges will be directed from lower-index vertices towards higher-index ones.
`mutual`: | Boolean, if the graph is directed this gives whether to create all connections as mutual.

Returns:

`` | Error code: `IGRAPH_EINVAL`: The size of `dims` must be either 1, 2, or 3 with all the components at least 1.

See also:

`` | `igraph_triangular_lattice()` and `igraph_square_lattice()` for creating other types of lattices; ; `igraph_regular_tree()` to create a Bethe lattice.

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

### 4.7. `igraph_ring` — Creates a cycle graph or a path graph.

    igraph_error_t igraph_ring(igraph_t *graph, igraph_int_t n, igraph_bool_t directed,
                    igraph_bool_t mutual, igraph_bool_t circular);

A circular ring on `n` vertices is commonly known in graph theory as the cycle graph, and often denoted by `C_n`. Removing a single edge from the cycle graph `C_n` results in the path graph `P_n`. This function can generate both.

When `n` is 1 or 2, the result may not be a simple graph: the one-cycle contains a self-loop and the undirected or reciprocally connected directed two-cycle contains parallel edges.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`n`: | The number of vertices in the graph.
`directed`: | Whether to create a directed graph. All edges will be oriented in the same direction along the cycle or path.
`mutual`: | Whether to create mutual edges in directed graphs. It is ignored for undirected graphs.
`circular`: | Whether to create a closed ring (a cycle) or an open path.

Returns:

`` | Error code: `IGRAPH_EINVAL`: invalid number of vertices.

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

See also:

`` | `igraph_square_lattice()` for generating more general (periodic or non-periodic) lattices.

Example 11.5. File `examples/simple/igraph_ring.c`

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

    int main(void) {
        igraph_t graph;

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

        /* Create a directed path graph on 10 vertices. */
        igraph_ring(&graph, 10, IGRAPH_DIRECTED, /* mutual= */ 0, /* circular= */ 0);

        /* Output the edge list of the graph. */
        printf("10-path graph:\n");
        igraph_write_graph_edgelist(&graph, stdout);

        /* Destroy the graph. */
        igraph_destroy(&graph);

        /* Create a 4-cycle graph. */
        igraph_ring(&graph, 4, IGRAPH_UNDIRECTED, /* mutual= */ 0, /* circular= */ 1);

        /* Output the edge list of the graph. */
        printf("\n4-cycle graph:\n");
        igraph_write_graph_edgelist(&graph, stdout);

        /* Destroy the graph. */
        igraph_destroy(&graph);

        return 0;
    }

### 4.8. `igraph_path_graph` — A path graph `P_n`.

    igraph_error_t igraph_path_graph(
            igraph_t *graph, igraph_int_t n,
            igraph_bool_t directed, igraph_bool_t mutual);

Creates the path graph `P_n` on `n` vertices.

This is a convenience wrapper to `igraph_ring()`.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`n`: | The number of vertices in the graph.
`directed`: | Whether to create a directed graph.
`mutual`: | Whether to create mutual edges in directed graphs. It is ignored for undirected graphs.

Returns:

`` | Error code.

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

### 4.9. `igraph_cycle_graph` — A cycle graph `C_n`.

    igraph_error_t igraph_cycle_graph(
            igraph_t *graph, igraph_int_t n,
            igraph_bool_t directed, igraph_bool_t mutual);

Creates the cycle graph `C_n` on `n` vertices.

When `n` is 1 or 2, the result may not be a simple graph: the one-cycle contains a self-loop and the undirected or reciprocally connected directed two-cycle contains parallel edges.

This is a convenience wrapper to `igraph_ring()`.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`n`: | The number of vertices in the graph.
`directed`: | Whether to create a directed graph.
`mutual`: | Whether to create mutual edges in directed graphs. It is ignored for undirected graphs.

Returns:

`` | Error code.

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

### 4.10. `igraph_lcf` — Creates a graph from LCF notation.

    igraph_error_t igraph_lcf(igraph_t *graph, igraph_int_t n,
                              const igraph_vector_int_t *shifts,
                              igraph_int_t repeats);

LCF notation (named after Lederberg, Coxeter and Frucht) is a concise notation for 3-regular Hamiltonian graphs. It consists of three parameters: the number of vertices in the graph, a list of shifts giving additional edges to a cycle backbone, and another integer giving how many times the shifts should be performed. See https://mathworld.wolfram.com/LCFNotation.html for details.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`n`: | Integer constant giving the number of vertices. This is normally set to the number of shifts multiplied by the number of repeats.
`shifts`: | An integer vector giving the shifts.
`repeats`: | The number of repeats for the shifts.

Returns:

`` | Error code.

See also:

`` | `igraph_lcf_small()`, `igraph_extended_chordal_ring()`

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

### 4.11. `igraph_lcf_small` — Shorthand to create a graph from LCF notation, giving shifts as the arguments.

    igraph_error_t igraph_lcf_small(igraph_t *graph, igraph_int_t n, ...);

This function provides a shorthand to give the shifts of the LCF notation directly as function arguments. See `igraph_lcf()` for an explanation of LCF notation.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`n`: | Integer, the number of vertices in the graph.
`...`: | The shifts and the number of repeats for the shifts, plus an additional 0 to mark the end of the arguments.

Returns:

`` | Error code.

See also:

`` | See `igraph_lcf()` for a similar function using an `igraph_vector_t` instead of the variable length argument list; `igraph_circulant()` to create circulant graphs.

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

Example 11.6. File `examples/simple/igraph_lcf.c`

    #include <igraph.h>

    int main(void) {

        igraph_t g1, g2;
        igraph_vector_int_t edges;
        igraph_bool_t iso;

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

        // Heawood graph through LCF notation: [5, -5]^7
        // The number of vertices is normally the number of shifts
        // multiplied by the number of repeats, in this case 2*7 = 14.
        igraph_lcf_small(&g1,
                         /* n */ 14,
                         /* shifts */ 5, -5,
                         /* repeats */ 7,
                         0);

        printf("edges:\n");
        igraph_vector_int_init(&edges, 0);
        igraph_get_edgelist(&g1, &edges, false);
        igraph_vector_int_print(&edges);
        igraph_vector_int_destroy(&edges);

        // Built-in Heawood graph:
        igraph_famous(&g2, "Heawood");
        igraph_isomorphic(&g1, &g2, &iso);
        printf("isomorphic: %s\n", iso ? "true" : "false");
        igraph_destroy(&g2);

        igraph_destroy(&g1);

        return 0;
    }

### 4.12. `igraph_circulant` — Creates a circulant graph.

    igraph_error_t igraph_circulant(igraph_t *graph, igraph_int_t n, const igraph_vector_int_t *shifts, igraph_bool_t directed);

A circulant graph `G(n, shifts)` consists of `n` vertices `v_0`, ..., `v_(n-1)` such that for each `s_i` in the list of offsets `shifts`, `v_j` is connected to `v_((j + s_i) mod n)` for all j.

The function can generate either directed or undirected graphs. It does not generate multi-edges or self-loops.

Arguments:

`graph`: | Pointer to an uninitialized graph object, the result will be stored here.
`n`: | Integer, the number of vertices in the circulant graph.
`shifts`: | Integer vector, a list of the offsets within the circulant graph.
`directed`: | Boolean, whether to create a directed graph.

Returns:

`` | Error code.

See also:

`` | `igraph_ring()`, `igraph_generalized_petersen()`, `igraph_extended_chordal_ring()`, `igraph_lcf()`

Time complexity: O(|V| |shifts|), the number of vertices in the graph times the number of shifts.

### 4.13. `igraph_extended_chordal_ring` — Create an extended chordal ring.

    igraph_error_t igraph_extended_chordal_ring(
        igraph_t *graph, igraph_int_t nodes, const igraph_matrix_int_t *W,
        igraph_bool_t directed);

An extended chordal ring is a cycle graph with additional chords connecting its vertices. Each row `L` of the matrix `W` specifies a set of chords to be inserted, in the following way: vertex `i` will connect to a vertex `L[(i mod p)]` steps ahead of it along the cycle, where `p` is the length of `L`. In other words, vertex `i` will be connected to vertex `(i + L[(i mod p)]) mod nodes`. If multiple edges are defined in this way, this will output a non-simple graph. The result can be simplified using `igraph_simplify()`.

See also Kotsis, G: Interconnection Topologies for Parallel Processing Systems, PARS Mitteilungen 11, 1-6, 1993. The igraph extended chordal rings are not identical to the ones in the paper. In igraph the matrix specifies which edges to add. In the paper, a condition is specified which should simultaneously hold between two endpoints and the reverse endpoints.

Arguments:

`graph`: | Pointer to an uninitialized graph object, the result will be stored here.
`nodes`: | Integer constant, the number of vertices in the graph. It must be at least 3.
`W`: | The matrix specifying the extra edges. The number of columns should divide the number of total vertices. The elements are allowed to be negative.
`directed`: | Whether the graph should be directed.

Returns:

`` | Error code.

See also:

`` | `igraph_ring()`, `igraph_lcf()`, `igraph_circulant()`

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

## 5. Tree generators

These functions generate tree graphs.

### 5.1. `igraph_kary_tree` — Creates a k-ary tree in which almost all vertices have k children.

    igraph_error_t igraph_kary_tree(igraph_t *graph, igraph_int_t n, igraph_int_t children,
                    igraph_tree_mode_t type);

To obtain a completely symmetric tree with `l` layers, where each vertex has precisely `children` descendants, use `n = (children^(l+1) - 1) / (children - 1)`. Such trees are often called `k`-ary trees, where `k` refers to the number of children.

Note that for `n=0`, the null graph is returned, which is not considered to be a tree by `igraph_is_tree()`.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`n`: | Integer, the number of vertices in the graph.
`children`: | Integer, the number of children of a vertex in the tree.
`type`: | Constant, gives whether to create a directed tree, and if this is the case, also its orientation. Possible values:
`IGRAPH_TREE_OUT` | directed tree, the edges point from the parents to their children.
`IGRAPH_TREE_IN` | directed tree, the edges point from the children to their parents.
`IGRAPH_TREE_UNDIRECTED` | undirected tree.

Returns:

`` | Error code: `IGRAPH_EINVAL`: invalid number of vertices. `IGRAPH_INVMODE`: invalid mode argument.

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

See also:

`` | `igraph_regular_tree()`, `igraph_symmetric_tree()` and `igraph_star()` for creating other regular structures; `igraph_from_prufer()` and `igraph_tree_from_parent_vector()` for creating arbitrary trees; `igraph_tree_game()` for uniform random sampling of trees; `igraph_realize_degree_sequence()` with `IGRAPH_REALIZE_DEGSEQ_SMALLEST` to create a tree with given degrees.

Example 11.7. 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;
    }

### 5.2. `igraph_symmetric_tree` — Creates a symmetric tree with the specified number of branches at each level.

    igraph_error_t igraph_symmetric_tree(igraph_t *graph, const igraph_vector_int_t *branches,
                    igraph_tree_mode_t type);

This function creates a tree in which all vertices at distance `d` from the root have `branching_counts`[d] children.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`branches`: | Vector detailing the number of branches at each level.
`type`: | Constant, gives whether to create a directed tree, and if this is the case, also its orientation. Possible values:
`IGRAPH_TREE_OUT` | directed tree, the edges point from the parents to their children.
`IGRAPH_TREE_IN` | directed tree, the edges point from the children to their parents.
`IGRAPH_TREE_UNDIRECTED` | undirected tree.

Returns:

`` | Error code: `IGRAPH_INVMODE`: invalid mode argument. `IGRAPH_EINVAL`: invalid number of children.

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

See also:

`` | `igraph_kary_tree()`, `igraph_regular_tree()` and `igraph_star()` for creating other regular tree structures; `igraph_from_prufer()` for creating arbitrary trees; `igraph_tree_game()` for uniform random sampling of trees.

Example 11.8. File `examples/simple/igraph_symmetric_tree.c`

    #include <igraph.h>

    int main(void) {

        igraph_t graph;
        igraph_bool_t res;
        igraph_vector_int_t v;
        igraph_vector_int_init_int(&v, 3, 3, 4, 5);

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

        /* Create a directed symmetric tree with 2 levels -
           3 children in first and 4 children in second level,
           5 children in third level
           with edges pointing towards the root. */
        igraph_symmetric_tree(&graph, &v, 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);
        igraph_vector_int_destroy(&v);

        return 0;
    }

### 5.3. `igraph_regular_tree` — Creates a regular tree.

    igraph_error_t igraph_regular_tree(igraph_t *graph, igraph_int_t h, igraph_int_t k, igraph_tree_mode_t type);

All vertices of a regular tree, except its leaves, have the same total degree `k`. This is different from a k-ary tree (`igraph_kary_tree()`), where all vertices have the same number of children, thus the degre of the root is one less than the degree of the other internal vertices. Regular trees are also referred to as Bethe lattices.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`h`: | The height of the tree, i.e. the distance between the root and the leaves.
`k`: | The degree of the regular tree.
`type`: | Constant, gives whether to create a directed tree, and if this is the case, also its orientation. Possible values:
`IGRAPH_TREE_OUT` | directed tree, the edges point from the parents to their children.
`IGRAPH_TREE_IN` | directed tree, the edges point from the children to their parents.
`IGRAPH_TREE_UNDIRECTED` | undirected tree.

Returns:

`` | Error code.

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

See also:

`` | `igraph_kary_tree()` to create k-ary tree where each vertex has the same number of children, i.e. out-degree, instead of the same total degree. `igraph_symmetric_tree()` to use a different number of children at each level.

Example 11.9. File `examples/simple/igraph_regular_tree.c`

    #include <igraph.h>

    int main(void) {
        igraph_t tree;
        igraph_vector_t eccentricity;
        igraph_bool_t is_tree;

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

        /* Create a Bethe lattice with 5 levels, i.e. height 4. */
        igraph_regular_tree(&tree, 4, 3, IGRAPH_TREE_UNDIRECTED);

        /* Bethe lattices are trees. */
        igraph_is_tree(&tree, &is_tree, NULL, IGRAPH_ALL);
        printf("Is it a tree? %s\n", is_tree ? "Yes." : "No.");

        /* Compute and print eccentricities. The root is the most central. */
        igraph_vector_init(&eccentricity, 0);
        igraph_eccentricity(&tree, NULL, &eccentricity, igraph_vss_all(), IGRAPH_ALL);
        printf("Vertex eccentricities:\n");
        igraph_vector_print(&eccentricity);
        igraph_vector_destroy(&eccentricity);

        /* Clean up. */
        igraph_destroy(&tree);

        return 0;
    }

### 5.4. `igraph_tree_from_parent_vector` — Constructs a tree or forest from a vector encoding the parent of each vertex.

    igraph_error_t igraph_tree_from_parent_vector(
            igraph_t *graph,
            const igraph_vector_int_t *parents,
            igraph_tree_mode_t type);

Rooted trees and forests are conveniently represented using a `parents` vector where the ID of the parent of vertex `v` is stored in `parents[v]`. This function serves to construct an igraph graph from a parent vector representation. The result is guaranteed to be a forest or a tree. If the `parents` vector is found to encode a cycle or a self-loop, an error is raised.

Several igraph functions produce such vectors, such as graph traversal functions (`igraph_bfs()` and `igraph_dfs()`), shortest path functions that construct a shortest path tree, as well as some other specialized functions like `igraph_dominator_tree()` or `igraph_cohesive_blocks()`. Vertices which do not have parents (i.e. roots) get a negative entry in the `parents` vector.

Use `igraph_bfs()` or `igraph_dfs()` to convert a forest into a parent vector representation. For trees, i.e. forests with a single root, it is more convenient to use `igraph_bfs_simple()`.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`parents`: | The parent vector. `parents[v]` is the ID of the parent vertex of `v`. `parents[v] < 0` indicates that `v` does not have a parent.
`type`: | Constant, gives whether to create a directed tree, and if this is the case, also its orientation. Possible values:
`IGRAPH_TREE_OUT` | directed tree, the edges point from the parents to their children.
`IGRAPH_TREE_IN` | directed tree, the edges point from the children to their parents.
`IGRAPH_TREE_UNDIRECTED undirected tree.` |

Returns:

`` | Error code.

See also:

`` | `igraph_bfs()`, `igraph_bfs_simple()` for back-conversion; `igraph_from_prufer()` for creating trees from Prüfer sequences; `igraph_is_tree()` and `igraph_is_forest()` to check if a graph is a tree or forest.

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

### 5.5. `igraph_from_prufer` — Generates a tree from a Prüfer sequence.

    igraph_error_t igraph_from_prufer(igraph_t *graph, const igraph_vector_int_t *prufer);

A Prüfer sequence is a unique sequence of integers associated with a labelled tree. A tree on `n` vertices can be represented by a sequence of `n-2` integers, each between `0` and `n-1` (inclusive). The algorithm used by this function is based on Paulius Micikevičius, Saverio Caminiti, Narsingh Deo: Linear-time Algorithms for Encoding Trees as Sequences of Node Labels

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`prufer`: | The Prüfer sequence

Returns:

`` | Error code:
`IGRAPH_ENOMEM` | there is not enough memory to perform the operation.
`IGRAPH_EINVAL` | invalid Prüfer sequence given

See also:

`` | `igraph_to_prufer()`, `igraph_kary_tree()`, `igraph_tree_game()`

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

## 6. Graphs with given degrees

These functions generate graphs with the specified degrees.

### 6.1. `igraph_realize_degree_sequence` — Generates a graph with the given degree sequence.

    igraph_error_t igraph_realize_degree_sequence(
            igraph_t *graph,
            const igraph_vector_int_t *outdeg, const igraph_vector_int_t *indeg,
            igraph_edge_type_sw_t allowed_edge_types,
            igraph_realize_degseq_t method);

This function generates an undirected graph that realizes a given degree sequence, or a directed graph that realizes a given pair of out- and in-degree sequences.

Simple undirected graphs are constructed using the Havel-Hakimi algorithm (undirected case), or the analogous Kleitman-Wang algorithm (directed case). These algorithms work by choosing an arbitrary vertex and connecting all its stubs to other vertices of highest degree. In the directed case, the "highest" (in, out) degree pairs are determined based on lexicographic ordering. This step is repeated until all degrees have been connected up.

Loopless multigraphs are generated using an analogous algorithm: an arbitrary vertex is chosen, and it is connected with a single connection to a highest remaining degee vertex. If self-loops are also allowed, the same algorithm is used, but if a non-zero vertex remains at the end of the procedure, the graph is completed by adding self-loops to it. Thus, the result will contain at most one vertex with self-loops.

The `method` parameter controls the order in which the vertices to be connected are chosen. In the undirected case, `IGRAPH_REALIZE_DEGSEQ_SMALLEST` produces a connected graph when one exists. This makes this method suitable for constructing trees with a given degree sequence.

For a undirected simple graph, the time complexity is O(V + alpha(V) * E). For an undirected multi graph, the time complexity is O(V * E + V log V). For a directed graph, the time complexity is O(E + V^2 log V).

References:

V. Havel: Poznámka o existenci konečných grafů (A remark on the existence of finite graphs), Časopis pro pěstování matematiky 80, 477-480 (1955). http://eudml.org/doc/19050

S. L. Hakimi: On Realizability of a Set of Integers as Degrees of the Vertices of a Linear Graph, Journal of the SIAM 10, 3 (1962). https://www.jstor.org/stable/2098770

D. J. Kleitman and D. L. Wang: Algorithms for Constructing Graphs and Digraphs with Given Valences and Factors, Discrete Mathematics 6, 1 (1973). https://doi.org/10.1016/0012-365X%2873%2990037-X P. L. Erdős, I. Miklós, Z. Toroczkai: A simple Havel-Hakimi type algorithm to realize graphical degree sequences of directed graphs, The Electronic Journal of Combinatorics 17.1 (2010). http://eudml.org/doc/227072

Sz. Horvát and C. D. Modes: Connectedness matters: construction and exact random sampling of connected networks (2021). https://doi.org/10.1088/2632-072X/abced5

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`outdeg`: | The degree sequence of an undirected graph (if `indeg` is NULL), or the out-degree sequence of a directed graph (if `indeg` is given).
`indeg`: | The in-degree sequence of a directed graph. Pass `NULL` to generate an undirected graph.
`allowed_edge_types`: | The types of edges to allow in the graph. See `igraph_edge_type_sw_t`. For directed graphs, only `IGRAPH_SIMPLE_SW` is implemented at this moment. For undirected graphs, the following values are valid:
`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; currently not implemented.
`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.
`method`: | The method to generate the graph. Possible values:
`IGRAPH_REALIZE_DEGSEQ_SMALLEST` | The vertex with smallest remaining degree is selected first. The result is usually a graph with high negative degree assortativity. In the undirected case, this method is guaranteed to generate a connected graph, regardless of whether multi-edges are allowed, provided that a connected realization exists (see Horvát and Modes, 2021, as well as http://szhorvat.net/pelican/hh-connected-graphs.html). This method can be used to construct a tree from its degrees. In the directed case it tends to generate weakly connected graphs, but this is not guaranteed.
`IGRAPH_REALIZE_DEGSEQ_LARGEST` | The vertex with the largest remaining degree is selected first. The result is usually a graph with high positive degree assortativity, and is often disconnected.
`IGRAPH_REALIZE_DEGSEQ_INDEX` | The vertices are selected in order of their index (i.e. their position in the degree vector). Note that sorting the degree vector and using the `INDEX` method is not equivalent to the `SMALLEST` method above, as `SMALLEST` uses the smallest remaining degree for selecting vertices, not the smallest initial degree.

Returns:

`` | Error code:
`IGRAPH_UNIMPLEMENTED` | The requested method is not implemented.
`IGRAPH_ENOMEM` | There is not enough memory to perform the operation.
`IGRAPH_EINVAL` | Invalid method parameter, or invalid in- and/or out-degree vectors. The degree vectors should be non-negative, the length and sum of `outdeg` and `indeg` should match for directed graphs.

See also:

`` | `igraph_is_graphical()` to test graphicality without generating a graph; `igraph_realize_bipartite_degree_sequence()` to create bipartite graphs from two degree sequence; `igraph_degree_sequence_game()` to generate random graphs with a given degree sequence; `igraph_k_regular_game()` to generate random regular graphs; `igraph_rewire()` to randomly rewire the edges of a graph while preserving its degree sequence.

Example 11.10. File `examples/simple/igraph_realize_degree_sequence.c`

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

    int main(void){
        igraph_t g1, g2, g3;
        igraph_int_t nodes = 500, A = 0, power = 1, m = 1;
        igraph_real_t assortativity;

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

        igraph_rng_seed(igraph_rng_default(), 42);
        printf("Demonstration of difference in assortativities of graphs with the same degree sequence but different linkages:\n\nInitial graph based on the Barabasi-Albert model with %" IGRAPH_PRId " nodes.\n", nodes);

        /* Graph 1 generated by a randomized graph generator */
        igraph_barabasi_game(&g1, nodes, power, m, NULL, /* outpref */ 0, A, IGRAPH_UNDIRECTED, IGRAPH_BARABASI_PSUMTREE, /* start from */ NULL);

        igraph_vector_int_t degree;
        igraph_vector_int_init(&degree, nodes);
        igraph_degree(&g1, &degree, igraph_vss_all(), IGRAPH_ALL, IGRAPH_NO_LOOPS);

        /* Measuring assortativity of the first graph */
        igraph_assortativity_degree(&g1, &assortativity, IGRAPH_UNDIRECTED);
        printf("Assortativity of initial graph = %g\n\n", assortativity);
        igraph_destroy(&g1);

        /* Graph 2 (with the same degree sequence) generated by selecting vertices with the smallest degree first */
        igraph_realize_degree_sequence(&g2, &degree, NULL, IGRAPH_SIMPLE_SW, IGRAPH_REALIZE_DEGSEQ_SMALLEST);
        igraph_assortativity_degree(&g2, &assortativity, IGRAPH_UNDIRECTED);
        printf("Assortativity after choosing vertices with the smallest degrees first = %g\n\n", assortativity);
        igraph_destroy(&g2);

        /* Graph 3 (with the same degree sequence) generated by selecting vertices with the largest degree first */
        igraph_realize_degree_sequence(&g3, &degree, NULL, IGRAPH_SIMPLE_SW, IGRAPH_REALIZE_DEGSEQ_LARGEST);
        igraph_assortativity_degree(&g3, &assortativity, IGRAPH_UNDIRECTED);
        printf("Assortativity after choosing vertices with the largest degrees first = %g\n", assortativity);
        igraph_destroy(&g3);
        igraph_vector_int_destroy(&degree);

        return 0;
    }

### 6.2. `igraph_realize_bipartite_degree_sequence` — Generates a bipartite graph with the given bidegree sequence.

    igraph_error_t igraph_realize_bipartite_degree_sequence(
        igraph_t *graph,
        const igraph_vector_int_t *degrees1, const igraph_vector_int_t *degrees2,
        const igraph_edge_type_sw_t allowed_edge_types, const igraph_realize_degseq_t method
    );

This function generates a bipartite graph with the given bidegree sequence, using a Havel-Hakimi-like construction algorithm. The order in which vertices are connected up is controlled by the `method` parameter. When using the `IGRAPH_REALIZE_DEGSEQ_SMALLEST` method, it is ensured that the graph will be connected if and only if the given bidegree sequence is potentially connected.

The vertices of the graph will be ordered so that those having `degrees1` come first, followed by `degrees2`.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`degrees1`: | The degree sequence of the first partition.
`degrees2`: | The degree sequence of the second partition.
`allowed_edge_types`: | The types of edges to allow in the graph.
`IGRAPH_SIMPLE_SW` | simple graph (i.e. no multi-edges allowed).
`IGRAPH_MULTI_SW` | multi-edges are allowed
`method`: | Controls the order in which vertices are selected for connection. Possible values:
`IGRAPH_REALIZE_DEGSEQ_SMALLEST` | The vertex with smallest remaining degree is selected first, from either partition. The result is usually a graph with high negative degree assortativity. This method is guaranteed to generate a connected graph, if one exists.
`IGRAPH_REALIZE_DEGSEQ_LARGEST` | The vertex with the largest remaining degree is selected first, from either parition. The result is usually a graph with high positive degree assortativity, and is often disconnected.
`IGRAPH_REALIZE_DEGSEQ_INDEX` | The vertices are selected in order of their index.

Returns:

`` | Error code.

See also:

`` | `igraph_is_bigraphical()` to test bigraphicality without generating a graph.

## 7. Complete graphs

These functions produce single and multipartite complete graphs, as well as related graphs.

### 7.1. `igraph_full` — Creates a full graph (complete graph).

    igraph_error_t igraph_full(igraph_t *graph, igraph_int_t n, igraph_bool_t directed,
                    igraph_bool_t loops);

In a full graph every possible edge is present: every vertex is connected to every other vertex. igraph generalizes the usual concept of complete graphs in graph theory to graphs with self-loops as well as to directed graphs.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`n`: | Integer, the number of vertices in the graph.
`directed`: | Whether to create a directed graph.
`loops`: | Whether to include self-loops.

Returns:

`` | Error code: `IGRAPH_EINVAL`: invalid number of vertices.

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

See also:

`` | `igraph_square_lattice()`, `igraph_star()`, `igraph_kary_tree()` for creating other regular structures.

Example 11.11. File `examples/simple/igraph_full.c`

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

    int main(void) {
        igraph_t graph;
        igraph_int_t n_vertices = 10;

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

        /* Create an undirected complete graph. */
        /* Use IGRAPH_UNDIRECTED and IGRAPH_NO_LOOPS instead of true and false for better readability. */
        igraph_full(&graph, n_vertices, IGRAPH_UNDIRECTED, IGRAPH_NO_LOOPS);
        printf("The undirected complete graph on %" IGRAPH_PRId " vertices has %" IGRAPH_PRId " edges.\n",
              igraph_vcount(&graph), igraph_ecount(&graph));

        /* Remember to destroy the object at the end. */
        igraph_destroy(&graph);

        /* Create a directed complete graph. */
        igraph_full(&graph, n_vertices, IGRAPH_DIRECTED, IGRAPH_NO_LOOPS);
        printf("The directed complete graph on %" IGRAPH_PRId " vertices has %" IGRAPH_PRId " edges.\n",
              igraph_vcount(&graph), igraph_ecount(&graph));

        igraph_destroy(&graph);

        /* Create an undirected complete graph with self-loops. */
        igraph_full(&graph, n_vertices, IGRAPH_UNDIRECTED, IGRAPH_LOOPS);
        printf("The undirected complete graph on %" IGRAPH_PRId " vertices with self-loops has %" IGRAPH_PRId " edges.\n",
              igraph_vcount(&graph), igraph_ecount(&graph));

        igraph_destroy(&graph);

        /* Create a directed graph with self-loops. */
        igraph_full(&graph, n_vertices, IGRAPH_DIRECTED, IGRAPH_LOOPS);
        printf("The directed complete graph on %" IGRAPH_PRId " vertices with self-loops has %" IGRAPH_PRId " edges.\n",
              igraph_vcount(&graph), igraph_ecount(&graph));

        igraph_destroy(&graph);

        return 0;

    }

### 7.2. `igraph_full_citation` — Creates a full citation graph (a complete directed acyclic graph).

    igraph_error_t igraph_full_citation(igraph_t *graph, igraph_int_t n,
                             igraph_bool_t directed);

This is a directed graph, where every `i->j` edge is present if and only if `j<i`. If the `directed` argument is false then an undirected graph is created, and it is just a complete graph.

Arguments:

`graph`: | Pointer to an uninitialized graph object, the result is stored here.
`n`: | The number of vertices.
`directed`: | Whether to created a directed graph. If false an undirected graph is created.

Returns:

`` | Error code.

See also:

`` | `igraph_full()`

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

### 7.3. `igraph_full_multipartite` — Creates a full multipartite graph.

    igraph_error_t igraph_full_multipartite(igraph_t *graph,
                              igraph_vector_int_t *types,
                              const igraph_vector_int_t *n,
                              igraph_bool_t directed,
                              igraph_neimode_t mode);

A multipartite graph contains two or more types of vertices and connections are only possible between two vertices of different types. This function creates a complete multipartite graph.

Arguments:

`graph`: | Pointer to an uninitialized graph object, the graph will be created here.
`types`: | Pointer to an integer vector. If not a null pointer, the type of each vertex will be stored here.
`n`: | Pointer to an integer vector, the number of vertices of each type.
`directed`: | Boolean, whether to create a directed graph.
`mode`: | A constant that gives the type of connections for directed graphs. If `IGRAPH_OUT`, then edges point from vertices of low-index vertices to high-index vertices; if `IGRAPH_IN`, then the opposite direction is realized; `IGRAPH_ALL`, then mutual edges will be created.

Returns:

`` | Error code.

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

See also:

`` | `igraph_full_bipartite()` for complete bipartite graphs, `igraph_turan()` for Turán graphs.

### 7.4. `igraph_turan` — Creates a Turán graph.

    igraph_error_t igraph_turan(igraph_t *graph,
                                igraph_vector_int_t *types,
                                igraph_int_t n,
                                igraph_int_t r);

Turán graphs are complete multipartite graphs with the property that the sizes of the partitions are as close to equal as possible.

The Turán graph with `n` vertices and `r` partitions is the densest graph on `n` vertices that does not contain a clique of size `r+1`.

This function generates undirected graphs. The null graph is returned when the number of vertices is zero. A complete graph is returned if the number of partitions is greater than the number of vertices.

Arguments:

`graph`: | Pointer to an igraph_t object, the graph will be created here.
`types`: | Pointer to an integer vector. If not a null pointer, the type (partition index) of each vertex will be stored here.
`n`: | Integer, the number of vertices in the graph.
`r`: | Integer, the number of partitions of the graph, must be positive.

Returns:

`` | Error code.

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

See also:

`` | `igraph_full_multipartite()` for full multipartite graphs.

## 8. Pre-defined graphs

These functions return graphs from various graph collections.

### 8.1. `igraph_famous` — Create a famous graph by simply providing its name.

    igraph_error_t igraph_famous(igraph_t *graph, const char *name);

The name of the graph can be simply supplied as a string. Note that this function creates graphs which don't take any parameters, there are separate functions for graphs with parameters, e.g. `igraph_full()` for creating a full graph.

The following graphs are supported:

`Bull` | The bull graph, 5 vertices, 5 edges, resembles the head of a bull if drawn properly.
`Chvatal` | This is the smallest triangle-free graph that is both 4-chromatic and 4-regular. According to the Grunbaum conjecture there exists an m-regular, m-chromatic graph with n vertices for every m>1 and n>2. The Chvatal graph is an example for m=4 and n=12. It has 24 edges.
`Coxeter` | A non-Hamiltonian cubic symmetric graph with 28 vertices and 42 edges.
`Cubical` | The Platonic graph of the cube. A convex regular polyhedron with 8 vertices and 12 edges.
`Diamond` | A graph with 4 vertices and 5 edges, resembles a schematic diamond if drawn properly.
`Dodecahedral, Dodecahedron` | Another Platonic solid with 20 vertices and 30 edges.
`Folkman` | The semisymmetric graph with minimum number of vertices, 20 and 40 edges. A semisymmetric graph is regular, edge transitive and not vertex transitive.
`Franklin` | This is a graph whose embedding to the Klein bottle can be colored with six colors, it is a counterexample to the necessity of the Heawood conjecture on a Klein bottle. It has 12 vertices and 18 edges.
`Frucht` | The Frucht Graph is the smallest cubical graph whose automorphism group consists only of the identity element. It has 12 vertices and 18 edges.
`Grotzsch, Groetzsch` | The Grötzsch graph is a triangle-free graph with 11 vertices, 20 edges, and chromatic number 4. It is named after German mathematician Herbert Grötzsch, and its existence demonstrates that the assumption of planarity is necessary in Grötzsch's theorem that every triangle-free planar graph is 3-colorable.
`Heawood` | The Heawood graph is an undirected graph with 14 vertices and 21 edges. The graph is cubic, and all cycles in the graph have six or more edges. Every smaller cubic graph has shorter cycles, so this graph is the 6-cage, the smallest cubic graph of girth 6.
`Herschel` | The Herschel graph is the smallest nonhamiltonian polyhedral graph. It is the unique such graph on 11 nodes, and has 18 edges.
`House` | The house graph is a 5-vertex, 6-edge graph, the schematic draw of a house if drawn properly, basically a triangle on top of a square.
`HouseX` | The same as the house graph with an X in the square. 5 vertices and 8 edges.
`Icosahedral, Icosahedron` | A Platonic solid with 12 vertices and 30 edges.
`Krackhardt_Kite` | A social network with 10 vertices and 18 edges. Krackhardt, D. Assessing the Political Landscape: Structure, Cognition, and Power in Organizations. Admin. Sci. Quart. 35, 342-369, 1990.
`Levi` | The graph is a 4-arc transitive cubic graph, it has 30 vertices and 45 edges.
`McGee` | The McGee graph is the unique 3-regular 7-cage graph, it has 24 vertices and 36 edges.
`Meredith` | The Meredith graph is a quartic graph on 70 nodes and 140 edges that is a counterexample to the conjecture that every 4-regular 4-connected graph is Hamiltonian.
`Noperfectmatching` | A connected graph with 16 vertices and 27 edges containing no perfect matching. A matching in a graph is a set of pairwise non-incident edges; that is, no two edges share a common vertex. A perfect matching is a matching which covers all vertices of the graph.
`Nonline` | A graph whose connected components are the 9 graphs whose presence as a vertex-induced subgraph in a graph makes a nonline graph. It has 50 vertices and 72 edges.
`Octahedral, Octahedron` | Platonic solid with 6 vertices and 12 edges.
`Petersen` | A 3-regular graph with 10 vertices and 15 edges. It is the smallest hypohamiltonian graph, i.e. it is non-hamiltonian but removing any single vertex from it makes it Hamiltonian.
`Robertson` | The unique (4,5)-cage graph, i.e. a 4-regular graph of girth 5. It has 19 vertices and 38 edges.
`Smallestcyclicgroup` | A smallest nontrivial graph whose automorphism group is cyclic. It has 9 vertices and 15 edges.
`Tetrahedral, Tetrahedron` | Platonic solid with 4 vertices and 6 edges.
`Thomassen` | The smallest hypotraceable graph, on 34 vertices and 52 edges. A hypotracable graph does not contain a Hamiltonian path but after removing any single vertex from it the remainder always contains a Hamiltonian path. A graph containing a Hamiltonian path is called traceable.
`Tutte` | Tait's Hamiltonian graph conjecture states that every 3-connected 3-regular planar graph is Hamiltonian. This graph is a counterexample. It has 46 vertices and 69 edges.
`Uniquely3colorable` | Returns a 12-vertex, triangle-free graph with chromatic number 3 that is uniquely 3-colorable.
`Walther` | An identity graph with 25 vertices and 31 edges. An identity graph has a single graph automorphism, the trivial one.
`Zachary` | Social network of friendships between 34 members of a karate club at a US university in the 1970s. See W. W. Zachary, An information flow model for conflict and fission in small groups, Journal of Anthropological Research 33, 452-473 (1977).

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`name`: | Character constant, the name of the graph to be created, it is case insensitive.

Returns:

`` | Error code, `IGRAPH_EINVAL` if there is no graph with the given name.

See also:

`` | Other functions for creating graph structures: `igraph_ring()`, `igraph_kary_tree()`, `igraph_square_lattice()`, `igraph_full()`.

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

### 8.2. `igraph_atlas` — Create a small graph from the “Graph Atlas”.

    igraph_error_t igraph_atlas(igraph_t *graph, igraph_int_t number);

The graph atlas contains all simple undirected unlabeled graphs on between 0 and 7 vertices. The number of the graph is given as a parameter. The graphs are listed:

1. in increasing order of number of vertices;

2. for a fixed number of vertices, in increasing order of the number of edges;

3. for fixed numbers of vertices and edges, in lexicographically increasing order of the degree sequence, for example 111223 < 112222;

4. for fixed degree sequence, in increasing number of automorphisms.

The data was converted from the NetworkX software package, see https://networkx.org/.

See An Atlas of Graphs by Ronald C. Read and Robin J. Wilson, Oxford University Press, 1998.

Arguments:

`graph`: | Pointer to an uninitialized graph object.
`number`: | The number of the graph to generate. Must be between 0 and 1252 (inclusive). Graphs on 0-7 vertices start at numbers 0, 1, 2, 4, 8, 19, 53, and 209, respectively.

Returns:

`` | Error code.

Added in version 0.2.

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

Example 11.12. File `examples/simple/igraph_atlas.c`

    #include <igraph.h>

    int main(void) {
        igraph_t g;

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

        igraph_atlas(&g, 45);
        igraph_write_graph_edgelist(&g, stdout);
        printf("\n");
        igraph_destroy(&g);

        igraph_atlas(&g, 0);
        igraph_write_graph_edgelist(&g, stdout);
        printf("\n");
        igraph_destroy(&g);

        igraph_atlas(&g, 1252);
        igraph_write_graph_edgelist(&g, stdout);
        printf("\n");
        igraph_destroy(&g);

        return 0;
    }

## 9. Other well-known graphs from graph theory

### 9.1. `igraph_de_bruijn` — Generate a de Bruijn graph.

    igraph_error_t igraph_de_bruijn(igraph_t *graph, igraph_int_t m, igraph_int_t n);

A de Bruijn graph represents relationships between strings. An alphabet of `m` letters are used and strings of length `n` are considered. A vertex corresponds to every possible string and there is a directed edge from vertex `v` to vertex `w` if the string of `v` can be transformed into the string of `w` by removing its first letter and appending a letter to it.

Please note that the graph will have `m` to the power `n` vertices and even more edges, so probably you don't want to supply too big numbers for `m` and `n`.

De Bruijn graphs have some interesting properties, please see another source, e.g. Wikipedia for details.

Arguments:

`graph`: | Pointer to an uninitialized graph object, the result will be stored here.
`m`: | Integer, the number of letters in the alphabet.
`n`: | Integer, the length of the strings.

Returns:

`` | Error code.

See also:

`` | `igraph_kautz()`.

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

### 9.2. `igraph_kautz` — Generate a Kautz graph.

    igraph_error_t igraph_kautz(igraph_t *graph, igraph_int_t m, igraph_int_t n);

A Kautz graph is a labeled graph, vertices are labeled by strings of length `n`+1 above an alphabet with `m`+1 letters, with the restriction that every two consecutive letters in the string must be different. There is a directed edge from a vertex `v` to another vertex `w` if it is possible to transform the string of `v` into the string of `w` by removing the first letter and appending a letter to it. For string length 1 the new letter cannot equal the old letter, so there are no loops.

Kautz graphs have some interesting properties, see e.g. Wikipedia for details.

Vincent Matossian wrote the first version of this function in R, thanks.

Arguments:

`graph`: | Pointer to an uninitialized graph object, the result will be stored here.
`m`: | Integer, `m`+1 is the number of letters in the alphabet.
`n`: | Integer, `n`+1 is the length of the strings.

Returns:

`` | Error code.

See also:

`` | `igraph_de_bruijn()`.

Time complexity: O(|V|* [(m+1)/m]^n +|E|), in practice it is more like O(|V|+|E|). |V| is the number of vertices, |E| is the number of edges and `m` and `n` are the corresponding arguments.

### 9.3. `igraph_generalized_petersen` — Creates a Generalized Petersen graph.

    igraph_error_t igraph_generalized_petersen(igraph_t *graph, igraph_int_t n, igraph_int_t k);

The generalized Petersen graph `G(n, k)` consists of `n` vertices `v_0`, ..., `v_n` forming an "outer" cycle graph, and `n` additional vertices `u_0`, ..., `u_n` forming an "inner" circulant graph where `u_i` is connected to `u_(i + k mod n)`. Additionally, all `v_i` are connected to `u_i`.

`G(n, k)` has `2n` vertices and `3n` edges. The Petersen graph itself is `G(5, 2)`.

Reference:

M. E. Watkins, A Theorem on Tait Colorings with an Application to the Generalized Petersen Graphs, Journal of Combinatorial Theory 6, 152-164 (1969). https://doi.org/10.1016%2FS0021-9800%2869%2980116-X

Arguments:

`graph`: | Pointer to an uninitialized graph object, the result will be stored here.
`n`: | Integer, `n` is the number of vertices in the inner and outer cycle/circulant graphs. It must be at least 3.
`k`: | Integer, `k` is the shift of the circulant graph. It must be positive and less than `n/2`.

Returns:

`` | Error code.

See also:

`` | `igraph_famous()` for the original Petersen graph.

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

### 9.4. `igraph_mycielski_graph` — The Mycielski graph of order `k`.

    igraph_error_t igraph_mycielski_graph(igraph_t *graph, igraph_int_t k);

The Mycielski graph of order `k`, denoted `M_k`, is a triangle-free graph on `k` vertices with chromatic number `k`. It is defined through the Mycielski construction described in the documentation of `igraph_mycielskian()`.

Some authors define Mycielski graphs only for `k > 1`. igraph extends this to all `k >= 0`. The first few Mycielski graphs are:

1. M_0: Null graph

2. M_1: Single vertex

3. M_2: Path graph with 2 vertices

4. M_3: Cycle graph with 5 vertices

5. M_4: Grötzsch graph (a triangle-free graph with chromatic number 4)

The vertex count of `M_k` is `n_k = 3 * 2^(k-2) - 1` for `k > 1` and `k` otherwise. The edge count is `m_k = (7 * 3^(k-2) + 1) / 2 - 3 * 2^(k - 2)` for `k > 1` and 0 otherwise.

Arguments:

`graph`: | Pointer to an uninitialized graph object. The generated Mycielski graph will be stored here.
`k`: | Integer, the order of the Mycielski graph (must be non-negative).

Returns:

`` | Error code.

See also:

`` | `igraph_mycielskian()`.

Time complexity: O(3^k), i.e. exponential in `k`.