Add docstrings to CellularAutomaton class (#23, #27)

xentica/core/base.py

@@ -458,10 +458,45 @@ def pack_state(self, state):
 
 class CellularAutomaton(metaclass=BSCA):
     """
-    Base class for all Xentica mods.
+    Base class for all Xentica models.
+
+    Compiles GPU kernels generated by :class:`BSCA` metaclass,
+    initializes necessary GPU arrays and popupates them with the seed.
+
+    After initialization, you can run step-by-step simulation and
+    render the field at any moment::
+
+        from xentica import core
+        import moire
+
+        class MyCA(core.CellularAutomaton):
+            # ...
+
+        class MyExperiment(core.Experiment):
+            # ...
+
+        ca = MyCA(MyExperiment)
+        ca.set_viewport((320, 200))
+
+        # run CA manually for 100 steps
+        for i in range(100):
+            ca.step()
+        # render current timestep
+        frame = ca.render()
+
+        # or run the whole process interactively with Moire
+        gui = moire.GUI(runnable=ca)
+        gui.run()
+
+    :param experiment_class:
+        :class:`Experiment <xentica.core.experiments.Experiment>`
+        instance, holding all necessary parameters for the field
+        initialization.
 
     """
+
     def __init__(self, experiment_class):
+        """Initialize kernels, GPU arrays and other stuff."""
         # visuals
         self.frame_buf = np.zeros((3, ), dtype=np.uint8)
         # populate attributes from Experiment class
@@ -503,16 +538,43 @@ def __init__(self, experiment_class):
         self.lock = threading.Lock()
 
     def apply_speed(self, dval):
+        """
+        Change the simulation speed.
+
+        Usable only in conduction with Moire, although you can use the
+        ``speed`` value in your custom GUI too.
+
+        :param dval: Delta by which speed is changed.
+
+        """
         self.speed = max(1, (self.speed + dval))
 
     def toggle_pause(self):
+        """
+        Toggle ``paused`` flag.
+
+        When paused, the ``step()`` method does nothing.
+
+        """
         self.paused = not self.paused
 
     def set_viewport(self, size):
+        """
+        Set viewport (camera) size and initialize GPU array for it.
+
+        :param size: tuple with width and height in pixels.
+
+        """
         self.width, self.height = w, h = size
         self.img_gpu = gpuarray.zeros((w * h * 3), dtype=np.int32)
 
     def step(self):
+        """
+        Perform a single simulation step.
+
+        ``timestep`` attribute will hold the current step number.
+
+        """
         if self.paused:
             return
         block, grid = self.cells_gpu._block, self.cells_gpu._grid
@@ -525,6 +587,16 @@ def step(self):
             self.timestep += 1
 
     def render(self):
+        """
+        Render the field at the current timestep.
+
+        You must call :meth:`set_viewport` before do any rendering.
+
+        :returns:
+            NumPy array of ``np.uint8`` values, ``width * height * 3``
+            size. The RGB values are consecutive.
+
+        """
         block, grid = self.img_gpu._block, self.img_gpu._grid
         with self.lock:
             args = self.renderer.get_args_vals(self)
@@ -533,6 +605,7 @@ def render(self):
             return self.img_gpu.get().astype(np.uint8)
 
     def save(self, filename):
+        """Save the CA state into ``filename`` file."""
         with open(filename, "wb") as f:
             ca_state = {
                 "cells": self.cells_gpu.get(),
@@ -542,6 +615,7 @@ def save(self, filename):
             pickle.dump(ca_state, f)
 
     def load(self, filename):
+        """Load the CA state from ``filename`` file."""
         with open(filename, "rb") as f:
             ca_state = pickle.load(f)
             self.cells_gpu = gpuarray.to_gpu(ca_state['cells'])