181 lines
5.5 KiB
Markdown
181 lines
5.5 KiB
Markdown
# MabeLabRS — a Rust port of MABE2
|
|
|
|
**MabeLabRS** is a Rust re-implementation of the MSU **MABE2** artificial life framework, aiming for:
|
|
- **API parity** where sensible, with a modern Rust design (traits, enums, safe concurrency).
|
|
- **Determinism** for research reproducibility (seeded RNG, stable iteration order).
|
|
- **Portability** to the web (WASM) for teaching demos (evo-edu.org) and outreach (TalkOrigins).
|
|
|
|
> Upstream: MABE2 (C++, MIT) — https://github.com/mercere99/MABE2
|
|
> This project is an independent port; see **License & Attribution** below.
|
|
|
|
---
|
|
|
|
## Project status
|
|
|
|
- 🚧 **Pre-alpha (porting in progress)** — core traits and module skeletons are landing first.
|
|
- 🎯 Goals: organism + genome abstractions, worlds/topologies, evaluators, experiment runner, config I/O, parity tests.
|
|
|
|
---
|
|
|
|
## Workspace layout
|
|
|
|
- mabelabrs/
|
|
- ├─ Cargo.toml # [workspace]
|
|
- ├─ rust-toolchain.toml # pin stable or MSRV
|
|
- ├─ LICENSE-APACHE
|
|
- ├─ LICENSE-MIT
|
|
- ├─ ACKNOWLEDGEMENTS.md
|
|
- ├─ README.md
|
|
- ├─ crates/
|
|
- │ ├─ mabelabrs-core/ # genomes, organisms, traits, RNG & schedulers
|
|
- │ ├─ mabelabrs-world/ # populations, environments, spatial/graph topologies
|
|
- │ ├─ mabelabrs-eval/ # tasks, fitness functions, analyzers
|
|
- │ ├─ mabelabrs-io/ # serde configs, logging, (bincode/json) state
|
|
- │ ├─ mabelabrs-utils/ # CLI runner, experiment manifests
|
|
- │ └─ mabelabrs-ffi/ # optional C++ bridge to MABE2 for parity (feature-gated)
|
|
- ├─ tests/
|
|
- │ ├─ golden/ # small deterministic fixtures
|
|
- │ └─ parity/ # cross-lang checks (behind ffi feature)
|
|
- ├─ benches/ # criterion benches for hotspots
|
|
- └─ porting/ # LLM-driven port tooling (only on porting branch)
|
|
- ├─ TRANSLATION_GLOSSARY.md
|
|
- ├─ STYLE.md
|
|
- ├─ DETERMINISM.md
|
|
- ├─ UNSAFE_POLICY.md
|
|
- ├─ prompts/
|
|
- └─ tools/ # scripts to run local LLM, compile, test, open PRs
|
|
|
|
|
|
---
|
|
|
|
## Why Rust?
|
|
|
|
- **Memory safety** and clear ownership models for complex evolutionary simulations.
|
|
- **Deterministic** iteration and seeded RNG for reproducibility.
|
|
- **Great tooling** (cargo, clippy, criterion, proptest) and easy WASM targets for classroom demos.
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# clone
|
|
git clone <your-forgejo-url>/MabeLabRS.git
|
|
cd MabeLabRS
|
|
|
|
# build all crates
|
|
cargo build
|
|
|
|
# run tests
|
|
cargo test
|
|
|
|
# optional parity tests (requires C++ MABE2 + ffi feature)
|
|
cargo test -p mabelabrs-ffi --features ffi
|
|
|
|
|
|
Feature flags:
|
|
|
|
ffi — enable C++ bridge for cross-language parity tests.
|
|
|
|
fast-math — allow non-deterministic float reductions (off by default).
|
|
|
|
Determinism
|
|
|
|
RNG: rand_chacha (documented seed in experiment manifest).
|
|
|
|
Order-sensitive collections: indexmap where iteration order matters.
|
|
|
|
Parallelism: gated by feature flags (rayon), default serial to preserve bit-for-bit comparable runs.
|
|
|
|
Using with evo-edu.org / TalkOrigins
|
|
|
|
WASM builds will be provided as examples under examples/wasm/ for web-hosted demos and teaching modules.
|
|
|
|
Naming and metadata optimized for search discoverability: MabeLabRS / mabelabrs-* crates.
|
|
|
|
Contributing
|
|
|
|
Discuss issues in the tracker; claim a module before starting.
|
|
|
|
Follow STYLE.md and UNSAFE_POLICY.md.
|
|
|
|
Every PR must:
|
|
|
|
compile (cargo check),
|
|
|
|
be formatted (cargo fmt),
|
|
|
|
lint cleanly (cargo clippy -- -D warnings),
|
|
|
|
include tests for added behavior.
|
|
|
|
Deterministic tests belong in tests/golden/. Heavier regression and parity tests go in tests/parity/.
|
|
|
|
We welcome LLM-assisted contributions only if the result compiles and includes tests. Please include the prompt and model info in the PR description for provenance.
|
|
|
|
Branch strategy
|
|
|
|
main: always buildable; docs + examples meant for users.
|
|
|
|
porting: long-lived branch for translation scripts, FFI harnesses, and staged module ports.
|
|
|
|
Feature branches: feat/<module> or fix/<area>; merge into porting, and periodically milestone-merge porting → main when a vertical slice is stable (e.g., genome+mutation+simple world).
|
|
|
|
Protect main and porting with required checks.
|
|
|
|
License & Attribution
|
|
|
|
Port license: Dual MIT OR Apache-2.0 (choose at your option).
|
|
See LICENSE-MIT and LICENSE-APACHE.
|
|
|
|
Upstream attribution:
|
|
This project is a Rust port inspired by MABE2 (MIT) and conceptually by the Empirical library (MIT).
|
|
Copyright and license notices from upstream are preserved in ACKNOWLEDGEMENTS.md.
|
|
|
|
You may use MabeLabRS under the terms of MIT or Apache-2.0.
|
|
|
|
Citation
|
|
|
|
If you use MabeLabRS in academic work, please cite MABE2 as appropriate and this repository (commit or release tag). A CITATION.cff will be added at first release.
|
|
|
|
Roadmap (short)
|
|
|
|
Core traits: Genome, Organism, Evaluator, World, Scheduler
|
|
|
|
Config & manifests (serde + JSON/TOML)
|
|
|
|
Minimal world & evaluator example with golden tests
|
|
|
|
Optional ffi parity tests against MABE2
|
|
|
|
WASM demo example for evo-edu.org
|
|
|
|
First alpha release on crates.io
|
|
|
|
|
|
---
|
|
|
|
## Container-first workflow
|
|
|
|
This repo ships with a containerized toolchain for **development**, **testing**, and **releases**.
|
|
|
|
### Quick start (Dev container)
|
|
```bash
|
|
# one-time build of the dev image (with Rust toolchain, sccache, tools)
|
|
docker compose build dev
|
|
|
|
# launch an interactive dev shell with your repo mounted at /work
|
|
docker compose run --rm dev bash
|
|
|
|
# inside the container
|
|
cargo build
|
|
cargo test
|
|
cargo clippy -- -D warnings
|
|
|
|
# Generative AI Notice
|
|
|
|
This project is planned to be largely conducted through the use of generative AI tools,
|
|
including OpenAI ChatGPT. While the plan is to conduct testing, be aware that
|
|
generative AI may not be entirely accurate in its outputs, and determine suitability
|
|
to purpose incorporating this information.
|