dynamisk-rettsstat/docs/scenarioformat.md

# Scenarioformatet

En scenariofil er en JSON-fil som sier hvilken av modellens simuleringer som skal kjøres, med hvilke forutsetninger.
Scenariokjøreren (`modell/scenario.py`) kaller kjernen i `modell/kjerne/sim.py` uendret med verdiene i fila, og
skriver et sammendrag, tidsseriene og alle parametere slik de ble brukt.

```
python3 modell/kjor.py scenario <fil.json> [--ut <mappe>]
```

Alt som ikke står i fila, er notatets verdier (tabell 3 i notatet). De er stiliserte og ikke kalibrert på norske
data, og sammendraget sier det. Tallene viser modellens dynamikk, ikke prognoser. Feltnavnene er norske; navnene på
modellens parametere er kjernens egne, slik at de kan slås opp i `sim.py` og i [modellkart.md](modellkart.md).

## Et første eksempel

```json
{
  "navn": "kapasitet_tidlig",
  "beskrivelse": "Hva om domstolens kapasitet økes allerede fra måned 12, ikke 24?",
  "modell": "simulate_chain",
  "tiltak": {"kapasitet": {"faktor": 1.34, "fra": 12, "over": 24}},
  "sveip": {"parameter": "styring.forsinkelse", "verdier": [3, 6, 11]}
}
```

Dette kjører den koblede modellen med domstolskø (avsnitt 8.2) tre ganger, med forsinkelse 3, 6 og 11 måneder i
politiets styring, og med kapasiteten i domstolen økt med 34 % lineært fra måned 12 til 36. Resten er notatets
regime A og scenario 2.

## Feltene

| Felt | Type | Standard | Gjelder | Hva |
|---|---|---|---|---|
| `navn` | tekst | filnavnet uten `.json` | alle | navn på kjøringen; gir navnet på resultatmappa og filene |
| `beskrivelse` | tekst | tom | alle | hvilket spørsmål scenarioet svarer på; står øverst i sammendraget |
| `merknad` | tekst | ingen | alle | fritekst for deg selv; brukes ikke |
| `modell` | tekst | **må oppgis** | | hvilken simulator, se under |
| `startlikevekt` | `"krev"`, `"kalibrer"` eller `"ubalanse"` | `"krev"` | alle | hva som skjer når parametrene gjør at startpunktet ikke er en likevekt, se under |
| `styring` | objekt | regime A | alle | regulator, forsinkelse og reaktivitet for politiets innsats |
| `parametere` | objekt | notatets verdier | alle | overstyring av kjernens parametere, gruppert som i kjernen |
| `regel` | tekst | **må oppgis** for `simulate_endo` | `simulate_endo` | beslutningsregel for andel utenom og kapasitet |
| `sjokk` | objekt | notatets sjokk | alle unntatt utvidelser | størrelse og tidspunkt for makrosjokket |
| `tiltak` | objekt | ingen tiltak | `simulate_chain`, `simulate_chain2`, `simulate_endo` med regel `sched`, utvidelser med kjede | andel utenom, kapasitet, trommel–buffer–tau |
| `slutt` | tall | 120 | alle | horisont i måneder (minst 1, høyst 2 400) |
| `sveip` | objekt eller liste | ingen | alle | én parameter over en liste verdier, eller to (rutenett) |
| `utdata` | objekt | CSV med alle tidsserier, én rad per måned | alle | format, kolonner og hvor tett radene står |
| `utvidelse` | objekt | utvidelsens `PARAMETERE` | `utvidelse:<navn>` | utvidelsens egne parametere |

Ukjente felt er en feil, med en melding som nevner feltet og lister de gyldige (og foreslår det nærmeste ved en
skrivefeil). Det samme gjelder ukjente parameternavn. En skrivefeil gir aldri en stille standardverdi.

Tall skrives med punktum som desimaltegn, som JSON krever. Uendelig skrives som teksten `"inf"` (i anførselstegn),
og bare der det er tillatt (står i tabellene under). `Infinity` og `NaN` er ikke gyldig JSON og avvises. Står et felt
to ganger i samme objekt, er det en feil.

### `modell`

| Verdi | Hva | Kjernens funksjon | Avsnitt |
|---|---|---|---|
| `"simulate"` | grunnmodellen uten straffesakskjede: kriminalitet K, trygghet U, tillit Λ, innsats T | `simulate(controller, tau, p, kp)` | 8.1 (regime A–E) |
| `"simulate_chain"` | domstolen som ledd med kø, koblet til grunnmodellen | `simulate_chain(controller, tau, ch, p, kp, mpc_knows_chain)` | 7.3 og 8.2 |
| `"simulate_chain2"` | domstol med to sakstyper (A alvorlige, B øvrige), forrang eller felles kø, c spor | `simulate_chain2(tau, ch2, p, kp)` | 8.3 |
| `"simulate_soc"` | rekruttering og vippepunkt, med et forbigående sjokk | `simulate_soc(controller, tau, p, s, kp, shock, t_on, t_off)` | 8.4 |
| `"simulate_endo"` | endogene tiltak: andel utenom og kapasitet bestemt av beslutningsregler | `simulate_endo(policy, tau, p, ch, e, kp, tend, xi_sched, Z_sched)` | 8.5 |
| `"utvidelse:<navn>"` | en mekanisme utenfor kjernen, i `modell/utvidelser/<navn>.py` | `simuler(scenario)` i utvidelsen | se [utvidelser.md](utvidelser.md) |

### `styring`

| Felt | Type | Standard | Gyldig | Hva |
|---|---|---|---|---|
| `regulator` | tekst | `"P"` | se under | hvordan politiets innsats T settes |
| `forsinkelse` | tall (mnd) | 3 | 0 til `slutt` | τ: fra kriminalitetsbildet endrer seg til innsatsen er endret |
| `reaktivitet` | tall | 3 | 0 til 100 | k_p: prosent mer innsats per prosent avvik fra målet (P-regelen) |
| `mpc_kjenner_kjeden` | true/false | true | bare `simulate_chain` med `"MPC"` | om MPC-ens interne modell har med køen |

Regulatorer: `"P"` (proporsjonal regel) for alle modeller; `"MPC"` (modellprediktiv styring, avsnitt 8.1, regime D)
for `simulate` og `simulate_chain`; `"fast"` (innsatsen står fast på T₀) for `simulate_soc`. Standardverdiene er
regime A i notatet. MPC er tregt: én kjøring tar om lag 7 sekunder.

### `parametere`

Overstyring av kjernens parametere, gruppert etter dicten de står i i `sim.py`. Bare dictene modellen bruker, er
tillatt:

| Gruppe | Brukes av | Nøkler |
|---|---|---|
| `P` | alle | `gamma`, `eta`, `delta`, `Omega0`, `shock`, `t_shock`, `T0`, `Tmax`, `Kstar`, `kU`, `U0`, `psiU`, `kL`, `mu1`, `mu2`, `Tprop`, `Lam0`, `ksat` |
| `CH0` | `simulate_chain`, `simulate_endo`, `utvidelse:paadrag_tidsserie` | `Z`, `m`, `theta`, `chi`, `mu4`, `tauh`, `varsigma`, `xi` |
| `CH2` | `simulate_chain2` | `Z`, `m`, `c`, `prio`, `piA`, `thetaA`, `thetaB`, `chi`, `mu4`, `tauh`, `varsigma`, `xiA`, `xiB` |
| `ENDO` | `simulate_endo` | `lagD`, `xi_min`, `tau_thr`, `k_xi`, `tau_xi`, `ups_star`, `ups_hi`, `ups_lo`, `kZ`, `L1`, `L2`, `tau_down`, `T_clear`, `H_pred`, `period`, `qloop`, `mu3`, `Lam_star`, `k_q`, `q_max`, `lag_survey` |
| `SOC` | `simulate_soc` | `eps`, `Kh`, `pexp` |

Hva hver parameter betyr, hvilken ligning den står i og notatets verdi: [modellkart.md](modellkart.md), del (b).
Listen over gyldige nøkler leses fra kjernen hver gang, så en parameter du legger til i en arbeidskopi, kan
overstyres uten å endre kjøreren.

Typen følger kjernens standardverdi: tall, heltall (`CH2.c`, `SOC.pexp`) eller true/false (`CH2.prio`,
`ENDO.qloop`). Kjøreren sjekker også at verdien gir mening:

- uendelig (`"inf"`) er tillatt for `P.ksat` (ingen politimetning), `CH0.Z` (ingen flaskehals, = regime A) og
  `ENDO.T_clear` (restansen avvikles ikke);
- andeler ligger mellom 0 og 1 (`U0`, `theta`, `xi`, `xi_min`, …), og `Lam0`, `piA` og `Lam_star` strengt mellom;
- tider, forsterkninger og rater er ikke negative, og tidskonstanter og kapasiteter er større enn 0;
- `ENDO.L1` < `ENDO.L2` og `ENDO.ups_lo` < `ENDO.ups_hi`;
- `ENDO.period` (budsjettsyklusen) er et helt antall måneder, minst 1: kjernen gjør budsjettvedtak bare i hele
  måneder (`sim.py:614`), så en annen verdi ville gitt en regel som aldri gjør vedtak.

`CH2.m` kan settes til `"kalibrer"`: da regnes m ut med kjernens `calibrate_m`, slik at saksbehandlingstiden i
utgangslikevekten blir 3 måneder (det notatet gjør for c = 10 spor). Med flere spor (`c` > 1) og uten kalibrering
er utgangslikevekten en annen enn notatets.

Funksjonene i kjedene (`Zfun`, `xifun`, `xiBfun`) og `dbr` settes ikke her, men med `tiltak`.

Endrer du en av parametrene som bestemmer likevekten før sjokket, sjekker kjøreren om startpunktet fortsatt er en
likevekt; se `startlikevekt` under.

### `startlikevekt`

Notatets parametere er kalibrert slik at kriminaliteten K = 1 og innsatsen T = T₀ er en likevekt i grunnmodellen, og
slik at domstolen er 95 % utnyttet med 3 måneders saksbehandlingstid. I modellene med kø i domstolen er
startpunktet nesten, men ikke helt, en likevekt (se under). Endrer du for eksempel `P.gamma` («hva om politiet blir
20 % mer effektivt»), stemmer kalibreringen ikke lenger: modellen driver bort fra startpunktet før sjokket kommer, og
det ser ut som en virkning av endringen. Derfor sjekker kjøreren startpunktet for hver kjøring, med kjernens egne
funksjoner:

| Hva sjekkes | Betingelse | Kan kalibreres |
|---|---|---|
| pådraget mot fjerning og frafall | `Omega0` = `removal(1, Lam0, T0, P)` + `delta` (tillatt rest 10⁻¹²); berøres av `gamma`, `eta`, `delta`, `Omega0`, `T0`, `Lam0` og `ksat` | ja, `P.Omega0` regnes ut på nytt (ikke hvis fila setter `Omega0` selv) |
| målet for styringen | `Kstar` = 1 (når regelen virker: P med reaktivitet over 0, eller MPC) | nei |
| taket på innsatsen | `T0` ≤ `Tmax` | nei |
| forholdsmessighet | `T0` ≤ `Tprop` · 1 (ellers faller tilliten fra start) | nei |
| domstolen mot strømmen (`simulate_chain`, `simulate_chain2`, `simulate_endo`, utvidelser med kjede) | `CH0.Z`/`CH0.m` (eller `CH2.Z`/`CH2.m`) er notatets, regnet for strømmen J0 = `gamma`·`Lam0`·`T0` = 0,1. Endres `gamma`, `Lam0` eller `T0` uten at fila setter både `Z` og `m`, passer de ikke lenger | ja: `Z` = J0/0,95 og `m` = 3 − J0/(Z·(1/3 + `varsigma`)), som `sim.py:151-155` (for `CH2` med flere spor: `calibrate_m`); bare det fila ikke setter selv |
| domstolen er ikke overbelastet ved start | strømmen til domstolen ved start er mindre enn kapasiteten `Z` | bare når `Z` kalibreres |
| `eta` i kjedemodellene | `eta` = 1: kjernen regner strømmen til domstolen ved start uten η (`init_chain`, `simulate_chain2`) | nei |

`ksat` og rekrutteringen i `simulate_soc` (`SOC`) rekalibrerer kjernen selv (`removal` og `Omega0 − eps·H(1)`), og
sjekken bekrefter det.

**Modellene med kø i domstolen står ikke helt i ro, heller ikke med notatets verdier.** Ved start er
dK/dt = ϑ·ς·Q₀ > 0: det som faller fra køen (henleggelse, foreldelse), blir aldri fjernet fra kriminaliteten. Notatets
koblede modell uten sjokk (`eksempler/scenarioer/uten_sjokk_kjede.json`) gir K 1,007 i måned 11, 1,015 i måned 120 og
1,018 i måned 240, og saksbehandlingstiden 3,1, 4,2 og 4,6 måneder, fortsatt stigende. Det gjelder `simulate_chain`,
`simulate_chain2`, `simulate_endo` og utvidelser med kjede, og det er notatets referanse; sjekken over gjelder
kalibreringen, ikke denne driften. Derfor:

- sammendraget for disse modellene kaller 1,00 nivået ved start (notatets referansetilstand), sier at det er nesten,
  men ikke helt, en likevekt, og viser hvor langt K, T, tilliten og saksbehandlingstiden har drevet fra start til
  måneden sjokket begynner. Uten sjokk, eller med sjokk fra måned 0, sier det i én setning at modellen kryper sakte
  oppover;
- når små virkninger betyr noe, sammenlign med en kjøring uten sjokk (`"sjokk": {"faktor": 1}`, samme parametere og
  horisont) og trekk driften fra.

| Verdi | Hva skjer når startpunktet ikke er en likevekt |
|---|---|
| `"krev"` (standard) | kjøringen stopper (exit 2) med en melding som sier hva som er galt og de to veiene ut under |
| `"kalibrer"` | kjøreren regner om det som kan kalibreres (tabellen over) som i notatets kalibrering, slik at startpunktet blir notatets referansetilstand for de nye verdiene (med samme lille drift i modellene med kø), og sammendraget sier hvilke verdier som ble endret, fra hva og til hva. Er noe som ikke kan kalibreres galt, stopper den |
| `"ubalanse"` | kjøringen går fra ubalansen med vilje. Forklaringen under tabellen («1,00 er nivået i referanselikevekten …») byttes ut med hva som er galt og hvor langt K, T, tilliten og saksbehandlingstiden har drevet fram til måneden sjokket begynner (måned 12 når det ikke er noe sjokk, høyst `slutt`) |

`resultat.json` har for hver kjøring `startlikevekt` med valget, de kalibrerte verdiene (`for` og `etter`) og grunnene
til ubalansen.

**`simulate_endo` har én grense til.** Regelen i kjernen bruker 0,1 som observert strøm de første månedene
(`sim.py:588`). Er strømmen ved start (`removal(1, Lam0, T0, P)`) en annen, stopper kjøringen uansett valg. Målt: med
`gamma` 0,11 og 0,10 (og `Omega0`, `CH0.Z` og `CH0.m` kalibrert) gir den koordinerte regelen en annen bane enn med
riktig observasjon (største avvik 0,33 og 0,44 i tidsseriene, andre budsjettvedtak); de desentraliserte reglene og
`sched` endret seg ikke. Å endre `gamma`, `Lam0`, `T0`, `eta` eller `ksat` i `simulate_endo` er derfor en endring i
kjernen (arbeidskopi og ferdigheten `forbedre`).

### `regel` (bare `simulate_endo`)

| Verdi | Hva (avsnitt 8.5) |
|---|---|
| `"sched"` | faste tidsplaner; med `tiltak` er det scenario 5 som vedtak (`endo_e5`), uten er det scenario 2 |
| `"desentral"` | påtalemyndigheten justerer andelen utenom etter observert saksbehandlingstid; budsjettet bestiller etter observert innstrømning |
| `"desentral_prog"` | som `desentral`, men budsjettet dimensjonerer etter prognosen |
| `"koord"` | koordinert regel: andel utenom og kapasitet ut fra en felles kapasitetsbalanse (metoden i avsnitt 7.7) |

Kvalitetssløyfen slås på med `"parametere": {"ENDO": {"qloop": true}}`. Avviklingstiden for restansen i den
koordinerte regelen er `ENDO.T_clear`.

### `sjokk`

| Felt | Type | Standard | Hva |
|---|---|---|---|
| `faktor` | tall > 0 | 1,30 (`simulate_soc`: 1,6) | det strukturelle pådraget Ω ganges med dette |
| `fra` | tall ≥ 0 (mnd) | 12 | når sjokket kommer |
| `til` | tall (mnd) | 36 | bare `simulate_soc`: når sjokket er over |

For alle modeller unntatt `simulate_soc` er sjokket varig, og `faktor` og `fra` er det samme som `P.shock` og
`P.t_shock`; oppgis begge steder, er det en feil. I `simulate_soc` er sjokket forbigående og settes bare her. Vil du
ha et forbigående sjokk, en bølge eller flere trinn i de andre modellene, bruk utvidelsen `paadrag_tidsserie`
([utvidelser.md](utvidelser.md)); utvidelser tar ikke `sjokk`.

### `tiltak`

| Felt | Type | Standard | Hva | Notatets verdi |
|---|---|---|---|---|
| `andel_utenom.andel` | tall i [0, 1) | må oppgis | andelen av sakene som ledes til forenklede reaksjoner | 0,2 |
| `andel_utenom.fra` | tall ≥ 0 (mnd) | 24 | fra hvilken måned | 24 |
| `kapasitet.faktor` | tall > 0 | må oppgis | domstolens kapasitet ganges med dette til slutt | 1,34 |
| `kapasitet.fra` | tall ≥ 0 (mnd) | 24 | økningen begynner | 24 |
| `kapasitet.over` | tall > 0 (mnd) | 24 | økningen fordeles lineært over så mange måneder | 24 |
| `trommel_buffer_tau` | tall > 0 | ingen | politiets innsats begrenses slik at strømmen til domstolen er høyst dette ganger kapasiteten | 0,95 |

Hvor tiltakene virker:

- `simulate_chain`: andelen blir `xifun` (ξ_D = 1 − andel fra måned `fra`), kapasiteten `Zfun`
  (Z_D = Z · (1 + (faktor − 1) · min(max((t − fra)/over, 0), 1)), samme regneuttrykk som `Z_utv` i `sim.py`), og
  trommel–buffer–tau `dbr`. Scenario 3, 4 og 5 i notatet.
- `simulate_chain2`: andelen er av alle saker og tas fra klasse B, som i notatet: ξ_B = 1 − andel/(1 − `piA`).
  Andelen kan derfor være høyst 1 − `piA`.
- `simulate_endo`: bare med regel `"sched"`; tiltakene blir tidsplanene `xi_sched` og `Z_sched`. De andre reglene
  bestemmer andel og kapasitet selv. `trommel_buffer_tau` brukes ikke her.
- Kapasitet og trommel–buffer–tau gir ingen mening når `CH0.Z` er `"inf"`, og avvises.

### `slutt`

Horisont i måneder, minst 1 og høyst 2 400. Standard er 120 (`TEND` i `sim.py`); notatets kjøringer med
`simulate_endo` bruker 180. For simulatorene som leser den globale `TEND`, setter kjøreren `sim.TEND` midlertidig og
setter den tilbake etterpå; `simulate_endo` får den som argumentet `tend`. Tidssteget er alltid `DT` = 0,05 måned.
Er horisonten kortere enn forsinkelsen i styringen, stopper kjøreren med en melding om `slutt`. Kommer sjokket ved
eller etter `slutt` (eller varer det i `simulate_soc` lenger enn `slutt`), kjøres det, men sammendraget har en
merknad om det.

### `sveip`

Ett sveip kjører samme scenario én gang per verdi:

```json
"sveip": {"parameter": "parametere.ENDO.T_clear", "verdier": [12, 24, 48, "inf"]}
```

To sveip i en liste gir et rutenett (alle kombinasjoner, den første parameteren ytterst):

```json
"sveip": [
  {"parameter": "styring.reaktivitet", "verdier": [1, 2, 3]},
  {"parameter": "styring.forsinkelse", "verdier": [3, 6, 11]}
]
```

`parameter` er en sti med punktum inn i scenariofila. Stien kan begynne med `styring`, `parametere`, `regel`,
`sjokk`, `tiltak`, `slutt`, `utvidelse` eller `startlikevekt`, og må ende i én verdi, for eksempel:

| Sti | Hva |
|---|---|
| `styring.reaktivitet`, `styring.forsinkelse`, `styring.regulator` | styringen |
| `parametere.P.ksat`, `parametere.CH0.Z`, `parametere.ENDO.T_clear`, `parametere.ENDO.qloop`, … | en av kjernens parametere |
| `regel` | beslutningsregelen i `simulate_endo` |
| `sjokk.faktor`, `sjokk.fra`, `sjokk.til` | sjokket |
| `tiltak.kapasitet.faktor`, `tiltak.andel_utenom.andel`, `tiltak.trommel_buffer_tau`, … | tiltakene |
| `slutt` | horisonten |
| `utvidelse.punkter`, … | en av utvidelsens parametere |

Regler:

- Verdien i sveipet erstatter verdien i fila for den stien. Hver kombinasjon valideres som om den sto i fila, og en
  feil sier hvilken kombinasjon den gjelder.
- `null` som verdi betyr kjernens verdi (feltet tas bort), for eksempel `"verdier": [null, "inf"]` for notatets
  kapasitet og ingen flaskehals. Den vises som «standard».
- Høyst to parametere og høyst 400 kjøringer. Samme verdi to ganger (også 3 og 3.0) er en feil.
- Kjøringene heter `<siste del av stien>=<verdi>`, i et rutenett skilt med `_`, for eksempel `T_clear=24` og
  `reaktivitet=3_forsinkelse=11`. Filene heter `<navn>__<kjøring>.csv`.

### `utdata`

| Felt | Type | Standard | Hva |
|---|---|---|---|
| `format` | `"csv"` eller `"notat"` | `"csv"` | filformatet for tidsseriene |
| `kolonner` | liste med navn | alle tidsseriene modellen gir | hvilke tidsserier, i hvilken rekkefølge |
| `hvert` | heltall ≥ 1 | 20 (`csv`), 10 (`notat`) | hvert så mange tidssteg skrives (20 = én rad per måned) |
| `overskrift` | tekst | kolonnenavnene | bare `"notat"`: overskriftslinjen, ett ord per kolonne |

`"csv"`: komma mellom feltene, punktum som desimaltegn, én overskriftslinje med kolonnenavnene og tallene med ti
gjeldende sifre. Leses direkte av R, Python, regneark og pgfplots (`col sep=comma`). Fila heter `<navn>.csv`.

`"notat"`: nøyaktig notatets filformat, skrevet med kjernens egen `write_csv`: mellomrom mellom feltene, `%.5f`,
hver tiende rad, og overskriften du gir. Fila heter `<navn>.dat`. Med dette formatet gjenskaper scenariofilene i
`eksempler/scenarioer/notatet/` notatets datafiler, og notatets figurer kan lages på nytt fra dem (pgfplots i
LaTeX-kilden leser filene direkte).

## Tidsseriene per modell

| Modell | Tidsserier (kolonnenavn) |
|---|---|
| `simulate`, `simulate_soc` | `t K U L T` |
| `simulate_chain` | `t K U L T Q tauD JD RD xi`, og `Z Z_rel` når kapasiteten er endelig |
| `simulate_chain2` | `t K KA KB U L T QA QB tauA tauB RA RB Z Z_rel xi` |
| `simulate_endo` | `t K U L T Q tauD JD RD Z xi q Z_rel` |
| `utvidelse:paadrag_tidsserie` | som `simulate_chain` (med kjede) eller `simulate` (uten), og `Omega_faktor` |

`t` er tid i måneder, `K` kriminalitet (1 = før sjokket), `U` trygghet, `L` tillit Λ (0,80 før sjokket), `T`
politiets innsats (1 = før sjokket), `Q` køen i domstolen, `tauD` saksbehandlingstiden (mnd), `JD` saker inn og `RD`
saker avgjort per måned, `xi` andelen som går til domstolen (1 − andel utenom), `Z` kapasiteten og `Z_rel` kapasiteten
delt på kapasiteten ved start, `q` prosessuell kvalitet. I `simulate_chain2` er `KA`/`KB`, `QA`/`QB`, `tauA`/`tauB` og
`RA`/`RB` det samme per sakstype. Kø, strøm og kapasitet er i modellens normaliserte enheter. `Z`, `xi` og `Z_rel` i
`simulate_chain` regnes ut av kjøreren fra kjernens `chain_at`, og i `simulate_chain2` fra `Zfun` og `xiBfun` slik
`court2` bruker dem (der er `xi` andelen av alle saker som går til domstolen, `piA`·`xiA` + (1 − `piA`)·ξ_B).
`Z_rel` i `simulate_endo` er det notatets `endo_*.dat` kaller `Z`. I datafilene står køen i modellens enheter; i
sammendraget står den i måneder av innstrømningen før sjokket (se under).

## Hva kjøreren skriver

I mappa `resultater/<navn>/` under mappa du står i, eller i mappa du gir med `--ut`:

- `sammendrag.md`: hva som ble kjørt, hvilke felt fila satte selv, nøkkeltallene i en tabell (én kolonne per
  kjøring, høyst seks per tabell), for et rutenett også en tabell med ett nøkkeltall over begge parametrene (spennet
  i K de siste 60 månedene når horisonten er over 120 mnd, ellers spennet etter måned 60), og for
  `simulate_endo` budsjettvedtakene fra regelen. Med `"kalibrer"` står de kalibrerte verdiene øverst, og med
  `"ubalanse"` driften før sjokket. Under «Merknader» står forhold som ikke stopper kjøringen: at K går utenfor
  0,01–12 (området kjernens `soc_equilibria` leter i; notatets egne kjøringer ligger mellom 0,83 og 9,82), og at
  sjokket ligger utenfor horisonten. Det samme skrives til skjermen, sammen med stien til mappa.
- én CSV (eller `.dat`) per kjøring;
- `resultat.json`: scenarioets navn og fil med sha256, Python-, numpy- og scipy-versjon, sha256 for de tre filene i
  kjernen (og for utvidelsen), og for hver kjøring alle parametere slik simulatoren fikk dem (fullt utfylt, også det
  fila ikke satte), nøkkeltallene med full presisjon, budsjettvedtakene og `startlikevekt`. Uendelig står som
  `"inf"`.

Samme scenariofil gir samme bytes i alle tre filene på samme maskin og med samme versjoner: det står ingen
tidspunkter i dem. Finnes mappa fra før med et tidligere resultat (en `resultat.json` med kjørerens egne nøkler), tas
bare filene det resultatet laget bort: sammendraget, `resultat.json` og `.csv`/`.dat`-filer uten mappe i navnet. Alle
andre filer blir stående. Finnes mappa med andre filer og uten et slikt resultat, stopper kjøreren uten å skrive noe.
Kan mappa ikke lages eller skrives i, stopper den med «Kan ikke skrive i <mappe>: <grunn>. Velg en annen mappe med
--ut.» (exit 2).

## Nøkkeltallene

Fra det kjernens `summary`, `summary2` og `summary_endo` skriver ut, med norske navn og norsk tallformat. Et
nøkkeltall vises bare når modellen har tidsserien det bygger på.

| Nøkkel i `resultat.json` | Hva |
|---|---|
| `K_snitt` | kriminalitet, gjennomsnitt fra måned 12 (bare `simulate_endo`, som `Kmean`) |
| `K_maks`, `K_slutt` | kriminalitet, høyeste og ved slutt |
| `spenn_K` | høyeste minus laveste K etter måned 60 (`amp(K,t>60)` i `sim.py`) |
| `spenn_K_sist` | høyeste minus laveste K de siste 60 månedene, når horisonten er over 120 mnd: vedvarende svingning |
| `KA_slutt`, `KB_slutt` | belastning per sakstype ved slutt (`simulate_chain2`) |
| `T_maks`, `T_slutt` | politiets innsats |
| `L_min`, `L_slutt` | tillit |
| `tauD_maks`, `tauD_slutt` (og `tauA_*`, `tauB_*`) | saksbehandlingstid, mnd |
| `Q_slutt_mnd` (og `QA_slutt_mnd`, `QB_slutt_mnd`) | kø ved slutt, i måneder av innstrømningen før sjokket (Q delt på J0 = `gamma`·`Lam0`·`T0`, 0,1 med notatets tall; køen før sjokket er om lag 2,9) |
| `inn_ut_slutt` | saker inn delt på saker avgjort ved slutt (`ups_end` i `summary`) |
| `Z_maks`, `Z_slutt` | kapasitet, 1,00 = ved start (når kapasiteten endres) |
| `utenom_maks_pst`, `utenom_slutt_pst` | andel ledet utenom, prosent (når den endres) |
| `q_maks` | prosessuell kvalitet (når kvalitetssløyfen er på) |
| `frafall`, `kapasitetsaar` | frafall fra køen summert over tid, i måneder av innstrømningen før sjokket (som i notatets tabell i avsnitt 8.5; `summary_endo` skriver det i modellens enheter, en tidel av dette), og kapasitetsår over utgangsnivået (`simulate_endo`) |

Under tabellen står: 1,00 er nivået i referanselikevekten før sjokket for K og T (i modellene med kø: nivået ved
start, nesten, men ikke helt, en likevekt, med driften før sjokket), tilliten er `Lam0` der (0,80 med notatets tall),
kapasitet 1,00 er kapasiteten ved start, tider er i måneder, og (når modellen har kø) at køen er målt i måneder av
innstrømningen før sjokket. Med `"startlikevekt": "ubalanse"` byttes den første delen ut, se over.

## Feil og exit-koder

Exit-kode 0 når alt gikk, 2 ved feil i scenariofila eller bruken. Meldingen nevner feltet:

```
Feil i scenariofila mitt.json: parametere.P.gama: ukjent parameter i P. Mente du "gamma"? Gyldige: gamma, eta, ...
Feil i scenariofila mitt.json: styring.forsinkelse: må være et tall minst 0, ikke "tre".
Feil i scenariofila mitt.json: sveip[0].parameter: "styring.reaktivtet": ukjent felt "reaktivtet" under styring. ...
Fila mitt.json er ikke gyldig JSON: feil på linje 2, kolonne 15.
```

Stopper en kjøring i kjernen (en regnefeil, for eksempel en kombinasjon der kjernen ikke finner køen ved start), eller
gir den verdier som ikke er endelige tall (uendelig eller NaN, en løsning som har vokst over alle grenser), stopper
kjøreren med exit 2. Meldingen sier hvilken kjøring det var og hvilke tidsserier, og ingenting skrives. Store, men
endelige utslag stopper ikke; de får en merknad i sammendraget.

## Eksempelfilene

### Notatets datafiler: `eksempler/scenarioer/notatet/`

Hver fil gjenskaper en av notatets datafiler med `"format": "notat"`. Testene i `tests/test_scenario.py` sammenligner.

| Notatets fil | Scenariofil | Gjenskapt |
|---|---|---|
| `p3`, `p6`, `p11`, `p11d`, `mpc11` | samme navn | byte for byte |
| `kjede_s1` … `kjede_s5` | samme navn | byte for byte |
| `endo_e5`, `endo_des`, `endo_desp`, `endo_ko` | samme navn | byte for byte |
| `sat_B`, `sat_C` | samme navn (sveip over `P.ksat`: `inf`, 3, 1,5) | kolonne for kolonne |
| `prio_s2`, `prio_s3`, `prio_s5` | samme navn (sveip over `CH2.prio`: med og uten forrang) | kolonne for kolonne |
| `vippe` | `vippe.json` (fast, p3, p6) og `vippe_tak.json` (p3cap, p6cap) | kolonne for kolonne |

«Kolonne for kolonne»: notatets fil setter sammen kolonner fra flere kjøringer; hver kolonne er lik tegn for tegn
den tilsvarende kolonnen i kjøringens fil. `stab.dat` og `thumb.dat` er analytiske kart (`critical_delay`), ikke
simuleringer, og har ingen scenariofil.

### Spørsmål notatet ikke har figur for: `eksempler/scenarioer/`

| Fil | Spørsmål |
|---|---|
| `avviklingstid_koordinert.json` | hvor raskt bør restansen avvikles i den koordinerte regelen (T_clear fra 6 til 96 mnd og uendelig)? |
| `stabilitet_reaktivitet_forsinkelse.json` | hvor går grensen for svingninger, over reaktivitet og forsinkelse, sammenlignet med den kritiske forsinkelsen? |
| `sjokkstorrelse_kjede.json` | hvor mye betyr størrelsen på sjokket når domstolen er en flaskehals? |
| `kvalitetssloyfe.json` | hva gjør kvalitetssløyfen med desentraliserte og koordinerte regler? |
| `utvidelse_bolge.json` | hva etterlater en forbigående bølge i pådraget, med og uten flaskehals (utvidelsen `paadrag_tidsserie`)? |
| `uten_sjokk_kjede.json` | hvor mye driver modellen med kø av seg selv uten sjokk (240 mnd)? Nullinjen å sammenligne små virkninger med |