neuropercolation/README.md
Richard Feistenauer 9b527a044f Reworked CellularAutomaton to improve API and speed
+ Added CI
+ Restructured Project
+ Improved API Improved creation speed by factor of \~2
+ Improved execution speed by factor of \~15

- Removed multi processor since it doesn't work with the new setup and was not fast enough to matter.
2020-10-20 10:14:05 +00:00

5.8 KiB

Cellular Automaton

This package provides an cellular automaton for Python 3

A cellular automaton defines a grid of cells and a set of rules. All cells then evolve their state depending on their neighbours state simultaneously.

For further information on cellular automatons consult e.g. mathworld.wolfram.com

Yet another cellular automaton module?

It is not the first python module to provide a cellular automaton, but it is to my best knowledge the first that provides all of the following features:

  • easy to use
  • n dimensional
  • speed optimized
  • documented
  • tested

I originally did not plan to write a new cellular automaton module, but when searching for one, I just found some that had little or no documentation with an API that really did not fit my requirements and/or Code that was desperately asking for some refactoring.

So I started to write my own module with the goal to provide an user friendly API and acceptable documentation. During the implementation I figured, why not just provide n dimensional support and with reading Clean Code from Robert C. Martin the urge to have a clean and tested code with a decent coverage added some more requirements. The speed optimization and multi process capability was more of challenge for myself. IMHO the module now reached an acceptable speed, but there is still room for improvements (e.g. with Numba?).

Changelog

0.3.0

With the new changes I could improve the speed drastically: Creation time: * 1/2 Processing time: * 1/15

I however omitted the multiprocessing capabilities. Speed increase was minimal and the new structure allowing single processor to be that fast does not yet support MP usage.

The API did change!

  • No separate factory anymore: Just create a CellularAutomaton(...)
  • No Rule class anymore: Subclass CellularAutomaton and override evolve_rule and init_cell_state
  • Cell color is now defined by the CAWindow state_to_color_cb parameter.
  • Neighborhood does not need to know the dimension anymore

Installation

This module can be loaded and installed from pipy: pip install cellular-automaton

Usage

To start and use the automaton you will have to define four things:

  • The neighborhood
  • The dimensions of the grid
  • The evolution rule
  • The initial cell state
class MyCellularAutomaton(CellularAutomaton):
    def init_cell_state(self, coordinate: tuple) -> Sequence:
        return initial_cell_state

    def evolve_rule(self, last_state: tuple, neighbors_last_states: Sequence) -> Sequence:
        return next_cell_state


neighborhood = MooreNeighborhood(EdgeRule.IGNORE_EDGE_CELLS)
ca = MyCellularAutomaton(dimension=[100, 100],
                         neighborhood=neighborhood)

Neighbourhood

The Neighborhood defines for a cell neighbours in relative coordinates. The evolution of a cell will depend solely on those neighbours.

The Edge Rule passed as parameter to the Neighborhood defines, how cells on the edge of the grid will be handled. There are three options:

  • Ignore edge cells: Edge cells will have no neighbours and thus not evolve.
  • Ignore missing neighbours: Edge cells will add the neighbours that exist. This results in varying count of neighbours on edge cells.
  • First and last cell of each dimension are neighbours: All cells will have the same neighbour count and no edge exists.

Dimension

A list or Tuple which states each dimensions size. The example above defines a two dimensional grid with 100 x 100 cells.

There is no limitation in how many dimensions you choose but your memory and processor power.

Evolution and Initial State

To define the evolution rule and the initial state create a class inheriting from CellularAutomaton.

  • The init_cell_state method will be called once during the creation process for every cell.
    It will get the coordinate of that cell and is supposed to return a tuple representing that cells state.
  • The evolve_rule gets passed the last cell state and the states of all neighbors.
    It is supposed to return a tuple representing the new cell state.
    All new states will be applied simultaneously, so the order of processing the cells is irrelevant.

Visualisation

The package provides a module for visualization of a 2D automaton in a pygame window.

CAWindow(cellular_automaton=StarFallAutomaton()).run()

The visual part of this module is fully decoupled and thus should be easily replaceable.

Examples

The package contains three examples:

Those example implementations should provide a good start for your own project.

Getting Involved

Feel free to open pull requests, send me feature requests or even join as developer. There ist still quite some work to do.

And for all others, don't hesitate to open issues when you have problems!

Dependencies

For direct usage of the cellular automaton there is no dependency. If you want to use the display option however or execute the examples you will have to install pygame for visualisation. If you do for some reason not want to use this engine simply inherit from display.DrawEngine and overwrite the necessary methods. (for an example of how to do so see ./test/test_display.py)

Licence

This package is distributed under the Apache License, Version 2.0, see LICENSE.txt