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