openenergyid 0.1.29__py3-none-any.whl → 0.1.30__py3-none-any.whl

openenergyid/pvsim/main.py

@@ -0,0 +1,49 @@
+"""PV Simulation module."""
+
+from typing import Annotated, Union
+
+import pandas as pd
+from pydantic import Field
+
+from ..abstractsim import SimulationSummary
+from ..const import ELECTRICITY_DELIVERED, ELECTRICITY_EXPORTED, ELECTRICITY_PRODUCED
+from .elia import EliaPVSimulationInput, EliaPVSimulator
+from .pvlib import PVLibSimulationInput, PVLibSimulator
+
+PVSimulationInput = Annotated[
+    Union[PVLibSimulationInput, EliaPVSimulationInput], Field(discriminator="type")
+]
+
+
+class PVSimulationSummary(SimulationSummary):
+    """Summary of a PV simulation including ex-ante, simulation results, ex-post, and comparisons."""
+
+
+def get_simulator(input_: PVSimulationInput) -> PVLibSimulator | EliaPVSimulator:
+    """Get an instance of the simulator based on the input data."""
+    if isinstance(input_, PVLibSimulationInput):
+        return PVLibSimulator.from_pydantic(input_)
+    if isinstance(input_, EliaPVSimulationInput):
+        return EliaPVSimulator.from_pydantic(input_)
+    raise ValueError(f"Unknown simulator type: {input_.type}")
+
+
+def apply_simulation(input_data: pd.DataFrame, simulation_results: pd.Series) -> pd.DataFrame:
+    """Apply simulation results to input data."""
+    df = input_data.copy()
+
+    if ELECTRICITY_PRODUCED not in df.columns:
+        df[ELECTRICITY_PRODUCED] = 0.0
+    df[ELECTRICITY_PRODUCED] = df[ELECTRICITY_PRODUCED] + simulation_results
+
+    new_delivered = (df[ELECTRICITY_DELIVERED] - simulation_results).clip(lower=0.0)
+    self_consumed = df[ELECTRICITY_DELIVERED] - new_delivered
+    df[ELECTRICITY_DELIVERED] = new_delivered
+
+    exported = simulation_results - self_consumed
+
+    if ELECTRICITY_EXPORTED not in df.columns:
+        df[ELECTRICITY_EXPORTED] = 0.0
+    df[ELECTRICITY_EXPORTED] = df[ELECTRICITY_EXPORTED] + exported
+
+    return df

openenergyid/pvsim/pvlib/__init__.py

@@ -0,0 +1,11 @@
+"""PVLib-based simulator implementation."""
+
+from .main import PVLibSimulationInput, PVLibSimulator
+from .models import ModelChainModel, to_pv
+
+__all__ = [
+    "PVLibSimulator",
+    "PVLibSimulationInput",
+    "ModelChainModel",
+    "to_pv",
+]

openenergyid/pvsim/pvlib/main.py

@@ -0,0 +1,115 @@
+"""
+PVLib-based simulator implementation.
+
+Defines a PVSimulator subclass that uses PVLib's ModelChain and weather data
+to simulate PV system performance.
+"""
+
+import datetime as dt
+from typing import Annotated, Literal, Union
+
+import pandas as pd
+import pvlib
+from aiohttp import ClientSession
+from pvlib.modelchain import ModelChain
+from pydantic import Field
+
+from openenergyid.pvsim.abstract import PVSimulationInputAbstract, PVSimulator
+
+from .models import ModelChainModel, to_pv
+from .quickscan import (
+    QuickScanModelChainModel,  # pyright: ignore[reportAttributeAccessIssue]
+)
+from .weather import get_weather
+
+ModelChainUnion = Annotated[
+    Union[ModelChainModel, QuickScanModelChainModel], Field(discriminator="type")
+]
+
+
+class PVLibSimulationInput(PVSimulationInputAbstract):
+    """
+    Input parameters for the PVLibSimulator.
+    """
+
+    type: Literal["pvlibsimulation"] = Field("pvlibsimulation", frozen=True)  # tag
+    modelchain: ModelChainUnion
+
+
+class PVLibSimulator(PVSimulator):
+    """
+    Simulator for PV systems using PVLib's ModelChain and weather data.
+    """
+
+    def __init__(
+        self,
+        start: dt.date,
+        end: dt.date,
+        modelchain: pvlib.modelchain.ModelChain,
+        weather: pd.DataFrame | None = None,
+        **kwargs,
+    ):
+        """
+        Initialize the simulator with a ModelChain and weather DataFrame.
+
+        Args:
+            modelchain: An instance of pvlib.modelchain.ModelChain.
+            weather: Weather data as a pandas DataFrame.
+        """
+        super().__init__(**kwargs)
+
+        self.start = start
+        self.end = end
+        self.modelchain = modelchain
+        self.weather = weather
+
+    def simulate(self, **kwargs) -> pd.Series:
+        """
+        Run the simulation and return the resulting AC energy series.
+
+        Returns:
+            pd.Series: Simulated AC energy in kWh for each timestep.
+
+        Raises:
+            ValueError: If the AC power result is None.
+        """
+        # Run model
+        self.modelchain.run_model(self.weather)
+
+        results = self.modelchain.results
+        ac = results.ac
+
+        if ac is None:
+            raise ValueError("AC power is None")
+
+        # Convert W to kWh
+        energy = ac * 0.25 / 1000
+
+        energy.name = None
+
+        return energy
+
+    @classmethod
+    def from_pydantic(cls, input_: PVLibSimulationInput) -> "PVLibSimulator":
+        """
+        Create a PVLibSimulator instance from a PVLibSimulationInput model.
+
+        Args:
+            input_: A PVLibSimulationInput instance.
+
+        Returns:
+            PVLibSimulator: An initialized simulator.
+        """
+        mc: ModelChain = to_pv(input_.modelchain)
+
+        return cls(modelchain=mc, **input_.model_dump(exclude={"modelchain"}))
+
+    async def load_resources(self, session: ClientSession | None = None) -> None:
+        weather = get_weather(
+            latitude=self.modelchain.location.latitude,
+            longitude=self.modelchain.location.longitude,
+            start=self.start,
+            end=self.end,
+            tz=self.modelchain.location.tz,
+        )
+        self.weather = weather

openenergyid/pvsim/pvlib/models.py

@@ -0,0 +1,235 @@
+"""
+Dynamic Pydantic models for PVLib classes.
+
+This module provides utilities to generate Pydantic models from PVLib classes,
+enabling serialization, validation, and conversion between Pydantic and PVLib objects.
+It also provides helper functions for recursive conversion and type overlays for
+special PVLib constructs.
+"""
+
+from collections.abc import Mapping, Sequence
+from inspect import Parameter, isclass, signature
+from typing import Annotated, Any, Literal, Union
+
+from pvlib.location import Location
+from pvlib.modelchain import ModelChain
+from pvlib.pvsystem import Array, FixedMount, PVSystem, SingleAxisTrackerMount
+from pydantic import BaseModel, ConfigDict, Field, create_model
+from typing_inspect import get_args, get_origin
+
+# Registry of PVLib classes for which models can be generated
+REGISTRY: dict[str, type] = {
+    "Location": Location,
+    "FixedMount": FixedMount,
+    "SingleAxisTrackerMount": SingleAxisTrackerMount,
+    "Array": Array,
+    "PVSystem": PVSystem,
+    "ModelChain": ModelChain,
+}
+
+# Cache for generated Pydantic models
+MODEL_CACHE: dict[type, type[BaseModel]] = {}
+
+
+def normalize_annotation(ann: Any) -> Any:
+    """
+    Normalize type annotations for use in Pydantic models.
+
+    Converts unknown or third-party types (e.g., numpy, pandas) to Any.
+    """
+    if ann in (Parameter.empty, None):
+        return Any
+    try:
+        mod = getattr(ann, "__module__", "")
+        if mod.startswith(("numpy", "pandas")):
+            return Any
+    except Exception:
+        pass
+    return ann
+
+
+# Overlay for type hints that need to be replaced in generated models
+TYPE_OVERLAY: dict[type, dict[str, Any]] = {}
+
+
+def pyd_model_from_type(py_type: type) -> type[BaseModel]:
+    """
+    Recursively create or retrieve a Pydantic model for a given PVLib class.
+
+    Args:
+        py_type: The PVLib class type.
+
+    Returns:
+        A dynamically created Pydantic model class.
+    """
+    if py_type in MODEL_CACHE:
+        return MODEL_CACHE[py_type]
+
+    # Use the __init__ signature to determine fields
+    sig = signature(py_type.__init__)
+    fields = {}
+
+    for pname, param in sig.parameters.items():
+        if pname == "self":
+            continue
+        default = Field(...) if param.default is Parameter.empty else Field(param.default)
+
+        # Use overlay type if available, otherwise normalized annotation
+        ann = TYPE_OVERLAY.get(py_type, {}).get(pname, normalize_annotation(param.annotation))
+
+        origin = get_origin(ann)
+
+        # Recursively generate models for PVLib class fields
+        if isclass(ann) and ann in REGISTRY.values():
+            ann = pyd_model_from_type(ann)
+
+        # Handle lists/unions of PVLib classes
+        elif origin in (list, list):
+            (t,) = get_args(ann) or (Any,)
+            if isclass(t) and t in REGISTRY.values():
+                t = pyd_model_from_type(t)  # type: ignore
+            ann = list[t]
+        elif origin in (Union,):
+            args = []
+            for t in get_args(ann):
+                if isclass(t) and t in REGISTRY.values():
+                    t = pyd_model_from_type(t)
+                args.append(t)
+            ann = Union[tuple(args)]  # type: ignore
+
+        fields[pname] = (ann, default)
+
+    # Create the Pydantic model dynamically
+    model = create_model(
+        py_type.__name__ + "Model",
+        __base__=BaseModel,
+        __config__=ConfigDict(extra="allow"),
+        __doc__=py_type.__doc__,
+        **fields,
+    )
+    # Attach a back-reference to the PVLib class
+    setattr(model, "_pvlib_type", py_type)
+    MODEL_CACHE[py_type] = model
+    return model
+
+
+def _filter_kwargs(pv_type: type, kwargs: dict) -> dict:
+    """
+    Remove keys from kwargs that are not accepted by the PVLib class constructor.
+
+    Args:
+        pv_type: The PVLib class type.
+        kwargs: Dictionary of keyword arguments.
+
+    Returns:
+        Filtered dictionary with only accepted keys.
+    """
+    sig = signature(pv_type.__init__)
+    params = sig.parameters
+    if any(p.kind is Parameter.VAR_KEYWORD for p in params.values()):
+        return kwargs  # accepts **kwargs, keep all
+    allowed = {n for n in params if n != "self"}
+    return {k: v for k, v in kwargs.items() if k in allowed}
+
+
+def to_pv(obj: Any) -> Any:
+    """
+    Recursively convert a Pydantic model (or nested structure) to a PVLib object.
+
+    Handles BaseModel instances, mappings, sequences, and primitives.
+
+    Args:
+        obj: The object to convert.
+
+    Returns:
+        The corresponding PVLib object or primitive.
+    """
+    # 1) Pydantic model → recurse on attributes (NOT model_dump)
+    if isinstance(obj, BaseModel):
+        pv_type = getattr(obj.__class__, "_pvlib_type", None)
+
+        # Collect declared fields
+        kwargs = {name: to_pv(getattr(obj, name)) for name in obj.__class__.model_fields}
+
+        # Include extras if extra="allow"
+        extra = getattr(obj, "__pydantic_extra__", None)
+        if isinstance(extra, dict):
+            for k, v in extra.items():
+                kwargs[k] = to_pv(v)
+
+        if pv_type is None:
+            # Not a pvlib-backed model: return plain nested dict
+            return kwargs
+
+        # Special case: ModelChain(system, location, **kwargs)
+        if pv_type is ModelChain:
+            system = kwargs.pop("system")
+            location = kwargs.pop("location")
+            return ModelChain(system, location, **_filter_kwargs(pv_type, kwargs))
+
+        # General case: keyword construction
+        return pv_type(**_filter_kwargs(pv_type, kwargs))
+
+    # 2) Containers
+    if isinstance(obj, Mapping):
+        return {k: to_pv(v) for k, v in obj.items()}
+    if isinstance(obj, Sequence) and not isinstance(obj, (str, bytes, bytearray)):
+        return type(obj)(to_pv(v) for v in obj)  # type: ignore
+
+    # 3) Primitives
+    return obj
+
+
+# --- Model definitions for PVLib classes ---
+
+# Location model
+LocationModel = pyd_model_from_type(Location)
+
+# FixedMount model with discriminator field
+FixedMountModel = create_model(
+    "FixedMountModel",
+    kind=(Literal["fixed"], Field("fixed", frozen=True)),  # tag
+    __base__=pyd_model_from_type(FixedMount),
+    __config__=ConfigDict(extra="allow"),
+)
+
+# SingleAxisTrackerMount model with discriminator field
+TrackerMountModel = create_model(
+    "SingleAxisTrackerMountModel",
+    kind=(Literal["tracker"], Field("tracker", frozen=True)),
+    __base__=pyd_model_from_type(SingleAxisTrackerMount),
+    __config__=ConfigDict(extra="allow"),
+)
+
+# Union type for mount models, with discriminator
+MountUnion = Annotated[Union[FixedMountModel, TrackerMountModel], Field(discriminator="kind")]
+
+# Overlay Array.mount type with MountUnion
+TYPE_OVERLAY.update({Array: {"mount": MountUnion}})
+
+# Array model
+ArrayModel = pyd_model_from_type(Array)
+
+# Overlay PVSystem.arrays type to allow list, single, or None
+TYPE_OVERLAY.update({PVSystem: {"arrays": list[ArrayModel] | ArrayModel | None}})
+
+# PVSystem model
+PVSystemModel = pyd_model_from_type(PVSystem)
+
+# Overlay ModelChain system/location types
+TYPE_OVERLAY.update(
+    {
+        ModelChain: {
+            "system": PVSystemModel,
+            "location": LocationModel,
+        }
+    }
+)
+
+# ModelChain model
+ModelChainModel = create_model(
+    "ModelChainModel",
+    type=(Literal["modelchain"], Field("modelchain", frozen=True)),  # tag
+    __base__=pyd_model_from_type(ModelChain),
+    __config__=ConfigDict(extra="allow"),
+)

openenergyid/pvsim/pvlib/quickscan.py

@@ -0,0 +1,99 @@
+"""
+Quick PV system and model chain models for rapid PV simulation setup.
+
+Provides convenience Pydantic models for specifying PV system parameters
+with simplified fields for module and inverter sizing, and for configuring
+a PVLib ModelChain for quick simulations.
+"""
+
+from typing import Any, Literal
+
+from pydantic import ConfigDict, Field, model_validator
+
+from .models import ModelChainModel, PVSystemModel
+
+
+class QuickPVSystemModel(PVSystemModel):
+    """
+    Model for quickly specifying a PV system with simplified sizing fields.
+
+    Allows specifying module and inverter power directly, and automatically
+    derives detailed parameters for use with PVLib.
+    """
+
+    p_module: float = Field(default=420, gt=0, description="Module max DC power in W")
+    p_inverter: float = Field(
+        gt=0,
+        description="Inverter max power in W",
+    )
+    inverter_efficiency: float = Field(
+        default=0.96, gt=0, le=1, description="PVWatts efficiency used to derive PDC0 from PAC."
+    )
+    module_parameters: dict[str, float] = Field(default={"pdc0": 420, "gamma_pdc": -0.003})
+    module_type: str = Field(default="glass_polymer", description="Type of PV module")
+    racking_model: str = Field(default="open_rack", description="Type of racking model")
+
+    model_config = ConfigDict(extra="allow")
+
+    @model_validator(mode="after")
+    def _apply_p_inverter_to_pdc0(self):
+        """
+        If p_inverter is provided, set inverter_parameters['pdc0'] accordingly.
+
+        Raises:
+            ValueError: If both p_inverter and inverter_parameters['pdc0'] are provided.
+        """
+        p_inverter = self.p_inverter
+        inv_params: dict[str, Any] = self.inverter_parameters or {}  # type: ignore
+
+        # choose policy: reject or overwrite if user also sent pdc0
+        if "pdc0" in inv_params:
+            if inv_params["pdc0"] != p_inverter / self.inverter_efficiency:
+                raise ValueError("Provide either 'pac' or 'inverter_parameters.pdc0', not both.")
+            return self
+
+        inv_params = dict(inv_params)  # avoid mutating shared defaults
+        inv_params["pdc0"] = p_inverter / self.inverter_efficiency
+        object.__setattr__(self, "inverter_parameters", inv_params)
+        return self
+
+    @model_validator(mode="after")
+    def _p_module_to_module_parameters(self):
+        """
+        Set module_parameters['pdc0'] to the value of p_module.
+        """
+        p_module = self.p_module
+        mod_params: dict[str, float] = self.module_parameters
+        mod_params = dict(mod_params)  # avoid mutating shared defaults
+        mod_params["pdc0"] = p_module
+        object.__setattr__(self, "module_parameters", mod_params)
+        return self
+
+    @model_validator(mode="after")
+    def _push_settings_to_arrays(self):
+        """
+        If settings are specified for the entire system, but not per array,
+        and there are arrays defined, push the settings to each array.
+        """
+        if hasattr(self, "arrays") and self.arrays is not None:  # type: ignore
+            for array in self.arrays:  # type: ignore
+                if not array.module_parameters:
+                    object.__setattr__(array, "module_parameters", self.module_parameters)
+                if not array.module_type:
+                    object.__setattr__(array, "module_type", self.module_type)
+                if not array.mount.racking_model:
+                    object.__setattr__(array.mount, "racking_model", self.racking_model)
+        return self
+
+
+class QuickScanModelChainModel(ModelChainModel):
+    """
+    ModelChain model for quick PV simulation setup using QuickPVSystemModel.
+
+    Sets default AOI and DC models for PVWatts.
+    """
+
+    type: Literal["quickscan"] = Field("quickscan", frozen=True)  # tag
+    system: QuickPVSystemModel
+    aoi_model: str = "physical"
+    dc_model: str = "pvwatts"

openenergyid/pvsim/pvlib/weather.py

@@ -0,0 +1,91 @@
+"""
+Weather data utilities for PV simulation.
+
+Provides functions to retrieve and process weather data for PV simulations,
+including timezone-aware handling and leap year adjustments.
+"""
+
+import datetime as dt
+import typing
+
+import pandas as pd
+import pvlib
+
+
+def get_utc_offset_on_1_jan(timezone: str) -> int:
+    """
+    Get the UTC offset in hours for the given timezone on January 1st.
+
+    Args:
+        timezone: The timezone string (e.g., "Europe/Amsterdam").
+
+    Returns:
+        The UTC offset in hours as an integer.
+
+    Raises:
+        ValueError: If the UTC offset cannot be determined.
+    """
+    jan_first = pd.Timestamp("2020-01-01 00:00:00", tz=timezone)
+    utc_offset = jan_first.utcoffset()
+    if utc_offset is None:
+        raise ValueError(f"Could not determine UTC offset for timezone {timezone}")
+    return int(utc_offset.total_seconds() / 3600)
+
+
+def get_weather(
+    latitude: float, longitude: float, start: dt.date, end: dt.date, tz: str
+) -> pd.DataFrame:
+    """
+    Retrieve and process weather data for the specified location and date range.
+
+    Downloads a "normal year" TMY dataset from PVGIS, aligns it to the requested
+    date range and timezone, and handles leap year adjustments.
+
+    Args:
+        latitude: Latitude of the location.
+        longitude: Longitude of the location.
+        start: Start date (inclusive).
+        end: End date (exclusive).
+        tz: Timezone string.
+
+    Returns:
+        A pandas DataFrame indexed by timestamp with weather data.
+    """
+    # Get a "normal year" from pvgis, it will be indexed in 1990
+    utc_offset = get_utc_offset_on_1_jan(tz)
+    weather = pvlib.iotools.get_pvgis_tmy(
+        latitude=latitude, longitude=longitude, roll_utc_offset=utc_offset
+    )[0]
+    weather = typing.cast(pd.DataFrame, weather)
+    weather = weather.tz_convert(tz)
+    weather.index.name = None
+
+    # Check if 29 februari is included in the weather data
+    weather_index = typing.cast(pd.DatetimeIndex, weather.index)
+    leap_included = "02-29" in weather_index.strftime("%m-%d").unique()
+
+    # Construct our desired index
+    new_index = pd.date_range(start, end, freq="15min", tz=tz)
+    temp_df = pd.DataFrame(index=new_index)
+    # Add a key that doesn't contain year
+    temp_df["tkey"] = new_index.tz_convert("UTC").strftime("%m-%dT%H:%M:%S%z")
+    temp_df["timestamp"] = new_index
+    if not leap_included:
+        # Replace all tkey's starting with "02-29" with "02-28"
+        temp_df.loc[temp_df.tkey.str.startswith("02-29"), "tkey"] = temp_df.loc[
+            temp_df.tkey.str.startswith("02-29"), "tkey"
+        ].str.replace("02-29", "02-28")
+
+    # Add the key to the weather frame and join
+    weather["tkey"] = weather_index.tz_convert("UTC").strftime("%m-%dT%H:%M:%S%z")
+    df = (
+        pd.merge(temp_df, weather, on="tkey", how="left")
+        .set_index("timestamp")
+        .drop(columns=["tkey"])
+    )
+
+    # Interpolate and drop last value
+    df = df.interpolate(method="time")
+    df = df.iloc[:-1]
+
+    return df

openenergyid/sim/__init__.py

@@ -0,0 +1,5 @@
+"""Main Simulation Package that can handle every simulation."""
+
+from .main import ExAnteData, FullSimulationInput, run_simulation
+
+__all__ = ["FullSimulationInput", "run_simulation", "ExAnteData"]

openenergyid/sim/main.py

@@ -0,0 +1,67 @@
+"""Generic Simulation Analysis Module."""
+
+from typing import Annotated, Union
+
+import aiohttp
+from pydantic import BaseModel, Field
+
+from ..abstractsim import SimulationSummary, Simulator
+from ..pvsim import PVSimulationInput, apply_simulation
+from ..pvsim import get_simulator as get_pv_simulator
+from ..simeval import EvaluationInput, compare_results, evaluate
+from ..simeval.models import Frequency
+
+# Here we define all types of simulations
+SimulationInput = Annotated[Union[PVSimulationInput], Field(discriminator="type")]
+
+
+def get_simulator(input_: SimulationInput) -> Simulator:
+    """Get an instance of the simulator based on the input data."""
+    # Only PV simulators for now
+    return get_pv_simulator(input_)
+
+
+class ExAnteData(EvaluationInput):
+    """Ex-ante data for simulation analysis."""
+
+
+class FullSimulationInput(BaseModel):
+    """Full input for running a simulation analysis."""
+
+    ex_ante_data: ExAnteData
+    simulation_parameters: SimulationInput
+    timezone: str = "Europe/Brussels"
+    return_frequencies: list[Frequency] | None = Field(
+        default=None,
+        examples=["MS", "W-MON"],
+        description="Optional list of frequencies that should be included in the analysis. Be default, only `total` is included, but you can add more here. Uses the Pandas freqstr.",
+    )
+
+
+async def run_simulation(
+    input_: FullSimulationInput, session: aiohttp.ClientSession
+) -> SimulationSummary:
+    """Run the full simulation analysis workflow."""
+    df = input_.ex_ante_data.to_pandas(timezone=input_.timezone)
+
+    ex_ante_eval = evaluate(df, return_frequencies=input_.return_frequencies)
+
+    simulator: Simulator = get_simulator(input_.simulation_parameters)
+    await simulator.load_resources(session=session)
+
+    sim_eval = evaluate(simulator.result_as_frame(), return_frequencies=input_.return_frequencies)
+
+    df_post = apply_simulation(df, simulator.simulation_results)
+
+    post_eval = evaluate(df_post, return_frequencies=input_.return_frequencies)
+
+    comparison = compare_results(ex_ante_eval, post_eval)
+
+    summary = SimulationSummary.from_simulation(
+        ex_ante=ex_ante_eval,
+        simulation_result=sim_eval,
+        ex_post=post_eval,
+        comparison=comparison,
+    )
+
+    return summary

openenergyid/simeval/__init__.py

@@ -0,0 +1,6 @@
+"""Module containing basic evaluation functions for energy systems."""
+
+from .main import compare_results, evaluate
+from .models import EvaluationInput, EvaluationOutput
+
+__all__ = ["EvaluationInput", "EvaluationOutput", "evaluate", "compare_results"]