Module square_lattice 

Square (multi-dimensional grid) lattice constructor (ALGO-CN-009).

Counterpart of igraph_square_lattice() in references/igraph/src/constructors/regular.c:337-459.

Builds a d-dimensional square lattice with arbitrary per-dimension cardinalities and optional per-dimension torus wrap-around. The vertex at lattice position (i_0, i_1, …, i_{d-1}) in a lattice of shape (n_0, n_1, …, n_{d-1}) carries vertex id i_0 + n_0 · i_1 + n_0·n_1 · i_2 + … (little-endian, matching the upstream convention).

Modes:

• directed = false: each lattice edge is emitted once with the lower vertex id as the source.
• directed = true, mutual = false: each edge becomes a single arc pointing from the lower-indexed vertex to the higher one.
• directed = true, mutual = true: every undirected lattice edge becomes a pair of opposite arcs. For periodic dimensions of size 2 the upstream code suppresses the duplicate so the forward/back wrap edges are not double-emitted; this port matches that behaviour bit-for-bit.

Limitations of this first cut:

• nei (neighbour-distance radius) is restricted to 0 or 1. Higher values require the future igraph_connect_neighborhood helper (a separate AWU) — they are rejected with InvalidArgument for now.

Special cases:

• dim = [] (zero dimensions) → singleton (one vertex).
• any dim[k] == 0 → null graph (zero vertices, zero edges).
• any dim[k] == 1 contributes no edges along that dimension.

Algorithm: walk every vertex in little-endian lattice order. At each step, for every dimension j, emit the canonical “forward” edge to the neighbour with coords[j] + 1 (or the wrap-around when coords[j] == dim[j] − 1 and that dimension is periodic). When directed && mutual, additionally emit the “backward” reverse arc. Self-loops (only possible when a wrap produces the same vertex) and duplicate dim-2 edges are filtered out exactly as upstream does. Mirrors the C loop.

Time complexity: O(|V| · d) = O(|E|).

Functions

square_lattice

Build a d-dimensional square lattice graph.