Architecture

io.github.carmelolg.jcal
├── core/
│   ├── CellularAutomata                   ← the grid (CellGrid); holds neighbourhood + config
│   ├── CellularAutomataConfiguration      ← immutable config; use inner Builder
│   │   └── CellularAutomataConfigurationBuilder
│   ├── CellularAutomataRule           ← abstract; extend to define the transition rule
│   └── parallel/
│       ├── CellularAutomataParallelRule   ← parallel variant of the executor
│       ├── Runner                             ← internal — Callable for parallel transition
│       └── RefinementRunner                   ← internal — Callable for parallel refinement
│
├── grid/
│   ├── Cell                               ← one cell; has a CellState + int[] coordinates
│   ├── CellState                          ← a cell's state; key + arbitrary value Object
│   ├── CellGrid                           ← unified n-dimensional grid (2D–4D, flat array)
│   └── GridDimensions                     ← immutable nD descriptor (sizes, strides, total)
│
├── neighborhood/
│   ├── Neighborhood                       ← abstract base; extend for custom neighbourhoods
│   ├── NDCapable                          ← marker interface; implement for 3D/4D custom neighbourhoods
│   ├── NeighborhoodType                   ← enum: MOORE | VON_NEUMANN
│   ├── MooreNeighborhood                  ← built-in 2D: 8 surrounding cells
│   ├── VonNeumannNeighborhood             ← built-in 2D: 4 orthogonal cells
│   ├── Moore3DNeighborhood                ← built-in 3D: 26 surrounding cells
│   ├── VonNeumann3DNeighborhood           ← built-in 3D: 6 orthogonal cells
│   ├── Moore4DNeighborhood                ← built-in 4D: 80 surrounding cells
│   └── VonNeumann4DNeighborhood           ← built-in 4D: 8 orthogonal cells
│
├── utils/
│   └── Utils                              ← internal helpers (isInside, cloneGrid)
│
└── examples/
    ├── GameOfLifeExample                  ← 2D minimal runnable example
    ├── GameOfLife3DExample                ← 3D example: Carter Bays' 3D Life
    └── CustomStateExample                 ← advanced example with multi-value state

for each generation:
  1. refinements(cell)           — applied to every cell  [optional CCA hook]
  2. snapshot the grid           — clone the grid before any mutation
  3. transition(cell, neighbors)  — per cell, reads snapshot, writes result
  4. copy result back            — update the main grid with all new states

Cell   get(int[] coords)
void   set(int[] coords, Cell cell)
List<int[]> allCoordinates()
GridDimensions getDimensions()
boolean is2D()

flat index = coords[0] * stride[0] + coords[1] * stride[1] + … + coords[n-1] * stride[n-1]

public class MyRule extends CellularAutomataRule {
    @Override
    public Cell transition(Cell cell, List<Cell> neighbors) {
        // inspect cell.getCurrentStatus() and neighbors
        // return a new Cell with the next state
    }
}

CellState complex = new CellState("state", Map.of("temp", 100, "pressure", 3));

public class DiagonalNeighborhood extends Neighborhood {
    @Override
    public List<Cell> getNeighbors(Cell[][] matrix, int i, int j) {
        // return a list of neighbor cells
    }
}

public class Custom3DNeighborhood extends Neighborhood {
    @Override
    public List<Cell> getNeighbors(CellGrid grid, int[] coords) {
        // return a list of neighbor cells
    }
}

@Override
public Cell refinements(Cell cell) {
    // update internal state before neighbors are read
    return cell;
}

CellularAutomataConfigurationBuilder
    → CellularAutomataConfiguration (immutable)
    → CellularAutomata(config)       ← builds CellGrid + resolves neighborhood
    → executor.run(ca)               ← applies transition for N generations
    → updated CellularAutomata