Source code for energy_data_retrieval.hydro_catalogue.nve

"""Offline NVE candidate staging. Never merge source identities by plant name.

Attribution: Norwegian Water Resources and Energy Directorate (NVE), NLOD.
https://api.nve.no/doc/vannkraftdatabase/ documents the source field semantics.
Candidates require an explicit identity review before canonical acceptance.
"""

from __future__ import annotations

import json
import math
from typing import Any

from energy_data_retrieval.pv_catalogue.catalogue import canonical_json

from .catalogue import stable_id
from .gppd import evidence_record


def _number(raw: dict[str, Any], key: str) -> float | None:
    value = raw.get(key)
    if value is None:
        return None
    if isinstance(value, bool) or not isinstance(value, (float, int)):
        raise ValueError(f"Invalid numeric {key}")
    value = float(value)
    if not math.isfinite(value) or value < 0:
        raise ValueError(f"Invalid numeric {key}")
    return value


[docs] def parse_nve( text: str, *, source_id: str, now: str ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]: """Stage all generating assets and record exclusions/conflicts by registry ID. PK identifies pumped capability, not pure/mixed subtype. P is pump-only and cannot supply generating MW. Normal-period generation is not measured annual output. API January-1 commissioning dates are retained only as raw metadata. Every candidate has unresolved aggregation and remains outside the catalogue. """ payload = json.loads(text) if not isinstance(payload, list): raise ValueError("Expected NVE JSON array") seen: set[int] = set() candidates, decisions = [], [] for index, raw in enumerate(payload): external = raw.get("VannKraftverkID") if type(external) is not int or external in seen: raise ValueError("Missing/duplicate NVE registry ID") seen.add(external) locator = f"JSON array index {index}; VannKraftverkID={external}" decision = {"nve_id": external, "locator": locator} if raw.get("VannKVTypeID") == "P": decisions.append({**decision, "decision": "excluded_pump_only"}) continue try: if raw.get("VannKVTypeID") not in {"K", "PK"} or not raw.get("Navn"): raise ValueError("Unknown type or missing name") operating = raw.get("ErIDrift") retired = raw.get("Kraftverkstatus") == "Ute av drift" building = raw.get("UnderBygging") if type(operating) is not bool or type(building) is not bool: raise ValueError("Missing lifecycle flags") if operating and (retired or building): raise ValueError("Conflicting lifecycle flags") status = ( "operational" if operating else "under_construction" if building else "decommissioned" if retired else "unknown" ) capacity = _number(raw, "MaksYtelse") generation = _number(raw, "MidProd_91_20") values = { "record_id": stable_id("projects", "NVE", str(external)), "entity_type": "projects", "record_scope": "plant", "name": raw["Navn"], "country_code": "NOR", "external_ids_json": canonical_json({"nve": str(external)}), "aggregation_role": "unresolved", "quality_status": "needs_review", "capacity_scope": "NVE registry asset; WRI and other catalogue overlap unresolved", "status": status, "status_as_of": now[:10], "status_date_basis": "Retrieval of continuously maintained official NVE API", "technology": "pumped_storage" if raw["VannKVTypeID"] == "PK" else "unknown", "installed_capacity_mw": capacity if operating else None, "operational_capacity_mw": capacity if operating else None, "gross_head_m": _number(raw, "BruttoFallhoyde_M"), "design_flow_m3_s": _number(raw, "Slukeevne"), "basin": raw.get("Nedborsfeltnavn") or None, "owner_names": [raw["HovedEier"]] if raw.get("HovedEier") else None, "operator_names": sorted( { o["Navn"] for o in raw.get("Eiere", []) if o.get("Driftselskap") and o.get("Navn") } ) or None, "observations_json": canonical_json( [ { "field": "mean_annual_generation", "value": generation, "unit": "GWh/year", "kind": "modeled", "period": "1991-2020", "boundary": "NVE production referenced to inflow normal period", "source_id": source_id, "locator": locator + "; MidProd_91_20", } ] ) if generation is not None else None, "extensions_json": canonical_json( { "region": raw.get("Fylke"), "municipality": raw.get("Kommune"), "regine_id": raw.get("RegineNr"), "price_area_number": raw.get("ElspotomraadeNummer"), "commissioning_date_raw": raw.get("IDriftDato"), "commissioning_precision": "unverified; do not treat January 1 as precise", "source_type": raw["VannKVTypeID"], "pumped_subtype": "pure/mixed unresolved" if raw["VannKVTypeID"] == "PK" else None, "reported_maximum_mw": capacity, "head_basis": "Source gross head at 67 percent reservoir filling", "flow_basis": "Maximum turbine water flow, not observed discharge", } ), } candidates.append( evidence_record(values, source_id=source_id, now=now, locator=locator) ) decisions.append({**decision, "decision": "candidate_identity_review_required"}) except ValueError as exc: decisions.append({**decision, "decision": "quarantined", "reason": str(exc)}) return candidates, decisions