CellPyLib is a library for working with 1- and 2-dimensional k-color Cellular Automata in Python. CellPyLib-3d is an extension of this library, bringing support for 3-dimensional and 2-dimensional layered automata.

Example usage:

import cellpylib3d

# empty 3d grid
grid = cellpylib3d.init_simple3d(10, 10, 10, val=0) # init empty 3d grid

# oscilating shape from donut
grid[:, [3, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 7], 4, [4, 5, 6, 3, 7, 3, 7, 3, 7, 4, 5, 6]] = 1

# run using GOL ruleset for N timesteps
cellular_automaton = cellpylib3d.evolve3d(grid, timesteps=50, neighbourhood='Moore', apply_rule=cellpylib3d.game_of_life_rule_3d)

# animate
cellpylib3d.plot3d_animate(cellular_automaton, title='3D Game of Life')

import cellpylib3d

# empty 3d grid
grid = cellpylib3d.init_simple3d(10, 10, 7, val=0) # init empty 3d grid

# oscilating shape from donut
grid[:, [3, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 7], 4, [4, 5, 6, 3, 7, 3, 7, 3, 7, 4, 5, 6]] = 1

# each layer requires a separate rule
rules = [cellpylib3d.game_of_life_rule_parallel,] * 7

# run using GOL ruleset for N timesteps
cellular_automaton = cellpylib3d.evolveParallel(grid, timesteps=50, neighbourhood='Moore', apply_rules=rules)

# animate
cellpylib3d.plotParallel_animate(cellular_automaton, title='Parallel Game of Life')

CellPyLib can be installed via pip:

pip install cellpylib3d

Requirements for using this library are Python 3.7, NumPy, and Matplotlib. This extension library largely followsHave a look at the documentation, located at cellpylib.org, for more information.

Initialising 3d automata Arguments for tabled functions mirror 2d equivalent CellPyLib init_simple2d and init_random2d functions, unless noted.

Evolving Arguments for tabled functions mirror 2d equivalent CellPyLib evolve2d function.

Plotting Arguments for tabled functions mirror 2d equivalent CellPyLib plot2d and plot2d_animate functions, unless noted

Parallel CA are a more customisable form of 3d CA. Instead of applying a single 3d-aware ruleset to an entire CA, each layer of a parallel CA can have a seperate ruleset. This can be helpful for simulations with weak interaction between layers.

Initialising parallel automata Initialise your CA using the 3d functions described above. Parallel CA are treated at regular 3d shapes at a base level.

Evolving Arguments for tabled functions mirror 2d equivalent CellPyLib evolve2d function.

Plotting Arguments for tabled functions mirror 2d equivalent CellPyLib plot2d and plot2d_animate functions.

Create a Conda environment from the provided environment YAML file:

$ conda env create -f environment.yml

Documentation

To build the Sphinx documentation locally, from the doc directory:

$ make clean html

The generated files will be in _build/html.

To build the documentation for publication, from the doc directory:

$ make github

The generated files will be in _build/html and in the site/docs folder.

Testing

There are a number of unit tests for this project. To run the tests:

$ python3 -m pytest tests

If the pytest-cov package is installed, a coverage report can be generated by running the tests with:

$ python3 -m pytest tests/ --cov=cellpylib3d

Apache License 2.0