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)
@@ -658,6 +659,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/make.R

@@ -2001,6 +2001,73 @@ lattice <- function(...) constructor_spec(make_lattice, ...)
 
 ## -----------------------------------------------------------------
 
+#' Create a hexagonal lattice graph
+#'
+#' `make_hex_lattice()` creates a triangular lattice, also known as a hexagonal
+#' lattice. The name "hexagonal lattice" refers to the hexagonal tiling pattern
+#' created when vertices are arranged in this structure, while "triangular
+#' lattice" refers to the fact that edges form triangles. Both terms describe
+#' the same graph structure. The term "triangular lattice" is more common in
+#' graph theory, while "hexagonal lattice" is often used in crystallography
+#' and physics.
+#'
+#' @details
+#' A triangular (or hexagonal) lattice is a lattice structure where each
+#' interior vertex (not on the boundary) has degree 3. The fundamental structure
+#' is based on triangular tiling, but 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_triangular_lattice
+make_hex_lattice <- function(dims, directed = FALSE, mutual = FALSE) {
+  on.exit(.Call(R_igraph_finalizer))
+  res <- triangular_lattice_impl(dims, directed, 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

tests/testthat/test-make.R

@@ -456,3 +456,45 @@ test_that("graph_from_lcf() works", {
   g2 <- make_graph("Franklin")
   expect_isomorphic(g1, g2)
 })
+
+test_that("make_hex_lattice works", {
+  # Test triangular shape (1D)
+  g1 <- make_hex_lattice(3)
+  expect_equal(vcount(g1), 6)
+  expect_equal(ecount(g1), 9)
+  expect_false(is_directed(g1))
+
+  # Test rectangular shape (2D)
+  g2 <- make_hex_lattice(c(3, 4))
+  expect_equal(vcount(g2), 12)
+  expect_true(ecount(g2) > 0)
+
+  # Test hexagonal shape (3D)
+  g3 <- make_hex_lattice(c(2, 2, 2))
+  expect_equal(vcount(g3), 7)
+  expect_equal(ecount(g3), 12)
+
+  # Test directed graph
+  g4 <- make_hex_lattice(3, directed = TRUE, mutual = FALSE)
+  expect_true(is_directed(g4))
+
+  # Test mutual edges
+  g5 <- make_hex_lattice(3, directed = TRUE, mutual = TRUE)
+  expect_true(is_directed(g5))
+  # Check that edges come in pairs (mutual)
+  expect_equal(ecount(g5), 18) # Should have double the edges
+})
+
+test_that("hex_lattice works with make_()", {
+  # Test basic usage with make_()
+  g1 <- make_(hex_lattice(3))
+  expect_equal(vcount(g1), 6)
+  expect_equal(ecount(g1), 9)
+
+  # Test with different dimensions
+  g2 <- make_(hex_lattice(c(3, 4)))
+  expect_equal(vcount(g2), 12)
+
+  g3 <- make_(hex_lattice(c(2, 2, 2)))
+  expect_equal(vcount(g3), 7)
+})