adding docstrings to block CA evolve functions

Author: lantunes

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added `evolve_block` function
+- Added `evolve2d_block` function
+- Added block CA demos
 
 ## [2.3.1] - 2021-12-25
 

README.md

@@ -265,6 +265,35 @@ For more information about Conway's Game of Life, see:
 
 > Conway, J. (1970). The game of life. Scientific American, 223(4), 4.
 
+### Block Cellular Automata
+
+Instead of a rule applying to a single cell at a time (given its neighbourhood), a rule can apply to a block of cells, 
+given only the states of the cells in the block. Such a system is called a block cellular automaton. For example, the
+following code reproduces the block CA at the bottom of page 460 of [Wolfram's NKS](https://www.wolframscience.com/nks/):
+
+```python
+import cellpylib as cpl
+import numpy as np
+
+initial_conditions = np.array([[0]*13 + [1]*2 + [0]*201])
+
+def block_rule(n, t):
+ if n == (1, 1): return 1, 1
+ elif n == (1, 0): return 1, 0
+ elif n == (0, 1): return 0, 0
+ elif n == (0, 0): return 0, 1
+
+ca = cpl.evolve_block(initial_conditions, block_size=2, 
+ timesteps=200, apply_rule=block_rule)
+cpl.plot(ca)
+```
+
+<img src="https://raw.githubusercontent.com/lantunes/cellpylib/master/resources/block_ca_1d.png" width="50%"/>
+
+Block cellular automata can also exist in 2 dimensions, as the following example demonstrates:
+
+<img src="https://raw.githubusercontent.com/lantunes/cellpylib/master/resources/block_ca_2d.gif" width="65%"/>
+
 ### Increasing Execution Speed with Memoization
 
 Memoization is expected to provide an increase to execution speed when there is some overhead involved when invoking 

cellpylib/__init__.py

@@ -7,7 +7,7 @@
 For complete documentation, see: https://cellpylib.org
 """
 
-__version__ = "2.3.1"
+__version__ = "2.4.0"
 
 from .ca_functions import BaseRule, AsynchronousRule, ReversibleRule, binary_rule, init_simple, nks_rule, \
  totalistic_rule, plot_multiple, bits_to_int, int_to_bits, init_random, plot, evolve, until_fixed_point, NKSRule, \

cellpylib/ca_functions.py

@@ -60,12 +60,24 @@ def plot_multiple(ca_list, titles, *, colormap='Greys', xlabel='', ylabel='time'
 
 def evolve_block(cellular_automaton, block_size, timesteps, apply_rule):
  """
- TODO
+ Evolves the given block cellular automaton for the specified time steps. Applies the given function to each block
+ during the evolution. A cellular automaton is represented here as an array of arrays, or matrix. This function
+ expects an array containing the initial time step (i.e. initial condition, an array) for the cellular automaton.
+ The final result is a matrix, where the number of rows equal the number of time steps specified.
 
- :param cellular_automaton:
- :param block_size:
- :param timesteps:
- :param apply_rule:
+ :param cellular_automaton: the cellular automaton starting condition representing the first time step,
+ e.g. [[0,0,0,0,1,0,0,0,0]]
+
+ :param block_size: the number of cells in the block; the total number of cells in the CA must be divisible by the
+ block size
+
+ :param timesteps: the number of time steps in this evolution; this value refers to the total number of time steps
+ in this cellular automaton evolution, which includes the initial condition
+
+ :param apply_rule: a function representing the rule to be applied to each block during the evolution; this function
+ will be given two arguments, in the following order: a tuple containing the activities of the
+ cells in the block, and a scalar representing the timestep in the evolution; this function must
+ return a tuple with the new activities for the block
 
  :return: a matrix, containing the results of the evolution, where the number of rows equal the number of time steps
  specified

cellpylib/ca_functions2d.py

@@ -260,16 +260,27 @@ def _add_grid_lines(ca, ax, show_grid):
 
 def evolve2d_block(cellular_automaton, block_size, timesteps, apply_rule):
  """
- TODO
- :param cellular_automaton:
+ Evolves the given block cellular automaton for the specified time steps. Applies the given function to each block
+ during the evolution. A cellular automaton is represented here as an array of arrays, or matrix. This function
+ expects an array containing the initial time step (i.e. initial condition, an array) for the cellular automaton.
+ The final result is a matrix, where the number of rows equal the number of time steps specified.
 
- :param block_size:
+ :param cellular_automaton: the cellular automaton starting condition representing the first time step
 
- :param timesteps:
+ :param block_size: a 2-tuple representing the number of rows and columns in the block; the total number of cells in
+ the CA must be divisible by the block size
 
- :param apply_rule:
+ :param timesteps: the number of time steps in this evolution; this value refers to the total number of time steps
+ in this cellular automaton evolution, which includes the initial condition
 
- :return:
+ :param apply_rule: a function representing the rule to be applied to each block during the evolution; this function
+ will be given two arguments, in the following order: the block, which is a numpy 2D array with
+ the number of rows and columns specified in the `block_size`, and the time step, which is a
+ scalar representing the time step in the evolution; this function must return a 2D array
+ containing the new values of the block
+
+ :return: a list of matrices, containing the results of the evolution, where the number of rows equal the number
+ of time steps specified
  """
  initial_conditions = cellular_automaton[-1]
  _, rows, cols = cellular_automaton.shape