feat: add make_hex_lattice() and hex_lattice() functions

NAMESPACE

@@ -487,6 +487,7 @@ export(has_eulerian_cycle)
 export(has_eulerian_path)
 export(head_of)
 export(head_print)
+export(hex_lattice)
 export(hierarchical_sbm)
 export(hierarchy)
 export(hits_scores)
@@ -659,6 +660,7 @@ export(make_full_bipartite_graph)
 export(make_full_citation_graph)
 export(make_full_graph)
 export(make_graph)
+export(make_hex_lattice)
 export(make_kautz_graph)
 export(make_lattice)
 export(make_line_graph)

R/aaa-auto.R

@@ -274,6 +274,28 @@ triangular_lattice_impl <- function(
   res
 }
 
+hexagonal_lattice_impl <- function(
+  dimvector,
+  directed = FALSE,
+  mutual = FALSE
+) {
+  # Argument checks
+  dimvector <- as.numeric(dimvector)
+  directed <- as.logical(directed)
+  mutual <- as.logical(mutual)
+
+  on.exit(.Call(R_igraph_finalizer))
+  # Function call
+  res <- .Call(
+    R_igraph_hexagonal_lattice,
+    dimvector,
+    directed,
+    mutual
+  )
+
+  res
+}
+
 path_graph_impl <- function(
   n,
   directed = FALSE,

R/make.R

@@ -2022,6 +2022,76 @@ lattice <- function(...) constructor_spec(make_lattice, ...)
 
 ## -----------------------------------------------------------------
 
+#' Create a hexagonal lattice graph
+#'
+#' `r lifecycle::badge("experimental")`
+#'
+#' `make_hex_lattice()` creates a hexagonal lattice. In graph theory, this is
+#' also sometimes referred to as a "triangular lattice" due to the triangular
+#' faces formed by the edges. The name "hexagonal lattice" refers to the
+#' hexagonal tiling pattern created when vertices are arranged in this structure,
+#' and is more commonly used in crystallography and physics.
+#'
+#' @details
+#' A hexagonal lattice is a lattice structure where each interior vertex
+#' (not on the boundary) has degree 3. The function supports creating lattices
+#' with different boundary shapes.
+#'
+#' The `dims` parameter determines the boundary shape of the lattice:
+#' \itemize{
+#'   \item If `dims` is a single number, the lattice has a triangular boundary
+#'     where each side contains `dims` vertices.
+#'   \item If `dims` is a vector of length 2, the lattice has a rectangular
+#'     boundary with sides containing `dims[1]` and `dims[2]` vertices.
+#'   \item If `dims` is a vector of length 3, the lattice has a hexagonal
+#'     boundary where the sides contain `dims[1]`, `dims[2]`, and `dims[3]`
+#'     vertices.
+#' }
+#'
+#' @param dims Integer vector, defines the shape of the lattice. See details below.
+#' @param directed Logical scalar, whether to create a directed graph.
+#' @param mutual Logical scalar, if the graph is directed this parameter
+#'   controls whether edges are mutual (bidirectional).
+#' @return An igraph graph.
+#'
+#' @family deterministic constructors
+#' @export
+#' @examples
+#' # Triangular shape with 5 vertices on each side
+#' g1 <- make_hex_lattice(5)
+#' plot(g1)
+#'
+#' # Rectangular shape
+#' g2 <- make_hex_lattice(c(3, 4))
+#' plot(g2)
+#'
+#' # Hexagonal shape
+#' g3 <- make_hex_lattice(c(3, 3, 3))
+#' plot(g3)
+#' @cdocs igraph_hexagonal_lattice
+make_hex_lattice <- function(dims, directed = FALSE, mutual = FALSE) {
+  on.exit(.Call(R_igraph_finalizer))
+  res <- hexagonal_lattice_impl(
+    dimvector = dims,
+    directed = directed,
+    mutual = mutual
+  )
+  if (igraph_opt("add.params")) {
+    res$name <- "Hexagonal lattice"
+    res$dims <- dims
+    res$directed <- directed
+    res$mutual <- mutual
+  }
+  res
+}
+
+#' @rdname make_hex_lattice
+#' @param ... Passed to `make_hex_lattice()`.
+#' @export
+hex_lattice <- function(...) constructor_spec(make_hex_lattice, ...)
+
+## -----------------------------------------------------------------
+
 #' Create a ring graph
 #'
 #' A ring is a one-dimensional lattice and this function is a special case

src/cpp11.cpp

@@ -227,6 +227,7 @@ extern SEXP R_igraph_harmonic_centrality_cutoff(SEXP, SEXP, SEXP, SEXP, SEXP, SE
 extern SEXP R_igraph_has_loop(SEXP);
 extern SEXP R_igraph_has_multiple(SEXP);
 extern SEXP R_igraph_has_mutual(SEXP, SEXP);
+extern SEXP R_igraph_hexagonal_lattice(SEXP, SEXP, SEXP);
 extern SEXP R_igraph_hrg_consensus(SEXP, SEXP, SEXP, SEXP);
 extern SEXP R_igraph_hrg_create(SEXP, SEXP);
 extern SEXP R_igraph_hrg_fit(SEXP, SEXP, SEXP, SEXP);
@@ -704,6 +705,7 @@ static const R_CallMethodDef CallEntries[] = {
     {"R_igraph_has_loop",                                   (DL_FUNC) &R_igraph_has_loop,                                    1},
     {"R_igraph_has_multiple",                               (DL_FUNC) &R_igraph_has_multiple,                                1},
     {"R_igraph_has_mutual",                                 (DL_FUNC) &R_igraph_has_mutual,                                  2},
+    {"R_igraph_hexagonal_lattice",                          (DL_FUNC) &R_igraph_hexagonal_lattice,                           3},
     {"R_igraph_hrg_consensus",                              (DL_FUNC) &R_igraph_hrg_consensus,                               4},
     {"R_igraph_hrg_create",                                 (DL_FUNC) &R_igraph_hrg_create,                                  2},
     {"R_igraph_hrg_fit",                                    (DL_FUNC) &R_igraph_hrg_fit,                                     4},