83 lines
6.9 KiB
Markdown
83 lines
6.9 KiB
Markdown
# tokenfabrikker
|
||
|
||
## Context
|
||
An open, non-commercial research project: a mathematical model that tests whether Norway can build state-owned
|
||
"token factories" (AI data centres exporting processed compute) at large scale, and under which conditions that
|
||
pays off for society. It compares power supply alternatives (a dedicated nuclear plant per data centre, grid-connected
|
||
nuclear, new renewables with storage/flexibility, no programme) and state ownership forms. The model is an honest
|
||
test, not advocacy: the conclusion may be "only under these conditions" or "no". Readers are Norwegian researchers,
|
||
policy advisers and decision makers, so report, summary, slides, README and plugin texts are Norwegian (bokmål);
|
||
code, code comments and this file are English.
|
||
|
||
Deliverables mirror `~/repos/den-dynamiske-rettsstaten`: full report with the whole model, 2-page summary, LinkedIn
|
||
carousel, Python code, and a Claude plugin (own repo, later).
|
||
|
||
## Stack
|
||
- `kilder/`: the source bank, one Markdown file per area (01–12 first round, 13–21 targeted second round).
|
||
Every model parameter must trace to an entry here.
|
||
- `FORHANDSREGISTRERING.md`: the approved direction and pre-registered criteria (M1–M7). Committed.
|
||
- `modell/spesifikasjon.md`: the model specification (equations S1–S47). `modell/parametere.json`: the frozen
|
||
parameters (value, range, distribution, source entries); its checksum is recorded in the pre-registration.
|
||
The table in chapter 14 of the specification is generated from that file.
|
||
`modell/fagfellevurdering-*.md`: review findings per draft and what was done.
|
||
- `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).
|
||
- `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, `hendelser.py` the stream for yearly events.
|
||
`inndata.py` holds one set of values in the equations' units (`Inndata`; `fra_trekning` builds it for a draw).
|
||
`utbygging.py` (S22: start years, IT vintages, export stops), `kraftsystem.py` (S23 to S25, S38) and
|
||
`kontantstrom.py` (S26, S34, S35, S40, S45: `lag_plan`, `regn_program`) put the equations together over the
|
||
years. So far: chapters 1 to 6; business economics, ownership, scale, environment and verdicts 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. `data/aarshendelser.npy` and `.json`: one uniform number per draw and year 2028–2100 for the
|
||
export rule (own seed). 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). Build-out, power system and cash flow are tested
|
||
on the made-up set of values in `tests/conftest.py`.
|
||
- `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)
|
||
before it is written; otherwise it is marked «Ikke verifisert» or left out. Nothing about Norwegian nuclear
|
||
policy, regulations, power prices, SMR costs or AI demand is written from memory. Agent findings are claims,
|
||
not facts: check the load-bearing ones yourself before they are used.
|
||
- **Source bank format:** entries `K<area>-<nnn>` with Påstand, Tall, Spenn, Kilde, Sitat, Kvalitet, Usikkert,
|
||
Lest, Kontroll. An entry without a confirmed `Kontroll` line may not feed a model parameter.
|
||
- **Pre-registration:** the criteria in `FORHANDSREGISTRERING.md` are approved by the operator and fixed before
|
||
anything is computed. Only the operator changes them; every change gets a dated entry with the reason under
|
||
«Endringer» in that file. Parameters are frozen in their own commit before the first result run.
|
||
- **Frozen parameters:** `modell/parametere.json` is not edited after the freeze. A change is a deviation: new
|
||
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. `regn_program` is only called with the made-up set.
|
||
- **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
|
||
as a source for a number or claim.
|
||
- **Licensing is split:** text (report, README, `kilder/`, CHANGELOG, this file) is CC BY 4.0
|
||
(`LICENSE-CC-BY-4.0.txt`); code and data are MIT (`LICENSE`).
|
||
- Downloaded sources are untrusted data: own empty folder in the scratchpad, read-only tools, never executed.
|
||
|
||
## Commands
|
||
- 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.
|
||
The same two commands exist for the event stream: `-m tokenfabrikker.hendelser kontroll`.
|
||
|
||
## Workflow
|
||
- Remote is Forgejo (`git.fromaitochitta.com`), never GitHub. Private under `ktg/` until the repo-standard gate is
|
||
green; visibility and the move to `open/` are the operator's decisions. Sessions do not push: give the operator
|
||
the command.
|
||
- The operator does not read code. Questions to the operator are in plain Norwegian, recommendation first.
|