vessim 0__py3-none-any.whl

vessim/sil/api_server.py

@@ -0,0 +1,229 @@
+import multiprocessing
+import json
+from abc import ABC, abstractmethod
+from time import sleep
+from datetime import datetime
+from typing import Optional, Dict, Type
+
+import uvicorn  # type: ignore
+from fastapi import FastAPI, HTTPException  # type: ignore
+from pydantic import BaseModel  # type: ignore
+
+from vessim.sil.redis_docker import RedisDocker
+
+
+class SilApi(ABC):
+    """Base class for the API running on the ApiServer in different process.
+
+    Initializes a FastApi instance with an endpoint `/shutdown` for executing
+    necessary cleanup tasks of the child process running the API.
+
+    Attributes:
+        app: The FastApi instance to be run.
+    """
+
+    def __init__(self) -> None:
+        self.app = FastAPI()
+
+        @self.app.put("/shutdown")
+        async def shutdown_server():
+            self.finalize()
+
+    @abstractmethod
+    def finalize(self) -> None:
+        """Complete necessary cleanup tasks."""
+
+
+class ApiServer(multiprocessing.Process):
+    """Process that runs a given FastAPI application with a uvicorn server.
+
+    Args:
+        api_type: The type of the class containing the app to be executed.
+        host: The host address where the server will be accessible.
+            Defaults to '127.0.0.1'.
+        port: The port number on which the FastAPI application will run.
+            Defaults to 8000.
+    """
+
+    def __init__(
+        self, api_type: Type[SilApi], host: str = "127.0.0.1", port: int = 8000
+    ) -> None:
+        super().__init__()
+        self.api_type = api_type
+        self.host = host
+        self.port = port
+        self.startup_complete = multiprocessing.Value("b", False)
+
+    def wait_for_startup_complete(self):
+        """Waiting for completion of startup process.
+
+        To ensure the server is operational for the simulation, the startup
+        needs to complete before any requests can be made. Waits for the
+        uvicorn server to finish startup.
+        """
+        while not self.startup_complete.value:
+            sleep(1)
+
+    def run(self):
+        """Called with `multiprocessing.Process.start()`. Runs the uvicorn server."""
+        api = self.api_type()
+
+        @api.app.on_event("startup")
+        async def startup_event():
+            self.startup_complete.value = True
+
+        config = uvicorn.Config(
+            app=api.app, host=self.host, port=self.port, access_log=False
+        )
+        server = uvicorn.Server(config=config)
+        try:
+            server.run()
+        finally:
+            api.finalize()
+
+
+class VessimApi(SilApi):
+    """Specialized Vessim API to be executed in a different process.
+
+    Initializes a FastAPI instance with specific routes related to the Vessim API.
+    This app is very specific for the use case of the `Vessim vision paper <https://arxiv.org/pdf/2306.09774.pdf>`_.
+
+    Attributes:
+        app: The FastApi instance to be run.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.redis_docker = RedisDocker()
+        self._init_get_routes(self.app)
+        self._init_put_routes(self.app)
+
+    def finalize(self) -> None:
+        """Terminate Docker container for cleanup."""
+        self.redis_docker.__del__()
+
+    def _init_get_routes(self, app: FastAPI) -> None:
+        """Initializes GET routes for a FastAPI.
+
+        Args:
+            app: The FastAPI app to add the GET routes to.
+        """
+        # /api/
+
+        class SolarModel(BaseModel):
+            solar: Optional[float]
+
+        @app.get("/api/solar", response_model=SolarModel)
+        async def get_solar() -> SolarModel:
+            solar = self.redis_docker.redis.get("solar")
+            if solar is not None:
+                solar = float(solar)
+            return SolarModel(solar=solar)
+
+        class CiModel(BaseModel):
+            ci: Optional[float]
+
+        @app.get("/api/ci", response_model=CiModel)
+        async def get_ci() -> CiModel:
+            ci = self.redis_docker.redis.get("ci")
+            if ci is not None:
+                ci = float(ci)
+            return CiModel(ci=ci)
+
+        class BatterySocModel(BaseModel):
+            battery_soc: Optional[float]
+
+        @app.get("/api/battery-soc", response_model=BatterySocModel)
+        async def get_battery_soc() -> BatterySocModel:
+            battery_soc = self.redis_docker.redis.get("battery_soc")
+            if battery_soc is not None:
+                battery_soc = float(battery_soc)
+            return BatterySocModel(battery_soc=battery_soc)
+
+        # /sim/
+
+        class CollectSetModel(BaseModel):
+            battery_min_soc: Optional[Dict[str, float]]
+            battery_grid_charge: Optional[Dict[str, float]]
+            nodes_power_mode: Optional[Dict[str, Dict[str, str]]]
+
+        @app.get("/sim/collect-set", response_model=CollectSetModel)
+        async def get_collect_set() -> CollectSetModel:
+            model = CollectSetModel(
+                battery_min_soc=self._deserialize_redis_hash("battery_min_soc_log"),
+                battery_grid_charge=self._deserialize_redis_hash(
+                    "battery_grid_charge_log"
+                ),
+                nodes_power_mode=self._deserialize_redis_hash("power_mode_log"),
+            )
+            self._delete_all_keys_in_hash("battery_min_soc_log")
+            self._delete_all_keys_in_hash("battery_grid_charge_log")
+            self._delete_all_keys_in_hash("power_mode_log")
+            return model
+
+    def _deserialize_redis_hash(self, hash_name):
+        return {
+            key.decode(): json.loads(value.decode())
+            for key, value in self.redis_docker.redis.hgetall(hash_name).items()
+        }
+
+    def _delete_all_keys_in_hash(self, hash_name: str) -> None:
+        keys = self.redis_docker.redis.hkeys(hash_name)
+        for key in keys:
+            self.redis_docker.redis.hdel(hash_name, key)
+
+    def _init_put_routes(self, app: FastAPI) -> None:
+        """Initialize PUT routes for the FastAPI application.
+
+        Args:
+            app: FastAPI application instance to which PUT routes are added.
+        """
+        # /api/
+
+        class BatteryModel(BaseModel):
+            min_soc: float
+            grid_charge: float
+
+        @app.put("/api/battery", response_model=BatteryModel)
+        async def put_battery(battery: BatteryModel) -> BatteryModel:
+            timestamp = datetime.now().isoformat()
+            self.redis_docker.redis.hset(
+                "battery_min_soc_log", str(timestamp), battery.min_soc
+            )
+            self.redis_docker.redis.hset(
+                "battery_grid_charge_log", str(timestamp), battery.grid_charge
+            )
+            return battery
+
+        class NodeModel(BaseModel):
+            power_mode: str
+
+        @app.put("/api/nodes/{item_id}", response_model=NodeModel)
+        async def put_nodes(node: NodeModel, item_id: str) -> NodeModel:
+            power_modes = ["power-saving", "normal", "high performance"]
+            power_mode = node.power_mode
+            if power_mode not in power_modes:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"{power_mode} is not a valid power mode. "
+                    f"Available power modes: {power_modes}",
+                )
+            timestamp = datetime.now().isoformat()
+            self.redis_docker.redis.hset(
+                "power_mode_log", str(timestamp), json.dumps({item_id: power_mode})
+            )
+            return node
+
+        # /sim/
+
+        class UpdateModel(BaseModel):
+            solar: float
+            ci: float
+            battery_soc: float
+
+        @app.put("/sim/update", response_model=UpdateModel)
+        async def put_update(update: UpdateModel) -> UpdateModel:
+            self.redis_docker.redis.set("solar", update.solar)
+            self.redis_docker.redis.set("ci", update.ci)
+            self.redis_docker.redis.set("battery_soc", update.battery_soc)
+            return update

vessim/sil/http_client.py

@@ -0,0 +1,54 @@
+import requests
+import json
+from typing import Any, Dict
+
+
+class HttpClient:
+    """Class for making HTTP requests to the Vessim API server.
+
+    Args:
+        server_address: The address of the server to connect to.
+            e.g. http://localhost
+    """
+
+    def __init__(self, server_address: str, timeout: float = 5) -> None:
+        self.server_address = server_address
+        self.timeout = timeout
+
+    def get(self, route: str) -> dict:
+        """Sends a GET request to the server and retrieves data.
+
+        Args:
+            route: The path of the endpoint to send the request to.
+
+        Raises:
+            HTTPError: If response code is != 200.
+
+        Returns:
+            A dictionary containing the response.
+        """
+        response = requests.get(self.server_address + route, timeout=self.timeout)
+        if response.status_code != 200:
+            response.raise_for_status()
+        data = response.json()  # assuming the response data is in JSON format
+        return data
+
+    def put(self, route: str, data: Dict[str, Any] = {}) -> None:
+        """Sends a PUT request to the server to update data.
+
+        Args:
+            route: The path of the endpoint to send the request to.
+            data: The data to be updated, in dictionary format.
+
+        Raises:
+            HTTPError: If response code is != 200.
+        """
+        headers = {"Content-type": "application/json"}
+        response = requests.put(
+            self.server_address + route,
+            data=json.dumps(data),
+            headers=headers,
+            timeout=self.timeout,
+        )
+        if response.status_code != 200:
+            response.raise_for_status()

vessim/sil/loop_thread.py

@@ -0,0 +1,46 @@
+import threading
+import time
+from typing import Callable
+
+class LoopThread(threading.Thread):
+    """Thread subclass that runs a target function until `stop()` is called.
+
+    Also facilitates the propagation of exceptions to the main thread.
+
+    Args:
+        target_function: The function to be run in the thread.
+
+    Attributes:
+        target_function: The function to be run in the thread.
+        stop_signal: An event that can be set to signal the
+            thread to stop.
+        exc: Variable that is set to propagate an exception to the main thread.
+    """
+
+    def __init__(self, target_function: Callable[[], None], interval: float):
+        super().__init__()
+        self.target_function = target_function
+        self.stop_signal = threading.Event()
+        self.interval = interval
+        self.exc = None
+
+    def run(self):
+        """Run the target function in a loop until the stop signal is set."""
+        try:
+            while not self.stop_signal.is_set():
+                self.target_function()
+                time.sleep(self.interval)
+        except Exception as e:
+            self.exc = e
+
+    def stop(self):
+        """Set the stop signal to stop the thread."""
+        self.stop_signal.set()
+        self.join()
+        if self.exc:
+            raise self.exc
+
+    def propagate_exception(self):
+        """Raises an exception if the target function raised an exception."""
+        if self.exc:
+            raise self.exc

vessim/sil/node.py

@@ -0,0 +1,31 @@
+from typing import Set
+
+class Node:
+    """Represents a physical or virtual computing node.
+
+    This class keeps track of nodes and assigns unique IDs to each new
+    instance. It also allows the setting of a power meter and power mode.
+
+    Args:
+        id: A unique ID assigned to each node.
+        address: The network address of the node.
+        port: The application port of the node api.
+        power_mode: The power mode of the node. Default is `high performance`.
+    """
+
+    existing_ids: Set[str] = set()
+
+    def __init__(
+        self,
+        id: str,
+        address: str,
+        port: int = 8000,
+        power_mode: str = "high performance"
+    ) -> None:
+        if id in self.existing_ids:
+            raise ValueError(f"Node ID \"{id}\" already exists.")
+        self.existing_ids.add(id)
+        self.id = id
+        self.address = address
+        self.port = port
+        self.power_mode = power_mode

vessim/sil/power_meter.py

@@ -0,0 +1,44 @@
+from vessim.core.consumer import PowerMeter
+from vessim.sil.http_client import HttpClient
+from vessim.sil.loop_thread import LoopThread
+
+
+class HttpPowerMeter(PowerMeter):
+    """Power meter for an external node that implements the vessim node API.
+
+    This class represents a power meter for an external node. It creates a thread
+    that updates the power demand from the node API at a given interval.
+
+    Args:
+        interval: The interval in seconds to update the power demand.
+        server_address: The IP address of the node API.
+        port: The IP port of the node API.
+        name: The name of the power meter.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        interval: float,
+        server_address: str,
+        port: int = 8000
+    ) -> None:
+        super().__init__(name)
+        self.http_client = HttpClient(f"{server_address}:{port}")
+        self.power = 0.0
+        self.update_thread = LoopThread(self._update_power, interval)
+        self.update_thread.start()
+
+    def _update_power(self) -> None:
+        """Gets the power demand every `interval` seconds from the API server."""
+        self.power = float(self.http_client.get("/power")["power"])
+
+    def measure(self) -> float:
+        """Returns the current power demand of the node."""
+        self.update_thread.propagate_exception()
+        return self.power
+
+    def finalize(self) -> None:
+        """Terminates the power update thread when the instance is finalized."""
+        self.update_thread.stop()
+        self.update_thread.join()

vessim/sil/redis_docker.py

@@ -0,0 +1,63 @@
+from time import sleep
+import docker # type: ignore
+import redis # type: ignore
+
+
+class RedisDocker:
+    """Class for connection to a Docker container with Redis.
+
+    Args:
+        host: Host address, defaults to '127.0.0.1'.
+        port: Port for connection, defaults to 6379 as specified by Redis.
+
+    Attributes:
+        redis: The redis db that can be used to get and set key, value pairs.
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 6379) -> None:
+        self.host = host
+        self.port = port
+        try:
+            self._init_docker()
+        except docker.errors.DockerException:
+            raise RuntimeError("Please start Docker before execution.")
+        self.redis = self._connect_redis()
+
+    def _init_docker(self) -> None:
+        """Initializes Docker client and starts Docker container with Redis."""
+        client = docker.from_env()
+        self.redis_container = client.containers.run(
+            "redis:latest",
+            auto_remove=True,
+            ports={f"{self.port}/tcp": self.port},
+            detach=True,
+        )
+
+        # Check if the container has started
+        while True:
+            container_info = client.containers.get(self.redis_container.id)
+            if container_info.status == "running":
+                break
+            sleep(1)
+
+    def _connect_redis(self) -> redis.Redis:
+        """Connects to the Redis instance in the Docker container.
+
+        Waits until a connection is established.
+        """
+        db = None
+        connected = False
+        while not connected:
+            try:
+                db = redis.Redis(host=self.host, port=self.port, db=0)
+                connected = db.ping()
+            except redis.exceptions.RedisError as redis_error:
+                print(f"Error connecting to Redis: {redis_error}")
+                sleep(1)
+        assert db is not None
+        return db
+
+    def __del__(self) -> None:
+        """Stops the Docker container with Redis when instance is deleted."""
+        if self.redis_container:
+            self.redis_container.stop()

vessim/sil/sil_interface.py

@@ -0,0 +1,174 @@
+from threading import Thread
+from typing import List, Optional
+
+from vessim.core.storage import SimpleBattery, DefaultStoragePolicy, StoragePolicy
+from vessim.cosim._util import VessimSimulator, VessimModel, simplify_inputs
+from vessim.sil.api_server import ApiServer, VessimApi
+from vessim.sil.http_client import HttpClient
+from vessim.sil.node import Node
+from vessim.sil.loop_thread import LoopThread
+
+
+class SilInterfaceSim(VessimSimulator):
+    """Software-in-the-Loop (SiL) interface simulator that executes the model."""
+
+    META = {
+        "type": "time-based",
+        "models": {
+            "SilInterface": {
+                "public": True,
+                "any_inputs": True,
+                "params": [
+                    "nodes",
+                    "battery",
+                    "policy",
+                    "collection_interval",
+                    "api_host",
+                    "api_port"
+                ],
+                "attrs": []
+            },
+        },
+    }
+
+    def __init__(self) -> None:
+        self.step_size = None
+        super().__init__(self.META, _SilInterfaceModel)
+
+    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 the api server and the collector thread when the simulation finishes."""
+        super().finalize()
+        for model_instance in self.entities.values():
+            model_instance.collector_thread.stop() # type: ignore
+            model_instance.collector_thread.join() # type: ignore
+            model_instance.http_client.put("/shutdown") # type: ignore
+            model_instance.api_server.terminate() # type: ignore
+            model_instance.api_server.join() # type: ignore
+
+    def next_step(self, time):
+        return time + self.step_size
+
+
+class _SilInterfaceModel(VessimModel):
+    """Software-in-the-Loop interface to the energy system simulation.
+
+    TODO this class is still very specific to our paper use case and does not
+    generalize well to other scenarios.
+
+    Args:
+        nodes: List of vessim SiL nodes.
+        battery: SimpleBattery battery used by the system.
+        policy: The (dis)charging policy used to control the battery.
+        nodes: List of physical or virtual computing nodes.
+        collection_interval: Interval in which `/sim/collet-set` in fetched from
+            the API server.
+        api_host: Server address for the API.
+        api_port: Server port for the API.
+    """
+
+    def __init__(
+        self,
+        nodes: List[Node],
+        battery: SimpleBattery,
+        collection_interval: float,
+        policy: Optional[StoragePolicy] = None,
+        api_host: str = "127.0.0.1",
+        api_port: int = 8000
+    ):
+        self.nodes = nodes
+        self.updated_nodes: List[Node] = []
+        self.battery = battery
+        self.policy = policy if policy is not None else DefaultStoragePolicy()
+        self.p_cons = 0
+        self.p_gen = 0
+        self.p_grid = 0
+        self.ci = 0
+
+        # start server process
+        self.api_server = ApiServer(VessimApi, api_host, api_port)
+        self.api_server.start()
+        self.api_server.wait_for_startup_complete()
+
+        # init server values and wait for put request confirmation
+        self.http_client = HttpClient(f"http://{api_host}:{api_port}")
+        self.http_client.put("/sim/update", {
+            "solar": self.p_gen,
+            "ci": self.ci,
+            "battery_soc": self.battery.soc(),
+        })
+
+        self.collector_thread = LoopThread(self._api_collector, collection_interval)
+        self.collector_thread.start()
+
+    def _api_collector(self):
+        """Collects data from the API server.
+
+        The endpoint "/sim/collect-set" yields the 3 fields `battery_min_soc`,
+        `battery_grid_charge` and `nodes_power_mode`. Since multiple set
+        request of these values from different actors are possible, each of
+        these fields is a list of dictionaries with the timestamp (formated as
+        `datetime.now().isoformat()`) and the set value at that time.
+
+        TODO implement user defined collection method. Current static
+        collection method: most recent entry.
+        """
+        collection = self.http_client.get("/sim/collect-set")
+
+        # The value of the keys is None by default if no set request was made
+        # by an actor => Check if not None first.
+        if collection["battery_min_soc"]:
+            # The newest entry is the one with the highest iso timestamp.
+            newest_key = max(collection["battery_min_soc"].keys())
+            self.battery.min_soc = float(collection["battery_min_soc"][newest_key])
+
+        if collection["battery_grid_charge"]:
+            newest_key = max(collection["battery_grid_charge"].keys())
+            self.policy.grid_power = float(collection["battery_grid_charge"][newest_key])
+
+        if collection["nodes_power_mode"]:
+            newest_key = max(collection["nodes_power_mode"].keys())
+            nodes_power_mode = dict(collection['nodes_power_mode'][newest_key].items())
+            # nodes_power_mode looks e.g. like {"gcp": "normal",...}
+            # Loop through all nodes,
+            for node in self.nodes:
+                if node.id in nodes_power_mode:
+                    # update the power_mode if it changed
+                    node.power_mode = nodes_power_mode[node.id]
+                    # and save whatever node had its powermode updated to
+                    # remotely update only that nodes' power mode in step().
+                    self.updated_nodes.append(node)
+
+    def step(self, time: int, inputs: dict) -> None:
+        self.collector_thread.propagate_exception()
+        inputs = simplify_inputs(inputs)
+        self.p_cons = inputs["p_cons"]
+        self.p_gen = inputs["p_gen"]
+        self.ci = inputs["ci"]
+        self.p_grid = inputs["p_grid"]
+
+        # update values to the api server
+        def update_api_server():
+            self.http_client.put("/sim/update", {
+                "solar": self.p_gen,
+                "ci": self.ci,
+                "battery_soc": self.battery.soc(),
+            })
+        # use thread to not slow down simulation
+        api_server_update_thread = Thread(target=update_api_server)
+        api_server_update_thread.start()
+
+        # update power mode for the node remotely
+        for node in self.updated_nodes:
+            http_client = HttpClient(f"{node.address}:{node.port}")
+
+            def update_node_power_model():
+                http_client.put("/power_mode", {"power_mode": node.power_mode})
+            # use thread to not slow down simulation
+            node_update_thread = Thread(target=update_node_power_model)
+            node_update_thread.start()
+        self.updated_nodes.clear()
+