vessim 0.9__0-py3-none-any.whl

vessim/__init__.py

@@ -0,0 +1,34 @@
+"""A simulator for carbon-aware applications and systems."""
+
+from vessim.actor import ActorBase, Actor, ComputingSystem
+from vessim.controller import Controller, Monitor
+from vessim.cosim import Microgrid, Environment
+from vessim.policy import MicrogridPolicy, DefaultMicrogridPolicy
+from vessim.signal import Signal, HistoricalSignal, MockSignal, CollectorSignal
+from vessim.storage import Storage, SimpleBattery, ClcBattery
+
+__all__ = [
+    "ActorBase",
+    "Actor",
+    "ComputingSystem",
+    "Controller",
+    "Monitor",
+    "Microgrid",
+    "Environment",
+    "MicrogridPolicy",
+    "DefaultMicrogridPolicy",
+    "CollectorSignal",
+    "MockSignal",
+    "Signal",
+    "HistoricalSignal",
+    "Storage",
+    "ClcBattery",
+    "SimpleBattery",
+]
+
+try:
+    from vessim.sil import Broker, SilController, WatttimeSignal, get_latest_event  # noqa: F401
+
+    __all__.extend(["Broker", "SilController", "WatttimeSignal", "get_latest_event"])
+except ImportError:
+    pass

vessim/_data.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import os
+import urllib.request
+from datetime import timedelta
+from pathlib import Path
+from typing import Optional
+from zipfile import ZipFile
+
+import pandas as pd
+
+VESSIM_DATASETS: dict[str, dict[str, str]] = {
+    "solcast2022_germany": {
+        "actual": "solcast2022_germany_actual.csv",
+        "forecast": "solcast2022_germany_forecast.csv",
+        "fill_method": "bfill",
+        "url": "https://raw.githubusercontent.com/dos-group/vessim/main/datasets/solcast2022_germany.zip",
+    },
+    "solcast2022_global": {
+        "actual": "solcast2022_global_actual.csv",
+        "forecast": "solcast2022_global_forecast.csv",
+        "fill_method": "bfill",
+        "url": "https://raw.githubusercontent.com/dos-group/vessim/main/datasets/solcast2022_global.zip",
+    },
+    "watttime2023_caiso-north": {
+        "actual": "watttime2023_caiso-north_actual.csv",
+        "forecast": "watttime2023_caiso-north_forecast.csv",
+        "fill_method": "ffill",
+        "url": "https://raw.githubusercontent.com/dos-group/vessim/main/datasets/watttime2023_caiso-north.zip",
+    },
+}
+
+
+def load_dataset(dataset: str, dir_path: Path, params: Optional[dict] = None) -> dict:
+    """Downloads a dataset from the vessim repository, unpacks it and loads data."""
+    if dataset not in VESSIM_DATASETS:
+        raise ValueError(f"Dataset '{dataset}' not found. Available datasets are: "
+                         f"{', '.join(list(VESSIM_DATASETS.keys()))}")
+
+    if params is not None:
+        allowed_parameters = ["scale", "start_time", "use_forecast"]
+        for key in params.keys():
+            if key not in allowed_parameters:
+                raise ValueError(f"Parameter '{key}' not allowed. "
+                                 f"Allowed parameters are: {allowed_parameters}.")
+
+    scale = _get_parameter(params, "scale", default=1.0)
+    start_time = _get_parameter(params, "start_time", default=None)
+    use_forecast = _get_parameter(params, "use_forecast", default=True)
+
+    dataset_config = VESSIM_DATASETS[dataset]
+    required_files = [dataset_config["actual"]]
+    if use_forecast:
+        required_files.append(dataset_config["forecast"])
+
+    if not _check_files(required_files, dir_path):
+        print("Required data files not present locally. Try downloading...")
+        os.makedirs(dir_path, exist_ok=True)
+        zip_path = dir_path / "dataset.zip"
+        try:
+            urllib.request.urlretrieve(dataset_config["url"], zip_path)
+        except Exception:
+            raise RuntimeError(f"Dataset could not be retrieved from url: "
+                               f"{dataset_config['url']}")
+
+        with ZipFile(zip_path, "r") as zip_ref:
+            zip_ref.extractall(path=dir_path)
+        os.remove(zip_path)
+        print("Successfully downloaded and unpacked data files.")
+
+    actual = _read_data_from_csv(
+        dir_path / dataset_config["actual"], index_cols=[0], scale=scale
+    )
+
+    forecast: Optional[pd.Series | pd.DataFrame] = None
+    if use_forecast:
+        forecast = _read_data_from_csv(
+            dir_path / dataset_config["forecast"], index_cols=[0, 1], scale=scale
+        )
+
+    if start_time is not None:
+        shift = pd.to_datetime(start_time) - actual.index[0]
+        print(f"Data is being shifted by {shift}")
+        actual.index += shift
+        if use_forecast:
+            forecast = _shift(forecast, shift)  # type: ignore
+
+    return dict(
+        actual=actual,
+        forecast=None if not use_forecast else forecast,
+        fill_method=dataset_config.get("fill_method", "ffill"),
+    )
+
+
+def _get_parameter(params: Optional[dict], key: str, default):
+    if params is None:
+        return default
+    return params.get(key, default)
+
+
+def _check_files(files: list[str], base_dir: Path) -> bool:
+    """Check whether files are present in specified base directory."""
+    for file in files:
+        path = os.path.join(base_dir, file)
+        if not os.path.isfile(path):
+            return False
+    return True
+
+
+def _read_data_from_csv(
+    path: Path, index_cols: list[int], scale: float = 1.0
+) -> pd.Series | pd.DataFrame:
+    """Retrieves a dataframe from a csv file and transforms it."""
+    df = pd.read_csv(path, index_col=index_cols)
+    if isinstance(df.index, pd.MultiIndex):
+        index: pd.MultiIndex = df.index
+        for i, level in enumerate(index.levels):
+            index = index.set_levels(pd.to_datetime(level), level=i)
+        df.index = index
+    else:
+        df.index = pd.to_datetime(df.index)
+
+    df.sort_index(inplace=True)
+    return (df * scale).astype(float)
+
+
+def _shift(df: pd.Series | pd.DataFrame, shift: timedelta) -> pd.Series | pd.DataFrame:
+    """Shifts indices of the given DataFrame by a timedelta."""
+    if isinstance(df.index, pd.MultiIndex):
+        index: pd.MultiIndex = df.index
+        for i, level in enumerate(index.levels):
+            index = index.set_levels(level + shift, level=i)
+        df.index = index
+    else:
+        df.index += shift
+    return df

vessim/_util.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Union
+from loguru import logger
+import sys
+
+import pandas as pd
+import numpy as np
+
+DatetimeLike = Union[str, datetime, np.datetime64]
+
+
+class Clock:
+    def __init__(self, sim_start: str | datetime):
+        self.sim_start = pd.to_datetime(sim_start)
+
+    def to_datetime(self, simtime: int) -> datetime:
+        return self.sim_start + timedelta(seconds=simtime)
+
+    def to_simtime(self, dt: datetime) -> int:
+        return int((dt - self.sim_start).total_seconds())
+
+
+def disable_rt_warnings(behind_threshold: float):
+    """Disables Mosaik's rt_check warnings.
+
+    Mosaik's current implementation of the real-time checks are faulty and a new
+    implementation is already outlined in
+    https://gitlab.com/mosaik/mosaik/-/issues/172. As this issue was opened in
+    June 2023, it is unlikely that the issue will be resolved soon. Therefore,
+    we disable the warnings with a threshold after which these offsets are
+    logged.
+
+    Args:
+        behind_threshold: Time the simulation is allowed to be behind schedule.
+    """
+
+    def filter_record(record):
+        is_warning = record["level"].name == "WARNING"
+        is_mosaik_log = record["name"].startswith("mosaik")
+        is_below_threshold = (
+            record["function"] == "rt_check"
+            and float(record["message"].split(" - ")[1].split("s")[0]) < behind_threshold
+        )
+        return not (is_warning and is_mosaik_log and is_below_threshold)
+
+    # Add the filter to the logger
+    logger.remove()
+    logger.add(sys.stdout, filter=filter_record)

vessim/actor.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from datetime import datetime
+from itertools import count
+from typing import Optional
+from abc import ABC, abstractmethod
+
+import mosaik_api_v3  # type: ignore
+
+from vessim.signal import Signal
+
+
+class ActorBase(ABC):
+    """Abstract base class representing a power consumer or producer."""
+
+    def __init__(self, name: str, step_size: Optional[int] = None) -> None:
+        self.name = name
+        self.step_size = step_size
+
+    @abstractmethod
+    def p(self, now: datetime) -> float:
+        """Current power consumption/production to be used in the grid simulation."""
+
+    def state(self, now: datetime) -> dict:
+        """Current state of the actor to be used in controllers."""
+        return {}
+
+    def finalize(self) -> None:
+        """Perform any finalization tasks for the consumer.
+
+        This method can be overridden by subclasses to implement necessary
+        finalization steps.
+        """
+        return
+
+
+class Actor(ActorBase):
+    """Actor that represents a consumer of producer based on a single Signal."""
+
+    def __init__(self, name: str, signal: Signal, step_size: Optional[int] = None) -> None:
+        super().__init__(name, step_size)
+        self.signal = signal
+
+    def p(self, now: datetime) -> float:
+        return self.signal.now(at=now)
+
+    def state(self, now: datetime) -> dict:
+        return {
+            "p": self.p(now),
+        }
+
+
+class ComputingSystem(ActorBase):
+    """Model of the computing system.
+
+    This model considers the power usage effectiveness (PUE) and power
+    consumption of a list of power meters.
+
+    Args:
+        nodes: list of consumer node signals that constitute the computing system's demand.
+        pue: The power usage effectiveness of the system.
+    """
+
+    _ids = count(0)
+
+    def __init__(
+        self,
+        nodes: list[Signal],
+        name: Optional[str] = None,
+        step_size: Optional[int] = None,
+        pue: float = 1,
+    ):
+        if name is None:
+            name = f"ComputingSystem-{next(self._ids)}"
+        super().__init__(name, step_size)
+        self.nodes = nodes
+        node_ids = count(0)
+        for node in self.nodes:
+            if not node.name:
+                node.name = f"Node-{next(node_ids)}"
+        self.pue = pue
+
+    def p(self, now: datetime) -> float:
+        return self.pue * sum(-signal.now(at=now) for signal in self.nodes)
+
+    def state(self, now: datetime) -> dict:
+        return {
+            "p": self.p(now),
+            "nodes": {signal.name: -signal.now(at=now) for signal in self.nodes},
+        }
+
+
+class _ActorSim(mosaik_api_v3.Simulator):
+    META = {
+        "type": "time-based",
+        "models": {
+            "Actor": {
+                "public": True,
+                "params": ["actor"],
+                "attrs": ["p", "state"],
+            },
+        },
+    }
+
+    def __init__(self):
+        super().__init__(self.META)
+        self.eid = None
+        self.step_size = None
+        self.clock = None
+        self.actor = None
+        self.p = 0
+        self.state = {}
+
+    def init(self, sid, time_resolution=1.0, **sim_params):
+        self.step_size = sim_params["step_size"]
+        self.clock = sim_params["clock"]
+        return self.meta
+
+    def create(self, num, model, **model_params):
+        assert num == 1, "Only one instance per simulation is supported"
+        self.actor = model_params["actor"]
+        self.eid = self.actor.name
+        return [{"eid": self.eid, "type": model}]
+
+    def step(self, time, inputs, max_advance):
+        assert self.clock is not None
+        now = self.clock.to_datetime(time)
+        assert self.actor is not None
+        self.p = self.actor.p(now)
+        self.state = self.actor.state(now)
+        assert self.step_size is not None
+        return time + self.step_size
+
+    def get_data(self, outputs):
+        return {self.eid: {"p": self.p, "state": self.state}}

vessim/controller.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+from csv import DictWriter
+from itertools import count
+from collections.abc import Iterator
+from typing import Any, MutableMapping, Optional, Callable, TYPE_CHECKING
+
+import mosaik_api_v3  # type: ignore
+import pandas as pd
+
+from vessim.signal import Signal
+
+if TYPE_CHECKING:
+    from vessim.cosim import Microgrid
+
+
+class Controller(ABC):
+    _counters: dict[type[Controller], Iterator[int]] = {}
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        """Initializes the subclass and sets up a counter for naming."""
+        super().__init_subclass__(**kwargs)
+        cls._counters[cls] = count()
+
+    def __init__(self, step_size: Optional[int] = None) -> None:
+        cls = self.__class__
+        self.name: str = f"{cls.__name__}-{next(cls._counters[cls])}"
+        self.step_size = step_size
+        self.set_parameters: dict[str, Any] = {}
+
+    def start(self, microgrid: Microgrid) -> None:
+        """Function to be executed before simulation is started. Can be overridden."""
+        pass
+
+    @abstractmethod
+    def step(self, time: datetime, p_delta: float, e_delta: float, state: dict) -> None:
+        """Performs a simulation step.
+
+        Args:
+            time: Current datetime.
+            p_delta: Power delta in W based on the consumption and production of all actors.
+            e_delta: Total energy in Ws that has been drawn from/ fed to the utility grid
+                in the previous time step.
+            state: Contains the last state dictionaries by all actors, the policy, and the storage
+                in the microgrid. The state dictionary is defined by the microgrid components and
+                can contain any information about their custom defined state.
+                The keys are the actor names, `policy`, and `storage` respectively.
+        """
+
+    def finalize(self) -> None:
+        """Function to be executed after simulation has ended. Can be overridden for clean-up."""
+        pass
+
+
+class Monitor(Controller):
+    def __init__(
+        self,
+        step_size: Optional[int] = None,
+        outfile: Optional[str | Path] = None,
+        grid_signals: Optional[dict[str, Signal]] = None,
+    ):
+        super().__init__(step_size=step_size)
+        self.outpath: Optional[Path] = None
+        if outfile:
+            self.outpath = Path(outfile).expanduser()
+        self._fieldnames: Optional[list] = None
+
+        self.monitor_log: dict[datetime, dict] = defaultdict(dict)
+        self.custom_monitor_fns: list[Callable] = []
+
+        if grid_signals is not None:
+            for signal_name, signal_api in grid_signals.items():
+
+                def fn(time):
+                    return {signal_name: signal_api.now(time)}
+
+                self.add_monitor_fn(fn)
+
+    def add_monitor_fn(self, fn: Callable[[float], dict[str, Any]]):
+        self.custom_monitor_fns.append(fn)
+
+    def step(self, time: datetime, p_delta: float, e_delta: float, state: dict) -> None:
+        log_entry = dict(
+            p_delta=p_delta,
+            e_delta=e_delta,
+        )
+        log_entry.update(state)
+        for monitor_fn in self.custom_monitor_fns:
+            log_entry.update(monitor_fn(time))
+        self.monitor_log[time] = log_entry
+
+        if self.outpath:
+            if not self._fieldnames:
+                log_dict = _flatten_dict(log_entry)
+                self._fieldnames = list(log_dict.keys())
+                self._fieldnames.insert(0, "time")
+                log_dict["time"] = time
+                with self.outpath.open("w") as csvfile:
+                    writer = DictWriter(csvfile, fieldnames=self._fieldnames)
+                    writer.writeheader()
+                    writer.writerow(log_dict)
+            else:
+                with self.outpath.open('a', newline='') as csvfile:
+                    writer = DictWriter(csvfile, fieldnames=self._fieldnames)
+                    log_dict = _flatten_dict(log_entry)
+                    log_dict["time"] = time
+                    writer.writerow(log_dict)
+
+    def to_csv(self, out_path: str):
+        df = pd.DataFrame({k: _flatten_dict(v) for k, v in self.monitor_log.items()}).T
+        df.to_csv(out_path)
+
+
+def _flatten_dict(d: MutableMapping, parent_key: str = "") -> MutableMapping:
+    items: list[tuple[str, Any]] = []
+    for k, v in d.items():
+        new_key = parent_key + "." + k if parent_key else k
+        if isinstance(v, MutableMapping):
+            items.extend(_flatten_dict(v, str(new_key)).items())
+        else:
+            items.append((new_key, v))
+    return dict(items)
+
+
+class _ControllerSim(mosaik_api_v3.Simulator):
+    META = {
+        "type": "time-based",
+        "models": {
+            "Controller": {
+                "public": True,
+                "any_inputs": True,
+                "params": ["controller"],
+                "attrs": ["set_parameters"],
+            },
+        },
+    }
+
+    def __init__(self):
+        super().__init__(self.META)
+        self.eid = "Controller"
+        self.step_size = None
+        self.clock = None
+        self.controller = None
+        self.e = 0.0
+
+    def init(self, sid, time_resolution=1.0, **sim_params):
+        self.step_size = sim_params["step_size"]
+        self.clock = sim_params["clock"]
+        return self.meta
+
+    def create(self, num, model, **model_params):
+        assert num == 1, "Only one instance per simulation is supported"
+        self.controller = model_params["controller"]
+        return [{"eid": self.eid, "type": model}]
+
+    def step(self, time, inputs, max_advance):
+        assert self.controller is not None
+        assert self.clock is not None
+        assert self.step_size is not None
+        now = self.clock.to_datetime(time)
+        self.controller.step(now, *self._parse_controller_inputs(inputs[self.eid]))
+        self.set_parameters = self.controller.set_parameters.copy()
+        self.controller.set_parameters = {}
+        return time + self.step_size
+
+    def get_data(self, outputs):
+        return {self.eid: {"set_parameters": self.set_parameters}}
+
+    def finalize(self) -> None:
+        """Stops the api server and the collector thread when the simulation finishes."""
+        assert self.controller is not None
+        self.controller.finalize()
+
+    def _parse_controller_inputs(
+        self, inputs: dict[str, dict[str, Any]]
+    ) -> tuple[float, float, dict]:
+        p_delta = _get_val(inputs, "p_delta")
+        last_e = self.e
+        self.e = _get_val(inputs, "e")
+        actor_keys = [k for k in inputs.keys() if k.startswith("actor")]
+        actors: defaultdict[str, Any] = defaultdict(dict)
+        for k in actor_keys:
+            _, actor_name = k.split(".")
+            actors[actor_name] = _get_val(inputs, k)
+        state = dict(actors)
+        state.update(_get_val(inputs, "state"))
+        return p_delta, self.e - last_e, state
+
+
+def _get_val(inputs: dict, key: str) -> Any:
+    return list(inputs[key].values())[0]