MachineSex/Makefile

# Layer 1 + Layer 1.5 automation. The uv venv (built from the committed uv.lock) is the
# reproducibility source of truth; every target runs inside it via `uv run`.

.PHONY: env env-neural env-mnist env-llm env-notebooks test layer1 layer2 neural mnist llm \
	llm-epistasis llm-society llm-society-calib llm-society-calib-b llm-society-v2-smoke \
	figures paper-figures paper notebooks clean

env:               ## build .venv from the committed lockfile
	uv sync --extra dev

env-neural:        ## add the Layer 1.5 torch stack (GPU; Stage C onward)
	uv sync --extra dev --extra neural

env-mnist:         ## add torchvision for the real-MNIST confirmation tier
	uv sync --extra dev --extra neural --extra mnist

test:              ## correctness tests + scientific-validation tests (the spine of trust)
	uv run pytest

layer1:            ## run experiments E1-E6 + the learning-kernel bridge (analytic)
	for e in E1 E2 E3 E4 E5 E6 E7 E8 E9 E10 E11 E12 E12_nk E14 kernel_sharpen kernel_smooth; do uv run python -m knowledge.experiment configs/layer1/$$e.yaml; done

neural:            ## run Layer 1.5 synthetic neural experiments (excludes the MNIST/torchvision tiers)
	for c in configs/neural/*.yaml; do case "$$c" in *mnist*|*speciation_real*) ;; \
		*) uv run python -m neural.experiment "$$c" ;; esac; done

mnist:             ## run the torchvision tiers: MNIST collapse + E13 real-weight speciation (needs env-mnist)
	uv run python -m neural.experiment configs/neural/mnist_collapse.yaml
	uv run python -m neural.experiment configs/neural/speciation_real.yaml
	uv run python -m neural.experiment configs/neural/speciation_real_cliff.yaml
	uv run python -m neural.experiment configs/neural/speciation_real_emergent.yaml
	MPLBACKEND=Agg uv run python figures/mnist_montage.py   # the asset paper Fig. 2B embeds

env-llm:           ## add the LLM stack for the Layer-2 prototype (GPU; transformers/peft)
	uv sync --extra dev --extra neural --extra llm

llm:               ## run the LLM prototypes: merge (fusion) + moe (union) + directed (offspring select)
	uv run python -m llm.experiment configs/llm/merge.yaml
	uv run python -m llm.experiment configs/llm/moe.yaml
	uv run python -m llm.experiment configs/llm/directed.yaml

llm-speciation:    ## LLM-tier speciation: conflict cliff (replace + de-confounded add) and duration null
	uv run python -m llm.experiment configs/llm/speciation.yaml
	uv run python -m llm.experiment configs/llm/speciation_add.yaml

llm-epistasis:     ## the controlled predictive test (feeds paper Fig. 3C-D) + its robust statistics
	uv run python -m llm.experiment configs/llm/epistasis.yaml
	uv run python -m llm.experiment configs/llm/epistasis_compat.yaml
	uv run python figures/stats_llm_epistasis.py

llm-society:       ## the composed society at LLM scale (C3): pilot; the campaign runs on HPC
	uv run python -m llm.experiment configs/llm/society.yaml

llm-society-calib: ## v2 society calibration gates (prereg §4): stage A (families), then B (C2/C3/C5)
	uv run python -m llm.experiment configs/llm/society_v2_calib_a.yaml
	@echo "Review the C1 table, fix the 12 families in society_v2_calib_b.yaml, then: make llm-society-calib-b"

llm-society-calib-b: ## v2 calibration stage B over the chosen 12 families: transmission, cross, consensus
	uv run python -m llm.experiment configs/llm/society_v2_calib_b.yaml
	mkdir -p configs/llm/_gen
	uv run python - <<'EOF'
	import yaml; c = yaml.safe_load(open("configs/llm/society_v2_calib_b.yaml"))
	for st in ("cross", "consensus"):
	    c["stage"] = st; c["output"] = {"dir": f"results/llm_society_v2_calib_b_{st}"}
	    yaml.safe_dump(c, open(f"configs/llm/_gen/calib_{st}.yaml", "w"), sort_keys=False)
	EOF
	uv run python -m llm.experiment configs/llm/_gen/calib_cross.yaml
	uv run python -m llm.experiment configs/llm/_gen/calib_consensus.yaml

llm-society-v2-smoke: ## v2 society loop smoke (4 families, 4 agents, 2 generations, all arms)
	uv run python -m llm.experiment configs/llm/society_v2_smoke.yaml
	uv run python figures/plot_llm_society.py results/llm_society_v2_smoke

llm-seeds:         ## multi-seed firm-up (heavy): merge x5, moe-hard x3, directed-hard x3
	uv run python -m llm.experiment configs/llm/merge_seeds.yaml
	uv run python -m llm.experiment configs/llm/moe_hard_seeds.yaml
	uv run python -m llm.experiment configs/llm/directed_hard_seeds.yaml

layer2: neural     ## alias: Layer 1.5 is the current Layer-2 deliverable (LLM rung deferred)

figures:           ## regenerate per-experiment figures from committed results (pure; no re-simulation)
	for e in E1 E2 E3 E4 E5 E6; do MPLBACKEND=Agg uv run python figures/plot_$$e.py; done
	for p in figures/plot_*.py; do case "$$p" in */plot_E[1-6].py|*/_*) ;; \
		*) [ -e "$$p" ] && MPLBACKEND=Agg uv run python "$$p" ;; esac; done

paper-figures:     ## regenerate the manuscript figures (Fig. 1-7) and rebuild the PDF bodies
	MPLBACKEND=Agg uv run python paper/pnas/make_figs.py
	uv run python paper/pnas/build.py
	uv run python paper/pnas/build.py si

paper:  paper-figures  ## figures + compile both PDFs (needs tectonic)
	cd paper/pnas && tectonic main.tex && tectonic si.tex
	uv run python paper/pnas/build_lay_legends.py && cd paper/pnas && tectonic figure_legends_for_students.tex

env-notebooks:     ## add Jupyter for the walkthrough notebooks
	uv sync --extra dev --extra notebooks

notebooks:         ## execute every notebook end-to-end (a reproduction check in itself)
	for nb in notebooks/*.ipynb; do uv run jupyter nbconvert --to notebook --execute \
		--inplace --ExecutePreprocessor.timeout=1800 "$$nb"; done

clean:             ## remove caches and generated results (keeps committed manifests)
	rm -rf .pytest_cache **/__pycache__
	find results -type f ! -name '.gitkeep' -delete 2>/dev/null || true