vessim 0__tar.gz

vessim-0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.1
+Name: vessim
+Version: 0
+Summary: A simulator for carbon-aware applications and systems.
+Home-page: https://github.com/dos-group/vessim
+License: MIT
+Keywords: simulation,energy system,testbed,carbon-aware computing,software-in-the-loop
+Author: Philipp Wiesner
+Author-email: wiesner@tu-berlin.de
+Requires-Python: >=3.8,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Testing
+Provides-Extra: analysis
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: sil
+Requires-Dist: black ; extra == "dev"
+Requires-Dist: docker ; extra == "sil"
+Requires-Dist: fastapi ; extra == "sil"
+Requires-Dist: furo ; extra == "docs"
+Requires-Dist: jupyterlab ; extra == "analysis"
+Requires-Dist: loguru
+Requires-Dist: matplotlib ; extra == "analysis"
+Requires-Dist: mosaik
+Requires-Dist: mosaik-api
+Requires-Dist: mypy ; extra == "dev"
+Requires-Dist: pandas
+Requires-Dist: pandas-stubs ; extra == "dev"
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: redis ; extra == "sil"
+Requires-Dist: requests ; extra == "sil"
+Requires-Dist: ruff ; extra == "dev"
+Requires-Dist: seaborn (==0.12.2) ; extra == "analysis"
+Requires-Dist: sphinx-copybutton ; extra == "docs"
+Requires-Dist: types-psutil ; extra == "dev"
+Requires-Dist: types-requests ; extra == "dev"
+Requires-Dist: uvicorn ; extra == "sil"
+Project-URL: Bug Reports, https://github.com/dos-group/vessim/issues
+Project-URL: Documentation, https://github.com/dos-group/vessim
+Project-URL: Repository, https://github.com/dos-group/vessim
+Description-Content-Type: text/markdown
+
+# Vessim
+
+[![PyPI version](https://img.shields.io/pypi/v/vessim.svg?color=52c72b)](https://pypi.org/project/vessim/)
+![Tests](https://github.com/dos-group/vessim/actions/workflows/linting-and-testing.yml/badge.svg)
+[![License](https://img.shields.io/pypi/l/vessim.svg)](https://pypi.org/project/vessim/)
+[![Supported versions](https://img.shields.io/pypi/pyversions/vessim.svg)](https://pypi.org/project/vessim/)
+
+Vessim is a versatile **co-simulation testbed for carbon-aware applications and systems**.
+It lets users connect domain-specific simulators for energy system components like renewable power generation, 
+energy storage, and power flow analysis with real software and hardware.
+
+Vessim is in alpha stage and under active development.
+Functionality and documentation will improve in the next weeks and months.
+
+
+## Installation
+
+If you are using Vessim for the first time, we recommend to clone and install this repository, so you have all
+code and examples at hand:
+
+```
+pip install -e .
+```
+
+Alternatively, you can also install our [latest release](https://pypi.org/project/vessim/) 
+via [pip](https://pip.pypa.io/en/stable/quickstart/):
+
+```
+pip install vessim
+```
+
+
+## Getting started
+
+To execute our exemplary co-simulation scenario, run:
+
+```
+python examples/cosim_example.py
+```
+
+Software-in-the-Loop (SiL) simulation allows real computing systems to interact with Vessim at runtime.
+We're currently working on better documentation on how to set up a full SiL scenario, but you can experiment with the existing
+functionality by installing the "sil" extension (`pip install vessim[sil]`) and running:
+
+```
+python examples/sil_example.py
+```
+
+
+## Work in progress
+
+Our team at the [Distributed and Operating Systems](https://distributedsystems.berlin/) group at TU Berlin is actively working to improve Vessim.
+We are currently working on the following aspects and features:
+
+- **Better documentation**: You can find the current WiP documentation [here](https://vessim.readthedocs.io/en/latest/)
+- **Improving the scenario API**: We currently heavily rely on [Mosaik](https://mosaik.offis.de/)'s scenario interface for defining experiment, but want to offer a more opinionated, high-level API to improve usability.
+- **Software-in-the-loop (SiL) capabilities**: The current SiL implementation is focussed around our exemplary use case presented in our [journal paper](https://doi.org/10.1002/spe.3275). We want this to become more general purpose, so users can implement custom interfaces for the communication of computing and energy systems.
+- **Prodiving access to relevant datasets**: We're currently collectig relevant datasets for carbon-aware test cases such as solar production or carbon intensity traces to simplify the setup of test cases.
+- **Integrating the SAM**: NREL's [System Advisor Model (SAM)](https://sam.nrel.gov/) will soon be available as a subsystem in Vessim.
+
+
+## Publications
+
+If you use Vessim in your research, please cite our vision paper:
+
+- Philipp Wiesner, Ilja Behnke and Odej Kao. "[A Testbed for Carbon-Aware Applications and Systems](https://arxiv.org/pdf/2306.09774.pdf)" arXiv:2302.08681 [cs.DC]. 2023.
+```
+@misc{wiesner2023vessim,
+    title={A Testbed for Carbon-Aware Applications and Systems}, 
+    author={Wiesner, Philipp and Behnke, Ilja and Kao, Odej},
+    year={2023},
+    eprint={2306.09774},
+    archivePrefix={arXiv},
+    primaryClass={cs.DC}
+}
+```
+
+Or our journal paper on software-in-the-loop similation for carbon-aware applications:
+- Philipp Wiesner, Marvin Steinke, Henrik Nickel, Yazan Kitana, and Odej Kao. "[Software-in-the-Loop Simulation for Developing and Testing Carbon-Aware Applications](https://doi.org/10.1002/spe.3275)" Software: Practice and Experience, 53 (12). 2023.
+```
+@article{wiesner2023sil,
+    author = {Wiesner, Philipp and Steinke, Marvin and Nickel, Henrik and Kitana, Yazan and Kao, Odej},
+    title = {Software-in-the-loop simulation for developing and testing carbon-aware applications},
+    journal = {Software: Practice and Experience},
+    year = {2023},
+    volume = {53},
+    number = {12},
+    pages = {2362-2376},
+    doi = {https://doi.org/10.1002/spe.3275}
+}
+```
+

vessim-0/README.md

@@ -0,0 +1,91 @@
+# Vessim
+
+[![PyPI version](https://img.shields.io/pypi/v/vessim.svg?color=52c72b)](https://pypi.org/project/vessim/)
+![Tests](https://github.com/dos-group/vessim/actions/workflows/linting-and-testing.yml/badge.svg)
+[![License](https://img.shields.io/pypi/l/vessim.svg)](https://pypi.org/project/vessim/)
+[![Supported versions](https://img.shields.io/pypi/pyversions/vessim.svg)](https://pypi.org/project/vessim/)
+
+Vessim is a versatile **co-simulation testbed for carbon-aware applications and systems**.
+It lets users connect domain-specific simulators for energy system components like renewable power generation, 
+energy storage, and power flow analysis with real software and hardware.
+
+Vessim is in alpha stage and under active development.
+Functionality and documentation will improve in the next weeks and months.
+
+
+## Installation
+
+If you are using Vessim for the first time, we recommend to clone and install this repository, so you have all
+code and examples at hand:
+
+```
+pip install -e .
+```
+
+Alternatively, you can also install our [latest release](https://pypi.org/project/vessim/) 
+via [pip](https://pip.pypa.io/en/stable/quickstart/):
+
+```
+pip install vessim
+```
+
+
+## Getting started
+
+To execute our exemplary co-simulation scenario, run:
+
+```
+python examples/cosim_example.py
+```
+
+Software-in-the-Loop (SiL) simulation allows real computing systems to interact with Vessim at runtime.
+We're currently working on better documentation on how to set up a full SiL scenario, but you can experiment with the existing
+functionality by installing the "sil" extension (`pip install vessim[sil]`) and running:
+
+```
+python examples/sil_example.py
+```
+
+
+## Work in progress
+
+Our team at the [Distributed and Operating Systems](https://distributedsystems.berlin/) group at TU Berlin is actively working to improve Vessim.
+We are currently working on the following aspects and features:
+
+- **Better documentation**: You can find the current WiP documentation [here](https://vessim.readthedocs.io/en/latest/)
+- **Improving the scenario API**: We currently heavily rely on [Mosaik](https://mosaik.offis.de/)'s scenario interface for defining experiment, but want to offer a more opinionated, high-level API to improve usability.
+- **Software-in-the-loop (SiL) capabilities**: The current SiL implementation is focussed around our exemplary use case presented in our [journal paper](https://doi.org/10.1002/spe.3275). We want this to become more general purpose, so users can implement custom interfaces for the communication of computing and energy systems.
+- **Prodiving access to relevant datasets**: We're currently collectig relevant datasets for carbon-aware test cases such as solar production or carbon intensity traces to simplify the setup of test cases.
+- **Integrating the SAM**: NREL's [System Advisor Model (SAM)](https://sam.nrel.gov/) will soon be available as a subsystem in Vessim.
+
+
+## Publications
+
+If you use Vessim in your research, please cite our vision paper:
+
+- Philipp Wiesner, Ilja Behnke and Odej Kao. "[A Testbed for Carbon-Aware Applications and Systems](https://arxiv.org/pdf/2306.09774.pdf)" arXiv:2302.08681 [cs.DC]. 2023.
+```
+@misc{wiesner2023vessim,
+    title={A Testbed for Carbon-Aware Applications and Systems}, 
+    author={Wiesner, Philipp and Behnke, Ilja and Kao, Odej},
+    year={2023},
+    eprint={2306.09774},
+    archivePrefix={arXiv},
+    primaryClass={cs.DC}
+}
+```
+
+Or our journal paper on software-in-the-loop similation for carbon-aware applications:
+- Philipp Wiesner, Marvin Steinke, Henrik Nickel, Yazan Kitana, and Odej Kao. "[Software-in-the-Loop Simulation for Developing and Testing Carbon-Aware Applications](https://doi.org/10.1002/spe.3275)" Software: Practice and Experience, 53 (12). 2023.
+```
+@article{wiesner2023sil,
+    author = {Wiesner, Philipp and Steinke, Marvin and Nickel, Henrik and Kitana, Yazan and Kao, Odej},
+    title = {Software-in-the-loop simulation for developing and testing carbon-aware applications},
+    journal = {Software: Practice and Experience},
+    year = {2023},
+    volume = {53},
+    number = {12},
+    pages = {2362-2376},
+    doi = {https://doi.org/10.1002/spe.3275}
+}
+```

vessim-0/pyproject.toml

@@ -0,0 +1,110 @@
+[tool.poetry]
+name = "vessim"
+version = "0" # Poetry requires a version configuration to be present. The poetry-version-plugin extracts the correct version from the git-tag.
+description = "A simulator for carbon-aware applications and systems."
+keywords = ["simulation", "energy system", "testbed", "carbon-aware computing", "software-in-the-loop"]
+authors = ["Philipp Wiesner <wiesner@tu-berlin.de>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/dos-group/vessim"
+repository = "https://github.com/dos-group/vessim"
+documentation = "https://github.com/dos-group/vessim"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Testing",
+  "Topic :: Education",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[tool.poetry-version-plugin]
+source = "git-tag"
+
+[tool.poetry.urls]
+"Bug Reports" = "https://github.com/dos-group/vessim/issues"
+
+[tool.poetry.dependencies]
+python = "^3.8"
+# Mandatory dependencies
+pandas = "*"
+mosaik = "*"
+mosaik-api = "*"
+loguru = "*"
+# Optional dependencies (software-in-the-loop)
+requests = {version = "*", optional = true}
+fastapi = {version = "*", optional = true}
+docker = {version = "*", optional = true}
+redis = {version = "*", optional = true}
+uvicorn = {version = "*", optional = true}
+# Optional dependencies (analysis)
+jupyterlab = {version = "*", optional = true}
+matplotlib = {version = "*", optional = true}
+seaborn = {version = "0.12.2", optional = true}
+# Optional dependencies (development)
+pytest = {version = "*", optional = true}
+mypy = {version = "*", optional = true}
+types-psutil = {version = "*", optional = true}
+pandas-stubs = {version = "*", optional = true}
+types-requests = {version = "*", optional = true}
+black = {version = "*", optional = true}
+ruff = {version = "*", optional = true}
+# Optional dependencies (documentation)
+furo = {version = "*", optional = true}
+sphinx-copybutton = {version = "*", optional = true}
+
+[tool.poetry.extras]
+sil = ["requests", "fastapi", "docker", "redis", "uvicorn"]
+analysis = ["jupyterlab", "matplotlib", "seaborn"]
+dev = ["pytest", "mypy", "types-psutil", "pandas-stubs", "types-requests", "black", "ruff"]
+docs = ["furo", "sphinx-copybutton"]
+
+[build-system]
+requires = ["poetry-core>=1.1.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 90  # Set the maximum characters per line
+target-version = ['py38']   # Set python versions that black should format the code for
+include = '\.py$'  # Format only python files
+
+[tool.ruff]
+# Enable Ruff to check for issues (https://beta.ruff.rs/docs/rules)
+select = [
+  "E", "W",  # pycodestyle (error and warning)
+  "D",  # docstrings
+  "F",  # Pyflakes
+  "N",  # variable naming
+  #  "B",  # flake8-bugbear
+]
+
+# For now the following rules are disabled:
+#   D100: Missing docstring in public module
+#   D101: Missing docstring in public class
+#   D102: Missing docstring in public method
+#   D103: Missing docstring in public function
+#   D107: Missing docstring in __init__
+ignore = ["D100", "D101", "D102", "D103", "D107", "E722"]
+
+# Allow autofix for all enabled rules (when `--fix`) is provided.
+fixable = ["D", "E", "W"]
+unfixable = ["F"]
+
+line-length = 90  # Set the maximum characters per line (similar to black)
+target-version = "py38"  # Set python version for linting (similar to black)
+include = ["*.py"]  # Only enable linting for python files (similar to black)
+
+# Configure Ruff to enforce Google-style docstrings when checking documentation
+[tool.ruff.pydocstyle]
+convention = "google"
+
+# Configure mypy to ignore missing imports
+[mypy]
+ignore_missing_imports = true

vessim-0/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]