feat: added create_square_lattice()

Author: ntamas

src/codegen/types.yaml

@@ -54,8 +54,9 @@ VECTOR_INT:
   OUTCONV: "%I% = igraph_vector_int_t_to_numpy_array(%C%)"
 
 VECTOR_BOOL:
-  # we can convert anything into a bool
-  PY_TYPE: Iterable[Any]
+  # we can convert anything into a bool, but we declare the type as
+  # Iterable[bool] only to nudge the user towards using bools
+  PY_TYPE: Iterable[bool]
   PY_RETURN_TYPE: npt.NDArray[np_type_of_igraph_bool_t]
   INCONV:
     IN: "%C% = iterable_to_igraph_vector_bool_t_view(%I%)"

src/igraph_ctypes/_internal/functions.py

@@ -424,7 +424,7 @@ def wheel(n: int, mode: WheelMode = WheelMode.OUT, center: int = 0) -> _Graph:
     return graph
 
 
-def square_lattice(dimvector: Iterable[int], nei: int = 1, directed: bool = False, mutual: bool = False, periodic: Optional[Iterable[Any]] = None) -> _Graph:
+def square_lattice(dimvector: Iterable[int], nei: int = 1, directed: bool = False, mutual: bool = False, periodic: Optional[Iterable[bool]] = None) -> _Graph:
     """Type-annotated wrapper for ``igraph_square_lattice``."""
     # Prepare input arguments
     c_graph = _Graph()
@@ -4636,7 +4636,7 @@ def community_fluid_communities(graph: _Graph, no_of_communities: int) -> npt.ND
     return membership
 
 
-def community_label_propagation(graph: _Graph, mode: NeighborMode = NeighborMode.ALL, weights: Optional[Iterable[float]] = None, initial: Optional[Iterable[int]] = None, fixed: Optional[Iterable[Any]] = None) -> npt.NDArray[np_type_of_igraph_integer_t]:
+def community_label_propagation(graph: _Graph, mode: NeighborMode = NeighborMode.ALL, weights: Optional[Iterable[float]] = None, initial: Optional[Iterable[int]] = None, fixed: Optional[Iterable[bool]] = None) -> npt.NDArray[np_type_of_igraph_integer_t]:
     """Type-annotated wrapper for ``igraph_community_label_propagation``."""
     # Prepare input arguments
     c_graph = graph

src/igraph_ctypes/constructors.py

@@ -1,9 +1,14 @@
-from typing import Iterable
+from typing import Iterable, Optional, Union
 
 from .graph import Graph
-from ._internal.functions import create, famous
+from ._internal.functions import create, famous, square_lattice
 
-__all__ = ("create_empty_graph", "create_graph_from_edge_list")
+__all__ = (
+    "create_empty_graph",
+    "create_famous_graph",
+    "create_graph_from_edge_list",
+    "create_square_lattice",
+)
 
 
 def create_empty_graph(n: int, directed: bool = False) -> Graph:
@@ -39,3 +44,34 @@ def create_graph_from_edge_list(
             the maximum edge ID in the edge list
     """
     return Graph(_wrap=create(edges, n, directed))
+
+
+def create_square_lattice(
+    dimvector: Iterable[int],
+    nei: int = 1,
+    directed: bool = False,
+    mutual: bool = False,
+    periodic: Union[bool, Iterable[bool]] = False,
+) -> Graph:
+    """Creates a square lattice graph.
+
+    Parameters:
+        dimvector: number of vertices along each dimension of the lattice
+        directed: whether the generated lattice should be directed
+        mutual: whether the vertices should be connected in both directions
+            if the lattice is directed
+        periodic: whether the lattice should be periodic along each dimension.
+            `True` or `False` means a periodic or an aperiodic lattice along
+            _all_ dimensions. You may supply an iterable having the same
+            length as the number of dimensions to specify periodicity along
+            each dimension separately.
+    """
+    if not hasattr(periodic, "__iter__"):
+        num_dims = len(list(dimvector))
+        periodic_per_dim = [bool(periodic)] * num_dims
+    else:
+        periodic_per_dim = list(periodic)  # type: ignore
+
+    return Graph(
+        _wrap=square_lattice(dimvector, nei, directed, mutual, periodic_per_dim)
+    )

test/test_constructors.py

@@ -1,8 +1,14 @@
 import pytest
 
 from numpy import array, ndarray
+from numpy.testing import assert_array_equal
 
-from igraph_ctypes.constructors import create_famous_graph, create_graph_from_edge_list
+from igraph_ctypes.constructors import (
+    create_famous_graph,
+    create_graph_from_edge_list,
+    create_square_lattice,
+)
+from igraph_ctypes._internal.functions import get_edgelist
 
 
 def test_create_famous_graph():
@@ -37,3 +43,25 @@ def test_create_graph_from_edge_list(edges, n, directed):
 
     for i, edge in enumerate(edges):
         assert list(g.edge(i)) == list(edge)
+
+
+def test_create_square_lattice():
+    g = create_square_lattice([4, 3])
+
+    assert not g.is_directed()
+    assert g.vcount() == 12 and g.ecount() == 17
+    # fmt: off
+    assert_array_equal(
+        get_edgelist(g._instance),
+        array([0, 1, 0, 4, 1, 2, 1, 5, 2, 3, 2, 6, 3, 7,
+               4, 5, 4, 8, 5, 6, 5, 9, 6, 7, 6, 10, 7, 11,
+               8, 9, 9, 10, 10, 11])
+    )
+    # fmt: on
+
+    g = create_square_lattice(
+        [4, 3], directed=True, mutual=True, periodic=[False, True]
+    )
+
+    assert g.is_directed()
+    assert g.vcount() == 12 and g.ecount() == 42