openenergyid 0.1.31__py3-none-any.whl

openenergyid/pvsim/abstract.py

@@ -0,0 +1,60 @@
+"""
+This module contains the abstract base class for PVSimulator.
+"""
+
+import datetime as dt
+from abc import ABC
+from typing import cast
+
+import pandas as pd
+from pydantic import Field
+
+from openenergyid.models import TimeSeries
+
+from ..abstractsim import SimulationInputAbstract, Simulator
+from ..const import ELECTRICITY_PRODUCED
+
+
+class PVSimulationInputAbstract(SimulationInputAbstract):
+    """
+    Input parameters for the PV simulation.
+    """
+
+    start: dt.date
+    end: dt.date
+    result_resolution: str = Field(
+        "15min",
+        description="Resolution of the simulation results",
+        examples=["15min", "1h", "D", "MS"],
+    )
+
+
+class PVSimulator(Simulator, ABC):
+    """
+    An abstract base class for PV simulators.
+    """
+
+    def __init__(self, result_resolution: str = "15min", **kwargs) -> None:
+        self._simulation_results: pd.Series | None = None
+        self.result_resolution = result_resolution
+
+    @property
+    def simulation_results(self) -> pd.Series:
+        """The results of the simulation."""
+        if self._simulation_results is None:
+            results = self.simulate()
+            self._simulation_results = cast(pd.Series, results)
+        return self._simulation_results
+
+    def result_to_timeseries(self):
+        """
+        Convert the simulation results to a TimeSeries object.
+        """
+        result = self.simulation_results.resample(self.result_resolution).sum()
+        return TimeSeries.from_pandas(result)
+
+    def result_as_frame(self) -> pd.DataFrame:
+        """
+        Convert the simulation results to a DataFrame.
+        """
+        return self.simulation_results.rename(ELECTRICITY_PRODUCED).to_frame()

openenergyid/pvsim/elia/__init__.py

@@ -0,0 +1,3 @@
+from .main import EliaPVSimulationInput, EliaPVSimulator
+
+__all__ = ["EliaPVSimulationInput", "EliaPVSimulator"]

openenergyid/pvsim/elia/main.py

@@ -0,0 +1,89 @@
+"""
+This module contains the LoadFactorPVSimulator class which
+simulates the power output of a PV system based on load factors.
+"""
+
+import datetime as dt
+from typing import Literal
+
+import aiohttp
+import pandas as pd
+from pydantic import Field
+
+from openenergyid import elia
+from openenergyid.pvsim.abstract import PVSimulationInputAbstract, PVSimulator
+
+
+class EliaPVSimulationInput(PVSimulationInputAbstract):
+    """Input parameters for the Elia PV simulation."""
+
+    type: Literal["eliapvsimulation"] = Field("eliapvsimulation", frozen=True)  # tag
+    region: elia.Region
+    panel_power: float = Field(..., gt=0, description="Installed panel power in W")
+    inverter_power: float = Field(..., gt=0, description="Installed inverter power in W")
+
+
+class EliaPVSimulator(PVSimulator):
+    """
+    A PV simulator that simulates the power output of a PV system based on load factors.
+    """
+
+    def __init__(
+        self,
+        start: dt.date,
+        end: dt.date,
+        panel_power: float,
+        inverter_power: float,
+        region: elia.Region,
+        load_factors: pd.Series | None = None,
+        **kwargs,
+    ):
+        self.start = start
+        self.end = end
+        self.panel_power = panel_power / 1000  # convert to kW
+        self.inverter_power = inverter_power / 1000  # convert to kW
+        self.region = region
+        self.load_factors = load_factors if load_factors is not None else pd.Series(dtype=float)
+
+        super().__init__(**kwargs)
+
+    def simulate(self, **kwargs) -> pd.Series:
+        """Run the simulation."""
+        result = self.load_factors * self.panel_power * 0.01
+        result.clip(upper=self.inverter_power, inplace=True)
+        result = result * 0.25  # To Energy
+        result.name = None
+        return result
+
+    @staticmethod
+    async def download_load_factors(
+        start: dt.date,
+        end: dt.date,
+        region: elia.Region,
+        session: aiohttp.ClientSession,
+    ) -> pd.Series:
+        """Download load factors from the API."""
+        pv_load_factor_json = await elia.get_dataset(
+            dataset="ods032",
+            start=start,
+            end=end,
+            region=region,
+            select={"loadfactor"},
+            session=session,
+        )
+        pv_load_factors = elia.parse_response(
+            data=pv_load_factor_json, index="datetime", columns=["loadfactor"]
+        )["loadfactor"]
+        pv_load_factors = pv_load_factors.truncate(
+            after=pd.Timestamp(end, tz="Europe/Brussels") - pd.Timedelta(minutes=15)
+        )
+        return pv_load_factors
+
+    async def load_resources(self, session: aiohttp.ClientSession) -> None:
+        """Load resources required for the simulation."""
+        self.load_factors = await self.download_load_factors(
+            start=self.start,
+            end=self.end,
+            region=self.region,
+            session=session,
+        )

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"