fram-core 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

framcore/components/Transmission.py

@@ -0,0 +1,198 @@
+"""Contain class describing transmission of Power commodity between nodes."""
+
+from framcore.attributes import Arrow, AvgFlowVolume, Conversion, Cost, FlowVolume, Loss, Proportion
+from framcore.components import Component, Flow
+
+
+class Transmission(Component):
+    """
+    Transmission component representing a one directional transmission line. Subclass of Component.
+
+    An object of this class represents one transmission line where power flows one direction (the other direction is
+    represented by another Transmission object). However, the actual measured power being sent can be higher than the
+    amount being recieved because of loss. One Transmission object therefore represents the viewpoints of both the
+    sender and the reciever of power on this specific line.
+
+    """
+
+    def __init__(
+        self,
+        from_node: str,
+        to_node: str,
+        max_capacity: FlowVolume = None,
+        min_capacity: FlowVolume | None = None,
+        loss: Loss | None = None,
+        tariff: Cost | None = None,
+        ramp_up: Proportion | None = None,
+        ramp_down: Proportion | None = None,
+        ingoing_volume: AvgFlowVolume | None = None,
+        outgoing_volume: AvgFlowVolume | None = None,
+    ) -> None:
+        """
+        Initialize object of the Transmission class. Perform type checks and convert arguments to expressions.
+
+        Args:
+            from_node (str): Node which power is transported from.
+            to_node (str): Destination Node.
+            max_capacity (FlowVolume, optional): Maximum transmission capacity. Defaults to None.
+            min_capacity (FlowVolume | None, optional): Minimum transmission capacity. Defaults to None.
+            loss (Loss | None, optional): Amount of power lost while transmitting. Defaults to None.
+            tariff (Cost | None, optional): Costs associated with operating this transmission line. Defaults to None.
+            ramp_up (Proportion | None, optional): Max upwards change in transmission per time. Defaults to None.
+            ramp_down (Proportion | None, optional): Max downwards change in transmission per time. Defaults to None.
+            ingoing_volume (AvgFlowVolume | None, optional): Volume of power recieved by to_node. Defaults to None.
+            outgoing_volume (AvgFlowVolume | None, optional): Volume of power sent by from_node. Defaults to None.
+
+        """
+        super().__init__()
+
+        self._check_type(from_node, str)
+        self._check_type(to_node, str)
+        self._check_type(max_capacity, FlowVolume)
+        self._check_type(min_capacity, (FlowVolume, type(None)))
+        self._check_type(loss, (Loss, type(None)))
+        self._check_type(tariff, (Cost, type(None)))
+        self._check_type(ramp_up, (Proportion, type(None)))
+        self._check_type(ramp_down, (Proportion, type(None)))
+        self._check_type(ingoing_volume, (AvgFlowVolume, type(None)))
+        self._check_type(outgoing_volume, (AvgFlowVolume, type(None)))
+
+        self._from_node = from_node
+        self._to_node = to_node
+        self._max_capacity = max_capacity
+        self._min_capacity = min_capacity
+        self._loss = loss
+        self._tariff = tariff
+        self._ramp_up = ramp_up
+        self._ramp_down = ramp_down
+
+        if outgoing_volume is None:
+            outgoing_volume = AvgFlowVolume()
+
+        if ingoing_volume is None:
+            ingoing_volume = AvgFlowVolume()
+
+        self._outgoing_volume: AvgFlowVolume = outgoing_volume
+        self._ingoing_volume: AvgFlowVolume = ingoing_volume
+
+    def get_from_node(self) -> str:
+        """Get the from node of the transmission line."""
+        return self._from_node
+
+    def set_from_node(self, node: str) -> None:
+        """Set the from node of the transmission line."""
+        self._check_type(node, str)
+        self._from_node = node
+
+    def get_to_node(self) -> str:
+        """Get the to node of the transmission line."""
+        return self._to_node
+
+    def set_to_node(self, node: str) -> None:
+        """Set the to node of the transmission line."""
+        self._check_type(node, str)
+        self._to_node = node
+
+    def get_max_capacity(self) -> FlowVolume:
+        """Get the maximum capacity (before losses) of the transmission line."""
+        return self._max_capacity
+
+    def get_min_capacity(self) -> FlowVolume:
+        """Get the minimum capacity (before losses) of the transmission line."""
+        return self._min_capacity
+
+    def set_min_capacity(self, value: FlowVolume | None) -> None:
+        """Set the minimum capacity (before losses) of the transmission line."""
+        self._check_type(value, (FlowVolume, type(None)))
+        self._min_capacity = value
+
+    def get_outgoing_volume(self) -> AvgFlowVolume:
+        """Get the outgoing (before losses) flow volume of the transmission line."""
+        return self._outgoing_volume
+
+    def get_ingoing_volume(self) -> AvgFlowVolume:
+        """Get the ingoing (after losses) flow volume of the transmission line."""
+        return self._ingoing_volume
+
+    def get_loss(self) -> Loss | None:
+        """Get the loss of the transmission line."""
+        return self._loss
+
+    def set_loss(self, loss: Loss | None) -> None:
+        """Set the loss of the transmission line."""
+        self._check_type(loss, (Loss, type(None)))
+        self._loss = loss
+
+    def get_tariff(self) -> Cost | None:
+        """Get the tariff of the transmission line."""
+        return self._tariff
+
+    def set_tariff(self, tariff: Cost | None) -> None:
+        """Set the tariff of the transmission line."""
+        self._check_type(tariff, (Cost, type(None)))
+        self._tariff = tariff
+
+    def get_ramp_up(self) -> Proportion | None:
+        """Get the ramp up profile level of the transmission line."""
+        return self._ramp_up
+
+    def set_ramp_up(self, value: Proportion | None) -> None:
+        """Set the ramp up of the transmission line."""
+        self._check_type(value, (Proportion, type(None)))
+        self._ramp_up = value
+
+    def get_ramp_down(self) -> Proportion | None:
+        """Get the ramp down of the transmission line."""
+        return self._ramp_down
+
+    def set_ramp_down(self, value: Proportion | None) -> None:
+        """Set the ramp down of the transmission line."""
+        self._check_type(value, (Proportion, type(None)))
+        self._ramp_down = value
+
+    """Implementation of Component interface"""
+
+    def _get_simpler_components(self, base_name: str) -> dict[str, Component]:
+        return {base_name + "_Flow": self._create_flow()}
+
+    def _replace_node(self, old: str, new: str) -> None:
+        if old == self._from_node:
+            self._from_node = new
+        if old == self._to_node:
+            self._to_node = new
+
+    def _create_flow(self) -> Flow:
+        arrow_volumes: dict[Arrow, FlowVolume] = dict()
+
+        flow = Flow(
+            main_node=self._from_node,
+            max_capacity=self._max_capacity,
+            volume=self._outgoing_volume,
+            arrow_volumes=arrow_volumes,
+            # ramp_up=self._ramp_up,    # TODO
+            # ramp_down=self._ramp_up,  # TODO
+        )
+
+        outgoing_arrow = Arrow(
+            node=self._from_node,
+            is_ingoing=False,
+            conversion=Conversion(value=1),
+        )
+        flow.add_arrow(outgoing_arrow)
+        arrow_volumes[outgoing_arrow] = self._outgoing_volume
+
+        # TODO: Extend Loss to support more fetures, such as quadratic losses? Needs loss param in Arrow to do this
+
+        ingoing_arrow = Arrow(
+            node=self._to_node,
+            is_ingoing=True,
+            conversion=Conversion(value=1),
+            loss=self._loss,
+        )
+        flow.add_arrow(ingoing_arrow)
+        arrow_volumes[ingoing_arrow] = self._ingoing_volume
+
+        if self._tariff is not None:
+            flow.add_cost_term("tariff", self._tariff)
+
+        return flow

framcore/components/_PowerPlant.py

@@ -0,0 +1,81 @@
+from framcore.attributes import AvgFlowVolume, Cost, FlowVolume
+from framcore.components import Component
+
+
+class _PowerPlant(Component):
+    """
+    PowerPlant parent class component representing a power plant. Subclass of Component.
+
+    This class models a powerplant with various attributes such as power node,
+    capacity, VOC levels and profile, and production.
+
+    Functions that are dependent on commodity nodes other than power are defined in the spesific power plant components.
+    """
+
+    def __init__(
+        self,
+        power_node: str,
+        max_capacity: FlowVolume,
+        min_capacity: FlowVolume | None,
+        voc: Cost | None = None,
+        production: AvgFlowVolume | None = None,
+    ) -> None:
+        """Initialize the  class."""
+        super().__init__()
+
+        self._check_type(power_node, str)
+        self._check_type(max_capacity, FlowVolume)
+        self._check_type(min_capacity, (FlowVolume, type(None)))
+        self._check_type(voc, (Cost, type(None)))
+        self._check_type(production, (AvgFlowVolume, type(None)))
+
+        self._power_node = power_node
+        self._max_capacity = max_capacity
+        self._min_capacity = min_capacity
+        self._voc = voc
+
+        if not production:
+            production = AvgFlowVolume()
+
+        self._production = production
+
+    def get_max_capacity(self) -> FlowVolume:
+        """Get the capacity of the power unit."""
+        return self._max_capacity
+
+    def get_production(self) -> AvgFlowVolume:
+        """Get the production volume of the power unit."""
+        return self._production
+
+    def get_min_capacity(self) -> FlowVolume | None:
+        """Get the minimum capacity of the power unit."""
+        return self._min_capacity
+
+    def set_min_capacity(self, value: FlowVolume | None) -> None:
+        """Set the minimum capacity of the power unit."""
+        self._check_type(value, (FlowVolume, type(None)))
+        self._min_capacity = value
+
+    def get_power_node(self) -> str:
+        """Get the power node of the power unit."""
+        return self._power_node
+
+    def set_power_node(self, power_node: str) -> None:
+        """Set the power node of the power unit."""
+        self._check_type(power_node, str)
+        self._power_node = power_node
+
+    def get_voc(self) -> Cost | None:
+        """Get the variable operating cost (VOC) level of the power unit."""
+        return self._voc
+
+    def set_voc(self, voc: Cost | None) -> None:
+        """Set the variable operating cost (VOC) level of the power unit."""
+        self._check_type(voc, (Cost, type(None)))
+        self._voc = voc
+
+    """Implementation of Component interface"""
+
+    def _replace_node(self, old: str, new: str) -> None:
+        if old == self._power_node:
+            self._power_node = new

framcore/components/__init__.py

@@ -0,0 +1,22 @@
+# ruff: noqa: I001
+
+from framcore.components.Component import Component
+from framcore.components.Node import Node
+from framcore.components.Flow import Flow
+from framcore.components.Demand import Demand
+from framcore.components.HydroModule import HydroModule
+from framcore.components.Thermal import Thermal
+from framcore.components.Transmission import Transmission
+from framcore.components.wind_solar import Solar, Wind
+
+__all__ = [
+    "Component",
+    "Demand",
+    "Flow",
+    "HydroModule",
+    "Node",
+    "Solar",
+    "Thermal",
+    "Transmission",
+    "Wind",
+]

framcore/components/wind_solar.py

@@ -0,0 +1,82 @@
+from framcore.attributes import Arrow, AvgFlowVolume, Conversion, Cost, FlowVolume
+from framcore.components import Flow
+from framcore.components._PowerPlant import _PowerPlant
+
+
+class _WindSolar(_PowerPlant):
+    """
+    Wind and Solar class component representing a wind and solar power plant. Subclass of PowerPlant.
+
+    This class models a wind or solar power plant with various attributes inherited from the parent class PowerPlant.
+    """
+
+    def __init__(
+        self,
+        power_node: str,
+        max_capacity: FlowVolume,
+        voc: Cost | None = None,
+        production: AvgFlowVolume | None = None,
+    ) -> None:
+        """
+        Initialize the Wind and Solar class.
+
+        Args:
+            power_node (str): Reference to a power Node to produce to.
+            max_capacity (FlowVolume): Maximum capacity.
+            voc (Cost | None, optional): Variable operational costs. Defaults to None.
+            production (AvgFlowVolume | None, optional): Actual production. Defaults to None.
+
+        """
+        super().__init__(
+            power_node=power_node,
+            max_capacity=max_capacity,
+            min_capacity=None,
+            voc=voc,
+            production=production,
+        )
+
+    """Implementation of Component interface"""
+
+    def _get_simpler_components(self, base_name: str) -> dict[str, Flow]:
+        return {base_name + "_Flow": self._create_flow()}
+
+    def _create_flow(self) -> Flow:
+        flow = Flow(
+            main_node=self._power_node,
+            max_capacity=self._max_capacity,
+            volume=self._production,
+        )
+
+        flow.add_arrow(Arrow(node=self._power_node, is_ingoing=True, conversion=Conversion(value=1)))
+
+        if self._voc:
+            flow.add_cost_term("VOC", self._voc)
+        else:
+            flow.set_min_capacity(self._max_capacity)
+            flow.set_exogenous()
+
+        return flow
+
+
+class Wind(_WindSolar):
+    """
+    Wind power component.
+
+    Has attributes for power node, capacity, variable operation cost, and production.
+
+    Compatible with WindSolarAggregator.
+    """
+
+    pass
+
+
+class Solar(_WindSolar):
+    """
+    Solar power component.
+
+    Has attributes for power node, capacity, variable operation cost, and production.
+
+    Compatible with WindSolarAggregator.
+    """
+
+    pass

framcore/curves/Curve.py

@@ -0,0 +1,44 @@
+"""Curve interface."""
+
+from abc import ABC, abstractmethod
+
+from numpy.typing import NDArray
+
+from framcore import Base
+
+
+class Curve(Base, ABC):
+    """Curve interface class."""
+
+    @abstractmethod
+    def get_unique_name(self) -> str | None:
+        """Return unique name of curve."""
+        pass
+
+    @abstractmethod
+    def get_x_axis(self, is_float32: bool) -> NDArray:
+        """
+        Get array of x axis values.
+
+        Args:
+            is_float32 (bool): Flag for converting the array of values to numpy float32.
+
+        Returns:
+            NDArray: Numpy array of values.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_y_axis(self, is_float32: bool) -> NDArray:
+        """
+        Get array of y axis values.
+
+        Args:
+            is_float32 (bool): Flag for converting the array of values to numpy float32.
+
+        Returns:
+            NDArray: Numpy array of values.
+
+        """
+        pass

framcore/curves/LoadedCurve.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore.curves import Curve
+from framcore.fingerprints import Fingerprint
+
+if TYPE_CHECKING:
+    from framcore.loaders import CurveLoader
+
+
+class LoadedCurve(Curve):
+    """
+    Represents a curve loaded from a CurveLoader.
+
+    Methods
+    -------
+    get_unique_name()
+        Returns the unique name of the curve.
+    get_x_axis(precision=None)
+        Returns the x-axis data.
+    get_y_axis(precision=None)
+        Returns the y-axis data.
+    get_x_unit()
+        Returns the unit for the x-axis.
+    get_y_unit()
+        Returns the unit for the y-axis.
+    get_loader()
+        Returns the loader instance.
+    get_fingerprint()
+        Returns the fingerprint of the curve.
+
+    """
+
+    def __init__(self, curve_id: str, loader: CurveLoader) -> None:
+        """
+        Initialize a LoadedCurve instance.
+
+        Parameters
+        ----------
+        curve_id : str
+            Identifier for the curve.
+        loader : CurveLoader
+            Loader instance used to retrieve curve data.
+
+        """
+        self._curve_id = curve_id
+        self._loader = loader
+
+        # TODO: get from loader
+        self._reference_period = None
+
+    def __repr__(self) -> str:
+        """Return a string representation of the LoadedCurve instance."""
+        return f"{type(self).__name__}(curve_id={self._curve_id},loader={self._loader},x_unit={self.get_x_unit()}),y_unit={self.get_y_unit()}),"
+
+    def get_unique_name(self) -> str:
+        """
+        Return the unique name of the curve.
+
+        Returns
+        -------
+        str
+            The unique name for the curve.
+
+        """
+        return self._curve_id
+
+    def get_x_axis(self, is_float32: bool) -> NDArray:
+        """
+        Get x axis values of the curve as a numpy array.
+
+        Args:
+            is_float32 (bool): Flag for converting the array of values to numpy float32.
+
+        Returns:
+            NDArray: Numpy array of x axis values.
+
+        """
+        x_axis = self._loader.get_x_axis(self._curve_id)
+        if is_float32:
+            x_axis = x_axis.astype(np.float32)
+        return x_axis
+
+    def get_y_axis(self, is_float32: bool) -> NDArray:
+        """
+        Get y axis values of the curve as a numpy array.
+
+        Args:
+            is_float32 (bool): Flag for converting the array of values to numpy float32.
+
+        Returns:
+            NDArray: Numpy array of y axis values.
+
+        """
+        y_axis = self._loader.get_y_axis(self._curve_id)
+        if is_float32:
+            y_axis = y_axis.astype(np.float32)
+        return y_axis
+
+    def get_x_unit(self) -> str:
+        """
+        Return the unit for the x-axis.
+
+        Returns
+        -------
+        str
+            The unit for the x-axis.
+
+        """
+        return self._loader.get_x_unit(self._curve_id)
+
+    def get_y_unit(self) -> str:
+        """
+        Return the unit for the y-axis.
+
+        Returns
+        -------
+        str
+            The unit for the y-axis.
+
+        """
+        return self._loader.get_y_unit(self._curve_id)
+
+    def get_loader(self) -> CurveLoader:
+        """
+        Return the loader instance used to retrieve curve data.
+
+        Returns
+        -------
+        CurveLoader
+            The loader instance associated with this curve.
+
+        """
+        return self._loader
+
+    def get_fingerprint(self) -> Fingerprint:
+        """
+        Return the fingerprint of the curve.
+
+        The method is not implemented yet.
+        """
+        raise NotImplementedError("Not implemented yet.")

framcore/curves/__init__.py

@@ -0,0 +1,9 @@
+# framcore/curves/__init__.py
+
+from framcore.curves.Curve import Curve
+from framcore.curves.LoadedCurve import LoadedCurve
+
+__all__ = [
+    "Curve",
+    "LoadedCurve",
+]

framcore/events/__init__.py

@@ -0,0 +1,21 @@
+# framcore/events/__init__.py
+
+from framcore.events.events import (
+    get_event_handler,
+    set_event_handler,
+    send_debug_event,
+    send_error_event,
+    send_event,
+    send_info_event,
+    send_warning_event,
+)
+
+__all__ = [
+    "get_event_handler",
+    "send_debug_event",
+    "send_error_event",
+    "send_event",
+    "send_info_event",
+    "send_warning_event",
+    "set_event_handler",
+]

framcore/events/events.py

@@ -0,0 +1,51 @@
+"""
+Event system.
+
+All code in the core use these functions to communicate events.
+
+Calling systems (e.g. workflow codes) can get events by hooking into SEND_EVENT_CHANNEL.
+"""
+
+_EVENT_HANDLER = None
+
+
+def set_event_handler(handler: object | None) -> None:
+    """Set event handler if any."""
+    if handler is not None and (not hasattr(handler, "handle_event") or not callable(handler.handle_event)):
+        message = "Given handler does not implement handle_event."
+        raise ValueError(message)
+    global _EVENT_HANDLER  # noqa: PLW0603 # TODO: unsafe?
+    _EVENT_HANDLER = handler
+
+
+def get_event_handler() -> object | None:
+    """Get event handler if any."""
+    return _EVENT_HANDLER
+
+
+def send_event(sender: object, event_type: str, **kwargs: dict[str, object]) -> None:
+    """All events in core should use this."""
+    if _EVENT_HANDLER is None:
+        print(event_type, kwargs)
+    else:
+        _EVENT_HANDLER.handle_event(sender, event_type, **kwargs)
+
+
+def send_warning_event(sender: object, message: str) -> None:
+    """Use this to send warning event."""
+    send_event(sender, "warning", message=message)
+
+
+def send_error_event(sender: object, message: str, exception_type_name: str, traceback: str) -> None:
+    """Use this to send error event."""
+    send_event(sender, "error", message=message, exception_type_name=exception_type_name, traceback=traceback)
+
+
+def send_info_event(sender: object, message: str) -> None:
+    """Use this to send info event."""
+    send_event(sender, "info", message=message)
+
+
+def send_debug_event(sender: object, message: str) -> None:
+    """Use this to send debug event."""
+    send_event(sender, "debug", message=message)