enok/README.md

# enok

Årlig energiberegning og energirapport for bygninger etter **NS 3031:2025**, med
timesoppløsning gjennom hele året og energikarakter etter Enovas skala som gjelder fra
1. januar 2026.

Programmet tar en beskrivelse av bygningen — geometri, konstruksjoner, vinduer, ventilasjon,
varmekilder og drift — og et typisk klimaår, og gir 8760 timesverdier, et fullt energibudsjett
fra netto energibehov til vektet levert energi, en energikarakter og en ferdig rapport i PDF.

```
enok beregn bygning.toml
```

```
  Eldre enebolig med kjeller  (Småhus, 140 m², byggeår 1948)
  Klimadata: Indre Østfold

  Varmetapstall                3,00 W/(m²K)
  Netto energibehov           352,2 kWh/(m²·år)
  Levert energi               328,5 kWh/(m²·år)
  Vektet levert energi        328,5 kWh/(m²·år)
  Energikarakter                  F

  Tiltak:
    Isolerte varmerør og kjellervegger  311,9 kWh/(m²·år)   F
    Nye vinduer                         305,6 kWh/(m²·år)   E
    Etterisolert klimaskjerm            207,0 kWh/(m²·år)   D
    Væske-vann-varmepumpe               162,7 kWh/(m²·år)   C
    Full pakke                           68,5 kWh/(m²·år)   A
```

## Hva programmet gjør

**Beregningsmetode.** Dynamisk timesberegning etter NS-EN ISO 52016-1, slik NS 3031:2025
krever. Hver opake bygningsdel modelleres med fem noder der varmekapasiteten fordeles etter
masseplassering, vinduer med to noder, og sonen har en luftnode og en strålingsnode som
fordeler langbølget utveksling mellom innvendige overflater. Systemet løses implisitt for hver
time. Varme- og kjølebehovet bestemmes ved å løse uten tilført effekt og med en prøveeffekt;
siden systemet er lineært treffer interpolasjonen settpunktet nøyaktig.

**Beregningspunkter.** Budsjettet følger NS 3031:2025 fra A til E: netto energibehov,
brutto etter distribusjons- og akkumuleringstap, tilført energi etter systemvirkningsgrad og
årsvarmefaktor for hver varmekilde, levert energi per energibærer med fradrag for
egenprodusert solstrøm, og til slutt vektet levert energi.

**Energikarakter.** Vektet levert energi per kvadratmeter oppvarmet BRA slås opp i Enovas
skala, med arealkorreksjonen som gjelder for småhus og boligblokk. Vektingsfaktorene er
elektrisitet 1,0, fjernvarme og biobrensel 0,45, eksportert energi 0. Vedovn regnes å dekke
inntil 10 prosent av romoppvarmingen.

**Klimadata.** Timesverdier for alle norske kommuner fra datasettet som ble laget til
NS 3031:2025 (CERRA 1991–2020, CC-BY-4.0). Beregnes bygningen i lokalt klima, korrigeres de
klimaavhengige energipostene til referanseklima Oslo med klimakorrigeringsfaktorene fra
standardens tillegg, slik energimerkeforskriften krever. Arkivet lastes ned én gang og
hurtiglagres.

**Grunnen og kjelleren.** Flater mot grunnen regnes etter NS-EN ISO 13370: jordas varmemotstand
gjør at en uisolert grunnmur taper langt mindre enn U-verdien alene tilsier, og en kjellervegg
deles i en del over terreng, som er en vanlig yttervegg, og en nedgravd del. En uoppvarmet
kjeller eller et kaldt loft kan modelleres som en egen sone. Temperaturen der regnes ut time
for time av sonens varmebalanse etter NS-EN ISO 13789, med varme fra rommene over og fra
varmerør og beredere som står der. Uisolerte rør i kjelleren teller dermed både som tap fra
varmeanlegget og som varme som holder etasjeskilleren varm.

**Overoppheting.** Bygninger uten kjøleanlegg luftes gjennom vinduer. Uten det ville en tett
bygning med store vindusflater fått urealistisk høye innetemperaturer om våren og høsten, og
lagret solvarme ville kunstig redusert oppvarmingsbehovet. Grensen settes til den normerte
settpunkttemperaturen for kjøling, og luftingen koster ingen energi.

**Ventilasjon.** Varmegjenvinneren reguleres ned når den ellers ville varmet tilluften over
settpunktet. Et anlegg med `kjolebatteri = true` holder tilluften på normert temperatur i
driftstiden, slik DiBKs modellbygg for energirammene er regnet, og energien føres som
ventilasjonskjøling.

**Bygningskategorier.** Normerte laster og driftstider er lagt inn for småhus, boligblokk,
barnehage, kontorbygg, skolebygg, idrettsbygg og kulturbygg. Driftstidene har timer per døgn,
dager per uke og uker per år; lastene gjelder bare på driftsdager, og ukene uten drift legges
i ferier. For sykehus, sykehjem, hotell, forretningsbygg, universitet og lett industri er det
ikke funnet offentlige kilder, og de krever en egen fil i `--data KATALOG/normerte/`.

**Tiltak.** Scenarier i samme fil gir før-og-etter-tall og karakterer i én tabell.

## Installasjon

```sh
cargo install --path .
```

Typst må være installert for PDF-rapporten. Uten Typst kjører du med `--ingen-pdf`; da skrives
`rapport.typ` som du kan kompilere senere.

## Bruk

| Kommando | Hva den gjør |
| --- | --- |
| `enok beregn FIL.toml` | Beregner og skriver rapport, CSV og JSON til `ut/<navn>/` |
| `enok beregn modell.ifc` | Beregner rett fra en modell, uten at `bygning.toml` finnes fra før |
| `enok import FIL` | Leser IFC, gbXML eller regneark og skriver `bygning.toml` |
| `enok import FIL --tillegg prosjekt.toml` | Som over, med en tilleggsfil flettet inn (se nedenfor) |
| `enok tillegg modell.ifc bygning.toml` | Skriver forskjellen mellom modellen og en håndredigert fil som tilleggsfil |
| `enok klima --liste` | Lister alle kommuner med klimadata |
| `enok klima --kommune Oslo` | Viser nøkkeltall for ett klimasted |
| `enok skala smaahus --areal 140` | Viser karakterskalaen med arealkorreksjon |

Nyttige valg til `beregn`: `--tillegg FIL`, `--ingen-pdf`, `--ingen-timeserie`, `--enova-xml`,
`--uten-scenarier`, `--ut KATALOG`.

### Utdata

| Fil | Innhold |
| --- | --- |
| `rapport.pdf` | Energirapport med karakter, varmetapsbudsjett, energibudsjett og figurer |
| `rapport.typ`, `stil.typ` | Typst-kilde, slik at rapporten kan tilpasses |
| `resultat.json` | Hele resultatet, inkludert forutsetninger og månedsverdier |
| `timeserie.csv` | 8760 rader med temperaturer, laster, sol og energistrømmer |
| `maaned.csv` | Månedssummer |
| `enova-2014.xml` | XML for energimerkesystemet, med `--enova-xml` |

## Bygningsbeskrivelsen

En bygning beskrives i TOML. Alt som utelates fylles med normerte verdier for
bygningskategorien, eller med typiske verdier for byggeåret, og rapporten viser hva som er
antatt og hvor det kommer fra.

```toml
[bygning]
navn = "Eldre enebolig med kjeller"
kategori = "smaahus"
byggeaar = 1948
oppvarmet_bra = 140.0

[klima]
kommune = "Indre Østfold"   # eller posisjon = [59.63, 11.01] for nærmeste klimasted

[[flate]]
navn = "Yttervegg sør"
type = "vegg"
areal = 26.0
orientering = 180      # grader fra nord med klokka
u_verdi = 1.0          # eller `lag = [{ materiale = "tre", tykkelse = 0.02 }, …]`
masseklasse = "lett"
mot = "ute"            # ute | grunn | uoppvarmet

[[vindu]]
navn = "Vinduer sør"
areal = 6.0
orientering = 180
u_verdi = 2.80
g_verdi = 0.76

[infiltrasjon]
n50 = 8.0

[[sone]]                 # uoppvarmet kjeller, med egen temperaturberegning
navn = "Kjeller"
volum = 165.0
andel_distribusjonstap = 1.0   # uisolerte varmerør avgir varmen sin her

[[sone.flate]]
navn = "Kjellermur"
type = "vegg"
areal = 108.0
u_verdi = 3.13
mot = "grunn"
dybde = 1.6            # nedgravd høyde
over_terreng = 0.6     # høyden som står over terreng

[ventilasjon]
type = "naturlig"      # naturlig | avtrekk | balansert
# kjolebatteri = true  # balansert anlegg med kjølebatteri

[[oppvarming.kilde]]
type = "el_kjel"       # direkte_el, luft_luft_vp, vaeske_vann_vp, vedovn, fjernvarme, …
andel_rom = 0.75
andel_tappevann = 1.0

[[scenario]]
navn = "Nye vinduer"
endringer.vindu = [{ navn = "Vinduer sør", u_verdi = 0.80, g_verdi = 0.50 }]
```

Scenarier flettes inn i bygningsbeskrivelsen: tabeller flettes rekursivt, elementer i lister
matches på `navn` eller `type`, nye elementer legges til, og `slett = true` fjerner et element.
Et navn med `*` treffer alle elementer det passer på, for eksempel `navn = "Yttervegg*"`.

Ferdige eksempler ligger i `eksempler/`.

## Import fra Vectorworks og andre BIM-verktøy

| Format | Slik henter du det | Hva som kommer med |
| --- | --- | --- |
| IFC | *Fil → Eksporter → Export IFC Project* | Flater, areal, U-verdier fra egenskapssett, himmelretning fra plassering, vinduer og dører koblet til vegg |
| gbXML | Verktøy som eksporterer gbXML | Rom, flater, åpninger, konstruksjoner med lag |
| Regneark | *Fil → Eksporter → Export Worksheet* | Enkel CSV med én rad per bygningsdel |

### Modellen og en tilleggsfil

Modellen er kilden til alt den kan beskrive, og en modell alene gir en ferdig rapport: enok
fyller hullene med normerte verdier og typiske verdier for byggeåret, og rapporten sier hva
som er antatt. Det modellen ikke kan beskrive, som varmeanlegg, lekkasjetall og tiltak, og
rettelser der den mangler noe, legges i en tilleggsfil som flettes inn etter de samme reglene
som scenarioene:

```sh
enok beregn modell.ifc                              # bare modellen
enok beregn modell.ifc --tillegg prosjekt.toml      # modellen og tilleggsfilen
enok import modell.ifc --tillegg prosjekt.toml --ut bygning.toml   # samme, som fil
```

`beregn` skriver bygningsbeskrivelsen modellen ga, til `bygning.toml` i utdatakatalogen, slik
at beregningen kan etterprøves.

En ny import skriver aldri over manuelle endringer, for de ligger ikke i den genererte filen.
Har du likevel en `bygning.toml` du har redigert for hånd, lager `enok tillegg` en tilleggsfil
av forskjellen mot modellen, så arbeidet følger med videre:

```sh
enok tillegg modell.ifc bygning.toml --ut prosjekt.toml
```

Tillegget inneholder alt filen sier som modellen ikke sier: endrede U-verdier, drift,
varmeanlegg og scenarioer, og `slett = true` for oppføringer modellen har og filen ikke.
Kommandoen kontrollerer at tillegget gjenskaper filen det er laget av, og sier fra om noe
ikke lar seg uttrykke. `enok import` nekter dessuten å skrive over en fil enok ikke har laget
selv, med mindre `--overskriv` er oppgitt.

```toml
# prosjekt.toml
[import]
uoppvarmede_rom = ["Kott", "Bod"]   # holdes utenfor oppvarmet BRA

[[flate]]
navn = "Yttervegg*"                 # alle ytterveggene, uansett himmelretning
masseklasse = "lett"

[[flate]]
navn = "Roof Slab"                  # skråtaket mangler U-verdi i modellen
u_verdi = 0.55

[[vindu]]
navn = "V-*"
g_verdi = 0.76

[[sone]]
navn = "Kjeller"
andel_distribusjonstap = 1.0

[[sone.flate]]
navn = "Kjellermur*"
over_terreng = 0.6

[[oppvarming.kilde]]
type = "el_kjel"
andel_rom = 1.0
andel_tappevann = 1.0
```

Flatene får navn etter konstruksjonen i modellen, og vegger får himmelretningen etter navnet
(«Yttervegg, sør»), slik at tilleggsfilen kan vise til dem. Importen er deterministisk: samme
modell og tilleggsfil gir alltid samme `bygning.toml`. Et mønster som ikke treffer noe, nevnes
i merknadene, og et vanlig navn som ikke finnes i modellen, legges til som ny oppføring.

### Hva enok henter ut av en IFC-modell

| Opplysning | Hvor den kommer fra |
| --- | --- |
| Areal for vegger, tak og dekker | Geometrien. Trekantene grupperes etter retning, og den største gruppen er delens hovedflate. Vinduer som er skåret ut av veggen kommer riktig fram, siden hullene mangler trekanter. Materialsjikt som ligger oppå hverandre telles én gang |
| Himmelretning og helning | Flatenormalen, dreid med elementets plassering og prosjektets sanne nord |
| U-verdi | `ThermalTransmittance` i egenskapssettene, for både konstruksjoner og vinduer |
| Ytre eller innvendig | `IsExternal` |
| Masseklasse | Materialnavnene. Betong, tegl og mur gir tung konstruksjon, bindingsverk og isolasjon lett |
| Etasjer og hva som ligger i dem | `IfcBuildingStorey` med høyde, og tilknytningen av rom og bygningsdeler |
| Uoppvarmet kjeller | En etasje under referansenivået blir satt opp som egen sone, med sine egne vegger og gulv, og dekket over som grense mot den oppvarmede delen |
| Oppvarmet BRA | Rommene i etasjene over terreng. Rom som heter kott, bod, loft eller garasje blir flagget |
| Vindus- og dørareal | `OverallHeight` og `OverallWidth`, og hvilken vegg de sitter i |
| Posisjon | `IfcMapConversion` med `IfcProjectedCRS`, ellers `IfcSite`. Uten oppgitt kommune velger beregningen nærmeste klimasted. EUREF89 UTM og Web Mercator forstås |
| Grunnmur over terreng | `ElevationOfRefHeight` og `ElevationOfTerrain` på bygningen |
| Adresse | `BuildingAddress` på bygningen, eller `SiteAddress` på tomta. Adressen i forfatteropplysningene er firmaets og brukes ikke |
| Energirådgiver | Person og organisasjon i forfatteropplysningene |
| Byggets navn | Bygningens navn, eller prosjektets når bygningen heter «Default Building» |
| Vernet bygning | `IsLandmarked`. Vernede bygninger er unntatt plikten til energiattest |

Himmelretningene og arealene bør likevel kontrolleres mot tegningen. Importen skriver merknader
øverst i TOML-filen om hva den måtte anta.

### Egenskaper enok leser

IFC beskriver geometri og konstruksjon, men har ingen fast plass til byggeår, tetthet,
ventilasjon eller hvordan huset varmes opp. Det er nettopp de opplysningene som skiller en god
energiberegning fra en middelmådig: for et hus fra 1948 er forskjellen mellom lekkasjetall 0,6
og 8 langt større enn alt annet i modellen.

De kan likevel følge med. I Vectorworks lager du et postformat, fester det på bygningen og
knytter feltene til et IFC-egenskapssett. enok leser da disse navnene fra et hvilket som helst
egenskapssett på `IfcBuilding`, `IfcSite` eller `IfcProject`:

| Felt | Godtar også | Eksempel |
| --- | --- | --- |
| `Byggeaar` | `Byggeår`, `YearOfConstruction` | `1948` |
| `Bygningskategori` | `Kategori`, `BuildingCategory` | `Småhus` |
| `Kommune` | `Municipality`, `Klimasted` | `Indre Østfold` |
| `Lekkasjetall` | `n50`, `AirPermeability` | `8.0` |
| `Ventilasjonstype` | `Ventilasjon`, `VentilationType` | `Balansert` |
| `Varmegjenvinning` | `Gjenvinning`, `HeatRecoveryEfficiency` | `80` |
| `Varmekilde` | `Oppvarming`, `HeatingSource` | `Bergvarmepumpe` |
| `OppvarmetBRA` | `HeatedFloorArea` | `120` |

Mangler en bygningsdel U-verdi i modellen, sier importen hvilke det gjelder, og beregningen
bruker en typisk verdi for byggeåret. Det gjelder også vinduer og dører, som i de fleste
eksportene ikke har U-verdi.

Med de åtte feltene på plass er importen fra IFC nær nok komplett til at beregningen står på
modellen alene.

Dette i selve modellen er verdt å gjøre riktig, omtrent i rekkefølge etter hva det betyr:

- **Ta med designlagene i eksporten.** I «Export IFC Project» må lagene være knyttet til
  etasjer under «Layer Mapping». Mangler de, blir filen bare prosjektstruktur uten vegger,
  dekker, vinduer eller rom. enok stopper da med en feilmelding i stedet for å skrive en tom
  bygning.
- **Georeferer tegningen, eller sett prosjektstedet.** Da får modellen koordinater, og
  beregningen velger selv nærmeste av de 358 klimastedene. Uten det står Vectorworks'
  standardverdi i Washington, og den blir oversett.
- **Merk yttervegger med `IsExternal`.** I en typisk eksport er bare en liten del av
  veggene merket, og kjellermurene er sjelden blant dem.
- **Fyll inn U-verdi for tak og vinduer.** Veggene har den, takflatene og vinduene ikke.
- **Gi etasjene navn.** «Kjeller», «1. etg.» og «2. etg.» er nok til at enok finner den
  uoppvarmede kjelleren og regner oppvarmet areal riktig.
- **Sett referansehøyde og terrenghøyde på bygningen.** Da regner enok ut hvor mye av
  grunnmuren som står over bakken. Uten dem regnes hele muren som nedgravd.
- **Legg byggets adresse på bygningen.** Adressen i forfatteropplysningene er firmaets, og
  brukes ikke som byggets adresse.

Regnearkformatet er bevisst enkelt, slik at det kan settes opp som en rapport i BIM-verktøyet:

```csv
type,navn,areal,u_verdi,orientering,helning,mot,g_verdi,antall
bygning,Eldre enebolig,140,,,,smaahus,1948,
vegg,Yttervegg sør,26,1.0,180,90,ute,,
gulv,Mot kjeller,98,0.8,,180,uoppvarmet,,
vindu,Stue sør,3.0,2.8,180,90,,0.76,2
```

## Rapporter fra byggeserveren

Rapportene lages i hvert prosjektlager, ikke i enok. enoks egne arbeidsflyter kjører på
vertskjøreren `fish` på samme måte som de andre prosjektene:

| Fil | Hva den gjør |
| --- | --- |
| `test.yml` | Formatering, clippy og tester på hver push |
| `release.yml` | Bygger enok og legger binærfilen ved utgivelsen |

### Energirapport fra et byggeprosjekt

Et prosjektlager med sin egen IFC-modell og tilleggsfil trenger ikke Rust. Det henter
binærfilen fra enoks siste utgivelse. Én jobb lager `bygning.toml` av modellen, og en annen
beregner rapporten av den:

```yaml
name: Energirapport
on:
  release:
    types: [published]
jobs:
  bygningsmodell:
    runs-on: fish
    defaults:
      run:
        shell: fish {0}
    steps:
      - uses: https://gitea.com/actions/checkout@v6
      - name: Hent enok og lag bygning.toml
        env:
          TOKEN: ${{ github.token }}
        run: |
          # Gitea har ingen «latest/download»-sti, så taggen slås opp først.
          set TAG (curl -sS --fail --header "Authorization: token $TOKEN" \
            "$GITHUB_SERVER_URL/api/v1/repos/klingenbergbygg/enok/releases/latest" | jq -r '.tag_name')
          curl -sSL --fail -o enok --header "Authorization: token $TOKEN" \
            "$GITHUB_SERVER_URL/klingenbergbygg/enok/releases/download/$TAG/enok"
          chmod +x enok
          ./enok import modell.ifc --tillegg prosjekt.toml --ut bygning.toml
      - uses: https://gitea.com/actions/upload-artifact@v4
        with:
          name: bygningsmodell
          path: |
            bygning.toml
            enok
  rapport:
    needs: bygningsmodell
    runs-on: fish
    defaults:
      run:
        shell: fish {0}
    steps:
      - uses: https://gitea.com/actions/checkout@v6
      - uses: https://gitea.com/actions/download-artifact@v4
        with:
          name: bygningsmodell
      - name: Lag rapporten
        run: |
          chmod +x enok
          ./enok beregn bygning.toml --ut dist
```

## Kontroll av beregningen

Motoren er kontrollert mot uavhengige referanser:

| Kontroll | Resultat |
| --- | --- |
| Solinnstråling på skrå og orienterte flater, mot pvlib (Hay–Davies) | avvik under 1 % for alle himmelretninger i Oslo-klima |
| Stasjonært varmetap mot U·A·ΔT | innenfor 2 % |
| Grunnmodellen mot NS-EN ISO 13370 | kompakthet, dybde og isolasjon virker som standarden beskriver |
| Kjellermodellen mot NS-EN ISO 13789 | varme rør hever kjellertemperaturen og reduserer romoppvarmingen |
| Årlig energibalanse | går opp innenfor 2 % |
| Varmebehov som funksjon av temperaturdifferanse | eksakt lineært |
| Varmetapsbudsjett for TEK17-referansebygget | identisk med publisert tabell, 0,69 W/(m²K) |
| Normerte energiposter for småhus | varmtvann 25,1, belysning 11,4, teknisk utstyr 17,5 kWh/(m²·år) |
| Faste energiposter for yrkesbyggene | belysning, utstyr og varmtvann treffer energibudsjettene i kildene |

### Kjent avvik

Standard Norges lanseringseksempel for NS 3031:2025 oppgir 46,2 kWh/(m²·år) romoppvarming og
106,4 kWh/(m²·år) netto energibehov for TEK17-referansebygget beregnet med Simien 8. enok
beregner 27,1 og 86,6 for den samme bygningen.

Varmetapsbudsjettet, de normerte energipostene, solinnstrålingen og energibalansen stemmer
hver for seg, så avviket ligger i hvor stor del av solvarmen som nyttiggjøres. NS 3031:2025
Tillegg A er ikke offentlig tilgjengelig, så de normerte solfaktorene, skjermings­forutsetningene
og timesprofilene Simien bruker, lar seg ikke etterprøve her. `tests/referansebygg.rs` låser
dagens verdier slik at endringer i motoren blir synlige, og oppdateres når standardens
forutsetninger er tilgjengelige.

Bruk derfor tallene til å sammenligne tiltak mot hverandre og til å se hvor varmen forsvinner.
Til en energiattest som skal leveres til Enova må resultatet kontrolleres mot et validert
beregningsprogram.

## Datagrunnlag

Alle normerte verdier ligger i `data/` og kan overstyres med `--data KATALOG`.

| Fil | Innhold og kilde |
| --- | --- |
| `skala.toml` | Energikarakterskalaen fra 1.1.2026, Enova SF via Multiconsult-notatet «Grunnlag for ny energikarakterskala», 19.12.2025 |
| `vekting.toml` | Vektingsfaktorer etter energimerkeforskriften § 10a med NVEs veileder |
| `normerte/*.toml` | Normerte laster, driftstider og settpunkt. Utgangspunktet er NS 3031:2014 Tillegg A; varmtvann for boliger er oppdatert til NS 3031:2025-verdien for småhus. Tillegg A er ikke offentlig, så yrkesbyggverdiene er hentet fra publiserte Simien-utskrifter og DiBK-utredninger. Hver fil oppgir kildene og hvilke verdier som er antatt. Timesprofiler fra NS 3031:2025 kan legges inn i `profil_*`-feltene |
| `varmepumpe_spf.toml` | Veiledende årsvarmefaktorer, NS 3031:2014 tabell B.9-3 |
| `materialer.toml` | Materialdata og typiske U-verdier per byggeperiode |
| `klimakorreksjon.csv` | Klimakorrigeringsfaktorer, Standard Norge SN/K 34, doi 10.5281/zenodo.15041587 |

Klimadata: «TMY files for Norway based on CERRA data from 1991-2020», doi
10.5281/zenodo.14779899, CC-BY-4.0.

## Regelverk

- Forskrift om energimerking av bygninger og energivurdering av varme- og klimaanlegg,
  §§ 10a og 10b, med NVEs veileder
- NS 3031:2025 *Bygningers energiytelse — Beregning av energi- og effektbehov*
- NS-EN ISO 52016-1:2017 og NS-EN ISO 52010-1:2017

## Lisens

MIT.