Enhance energy simulation evaluation and modeling

- Added methods to retrieve the first and last timestamps in TimeSeriesBase.
- Implemented a new function `apply_simulation` to apply simulation results to input data in the PV simulation module.
- Updated the PVSimulator class to include a method for converting simulation results to a DataFrame.
- Enhanced the evaluation module with a new function `compare_results` to compare two evaluation results and return differences.
- Modified the `evaluate` method to handle missing columns for electricity delivered and exported.
- Updated imports in various modules to include new functions and classes as needed.
- Adjusted execution counts in the demo notebook to reflect the new evaluation and simulation processes.

Author: Jan Pecinovsky

demo_simeval.ipynb

@@ -60,6 +60,14 @@ def from_json(cls, string: str | None = None, path: str | None = None, **kwargs)
                 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/models.py

@@ -1,3 +1,3 @@
-from .main import PVSimulationInput, get_simulator
+from .main import PVSimulationInput, apply_simulation, get_simulator
 
-__all__ = ["PVSimulationInput", "get_simulator"]
+__all__ = ["PVSimulationInput", "get_simulator", "apply_simulation"]

openenergyid/pvsim/__init__.py

@@ -4,14 +4,16 @@
 
 import datetime as dt
 from abc import ABC, abstractmethod
-from typing import cast
+from typing import Self, cast
 
 import pandas as pd
 from aiohttp import ClientSession
 from pydantic import BaseModel, Field
 
 from openenergyid.models import TimeSeries
 
+from ..const import ELECTRICITY_PRODUCED
+
 
 class PVSimulationInputAbstract(BaseModel):
     """
@@ -59,8 +61,14 @@ def result_to_timeseries(self):
         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()
+
     @classmethod
-    def from_pydantic(cls, input_: PVSimulationInputAbstract) -> "PVSimulator":
+    def from_pydantic(cls, input_: PVSimulationInputAbstract) -> Self:
         """
         Create an instance of the simulator from Pydantic input data.
         """

openenergyid/pvsim/abstract.py

@@ -1,5 +1,6 @@
 from typing import Annotated, Union
 
+import pandas as pd
 from pydantic import Field
 
 from .elia import EliaPVSimulationInput, EliaPVSimulator
@@ -17,3 +18,24 @@ def get_simulator(input_: PVSimulationInput) -> PVLibSimulator | EliaPVSimulator
     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/main.py

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

openenergyid/simeval/__init__.py

@@ -1,5 +1,7 @@
 """Module for evaluating energy simulation data."""
 
+import typing
+
 import numpy as np
 import pandas as pd
 
@@ -39,6 +41,8 @@ def __init__(self, data: pd.DataFrame, return_frequencies: list[str] | None = No
 
     def evaluate(self) -> dict[str, pd.DataFrame | pd.Series]:
         """Evaluate the data and return resampled results."""
+        if const.ELECTRICITY_DELIVERED not in self.data.columns:
+            self.data[const.ELECTRICITY_DELIVERED] = float("NaN")
         if const.ELECTRICITY_EXPORTED not in self.data.columns:
             self.data[const.ELECTRICITY_EXPORTED] = float("NaN")
         if const.ELECTRICITY_PRODUCED not in self.data.columns:
@@ -122,3 +126,23 @@ def evaluate(self) -> dict[str, pd.DataFrame | pd.Series]:
                     frame[const.ELECTRICITY_CONSUMED],
                 )
         return results
+
+
+def compare_results(
+    res_1: dict[str, pd.DataFrame | pd.Series], res_2: dict[str, pd.DataFrame | pd.Series]
+) -> dict[str, dict[str, pd.Series | pd.DataFrame]]:
+    """Compare two evaluation results and return the differences."""
+    results = {}
+    for key in res_1.keys():
+        if key in res_2:
+            df_1 = res_1[key]
+            df_2 = res_2[key]
+            if isinstance(df_1, pd.Series) and isinstance(df_2, pd.Series):
+                df_1 = df_1.to_frame().T
+                df_2 = df_2.to_frame().T
+            df_1, df_2 = typing.cast(pd.DataFrame, df_1), typing.cast(pd.DataFrame, df_2)
+            diff = df_2 - df_1
+            results[key] = {}
+            results[key]["diff"] = diff.dropna(how="all", axis=1).squeeze(axis=0)
+            results[key]["ratio_diff"] = (diff / df_1).dropna(how="all", axis=1).squeeze(axis=0)
+    return results