feat: add make_circulant() to expose igraph_circulant() (#2407)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: krlmlr <[email protected]>
Co-authored-by: Kirill Müller <[email protected]>
Co-authored-by: szhorvat <[email protected]>

Author: 3 people

NAMESPACE

@@ -222,6 +222,7 @@ export(centralize)
 export(centralize.scores)
 export(chordal_ring)
 export(chung_lu)
+export(circulant)
 export(cit_cit_types)
 export(cit_types)
 export(cited.type.game)
@@ -650,6 +651,7 @@ export(local_scan)
 export(make_)
 export(make_bipartite_graph)
 export(make_chordal_ring)
+export(make_circulant)
 export(make_clusters)
 export(make_de_bruijn_graph)
 export(make_directed_graph)

R/aaa-auto.R

@@ -845,6 +845,11 @@ circulant_impl <- function(
     directed
   )
 
+  if (igraph_opt("add.params")) {
+    res$name <- 'Circulant graph'
+    res$shifts <- shifts
+  }
+
   res
 }
 

R/make.R

@@ -2286,6 +2286,41 @@ chordal_ring <- function(...) constructor_spec(make_chordal_ring, ...)
 
 ## -----------------------------------------------------------------
 
+#' Create a circulant graph
+#'
+#' A circulant graph \eqn{C_n^{\textrm{shifts}}} consists of \eqn{n} vertices
+#' \eqn{v_0, \ldots, v_{n-1}} such that for each \eqn{s_i} in the list of offsets
+#' `shifts`, \eqn{v_j} is connected to \eqn{v_{(j + s_i) \mod n}} for all \eqn{j}.
+#'
+#' The function can generate either directed or undirected graphs.
+#' It does not generate multi-edges or self-loops.
+#'
+#' @param n Integer, the number of vertices in the circulant graph.
+#' @param shifts Integer vector, a list of the offsets within the circulant graph.
+#' @param directed Boolean, whether to create a directed graph.
+#' @return An igraph graph.
+#'
+#' @family deterministic constructors
+#' @export
+#' @examples
+#' # Create a circulant graph with 10 vertices and shifts 1 and 3
+#' g <- make_circulant(10, c(1, 3))
+#' plot(g, layout = layout_in_circle)
+#'
+#' # A directed circulant graph
+#' g2 <- make_circulant(10, c(1, 3), directed = TRUE)
+#' plot(g2, layout = layout_in_circle)
+make_circulant <- function(n, shifts, directed = FALSE) {
+  circulant_impl(n = n, shifts = shifts, directed = directed)
+}
+
+#' @rdname make_circulant
+#' @param ... Passed to `make_circulant()`.
+#' @export
+circulant <- function(...) constructor_spec(make_circulant, ...)
+
+## -----------------------------------------------------------------
+
 #' Line graph of a graph
 #'
 #' This function calculates the line graph of another graph.