feat: add make_hex_lattice() and hex_lattice() functions

NAMESPACE

@@ -491,6 +491,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)
@@ -665,6 +666,7 @@ export(make_full_citation_graph)
 export(make_full_graph)
 export(make_full_multipartite)
 export(make_graph)
+export(make_hex_lattice)
 export(make_kautz_graph)
 export(make_lattice)
 export(make_line_graph)

R/aaa-auto.R

@@ -412,6 +412,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

@@ -2028,6 +2028,80 @@ lattice <- function(...) constructor_spec(make_lattice, ...)
 
 ## -----------------------------------------------------------------
 
+#' Create a hexagonal lattice graph
+#'
+#' `r lifecycle::badge("experimental")`
+#'
+#' `make_hex_lattice()` creates a hexagonal lattice where each interior vertex
+#' has degree 3. The hexagonal lattice and triangular lattice are different
+#' structures; they are planar duals of each other. See `igraph_triangular_lattice()`
+#' in the C library for the triangular lattice.
+#'
+#' @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 ... These dots are for future extensions and must be empty.
+#' @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) {
+  check_dots_empty()
+
+  graph <- hexagonal_lattice_impl(
+    dimvector = dims,
+    directed = directed,
+    mutual = mutual
+  )
+
+  if (igraph_opt("add.params")) {
+    graph <- set_graph_attr(graph, "name", "Hexagonal lattice")
+    graph <- set_graph_attr(graph, "dimvector", dims)
+    graph <- set_graph_attr(graph, "directed", directed)
+    graph <- set_graph_attr(graph, "mutual", mutual)
+  }
+  graph
+}
+
+#' @rdname make_hex_lattice
+#' @export
+hex_lattice <- function(dims, ..., directed = FALSE, mutual = FALSE) {
+  check_dots_empty()
+  constructor_spec(make_hex_lattice, dims = dims, directed = directed, mutual = mutual)
+}
+
+## -----------------------------------------------------------------
+
 #' Create a ring graph
 #'
 #' A ring is a one-dimensional lattice and this function is a special case

src/cpp11.cpp

@@ -209,6 +209,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);
@@ -735,6 +736,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},

src/rinterface.c

@@ -697,6 +697,41 @@ SEXP R_igraph_triangular_lattice(SEXP dimvector, SEXP directed, SEXP mutual) {
   return(r_result);
 }
 
+/*-------------------------------------------/
+/ igraph_hexagonal_lattice                   /
+/-------------------------------------------*/
+SEXP R_igraph_hexagonal_lattice(SEXP dimvector, SEXP directed, SEXP mutual) {
+                                        /* Declarations */
+  igraph_t c_graph;
+  igraph_vector_int_t c_dimvector;
+  igraph_bool_t c_directed;
+  igraph_bool_t c_mutual;
+  SEXP graph;
+
+  SEXP r_result;
+                                        /* Convert input */
+  IGRAPH_R_CHECK(R_SEXP_to_vector_int_copy(dimvector, &c_dimvector));
+  IGRAPH_FINALLY(igraph_vector_int_destroy, &c_dimvector);
+  IGRAPH_R_CHECK_BOOL(directed);
+  c_directed = LOGICAL(directed)[0];
+  IGRAPH_R_CHECK_BOOL(mutual);
+  c_mutual = LOGICAL(mutual)[0];
+                                        /* Call igraph */
+  IGRAPH_R_CHECK(igraph_hexagonal_lattice(&c_graph, &c_dimvector, c_directed, c_mutual));
+
+                                        /* Convert output */
+  IGRAPH_FINALLY(igraph_destroy, &c_graph);
+  PROTECT(graph=R_igraph_to_SEXP(&c_graph));
+  IGRAPH_I_DESTROY(&c_graph);
+  IGRAPH_FINALLY_CLEAN(1);
+  igraph_vector_int_destroy(&c_dimvector);
+  IGRAPH_FINALLY_CLEAN(1);
+  r_result = graph;
+
+  UNPROTECT(1);
+  return(r_result);
+}
+
 /*-------------------------------------------/
 / igraph_path_graph                          /
 /-------------------------------------------*/