🧬 Replicode

“When code can reproduce, learn, and adapt, it becomes life in silicon.”

Replicode is a research framework for self-building, self-learning digital organisms inspired by Richard Dawkins’ Replicator concept and the evolutionary principles of NEAT and DeepNEAT.

Each organism in Replicode is a compiled program that can:

1. Act – interact with its environment and collect experience.
2. Learn – perform local backpropagation and sparse rewiring during its sleep phase.
3. Reproduce – mutate its genome, emit new C code, and compile an optimized offspring using TCC or LLVM Clang.

---

⚙️ System Overview

┌────────────┐ ┌─────────────┐ ┌────────────┐ │ Act │ ─→── │ Learn │ ─→── │ Reproduce │ │ (runtime) │ │ (backprop) │ │ (codegen) │ └────────────┘ └─────────────┘ └────────────┘

Architecture Layers

Layer	Purpose	Implementation
Genome	Stores network topology, sparse edges, and hyper-parameters	genome.h
Phenotype / Runtime	Executes forward/backward passes and dynamic sparse rewiring	runtime.h
Compiler Interface	Creates offspring code and builds new executables	codegen.c + TCC/Clang
Environment	Provides inputs, rewards, and fitness feedback	user-defined

---

🚀 Quick Start

# Clone and build
git clone https://gitlab.com/yourname/replicode.git
cd replicode
./build_tcc.sh         # rapid iteration build with TCC (outputs to ./build)
./build_clang.sh       # optimized Clang build artifacts in ./build

# Outputs:
# - ./build/parent_clang (dense-only by default)
# - ./build/codegen_clang
# - ./build/sample_clang
#
# Optional: build parent with sparse helpers enabled
# SPARSE=1 ./build_clang.sh
# ./build/parent_clang --sparse

# Manual dense builds (optional)
tcc -O2 main_parent.c -lm -o replicode.exe
clang -O3 -march=native -ffast-math main_parent.c -lm -o replicode

# Run dense parent runtime demo (prints loss/acc/timing)
./build/parent_clang

# Quick compiler smoke tests (Linux)
clang -O2 -std=c99 -I . examples/sample_dense.c -lm -o sample_dense && ./sample_dense
tcc   -O2 -std=c99 -I . examples/sample_dense.c -lm -o sample_dense_tcc && ./sample_dense_tcc
clang -O2 -std=c99 -I . evo/dense_gradcheck.c -lm -o dense_gradcheck && ./dense_gradcheck

# Run the parent organism
./replicode

Emit Dense Offspring

# Build the codegen tool (Clang example)
# (or use ./build/codegen_clang from ./build_clang.sh)
clang -O3 -std=c99 -I evo evo/codegen.c -lm -o build/codegen

# Generate a child source from the sample genome
./build/codegen --genome examples/sample_parent.gen --out build/child.c

# Compile the generated child together with an environment implementation
clang -O2 -std=c99 build/child.c examples/sample_env.c -lm -o build/child_dense
./build/child_dense

The emitted child uses only the dense runtime path and links against env_act, env_feedback, and env_fitness_window. Swap in your own environment implementation to evolve specialised offspring.

Organisms will act, learn, rewire, and—on reaching fitness thresholds—spawn new offspring by generating and compiling new C code.

🧩 Core Principles

Self-containment — Each organism is an independent executable with its own weights, topology, and learning rules.

Dense Core — Default genome/runtime path uses contiguous buffers for hot learning loops.

Sparse Plasticity — Optional CSR helpers in evo/sparse.* enable experiments without regressing dense performance.

Evolution through Compilation — Structural mutations produce new source code; compilation is reproduction.

Speed as Survival — Faster learners gain evolutionary advantage; compilation and backprop are both optimized.

📚 Inspiration

Richard Dawkins — The Selfish Gene (1976)

Kenneth O. Stanley & Risto Miikkulainen — Evolving Neural Networks through Augmenting Topologies (NEAT, 2002)

Stanley et al. — DeepNEAT / CoDeepNEAT (2017)

J. S. Alma & A. M. Clune — Evolving Deep Neural Networks (2018)