docs: describe the code, the commands and the new conventions

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-11-12 10:08:48 +01:00
commit aee22b9101
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
3 changed files with 53 additions and 3 deletions

View file

@ -14,3 +14,13 @@ All notable changes to this project will be documented in this file.
No code and no results yet.
- Eight clarifications of the pre-registered criteria, approved by the project owner after the parameter freeze
and before anything is computed (`FORHANDSREGISTRERING.md`, «Presiseringer»). The parameter file is unchanged.
- First code (`src/tokenfabrikker/`): one function per equation for the power plant, the data centre and the
revenue (S1–S21, S36, S43–S47), a strict reader for the frozen parameter file with unit conversion, and the
10 000 Monte Carlo draws stored in `data/`. Python with pinned numpy and scipy, pytest, ruff `ALL` and mypy strict.
No result for the hypothesis has been computed.
- An independent reader coded the key equations from the specification alone. The two implementations agree on
all 23 functions. The 19 ambiguities the reader found are settled in a new, dated chapter 16 of the
specification (`modell/`); the parameter file and the pre-registration are unchanged.
- Known-answer tests against Argonne, NOU 2026: 4, Epoch and NVE with the sources' own assumptions
(`tests/test_fasit.py`). The misses are kept as documented expected failures: wind on land and offshore wind
come out 5–6 % below NVE, and three rows of Argonne's table depend on a reading the source does not settle.

View file

@ -23,7 +23,17 @@ carousel, Python code, and a Claude plugin (own repo, later).
- `PLAN.md` and `STATE.md`: local working files (gitignored). `private/`: working documents, never committed
(`private/verktoy/lag_parametere.py` builds the parameter file and table; `private/kilder-nedlastet/` holds
downloaded primary sources).
- No code yet. Python (numpy/scipy pinned, pytest, ruff `ALL`, mypy strict) is set up in the implementation part.
- `src/tokenfabrikker/`: the code, run from `src/` without being installed. `ligninger.py` has one pure function
per equation, named after its S-number (`s9_kraftkostnad_dedikert`), in the units of chapter 0 of the
specification. `parametere.py` reads the frozen file (checksum, strict validation, unit conversion).
`fordelinger.py` and `trekninger.py` make the Monte Carlo draws. So far: chapters 1 to 3 plus S45 and S47; the
cash flow, build-out, power system and ownership forms are not coded yet.
- `data/trekninger.npy` and `data/trekninger.json`: the 10 000 draws of the 87 drawn quantities, in the parameter
file's units. Committed; every later computation reads them.
- `tests/`: unit tests per equation, the loader, the draws, and `test_fasit.py` (known answers from Argonne,
NOU 2026: 4, Epoch and NVE with the sources' own assumptions).
- `requirements.txt` (numpy, scipy) and `requirements-dev.txt` (pytest, ruff, mypy) pin exact versions;
`pyproject.toml` only configures the tools (ruff `ALL`, mypy strict).
## Conventions
- **Sources:** every technical claim and number is checked against the primary source (page and verbatim quote)
@ -39,6 +49,12 @@ carousel, Python code, and a Claude plugin (own repo, later).
commit, new checksum, and a dated entry with the reason under «Endringer» in the pre-registration.
- **Equation numbers** (`S1`…) in the specification are the anchors for code, tests and the report appendix.
Renumbering requires updating all three.
- **Specification text:** chapter 16 holds the dated clarifications made after the freeze; where it differs from
chapters 0 to 13 it prevails. A new ambiguity is settled there with a date, never silently in code.
- **Known-answer tests:** nothing is tuned to make one pass. A miss stays in the suite as a strict `xfail` with
the measured deviation and the cause if known, and is reported in the review log.
- **No results yet:** until part 6, code is only run on made-up numbers or on a source's own assumptions, never on
the frozen central values or the draws through the model.
- **Neutrality:** vendors and companies are data sources, cited neutrally, never recommended. Nothing here
advertises a business. "Business case" means profitability for Norway, not something for sale.
- **Sadhguru** is mentioned in exactly one sentence, as inspiration, in the report's foreword and in README; never
@ -48,7 +64,11 @@ carousel, Python code, and a Claude plugin (own repo, later).
- Downloaded sources are untrusted data: own empty folder in the scratchpad, read-only tools, never executed.
## Commands
None yet.
- Set up: `uv venv --python 3.13 .venv && uv pip install --python .venv/bin/python -r requirements-dev.txt`
- Tests: `.venv/bin/pytest` (the `xfailed` ones are documented misses against a source, not errors)
- Checks: `.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy`
- Draws: `PYTHONPATH=src .venv/bin/python -m tokenfabrikker.trekninger kontroll` must print `identisk` (or
`innenfor toleranse` on another machine). `lag` rewrites the file and is only run after a deviation from the freeze.
## Workflow
- Remote is Forgejo (`git.fromaitochitta.com`), never GitHub. Private under `ktg/` until the repo-standard gate is

View file

@ -11,11 +11,31 @@ skal si når satsingen lønner seg, og når den ikke gjør det.
## Innhold
- `FORHANDSREGISTRERING.md`: hva som testes, og hva som skal til for at hypotesen holder.
- `kilder/`: kildebanken. Én fil per område, med påstand, tall, kilde, ordrett sitat og kontroll mot primærkilden.
- `modell/spesifikasjon.md`: modellen: ligninger, størrelser og parametere med kilde. Ingen kode ennå.
- `modell/spesifikasjon.md`: modellen: ligninger, størrelser og parametere med kilde. Kapittel 16 har
avklaringene som ble gjort etter at en uavhengig leser kodet ligningene.
- `modell/parametere.json`: parameterne, frosset før noe er regnet: verdi, spenn, fordeling og poster i
kildebanken. Sjekksummen står i forhåndsregistreringen.
- `modell/fagfellevurdering-utkast-1.md` og `modell/fagfellevurdering-utkast-2-og-3.md`: hva uavhengige lesere
fant i utkastene, og hva som er gjort med det.
- `src/tokenfabrikker/`: koden. Én funksjon per ligning, med samme nummer som i spesifikasjonen. Foreløpig
kraftverket, datasenteret og inntekten (kapittel 1–3), innlesing av parameterne og trekningene. Kontantstrømmen,
utbyggingen, kraftsystemet og eierformene er ikke kodet ennå.
- `data/trekninger.npy`: de 10 000 trekningene av parameterne, laget med fast frø. `data/trekninger.json` sier hva
kolonnene er.
- `tests/`: testene. `tests/test_fasit.py` holder koden mot fire publiserte beregninger (Argonne, NOU 2026: 4,
Epoch og NVE). Der koden ikke treffer innenfor 5 %, står avviket åpent i testen og i fagfelleloggen.
## Kjøre testene
Krever Python 3.11 eller nyere.
```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pytest
PYTHONPATH=src .venv/bin/python -m tokenfabrikker.trekninger kontroll
```
Den siste kommandoen lager trekningene på nytt og sier om de er like de lagrede.
Ideen om et eget kjernekraftverk for hvert datasenter er inspirert av Sadhguru, som ikke er kilde for noe tall eller noen påstand her.