feat: simple_cycles()

NAMESPACE

@@ -801,6 +801,7 @@ export(similarity)
 export(similarity.dice)
 export(similarity.invlogweighted)
 export(similarity.jaccard)
+export(simple_cycles)
 export(simplified)
 export(simplify)
 export(simplify_and_colorize)

R/aaa-auto.R

@@ -3580,16 +3580,16 @@ find_cycle_impl <- function(graph, mode=c("out", "in", "all", "total")) {
   res
 }
 
-simple_cycles_impl <- function(graph, mode=c("out", "in", "all", "total"), min.cycle.length=-1, max.cycle.length=-1) {
+simple_cycles_impl <- function(graph, mode=c("out", "in", "all", "total"), min=-1, max=-1) {
   # Argument checks
   ensure_igraph(graph)
   mode <- switch(igraph.match.arg(mode), "out"=1L, "in"=2L, "all"=3L, "total"=3L)
-  min.cycle.length <- as.numeric(min.cycle.length)
-  max.cycle.length <- as.numeric(max.cycle.length)
+  min <- as.numeric(min)
+  max <- as.numeric(max)
 
   on.exit( .Call(R_igraph_finalizer) )
   # Function call
-  res <- .Call(R_igraph_simple_cycles, graph, mode, min.cycle.length, max.cycle.length)
+  res <- .Call(R_igraph_simple_cycles, graph, mode, min, max)
   if (igraph_opt("return.vs.es")) {
     res$vertices <- lapply(res$vertices, unsafe_create_vs, graph = graph, verts = V(graph))
   }

R/cycles.R

@@ -50,3 +50,35 @@
 #' @export
 
 find_cycle <- find_cycle_impl
+
+
+#' Finds all simple cycles in a graph.
+#'
+#' @description
+#' `r lifecycle::badge("experimental")`
+#'
+#' This function lists all simple cycles in a graph within a range of cycle
+#' lengths. A cycle is called simple if it has no repeated vertices.
+#'
+#' Multi-edges and self-loops are taken into account. Note that graph can have
+#' exponentially many cycles and the presence of multi-edges exacerbates this
+#' combinatorial explosion.
+#'
+#' @inheritParams find_cycle
+#' @param min Lower limit on cycle lengths to consider. Pass `-1` to use no limit.
+#' @param max Upper limit on cycle lengths to consider. Pass `-1` to use no limit.
+#' @return A named list, with two entries:
+#' \item{vertices}{The list of cycles in terms of their vertices.}
+#' \item{edges}{The list of cycles in terms of their edges.}
+#' @keywords graphs
+#' @examples
+#'
+#' g <- graph_from_literal(A-+B-+C-+A-+D-+E+-F-+A, E-+E, A-+F, simplify=F)
+#' simple_cycles(g)
+#' simple_cycles(g, mode = "all") # ignore edge directions
+#' simple_cycles(g, mode = "all", min = 2, max = 3) # limit cycle lengths
+#'
+#' @family cycles
+#' @export
+
+simple_cycles <- simple_cycles_impl

tools/stimulus/functions-R.yaml

@@ -1464,6 +1464,9 @@ igraph_solve_lsap:
 igraph_find_cycle:
 
 igraph_simple_cycles:
+    PARAM_NAMES:
+        min_cycle_length: min
+        max_cycle_length: max
 
 igraph_simple_cycles_callback:
     IGNORE: RR, RC