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.

Et første eksempel

{
  "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
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 (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

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, 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.

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.

Viktig: CH0.Z og CH0.m (og CH2.Z, CH2.m) er regnet ut fra P da sim.py ble lest inn (ZD0, MD). Endrer du P.gamma, P.Lam0 eller P.T0, regnes de ikke om; domstolen er da ikke lenger 95 % utnyttet før sjokket. Oppgi CH0.Z og CH0.m selv om du vil ha det.

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 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, større enn 0 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.

sveip

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

"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):

"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 eller utvidelse, 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
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; Z_rel i simulate_endo er det notatets endo_*.dat kaller Z.

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. 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 og budsjettvedtakene. 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, tas bare filene det resultatet laget bort. Finnes den med andre filer, stopper kjøreren uten å skrive noe.

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 (og QA_slutt, QB_slutt)	kø ved slutt
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, tilliten er 0,80 der, kapasitet 1,00 er kapasiteten ved start, tider er i måneder.

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 og høyst 120, 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 kombinasjon uten likevekt ved start eller med en løsning som vokser over alle grenser), sier meldingen hvilken kjøring det var, og ingenting skrives.

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)?