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

openenergyid/__init__.py

@@ -1,6 +1,6 @@
 """Open Energy ID Python SDK."""
 
-__version__ = "0.1.28"
+__version__ = "0.1.30"
 
 from .enums import Granularity
 from .models import TimeDataFrame, TimeSeries

openenergyid/abstractsim/__init__.py

@@ -0,0 +1,5 @@
+"""Module with abstract definitions that ALL SIMULATIONS should adhere to."""
+
+from .abstract import SimulationInputAbstract, SimulationSummary, Simulator
+
+__all__ = ["SimulationInputAbstract", "SimulationSummary", "Simulator"]

openenergyid/abstractsim/abstract.py

@@ -0,0 +1,102 @@
+from abc import ABC, abstractmethod
+from typing import Annotated, Self
+
+import pandas as pd
+from aiohttp import ClientSession
+from pydantic import BaseModel, Field
+
+from ..simeval.models import ComparisonPayload, EvalPayload, EvaluationOutput
+
+
+class SimulationInputAbstract(BaseModel):
+    """Abstract input parameters for any Simulation"""
+
+    type: str
+
+
+class SimulationSummary(BaseModel):
+    """Summary of a simulation including ex-ante, simulation results, ex-post, and comparisons."""
+
+    ex_ante: Annotated[EvalPayload, Field(description="Ex-ante evaluation results.")]
+    simulation_result: Annotated[EvalPayload, Field(description="Simulation results.")]
+    ex_post: Annotated[EvalPayload, Field(description="Ex-post evaluation results.")]
+    comparison: Annotated[
+        ComparisonPayload, Field(description="Comparison between ex-ante and ex-post results.")
+    ]
+
+    @classmethod
+    def from_simulation(
+        cls,
+        ex_ante: dict[str, pd.DataFrame | pd.Series],
+        simulation_result: dict[str, pd.DataFrame | pd.Series],
+        ex_post: dict[str, pd.DataFrame | pd.Series],
+        comparison: dict[str, dict[str, pd.DataFrame | pd.Series]],
+    ) -> Self:
+        """Create a SimulationSummary from simulation data."""
+        ea = {
+            k: EvaluationOutput.from_pandas(v) if isinstance(v, pd.DataFrame) else v.to_dict()
+            for k, v in ex_ante.items()
+        }
+        sr = {
+            k: EvaluationOutput.from_pandas(v) if isinstance(v, pd.DataFrame) else v.to_dict()
+            for k, v in simulation_result.items()
+        }
+        ep = {
+            k: EvaluationOutput.from_pandas(v) if isinstance(v, pd.DataFrame) else v.to_dict()
+            for k, v in ex_post.items()
+        }
+        c = {
+            k: {
+                kk: EvaluationOutput.from_pandas(vv)
+                if isinstance(vv, pd.DataFrame)
+                else vv.to_dict()
+                for kk, vv in v.items()
+            }
+            for k, v in comparison.items()
+        }
+        return cls(
+            ex_ante=ea,  # type: ignore
+            simulation_result=sr,  # type: ignore
+            ex_post=ep,  # type: ignore
+            comparison=c,  # type: ignore
+        )
+
+
+class Simulator(ABC):
+    """
+    An abstract base class simulators.
+    """
+
+    @property
+    @abstractmethod
+    def simulation_results(self):
+        """The results of the simulation."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def simulate(self, **kwargs):
+        """
+        Run the simulation and return the results.
+        """
+        raise NotImplementedError()
+
+    @abstractmethod
+    def result_as_frame(self) -> pd.DataFrame:
+        """
+        Convert the simulation results to a DataFrame.
+        """
+        raise NotImplementedError()
+
+    @classmethod
+    def from_pydantic(cls, input_: SimulationInputAbstract) -> Self:
+        """
+        Create an instance of the simulator from Pydantic input data.
+        """
+        return cls(**input_.model_dump())
+
+    @abstractmethod
+    async def load_resources(self, session: ClientSession) -> None:
+        """
+        Asynchronously load any required resources using the provided session.
+        """
+        raise NotImplementedError()

openenergyid/baseload/__init__.py

@@ -1,8 +1,8 @@
 """Baseload analysis package for power consumption data."""
 
-from .models import PowerReadingSchema, PowerSeriesSchema, BaseloadResultSchema
 from .analysis import BaseloadAnalyzer
 from .exceptions import InsufficientDataError, InvalidDataError
+from .models import BaseloadResultSchema, PowerReadingSchema, PowerSeriesSchema
 
 __version__ = "0.1.0"
 __all__ = [

openenergyid/capacity/__init__.py

@@ -1,6 +1,6 @@
 """Power Offtake peak analysis module."""
 
-from .models import CapacityInput, CapacityOutput, PeakDetail
 from .main import CapacityAnalysis
+from .models import CapacityInput, CapacityOutput, PeakDetail
 
 __all__ = ["CapacityInput", "CapacityAnalysis", "CapacityOutput", "PeakDetail"]

openenergyid/capacity/main.py

@@ -2,6 +2,7 @@
 
 import datetime as dt
 import typing
+
 import pandas as pd
 import pandera.typing as pdt
 

openenergyid/capacity/models.py

@@ -1,7 +1,9 @@
 """Model for Capacity Analysis."""
 
 import datetime as dt
+
 from pydantic import BaseModel, ConfigDict, Field
+
 from openenergyid.models import TimeSeries
 
 

openenergyid/const.py

@@ -7,6 +7,8 @@ from typing import Literal
 ELECTRICITY_DELIVERED: Literal["electricity_delivered"] = "electricity_delivered"
 ELECTRICITY_EXPORTED: Literal["electricity_exported"] = "electricity_exported"
 ELECTRICITY_PRODUCED: Literal["electricity_produced"] = "electricity_produced"
+ELECTRICITY_CONSUMED: Literal["electricity_consumed"] = "electricity_consumed"
+ELECTRICITY_SELF_CONSUMED: Literal["electricity_self_consumed"] = "electricity_self_consumed"
 
 PRICE_DAY_AHEAD: Literal["price_day_ahead"] = "price_day_ahead"
 PRICE_IMBALANCE_UPWARD: Literal["price_imbalance_upward"] = "price_imbalance_upward"
@@ -16,3 +18,12 @@ PRICE_ELECTRICITY_EXPORTED: Literal["price_electricity_exported"] = "price_elect
 
 RLP: Literal["RLP"] = "RLP"
 SPP: Literal["SPP"] = "SPP"
+
+COST_ELECTRICITY_DELIVERED: Literal["cost_electricity_delivered"] = "cost_electricity_delivered"
+EARNINGS_ELECTRICITY_EXPORTED: Literal["earnings_electricity_exported"] = (
+    "earnings_electricity_exported"
+)
+COST_ELECTRICITY_NET: Literal["cost_electricity_net"] = "cost_electricity_net"
+
+RATIO_SELF_CONSUMPTION: Literal["ratio_self_consumption"] = "ratio_self_consumption"
+RATIO_SELF_SUFFICIENCY: Literal["ratio_self_sufficiency"] = "ratio_self_sufficiency"

openenergyid/dyntar/main.py

@@ -1,6 +1,7 @@
 """Main module of the DynTar package."""
 
 from typing import cast
+
 import pandas as pd
 
 from openenergyid.const import (
@@ -13,22 +14,22 @@ from openenergyid.const import (
 )
 
 from .const import (
-    ELECTRICITY_DELIVERED_SMR3,
-    ELECTRICITY_EXPORTED_SMR3,
-    ELECTRICITY_DELIVERED_SMR2,
-    ELECTRICITY_EXPORTED_SMR2,
     COST_ELECTRICITY_DELIVERED_SMR2,
-    COST_ELECTRICITY_EXPORTED_SMR2,
     COST_ELECTRICITY_DELIVERED_SMR3,
+    COST_ELECTRICITY_EXPORTED_SMR2,
     COST_ELECTRICITY_EXPORTED_SMR3,
-    RLP_WEIGHTED_PRICE_DELIVERED,
-    SPP_WEIGHTED_PRICE_EXPORTED,
+    ELECTRICITY_DELIVERED_SMR2,
+    ELECTRICITY_DELIVERED_SMR3,
+    ELECTRICITY_EXPORTED_SMR2,
+    ELECTRICITY_EXPORTED_SMR3,
     HEATMAP_DELIVERED,
-    HEATMAP_EXPORTED,
-    HEATMAP_TOTAL,
     HEATMAP_DELIVERED_DESCRIPTION,
+    HEATMAP_EXPORTED,
     HEATMAP_EXPORTED_DESCRIPTION,
+    HEATMAP_TOTAL,
     HEATMAP_TOTAL_DESCRIPTION,
+    RLP_WEIGHTED_PRICE_DELIVERED,
+    SPP_WEIGHTED_PRICE_EXPORTED,
     Register,
 )
 

openenergyid/dyntar/models.py

@@ -1,11 +1,12 @@
 """Models for dynamic tariff analysis."""
 
 from typing import Literal
-from pydantic import Field, conlist, confloat, BaseModel
+
+from pydantic import BaseModel, Field, confloat, conlist
 
 from openenergyid.models import TimeDataFrame
-from .const import Register
 
+from .const import Register
 
 RequiredColumns = Literal[
     "electricity_delivered",

openenergyid/elia/__init__.py

@@ -0,0 +1,4 @@
+from .api import get_dataset, parse_response
+from .const import Region
+
+__all__ = ["get_dataset", "parse_response", "Region"]

openenergyid/elia/api.py

@@ -0,0 +1,91 @@
+"""
+This module contains the functions to interact with the Elia API.
+"""
+
+import datetime as dt
+
+import aiohttp
+import pandas as pd
+
+from .const import Region
+
+DATE_FORMAT = "%Y-%m-%d"
+
+
+async def get_dataset(
+    dataset: str,
+    start: dt.date,
+    end: dt.date,
+    region: Region,
+    select: set[str],
+    session: aiohttp.ClientSession,
+    timezone: str = "Europe/Brussels",
+) -> dict:
+    """
+    Fetches a dataset from the Elia open data API within a specified date range and region.
+
+    Args:
+        dataset (str): The name of the dataset to fetch.
+        start (dt.date): The start date for the data range.
+        end (dt.date): The end date for the data range.
+        region (Region): The region for which to fetch the data.
+        select (set[str]): A set of fields to select in the dataset.
+        session (aiohttp.ClientSession): The aiohttp session to use for making the request.
+        timezone (str, optional): The timezone to use for the data. Defaults to "Europe/Brussels".
+
+    Returns:
+        dict: The dataset fetched from the API.
+
+    Raises:
+        aiohttp.ClientError: If there is an error making the request.
+    """
+    url = f"https://opendata.elia.be/api/explore/v2.1/catalog/datasets/{dataset}/exports/json"
+
+    if "datetime" not in select:
+        select.add("datetime")
+    select_str = ",".join(select)
+
+    params = {
+        "where": (
+            f"datetime IN [date'{start.strftime(DATE_FORMAT)}'..date'{end.strftime(DATE_FORMAT)}'] "
+            f"AND region='{region.value}'"
+        ),
+        "timezone": timezone,
+        "select": select_str,
+    }
+
+    async with session.get(url, params=params) as response:
+        data = await response.json()
+
+    return data
+
+
+def parse_response(
+    data: dict, index: str, columns: list[str], timezone: str = "Europe/Brussels"
+) -> pd.DataFrame:
+    """
+    Parses a response dictionary into a pandas DataFrame.
+
+    Args:
+        data (dict): The input data where each key is a column name
+            and each value is a list of column values.
+        index (str): The key in the data dictionary to be used as the index for the DataFrame.
+        columns (list[str]): The list of column names for the DataFrame.
+        timezone (str, optional): The timezone to convert the DataFrame index to.
+            Defaults to "Europe/Brussels".
+
+    Returns:
+        pd.DataFrame: A pandas DataFrame with the specified columns and index,
+            converted to the specified timezone.
+    """
+    df = pd.DataFrame(
+        data,
+        index=pd.to_datetime([x[index] for x in data], utc=True),
+        columns=columns,
+    )
+    df.index = pd.DatetimeIndex(df.index)
+    df = df.tz_convert(timezone)
+    df.sort_index(inplace=True)
+    df.dropna(inplace=True)
+
+    return df

openenergyid/elia/const.py

@@ -0,0 +1,18 @@
+from enum import Enum
+
+
+class Region(Enum):
+    Belgium = "Belgium"
+    Brussels = "Brussels"
+    Flanders = "Flanders"
+    Wallonia = "Wallonia"
+    Antwerp = "Antwerp"
+    East_Flanders = "East-Flanders"
+    Flemish_Brabant = "Flemish-Brabant"
+    Limburg = "Limburg"
+    West_Flanders = "West-Flanders"
+    Hainaut = "Hainaut"
+    Liège = "Liège"
+    Luxembourg = "Luxembourg"
+    Namur = "Namur"
+    Walloon_Brabant = "Walloon-Brabant"

openenergyid/energysharing/data_formatting.py

@@ -1,7 +1,15 @@
 """Functions to create multi-indexed DataFrames for input and output data for energy sharing."""
 
 import pandas as pd
-from .const import GROSS_INJECTION, GROSS_OFFTAKE, KEY, NET_INJECTION, NET_OFFTAKE, SHARED_ENERGY
+
+from .const import (
+    GROSS_INJECTION,
+    GROSS_OFFTAKE,
+    KEY,
+    NET_INJECTION,
+    NET_OFFTAKE,
+    SHARED_ENERGY,
+)
 
 
 def create_multi_index_input_frame(

openenergyid/energysharing/main.py

@@ -1,9 +1,20 @@
 """Main Calcuation Module for Energy Sharing."""
 
 import pandas as pd
+
+from .const import (
+    GROSS_INJECTION,
+    GROSS_OFFTAKE,
+    KEY,
+    NET_INJECTION,
+    NET_OFFTAKE,
+    SHARED_ENERGY,
+)
+from .data_formatting import (
+    create_multi_index_output_frame,
+    result_to_input_for_reiteration,
+)
 from .models import CalculationMethod
-from .const import GROSS_INJECTION, GROSS_OFFTAKE, KEY, NET_INJECTION, NET_OFFTAKE, SHARED_ENERGY
-from .data_formatting import create_multi_index_output_frame, result_to_input_for_reiteration
 
 
 def _calculate(df: pd.DataFrame, method: CalculationMethod) -> pd.DataFrame:

openenergyid/energysharing/models.py

@@ -3,12 +3,13 @@
 from enum import Enum
 from typing import Annotated, Any
 
-from pydantic import BaseModel, Field, confloat
 import pandas as pd
+from pydantic import BaseModel, Field, confloat
 
 from openenergyid import TimeDataFrame
-from .data_formatting import create_multi_index_input_frame
+
 from .const import NET_INJECTION, NET_OFFTAKE, SHARED_ENERGY
+from .data_formatting import create_multi_index_input_frame
 
 
 class CalculationMethod(Enum):

openenergyid/models.py

@@ -1,13 +1,11 @@
 """Data models for the Open Energy ID."""
 
 import datetime as dt
-from typing import overload
-
-from typing import Self
+from typing import Self, overload
 
 import pandas as pd
-from pydantic import BaseModel
 import polars as pl
+from pydantic import BaseModel
 
 
 class TimeSeriesBase(BaseModel):
@@ -62,6 +60,14 @@ class TimeSeriesBase(BaseModel):
                 return cls.model_validate_json(file.read(), **kwargs)
         raise ValueError("Either string or path must be provided.")
 
+    def first_timestamp(self) -> dt.datetime:
+        """Get the first timestamp in the index."""
+        return min(self.index)
+
+    def last_timestamp(self) -> dt.datetime:
+        """Get the last timestamp in the index."""
+        return max(self.index)
+
 
 class TimeSeries(TimeSeriesBase):
     """

openenergyid/mvlr/__init__.py

@@ -3,10 +3,10 @@
 from .main import find_best_mvlr
 from .models import (
     IndependentVariableInput,
+    IndependentVariableResult,
     MultiVariableRegressionInput,
     MultiVariableRegressionResult,
     ValidationParameters,
-    IndependentVariableResult,
 )
 
 __all__ = [

openenergyid/mvlr/main.py

@@ -1,7 +1,7 @@
 """Main module for the MultiVariableLinearRegression class."""
 
-from .models import MultiVariableRegressionInput, MultiVariableRegressionResult
 from .helpers import resample_input_data
+from .models import MultiVariableRegressionInput, MultiVariableRegressionResult
 from .mvlr import MultiVariableLinearRegression
 
 

openenergyid/mvlr/models.py

@@ -1,17 +1,16 @@
 """Models for multivariable linear regression."""
 
 from typing import Any
-import pandas as pd
 
-from pydantic import BaseModel, Field, ConfigDict
+import pandas as pd
 import statsmodels.formula.api as fm
+from pydantic import BaseModel, ConfigDict, Field
 
 from openenergyid.enums import Granularity
 from openenergyid.models import TimeDataFrame
 
 from .mvlr import MultiVariableLinearRegression
 
-
 COLUMN_TEMPERATUREEQUIVALENT = "temperatureEquivalent"
 
 

openenergyid/pvsim/__init__.py

@@ -0,0 +1,8 @@
+from .main import (
+    PVSimulationInput,
+    PVSimulationSummary,
+    apply_simulation,
+    get_simulator,
+)
+
+__all__ = ["PVSimulationInput", "get_simulator", "apply_simulation", "PVSimulationSummary"]

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,
+        )