{"id":49616166,"url":"https://github.com/carmelolg/jcal","last_synced_at":"2026-05-04T22:02:10.590Z","repository":{"id":75044909,"uuid":"602769865","full_name":"carmelolg/JCAL","owner":"carmelolg","description":"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.","archived":false,"fork":false,"pushed_at":"2026-04-30T22:12:55.000Z","size":2401,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-30T23:18:09.561Z","etag":null,"topics":["cellular-automata","computer-science","java"],"latest_commit_sha":null,"homepage":"https://carmelolg.github.io/JCAL/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carmelolg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-02-16T22:45:51.000Z","updated_at":"2026-04-30T22:13:00.000Z","dependencies_parsed_at":"2023-07-05T19:31:58.988Z","dependency_job_id":null,"html_url":"https://github.com/carmelolg/JCAL","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/carmelolg/JCAL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carmelolg%2FJCAL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carmelolg%2FJCAL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carmelolg%2FJCAL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carmelolg%2FJCAL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carmelolg","download_url":"https://codeload.github.com/carmelolg/JCAL/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carmelolg%2FJCAL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32626501,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cellular-automata","computer-science","java"],"created_at":"2026-05-04T22:01:56.330Z","updated_at":"2026-05-04T22:02:10.585Z","avatar_url":"https://github.com/carmelolg.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧬 JCAL — Java Cellular Automata Library\n\n\u003cimg src=\"https://img.shields.io/badge/License-CC_BY--NC--SA_4.0-lightgrey.svg\" alt=\"License\"/\u003e \u003cimg src=\".github/badges/jacoco.svg\" alt=\"Test Coverage\"/\u003e \u003cimg src=\"https://img.shields.io/badge/Java-16-orange.svg\" alt=\"Java 16\"/\u003e \u003cimg src=\"https://img.shields.io/badge/build-Maven-blue.svg\" alt=\"Maven\"/\u003e\n\n\u003e **Model natural and artificial phenomena** — lava flows, heat diffusion, Conway's Game of Life and more — with a\n\u003e clean, extensible Java API. 2D, 3D, and 4D grids out of the box.\n\n## 🧩 What is a Cellular Automaton?\n\nA Cellular Automaton (CA) is formally defined as the quadruple **`\u003cZ^d, S, X, σ\u003e`**:\n\n| Symbol | Meaning                                                         |\n|--------|-----------------------------------------------------------------|\n| `Z^d`  | A d-dimensional grid of cells                                   |\n| `S`    | The finite set of states a cell can be in                       |\n| `X`    | The neighbourhood — which cells are considered \"neighbours\"     |\n| `σ`    | The transition function — how each cell evolves each generation |\n\nWith this model you can simulate a surprising range of natural phenomena: landslides, lava flows, epidemic spreading,\ncrystal growth, and more.\n\n📖 More reading:\n\n- [Wolfram — Cellular Automaton](https://mathworld.wolfram.com/CellularAutomaton.html)\n- [The Nature of Code — Chapter 7](https://natureofcode.com/book/chapter-7-cellular-automata/) by Daniel Shiffman\n- [Master thesis (Italian)](https://github.com/carmelolg/master-thesis/blob/master/Tesi/pdf/main.pdf) — the research\n  that inspired JCAL\n\n---\n\n## ✨ Features\n\n- 🗺️ **Multi-dimensional grids** — 2D, 3D, and 4D cellular automata with a single unified `CellGrid` API\n- ⚡ **Sequential \u0026 parallel execution** — choose `CellularAutomataExecutor` or `CellularAutomataParallelExecutor`\n- 🔲 **Built-in neighbourhoods** — Moore and Von Neumann in 2D, 3D, and 4D\n- 🔌 **Fully extensible** — plug in any custom state, neighbourhood, or transition rule\n- ✅ **100% test coverage** — 148 JUnit 5 tests, JaCoCo verified\n\n---\n\n## 🚀 Quick Start\n\n### 1. Define your states\n\n```java\nCellState DEAD = new CellState(\"dead\", \"0\");\nCellState ALIVE = new CellState(\"alive\", \"1\");\n```\n\n### 2. Configure the grid\n\n```java\nCellularAutomataConfiguration config = new CellularAutomataConfigurationBuilder()\n        .setWidth(10)\n        .setHeight(10)\n        .setTotalIterations(5)\n        .setDefaultStatus(DEAD)\n        .setInitalState(List.of(new Cell(ALIVE, 5, 4), new Cell(ALIVE, 5, 5), new Cell(ALIVE, 5, 6)))\n        .setNeighborhoodType(NeighborhoodType.MOORE)\n        .build();\n```\n\n### 3. Implement your rule\n\n```java\nclass GameOfLifeRule extends CellularAutomataExecutor {\n    @Override\n    public Cell singleRun(Cell cell, List\u003cCell\u003e neighbors) {\n        long alive = neighbors.stream()\n                .filter(n -\u003e n.getCurrentStatus().equals(ALIVE)).count();\n        Cell next = new Cell(DEAD, cell.getCol(), cell.getRow());\n        boolean isAlive = cell.getCurrentStatus().equals(ALIVE);\n        if ((!isAlive \u0026\u0026 alive == 3) || (isAlive \u0026\u0026 (alive == 2 || alive == 3)))\n            next.setCurrentStatus(ALIVE);\n        return next;\n    }\n}\n```\n\n### 4. Run it\n\n```java\nCellularAutomata ca = new CellularAutomata(config);\nca =new\n\nGameOfLifeRule().\n\nrun(ca);\nSystem.out.\n\nprintln(ca);\n```\n\n---\n\n## 🧊 3D Example — Carter Bays' Life\n\nGoing beyond 2D is just one builder call away:\n\n```java\nCellularAutomataConfiguration config = new CellularAutomataConfigurationBuilder()\n        .setDimensions(10, 10, 10)              // 3D grid\n        .setTotalIterations(5)\n        .setDefaultStatus(DEAD)\n        .setNeighborhoodType(NeighborhoodType.MOORE)   // resolves to Moore3DNeighborhood\n        .setInitalState(initialCells)\n        .build();\n\nCellularAutomata ca = new CellularAutomata(config);\nnew\n\nCarter3DLifeRule().\n\nrun(ca);\n```\n\nAccess cells by coordinate array:\n\n```java\nCellGrid grid = ca.getGrid();\nCell cell = grid.get(new int[]{x, y, z});\n```\n\n---\n\n## 🔌 Extension Points\n\n| What to customise            | How                                                                        |\n|------------------------------|----------------------------------------------------------------------------|\n| Transition rule (sequential) | Extend `CellularAutomataExecutor`, implement `singleRun(Cell, List\u003cCell\u003e)` |\n| Transition rule (parallel)   | Extend `CellularAutomataParallelExecutor` instead                          |\n| Cell state                   | Any `Object` as `value` in `CellState` (int, enum, Map, POJO…)             |\n| Neighbourhood (2D)           | Extend `Neighborhood`, implement `getNeighbors(CellGrid, int[])`           |\n| Neighbourhood (3D/4D)        | Extend `Neighborhood` **+** implement marker interface `NDCapable`         |\n| CCA pre-processing           | Override `refinements(Cell)` in your executor                              |\n\n---\n\n## 📦 Built-in Neighbourhoods\n\n| Class                      | Dimensions | Neighbours |\n|----------------------------|------------|------------|\n| `MooreNeighborhood`        | 2D         | 8          |\n| `VonNeumannNeighborhood`   | 2D         | 4          |\n| `Moore3DNeighborhood`      | 3D         | 26         |\n| `VonNeumann3DNeighborhood` | 3D         | 6          |\n| `Moore4DNeighborhood`      | 4D         | 80         |\n| `VonNeumann4DNeighborhood` | 4D         | 8          |\n\n---\n\n\n## 📖 Documentation\n\nFull API docs and guides at **[carmelolg.github.io/JCAL](https://carmelolg.github.io/JCAL/)**.\n\n---\n\n## 📄 License\n\nReleased under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) — free for non-commercial use with\nattribution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarmelolg%2Fjcal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarmelolg%2Fjcal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarmelolg%2Fjcal/lists"}