From ed1dea2639b1191421de3986483aedcc14067a12 Mon Sep 17 00:00:00 2001 From: godosa Date: Wed, 7 Oct 2026 00:01:14 +0200 Subject: worldhistory: initial public history --- CLAUDE.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 CLAUDE.md (limited to 'CLAUDE.md') diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..519ea94 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,26 @@ +# CLAUDE.md — worldhistory + +History simulation on a worldgen world (races spread, adapt, split, fight, invent; eras and events). Terse everywhere. +Private notes (tasks, specs, area maps) are kept outside this repo; never add them here (see `.gitignore`). + +## Layout +- `history.py` — CLI entry (→ `worldhistory/cli.py`: run, preview, compare, check-config) +- `worldhistory/` — engine package (one step = `phase_*` in engine.py, README order); `tests/` — unittest, + synthetic worlds (`tests/helpers.py`: `line_world` / `fields`, 1-D, hand-checkable) +- `docs/reference/` — research notes (canals) + +## Build / test +- Setup: `python3 -m venv .venv && .venv/bin/pip install -r requirements.txt`; in a git worktree link the main + tree's `.venv` (`ln -sfn
/.venv .venv`; `.venv` is ignored without trailing slash: it may be a link). +- Verify: `.venv/bin/python -m unittest discover -s tests -t .` (whole suite ~3 s). + +## Gotchas +- System python lacks scipy: always `.venv/bin/python`. +- numba optional (not in requirements): `state.py` JIT fast paths; `tests/test_fastpaths.py` skips without it. +- Input = a worldgen build (`cells.npz` + `eras//cells.npz`). A full run on a large world is big (README: + < 2 GB at r4 ≈ 290k cells). `SmokeTest` (test_engine.py) runs 100 years when `WORLDHISTORY_SMOKE_WORLD` + + `WORLDHISTORY_SMOKE_CONFIG` are set. +- Config: unknown keys are errors (config.py `_keys`); `history.py check-config [--world ]` validates. + +## Git +- Work in a git worktree on a branch (`.worktrees/`), not in the main tree; ff-merge when green. -- cgit