121 lines
11 KiB
Markdown
121 lines
11 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,
|
||
22–26 third round for the addition to the direction: fast start, stepwise build-up, on-device compute,
|
||
avoided emissions and cooling water).
|
||
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–S54; of chapter 17,
|
||
the addition to the direction, solution T is coded through the build-out, the power system, the cash
|
||
flow, the levelised cost, ownership and scale, and S48–S54 are coded; T through M5 and the verdicts is not).
|
||
`modell/parametere.json`: the frozen
|
||
parameters (value, range, distribution, source entries); its checksum is recorded in the pre-registration
|
||
(version 1.1 after the one deviation of 2026-11-12, which added the quantities of chapter 17.8).
|
||
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; chapter 17.1: `utbyggingsplan_trinnvis` for
|
||
solution T in modules, with the grid balance of the first stage, S49 and the two chip stocks of T-K; S50:
|
||
`tidslinje`), `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. `nivaaisert.py` (the power cost per facility, year and vintage on levelised form; S15, S19, S27, S42),
|
||
`eierskap.py` (S28 to S30: business cash flow, tax, ownership forms, the criteria over the draws), `skala.py`
|
||
(S31, M6), `miljo.py` (S32, the rules of M5) and `dommer.py` (S37, the verdict per target, the step of the
|
||
ladder, the overall verdicts) cover chapters 7 to 11. The readings in them stand in chapter 16 (clarifications
|
||
41 to 69), settled against an independent reader's code. Clarifications 62 to 66 correct the comparison of
|
||
ownership forms (residual value, levies, private owners, the rate the state's cash flow is valued with, the
|
||
cost of capital before tax), approved by the operator 2026-11-12; 67 lists what remains. Clarification 68
|
||
holds the sources' figures for M5 (i), mirrored in `miljo.KILDEVERDIER_M5`. Clarifications 70 to 75 hold the
|
||
readings of chapter 17 made when its build-out was coded, and 76 to 81 those made when T was taken through
|
||
the power system and the cash flow, and 82 to 87 those made when T and the loss of demand were taken through
|
||
the levelised cost, ownership and scale, all settled against an independent reader's code.
|
||
Solution T (`Losning.T_F`, `Losning.T_K`) goes through `lag_plan` (a `Trinnvisplan`) and `regn_program`
|
||
with a module in the place of a facility (`Programresultat.P_enhet`): renewable modules have their own
|
||
portfolio as in C, the nuclear modules of T-K share the programme's units as in B
|
||
(`paa_felles_kjernekraft`), and S41 counts to the first unit. The factor of S51 enters the revenue and the
|
||
disconnection arm of S47 through `regn_program(..., bortfall=...)` (`Programresultat.mu_d`; exactly one
|
||
without a loss). `miljo.py` puts S53 (`unngaatt_utslipp`, `utslipp_med_fradrag`) and S54 (`kjolevann`)
|
||
together over a programme for all solutions. `nivaaisert.py`, `eierskap.py` and `skala.py` take T per
|
||
module (`res.P_enhet`, `res.reaktoreffekt(k)`, `res.antall_paa_felles(t, ...)`) and carry the factor of
|
||
S51 per vintage in S19, S27, S31 and S42; the rules of M5 in `miljo.py` and the verdicts in `dommer.py`
|
||
do not know five solutions yet (part 5T-4d).
|
||
Present values are exactly rounded sums (`math.fsum`), never numpy dot products: those are not repeatable
|
||
to the last digit. Sums over technologies go in the plants' own order, never over a set of names: its order
|
||
differs from run to run. The run over the draws, the sensitivities and the tools of chapter 12 are not coded yet.
|
||
- `data/trekninger.npy` and `data/trekninger.json`: the 10 000 draws of the 91 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`, and so are the levelised cost, ownership, scale and
|
||
environment. The verdicts are tested on invented outcomes per draw. `test_trinnvis.py` holds chapter 17:
|
||
hand-computed build-outs for T-F and T-K, and S48 to S54. `test_trinnvis_kontantstrom.py` holds T through
|
||
the power system and the cash flow, the loss of demand, and S53 and S54 over a programme.
|
||
`test_trinnvis_nivaaisert.py` holds T and the loss of demand through the levelised cost, ownership and scale.
|
||
- `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. Chapter 17
|
||
holds the addition to the direction (solution T in the versions T-F and T-K, on-device compute, avoided
|
||
emissions, cooling water; S48–S54). Where it is silent, T follows the rules for C and B. Its new quantities
|
||
(17.8) were frozen in the deviation of 2026-11-12 and stand last in the parameter file.
|
||
- **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.
|