Fix core.topology.* docs (#57)

xentica/core/topology/__init__.py

@@ -1,4 +1,5 @@
-"""This package helps you build the topology for CA models.
+"""
+This package helps you build the topology for CA models.
 
 All :class:`xentica.core.CellularAutomaton` subclasses **must** have
 ``Topology`` class declared inside. This class describes:
@@ -16,8 +17,8 @@
   cells. Built-in border types are available in
   :mod:`xentica.core.topology.border` module.
 
-In example, you can declare the topology for a 2-dimensional
-orthogonal lattice with Moore neighborhood, wrapped to a 3-torus, as
+For example, you can declare the topology for a 2-dimensional
+orthogonal lattice with Moore neighborhood wrapped to a 3-torus, as
 follows::
 
     class Topology:

xentica/core/topology/border.py

@@ -1,7 +1,7 @@
 """
-The collection of classes describing different types of field borders.
+The collection of classes describing different types of field's borders.
 
-All classes there are intended to be used inside ``Topology`` for
+All classes there are intended for use inside ``Topology`` for
 ``border`` class variable definition. They are also available via
 :mod:`xentica.core` shortcut. The example::
 
@@ -26,11 +26,11 @@ class Topology:
 
 class Border(DimensionsMixin):
     """
-    Base class for all types of borders.
+    The base class for all types of borders.
 
     You should not inherit your borders directly from this class, use
     either :class:`WrappedBorder` or :class:`GeneratedBorder` base
-    subclasses for this.
+    subclasses instead.
 
     """
 
@@ -42,7 +42,7 @@ def __init__(self):
 
 class WrappedBorder(Border):
     """
-    Base class for borders wrapping the field into different manifolds.
+    The base class for borders that wraps the field into different manifolds.
 
     For correct behavior, you should implement :meth:`wrap_coords` method.
 
@@ -59,14 +59,14 @@ def wrap_coords(self, coord_prefix):
         :class:`WrappedBorder` subclasses.
 
         :param coord_prefix:
-            The prefix for variables containing cell's coordinates.
+            The prefix for variables containing the cell's coordinates.
 
         """
 
 
 class GeneratedBorder(Border):
     """
-    Base class for borders generating states of the off-board cells.
+    The base class for borders that generates states of the off-board cells.
 
     For correct behavior, you should implement :meth:`off_board_state` method.
 
@@ -83,7 +83,7 @@ def off_board_state(self, coord_prefix):
         :class:`GeneratedBorder` subclasses.
 
         :param coord_prefix:
-            The prefix for variables containing cell's coordinates.
+            The prefix for variables containing the cell's coordinates.
 
         """
 
@@ -103,7 +103,7 @@ class TorusBorder(WrappedBorder):
 
     def wrap_coords(self, coord_prefix):
         """
-        Impement coordinates wrapping to torus.
+        Implement coordinates wrapping to torus.
 
         See :meth:`WrappedBorder.wrap_coords` for details.
 

xentica/core/topology/lattice.py

@@ -1,7 +1,7 @@
 """
 The collection of classes describing different lattice topologies.
 
-All classes there are intended to be used inside ``Topology`` for
+All classes there are intended for use inside ``Topology`` for
 ``lattice`` class variable definition. They are also available via
 :mod:`xentica.core` shortcut. The example::
 
@@ -25,7 +25,7 @@ class Topology:
 
 class Lattice(DimensionsMixin, BscaDetectorMixin, metaclass=abc.ABCMeta):
     """
-    Base class for all lattices.
+    The base class for all lattices.
 
     For correct behavior, lattice classes should be inherited from
     this class. You should also implement the following functions:
@@ -46,7 +46,7 @@ class Lattice(DimensionsMixin, BscaDetectorMixin, metaclass=abc.ABCMeta):
     width_prefix = "_w"
 
     def _define_constants_once(self):
-        """Define field size conctants in C code."""
+        """Define field size constants in the C code."""
         num_dimensions = self.bsca.topology.dimensions
         for i in range(num_dimensions):
             if not hasattr(self.bsca, "size") or i >= len(self.bsca.size):
@@ -60,35 +60,36 @@ def _define_constants_once(self):
     @abc.abstractmethod
     def index_to_coord_code(self, index_name, coord_prefix):
         """
-        Generate C code to obtain coordinates by cell's index.
+        Generate C code to obtain coordinates by the cell's index.
 
         This is an abstract method, you must implement it in :class:`Lattice`
         subclasses.
 
         :param index_name:
-            The name of variable containing cell's index.
+            The name of a variable containing the cell's index.
         :param coord_prefix:
             The prefix for resulting variables, containing coordinates.
 
         :returns:
-            A string with C code, doing all necessary to process
-            index variable and store coordinates to variables with
-            given prefix.
+            A string with the C code, doing all necessary to process
+            the index variable and store coordinates to variables with
+            the given prefix.
 
         """
 
     @abc.abstractmethod
     def index_to_coord(self, idx, bsca):
-        """Obtain cell's coordinates by its index, in pure Python.
+        """
+        Obtain the cell's coordinates by its index, in pure Python.
 
         This is an abstract method, you must implement it in :class:`Lattice`
         subclasses.
 
         :param idx:
-            Cell's index, a positive integer, or NumPy array of indices.
+            Cell's index, a positive integer, or a NumPy array of indices.
         :param bsca:
             :class:`xentica.core.CellularAutomaton` instance, to access
-            field size and number of dimensions.
+            the field's size and number of dimensions.
 
         :returns:
             Tuple of integer coordinates, or NumPy arrays of coords
@@ -99,7 +100,7 @@ def index_to_coord(self, idx, bsca):
     @abc.abstractmethod
     def coord_to_index_code(self, coord_prefix):
         """
-        Generate C code for obtaining cell's index by coordinates.
+        Generate C code for obtaining the cell's index by coordinates.
 
         This is an abstract method, you must implement it in :class:`Lattice`
         subclasses.
@@ -108,7 +109,7 @@ def coord_to_index_code(self, coord_prefix):
             The prefix for variables, containing coordinates.
 
         :returns:
-            A string with C code calculating cell's index. No
+            A string with the C code calculating cell's index. No
             assignment, only a valid expression needed.
 
         """
@@ -125,7 +126,7 @@ def is_off_board_code(self, coord_prefix):
             The prefix for variables, containing coordinates.
 
         :returns:
-            A string with C code testing coordinate variables. No
+            A string with the C code testing coordinates' variables. No
             assignment, only a valid expression with boolean result needed.
 
         """
@@ -144,7 +145,7 @@ class OrthogonalLattice(Lattice):
 
     def index_to_coord_code(self, index_name, coord_prefix):
         """
-        Implement coordinates obtaining by cell's index in C.
+        Generate C code for obtaining the cell's index by coordinates.
 
         See :meth:`Lattice.index_to_coord_code` for details.
 
@@ -170,7 +171,7 @@ def wrap_format(text):
 
     def index_to_coord(self, idx, bsca):
         """
-        Implement coordinates obtaining by cell's index in Python.
+        Obtain the cell's coordinates by its index, in pure Python.
 
         See :meth:`Lattice.index_to_coord` for details.
 
@@ -187,7 +188,7 @@ def index_to_coord(self, idx, bsca):
 
     def coord_to_index_code(self, coord_prefix):
         """
-        Implement cell's index obtaining by coordinates in C.
+        Generate C code for obtaining the cell's index by coordinates.
 
         See :meth:`Lattice.coord_to_index_code` for details.
 
@@ -204,7 +205,7 @@ def coord_to_index_code(self, coord_prefix):
 
     def is_off_board_code(self, coord_prefix):
         """
-        Implement off board cell obtaining in C.
+        Generate C code to test if the cell's coordinates are off board.
 
         See :meth:`Lattice.is_off_board_code` for details.
 

xentica/core/topology/neighborhood.py

@@ -1,7 +1,7 @@
 """
 The collection of classes describing different neighborhood topologies.
 
-All classes there are intended to be used inside ``Topology`` for
+All classes there are intended for use inside ``Topology`` for
 ``neighborhood`` class variable definition. They are also available via
 :mod:`xentica.core` shortcut. The example::
 
@@ -27,7 +27,7 @@ class Topology:
 
 class Neighborhood(DimensionsMixin):
     """
-    Base class for all neighborhood topologies.
+    The base class for all neighborhood topologies.
 
     For correct behavior, neighborhood classes should be inherited from
     this class. You should also implement the following functions:
@@ -52,60 +52,60 @@ def __init__(self):
         super(Neighborhood, self).__init__()
 
     def __len__(self):
-        """Return number of neighbors for a single cell."""
+        """Return the number of neighbors for a single cell."""
         return self.num_neighbors or 0
 
     @abc.abstractmethod
     def neighbor_coords(self, index, coord_prefix, neighbor_prefix):
         """
-        Generate C code to obtain neighbor coordinates by its index.
+        Generate the C code to obtain neighbor coordinates by its index.
 
         This is an abstract method, you must implement it in
         :class:`Neighborhood` subclasses.
 
         :param index:
-            Neighbor index, a non-negative integer less than number of
+            Neighbor's index, a non-negative integer less than the number of
             neighbors.
         :param coord_prefix:
             The prefix for variables containing main cell's coordinates.
         :param neighbor_prefix:
             The prefix for resulting variables containing neighbor coordinates.
 
         :returns:
-            A string with C code doing all necessary to get neighbor
-            state from RAM. No assignment, only a valid expression
+            A string with the C code doing all necessary to get neighbor's
+            state from the RAM. No assignment, only a valid expression
             needed.
 
         """
 
     @abc.abstractmethod
     def neighbor_state(self, neighbor_index, state_index, coord_prefix):
         """
-        Generate C code to obtain neighbor state by its index.
+        Generate the C code to obtain a neighbor's state by its index.
 
         This is an abstract method, you must implement it in
         :class:`Neighborhood` subclasses.
 
         :param neighbor_index:
-            Neighbor index, a non-negative integer less than number of
+            Neighbor's index, a non-negative integer less than the number of
             neighbors.
         :param state_index:
-            State index, a non-negative integer less than number of
+            State's index, a non-negative integer less than the number of
             neighbors for buffered states or -1 for main state.
         :param coord_prefix:
             The prefix for variables containing neighbor coordinates.
 
         :returns:
-            A string with C code doing all necessary to process
-            neighbors's coordinates and store them to neighbor
+            A string with the C code doing all necessary to process
+            neighbor's coordinates and store them to neighbor's
             coordinates variables.
 
         """
 
 
 class OrthogonalNeighborhood(Neighborhood):
     """
-    Base class for neighborhoods on orthogonal lattice.
+    The base class for neighborhoods on an orthogonal lattice.
 
     It is implementing all necessary :class:`Neighborhood` abstract
     methods, the only thing you should override is :meth:`dimensions`
@@ -120,7 +120,7 @@ class OrthogonalNeighborhood(Neighborhood):
 
     def neighbor_coords(self, index, coord_prefix, neighbor_prefix):
         """
-        Implement neighbor coordinates obtaining by its index, in C.
+        Generate the C code to obtain neighbor coordinates by its index.
 
         See :meth:`Neighborhood.neighbor_coords` for details.
 
@@ -136,7 +136,7 @@ def neighbor_coords(self, index, coord_prefix, neighbor_prefix):
 
     def neighbor_state(self, neighbor_index, state_index, coord_prefix):
         """
-        Implement state obtaining by neighbor/state index, in C.
+        Generate the C code to obtain a neighbor's state by its index.
 
         See :meth:`Neighborhood.neighbor_coords` for details.
 
@@ -157,7 +157,7 @@ class MooreNeighborhood(OrthogonalNeighborhood):
 
     @OrthogonalNeighborhood.dimensions.setter
     def dimensions(self, num_dim):
-        """Set number of neighbors and their relative coordinates."""
+        """Set the number of neighbors and their relative coordinates."""
         super_class = super(MooreNeighborhood, MooreNeighborhood)
         super_class.dimensions.fset(self, num_dim)
         self.num_neighbors = 3 ** num_dim - 1
@@ -175,7 +175,7 @@ class VonNeumannNeighborhood(OrthogonalNeighborhood):
 
     @OrthogonalNeighborhood.dimensions.setter
     def dimensions(self, num_dim):
-        """Set number of neighbors and their relative coordinates."""
+        """Set the number of neighbors and their relative coordinates."""
         super_class = super(VonNeumannNeighborhood, VonNeumannNeighborhood)
         super_class.dimensions.fset(self, num_dim)
         self.num_neighbors = 2 * num_dim