Awesome
CellPyLib 3D
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')
Getting Started
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.
3D extensions
Initialising 3d automata
Arguments for tabled functions mirror 2d equivalent CellPyLib init_simple2d and init_random2d functions, unless noted.
| Func | Special Args | Docs |
|---|---|---|
init_simple3d | Requires additional layers arg. | Returns a matrix initialized with zeroes, with its center value set to the specified value, or 1 by default. |
init_random3d | Requires additional layers arg. | Returns a randomly initialized matrix with values consisting of numbers in {0,...,k - 1}, where k = 2 by default. |
Evolving
Arguments for tabled functions mirror 2d equivalent CellPyLib evolve2d function.
| Func | Docs |
|---|---|
evolve3d | Evolve cellular automata in 3-dimensional space using 3d-aware ruleset. |
Plotting
Arguments for tabled functions mirror 2d equivalent CellPyLib plot2d and plot2d_animate functions, unless noted
| Func | Special Args | Docs |
|---|---|---|
plot3d | Replaces cmap argument with options for voxel cube face color and edge color (defaults face_color='#1f77b4', edge_color='gray') | Plot 3d CA at given timestep using voxels. |
plot3d_animate | Replaces cmap argument with options for voxel cube face color and edge color (defaults face_color='#1f77b4', edge_color='gray') | Animate 3d CA using voxels. |
Parallel extensions
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.
| Func | Docs |
|---|---|
evolveParallel | Evolve a layers of a 3d cellular automata using seperate 2D/3d-aware rulesets. |
Plotting
Arguments for tabled functions mirror 2d equivalent CellPyLib plot2d and plot2d_animate functions.
| Func | Docs |
|---|---|
plotParallel | Slice the 3D CA and subplot each layer for a given timestep. |
plotParallel_animate | Slice the 3D CA and animate each subplot of each layer. |
Development
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