openenergyid 0.1.28__tar.gz → 0.1.30__tar.gz

openenergyid-0.1.30/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: openenergyid
+Version: 0.1.30
+Summary: Open Source Python library for energy analytics and simulations
+Author-email: Jan Pecinovsky <jan@energieid.be>, Max Helskens <max@energieid.be>, Oscar Swyns <oscar@energieid.be>
+License-Expression: MIT
+Keywords: energy,analytics,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.12.15
+Requires-Dist: pandera[polars]>=0.22.1
+Requires-Dist: pvlib>=0.13.0
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: statsmodels>=0.14.2
+Dynamic: license-file
+
+# OpenEnergyID
+
+Open Source Python library for energy data analytics and simulations
+
+[*more info for developers*](DEVELOPERS.md)

{openenergyid-0.1.28 → openenergyid-0.1.30}/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-0.1.30/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-0.1.30/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-0.1.28 → openenergyid-0.1.30}/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-0.1.28 → openenergyid-0.1.30}/openenergyid/baseload/analysis.py

@@ -163,11 +163,13 @@ class BaseloadAnalyzer:
                         pl.col("total_consumption_in_kilowatthour")
                         - pl.col("consumption_due_to_baseload_in_kilowatthour")
                     ).alias("consumption_not_due_to_baseload_in_kilowatthour"),
-                    # What fraction of total energy was from baseload
-                    (
+                    pl.when(pl.col("total_consumption_in_kilowatthour") != 0)
+                    .then(
                         pl.col("consumption_due_to_baseload_in_kilowatthour")
                         / pl.col("total_consumption_in_kilowatthour")
-                    ).alias("baseload_ratio"),
+                    )
+                    .otherwise(None)
+                    .alias("baseload_ratio"),
                 ]
             )
         )

{openenergyid-0.1.28 → openenergyid-0.1.30}/openenergyid/capacity/main.py

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

{openenergyid-0.1.28 → openenergyid-0.1.30}/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-0.1.28 → openenergyid-0.1.30}/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-0.1.28 → openenergyid-0.1.30}/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-0.1.28 → openenergyid-0.1.30}/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",
@@ -95,16 +96,6 @@ class DynamicTariffAnalysisOutputSummary(BaseModel):
 class DynamicTariffAnalysisOutput(TimeDataFrame):
     """Output frame for dynamic tariff analysis."""
 
-    columns: list[OutputColumns] = Field(
-        min_length=1,
-        max_length=len(OutputColumns.__args__),
-        examples=[OutputColumns.__args__],
-    )
-    data: list[
-        conlist(
-            item_type=confloat(allow_inf_nan=True),
-            min_length=1,
-            max_length=len(OutputColumns.__args__),
-        )  # type: ignore
-    ] = Field(examples=[[0.0] * len(OutputColumns.__args__)])
+    columns: list[str]
+    data: list[list[float | None]]
     summary: DynamicTariffAnalysisOutputSummary | None = None

openenergyid-0.1.30/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-0.1.30/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-0.1.30/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-0.1.28 → openenergyid-0.1.30}/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-0.1.28 → openenergyid-0.1.30}/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-0.1.28 → openenergyid-0.1.30}/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-0.1.28 → openenergyid-0.1.30}/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):
     """
@@ -88,7 +94,11 @@ class TimeSeries(TimeSeriesBase):
     @classmethod
     def from_pandas(cls, data: pd.Series) -> Self:
         """Create from a Pandas Series."""
-        return cls(name=str(data.name), data=data.tolist(), index=data.index.tolist())
+        if not hasattr(data, "name") or data.name is None:
+            name = None
+        else:
+            name = str(data.name)
+        return cls(name=name, data=data.tolist(), index=data.index.tolist())
 
     def to_pandas(self, timezone: str = "UTC") -> pd.Series:
         """Convert to a Pandas Series."""

{openenergyid-0.1.28 → openenergyid-0.1.30}/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-0.1.28 → openenergyid-0.1.30}/openenergyid/mvlr/mvlr.py

@@ -206,9 +206,9 @@ class MultiVariableLinearRegression:
 
     def _do_analysis_cross_validation(self):
         """Find the best model (fit) based on cross-valiation (leave one out)"""
-        assert (
-            len(self.data) < 15
-        ), "Cross-validation is not implemented if your sample contains more than 15 datapoints"
+        assert len(self.data) < 15, (
+            "Cross-validation is not implemented if your sample contains more than 15 datapoints"
+        )
 
         # initialization: first model is the mean, but compute cv correctly.
         errors = []

openenergyid-0.1.30/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-0.1.30/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-0.1.30/openenergyid/pvsim/elia/__init__.py

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