scada-schema 0.1.0__py3-none-any.whl

scada_schema/__init__.py

@@ -0,0 +1,31 @@
+"""An open data standard for wind and PV SCADA.
+
+* [`signals`][scada_schema.signals] - the registry of canonical signals (names, units, conventions, limits);
+* [`model`][scada_schema.model] - dataset metadata and profiles (wind, PV);
+* [`validate`][scada_schema.validate] - is a table in the schema?
+* [`io`][scada_schema.io] - self-describing Parquet;
+* [`loaders`][scada_schema.loaders] - Kelmarsh, Penmanshiel, Hill of Towie, La Haute Borne, CARE and PVDAQ to the schema;
+* [`qc`][scada_schema.qc] - data quality checks and an HTML report;
+* [`states`][scada_schema.states] - status codes to IEC 61400-26 categories;
+* [`convert`][scada_schema.convert] - wind-up, OpenOA and pvlib.
+"""
+
+from scada_schema._version import __version__
+from scada_schema.io import finalise, read_meta, read_parquet, write_parquet
+from scada_schema.model import DatasetMeta, Device, Source
+from scada_schema.signals import SIGNALS
+from scada_schema.validate import SchemaError, validate
+
+__all__ = [
+    "SIGNALS",
+    "DatasetMeta",
+    "Device",
+    "SchemaError",
+    "Source",
+    "__version__",
+    "finalise",
+    "read_meta",
+    "read_parquet",
+    "validate",
+    "write_parquet",
+]

scada_schema/__main__.py

@@ -0,0 +1,3 @@
+from scada_schema.cli import main
+
+raise SystemExit(main())

scada_schema/_steps.py

@@ -0,0 +1,50 @@
+"""Finding a step in the level of a series: the common core of the unit-switch check of the quality control and of the
+loader that corrects PVDAQ's hectowatt-to-watt change."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+__all__ = ["daily_log_ratio", "level_step"]
+
+
+def daily_log_ratio(power: pd.Series, reference: pd.Series, min_reference: float = 200.0, min_points: int = 8) -> pd.Series | None:
+    """log10 of the daily median of ``power / reference`` where the reference (irradiance) exceeds ``min_reference``.
+
+    Both series are indexed by time stamp; days with fewer than ``min_points`` such intervals are dropped. ``None`` when fewer
+    than 14 days remain.
+    """
+    ref = reference.reindex(power.index)
+    r = (power.where(power > 0) / ref.where(ref > min_reference)).dropna()
+    if r.empty:
+        return None
+    g = r.groupby(r.index.floor("D"))
+    d, n = g.median(), g.size()
+    d = d[(n >= min_points) & (d > 0)]
+    return np.log10(d) if len(d) >= 14 else None
+
+
+def level_step(levels: pd.Series, window: int = 7, min_decades: float = 0.8) -> tuple[pd.Timestamp, float] | None:
+    """The largest step of at least ``min_decades`` (log10) in a daily series, as ``(first day at the new level, step)``.
+
+    The step is the difference between the median of the next ``window`` days and of the previous ``window`` days; the median
+    windows smear a step over +-``window`` days, so the change is put at the first day past the midpoint level.
+    """
+    vals = levels.to_numpy(dtype=float)
+    n = len(vals)
+    if n < 2 * window + 1:
+        return None
+    jump = np.full(n, np.nan)
+    for i in range(window, n - window):
+        jump[i] = np.median(vals[i:i + window]) - np.median(vals[i - window:i])
+    if not np.isfinite(jump).any():
+        return None
+    i = int(np.nanargmax(np.abs(jump)))
+    step = float(jump[i])
+    if abs(step) < min_decades:
+        return None
+    mid = (np.median(vals[max(i - window, 0):i]) + np.median(vals[i:i + window])) / 2
+    span = np.arange(max(i - window, 0), min(i + window, n))
+    cross = span[(vals[span] > mid) if step > 0 else (vals[span] < mid)]
+    return levels.index[int(cross[0]) if len(cross) else i], step

scada_schema/_time.py

@@ -0,0 +1,12 @@
+"""Time helpers: pandas 3 no longer defaults to nanosecond resolution, the code below does arithmetic on nanoseconds."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def to_ns(s: pd.Series | pd.DatetimeIndex) -> np.ndarray:
+    """Time stamps as int64 nanoseconds since the epoch, whatever the resolution of the datetime column."""
+    s = pd.Series(s) if isinstance(s, pd.DatetimeIndex) else s
+    return s.dt.as_unit("ns").astype("int64").to_numpy()

scada_schema/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

scada_schema/cli.py

@@ -0,0 +1,295 @@
+"""Command line interface of scada-schema.
+
+Usage:
+    scada-schema signals --profile wind
+    scada-schema fetch kelmarsh --years 2019 --data-dir data/kelmarsh
+    scada-schema load kelmarsh --years 2019 --data-dir data/kelmarsh --states --out out/kelmarsh_2019.parquet
+    scada-schema validate out/kelmarsh_2019.parquet
+    scada-schema qc out/kelmarsh_2019.parquet --html out/qc.html --dst-zone Europe/London
+    scada-schema convert out/kelmarsh_2019.parquet --to windup --out out/windup
+    scada-schema resample plant.parquet --to 1h --out plant_1h.parquet
+    scada-schema import mapping.yaml --out my_farm.parquet
+    scada-schema jsonschema --out schema
+    scada-schema spec > SPEC.md
+    scada-schema study --out results
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from scada_schema import __version__
+from scada_schema.io import read_parquet, write_parquet
+from scada_schema.loaders import DATASETS
+from scada_schema.signals import PROFILE_SIGNALS, SIGNALS
+from scada_schema.validate import validate
+
+log = logging.getLogger("scada_schema")
+
+
+def _signals(args) -> int:
+    rows = [s for n, s in SIGNALS.items() if args.profile in (None, *s.profiles)]
+    df = pd.DataFrame([{"signal": s.name, "unit": s.unit, "kind": s.kind, "profiles": "+".join(s.profiles), "devices": ",".join(s.devices),
+                        "lo": s.lo, "hi": s.hi, "stats": s.stats, "description": s.description} for s in rows])
+    if args.format == "csv":
+        print(df.to_csv(index=False))
+    elif args.format == "json":
+        print(df.to_json(orient="records", indent=1))
+    else:
+        print(df.to_string(index=False, max_colwidth=70))
+    log.info("%d signals (wind %d, pv %d)", len(df), len(PROFILE_SIGNALS["wind"]), len(PROFILE_SIGNALS["pv"]))
+    return 0
+
+
+def _loader_kwargs(args) -> dict:
+    mod = DATASETS[args.dataset]
+    kw: dict = {}
+    if args.dataset == "pvdaq":
+        kw["system"] = args.system
+        if args.no_fix_units:
+            kw["fix_units"] = False
+    elif args.dataset == "care":
+        kw.update(farm=args.farm, event_id=args.event)
+    if args.years and args.dataset not in ("care", "la_haute_borne"):
+        kw["years"] = args.years
+    del mod
+    return kw
+
+
+def _fetch(args) -> int:
+    mod = DATASETS[args.dataset]
+    if args.dataset == "pvdaq":
+        n = mod.fetch(args.data_dir, system=args.system, years=args.years or [2016])
+        log.info("fetched %d daily files", n)
+    elif args.dataset == "care":
+        p = mod.fetch(args.data_dir, datasets={args.farm: [args.event]})
+        log.info("wrote %s", p)
+    elif args.dataset == "la_haute_borne":
+        for p in mod.fetch(args.data_dir):
+            log.info("ready %s", p)
+    else:
+        for p in mod.fetch(args.data_dir, years=args.years):
+            log.info("ready %s", p)
+    return 0
+
+
+def _load(args) -> int:
+    mod = DATASETS[args.dataset]
+    loaded = mod.load(args.data_dir, **_loader_kwargs(args))
+    if args.states:
+        from scada_schema.states import attach_states
+
+        if len(loaded.events):
+            attach_states(loaded)
+        else:
+            log.warning("no event log: --states ignored")
+    rep = validate(loaded.table, loaded.meta)
+    for i in rep.issues:
+        log.log(logging.ERROR if i.level == "error" else logging.WARNING, "%s: %s", i.code, i.message)
+    out = write_parquet(loaded.table, loaded.meta, args.out)
+    if len(loaded.events):
+        loaded.events.to_parquet(Path(args.out).with_suffix(".events.parquet"))
+    log.info("wrote %s: %d rows, %d devices, %d events", out, len(loaded.table), loaded.table["device_id"].nunique(), len(loaded.events))
+    return 0
+
+
+def _validate(args) -> int:
+    df, meta = read_parquet(args.file)
+    rep = validate(df, meta)
+    print(rep.to_frame().to_string(index=False) if rep.issues else "no issues")
+    print(f"{len(df):,} rows, {df['device_id'].nunique()} devices, profile {meta.profile}, interval {meta.interval}: "
+          + ("valid" if rep.ok else f"{len(rep.errors)} error(s)"))
+    return 0 if rep.ok else 1
+
+
+def _qc(args) -> int:
+    from scada_schema import qc
+
+    df, meta = read_parquet(args.file)
+    cfg = qc.QCConfig(dst_zone=args.dst_zone) if args.dst_zone else None
+    report = qc.run(df, meta, cfg, checks=args.checks)
+    s = report.summary()
+    print(s.to_string(index=False) if len(s) else "no findings")
+    print("severity counts:", report.counts(), "| skipped:", report.checks_skipped or "none")
+    if args.html:
+        report.to_html(args.html)
+        log.info("wrote %s", args.html)
+    if args.json:
+        report.to_json(args.json)
+        log.info("wrote %s", args.json)
+    return 1 if args.fail_on_error and report.counts()["error"] else 0
+
+
+def _convert(args) -> int:
+    df, meta = read_parquet(args.file)
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    if args.to == "windup":
+        from scada_schema.convert import windup
+
+        scada, notes = windup.to_windup_scada(df, meta)
+        scada.to_parquet(out / "scada.parquet")
+        spec = {"notes": notes}
+        try:
+            spec["turbine_type"] = windup.windup_turbine_types(df, meta, args.turbine_type)
+            spec["turbines"] = windup.windup_turbines(meta, spec["turbine_type"])
+        except ValueError as e:
+            spec["turbine_type_error"] = str(e)
+            log.warning("%s", e)
+        (out / "windup.json").write_text(json.dumps(spec, indent=1), encoding="utf-8")
+    elif args.to == "openoa":
+        from scada_schema.convert import openoa
+
+        scada, asset = openoa.to_openoa_frames(df, meta)
+        scada.to_parquet(out / "scada.parquet")
+        asset.to_parquet(out / "asset.parquet")
+    else:
+        from scada_schema.convert import pvlib
+
+        inp = pvlib.to_pvlib(df, meta, inverter=args.inverter, at=args.at)
+        inp.weather.to_parquet(out / "weather.parquet")
+        inp.p_ac_kw.to_frame().to_parquet(out / "p_ac_kw.parquet")
+        (out / "pvlib.json").write_text(json.dumps({"location": inp.location, "system": inp.system, "notes": inp.notes}, indent=1), encoding="utf-8")
+    log.info("wrote %s", out)
+    return 0
+
+
+def _resample(args) -> int:
+    from scada_schema.resample import resample
+
+    df, meta = read_parquet(args.file)
+    out, m = resample(df, meta, args.to, args.min_coverage)
+    write_parquet(out, m, args.out)
+    log.info("wrote %s: %d rows at %s (from %d at %s)", args.out, len(out), args.to, len(df), meta.interval)
+    return 0
+
+
+def _import(args) -> int:
+    from scada_schema.loaders.generic import import_table, load_spec
+
+    loaded = import_table(load_spec(args.mapping), validate_result=not args.no_validate)
+    out = write_parquet(loaded.table, loaded.meta, args.out, check=not args.no_validate)
+    log.info("wrote %s: %d rows, %d devices", out, len(loaded.table), loaded.table["device_id"].nunique())
+    return 0
+
+
+def _jsonschema(args) -> int:
+    from scada_schema import jsonschema
+
+    for p in jsonschema.write(args.out):
+        log.info("wrote %s", p)
+    return 0
+
+
+def _spec(args) -> int:
+    from scada_schema.spec import render_spec
+
+    sys.stdout.write(render_spec())
+    return 0
+
+
+def _study(args) -> int:
+    from scada_schema import study
+
+    study.run(Path(args.out), only=args.only, skip_converters=args.skip_converters)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="scada-schema", description="Open data standard for wind and PV SCADA.")
+    p.add_argument("--version", action="version", version=f"scada-schema {__version__}")
+    p.add_argument("-v", "--verbose", action="store_true", help="debug logging")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("signals", help="list the canonical signals")
+    s.add_argument("--profile", choices=["wind", "pv"])
+    s.add_argument("--format", choices=["table", "csv", "json"], default="table")
+    s.set_defaults(func=_signals)
+
+    def dataset_args(sp):
+        sp.add_argument("dataset", choices=sorted(DATASETS))
+        sp.add_argument("--data-dir", help="folder with the raw files (default: $SCADA_SCHEMA_<NAME>_DIR, $SCADA_SCHEMA_DATA/<name>, ./data/<name>)")
+        sp.add_argument("--years", type=int, nargs="+")
+        sp.add_argument("--system", type=int, default=34, choices=[34, 1276, 1278, 35], help="PVDAQ system")
+        sp.add_argument("--farm", default="A", choices=["A", "B", "C"], help="CARE wind farm")
+        sp.add_argument("--event", type=int, default=0, help="CARE event (dataset) id")
+
+    s = sub.add_parser("fetch", help="download an open dataset from its original source (checksums verified)")
+    dataset_args(s)
+    s.set_defaults(func=_fetch)
+
+    s = sub.add_parser("load", help="read an open dataset into a canonical Parquet file")
+    dataset_args(s)
+    s.add_argument("--out", required=True)
+    s.add_argument("--states", action="store_true", help="add status_code and iec_category from the event log")
+    s.add_argument("--no-fix-units", action="store_true", help="PVDAQ: keep the hectowatt reading of power (for demonstrating the unit check)")
+    s.set_defaults(func=_load)
+
+    s = sub.add_parser("validate", help="check a canonical Parquet file against the schema")
+    s.add_argument("file")
+    s.set_defaults(func=_validate)
+
+    s = sub.add_parser("qc", help="run the quality checks")
+    s.add_argument("file")
+    s.add_argument("--html")
+    s.add_argument("--json")
+    s.add_argument("--checks", nargs="+")
+    s.add_argument("--dst-zone", help="IANA zone whose daylight saving changes are looked for, e.g. Europe/Warsaw")
+    s.add_argument("--fail-on-error", action="store_true", help="exit with 1 when any finding has severity error")
+    s.set_defaults(func=_qc)
+
+    s = sub.add_parser("convert", help="convert a canonical file to the input of wind-up, OpenOA or pvlib")
+    s.add_argument("file")
+    s.add_argument("--to", required=True, choices=["windup", "openoa", "pvlib"])
+    s.add_argument("--out", required=True, help="output folder")
+    s.add_argument("--turbine-type", default="turbine", help="wind-up turbine type name")
+    s.add_argument("--inverter", help="pvlib: inverter id")
+    s.add_argument("--at", default="center", choices=["start", "center", "end"], help="pvlib: instant of the interval that indexes the weather")
+    s.set_defaults(func=_convert)
+
+    s = sub.add_parser("resample", help="move a canonical file to a coarser interval (rules by signal kind)")
+    s.add_argument("file")
+    s.add_argument("--to", required=True, choices=["10min", "15min", "30min", "1h"])
+    s.add_argument("--min-coverage", type=float, default=0.8, help="share of source intervals needed to fill a target interval")
+    s.add_argument("--out", required=True)
+    s.set_defaults(func=_resample)
+
+    s = sub.add_parser("import", help="turn your own export into a canonical Parquet file with a YAML mapping")
+    s.add_argument("mapping")
+    s.add_argument("--out", required=True)
+    s.add_argument("--no-validate", action="store_true")
+    s.set_defaults(func=_import)
+
+    s = sub.add_parser("jsonschema", help="write JSON Schema files and the column list of the standard")
+    s.add_argument("--out", default="schema")
+    s.set_defaults(func=_jsonschema)
+
+    s = sub.add_parser("spec", help="print the specification (SPEC.md) generated from the code")
+    s.set_defaults(func=_spec)
+
+    s = sub.add_parser("study", help="run the schema, QC, mapping and parity study on the open datasets and write results/")
+    s.add_argument("--out", default="results")
+    s.add_argument("--only", nargs="+", help="names of the study datasets to run")
+    s.add_argument("--skip-converters", action="store_true")
+    s.set_defaults(func=_study)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.INFO, format="%(levelname)s %(message)s", stream=sys.stderr)
+    try:
+        return int(args.func(args))
+    except (FileNotFoundError, ValueError, KeyError) as e:
+        log.error("%s", e)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scada_schema/convert/__init__.py

@@ -0,0 +1,8 @@
+"""Converters from the canonical table to the inputs of wind-up, OpenOA and pvlib.
+
+Each module imports its target lazily, so the package works without them; install ``scada-schema[converters]``.
+"""
+
+from scada_schema.convert import openoa, pvlib, windup
+
+__all__ = ["openoa", "pvlib", "windup"]

scada_schema/convert/openoa.py

@@ -0,0 +1,80 @@
+"""Canonical wind table to an [OpenOA](https://github.com/NREL/OpenOA) ``PlantData`` (v3).
+
+OpenOA's SCADA schema names the columns ``time``, ``asset_id``, ``WTUR_W`` (kW), ``WMET_HorWdSpd`` (m/s),
+``WMET_HorWdDir`` (deg), ``WMET_HorWdDirRel`` (deg), ``WTUR_TurSt`` (status, text), ``WROT_BlPthAngVal`` (deg) and
+``WMET_EnvTmp`` (degC); the asset table has one row per turbine (``asset_id``, ``latitude``, ``longitude``,
+``rated_power`` in kW, ``hub_height``, ``rotor_diameter``, ``elevation``, ``type``).
+
+============================  ==========================  ==============================================
+OpenOA column                 canonical signal            note
+============================  ==========================  ==============================================
+``WTUR_W``                    ``p_ac``                    kW
+``WMET_HorWdSpd``             ``wind_speed``              m/s
+``WMET_HorWdDir``             ``wind_dir``                absolute, from; absent if the source has none
+``WMET_HorWdDirRel``          ``wind_dir_rel``
+``WTUR_TurSt``                ``status_code``             text
+``WROT_BlPthAngVal``          ``pitch``                   deg
+``WMET_EnvTmp``               ``t_amb``                   degC
+============================  ==========================  ==============================================
+
+The ``time`` column is the canonical time stamp as naive UTC (OpenOA's schema does not state which instant of the interval
+it marks; the canonical table marks the start). Elevation is not part of the schema and is left empty unless given.
+
+Usage:
+    plant = to_openoa(df, meta)         # needs openoa
+    plant.scada, plant.asset
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from scada_schema.model import DatasetMeta
+
+__all__ = ["COLUMN_MAP", "to_openoa", "to_openoa_frames"]
+
+COLUMN_MAP = {
+    "p_ac": "WTUR_W", "wind_speed": "WMET_HorWdSpd", "wind_dir": "WMET_HorWdDir", "wind_dir_rel": "WMET_HorWdDirRel",
+    "status_code": "WTUR_TurSt", "pitch": "WROT_BlPthAngVal", "t_amb": "WMET_EnvTmp",
+}
+
+
+def to_openoa_frames(df: pd.DataFrame, meta: DatasetMeta, turbines: list[str] | None = None,
+                     elevation_m: float | None = None) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """The SCADA and asset frames of OpenOA, without needing OpenOA installed."""
+    if meta.profile != "wind":
+        raise ValueError("OpenOA's PlantData needs a wind table")
+    for need in ("p_ac", "wind_speed"):
+        if need not in df.columns or not df[need].notna().any():
+            raise ValueError(f"OpenOA's SCADA schema needs {need}")
+    devs = [d for d in meta.devices if d.type == "turbine" and (turbines is None or d.id in turbines)]
+    ids = [d.id for d in devs]
+    missing = [d.id for d in devs if d.lat is None or d.lon is None or d.rated_kw is None]
+    if missing:
+        raise ValueError(f"OpenOA's asset table needs latitude, longitude and rated power; missing for {missing[:5]}")
+    sub = df[df["device_id"].isin(ids)]
+    scada = pd.DataFrame({"time": sub["timestamp"].dt.tz_convert("UTC").dt.tz_localize(None).to_numpy(), "asset_id": sub["device_id"].to_numpy()})
+    for src, dst in COLUMN_MAP.items():
+        if src in sub.columns and sub[src].notna().any():
+            scada[dst] = sub[src].to_numpy(dtype="float64", na_value=np.nan) if src != "status_code" else sub[src].astype(object).to_numpy()
+    if "WTUR_TurSt" in scada:
+        scada["WTUR_TurSt"] = scada["WTUR_TurSt"].astype(object).where(scada["WTUR_TurSt"].notna(), None)
+    asset = pd.DataFrame({
+        "asset_id": ids, "latitude": [d.lat for d in devs], "longitude": [d.lon for d in devs],
+        "rated_power": [d.rated_kw for d in devs], "hub_height": [d.hub_height_m if d.hub_height_m else np.nan for d in devs],
+        "rotor_diameter": [d.rotor_diameter_m if d.rotor_diameter_m else np.nan for d in devs],
+        "elevation": [elevation_m if elevation_m is not None else np.nan] * len(devs), "type": "turbine",
+    })
+    return scada, asset
+
+
+def to_openoa(df: pd.DataFrame, meta: DatasetMeta, turbines: list[str] | None = None, elevation_m: float | None = None,
+              analysis_type: list[str] | None = None):
+    """An OpenOA ``PlantData`` from a canonical wind table (needs the ``openoa`` extra)."""
+    from openoa import PlantData
+
+    scada, asset = to_openoa_frames(df, meta, turbines, elevation_m)
+    md = {"latitude": float(asset["latitude"].mean()), "longitude": float(asset["longitude"].mean()),
+          "capacity": float(asset["rated_power"].sum() / 1000.0), "scada": {"frequency": meta.interval}, "asset": {}}
+    return PlantData(analysis_type=analysis_type, metadata=md, scada=scada, asset=asset)

scada_schema/convert/pvlib.py

@@ -0,0 +1,98 @@
+"""Canonical PV table to [pvlib](https://pvlib-python.readthedocs.io) inputs: weather, location, array geometry, measured power.
+
+pvlib works with instants and its own column names. The converter
+
+* takes the weather from the met device (``met`` or ``plant``) of the table: ``ghi``, ``dni``, ``dhi``, ``poa_global`` (from ``poa``),
+  ``temp_air`` (from ``t_amb``), ``wind_speed``, ``temp_module`` (from ``t_module``, the measured back-of-module value);
+* indexes it by the **centre of the interval** (``at="center"``, the right instant for a mean over the interval; ``"start"`` and
+  ``"end"`` are also available) in UTC;
+* gives the location and the array geometry of an inverter (``surface_tilt``, ``surface_azimuth`` clockwise from north, 180 =
+  south, ``pdc0`` in W from ``capacity_kwp``);
+* returns the measured AC power of the inverter in kW on the same index, to compare with a model.
+
+Units already agree (W/m2, degC, m/s); no conversion happens here.
+
+Usage:
+    inputs = to_pvlib(df, meta, inverter="INV")
+    loc = pvlib.location.Location(**inputs.location)
+    weather, p_meas = inputs.weather, inputs.p_ac_kw
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from scada_schema.model import DatasetMeta
+
+__all__ = ["COLUMN_MAP", "PvlibInputs", "to_pvlib"]
+
+COLUMN_MAP = {"ghi": "ghi", "dni": "dni", "dhi": "dhi", "poa": "poa_global", "t_amb": "temp_air", "wind_speed": "wind_speed",
+              "t_module": "temp_module"}
+_SHIFT = {"start": 0.0, "center": 0.5, "end": 1.0}
+
+
+@dataclass
+class PvlibInputs:
+    weather: pd.DataFrame
+    location: dict
+    system: dict
+    p_ac_kw: pd.Series
+    notes: list[str]
+
+
+def to_pvlib(df: pd.DataFrame, meta: DatasetMeta, inverter: str | None = None, met: str | None = None, at: str = "center") -> PvlibInputs:
+    """pvlib inputs for one inverter of a canonical PV table.
+
+    Parameters
+    ----------
+    df, meta
+        Canonical PV table and its metadata.
+    inverter : str, optional
+        Inverter id (the only one by default).
+    met : str, optional
+        Met device id (the only ``met`` or ``plant`` device by default).
+    at : {"center", "start", "end"}
+        Which instant of the interval indexes the result.
+    """
+    if meta.profile != "pv":
+        raise ValueError("to_pvlib needs a PV table")
+    if at not in _SHIFT:
+        raise ValueError(f"at must be one of {list(_SHIFT)}")
+    invs = [d for d in meta.devices if d.type == "inverter"]
+    mets = [d for d in meta.devices if d.type in ("met", "plant")]
+    inv = _pick(invs, inverter, "inverter")
+    met_dev = _pick(mets, met, "met")
+    shift = pd.Timedelta(meta.step * _SHIFT[at])
+    w = df[df["device_id"] == met_dev.id].set_index("timestamp")
+    weather = pd.DataFrame(index=w.index + shift)
+    for src, dst in COLUMN_MAP.items():
+        if src in w.columns and w[src].notna().any():
+            weather[dst] = w[src].to_numpy(dtype="float64", na_value=np.nan)
+    weather.index.name = "time"
+    p = df[df["device_id"] == inv.id].set_index("timestamp")
+    if "p_ac" not in p.columns:
+        raise ValueError(f"inverter {inv.id} has no p_ac")
+    p_ac = pd.Series(p["p_ac"].to_numpy(dtype="float64", na_value=np.nan), index=p.index + shift, name="p_ac_kw")
+    p_ac.index.name = "time"
+    loc_src = inv if inv.lat is not None else met_dev
+    if loc_src.lat is None or loc_src.lon is None:
+        raise ValueError("pvlib needs a latitude and longitude on the inverter or the met device")
+    location = {"latitude": loc_src.lat, "longitude": loc_src.lon, "tz": "UTC"}
+    system = {k: v for k, v in {"surface_tilt": inv.tilt_deg, "surface_azimuth": inv.azimuth_deg,
+                                "pdc0": None if inv.capacity_kwp is None else inv.capacity_kwp * 1000.0}.items() if v is not None}
+    notes = [f"index: {at} of the interval (UTC)"]
+    return PvlibInputs(weather, location, system, p_ac, notes)
+
+
+def _pick(devs, wanted, kind):
+    if wanted is not None:
+        for d in devs:
+            if d.id == wanted:
+                return d
+        raise KeyError(f"no {kind} device {wanted!r}")
+    if len(devs) != 1:
+        raise ValueError(f"the table has {len(devs)} {kind} devices; name one")
+    return devs[0]