Reference
cellpylib.apen

apen
(sequence, m=1, r=0) Calculates the Approximate Entropy, or ApEn, of the given sequence, as described in:
Pincus, S. M.; Gladstone, I. M.; Ehrenkranz, R. A. (1991). "A Regularity Statistic For Medical Data Analysis". Journal of Clinical Monitoring and Computing. 7 (4): 335345.
The implementation here is based on the Python implementation described in: https://en.wikipedia.org/wiki/Approximate_entropy
 Parameters
sequence – a string of whole numbers, such as ‘012301’, or an array of whole numbers, such as [0,1,2,3,0,1], or a numpy array of whole numbers
m – the length of compared runs of data
r – a filtering level
 Returns
a real number, representing the approximate entropy (ApEn) for the given sequence
cellpylib.bien

bien
(string) Calculate the BiEntropy of the given binary string, according to:
Croll, G. J. (2013). BiEntropyThe Approximate Entropy of a Finite Binary String. arXiv preprint arXiv:1305.0954.
The BiEntropy can be used to compare two binary strings in terms of the relative order and disorder of all the digits. It makes use of a weighted average of the Shannon entropies of all but the last binary derivative of the given string. This version of BiEntropy is suitable for strings with length <= 32.
 Parameters
string – a binary string, such as ‘110011’
 Returns
a real number representing the BiEntropy of the given string

binary_derivative
(string) Calculates the binary derivative of the given string, according to:
Nathanson, M. B. (1971). Derivatives of binary sequences. SIAM Journal on Applied Mathematics, 21(3), 407412
The derivative of a binary string is simply the bitwise exclusive OR between a binary digit in the string and its successor, if a successor exists. For example, the derivative of the binary string ‘01010101’ is the binary string ‘1111111’.
 Parameters
string – a binary string, such as ‘110011’
 Returns
a binary string representing the binary derivative of the given string

cyclic_binary_derivative
(string) Calculates the cyclic binary derivative, which is the “binary string of length n formed by XORing adjacent pairs of digits including the last and the first.” See:
Croll, G. J. (2018). The BiEntropy of Some Knots on the Simple Cubic Lattice. arXiv preprint arXiv:1802.03772.
The cyclic derivative of a binary string is simply the bitwise exclusive OR between a binary digit in the string and its successor, where the successor of the last digit in the string is the first digit in the string. For example, the cyclic derivative of the binary string ‘01010101’ is the binary string ‘11111111’.
 Parameters
string – a binary string, such as ‘110011’
 Returns
a binary string representing the cyclic binary derivative of the given string

ktbien
(string) Calculates the knot logarithmic weighting BiEntropy of the given string, according to:
Croll, G. J. (2018). The BiEntropy of Some Knots on the Simple Cubic Lattice. arXiv preprint arXiv:1802.03772.
The Logarithmic Knot BiEntropy can be used to compare two binary strings in terms of the relative order and disorder of all the digits. It makes use of a logarithmic weighted average of the Shannon entropies of all but the last cyclic binary derivative of the given string. This version of BiEntropy is suitable for strings with length > 32.
 Parameters
string – a binary string, such as ‘110011’
 Returns
a real number representing the knot logarithmic weighting BiEntropy of the given string

tbien
(string) Calculates the logarithmic weighting BiEntropy of the given string, according to:
Croll, G. J. (2013). BiEntropyThe Approximate Entropy of a Finite Binary String. arXiv preprint arXiv:1305.0954.
The Logarithmic BiEntropy can be used to compare two binary strings in terms of the relative order and disorder of all the digits. It makes use of a logarithmic weighted average of the Shannon entropies of all but the last binary derivative of the given string. This version of BiEntropy is suitable for strings with length > 32.
 Parameters
string – a binary string, such as ‘110011’
 Returns
a real number representing the logarithmic weighting BiEntropy of the given string
cellpylib.ca_functions

class
AsynchronousRule
(apply_rule, update_order=None, num_cells=None, randomize_each_cycle=False) Creates an asynchronous cellular automaton rule with a cyclic update scheme. Also known as a sequential cellular automaton rule, in NKS. This rule wraps a given rule, making the given rule asynchronous. This rule works for both 1D and 2D cellular automata.
This rule requires the specification of an update order (if none is provided, then an order is constructed based on the number of cells in the CA). An update order specifies which cell will be updated as the CA evolves. For example, the update order [2, 3, 1] states that cell 2 will be updated in the next timestep, followed by cell 3 in the subsequent timestep, and then cell 1 in the timestep after that. This update order is adhered to for the entire evolution of the CA. Cells that are not being updated do not have the rule applied to them in that timestep.
An option is provided to randomize the update order at the end of each cycle (i.e. timestep). This is equivalent to selecting a cell randomly at each timestep to update, leaving all others unchanged during that timestep.

class
BaseRule
A base rule class for custom rules to extend. A rule is a callable that accepts three parameters: 1, the current cell’s neighbourhood; 2, the index identifying the current cell; 3, an int identifying the current timestep. The rule returns the activity of the current cell at the next timestep.

class
BinaryRule
(rule, scheme=None, powers_of_two=None) A binary representation of the given rule number, which is used to determine the value to return. The process is approximately described as:
1. convert state to int, so [1,0,1] > 5, call this state_int 2. convert rule to binary, so 254 > [1,1,1,1,1,1,1,0], call this rule_bin_array 3. new value is rule_bin_array[7  state_int] we subtract 7 from state_int to be consistent with the numbering scheme used in NKS in NKS, rule 254 for a 1D binary cellular automaton is described as: [1,1,1] [1,1,0] [1,0,1] [1,0,0] [0,1,1] [0,1,0] [0,0,1] [0,0,0] 1 1 1 1 1 1 1 0
If None is provided for the scheme parameter, the neighbourhoods are listed in lexicographic order (the reverse of the NKS convention). If ‘nks’ is provided for the scheme parameter, the NKS convention is used for listing the neighbourhoods.

class
NKSRule
(nks_rule_number) An Elementary Cellular Automaton rule, indexed according the scheme in NKS.

class
ReversibleRule
(init_state, rule_number) An elementary cellular automaton rule explicitly set up to be reversible.

class
TotalisticRule
(k, rule) The totalistic rule as described in NKS. The average color is mapped to a whole number in [0, k  1]. The rule number is in base 10, but interpreted in base k. For a 1dimensional cellular automaton, there are 3k  2 possible average colors in the 3cell neighbourhood. There are n(k  1) + 1 possible average colors for a kcolor cellular automaton with an ncell neighbourhood.

binary_rule
(neighbourhood, rule, scheme=None, powers_of_two=None) Converts the given rule number to a binary representation, and uses this to determine the value to return. The process is approximately described as:
1. convert state to int, so [1,0,1] > 5, call this state_int 2. convert rule to binary, so 254 > [1,1,1,1,1,1,1,0], call this rule_bin_array 3. new value is rule_bin_array[7  state_int] we subtract 7 from state_int to be consistent with the numbering scheme used in NKS in NKS, rule 254 for a 1D binary cellular automaton is described as: [1,1,1] [1,1,0] [1,0,1] [1,0,0] [0,1,1] [0,1,0] [0,0,1] [0,0,0] 1 1 1 1 1 1 1 0
If None is provided for the scheme parameter, the neighbourhoods are listed in lexicographic order (the reverse of the NKS convention). If ‘nks’ is provided for the scheme parameter, the NKS convention is used for listing the neighbourhoods.
 Parameters
neighbourhood – a binary array of length 2r + 1
rule – an int or a binary array indicating the cellular automaton rule number
scheme – can be None (default) or ‘nks’; if ‘nks’ is given, the rule numbering scheme used in NKS is used
powers_of_two – a precomputed array containing the powers of two, e.g. [4,2,1]; can be None (default) or an array of length len(neighbourhood); if an array is given, it will used to speed up the calculation of state_int
 Returns
the result, 0 or 1, of applying the given rule on the given state

bits_to_int
(bits) Converts a binary array representing a binary number into the corresponding int.
 Parameters
bits – a list of 1s and 0s, representing a binary number
 Returns
and int representing the corresponding number

evolve
(cellular_automaton, timesteps, apply_rule, r=1, memoize=False) Evolves the given cellular automaton for the specified time steps. Applies the given function to each cell 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.
 Parameters
cellular_automaton – the cellular automaton starting condition representing the first time step, e.g. [[0,0,0,0,1,0,0,0,0]], or a history of previous states, with the last item in the given array being the starting condition for the evolution, e.g. [[0,0,0,0,0,0,0,0,0], [0,0,0,0,1,0,0,0,0]]
timesteps – the number of time steps in this evolution, or a callable that accepts the cellular automaton (in terms of the history of its evolution) and the current timestep number, and is expected to return a boolean indicating whether the evolution should continue; note that if a number is given, this value refers to the total number of time steps in this cellular automaton evolution, which includes the initial condition
apply_rule – a function representing the rule to be applied to each cell during the evolution; this function will be given three arguments, in the following order: the neighbourhood, which is a numpy array of length 2r + 1 representing the neighbourhood of the cell; the cell identity, which is a scalar representing the index of the cell in the cellular automaton array; the time step, which is a scalar representing the time step in the evolution
r – the neighbourhood radius; the neighbourhood size will be 2r + 1 (default is 1)
memoize – allowed values are True, False, and “recursive”; if True, then the result of applying the rule on a given neighbourhood will be cached, and used on subsequent invocations of the rule; if “recursive”, then a recursive memoized algorithm will be used, in which recursively wider neighbourhoods are cached, along with the result of applying the rule on the cells in the widened neighbourhood; the True and “recursive” options can result in a significant improvement to execution speed if the rule is expensive to invoke; the “recursive” option works best when there are strongly repetitive patterns in the CA, and when the state consists of 2^k cells; if False, then no caching will be used; NOTE: this should only be set to True or “recursive” for rules which do not store any state upon invocation, and for rules which do not depend in the cell index or timestep number (default is False)
 Returns
a matrix, containing the results of the evolution, where the number of rows equal the number of time steps specified

evolve_block
(cellular_automaton, block_size, timesteps, apply_rule) 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.
 Parameters
cellular_automaton – the cellular automaton starting condition representing the first time step, e.g. [[0,0,0,0,1,0,0,0,0]]
block_size – the number of cells in the block; the total number of cells in the CA must be divisible by the block size
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
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
 Returns
a matrix, containing the results of the evolution, where the number of rows equal the number of time steps specified

init_random
(size, k=2, n_randomized=None, empty_value=0, dtype=<class 'numpy.int32'>) Returns a randomly initialized array with values consisting of numbers in {0,…,k  1}, where k = 2 by default. If dtype is not an integer type, then values will be uniformly distributed over the halfopen interval [0, k  1).
 Parameters
size – the size of the array to be created
k – the number of states in the cellular automaton (2, by default)
n_randomized – the number of randomized sites in the array; this value must be >= 0 and <= size, if specified; if this value is not specified, all sites in the array will be randomized; the randomized sites will be centered in the array, while all others will have an empty value
empty_value – the value to use for nonrandomized sites (0, by default)
dtype – the data type
 Returns
a vector with shape (1, size), randomly initialized with numbers in {0,…,k  1}

init_simple
(size, val=1, dtype=<class 'numpy.int32'>) Returns an array initialized with zeroes, with its center value set to the specified value, or 1 by default.
 Parameters
size – the size of the array to be created
val – the value to be used in the center of the array (1, by default)
dtype – the data type
 Returns
a vector with shape (1, size), with its center value initialized to the specified value, or 1 by default

int_to_bits
(num, num_digits) Converts the given number, num, to the corresponding binary number in the form of a NumPy array of 1s and 0s comprised of num_digits digits.
 Parameters
num – the number, in base 10, to convert into binary
num_digits – the number of digits the binary number should contain
 Returns
a NumPy array of 1s and 0s representing the corresponding binary number

nks_rule
(neighbourhood, rule) A convenience function, that calls binary_rule with scheme = ‘nks’.
 Parameters
neighbourhood – a binary array of length 2r + 1
rule – an int indicating the cellular automaton rule number
 Returns
the result, 0 or 1, of applying the given rule on the given state

plot
(ca, title='', *, colormap='Greys', xlabel='', ylabel='time', show=True, **imshow_kwargs) Plots the given cellular automaton.
 Parameters
ca – the cellular automaton to plot
title – the title to place on the plot (default is empty)
colormap – the colormap to use (default is ‘Greys’)
xlabel – the label of the xaxis (default is empty)
ylabel – the label of the yaxis (default ‘time’)
show – show the plot (default is True)
imshow_kwargs – keyword arguments for the Matplotlib imshow function

plot_multiple
(ca_list, titles, *, colormap='Greys', xlabel='', ylabel='time', show=True, **imshow_kwargs) Plots multiple cellular automata separately.
 Parameters
ca_list – a list of cellular automata
titles – the titles to give the plots; there must be one title for each CA
colormap – the colormap to use for the plots (default is ‘Greys’)
xlabel – the label of the xaxis (default is empty)
ylabel – the label of the yaxis (default ‘time’)
show – show the plot (default is True)
imshow_kwargs – keyword arguments for the Matplotlib imshow function

totalistic_rule
(neighbourhood, k, rule) The totalistic rule as described in NKS. The average color is mapped to a whole number in [0, k  1]. The rule number is in base 10, but interpreted in base k. For a 1dimensional cellular automaton, there are 3k  2 possible average colors in the 3cell neighbourhood. There are n(k  1) + 1 possible average colors for a kcolor cellular automaton with an ncell neighbourhood.
 Parameters
neighbourhood – a kcolor array of any size
k – the number of colors in this cellular automaton, where only 2 <= k <= 36 is supported
rule – the kcolor cellular automaton rule number in base 10, interpreted in base k
 Returns
the result, a number from 0 to k  1, of applying the given rule on the given state

until_fixed_point
() Returns a callable to be used as the timesteps argument to the evolve and evolve2d functions, that will result in the evolution being halted when there have been no changes to the state of the CA in the last timestep. That is, if the last state of the CA is the same as the secondtolast state, the callable will return False, and evolution will be halted.
 Returns
a callable to be used as the timesteps argument to the evolve and evolve2d functions
cellpylib.ca_functions2d

evolve2d
(cellular_automaton, timesteps, apply_rule, r=1, neighbourhood='Moore', memoize=False) Evolves the given cellular automaton for the specified time steps. Applies the given function to each cell 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.
 Parameters
cellular_automaton – the cellular automaton starting condition representing the first time step, or a history of previous states, with the last item in the given array being the starting condition for the evolution
timesteps – the number of time steps in this evolution, or a callable that accepts the cellular automaton (in terms of the history of its evolution) and the current timestep number, and is expected to return a boolean indicating whether the evolution should continue; note that if a number is given, this value refers to the total number of time steps in this cellular automaton evolution, which includes the initial condition
apply_rule – a function representing the rule to be applied to each cell during the evolution; this function will be given three arguments, in the following order: the neighbourhood, which is a numpy 2D array of dimensions 2r+1 x 2r+1, representing the neighbourhood of the cell (if the ‘von Neumann’ neighbourhood is specified, the array will be a masked array); the cell identity, which is a tuple representing the row and column indices of the cell in the cellular automaton matrix, as (row, col); the time step, which is a scalar representing the time step in the evolution
r – the neighbourhood radius; the neighbourhood dimensions will be 2r+1 x 2r+1 (default is 1)
neighbourhood – the neighbourhood type; valid values are ‘Moore’ or ‘von Neumann’ (default is ‘Moore’)
memoize – allowed values are True, False, and “recursive”; if True, then the result of applying the rule on a given neighbourhood will be cached, and used on subsequent invocations of the rule; if “recursive”, then a recursive memoized algorithm will be used, in which recursively wider neighbourhoods are cached, along with the result of applying the rule on the cells in the widened neighbourhood; the True and “recursive” options can result in a significant improvement to execution speed if the rule is expensive to invoke; the “recursive” option works best when there are strongly repetitive patterns in the CA, and when the state consists of 2^k x 2^k cells; if False, then no caching will be used; NOTE: this should only be set to True or “recursive” for rules which do not store any state upon invocation, and for rules which do not depend in the cell index or timestep number (default is False)
 Returns
a list of matrices, containing the results of the evolution, where the number of rows equal the number of time steps specified

evolve2d_block
(cellular_automaton, block_size, timesteps, apply_rule) 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.
 Parameters
cellular_automaton – the cellular automaton starting condition representing the first time step
block_size – a 2tuple 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
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
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
 Returns
a list of matrices, containing the results of the evolution, where the number of rows equal the number of time steps specified

game_of_life_rule
(neighbourhood, c, t) Conway’s Game of Life rule.
 Parameters
neighbourhood – the current cell’s neighbourhood
c – the index of the current cell
t – the current timestep
 Returns
the state of the current cell at the next timestep

init_random2d
(rows, cols, k=2, dtype=<class 'numpy.int32'>) Returns a randomly initialized matrix with values consisting of numbers in {0,…,k  1}, where k = 2 by default. If dtype is not an integer type, then values will be uniformly distributed over the halfopen interval [0, k  1).
 Parameters
rows – the number of rows in the matrix
cols – the number of columns in the matrix
k – the number of states in the cellular automaton (2, by default)
dtype – the data type
 Returns
a tensor with shape (1, rows, cols), randomly initialized with numbers in {0,…,k  1}

init_simple2d
(rows, cols, val=1, dtype=<class 'numpy.int32'>, coords=None) Returns a matrix initialized with zeroes, with its center value set to the specified value, or 1 by default. If the coords argument is specified, then the specified cell at the given coordinates will have its value set to val, otherwise the center cell will be set.
 Parameters
rows – the number of rows in the matrix
cols – the number of columns in the matrix
val – the value to be used in the center of the matrix (1, by default)
dtype – the data type (np.int32 by default)
coords – a 2tuple specifying the row and column of the cell to be initialized (None by default)
 Returns
a tensor with shape (1, rows, cols), with the center value initialized to the specified value, or 1 by default

plot2d
(ca, timestep=None, title='', *, colormap='Greys', show_grid=False, show_margin=True, scale=0.6, show=True, **imshow_kwargs) Plots the state of the given 2D cellular automaton at the given timestep. If no timestep is provided, then the last timestep is plotted.
The show_margin argument controls whether or not a margin is displayed in the resulting plot. When show_margin is set to False, then the plot takes up the entirety of the window. The scale argument is only used when the show_margins argument is False. It controls the resulting scale (i.e. relative size) of the image when there are no margins.
 Parameters
ca – the 2D cellular automaton to plot
timestep – the timestep of interest
title – the title to place on the plot
colormap – the color map to use (default is “Greys”)
show_grid – whether to display a grid (default is False)
show_margin – whether to display the margin (default is True)
scale – the scale of the figure (default is 0.6)
show – show the plot (default is True)
imshow_kwargs – keyword arguments for the Matplotlib imshow function

plot2d_animate
(ca, title='', *, colormap='Greys', show_grid=False, show_margin=True, scale=0.6, dpi=80, interval=50, save=False, autoscale=False, show=True, **imshow_kwargs) Animate the given 2D cellular automaton.
The show_margin argument controls whether or not a margin is displayed in the resulting plot. When show_margin is set to False, then the plot takes up the entirety of the window. The scale argument is only used when the show_margins argument is False. It controls the resulting scale (i.e. relative size) of the image when there are no margins.
The dpi argument represents the dots per inch of the animation when it is saved. There will be no visible effect of the dpi argument if the animation is not saved (i.e. when save is False).
 Parameters
ca – the 2D cellular automaton to animate
title – the title to place on the plot (default is “”)
colormap – the color map to use (default is “Greys”)
show_grid – whether to display a grid (default is False)
show_margin – whether to display the margin (default is True)
scale – the scale of the figure (default is 0.6)
dpi – the dots per inch of the image (default is 80)
interval – the delay between frames in milliseconds (default is 50)
save – whether to save the animation to a local file (default is False)
autoscale – whether to autoscale the images in the animation; this should be set to True if the first frame has a uniform value (e.g. all zeroes) (default is False)
show – show the plot (default is True)
imshow_kwargs – keyword arguments for the Matplotlib imshow function
 Returns
the animation

plot2d_slice
(ca, slice=None, title='', *, colormap='Greys', show_grid=False, show_margin=True, scale=0.6, show=True, **imshow_kwargs) Plots a slice through the evolved states of a 2D cellular automaton. For example, consider the following ca, which may represent the evolution of a 3x3 2D cellular automaton over 3 timesteps:
[[[ 1, 2, 3], [ 4, 5, 6], [ 7, 8, 9]], [[10, 11, 12], [13, 14, 15], [16, 17, 18]], [[19, 20, 21], [22, 23, 24], [25, 26, 27]]]
By default, the following would be plotted:
[[ 4, 5, 6], [13, 14, 15], [22, 23, 24]]
If 0 is provided as the slice argument, then the following would be plotted:
[[ 1, 2, 3], [10, 11, 12], [19, 20, 21]]
The show_margin argument controls whether or not a margin is displayed in the resulting plot. When show_margin is set to False, then the plot takes up the entirety of the window. The scale argument is only used when the show_margins argument is False. It controls the resulting scale (i.e. relative size) of the image when there are no margins.
 Parameters
ca – the 2D cellular automaton to plot
slice – an int representing the index of the row to plot; by default, the “center” row is used
title – the title to place on the plot
colormap – the color map to use (default is “Greys”)
show_grid – whether to display a grid (default is False)
show_margin – whether to display the margin (default is True)
scale – the scale of the figure (default is 0.6)
show – show the plot (default is True)
imshow_kwargs – keyword arguments for the Matplotlib imshow function

plot2d_spacetime
(ca, alpha=None, title='', show=True) Plots the evolution of the given 2D cellular automaton as a 3D spacetime plot.
 Parameters
ca – the 2D cellular automaton to plot
alpha – the alpha blending value; a real number between 0 (transparent) and 1 (opaque)
title – the title to place on the plot
show – show the plot (default is True)
cellpylib.ctrbl_rule

class
CTRBLRule
(rule_table, add_rotations=False) A rule that operates on von Neumann neighbourhoods, taking into account the states of a cell’s neighbours at the top, right, bottom and left positions. Only supports 2D automata with periodic boundaries and a radius of 1.

property
rule_table
The rule table for this CTRBL rule.
 Returns
the rule table

property
cellpylib.entropy

average_cell_entropy
(cellular_automaton) Calculates the average cell entropy in the given cellular automaton, where entropy is the Shannon entropy. In the case of a 1D cellular automaton, the state of a cell over time is represented as a string, and its entropy is calculated. The same is done for all cells in this cellular automaton, and the average entropy is returned.
 Parameters
cellular_automaton – the cellular automaton to perform this operation on
 Returns
a real number representing the average cell Shannon entropy, in bits

average_mutual_information
(cellular_automaton, temporal_distance=1) Calculates the average mutual information between a cell and itself at the next n time steps, given by the specified temporal distance. A temporal distance of 1 means the next time step.
For example, consider the following string, ‘00101010110’, which represents the state of a cell over 11 time steps. The strings which will be used for the computation of the mutual information between a cell and itself at the next time step are: ‘0010101011’ and ‘0101010110’, since we pair each timestep value with its next value:
" 00101010110" "00101010110 "
 Parameters
cellular_automaton – the cellular automaton to perform this operation on
temporal_distance – the size of temporal separation, where the value must be greater than 0 and less than the number of time steps.
 Returns
a real number representing the average mutual information between a cell and itself at the next time step, in bits

joint_shannon_entropy
(stringX, stringY) Calculates the joint Shannon entropy between the given strings, which must be of the same length.
 Parameters
stringX – any string, such as ‘000101001’, ‘12402’, or ‘aBcd1234ef5g’
stringY – any string, such as ‘000101001’, ‘12402’, or ‘aBcd1234ef5g’
 Returns
a real number representing the joint Shannon entropy between the given strings, in bits

mutual_information
(stringX, stringY) Calculates the mutual information between the given strings, which must be of the same length.
 Parameters
stringX – any string, such as ‘000101001’, ‘12402’, or ‘aBcd1234ef5g’
stringY – any string, such as ‘000101001’, ‘12402’, or ‘aBcd1234ef5g’
 Returns
a real number representing the mutual information between the given strings, in bits

shannon_entropy
(string) Calculates the Shannon entropy for the given string.
 Parameters
string – any string, such as ‘000101001’, ‘12402’, or ‘aBcd1234ef5g’
 Returns
a real number representing the Shannon entropy, in bits
cellpylib.hopfield_net

class
HopfieldNet
(num_cells) An implementation of the Hopfield network. Due to limitations of this implementation, only an odd number of cells is supported.
For more information on Hopfield networks, see:
Hopfield, J. J. (1982). Neural networks and physical systems with emergent collective computational abilities. Proceedings of the national academy of sciences, 79(8), 25542558.

property
W
Returns the learned weight matrix.
 Returns
the learned weight matrix

property
r
The radius of this automaton.
 Returns
the radius

train
(P) The training set consists of patterns to be learned by this net. The patterns should be composed of bipolar ({1,1}), and not binary ({0,1}), values.
 Parameters
P – the set of training patterns

property
cellpylib.langtons_loop

class
LangtonsLoop
An implementation of Langton’s Loop, a kind of CTRBL rule. For more information, see:
Langton, C. G. (1984). Selfreproduction in Cellular Automata. Physica D: Nonlinear Phenomena, 10(12), 135144.
NOTE: This implementation is meant only for periodic boundary conditions, however, the original Langton’s loops rules here assume an infinitely sized space. There may be errors due to states missing from the rule table if the loops are allowed to overlap. (H. Sayama may have proposed a fix for this in his Ph.D. thesis.)

static
init_loops
(n, dim, row, col) Create the initial conditions by specifying the number of loops and their starting positions (as given by the coordinates of the first cell of the first row of the loop).
 Parameters
n – the number of loops to create
dim – a 2tuple representing the dimensions (number of rows and columns) of the CA
row – a list with length n, where the nth item specifies the row number of the nth loop
col – a list with length n, where the nth item specifies the column number of the nth loop
 Returns
the initial conditions

static
cellpylib.sdsr_loop

class
SDSRLoop
An implementation of H. Sayama’s SDSR loop. For more information, see:
Sayama, H. (1998). Constructing evolutionary systems on a simple deterministic cellular automata space. PhD, University of Tokyo, Department of Information Science.
cellpylib.evoloop

class
Evoloop
An implementation of H. Sayama’s Evoloop. For more information, see:
Sayama, H. (1998). Constructing evolutionary systems on a simple deterministic cellular automata space. PhD, University of Tokyo, Department of Information Science.

static
init_species13_loop
(dim, row, col) Create the initial conditions by specifying the a loop of species 13 and its starting position (as given by the coordinates of the first cell of the first row of the loop).
 Parameters
dim – a 2tuple representing the dimensions (number of rows and columns) of the CA
row – the row number of the loop
col – the column number of the loop
 Returns
the initial conditions

static
cellpylib.rule_tables

random_rule_table
(k, r, lambda_val=None, quiescent_state=None, strong_quiescence=False, isotropic=False) Constructs and returns a random rule table using the “randomtable” method, as described in:
Langton, C. G. (1990). Computation at the edge of chaos: phase transitions and emergent computation. Physica D: Nonlinear Phenomena, 42(13), 1237.
 Parameters
k – the number of cell states
r – the radius of the cellular automaton neighbourhood
lambda_val – a real number in (0., 1.), representing the value of lambda; if None, a default value of 1.0  1/k will be used, where all states will be represented equally in the rule table
quiescent_state – the state, a number in {0,…,k  1}, to use as the quiescent state
strong_quiescence – if True, all neighbourhood states uniform in cell state i will map to cell state i
isotropic – if True, all planar rotations of a neighbourhood state will map to the same cell state
 Returns
a tuple containing: a table describing a rule, constructed using the “randomtable” table method as described by C. G. Langton, the actual lambda value, and the quiescent state used

table_rule
(neighbourhood, table) A rule where the state is converted into a string, and looked up in the given table, to yield the return value.
 Parameters
neighbourhood – a kcolor array of length 2r + 1
table – a table (map) of string representations of each neighbourhood state to the associated next cell state value; for example, for k = 2 and r = 2, a valid table might be: {‘101’: 1, ‘111’: 0, ‘011’: 0, ‘110’: 1, ‘000’: 0, ‘100’: 0, ‘010’: 0, ‘001’: 1}
 Returns
a number, from 0 to k  1, associated with the given state as specified in the given table

table_walk_through
(rule_table, lambda_val, k, r, quiescent_state, strong_quiescence=False, isotropic=False) Perturbs the given rule table using the “tablewalkthrough” approach described in:
Langton, C. G. (1990). Computation at the edge of chaos: phase transitions and emergent computation. Physica D: Nonlinear Phenomena, 42(13), 1237.
The table’s actual lambda value will be increased or decreased, incrementally and stochastically, until it reaches the given lambda value.
 Parameters
rule_table – a table (map) of string representations of each neighbourhood state to the associated next cell state value; for example, for k = 2 and r = 2, a valid table might be: {‘101’: 1, ‘111’: 0, ‘011’: 0, ‘110’: 1, ‘000’: 0, ‘100’: 0, ‘010’: 0, ‘001’: 1}
lambda_val – a real number in (0., 1.), representing the value of lambda
k – the number of cell states
r – the radius of the cellular automaton neighbourhood
quiescent_state – the state, a number in {0,…,k  1}, to use as the quiescent state
strong_quiescence – if True, all neighbourhood states uniform in cell state i will map to cell state i
isotropic – if True, all planar rotations of a neighbourhood state will map to the same cell state
 Returns
a tuple containing: a table describing a rule, constructed using the “tablewalkthrough” method as described by C. G. Langton, the actual lambda value
cellpylib.sandpile

class
Sandpile
(rows, cols, is_closed_boundary=True) A rule that operates on von Neumann neighbourhoods with a radius of 1. A sandpile is a 2D cellular automaton and dynamical system that displays selforganized criticality. It was introduced by Bak, Tang and Wiesenfeld in 1987.

add_grain
(cell_index, timestep) Drop a grain of sand at the given cell in the given timestep.
 Parameters
cell_index – a 2tuple representing the row index and column index of the cell that will have a grain of sand added
timestep – the timestep at which the grain addition will occur
