scikit-complexity 0.2.0__py3-none-any.whl

skcomplex/core/spaces/_continuous.py

@@ -0,0 +1,93 @@
+"""Define continuous spaces, boxes of real positions or the whole of R^d."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Sequence
+
+import numpy as np
+import numpy.typing as npt
+
+from ...errors import ValidationError
+from ._base import BaseNeighborhood, BaseSpace
+
+BOUNDARIES = ('open', 'periodic', 'reflecting')
+
+
+class ContinuousSpace(BaseSpace):
+    """Continuous space of real positions, a box with a boundary or the whole of `R^d`.
+
+    A box has an extent along every dimension, from 0 to the extent. Its boundary acts on every position state of the
+    members on it: `'open'` leaves positions alone, `'periodic'` joins opposite sides and measures pair distances by the
+    minimum image, and `'reflecting'` mirrors positions back into the box and reverses the velocity across the wall.
+    Without an extent the space is unbounded and has `n_dim` dimensions. The positions are states of the members, so
+    the space has no sites, and a site has no neighbours in it.
+
+    Args:
+        extent:
+            The side of the box along every dimension, or empty for an unbounded space.
+
+        n_dim:
+            The number of dimensions of an unbounded space, or `None` for the number of sides of the box.
+
+        boundary:
+            `'open'`, `'periodic'`, or `'reflecting'`.
+
+        label:
+            The label of the space in its system.
+
+    Attributes:
+        extent_:
+            The side of the box along every dimension, or `()` for an unbounded space.
+
+    Examples:
+        >>> from skcomplex.core.spaces import ContinuousSpace
+        >>> ContinuousSpace(extent=(10.0, 5.0), boundary='periodic').check().prepare().extent_
+        (10.0, 5.0)
+        >>> ContinuousSpace(n_dim=3).check().prepare().n_dim_
+        3
+    """
+
+    def __init__(
+        self,
+        extent: Sequence[float] = (),
+        *,
+        n_dim: int | None = None,
+        boundary: str = 'open',
+        label: str = 'space',
+    ) -> None:
+        super().__init__(label)
+        self.extent = extent
+        self.n_dim = n_dim
+        self.boundary = boundary
+
+    def _check(self) -> None:
+        """Raise an error for an unknown boundary, no dimension, a side that is not positive, or walls in `R^d`."""
+        extent = tuple(self.extent)
+        n_dim = self.n_dim if self.n_dim is not None else len(extent)
+        if self.boundary not in BOUNDARIES:
+            error_msg = f'Unknown boundary {self.boundary!r}. Use one of {", ".join(BOUNDARIES)}.'
+            raise ValidationError(error_msg)
+        if not n_dim:
+            error_msg = 'A continuous space needs the sides of its box or a number of dimensions.'
+            raise ValidationError(error_msg)
+        if extent and (len(extent) != n_dim or min(extent) <= 0):
+            error_msg = f'The box {extent} needs one positive side for each of its {n_dim} dimensions.'
+            raise ValidationError(error_msg)
+        if not extent and self.boundary != 'open':
+            error_msg = f'An unbounded space has no walls for its boundary {self.boundary!r}. Give the sides of a box.'
+            raise ValidationError(error_msg)
+
+    def _prepare(self, context: None = None) -> None:
+        """Set the extent of the box, its dimension, and its boundary, with no sites."""
+        self.extent_ = tuple(float(side) for side in self.extent)
+        self.n_dim_ = int(self.n_dim) if self.n_dim is not None else len(self.extent_)
+        self.size_ = None
+        self.shape_ = ()
+        self.positions_ = np.zeros((0, self.n_dim_))
+        self.periodic_ = self.boundary == 'periodic'
+        self.default_visual_ = None
+
+    def _get_neighbors(self, site: int, neighborhood: BaseNeighborhood | None = None) -> npt.NDArray[np.intp]:
+        """Return no neighbours, since the space has no sites."""
+        return np.zeros(0, dtype=np.intp)

skcomplex/core/spaces/_continuous_time.py

@@ -0,0 +1,27 @@
+"""Define continuous time, in which rates, noise, equations, jumps, and crossings change the states."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ._base import BaseTime
+
+
+class ContinuousTime(BaseTime):
+    """Continuous time, in which rates, noise, implicit equations, jumps, and crossings change the states.
+
+    Args:
+        label:
+            The label of the time in its system.
+
+    Examples:
+        >>> from skcomplex.core.spaces import ContinuousTime
+        >>> ContinuousTime().check().prepare().schedule_ is None
+        True
+    """
+
+    def __init__(self, *, label: str = 'time') -> None:
+        super().__init__(label)
+
+    def _prepare(self, context: None = None) -> None:
+        """Set no schedule."""
+        self.schedule_ = None

skcomplex/core/spaces/_discrete_time.py

@@ -0,0 +1,53 @@
+"""Define discrete time, in which updates and rules change the states every step."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import numpy as np
+import numpy.typing as npt
+
+from ...errors import ValidationError
+from ...specs import ScheduleSpec
+from ._base import BaseTime
+
+SCHEDULES = ('synchronous', 'random-sequential')
+
+
+class DiscreteTime(BaseTime):
+    """Discrete time, in which updates, rules, local rules, rewrites, and samples change the states every step.
+
+    Args:
+        schedule:
+            `'synchronous'`, every update reads the states of the start of the step, `'random-sequential'`, members
+            update one after another in a new random order, or a `ScheduleSpec` that a formalism defines, such as the
+            phases of agents.
+
+        label:
+            The label of the time in its system.
+
+    Examples:
+        >>> from skcomplex.core.spaces import DiscreteTime
+        >>> DiscreteTime(schedule='random-sequential').check().prepare().schedule_
+        'random-sequential'
+    """
+
+    def __init__(self, schedule: str | ScheduleSpec = 'synchronous', *, label: str = 'time') -> None:
+        super().__init__(label)
+        self.schedule = schedule
+
+    def _check(self) -> None:
+        """Raise an error for a schedule that is neither known nor a `ScheduleSpec`."""
+        if isinstance(self.schedule, ScheduleSpec):
+            self.schedule.check()
+            return
+        if self.schedule not in SCHEDULES:
+            error_msg = f'Unknown schedule {self.schedule!r}. Use one of {", ".join(SCHEDULES)}, or a ScheduleSpec.'
+            raise ValidationError(error_msg)
+
+    def _prepare(self, context: None = None) -> None:
+        """Set the schedule."""
+        self.schedule_ = self.schedule
+
+    def _get_frames(self, until: float) -> npt.NDArray[np.float64]:
+        """Return every step from 0 to a time."""
+        return np.arange(int(np.floor(until)) + 1, dtype=float)

skcomplex/core/spaces/_generator.py

@@ -0,0 +1,51 @@
+"""Define generator neighbourhoods, the memory sets of the generators of a group."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ._memory import MemoryNeighborhood
+
+
+class GeneratorNeighborhood(MemoryNeighborhood):
+    """Memory set of the generators of a group, after the identity and with their inverses when asked.
+
+    Args:
+        generators:
+            The names of the generators of the group.
+
+        center:
+            Whether the identity comes first.
+
+        inverses:
+            Whether every generator is followed by its inverse.
+
+        label:
+            The label of the neighbourhood.
+
+    Attributes:
+        elements_:
+            The words of the memory set.
+
+    Examples:
+        >>> from skcomplex.core.spaces import GeneratorNeighborhood
+        >>> GeneratorNeighborhood(['a', 'b']).check().prepare().elements_
+        ('1', 'a', 'a^-1', 'b', 'b^-1')
+    """
+
+    def __init__(
+        self,
+        generators: tuple[str, ...],
+        *,
+        center: bool = True,
+        inverses: bool = True,
+        label: str = 'neighborhood',
+    ) -> None:
+        super().__init__((), label=label)
+        self.generators = generators
+        self.center = center
+        self.inverses = inverses
+
+    def _get_elements(self) -> tuple[str, ...]:
+        """Return the identity when included, then every generator followed by its inverse when asked."""
+        words = [word for name in self.generators for word in ((name, f'{name}^-1') if self.inverses else (name,))]
+        return ('1', *words) if self.center else tuple(words)

skcomplex/core/spaces/_lattice.py

@@ -0,0 +1,194 @@
+"""Define lattice spaces, boxes of Z^d or of the triangular lattice whose sites hold lattice group members."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+import numpy.typing as npt
+
+from ...errors import ValidationError
+from ._base import BaseNeighborhood, BaseSpace
+from ._box import BoxNeighborhood
+from ._lattice_neighborhood import LatticeNeighborhood
+from ._moore import MooreNeighborhood
+from ._triangular import TriangularNeighborhood
+from ._von_neumann import VonNeumannNeighborhood
+
+BOUNDARIES = ('periodic', 'fixed', 'reflecting')
+GEOMETRIES = ('square', 'triangular')
+TRIANGULAR_ROW_HEIGHT = float(np.sqrt(3.0) / 2)
+TRIANGULAR_DIMENSIONS = 2
+
+
+class LatticeSpace(BaseSpace):
+    """Box of the integer lattice `Z^d`, or of the triangular lattice in 2D, whose sites hold lattice group members.
+
+    Sites are numbered in row-major order, so site `(i, j)` of a lattice of shape `(n, m)` is member `i * m + j`. A
+    triangular site `(i, j)` keeps its integer coordinates on a skewed grid and sits at `(j + i / 2, i sqrt(3) / 2)` in
+    the plane, so it has six neighbours at unit distance.
+
+    Args:
+        shape:
+            The number of sites along every dimension.
+
+        geometry:
+            `'square'` for the integer lattice or `'triangular'` for the triangular lattice in two dimensions.
+
+        boundary:
+            `'periodic'` to join opposite edges, `'fixed'` to read the value `fill` outside the box, or `'reflecting'`
+            to read the mirror image of the box outside it.
+
+        fill:
+            The value read outside a lattice with fixed edges.
+
+        spacing:
+            The distance between neighbouring sites, or one distance per dimension.
+
+        neighborhood:
+            The neighbourhood agents on a two-dimensional square lattice query, `'moore'` for the 8 surrounding cells
+            or `'von_neumann'` for the 4 adjacent ones.
+
+        capacity:
+            The largest number of agents in a cell, or `None` for no limit.
+
+        label:
+            The label of the space in its system.
+
+    Attributes:
+        spacings_:
+            The distance between neighbouring sites along every dimension.
+
+    Examples:
+        >>> from skcomplex.core.spaces import LatticeSpace
+        >>> space = LatticeSpace((10, 20)).check().prepare()
+        >>> space.size_, space.n_dim_, space.shape_
+        (200, 2, (10, 20))
+        >>> LatticeSpace((2, 2), geometry='triangular').check().prepare().positions_.round(3).tolist()
+        [[0.0, 0.0], [1.0, 0.0], [0.5, 0.866], [1.5, 0.866]]
+    """
+
+    def __init__(
+        self,
+        shape: Sequence[int] | int,
+        *,
+        geometry: str = 'square',
+        boundary: str = 'periodic',
+        fill: float = 0.0,
+        spacing: float | Sequence[float] = 1.0,
+        neighborhood: str = 'moore',
+        capacity: int | None = None,
+        label: str = 'space',
+    ) -> None:
+        super().__init__(label)
+        self.shape = shape
+        self.geometry = geometry
+        self.boundary = boundary
+        self.fill = fill
+        self.spacing = spacing
+        self.neighborhood = neighborhood
+        self.capacity = capacity
+
+    def _check(self) -> None:
+        """Raise an error when the shape, the geometry, or the boundary is not valid."""
+        shape = tuple(np.ravel(self.shape).tolist())
+        if not shape or any(int(size) != size or size < 1 for size in shape):
+            error_msg = (
+                f'A lattice has a positive number of sites along every dimension, but its shape is {self.shape}.'
+            )
+            raise ValidationError(error_msg)
+        if self.boundary not in BOUNDARIES:
+            error_msg = f'Unknown lattice boundary {self.boundary!r}. Use one of {", ".join(BOUNDARIES)}.'
+            raise ValidationError(error_msg)
+        if self.geometry not in GEOMETRIES:
+            error_msg = f'Unknown lattice geometry {self.geometry!r}. Use one of {", ".join(GEOMETRIES)}.'
+            raise ValidationError(error_msg)
+        if self.geometry == 'triangular' and len(shape) != TRIANGULAR_DIMENSIONS:
+            error_msg = f'A triangular lattice has two dimensions, but its shape is {self.shape}.'
+            raise ValidationError(error_msg)
+
+    def _prepare(self, context: None = None) -> None:
+        """Set the shape, the size, the spacings, and the position of every site."""
+        self.shape_ = tuple(int(size) for size in np.ravel(self.shape).tolist())
+        self.n_dim_ = len(self.shape_)
+        self.size_ = int(np.prod(self.shape_))
+        spacings = np.ravel(np.asarray(self.spacing, dtype=float))
+        if spacings.size == 1:
+            spacings = np.repeat(spacings, self.n_dim_)
+        self.spacings_ = tuple(float(item) for item in spacings)
+        coordinates = np.indices(self.shape_).reshape(self.n_dim_, -1).T.astype(float)
+        if self.geometry == 'triangular':
+            rows, columns = coordinates.T
+            coordinates = np.column_stack([columns + rows / 2, rows * TRIANGULAR_ROW_HEIGHT])
+        self.positions_ = coordinates * np.asarray(self.spacings_)
+        self.periodic_ = self.boundary == 'periodic'
+        self.default_visual_ = 'image' if self.geometry == 'square' else 'sites'
+
+    def _axis_boundary(self, axis: int) -> str:
+        """Return the edges of an axis, the one boundary of the lattice."""
+        return self.boundary
+
+    def _with_edges(self, boundary: str, fill: float) -> LatticeSpace:
+        """Return the sites of the lattice with other edges, which the reads of a state with its own boundary use."""
+        return LatticeSpace(self.shape_, boundary=boundary, fill=fill).check().prepare()
+
+    def _default_neighborhood(self) -> LatticeNeighborhood:
+        """Return the neighbourhood agents query, the triangular, von Neumann, or Moore neighbourhood of radius 1."""
+        if self.geometry == 'triangular':
+            return TriangularNeighborhood()
+        if self.neighborhood == 'von_neumann':
+            return VonNeumannNeighborhood(n_dim=self.n_dim_)
+        return MooreNeighborhood(n_dim=self.n_dim_)
+
+    def _index_table(self, neighborhood: BaseNeighborhood) -> npt.NDArray[np.intp]:
+        """Return the member index of every neighbour of every site, with `size_` for sites outside fixed edges."""
+        if not isinstance(neighborhood, LatticeNeighborhood):
+            error_msg = f'A lattice reads a lattice neighbourhood of offsets, but it was given {neighborhood!r}.'
+            raise ValidationError(error_msg)
+        offsets = neighborhood.check().prepare().offsets_
+        if offsets and len(offsets[0]) != self.n_dim_:
+            error_msg = (
+                f'The neighbourhood has offsets of dimension {len(offsets[0])}, but the lattice has {self.n_dim_} '
+                'dimensions.'
+            )
+            raise ValidationError(error_msg)
+        coordinates = np.indices(self.shape_).reshape(self.n_dim_, -1)
+        table = np.empty((self.size_, len(offsets)), dtype=np.intp)
+        for column, offset in enumerate(offsets):
+            shifted = coordinates + np.asarray(offset)[:, None]
+            outside = np.zeros(self.size_, dtype=bool)
+            for axis, size in enumerate(self.shape_):
+                edges = self._axis_boundary(axis)
+                if edges == 'periodic':
+                    shifted[axis] %= size
+                elif edges == 'reflecting':
+                    shifted[axis] %= 2 * size
+                    shifted[axis] = np.where(shifted[axis] < size, shifted[axis], 2 * size - 1 - shifted[axis])
+                else:
+                    outside |= (shifted[axis] < 0) | (shifted[axis] >= size)
+                    shifted[axis] = np.clip(shifted[axis], 0, size - 1)
+            flat = np.ravel_multi_index(tuple(shifted), self.shape_)
+            table[:, column] = np.where(outside, self.size_, flat)
+        return table
+
+    def _ball(self, radius: int) -> LatticeNeighborhood:
+        """Return the box of offsets within a radius along every dimension, the site itself included."""
+        return BoxNeighborhood(radius, n_dim=self.n_dim_)
+
+    def _neighbor_pairs(self, layer: str | None = None) -> list[tuple[int, int]]:
+        """Return the pairs of distinct sites one step apart along a dimension, each pair once."""
+        sites = np.arange(self.size_).reshape(self.shape_)
+        found: dict[frozenset[int], tuple[int, int]] = {}
+        for axis, length in enumerate(self.shape_):
+            shifted = np.roll(sites, -1, axis=axis)
+            pairs = np.stack([sites.ravel(), shifted.ravel()], axis=1)
+            if self._axis_boundary(axis) != 'periodic':
+                edge = np.indices(self.shape_)[axis].ravel() == length - 1
+                pairs = pairs[~edge]
+            for first, second in pairs.tolist():
+                if first != second:
+                    found.setdefault(frozenset((first, second)), (first, second))
+        return list(found.values())

skcomplex/core/spaces/_lattice_neighborhood.py

@@ -0,0 +1,50 @@
+"""Define lattice neighbourhoods, the ordered offsets of the sites a local rule reads."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+
+import numpy as np
+
+from ...errors import ValidationError
+from ...types import IntTuple
+from ._base import BaseNeighborhood
+
+
+class LatticeNeighborhood(BaseNeighborhood):
+    """Ordered offsets of the sites a local rule reads, with the site itself as the zero offset when included.
+
+    Args:
+        offsets:
+            The offsets, one tuple of integers per neighbour, in the order rules receive their values.
+
+        label:
+            The label of the neighbourhood.
+
+    Attributes:
+        offsets_:
+            The offsets as tuples of integers.
+
+    Examples:
+        >>> from skcomplex.core.spaces import LatticeNeighborhood
+        >>> LatticeNeighborhood([(0, 1), (1, 0)]).check().prepare().offsets_
+        ((0, 1), (1, 0))
+    """
+
+    def __init__(self, offsets: tuple[IntTuple, ...], *, label: str = 'neighborhood') -> None:
+        super().__init__(label)
+        self.offsets = offsets
+
+    def _get_offsets(self) -> tuple[IntTuple, ...]:
+        """Return the offsets as tuples of integers."""
+        return tuple(tuple(int(step) for step in np.atleast_1d(offset)) for offset in self.offsets)
+
+    def _check(self) -> None:
+        """Raise an error for offsets of different numbers of dimensions."""
+        if len({len(offset) for offset in self._get_offsets()}) > 1:
+            error_msg = 'Every offset of a neighbourhood has the same number of dimensions.'
+            raise ValidationError(error_msg)
+
+    def _prepare(self, context: None = None) -> None:
+        """Set `offsets_`, the offsets as tuples of integers."""
+        self.offsets_ = self._get_offsets()

skcomplex/core/spaces/_memory.py

@@ -0,0 +1,45 @@
+"""Define memory neighbourhoods, the ordered memory sets of cellular automata on group spaces."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from collections.abc import Sequence
+
+from ._base import BaseNeighborhood
+
+
+class MemoryNeighborhood(BaseNeighborhood):
+    """Ordered memory set of a cellular automaton on a group space: the group elements whose values a rule reads.
+
+    A cell at the element `g` reads the cell at `g s` for every element `s` of the memory set, in its order, so the
+    neighbourhood keeps its orientation. Elements are words in the generators, such as `'a'`, `'a^-1'`, or `'a*b'`, and
+    `'1'` is the identity, the cell itself.
+
+    Args:
+        elements:
+            The words of the memory set.
+
+        label:
+            The label of the neighbourhood.
+
+    Attributes:
+        elements_:
+            The words of the memory set as strings.
+
+    Examples:
+        >>> from skcomplex.core.spaces import MemoryNeighborhood
+        >>> MemoryNeighborhood(['1', 'a', 'a^-1']).check().prepare().elements_
+        ('1', 'a', 'a^-1')
+    """
+
+    def __init__(self, elements: Sequence[str], *, label: str = 'neighborhood') -> None:
+        super().__init__(label)
+        self.elements = elements
+
+    def _get_elements(self) -> tuple[str, ...]:
+        """Return the words of the memory set as strings."""
+        return tuple(str(element) for element in self.elements)
+
+    def _prepare(self, context: None = None) -> None:
+        """Set `elements_`, the words of the memory set as strings."""
+        self.elements_ = self._get_elements()

skcomplex/core/spaces/_mesh.py

@@ -0,0 +1,71 @@
+"""Define mesh spaces, unstructured triangular and tetrahedral meshes that finite element fields live on."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+
+import numpy as np
+import numpy.typing as npt
+import skfem
+
+from ._base import BaseNeighborhood, BaseSpace
+
+TRIANGLE_DIMENSIONS = 2
+
+
+class MeshSpace(BaseSpace):
+    """Unstructured mesh of triangles or tetrahedra, whose nodes hold the members of finite element fields.
+
+    Build the nodes and cells with scikit-fem, such as `skfem.MeshTri.init_lshaped().refined(3)`, and pass its `p` and
+    `t` arrays.
+
+    Args:
+        points:
+            The coordinates of the nodes, one column per node and one row per dimension.
+
+        cells:
+            The node indices of every triangle or tetrahedron, one column per cell.
+
+        label:
+            The label of the space in its system.
+
+    Attributes:
+        mesh_:
+            The scikit-fem mesh of the nodes and cells, a `MeshTri` in 2D or a `MeshTet` in 3D.
+
+        boundary_nodes_:
+            The indices of the nodes on the boundary of the mesh.
+
+    Examples:
+        >>> import numpy as np
+        >>> import skfem
+        >>> from skcomplex.core.spaces import MeshSpace
+        >>> grid = skfem.MeshTri.init_tensor(np.linspace(0, 1, 5), np.linspace(0, 1, 4))
+        >>> mesh = MeshSpace(grid.p, grid.t).check().prepare()
+        >>> mesh.size_, mesh.n_dim_, mesh.positions_.shape
+        (20, 2, (20, 2))
+    """
+
+    def __init__(self, points: npt.ArrayLike, cells: npt.ArrayLike, *, label: str = 'space') -> None:
+        super().__init__(label)
+        self.points = points
+        self.cells = cells
+
+    def _prepare(self, context: None = None) -> None:
+        """Set the nodes, the scikit-fem mesh, and the boundary nodes."""
+        points = np.asarray(self.points, dtype=float)
+        kind = skfem.MeshTri if points.shape[0] == TRIANGLE_DIMENSIONS else skfem.MeshTet
+        self.mesh_ = kind(points, np.asarray(self.cells, dtype=np.int64))
+        self.boundary_nodes_ = np.asarray(self.mesh_.boundary_nodes(), dtype=np.intp)
+        self.n_dim_ = int(points.shape[0])
+        self.size_ = int(points.shape[1])
+        self.shape_ = (self.size_,)
+        self.positions_ = points.T
+        self.periodic_ = False
+        self.default_visual_ = None
+
+    def _get_neighbors(self, site: int, neighborhood: BaseNeighborhood | None = None) -> npt.NDArray[np.intp]:
+        """Return the nodes that share a cell with a node, in increasing order."""
+        cells = np.asarray(self.cells, dtype=np.intp)
+        around = np.unique(cells[:, (cells == site).any(axis=0)])
+        return around[around != site]

skcomplex/core/spaces/_moore.py

@@ -0,0 +1,49 @@
+"""Define Moore neighbourhoods, the sites within a radius along every dimension."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+import itertools
+
+from ...types import IntTuple
+from ._base import BaseNeighborhood
+from ._lattice_neighborhood import LatticeNeighborhood
+
+
+class MooreNeighborhood(LatticeNeighborhood):
+    """Sites within a radius along every dimension, the 8 surrounding cells in two dimensions for radius 1.
+
+    The offsets come in lexicographic order, after the site itself when it is included.
+
+    Args:
+        radius:
+            The largest offset along any dimension.
+
+        n_dim:
+            The number of dimensions.
+
+        center:
+            Whether the site itself comes first.
+
+        label:
+            The label of the neighbourhood.
+
+    Examples:
+        >>> from skcomplex.core.spaces import MooreNeighborhood
+        >>> len(MooreNeighborhood().check().prepare().offsets_)
+        8
+        >>> len(MooreNeighborhood(center=True).check().prepare().offsets_)
+        9
+    """
+
+    def __init__(self, radius: int = 1, *, n_dim: int = 2, center: bool = False, label: str = 'neighborhood') -> None:
+        BaseNeighborhood.__init__(self, label)
+        self.radius = radius
+        self.n_dim = n_dim
+        self.center = center
+
+    def _get_offsets(self) -> tuple[IntTuple, ...]:
+        """Return the offsets within the radius along every dimension, after the site itself when included."""
+        steps = range(-self.radius, self.radius + 1)
+        offsets = tuple(offset for offset in itertools.product(steps, repeat=self.n_dim) if any(offset))
+        return ((0,) * self.n_dim, *offsets) if self.center else offsets

skcomplex/core/spaces/_nearest.py

@@ -0,0 +1,41 @@
+"""Define nearest neighbourhoods, the members of a continuous space closest to a member."""
+
+# Author: Georgios Douzas <gdouzas@icloud.com>
+# License: MIT
+
+from ...errors import ValidationError
+from ._base import BaseNeighborhood
+
+
+class NearestNeighborhood(BaseNeighborhood):
+    """The `k` members of a continuous space closest to a member, the topological neighbourhood.
+
+    Distances are measured between the position states of the members, by the minimum image in a periodic box. A group
+    of at most `k` other members gives every member all the others.
+
+    Args:
+        k:
+            The number of neighbours.
+
+        center:
+            Whether a member is its own neighbour, besides its `k` nearest others.
+
+        label:
+            The label of the neighbourhood.
+
+    Examples:
+        >>> from skcomplex.core.spaces import NearestNeighborhood
+        >>> NearestNeighborhood(7).check().k
+        7
+    """
+
+    def __init__(self, k: int, *, center: bool = False, label: str = 'neighborhood') -> None:
+        super().__init__(label)
+        self.k = k
+        self.center = center
+
+    def _check(self) -> None:
+        """Raise an error for a number of neighbours that is not a whole number of at least 1."""
+        if int(self.k) != self.k or int(self.k) < 1:
+            error_msg = f'A nearest neighbourhood needs a whole number of neighbours of at least 1, but got {self.k!r}.'
+            raise ValidationError(error_msg)