1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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 <main>/.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/<era>/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 <dir> [--world <build>]` validates.
## Git
- Work in a git worktree on a branch (`.worktrees/<topic>`), not in the main tree; ff-merge when green.
|
