giorgio/MachineSex
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Restructure: descriptive tier and experiment names, paper/manuscript

Browse source 
- paper/pnas -> paper/manuscript (venue-neutral)
- configs/layer1 -> configs/inheritance, src/knowledge -> src/inheritance
  (imported as `inheritance`), make layer1 -> make inheritance; layer2 alias dropped
- inheritance and trained-network bundles named after the manuscript figure
  they feed (fig2_grounding_sweep, figS3_rebaselining, ...), or descriptively
  where they feed none; configs keep their `experiment:` value so parquet
  hashes are unchanged, only output.dir moves
- figure scripts, SI figure sources, notebooks, REPRODUCING.md, README and the
  SI Methods/tables updated; make clean no longer deletes tracked manifests;
  reproduce.sh hashes the s{seed}/ layouts too

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y64o8FKP7rCuXzC48pxpMm
This commit is contained in:
Giorgio Gilestro 2026-09-13 17:00:40 +01:00
parent 84124de143
commit ab3dc10587
240 changed files with 477 additions and 476 deletions
Download patch file Download diff file Expand all files Collapse all files

21
README.md
View file

@ -12,7 +12,7 @@ The framework is developed at three tiers of increasing realism:
| Tier | What it is | Hardware |
|---|---|---|
| **Biological model** | Wright–Fisher simulator over knowledge distributions; closed forms, bitwise reproducible | laptop |
| **Inheritance model** | Wright–Fisher simulator over knowledge distributions; closed forms, bitwise reproducible | laptop |
| **Trained networks** | RNN / MLP / VAE on a synthetic mode universe with an exact oracle; convolutional VAE on MNIST | one GPU |
| **Language models** | LoRA specialists on Qwen2.5-Instruct (0.5B / 7B) with an exact-match verifier | one GPU / L40S |
@ -25,7 +25,7 @@ and artifact-hash verification.
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh # one-time, if needed
./reproduce.sh # env -> tests -> biological-model tier at committed seeds -> figures
./reproduce.sh # env -> tests -> inheritance-model tier at committed seeds -> figures
./reproduce.sh --with-gpu # ... and the trained-network + language-model tiers
```
@ -34,9 +34,9 @@ Or tier by tier:
```bash
make env # build .venv from the committed, hash-pinned uv.lock
make test # correctness + closed-form scientific validation (the spine of trust)
make layer1 # the biological model: E1-E12, E14, learning kernel
make inheritance # the inheritance model, every experiment at its committed seed
make figures # per-experiment figures, from committed parquets (no re-simulation)
make paper-figures # the manuscript's Fig. 1-7 + rebuild the PDF body
make paper-figures # the manuscript's Fig. 1-5 + rebuild the PDF bodies
```
`make help` is not defined, but every target carries a `##` description — `grep '##' Makefile`.
@ -56,20 +56,21 @@ make env-notebooks && jupyter lab notebooks/
## Layout
```
src/knowledge/ biological-model tier (imported as `knowledge`)
src/inheritance/ inheritance-model tier (imported as `inheritance`)
src/neural/ trained-network tier
src/llm/ language-model tier
configs/ one YAML per experiment: layer1/ neural/ llm/ (each declares its master seed)
configs/ one YAML per experiment: inheritance/ neural/ llm/ (each declares its master seed)
figures/ plot_*.py — per-experiment diagnostics, read results.parquet only
paper/pnas/ the manuscript: main.md, make_figs.py (Fig. 1-7), build.py, si.md
paper/manuscript/ the manuscript: main.md, si.md, make_figs.py (Fig. 1-5), si_figures.py, build.py
notebooks/ executable walkthroughs
hpc/ PBS job scripts for the 7B tier (Imperial CX3)
tests/ correctness + test_scientific_validation.py (the closed forms as assertions)
results/ run artifacts: results.parquet (gitignored) + resolved_config.yaml + manifest.json
results/ run artifacts: results.parquet (gitignored) + resolved_config.yaml + manifest.json;
bundles are named after the manuscript figure they feed (fig2_*, figS4_*)
```
Design documents: `paper/blueprint.md` (the normative build spec) and `paper/results-summary.md`
(plain-language + technical summary of every result).
Development history, design documents, pre-registrations and exploratory experiments that did not
reach the manuscript live on the `dev` branch; `main` holds only what reproduces the paper.
## The engineering contract