# 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.