vessim 0__py3-none-any.whl

vessim/core/storage.py

@@ -0,0 +1,122 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from loguru import logger
+
+
+class Storage(ABC):
+    @abstractmethod
+    def update(self, power: float, duration: int) -> float:
+        """Feed or draw energy for specified duration.
+
+        Args:
+            power: Charging if positive, discharging if negative.
+            duration: Duration in seconds for which the storage will be (dis)charged.
+
+        Returns:
+            The power delta, in case not all requested power could be discharged from or
+            charged into the battery. This can happen either if the batter is full/empty
+            or if the C-rate was exceeded.
+            If 0, all power was successfully (dis)charged.
+        """
+
+    @abstractmethod
+    def soc(self) -> float:
+        """Returns the current State of Charge (SoC)."""
+
+
+class SimpleBattery(Storage):
+    """(Way too) simple battery.
+
+    Args:
+        capacity: Battery capacity in watt-seconds (Ws).
+        charge_level: Initial charge level in watt-seconds (Ws).
+        min_soc: Minimum allowed state of charge (SoC) for the battery.
+        c_rate: C-rate, which defines the charge and discharge rate of the battery.
+            For more information on C-rate, see `C-rate explanation <https://www.batterydesign.net/electrical/c-rate/>`_.
+    """
+
+    def __init__(
+        self,
+        capacity: float,
+        charge_level: float = 0,
+        min_soc: float = 0,
+        c_rate: Optional[float] = None,
+    ):
+        self.capacity = capacity
+        assert 0 <= charge_level <= self.capacity
+        self.charge_level = charge_level
+        assert 0 <= min_soc <= self.soc()
+        self.min_soc = min_soc
+        self.c_rate = c_rate
+
+    def update(self, power: float, duration: int) -> float:
+        if duration <= 0.0:
+            raise ValueError("Duration needs to be a positive value")
+
+        max_charge_p_delta, p_delta = 0.0, 0.0
+
+        if self.c_rate is not None:
+            max_rate = self.c_rate * self.capacity / 3600
+            if power >= max_rate:
+                logger.info(
+                    f"Trying to charge storage '{self.__class__.__name__}' with "
+                    f"{power} W but only {max_rate} W are supported."
+                )
+                max_charge_p_delta = power - max_rate
+                power = max_rate
+
+            if power <= -max_rate:
+                logger.info(
+                    f"Trying to discharge storage '{self.__class__.__name__}' "
+                    f"with {power} W but only {max_rate} W are supported."
+                )
+                max_charge_p_delta = power + max_rate
+                power = -self.c_rate
+
+        charge_energy = power * duration
+        new_charge_level = self.charge_level + power * duration
+
+        abs_min_soc = self.min_soc * self.capacity
+        if new_charge_level < abs_min_soc:
+            p_delta = (new_charge_level - abs_min_soc) / duration
+            self.charge_level = abs_min_soc
+        elif new_charge_level > self.capacity:
+            p_delta = (new_charge_level - self.capacity) / duration
+            self.charge_level = self.capacity
+        else:
+            self.charge_level += charge_energy
+
+        return p_delta + max_charge_p_delta
+
+    def soc(self) -> float:
+        return self.charge_level / self.capacity
+
+
+class StoragePolicy(ABC):
+    @abstractmethod
+    def apply(self, storage: Storage, p_delta: float, time_since_last_step: int) -> float:
+        """(Dis)charge the storage according to the policy."""
+
+
+class DefaultStoragePolicy(StoragePolicy):
+    """Storage policy which tries to (dis)charge as much of the delta as possible.
+
+    Args:
+        grid_power: If not 0, the battery is in "charge mode" and will draw the
+            provided power from the grid. In this case, the delta simply returned
+            together with the demand for charging.
+    """
+
+    def __init__(self, grid_power: float = 0):
+        self.grid_power = grid_power
+
+    def apply(self, storage: Storage, p_delta: float, time_since_last_step: int) -> float:
+        if self.grid_power == 0:
+            return storage.update(power=p_delta, duration=time_since_last_step)
+        else:
+            excess_energy = storage.update(
+                power=self.grid_power, duration=time_since_last_step
+            )
+            real_charge_power = self.grid_power - excess_energy
+            return p_delta - real_charge_power

vessim/cosim/__init__.py

@@ -0,0 +1,15 @@
+"""Vessim co-simulation components."""
+
+from vessim.cosim.carbon_api import CarbonApiSim
+from vessim.cosim.consumer import ConsumerSim
+from vessim.cosim.generator import GeneratorSim
+from vessim.cosim.microgrid import MicrogridSim
+from vessim.cosim.monitor import MonitorSim
+
+__all__ = [
+    "CarbonApiSim",
+    "ConsumerSim",
+    "GeneratorSim",
+    "MicrogridSim",
+    "MonitorSim",
+]

vessim/cosim/_util.py

@@ -0,0 +1,162 @@
+import sys
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from typing import Type, Dict, Any, Union
+
+import mosaik_api  # type: ignore
+import pandas as pd
+from loguru import logger
+
+
+class VessimModel:
+
+    @abstractmethod
+    def step(self, time: int, inputs: dict) -> None:
+        """Performs a simulation step on the model.
+
+        Args:
+            time: The current simulation time
+            inputs: The inputs from other simulators
+        """
+
+
+class VessimSimulator(mosaik_api.Simulator, ABC):
+    """Utility class for single-model simulators as supported by Vessim.
+
+    Most use cases for simulators simply require setting all inputs attr values
+    to model_instance attrs and then step the model_instance. This class takes
+    care of all basic mosaik abstractions that are simple copy and paste tasks
+    for each new simulator.
+
+    Attributes:
+        eid_prefix: The prefix to be used for entity IDs.
+        model_class: The class of the model to be simulated.
+        entities: A dictionary that maps entity IDs to their instances.
+        time: The current simulation time.
+        step_size: The simulation step size.
+    """
+
+    def __init__(self, meta, model_class: Type[VessimModel]):
+        """Initialization of a basic simulator with given model.
+
+        Args:
+            meta: A dictionary that describes the simulator's metadata.
+            model_class: The class of the model to be simulated. Model requires
+                step() method with no args (must only utilize object
+                attributes). Alternatively, the step() method of this class
+                must be overwritten and implemented individually.
+        """
+        super().__init__(meta)
+        self.eid_prefix = list(self.meta["models"])[0] + "_"
+        self.model_class = model_class
+        self.entities: Dict[str, VessimModel] = {}
+        self.time = 0
+
+    def init(self, sid, time_resolution, eid_prefix=None):
+        """Initialize Simulator and set `step_size` and `eid_prefix`."""
+        if float(time_resolution) != 1.0:
+            raise ValueError(
+                f"{self.__class__.__name__} only supports time_resolution=1., "
+                f"but {time_resolution} was set."
+            )
+        if eid_prefix is not None:
+            self.eid_prefix = eid_prefix
+        return self.meta
+
+    def create(self, num, model, *args, **kwargs):
+        """Create model instance and save it in `entities`."""
+        next_eid = len(self.entities)
+        entities = []
+        for i in range(next_eid, next_eid + num):
+            # Instantiate `model_class` specified in constructor and pass through args
+            entity = self.model_class(*args, **kwargs)
+            eid = self.eid_prefix + str(i)
+            self.entities[eid] = entity
+            entities.append({"eid": eid, "type": model})
+        return entities
+
+    def step(self, time, inputs, max_advance):
+        """Set all `inputs` attr values to the `entity` attrs, then step the `entity`."""
+        self.time = time
+        for eid, entity in self.entities.items():
+            entity.step(time, inputs.get(eid, {}))
+        return self.next_step(time)
+
+    @abstractmethod
+    def next_step(self, time):
+        """Return time of next simulation step (None for event-based)."""
+
+    def get_data(self, outputs):
+        """Return all requested data as attr from the `model_instance`."""
+        data = {}
+        model_name = list(self.meta["models"])[0]
+        for eid, attrs in outputs.items():
+            model = self.entities[eid]
+            data["time"] = self.time
+            data[eid] = {}
+            for attr in attrs:
+                if attr not in self.meta["models"][model_name]["attrs"]:
+                    raise ValueError(f"Unknown output attribute: {attr}")
+                if hasattr(model, attr):
+                    data[eid][attr] = getattr(model, attr)
+        return data
+
+
+class Clock:
+    def __init__(self, sim_start: Union[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 simplify_inputs(attrs: Dict[str, Dict[str, Any]]) -> Dict[str, Any]:
+    """Removes Mosaik source entity from input dict.
+
+    Examples:
+        >>> simplify_inputs({'p': {'ComputingSystem-0.ComputingSystem_0': -50}})
+        {'p': -50}
+    """
+    # TODO We should make this function a bit more elegant once we better evaluated
+    #   our requirements for Vessim simulations.
+    result = {}
+    for key, val_dict in attrs.items():
+        result[key] = list(val_dict.values())[0]
+        # flattening dicts
+        if isinstance(result[key], dict):
+            for kk in result[key].keys():
+                result[f"{key}.{kk}"] = result[key][kk]
+            del result[key]
+    return result
+
+
+def disable_mosaik_warnings(behind_threshold: float):
+    """Disables Mosaik's incorrect Loguru warnings.
+
+    Mosaik currently deems specific attribute connections as incorrect and logs
+    them as warnings. Also the simulation is always behind by a few fractions
+    of a second (which is fine, code needs time to execute) which Mosaik also
+    logs as a Warning. These Warnings are flagged as bugs in Mosaik's current
+    developement and should be fixed within its next release. Until then, this
+    function should do.
+
+    Args:
+        behind_threshold: Time the simulation is allowed to be behind schedule.
+    """
+    # Define a function to filter out WARNING level logs
+    def filter_record(record):
+        is_warning = record["level"].name == "WARNING"
+        is_mosaik_log = record["name"].startswith("mosaik")
+        is_attribute = record["function"] == "_check_attributes_values"
+        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 or is_attribute))
+
+    # Add the filter to the logger
+    logger.remove()
+    logger.add(sys.stdout, filter=filter_record)

vessim/cosim/carbon_api.py

@@ -0,0 +1,52 @@
+from datetime import datetime
+
+from vessim import TimeSeriesApi
+from vessim.cosim._util import VessimSimulator, VessimModel, Clock
+
+
+class CarbonApiSim(VessimSimulator):
+
+    META = {
+        'type': 'time-based',
+        'models': {
+            'CarbonApi': {
+                'public': True,
+                'params': ['zone'],
+                'attrs': ['carbon_intensity'],
+            },
+        },
+    }
+
+    def __init__(self):
+        super().__init__(self.META, _CarbonApiModel)
+        self.clock = None
+        self.sim_start = None
+        self.carbon_api = None
+
+    def init(self, sid, time_resolution, sim_start: datetime, # type: ignore
+            carbon_api: TimeSeriesApi, eid_prefix=None):
+        super().init(sid, time_resolution, eid_prefix=eid_prefix)
+        self.clock = Clock(sim_start)
+        self.carbon_api = carbon_api
+        return self.meta
+
+    def create(self, num, model, *args, **kwargs):
+        return super().create(num, model, *args, **kwargs, clock=self.clock,
+                              carbon_api=self.carbon_api)
+
+    def next_step(self, time: int) -> int:
+        dt = self.clock.to_datetime(time)
+        next_dt = self.carbon_api.next_update(dt)
+        return self.clock.to_simtime(next_dt)
+
+
+class _CarbonApiModel(VessimModel):
+    def __init__(self, carbon_api: TimeSeriesApi, clock: Clock, zone: str):
+        self.api = carbon_api
+        self.clock = clock
+        self.zone = zone
+        self.carbon_intensity = 0.0
+
+    def step(self, time: int, inputs: dict) -> None:
+        dt = self.clock.to_datetime(time)
+        self.carbon_intensity = self.api.actual(dt, self.zone)

vessim/cosim/consumer.py

@@ -0,0 +1,53 @@
+from typing import Dict
+
+from vessim.core.consumer import Consumer
+from vessim.cosim._util import VessimSimulator, VessimModel
+
+
+class ConsumerSim(VessimSimulator):
+    """Computing System simulator that executes its model."""
+
+    META = {
+        "type": "time-based",
+        "models": {
+            "Consumer": {
+                "public": True,
+                "params": ["consumer"],
+                "attrs": ["p", "info"],
+            },
+        },
+    }
+
+    def __init__(self):
+        self.step_size = None
+        super().__init__(self.META, _ComputingSystemModel)
+
+    def init(self, sid, time_resolution, step_size, eid_prefix=None):
+        self.step_size = step_size
+        return super().init(sid, time_resolution, eid_prefix=eid_prefix)
+
+    def finalize(self) -> None:
+        """Stops power meters' threads."""
+        super().finalize()
+        for model_instance in self.entities.values():
+            model_instance.consumer.finalize()  # type: ignore
+
+    def next_step(self, time):
+        return time + self.step_size
+
+
+class _ComputingSystemModel(VessimModel):
+
+    def __init__(self, consumer: Consumer):
+        self.consumer = consumer
+        self.p = 0.0
+        self.info: Dict = {}
+
+    def step(self, time: int, inputs: dict) -> None:
+        """Updates the power consumption of the system.
+
+        The power consumption is calculated as the product of the PUE and the
+        sum of the node power of all power meters.
+        """
+        self.p = -self.consumer.consumption()
+        self.info = self.consumer.info()

vessim/cosim/generator.py

@@ -0,0 +1,48 @@
+from datetime import datetime
+from typing import Optional
+
+from vessim import TimeSeriesApi
+from vessim.cosim._util import Clock, VessimSimulator, VessimModel
+
+
+class GeneratorSim(VessimSimulator):
+
+    META = {
+        "type": "time-based",
+        "models": {
+            "Generator": {
+                "public": True,
+                "params": ["generator"],
+                "attrs": ["p"],
+            },
+        },
+    }
+
+    def __init__(self):
+        super().__init__(self.META, _GeneratorModel)
+
+    def init(self, sid, time_resolution, sim_start: datetime,  # type: ignore
+             eid_prefix=None):
+        super().init(sid, time_resolution, eid_prefix=eid_prefix)
+        self.clock = Clock(sim_start)
+        return self.meta
+
+    def create(self, num, model, *args, **kwargs):
+        return super().create(num, model, *args, **kwargs, clock=self.clock)
+
+    def next_step(self, time: int) -> int:
+        dt = self.clock.to_datetime(time)
+        next_dt = min(e.generator.next_update(dt)   # type: ignore
+                      for e in self.entities.values())
+        return self.clock.to_simtime(next_dt)
+
+
+class _GeneratorModel(VessimModel):
+    def __init__(self, generator: TimeSeriesApi, clock: Clock):
+        self.generator = generator
+        self.clock = clock
+        self.p: Optional[float] = None
+
+    def step(self, time: int, inputs: dict) -> None:
+        dt = self.clock.to_datetime(time)
+        self.p = self.generator.actual(dt)

vessim/cosim/microgrid.py

@@ -0,0 +1,38 @@
+from typing import Dict
+
+from vessim.core.microgrid import Microgrid
+from vessim.cosim._util import VessimSimulator, VessimModel
+
+
+class MicrogridSim(VessimSimulator):
+
+    META = {
+        "type": "event-based",
+        "models": {
+            "Microgrid": {
+                "public": True,
+                "params": ["microgrid"],
+                "attrs": ["p", "p_delta"],
+            },
+        },
+    }
+
+    def __init__(self) -> None:
+        self.step_size = None
+        super().__init__(self.META, _MicrogridModel)
+
+    def next_step(self, time):
+        return None
+
+
+class _MicrogridModel(VessimModel):
+    def __init__(self, microgrid: Microgrid):
+        self.microgrid = microgrid
+        self.p_delta = 0.0
+        self._last_step_time = 0
+
+    def step(self, time: int, inputs: Dict) -> None:
+        duration = time - self._last_step_time
+        if duration > 0:
+            self.p_delta = self.microgrid.power_flow(p=inputs["p"], duration=duration)
+        self._last_step_time = time

vessim/cosim/monitor.py

@@ -0,0 +1,71 @@
+from collections import defaultdict
+from datetime import datetime
+from typing import Dict, Callable, Any
+
+import pandas as pd
+
+from vessim.cosim._util import Clock, VessimSimulator, VessimModel, simplify_inputs
+
+
+class MonitorSim(VessimSimulator):
+
+    META = {
+        "type": "time-based",
+        "models": {
+            "Monitor": {
+                "public": True,
+                "any_inputs": True,
+                "params": ["out_path", "fn"],
+                "attrs": [],
+            },
+        },
+    }
+
+    def __init__(self) -> None:
+        """Simple data collector for printing data at the end of simulation."""
+        self.step_size = None
+        self.clock = None
+        super().__init__(self.META, _MonitorModel)
+
+    def init(self, sid, time_resolution, sim_start: datetime,  # type: ignore
+             step_size: int, eid_prefix=None):
+        self.step_size = step_size  # type: ignore
+        self.clock = Clock(sim_start)  # type: ignore
+        return super().init(sid, time_resolution, eid_prefix=eid_prefix)
+
+    def create(self, num, model, *args, **kwargs):  # type: ignore
+        return super().create(num, model, *args, **kwargs, clock=self.clock)
+
+    def finalize(self):
+        """Collected data is printed to file at simulation end."""
+        for model in self.entities.values():
+            model: _MonitorModel
+            model.finalize()
+
+    def next_step(self, time):
+        return time + self.step_size
+
+
+class _MonitorModel(VessimModel):
+    def __init__(self, out_path: str, fn: Callable[[], Dict[str, Any]], clock: Clock):
+        self.out_path = out_path
+        self.fn = fn
+        self._clock = clock
+        self.data: Dict = defaultdict(dict)
+
+    def step(self, time: int, inputs: Dict) -> None:
+        inputs = simplify_inputs(inputs)
+        dt = self._clock.to_datetime(time)
+        # TODO Reimplement logging on DEBUG level
+        # logger.info(f"# --- {str(dt):>5} ---")
+
+        if self.fn is not None:
+            inputs.update(self.fn())
+
+        for attr, value in inputs.items():
+            # logger.info(f"{attr}: {value}")
+            self.data[attr][dt] = value
+
+    def finalize(self):
+        """Collected data is printed to file at simulation end."""
+        pd.DataFrame(self.data).to_csv(self.out_path)

vessim/sil/__init__.py

@@ -0,0 +1,4 @@
+"""Vessim Software-in-the-Loop (SiL) components.
+
+This module is highly experimental, the public API might change at any time.
+"""