Source code for energy_analysis.strata

"""Reproducible STRATA-to-asset study and local-output command line workflow.

Run ``python -m energy_analysis.strata --demo --output artifacts/strata``.
The demo creates synthetic native-layout arrays; it never invokes STRATA.
"""

from __future__ import annotations

import argparse
import hashlib
import json
from dataclasses import asdict
from importlib.metadata import version
from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import xarray as xr
from matplotlib.figure import Figure

from energy_methods.strata_impact import (
    energy_scenario,
    extract_strata_timeseries,
    nearest_strata_cell,
    paired_error_metrics,
)

REFERENCE_IDS = ("nvidia_strata_2026",)


[docs] def synthetic_inputs() -> tuple[xr.Dataset, pd.DataFrame]: """Create a deterministic 24-hour fixture with the STRATA output schema. One small synthetic face covers Canary coordinates; this is not a real cube mesh or forecast. Two model-level labels expose label-versus-index mistakes. """ lat, lon = np.meshgrid( np.linspace(27.5, 29.3, 37), np.linspace(-18.3, -15.0, 67), indexing="ij" ) hours = np.arange(1, 25, dtype=float) centre_lon = -18.5 + 0.16 * hours[:, None, None] pulse = np.exp(-(((lon - centre_lon) / 0.65) ** 2) - ((lat - 28.2) / 0.9) ** 2) u = 7 + 18 * pulse v = 3 + 7 * pulse temperature = 293.15 + 2 * np.sin((hours[:, None, None] - 8) * np.pi / 12) + 0 * pulse surface = ("time", "step", "face", "x", "y") volume = ("time", "step", "level", "face", "x", "y") ds = xr.Dataset( { "T_2m": (surface, temperature[None, :, None], {"units": "K"}), "precip_liq_surf_mass_flux": ( surface, (22 * pulse / 3_600_000)[None, :, None], {"units": "m/s"}, ), "U": (volume, np.stack((u * 1.3, u), axis=1)[None, :, :, None], {"units": "m/s"}), "V": (volume, np.stack((v * 1.3, v), axis=1)[None, :, :, None], {"units": "m/s"}), "lat": (("face", "x", "y"), lat[None]), # Deliberately store 0..360 longitudes, unlike asset coordinates. "lon": (("face", "x", "y"), (lon % 360)[None]), }, coords={ "time": [np.datetime64("2020-10-13T00:00:00", "ns")], "step": np.arange(1, 25).astype("timedelta64[h]"), "level": [24, 30], }, attrs={"source": "SYNTHETIC schema fixture; no STRATA inference or SCREAM data"}, ) assets = pd.DataFrame( [ {"asset": "Tenerife PV", "latitude": 28.30, "longitude": -16.57, "capacity_mw": 20}, { "asset": "Gran Canaria wind", "latitude": 27.94, "longitude": -15.55, "capacity_mw": 30, }, {"asset": "La Palma PV", "latitude": 28.65, "longitude": -17.85, "capacity_mw": 10}, ] ) return ds, assets
[docs] def sample_assets( dataset: xr.Dataset, assets: pd.DataFrame, *, wind_level: int, time_index: int = 0, max_distance_km: float = 25.0, ) -> tuple[pd.DataFrame, pd.DataFrame]: """Return weather and a reusable, auditable asset-to-cell mapping.""" required = {"asset", "latitude", "longitude"} if not required.issubset(assets.columns) or assets.empty: raise ValueError("Assets require nonempty asset, latitude and longitude columns") if assets.asset.isna().any() or assets.asset.duplicated().any(): raise ValueError("Asset names must be present and unique") weather, mappings = [], [] for row in assets.to_dict("records"): cell = nearest_strata_cell( dataset, latitude=float(row["latitude"]), longitude=float(row["longitude"]), max_distance_km=max_distance_km, ) table = extract_strata_timeseries( dataset, cell=cell, wind_level=wind_level, time_index=time_index ) table.insert(0, "asset", str(row["asset"])) weather.append(table) mappings.append( { "asset": str(row["asset"]), **asdict(cell), "requested_latitude": float(row["latitude"]), "requested_longitude": float(row["longitude"]), } ) return pd.concat(weather, ignore_index=True), pd.DataFrame(mappings)
[docs] def demo_baseline(weather: pd.DataFrame, assets: pd.DataFrame) -> np.ndarray: """Synthetic interval-mean power plan, separate from STRATA weather.""" capacity = weather.asset.map(assets.set_index("asset").capacity_mw).to_numpy(float) # Mid-interval solar-shaped plan; no irradiance or PV physical model is implied. solar = 0.75 * np.maximum(0, np.sin(np.pi * (weather.lead_hours.to_numpy() - 6.5) / 12)) factor = np.where(weather.asset.str.contains("wind"), 0.45, solar) return capacity * factor
[docs] def compare_reference(weather: pd.DataFrame, reference: pd.DataFrame) -> pd.DataFrame: """Score exact site/time/model-level pairs; also show first-lead persistence. Input reference CSV must contain asset, valid_time, wind_model_level, wind_speed_ms, precipitation_mm_h and temperature_c. No partial joins. """ keys = ["asset", "valid_time"] variables = ["wind_speed_ms", "precipitation_mm_h", "temperature_c"] required = {*keys, "wind_model_level", *variables} if not required.issubset(reference.columns): raise ValueError(f"Reference requires columns {sorted(required)}") ref = reference.copy() ref["valid_time"] = pd.to_datetime(ref.valid_time) pred = weather.set_index(keys).sort_index() ref = ref.set_index(keys).sort_index() if not pred.index.equals(ref.index) or not ref.index.is_unique: raise ValueError("Reference must match every asset and valid_time exactly") if not np.array_equal(pred.wind_model_level, ref.wind_model_level): raise ValueError("Reference model-level labels differ from forecast") rows = [] for asset, group in pred.groupby(level="asset", sort=False): truth = ref.loc[[asset]] for name in variables: for model, values in ( ("STRATA output", group[name]), ("First-lead persistence", pd.Series(group[name].iloc[0], index=group.index)), ): rows.append( { "asset": asset, "variable": name, "model": model, **paired_error_metrics(values, truth[name]), } ) return pd.DataFrame(rows)
[docs] def scenario_summary(scenario: pd.DataFrame) -> pd.DataFrame: """Sum energy/value and endpoint threshold exposure hours per asset.""" table = scenario.copy() table["wind_alert_hours"] = table.wind_alert * table.interval_hours table["rain_alert_hours"] = table.rain_alert * table.interval_hours return ( table.groupby("asset", sort=False)[ [ "baseline_mwh", "scenario_mwh", "energy_at_risk_mwh", "gross_value_at_risk_eur", "wind_alert_hours", "rain_alert_hours", ] ] .sum() .reset_index() )
[docs] def plot_weather(weather: pd.DataFrame) -> Figure: """Three shared-time panels for model-level wind, rain rate and temperature.""" fig, axes = plt.subplots(3, 1, figsize=(10, 8), sharex=True, layout="constrained") for asset, table in weather.groupby("asset", sort=False): for ax, variable in zip( axes, ["wind_speed_ms", "precipitation_mm_h", "temperature_c"], strict=True ): ax.plot(table.lead_hours, table[variable], label=str(asset), linewidth=2) for ax, label in zip( axes, ["Model-level wind (m/s)", "Liquid rain rate (mm/h)", "2-m temperature (°C)"], strict=True, ): ax.set_ylabel(label) ax.grid(alpha=0.2) axes[0].legend(ncol=3, fontsize=9) axes[0].set_title("Sampled STRATA-layout fields — check run provenance for data basis") axes[-1].set_xlabel("Lead time from initialization (hours)") return fig
[docs] def write_results( output: Path, weather: pd.DataFrame, cells: pd.DataFrame, *, provenance: dict[str, object], scenario: pd.DataFrame | None = None, metrics: pd.DataFrame | None = None, ) -> None: """Export CSVs, a plot and a manifest with hashes of the sampled artifacts.""" if output.exists() and any(output.iterdir()): raise ValueError("Output directory must be empty to prevent mixing different runs") output.mkdir(parents=True, exist_ok=True) tables = {"weather.csv": weather, "asset_cells.csv": cells} if scenario is not None: tables.update({"scenario.csv": scenario, "summary.csv": scenario_summary(scenario)}) if metrics is not None: tables["reference_metrics.csv"] = metrics for name, table in tables.items(): table.to_csv(output / name, index=False) fig = plot_weather(weather) fig.suptitle(str(provenance["data_basis"]), fontsize=11) fig.savefig(output / "weather.png", dpi=160) plt.close(fig) manifest = { **provenance, "versions": {name: version(name) for name in ["numpy", "pandas", "xarray"]}, "sha256": { name: hashlib.sha256((output / name).read_bytes()).hexdigest() for name in tables }, "units_when_absent": "Native SCREAM: T_2m K; U/V m/s; liquid flux m/s", "spatial_method": "nearest cell on sphere; no terrain/height correction", "interval_method": "right-endpoint rectangular exposure; baseline is interval-mean MW", "wind_basis": "SCREAM model-level coordinate; not hub-height, 10-m wind or gusts", "upstream": "https://github.com/NVlabs/STRATA", } (output / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
[docs] def main() -> None: """Run the synthetic example or consume a local, completed STRATA Zarr store.""" parser = argparse.ArgumentParser(description=__doc__) source = parser.add_mutually_exclusive_group(required=True) source.add_argument("--demo", action="store_true") source.add_argument("--input", type=Path, help="Local completed STRATA Zarr output") parser.add_argument("--assets", type=Path, help="CSV: asset,latitude,longitude") parser.add_argument( "--wind-level", type=int, default=30, help="Model-level label, not position" ) parser.add_argument("--time-index", type=int, default=0) parser.add_argument("--max-distance-km", type=float, default=25) parser.add_argument("--reference", type=Path, help="SCREAM paired-reference CSV; see guide") parser.add_argument("--baseline", type=Path, help="CSV: asset,valid_time,baseline_mw") parser.add_argument("--wind-threshold-ms", type=float, default=20) parser.add_argument("--rain-threshold-mm-h", type=float, default=15) parser.add_argument("--price-eur-mwh", type=float, default=60) parser.add_argument("--output", required=True, type=Path) args = parser.parse_args() if args.demo: dataset, assets = synthetic_inputs() else: if args.assets is None: parser.error("--assets is required with --input") dataset = xr.open_zarr(args.input, chunks=None, consolidated=False) assets = pd.read_csv(args.assets) try: weather, cells = sample_assets( dataset, assets, wind_level=args.wind_level, time_index=args.time_index, max_distance_km=args.max_distance_km, ) finally: dataset.close() initial_time = weather.valid_time.iloc[0] - pd.to_timedelta( weather.lead_hours.iloc[0], unit="h" ) baseline = demo_baseline(weather, assets) if args.demo else None if args.baseline: plan = pd.read_csv(args.baseline, parse_dates=["valid_time"]) keys = ["asset", "valid_time"] left, right = weather.set_index(keys), plan.set_index(keys) if not right.index.is_unique or set(left.index) != set(right.index): raise ValueError("Baseline must contain exactly one row for each asset/valid_time") baseline = right.reindex(left.index).baseline_mw.to_numpy(float) scenario = ( None if baseline is None else energy_scenario( weather, baseline, wind_threshold_ms=args.wind_threshold_ms, rain_threshold_mm_h=args.rain_threshold_mm_h, price_eur_mwh=args.price_eur_mwh, ) ) metrics = compare_reference(weather, pd.read_csv(args.reference)) if args.reference else None provenance = { "data_basis": "SYNTHETIC demonstration; no inference" if args.demo else "User-supplied STRATA simulation output", "source": str(args.input) if args.input else "synthetic_inputs()", "assets_source": str(args.assets) if args.assets else "illustrative Canary locations", "reference_source": str(args.reference) if args.reference else None, "baseline_source": str(args.baseline) if args.baseline else "synthetic plan" if args.demo else None, "wind_model_level": args.wind_level, "initialization_index": args.time_index, "initialization_time": initial_time.isoformat(), "max_distance_km": args.max_distance_km, "wind_threshold_ms": args.wind_threshold_ms, "rain_threshold_mm_h": args.rain_threshold_mm_h, "wind_reduction": 0.15, "rain_reduction": 0.05, "price_eur_mwh": args.price_eur_mwh, "input_csv_sha256": { str(path): hashlib.sha256(path.read_bytes()).hexdigest() for path in [args.assets, args.reference, args.baseline] if path }, "store_integrity": "Not verified; retain upstream successful-run log and store checksums", } write_results( args.output, weather, cells, provenance=provenance, scenario=scenario, metrics=metrics ) print(f"Wrote {len(weather)} asset/lead rows to {args.output}") if scenario is not None: print(scenario_summary(scenario).to_string(index=False))
if __name__ == "__main__": main()