feat: expose find_cycle()

NAMESPACE

@@ -348,6 +348,7 @@ export(farthest.nodes)
 export(farthest_vertices)
 export(fastgreedy.community)
 export(feedback_arc_set)
+export(find_cycle)
 export(fit_hrg)
 export(fit_power_law)
 export(forest.fire.game)

R/aaa-auto.R

@@ -3511,7 +3511,7 @@ solve_lsap_impl <- function(c, n) {
   res
 }
 
-find_cycle_impl <- function(graph, mode) {
+find_cycle_impl <- function(graph, mode=c("out", "in", "all", "total")) {
   # Argument checks
   ensure_igraph(graph)
   mode <- switch(igraph.match.arg(mode), "out"=1L, "in"=2L, "all"=3L, "total"=3L)

R/cycles.R

@@ -0,0 +1,53 @@
+## -----------------------------------------------------------------------
+##
+##   igraph R package
+##   Copyright (C) 2024  The igraph development team <[email protected]>
+##
+##   This program is free software; you can redistribute it and/or modify
+##   it under the terms of the GNU General Public License as published by
+##   the Free Software Foundation; either version 2 of the License, or
+##   (at your option) any later version.
+##
+##   This program is distributed in the hope that it will be useful,
+##   but WITHOUT ANY WARRANTY; without even the implied warranty of
+##   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+##   GNU General Public License for more details.
+##
+##   You should have received a copy of the GNU General Public License
+##   along with this program.  If not, see <https://www.gnu.org/licenses/>.
+##
+## -----------------------------------------------------------------------
+
+#' Finds a cycle in a graph, if there is one
+#'
+#' @description
+#' `r lifecycle::badge("experimental")`
+#'
+#' This function returns a cycle of the graph, in terms of both its vertices
+#' and edges. If the graph is acyclic, it returns empty vertex and edge
+#' sequences.
+#'
+#' Use [is_acyclic()] to determine if a graph has cycles, without returning
+#' a specific cycle.
+#'
+#' @param graph The input graph.
+#' @param mode Character constant specifying how to handle directed graphs.
+#'   `out` follows edge directions, `in` follows edges in the reverse direction,
+#'   and `all` ignores edge directions. Ignored in undirected graphs.
+#' @return A list of integer vectors, each integer vector is a path from
+#'   the source vertex to one of the target vertices. A path is given by its
+#'   vertex ids.
+#' @keywords graphs
+#' @examples
+#'
+#' g <- make_lattice(c(3,3))
+#' find_cycle(g)
+#'
+#' # Empty results are returned for acyclic graphs
+#' find_cycle(sample_tree(5))
+#'
+#' @family cycles
+#' @cdocs igraph_find_cycle
+#' @export
+
+find_cycle <- find_cycle_impl

R/paths.R

@@ -161,7 +161,7 @@ is_dag <- is_dag_impl
 #' This function tests whether the given graph is free of cycles.
 #'
 #' This function looks for directed cycles in directed graphs and undirected
-#' cycles in undirected graphs.
+#' cycles in undirected graphs. Use [find_cycle()] to return a specific cycle.
 #'
 #' @param graph The input graph.
 #' @return A logical vector of length one.

src/vendor/cigraph/CHANGELOG.md

@@ -36,6 +36,8 @@
  - `igraph_centralization_degree_tmax()`, `igraph_centralization_betweenness_tmax()`, `igraph_centralization_closeness_tmax()`, and `igraph_centralization_eigenvector_centrality_tmax()` now validate their `nodes` parameter.
  - `igraph_centralization_degree_tmax()`, `igraph_centralization_betweenness_tmax()`, `igraph_centralization_closeness_tmax()`, and `igraph_centralization_eigenvector_centrality_tmax()` now return NaN for zero-vertex graphs. Previously they would return invalid values.
  - `igraph_centralization_eigenvector_centrality_tmax()` now returns 0 for the undirected singleton graph. Previous it would return an invalid value.
+ - `igraph_motifs_randesu_estimate()` now validates the sample size.
+ - `igraph_bipartite_projection_size()` now validates the bipartite `types` vector.
 
 ### Deprecated
 

src/vendor/cigraph/etc/cmake/compilers.cmake

@@ -54,7 +54,7 @@ macro(use_all_warnings TARGET_NAME)
     )
   else()
     # Notes:
-    # GCC does not complain when encountering an unsupported "no"-prefixed wanring option such as -Wno-foo.
+    # GCC does not complain when encountering an unsupported "no"-prefixed warning option such as -Wno-foo.
     # Clang does complain, but these complaints can be silenced with -Wno-unknown-warning-option.
     # Therefore it is generally safe to use -Wno-... options that are only supported by recent GCC/Clang.
     target_compile_options(${TARGET_NAME} PRIVATE
@@ -70,7 +70,8 @@ macro(use_all_warnings TARGET_NAME)
       $<$<C_COMPILER_ID:Intel>:
         # disable #279: controlling expression is constant; affecting assert(condition && "message")
         # disable #592: variable "var" is used before its value is set; affecting IGRAPH_UNUSED
-        -wd279 -wd592 -diag-disable=remark
+        # disable #10148: warning option not supported, as a replacement for -Wno-unknown-warning-option
+        -wd279 -wd592 -diag-disable=remark -diag-disable=10148
       >
       # Intel LLVM:
       $<$<C_COMPILER_ID:IntelLLVM>:

src/vendor/cigraph/include/igraph.h

@@ -1,8 +1,6 @@
-/* -*- mode: C -*-  */
 /*
    IGraph library.
-   Copyright (C) 2003-2012  Gabor Csardi <[email protected]>
-   334 Harvard street, Cambridge, MA 02139 USA
+   Copyright (C) 2003-2024  The igraph development team
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -18,7 +16,6 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc.,  51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301 USA
-
 */
 
 #ifndef IGRAPH_H

src/vendor/cigraph/include/igraph_bitset.h

@@ -1,4 +1,3 @@
-/* -*- mode: C -*-  */
 /*
    IGraph library.
    Copyright (C) 2024  The igraph development team
@@ -17,7 +16,6 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc.,  51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301 USA
-
 */
 
 #ifndef IGRAPH_BITSET_H

src/vendor/cigraph/include/igraph_bitset_list.h

@@ -1,4 +1,3 @@
-/* -*- mode: C -*-  */
 /*
    IGraph library.
    Copyright (C) 2024  The igraph development team
@@ -17,7 +16,6 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc.,  51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301 USA
-
 */
 
 #ifndef IGRAPH_BITSET_LIST_H

src/vendor/cigraph/include/igraph_cycles.h

@@ -1,3 +1,22 @@
+/*
+   IGraph library.
+   Copyright (C) 2022-2024  The igraph development team
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 2 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, write to the Free Software
+   Foundation, Inc.,  51 Franklin Street, Fifth Floor, Boston, MA
+   02110-1301 USA
+*/
 
 #ifndef IGRAPH_CYCLES_H
 #define IGRAPH_CYCLES_H

src/vendor/cigraph/include/igraph_decls.h

@@ -1,3 +1,23 @@
+/*
+   IGraph library.
+   Copyright (C) 2016-2024  The igraph development team
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 2 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program; if not, write to the Free Software
+   Foundation, Inc.,  51 Franklin Street, Fifth Floor, Boston, MA
+   02110-1301 USA
+*/
+
 #undef __BEGIN_DECLS
 #undef __END_DECLS
 #ifdef __cplusplus

src/vendor/cigraph/include/igraph_statusbar.h

@@ -42,7 +42,7 @@ __BEGIN_DECLS
  *
  * <para>
  * Status handler functions must be of type \ref igraph_status_handler_t
- * and they can be install by a call to \ref igraph_set_status_handler().
+ * and they can be installed by a call to \ref igraph_set_status_handler().
  * Currently there is a simple predefined status handler function,
  * called \ref igraph_status_handler_stderr(), but the user can define
  * new ones.

src/vendor/cigraph/interfaces/functions.yaml

@@ -2509,7 +2509,7 @@ igraph_solve_lsap:
 igraph_find_cycle:
     PARAMS: |-
         GRAPH graph, OPTIONAL OUT VERTEX_INDICES vertices, OPTIONAL OUT EDGE_INDICES edges,
-        NEIMODE mode
+        NEIMODE mode=OUT
     DEPS: vertices ON graph, edges ON graph
 
 #######################################

src/vendor/cigraph/src/centrality/centralization.c

@@ -200,7 +200,7 @@ igraph_error_t igraph_centralization_degree(const igraph_t *graph, igraph_vector
  *     or total degree (\c IGRAPH_ALL). This is ignored if
  *     the \p graph argument is not a null pointer and the
  *     given graph is undirected.
- * \param loops Boolean scalar, whether to consider loop edges in the
+ * \param loops Boolean, whether to consider loop edges in the
  *     calculation.
  * \param res Pointer to a real variable, the result is stored here.
  * \return Error code.
@@ -358,7 +358,7 @@ igraph_error_t igraph_centralization_betweenness(const igraph_t *graph,
  *     above.
  * \param nodes The number of nodes. This is ignored if the
  *     \p graph argument is not a null pointer.
- * \param directed Boolean scalar, whether to use directed paths in
+ * \param directed Boolean, whether to use directed paths in
  *     the betweenness calculation. This argument is ignored if
  *     \p graph is not a null pointer and it is undirected.
  * \param res Pointer to a real variable, the result is stored here.
@@ -695,7 +695,7 @@ igraph_error_t igraph_centralization_eigenvector_centrality(
  *     above.
  * \param nodes The number of nodes. This is ignored if the
  *     \p graph argument is not a null pointer.
- * \param directed Boolean scalar, whether to consider edge
+ * \param directed Boolean, whether to consider edge
  *     directions. This argument is ignored if
  *     \p graph is not a null pointer and it is undirected.
  * \param scale This parameter is deprecated and ignored since igraph 0.10.14.

src/vendor/cigraph/src/centrality/closeness.c

@@ -183,8 +183,7 @@ static igraph_error_t igraph_i_closeness_cutoff_weighted(const igraph_t *graph,
     IGRAPH_FINALLY(igraph_lazy_inclist_destroy, &inclist);
 
     IGRAPH_VECTOR_INIT_FINALLY(&dist, no_of_nodes);
-    IGRAPH_CHECK(igraph_vector_int_init(&which, no_of_nodes));
-    IGRAPH_FINALLY(igraph_vector_int_destroy, &which);
+    IGRAPH_VECTOR_INT_INIT_FINALLY(&which, no_of_nodes);
 
     IGRAPH_CHECK(igraph_vector_resize(res, nodes_to_calc));
     igraph_vector_null(res);
@@ -594,8 +593,7 @@ static igraph_error_t igraph_i_harmonic_centrality_weighted(const igraph_t *grap
     IGRAPH_FINALLY(igraph_lazy_inclist_destroy, &inclist);
 
     IGRAPH_VECTOR_INIT_FINALLY(&dist, no_of_nodes);
-    IGRAPH_CHECK(igraph_vector_int_init(&which, no_of_nodes));
-    IGRAPH_FINALLY(igraph_vector_int_destroy, &which);
+    IGRAPH_VECTOR_INT_INIT_FINALLY(&which, no_of_nodes);
 
     IGRAPH_CHECK(igraph_vector_resize(res, nodes_to_calc));
     igraph_vector_null(res);