vendor: Update vendored sources to igraph/igraph@bd7b3a8

doc: several documentation improvements and cross-referencing

Author: krlmlr

src/vendor/cigraph/src/constructors/circulant.c

@@ -41,9 +41,10 @@
  * \param directed Boolean, whether to create a directed graph.
  * \return Error code.
  *
- * \sa \ref igraph_ring(), \ref igraph_generalized_petersen(), \ref igraph_extended_chordal_ring()
+ * \sa \ref igraph_ring(), \ref igraph_generalized_petersen(),
+ * \ref igraph_extended_chordal_ring(), \ref igraph_lcf()
  *
- * Time complexity: O(|V||shifts|), the number of vertices in the graph times the number
+ * Time complexity: O(|V| |shifts|), the number of vertices in the graph times the number
  * of shifts.
  */
 

src/vendor/cigraph/src/constructors/lattices.c

@@ -251,45 +251,47 @@ static igraph_error_t triangular_lattice_hex_shape(
  *
  * \experimental
  *
- * 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 \ref 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 \ref igraph_hexagonal_lattice()
+ * 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 \ref 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 \ref igraph_hexagonal_lattice()
  * with the same \p dims parameter.
  *
  * </para><para>
- * The vertices of the resulting graph are ordered lexicographically with the 2nd coordinate being
- * more significant, e.g., (i, j) &lt; (i + 1, j) and (i + 1, j) &lt; (i, j + 1)
+ * The vertices of the resulting graph are ordered lexicographically with the 2nd
+ * coordinate being more significant, e.g., (i, j) &lt; (i + 1, j) and
+ * (i + 1, j) &lt; (i, j + 1)
  *
  * \param graph An uninitialized graph object.
- * \param dims Integer vector, defines the shape of the lattice. (Below the "edge length"s are in terms of graph theoretical path lengths.)
- *        If \p dims is of length 1, the resulting lattice has a triangular shape
- *        where each side of the triangle contains <code>dims[0]</code> vertices.
- *        If \p dims is of length 2, the resulting lattice has a
- *        "quasi rectangular" shape with the sides containing <code>dims[0]</code> and
- *        <code>dims[1]</code> vertices, respectively.
- *        If \p dims is of length 3, the resulting lattice has a hexagonal shape
- *        where the sides of the hexagon contain <code>dims[0]</code>, <code>dims[1]</code> and
- *        <code>dims[2]</code> vertices.
- *        All coordinates must be non-negative.
+ * \param dims Integer vector, defines the shape of the lattice.
+ *    If \p dims is of length 1, the resulting lattice has a triangular shape
+ *    where each side of the triangle contains <code>dims[0]</code> vertices.
+ *    If \p dims is of length 2, the resulting lattice has a
+ *    "quasi rectangular" shape with the sides containing <code>dims[0]</code> and
+ *    <code>dims[1]</code> vertices, respectively.
+ *    If \p dims is of length 3, the resulting lattice has a hexagonal shape
+ *    where the sides of the hexagon contain <code>dims[0]</code>, <code>dims[1]</code>
+ *    and <code>dims[2]</code> vertices. All dimensions must be non-negative.
  * \param directed Boolean, whether to create a directed graph.
- *        If the \c mutual argument is not set to true,
- *        edges will be directed from lower-index vertices towards
- *        higher-index ones.
+ *    If the \c mutual argument is not set to true, edges will be directed from
+ *    lower-index vertices towards higher-index ones.
  * \param mutual Boolean, if the graph is directed this gives whether
- *        to create all connections as mutual.
+ *    to create all connections as mutual.
  * \return Error code:
- *         \c IGRAPH_EINVAL: The size of \p dims must be either 1, 2, or 3 with all the components
- *         at least 1.
- * \sa \ref igraph_hexagonal_lattice() for creating a triangular lattice.
+ *    \c IGRAPH_EINVAL: The size of \p dims must be either 1, 2, or 3 with all
+ *    the components at least 1.
+ *
+ * \sa \ref igraph_hexagonal_lattice() and \ref igraph_square_lattice() for creating
+ * other types of lattices; \ref igraph_regular_tree() to create a Bethe lattice.
  *
  * Time complexity:  O(|V|), where |V| is the number of vertices in the generated graph.
  *
  */
 igraph_error_t igraph_triangular_lattice(
-    igraph_t *graph, const igraph_vector_int_t *dims, igraph_bool_t directed,
-    igraph_bool_t mutual) {
+        igraph_t *graph, const igraph_vector_int_t *dims,
+        igraph_bool_t directed, igraph_bool_t mutual) {
     igraph_integer_t num_dims = igraph_vector_int_size(dims);
     if (igraph_vector_int_any_smaller(dims, 0)) {
         IGRAPH_ERROR("Invalid dimension vector.", IGRAPH_EINVAL);
@@ -534,46 +536,46 @@ static igraph_error_t hexagonal_lattice_hex_shape(
  *
  * \experimental
  *
- * 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 \ref 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 \ref igraph_triangular_lattice() function
+ * 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 \ref 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 \ref igraph_triangular_lattice() function
  * with the same \p dims parameter.
  *
  * </para><para>
- * The vertices of the resulting graph are ordered lexicographically with the 2nd coordinate being
- * more significant, e.g., (i, j) &lt; (i + 1, j) and (i + 1, j) &lt; (i, j + 1)
+ * The vertices of the resulting graph are ordered lexicographically with the 2nd
+ * coordinate being more significant, e.g., (i, j) &lt; (i + 1, j) and
+ * (i + 1, j) &lt; (i, j + 1)
  *
  * \param graph An uninitialized graph object.
- * \param dims Integer vector, defines the shape of the lattice. (Below the "edge length"s are in terms of graph theoretical path lengths.)
- *        If \p dims is of length 1, the resulting lattice has a triangular shape
- *        where each side of the triangle contains <code>dims[0]</code> vertices.
- *        If \p dims is of length 2, the resulting lattice has a
- *        "quasi rectangular" shape with the sides containing <code>dims[0]</code> and
- *        <code>dims[1]</code> vertices, respectively.
- *        If \p dims is of length 3, the resulting lattice has a hexagonal shape
- *        where the sides of the hexagon contain <code>dims[0]</code>, <code>dims[1]</code> and
- *        <code>dims[2]</code> vertices.
- *        All coordinates must be non-negative.
+ * \param dims Integer vector, defines the shape of the lattice.
+ *   If \p dims is of length 1, the resulting lattice has a triangular shape
+ *   where each side of the triangle contains <code>dims[0]</code> vertices.
+ *   If \p dims is of length 2, the resulting lattice has a "quasi rectangular"
+ *   shape with the sides containing <code>dims[0]</code> and <code>dims[1]</code>
+ *   vertices, respectively. If \p dims is of length 3, the resulting lattice has
+ *   a hexagonal shape where the sides of the hexagon contain <code>dims[0]</code>,
+ *   <code>dims[1]</code> and <code>dims[2]</code> vertices. All coordinates must
+ *   be non-negative.
  * \param directed Boolean, whether to create a directed graph.
- *        If the \c mutual argument is not set to true,
- *        edges will be directed from lower-index vertices towards
- *        higher-index ones.
- * \param mutual Boolean, if the graph is directed this gives whether
- *        to create all connections as mutual.
+ *   If the \c mutual argument is not set to true, edges will be directed from
+ *   lower-index vertices towards higher-index ones.
+ * \param mutual Boolean, if the graph is directed this gives whether to create
+ *   all connections as mutual.
  * \return Error code:
- *         \c IGRAPH_EINVAL: The size of \p dims must be either 1, 2, or 3 with all the components
- *         at least 1.
- * \sa \ref igraph_triangular_lattice() for creating a triangular lattice.
+ *   \c IGRAPH_EINVAL: The size of \p dims must be either 1, 2, or 3 with all
+ *   the components at least 1.
  *
- * Time complexity:  O(|V|), where |V| is the number of vertices in the generated graph.
+ * \sa \ref igraph_triangular_lattice() and \ref igraph_square_lattice() for creating
+ * other types of lattices; ; \ref igraph_regular_tree() to create a Bethe lattice.
  *
+ * Time complexity:  O(|V|), where |V| is the number of vertices in the generated graph.
  */
 igraph_error_t igraph_hexagonal_lattice(
-    igraph_t *graph, const igraph_vector_int_t *dims, igraph_bool_t directed,
-    igraph_bool_t mutual
-) {
+        igraph_t *graph, const igraph_vector_int_t *dims,
+        igraph_bool_t directed, igraph_bool_t mutual) {
     igraph_integer_t num_dims = igraph_vector_int_size(dims);
     if (igraph_vector_int_any_smaller(dims, 0)) {
         IGRAPH_ERROR("Invalid dimension vector.", IGRAPH_EINVAL);

src/vendor/cigraph/src/constructors/lcf.c

@@ -112,8 +112,9 @@ igraph_error_t igraph_lcf_vector(igraph_t *graph, igraph_integer_t n,
  *        plus an additional 0 to mark the end of the arguments.
  * \return Error code.
  *
- * \sa See \ref igraph_lcf_vector() for a similar function using a
- * vector_t instead of the variable length argument list.
+ * \sa See \ref igraph_lcf_vector() for a similar function using an
+ * \ref igraph_vector_t instead of the variable length argument list;
+ * \ref igraph_circulant() to create circulant graphs.
  *
  * Time complexity: O(|V|+|E|), the number of vertices plus the number
  * of edges.

src/vendor/cigraph/src/constructors/regular.c

@@ -66,7 +66,7 @@
  * Time complexity: O(|V|), the
  * number of vertices in the graph.
  *
- * \sa \ref igraph_square_lattice(), \ref igraph_ring(), \ref igraph_kary_tree()
+ * \sa \ref igraph_wheel(), \ref igraph_square_lattice(), \ref igraph_ring(), \ref igraph_kary_tree()
  * for creating other regular structures.
  *
  * \example examples/simple/igraph_star.c
@@ -346,6 +346,11 @@ igraph_error_t igraph_lattice(igraph_t *graph, const igraph_vector_int_t *dimvec
  *         \c IGRAPH_EINVAL: invalid (negative) dimension vector or mismatch
  *         between the length of the dimension vector and the periodicity vector.
  *
+ * \sa \ref igraph_hypercube() to create a hypercube graph; \ref igraph_ring()
+ * to create a cycle graph or path graph; \ref igraph_triangular_lattice()
+ * and \ref igraph_hexagonal_lattice() to create other types of lattices;
+ * \ref igraph_regular_tree() to create a Bethe lattice.
+ *
  * Time complexity: If \p 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
@@ -504,7 +509,8 @@ igraph_error_t igraph_square_lattice(
  *
  * Time complexity: O(|V|), the number of vertices in the graph.
  *
- * \sa \ref igraph_square_lattice() for generating more general lattices.
+ * \sa \ref igraph_square_lattice() for generating more general
+ * (periodic or non-periodic) lattices.
  *
  * \example examples/simple/igraph_ring.c
  */
@@ -605,7 +611,9 @@ igraph_error_t igraph_ring(igraph_t *graph, igraph_integer_t n, igraph_bool_t di
  * \sa \ref igraph_regular_tree(), \ref igraph_symmetric_tree() and \ref igraph_star()
  * for creating other regular structures; \ref igraph_from_prufer() and
  * \ref igraph_tree_from_parent_vector() for creating arbitrary trees;
- * \ref igraph_tree_game() for uniform random sampling of trees.
+ * \ref igraph_tree_game() for uniform random sampling of trees;
+ * \ref igraph_realize_degree_sequence() with \c IGRAPH_REALIZE_DEGSEQ_SMALLEST
+ * to create a tree with given degrees.
  *
  * \example examples/simple/igraph_kary_tree.c
  */
@@ -869,7 +877,8 @@ igraph_error_t igraph_regular_tree(igraph_t *graph, igraph_integer_t h, igraph_i
  * \param directed Whether the graph should be directed.
  * \return Error code.
  *
- * \sa \ref igraph_ring(), \ref igraph_lcf(), \ref igraph_lcf_vector().
+ * \sa \ref igraph_ring(), \ref igraph_lcf(), \ref igraph_lcf_vector(),
+ * \ref igraph_circulant()
  *
  * Time complexity: O(|V|+|E|), the number of vertices plus the number
  * of edges.

src/vendor/cigraph/src/misc/degree_sequence.cpp

@@ -752,6 +752,7 @@ static igraph_error_t igraph_i_realize_directed_degree_sequence(
  *          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.
  *          \cli IGRAPH_REALIZE_DEGSEQ_LARGEST

src/vendor/igraph_version.h

@@ -28,11 +28,11 @@
 
 __BEGIN_DECLS
 
-#define IGRAPH_VERSION "0.10.13-131-g764954eda"
+#define IGRAPH_VERSION "0.10.13-132-gbd7b3a82b"
 #define IGRAPH_VERSION_MAJOR 0
 #define IGRAPH_VERSION_MINOR 10
 #define IGRAPH_VERSION_PATCH 13
-#define IGRAPH_VERSION_PRERELEASE "131-g764954eda"
+#define IGRAPH_VERSION_PRERELEASE "132-gbd7b3a82b"
 
 IGRAPH_EXPORT void igraph_version(const char **version_string,
                                   int *major,