https://github.com/carmelolg/jcal
JCAL is a lightweight Java library for building and simulating Cellular Automata (CA) with minimal boilerplate. It provides a simple grid model, pluggable neighborhood strategies (Moore, Von Neumann, or custom), an abstract executor for transition rules, and optional parallel execution via Java streams.
https://github.com/carmelolg/jcal
cellular-automata computer-science java
Last synced: about 2 months ago
JSON representation
JCAL is a lightweight Java library for building and simulating Cellular Automata (CA) with minimal boilerplate. It provides a simple grid model, pluggable neighborhood strategies (Moore, Von Neumann, or custom), an abstract executor for transition rules, and optional parallel execution via Java streams.
- Host: GitHub
- URL: https://github.com/carmelolg/jcal
- Owner: carmelolg
- License: other
- Created: 2023-02-16T22:45:51.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2026-04-30T22:12:55.000Z (about 2 months ago)
- Last Synced: 2026-04-30T23:18:09.561Z (about 2 months ago)
- Topics: cellular-automata, computer-science, java
- Language: Java
- Homepage: https://carmelolg.github.io/JCAL/
- Size: 2.29 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 𧬠JCAL β Java Cellular Automata Library
> **Model natural and artificial phenomena** β lava flows, heat diffusion, Conway's Game of Life and more β with a
> clean, extensible Java API. 2D, 3D, and 4D grids out of the box.
## 𧩠What is a Cellular Automaton?
A Cellular Automaton (CA) is formally defined as the quadruple **``**:
| Symbol | Meaning |
|--------|-----------------------------------------------------------------|
| `Z^d` | A d-dimensional grid of cells |
| `S` | The finite set of states a cell can be in |
| `X` | The neighbourhood β which cells are considered "neighbours" |
| `Ο` | The transition function β how each cell evolves each generation |
With this model you can simulate a surprising range of natural phenomena: landslides, lava flows, epidemic spreading,
crystal growth, and more.
π More reading:
- [Wolfram β Cellular Automaton](https://mathworld.wolfram.com/CellularAutomaton.html)
- [The Nature of Code β Chapter 7](https://natureofcode.com/book/chapter-7-cellular-automata/) by Daniel Shiffman
- [Master thesis (Italian)](https://github.com/carmelolg/master-thesis/blob/master/Tesi/pdf/main.pdf) β the research
that inspired JCAL
---
## β¨ Features
- πΊοΈ **Multi-dimensional grids** β 2D, 3D, and 4D cellular automata with a single unified `CellGrid` API
- β‘ **Sequential & parallel execution** β choose `CellularAutomataExecutor` or `CellularAutomataParallelExecutor`
- π² **Built-in neighbourhoods** β Moore and Von Neumann in 2D, 3D, and 4D
- π **Fully extensible** β plug in any custom state, neighbourhood, or transition rule
- β
**100% test coverage** β 148 JUnit 5 tests, JaCoCo verified
---
## π Quick Start
### 1. Define your states
```java
CellState DEAD = new CellState("dead", "0");
CellState ALIVE = new CellState("alive", "1");
```
### 2. Configure the grid
```java
CellularAutomataConfiguration config = new CellularAutomataConfigurationBuilder()
.setWidth(10)
.setHeight(10)
.setTotalIterations(5)
.setDefaultStatus(DEAD)
.setInitalState(List.of(new Cell(ALIVE, 5, 4), new Cell(ALIVE, 5, 5), new Cell(ALIVE, 5, 6)))
.setNeighborhoodType(NeighborhoodType.MOORE)
.build();
```
### 3. Implement your rule
```java
class GameOfLifeRule extends CellularAutomataExecutor {
@Override
public Cell singleRun(Cell cell, List neighbors) {
long alive = neighbors.stream()
.filter(n -> n.getCurrentStatus().equals(ALIVE)).count();
Cell next = new Cell(DEAD, cell.getCol(), cell.getRow());
boolean isAlive = cell.getCurrentStatus().equals(ALIVE);
if ((!isAlive && alive == 3) || (isAlive && (alive == 2 || alive == 3)))
next.setCurrentStatus(ALIVE);
return next;
}
}
```
### 4. Run it
```java
CellularAutomata ca = new CellularAutomata(config);
ca =new
GameOfLifeRule().
run(ca);
System.out.
println(ca);
```
---
## π§ 3D Example β Carter Bays' Life
Going beyond 2D is just one builder call away:
```java
CellularAutomataConfiguration config = new CellularAutomataConfigurationBuilder()
.setDimensions(10, 10, 10) // 3D grid
.setTotalIterations(5)
.setDefaultStatus(DEAD)
.setNeighborhoodType(NeighborhoodType.MOORE) // resolves to Moore3DNeighborhood
.setInitalState(initialCells)
.build();
CellularAutomata ca = new CellularAutomata(config);
new
Carter3DLifeRule().
run(ca);
```
Access cells by coordinate array:
```java
CellGrid grid = ca.getGrid();
Cell cell = grid.get(new int[]{x, y, z});
```
---
## π Extension Points
| What to customise | How |
|------------------------------|----------------------------------------------------------------------------|
| Transition rule (sequential) | Extend `CellularAutomataExecutor`, implement `singleRun(Cell, List)` |
| Transition rule (parallel) | Extend `CellularAutomataParallelExecutor` instead |
| Cell state | Any `Object` as `value` in `CellState` (int, enum, Map, POJOβ¦) |
| Neighbourhood (2D) | Extend `Neighborhood`, implement `getNeighbors(CellGrid, int[])` |
| Neighbourhood (3D/4D) | Extend `Neighborhood` **+** implement marker interface `NDCapable` |
| CCA pre-processing | Override `refinements(Cell)` in your executor |
---
## π¦ Built-in Neighbourhoods
| Class | Dimensions | Neighbours |
|----------------------------|------------|------------|
| `MooreNeighborhood` | 2D | 8 |
| `VonNeumannNeighborhood` | 2D | 4 |
| `Moore3DNeighborhood` | 3D | 26 |
| `VonNeumann3DNeighborhood` | 3D | 6 |
| `Moore4DNeighborhood` | 4D | 80 |
| `VonNeumann4DNeighborhood` | 4D | 8 |
---
## π Documentation
Full API docs and guides at **[carmelolg.github.io/JCAL](https://carmelolg.github.io/JCAL/)**.
---
## π License
Released under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) β free for non-commercial use with
attribution.