Cellumina

A library to easily crate and run Cellular Automata.

Features

Cellumina provides an Automaton struct that represents a 2-dimensional grid of characters. This grid can be initialized from a vector, a file or an image. Additionally, the user can configure the Rule the automaton uses to transform itself into the next step. The transformation to the next state can be initiated manually or on a fixed time step, for example when using Cellumina as part of a larger graphical application.

Rules

• Pattern Replacement Rules
  • Specifiy a pattern that is searched each stepped and replaced with a second pattern.
  • Example: Falling Sand Simulations.
• Environment Rules
  • The next state of a cell is fully determined by its environment in the step before.
  • Example: Rule 90.
  • Example: Game Of Life.

These rules can be added by creating these struct using normal Rust code.

The Patter Replacement Rules can also (de-)serialized by using serde or loaded from (and saved to) a custom file type. This representation is more humanly readable than the serde version and can easily be created by hand if you do not want your rust files to contain large amounts of grid initializations for the patterns.

Additionally, the public trait Rule can be overwritten to implement completely custom rules.

Live View

Cellumina can be run in 'Live View' mode. It will then take ownership of a configured automaton, run it by itself and display the cell state in a separate window. This is useful when just playing around with cellular automata.

The user can also directly change the state of cells. Press any (character or space) button, and then mouse clicks will replace the currently hovered cell with the pressed character. The automaton can also be paused and resumed with Enter. The current state of the automaton can be saved to a file with Ctrl + S, currently the following formats are supported: txt (with one row of chararcters per line) as well as png, jpeg, ico, pnm, bmp, exr, tiff (exactly those supported by the image crate). Normal restrictions of those files apply, e.g. saving to jpeg may result in compression, so .jpeg-files are not suited for saving and reloading automata.

The live view functionality is not included in the library by default and must be enabled via the display feature.

Usage

To use Cellumina in your own project, simply add this line to your Cargo.toml file:

  [dependencies]
  cellumina = "0.1"

or

  [dependencies]
  cellumina = {version = "0.1", features = ["display"]}

if you want to enable live view.

Examples

The examples folder contains the following examples:

• game_of_life: An implementation of conways game of life using environment rules.
• sand: A small falling sand simulation using pattern replacement rules to simulate falling sand, fire and ash.
• rule90: A implementation of the Rule 90 1-dimensional cellular automaton that demonstrates how to use Cellumina's 2D-grid to display multiple successive states of a 1-dimensional automaton.
• to_string: An example that shows how to convert rules to and from the different string/file types.

All examples can be run by cloning this repository with

   git clone https://github.com/Linus-Mussmaecher/cellumina

and executed by using cargo run --examples <name> --features="display", for example

  cargo run --examples sand --features="display"

Logging

Cellumina supports logging via the log crate. You can use any logger, such as env-log or simple-logger, initialize them as described in their documentations and receive log outputs from cellumina.

Performance

Since pattern replacement can be a rather costly operation, cellumina runs these in parallel using the rayon crate. Small patterns (as they may appear when e.g. using a falling sand simulation to create a death animation or similar) have negligible runtime. Larger patters, especially with many patters or rules, may require more calculation time but can still be viewed in high FPS when running on their own. Note that the runtime differs considerably between compilation in debug and release configuration.