vessim 0__py3-none-any.whl

vessim/__init__.py

@@ -0,0 +1,327 @@
+"""A simulator for carbon-aware applications and systems."""
+
+from datetime import datetime, timedelta
+from typing import Union, List, Optional, Any, Literal
+
+import pandas as pd
+
+DatetimeLike = Union[str, datetime]
+
+
+class TimeSeriesApi:
+    """Simulates an API for time series data like solar irradiance or carbon intensity.
+
+    Args:
+        actual: The actual time-series data to be used. It should contain a datetime-like
+            index marking the time, and each column should represent a different zone
+            containing the data. The name of the zone is equal to the column name.
+            Note that while interpolation is possible when retrieving forecasts, the
+            actual data between timestamps is computed using either `ffill` or `bfill`.
+            If you wish a different behavior, you have to change your actual data
+            beforehand (e.g. by resampling into a different frequency).
+
+        forecast: An optional time-series dataset representing forecasted values. The
+            data should contain two datetime-like indices. One is the
+            `Request Timestamp`, marking the time when the forecast was made. One is the
+            `Forecast Timestamp`, indicating the time the forecast is made for.
+
+            - If data does not include a `Request Timestamp`, it is treated as a static
+              forecast that does not change over time.
+
+            - If `forecast` is not provided, predictions are derived from the actual
+              data when requesting forecasts (actual data is treated as static forecast).
+
+            - When using a non-static forecast, you have to be aware that all the
+              zones/column names also have to appear in the actual dataframe because some
+              actual values are used for interpolation.
+
+        fill_method: Either `ffill` or `bfill`. Determines how actual data is acquired in
+            between timestamps. Some data providers like `Solcast` index their data with a
+            timestamp marking the end of the time-period that the data is valid for.
+            In those cases, `bfill` should be chosen, but the default is `ffill`.
+
+    Example:
+        >>> actual_data = [
+        ...    ["2020-01-01T00:00:00", 100, 800],
+        ...    ["2020-01-01T00:30:00", 110, 850],
+        ...    ["2020-01-01T01:00:00", 105, 820],
+        ...    ["2020-01-01T01:30:00", 108, 840],
+        ... ]
+        >>> actual = pd.DataFrame(
+        ...    actual_data, columns=["timestamp", "zone_a", "zone_b"]
+        ... )
+        >>> actual.set_index(["timestamp"], inplace=True)
+
+        >>> forecast_data = [
+        ...    ["2020-01-01T00:00:00", "2020-01-01T00:30:00", 115, 850],
+        ...    ["2020-01-01T00:00:00", "2020-01-01T01:00:00", 110, 870],
+        ...    ["2020-01-01T00:00:00", "2020-01-01T01:30:00", 110, 860],
+        ...    ["2020-01-01T00:00:00", "2020-01-01T02:00:00", 120, 830],
+        ...    ["2020-01-01T01:00:00", "2020-01-01T01:30:00", 115, 840],
+        ...    ["2020-01-01T01:00:00", "2020-01-01T02:00:00", 110, 830],
+        ... ]
+        >>> forecast = pd.DataFrame(
+        ...    forecast_data, columns=["req_time", "forecast_time", "zone_a", "zone_b"]
+        ... )
+        >>> forecast.set_index(["req_time", "forecast_time"], inplace=True)
+
+        >>> time_series = TimeSeriesApi(actual, forecast)
+    """
+
+    def __init__(
+        self,
+        actual: Union[pd.Series, pd.DataFrame],
+        forecast: Optional[Union[pd.Series, pd.DataFrame]] = None,
+        fill_method: Literal["ffill", "bfill"] = "ffill",
+    ):
+        actual.index = pd.to_datetime(actual.index)
+        actual.sort_index(inplace=True)
+        if isinstance(actual, pd.Series):
+            self._actual = actual.to_frame()
+        elif isinstance(actual, pd.DataFrame):
+            self._actual = actual
+        else:
+            raise ValueError(f"Incompatible type {type(actual)} for 'actual'.")
+
+        if isinstance(forecast, (pd.Series, pd.DataFrame)):
+            # Convert all indices (either one or two columns) to datetime
+            if isinstance(forecast.index, pd.MultiIndex):
+                forecast_index: pd.MultiIndex = forecast.index
+                for level in range(forecast.index.nlevels):
+                    forecast.index = forecast_index.set_levels(
+                        pd.to_datetime(forecast_index.levels[level]), level=level
+                    )
+            else:
+                forecast.index = pd.to_datetime(forecast.index)
+
+            forecast.sort_index(inplace=True)
+        self._forecast: Optional[pd.DataFrame]
+        if isinstance(forecast, pd.Series):
+            self._forecast = forecast.to_frame()
+        else:
+            self._forecast = forecast  # type: ignore
+        self._fill_method = fill_method
+
+    def zones(self) -> List:
+        """Returns a list of all zones, where actual data is available."""
+        return list(self._actual.columns)
+
+    def actual(self, dt: DatetimeLike, zone: Optional[str] = None) -> Any:
+        """Retrieves actual data point of zone at given time.
+
+        If queried timestamp is not available in the `actual` dataframe, the last valid
+        datapoint is being returned.
+
+        Args:
+            dt: Timestamp, at which the data is needed.
+            zone: Optional zone for the data. Has to be provided if there is more than one
+                zone specified in the data. Defaults to None.
+
+        Raises:
+            ValueError: If there is no available data at specified zone or time.
+        """
+        data_at_time = self._get_actual_values_at_time(dt)
+        zone_index = self._get_zone_index_from_dataframe(data_at_time, zone)
+
+        data_point = data_at_time.iloc[0, zone_index]
+        if pd.isna(data_point):
+            raise ValueError(f"Cannot retrieve actual data at '{dt}' in zone '{zone}'.")
+        return data_point
+
+    def forecast(
+        self,
+        start_time: DatetimeLike,
+        end_time: DatetimeLike,
+        zone: Optional[str] = None,
+        frequency: Optional[Union[str, pd.DateOffset, timedelta]] = None,
+        resample_method: Optional[str] = None,
+    ) -> pd.Series:
+        """Retrieves of forecasted data points within window at a frequency.
+
+        - If no forecast time-series data is provided, actual data is used.
+        - Specified timestamps are always rounded down to the nearest existing.
+        - If frequency is not specified, all existing data in the window will be returned.
+        - For various resampling methods, the actual value valid at `start_time` is used.
+          So you have to make sure that there is a valid actual value.
+        - If there is more than one zone present in the data, zone has to be specified.
+          (Note that zone name must also appear in actual data for non-static forecast.)
+        - The forecast does not include the value at `start_time` (see example).
+
+        Args:
+            start_time: Starting time of the window.
+            end_time: End time of the window.
+            zone: Optional geographical zone of the forecast. Defaults to None.
+            frequency: Optional interval, in which the forecast data is to be provided.
+                Defaults to None.
+            resample_method: Optional method, to deal with holes in resampled data.
+                Can be either `bfill`, `ffill` or an interpolation method.
+                For more information on interpolation methods, see the
+                `pandas documentation <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.interpolate.html>`_.
+
+        Returns:
+            pd.Series of forecasted data with timestamps of forecast as index.
+
+        Raises:
+            ValueError: If no data is available for the specified zone or time, or if
+                insufficient data exists for the frequency, without `resample_method`
+                specified.
+
+        Example:
+            >>> index = pd.date_range(
+            ...    "2020-01-01T00:00:00", "2020-01-01T03:00:00", freq="1H"
+            ... )
+            >>> actual = pd.DataFrame({"zone_a": [4, 6, 2, 8]}, index=index)
+
+            >>> forecast_data = [
+            ...    ["2020-01-01T00:00:00", "2020-01-01T01:00:00", 5],
+            ...    ["2020-01-01T00:00:00", "2020-01-01T02:00:00", 2],
+            ...    ["2020-01-01T00:00:00", "2020-01-01T03:00:00", 6],
+            ... ]
+            >>> forecast = pd.DataFrame(
+            ...    forecast_data, columns=["req_time", "forecast_time", "zone_a"]
+            ... )
+            >>> forecast.set_index(["req_time", "forecast_time"], inplace=True)
+
+            >>> time_series = TimeSeriesApi(actual, forecast)
+
+            Forward-fill resampling between 2020-01-01T00:00:00 (actual value = 4.0) and
+            forecasted values between 2020-01-01T01:00:00 and 2020-01-01T02:00:00:
+
+            >>> time_series.forecast(
+            ...    start_time="2020-01-01T00:00:00",
+            ...    end_time="2020-01-01T02:00:00",
+            ...    frequency="30T",
+            ...    resample_method="ffill",
+            ... )
+            2020-01-01 00:30:00    4.0
+            2020-01-01 01:00:00    5.0
+            2020-01-01 01:30:00    5.0
+            2020-01-01 02:00:00    2.0
+            Freq: 30T, Name: zone_a, dtype: float64
+
+            Time interpolation between 2020-01-01T01:10:00 (actual value = 6.0) and
+            2020-01-01T02:00:00 (forecasted value = 2.0):
+
+            >>> time_series.forecast(
+            ...    start_time="2020-01-01T01:10:00",
+            ...    end_time="2020-01-01T01:55:00",
+            ...    zone="zone_a",
+            ...    frequency=timedelta(minutes=20),
+            ...    resample_method="time",
+            ... )
+            2020-01-01 01:30:00    4.4
+            2020-01-01 01:50:00    2.8
+            Freq: 20T, Name: zone_a, dtype: float64
+        """
+        data_src = self._get_forecast_data_source(start_time)
+
+        zone_index = self._get_zone_index_from_dataframe(data_src, zone)
+
+        # Get data of zone and convert to pd.Series
+        forecast: pd.Series = data_src.iloc[:, zone_index].squeeze()
+
+        # Resample the data to get the data to specified frequency
+        if frequency is not None:
+            forecast = self._resample_to_frequency(
+                forecast, start_time, end_time, frequency, resample_method=resample_method
+            )
+            return forecast.iloc[1:]
+
+        return forecast.loc[(forecast.index > start_time) & (forecast.index <= end_time)]
+
+    def _get_forecast_data_source(self, start_time: DatetimeLike):
+        """Returns dataframe used to derive forecast prediction."""
+        data_src: pd.DataFrame
+        if self._forecast is None:
+            # Get all data points beginning at the nearest existing timestamp
+            # lower than start time from actual data
+            data_src = self._actual.loc[self._actual.index.asof(start_time) :]
+        elif self._forecast.index.nlevels == 1:
+            # Forecast data does not include request_timestamp
+            data_src = self._forecast.loc[self._forecast.index.asof(start_time) :]
+        else:
+            # Get forecasts of the nearest existing timestamp lower than start time
+            first_index = self._forecast.index.get_level_values(0)
+            request_time = first_index[first_index <= start_time][-1]
+            data_src = self._forecast.loc[request_time]  # type: ignore
+
+            # Retrieve the actual value at start_time and attach it to the front of the
+            # forecast data with the timestamp (for interpolation at a later stage)
+            actual_values = self._get_actual_values_at_time(start_time)
+            data_src = pd.concat(
+                [actual_values, data_src.loc[(data_src.index > start_time)]]
+            )
+
+        if data_src.empty:
+            raise ValueError(f"Cannot retrieve forecast data at '{start_time}'.")
+
+        return data_src
+
+    def _get_actual_values_at_time(self, dt: DatetimeLike) -> pd.DataFrame:
+        """Return actual data that is valid at a specific time."""
+        return self._actual.reindex(index=[pd.to_datetime(dt)], method=self._fill_method)
+
+    def _get_zone_index_from_dataframe(self, df: pd.DataFrame, zone: Optional[str]):
+        """Return column index of zone from given dataframe.
+
+        If zone is not specified, but there is only one column in the dataframe, the
+        first index is returned.
+
+        Raises:
+            ValueError: If zone index can not be determined.
+        """
+        if zone is None:
+            if len(df.columns) == 1:
+                zone_index = 0
+            else:
+                raise ValueError("Zone needs to be specified.")
+        else:
+            try:
+                zone_index = df.columns.get_loc(zone)
+            except KeyError:
+                raise ValueError(f"Cannot retrieve data for zone '{zone}'.")
+
+        return zone_index
+
+    def _resample_to_frequency(
+        self,
+        df: pd.Series,
+        start_time: DatetimeLike,
+        end_time: DatetimeLike,
+        frequency: Optional[Union[str, pd.DateOffset, timedelta]] = None,
+        resample_method: Optional[str] = None,
+    ):
+        """Transform series into the desired frequency between start and end time."""
+        frequency = pd.tseries.frequencies.to_offset(frequency)
+        if frequency is None:
+            raise ValueError(f"Frequency '{frequency}' invalid.")
+
+        # Add NaN values in the specified frequency
+        new_index = pd.date_range(start=start_time, end=end_time, freq=frequency)
+        combined_index = df.index.union(new_index).sort_values()
+        df = df.reindex(combined_index)
+
+        # Use specific resample method if specified to fill NaN values
+        if resample_method == "ffill":
+            df.ffill(inplace=True)
+        elif resample_method == "bfill":
+            df.bfill(inplace=True)
+        elif resample_method is not None:
+            df.interpolate(method=resample_method, inplace=True)  # type: ignore
+        elif df.isnull().values.any():  # type: ignore
+            # Check if there are NaN values if resample method is not specified
+            raise ValueError(
+                f"Not enough data at frequency '{frequency}'. Specify resample_method"
+            )
+
+        # Get the data to the desired frequency after interpolation
+        return df.loc[(df.index >= start_time) & (df.index <= end_time)].asfreq(frequency)
+
+    def next_update(self, dt: DatetimeLike) -> datetime:
+        """Returns the next time of when the actual trace will change.
+
+        This method is being called in the time-based simulation model for Mosaik.
+        """
+        current_index = self._actual.index.asof(dt)
+        next_iloc = self._actual.index.get_loc(current_index) + 1
+        return self._actual.index[next_iloc]

vessim/analysis.py

@@ -0,0 +1,111 @@
+"""Utility functions for data analysis and plotting."""
+
+import matplotlib.pyplot as plt  # type: ignore
+import pandas as pd
+
+
+def plot_basic_evaluation(data: pd.DataFrame, title: str = "Evaluation"):
+    """Simple function for plotting of the simulation data.
+
+    Args:
+        data: The dataframe containing the simulation data.
+        title: The title of the plot. Defaults to `Evaluation`.
+    """
+    data.index = pd.to_datetime(data.index)
+
+    # Setup graph
+    fig, axs = plt.subplots(ncols=1, nrows=5, sharex="col",sharey="row", figsize=(10,5.5))
+    fig.tight_layout(pad=0)
+    fig.align_ylabels()
+    axs[0].set_title(title)
+
+    # Create plots from data
+    plot_production_and_consumption(axs[0], data["p_solar"], data["p_computing_system"])
+
+    plot_production_consumption_delta(axs[1], data["p_solar"], data["p_computing_system"])
+
+    plot_battery_soc(axs[2], data["battery_soc"], data["battery_min_soc"])
+
+    plot_grid_power_usage(axs[3], data["p_grid"])
+
+    ax3_twin = axs[3].twinx()
+    plot_carbon_intensity(ax3_twin, data["carbon_intensity"])
+    h1, l1 = axs[3].get_legend_handles_labels()
+    h2, l2 = ax3_twin.get_legend_handles_labels()
+    axs[3].legend(
+        [h1[0], h2[0]], ["grid power usage", "carbon emission"], loc="best", frameon=False
+    )
+
+    plot_accumulated_emissions(axs[4], data["p_grid"], data["carbon_intensity"])
+
+
+def plot_production_and_consumption(
+        ax, p_prod, p_cons, prod_color="#6B9A6E", cons_color="#D65D62"
+) -> None:
+    """Create plot for showing production and consumption."""
+    p_prod.plot(ax=ax, color=prod_color, label="production")
+    (- p_cons).plot(ax=ax, color=cons_color, label="consumption", linestyle=":")
+    ax.set_ylabel("power (W)")
+    ax.legend(loc="best", frameon=False)
+
+
+def plot_production_consumption_delta(
+    ax, p_prod, p_cons, pos_color="#79AE7C", neg_color="#D65D62"
+) -> None:
+    """Create a plot for the power delta from production and consumption."""
+    power_delta = p_prod + p_cons
+    power_delta.plot(ax=ax, alpha=0)
+    ax.fill_between(power_delta.index, 0, power_delta.values,
+                        where=power_delta.values > 0, color=pos_color)  # type: ignore
+    ax.fill_between(power_delta.index, 0, power_delta.values,
+                        where=power_delta.values < 0, color=neg_color)  # type: ignore
+    ax.set_ylabel("power\ndelta (W)")
+
+
+def plot_battery_soc(
+    ax, battery_soc, battery_min_soc, soc_color="#79AE7C", min_soc_color="black"
+) -> None:
+    """Create plot for battery state of charge with maximum discharge."""
+    battery_soc.plot(ax=ax, alpha=0)
+    ax.fill_between(battery_soc.index, 0, battery_soc.values * 100, color=soc_color)
+    ax.set_ylim(0, 100)
+    ax.set_ylabel("battery state\nof charge (%)")
+    (battery_min_soc * 100).plot(
+        ax=ax,
+        linestyle="--",
+        linewidth=.8,
+        color=min_soc_color,
+        label="minimum state of charge"
+    )
+    handles, lables = ax.get_legend_handles_labels()
+    ax.legend(handles[1:], lables[1:], frameon=False)
+
+
+def plot_grid_power_usage(ax, p_grid, power_color="#D65D62") -> None:
+    """Create plot of used power from grid over time."""
+    p_grid[p_grid > 0] = 0
+    (-p_grid).plot(ax=ax, color=power_color, linestyle="-")
+    ax.fill_between(p_grid.index, 0, (-p_grid).values.astype(float), color=power_color)
+    ax.set_ylabel("grid power\nusage (W)")
+
+
+def plot_carbon_intensity(ax, carbon_intensity, carbon_color="#333") -> None:
+    """Create plot of carbon intensity over time."""
+    carbon_intensity.plot(ax=ax, color=carbon_color, linewidth=.8)
+    ax.set_ylabel("carbon intensity\n(gCO2/kWh)")
+
+
+def plot_accumulated_emissions(
+    ax, p_grid, carbon_intensity, carbon_color="#999"
+) -> float:
+    """Create plot of total carbon emission over time.
+
+    Returns:
+        The total emission over the whole simulation as float.
+    """
+    emissions = (-p_grid) * carbon_intensity  # 60 Ws * gCO2/kWh
+    emissions /= 60000
+    emissions.cumsum().plot(ax=ax, color="#555", linewidth=.8)
+    ax.fill_between(emissions.index, emissions.cumsum().values, color=carbon_color)
+    ax.set_ylabel("accumulated\nemissions\n(gCO2)")
+    return emissions.sum()

vessim/core/__init__.py

@@ -0,0 +1 @@
+"""Vessim core components."""

vessim/core/consumer.py

@@ -0,0 +1,99 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List
+
+
+class PowerMeter(ABC):
+    """Abstract base class for power meters.
+
+    Args:
+        name: The name of the power meter.
+    """
+
+    def __init__(self, name: str):
+        self.name = name
+
+    @abstractmethod
+    def measure(self) -> float:
+        """Abstract method to measure and return the current node power demand.
+
+        Returns:
+            float: The current power demand of the node.
+        """
+
+    @abstractmethod
+    def finalize(self) -> None:
+        """Perform necessary finalization tasks of specific power meter."""
+
+
+class MockPowerMeter(PowerMeter):
+    """Simulates the behavior of a power meter with fixed power readings.
+
+    Args:
+        name: The name of the power meter.
+        p: Base factor for the measured power value. It is scaled by the consumption
+            factors in the different power modes specified in the power config.
+
+    Attributes:
+        factor: Scaling factor, multiplied with the base factor. Defaults to 1.
+
+    Raises:
+        ValueError: If p is less than 0.
+    """
+
+    def __init__(self, name: str, p: float):
+        super().__init__(name)
+        if p < 0:
+            raise ValueError("p must not be less than 0")
+        self.p = p
+        self.factor = 1.0
+
+    def measure(self) -> float:
+        return self.p * self.factor
+
+    def finalize(self) -> None:
+        pass
+
+class Consumer(ABC):
+    """Abstract base class representing a consumer of power."""
+
+    @abstractmethod
+    def consumption(self) -> float:
+        """Calculates and returns the power consumption of the consumer."""
+
+    def info(self) -> Dict:
+        return {}
+
+    @abstractmethod
+    def finalize(self) -> None:
+        """Perform any finalization tasks for the consumer.
+
+        This method should be overridden by subclasses to implement necessary
+        finalization steps.
+        """
+
+
+class ComputingSystem(Consumer):
+    """Model of the computing system.
+
+    This model considers the power usage effectiveness (PUE) and power
+    consumption of a list of power meters.
+
+    Args:
+        power_meters: A list of PowerMeter objects
+            representing power meters in the system.
+        pue: The power usage effectiveness of the system.
+    """
+
+    def __init__(self, power_meters: List[PowerMeter], pue: float = 1):
+        self.power_meters = power_meters
+        self.pue = pue
+
+    def consumption(self) -> float:
+        return self.pue * sum(pm.measure() for pm in self.power_meters)
+
+    def info(self) -> Dict:
+        return {pm.name: pm.measure() for pm in self.power_meters}
+
+    def finalize(self) -> None:
+        for power_meter in self.power_meters:
+            power_meter.finalize()

vessim/core/microgrid.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Optional
+
+from vessim.core.storage import Storage, StoragePolicy, DefaultStoragePolicy
+
+
+class Microgrid(ABC):
+    @abstractmethod
+    def power_flow(self, p: Dict[str, float], duration: int) -> float:
+        """Calculates the microgrids power flow.
+
+        Args:
+            p: Maps power consumers/producers to the amount of power they demand/supply
+            duration: Duration of the power flow (relevant for battery (dis)charge)
+
+        Returns:
+            Power delta (excess power if positive, power demand if negative)
+        """
+
+
+class SimpleMicrogrid(Microgrid):
+    def __init__(
+        self, storage: Optional[Storage] = None, policy: Optional[StoragePolicy] = None
+    ):
+        """Simply aggregates all supplied and demanded power.
+
+        Args:
+            storage: Optional energy storage to be used to (dis)charge a power delta
+            policy: Storage policy on when and how to use the battery
+        """
+        self.storage = storage
+        self.policy = policy if policy is not None else DefaultStoragePolicy()
+
+    def power_flow(self, p: Dict[str, float], duration: int) -> float:
+        p_delta = sum(p.values())
+        if self.storage is None:
+            return p_delta
+        else:
+            return self.policy.apply(self.storage, p_delta, duration)