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

framcore/components/Component.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+from framcore import Base
+from framcore.metadata import Meta
+
+
+class Component(Base, ABC):
+    """
+    Components describe the main elements in the energy system. Can have additional Attributes and Metadata.
+
+    We have high-level and low-level Components. High-level Components, such as a HydroModule,
+    can be decomposed into low-level Components like Flows and Nodes. The high-level description lets
+    analysts work with recognizable domain objects, while the low-level descriptions enable generic algorithms
+    that minimize code duplication and simplify data manipulation.
+
+    Some energy market models like JulES, SpineOpt and PyPSA also have a generic description of the system,
+    so this two-tier system can be used to easier adapt the dataset to their required formats.
+
+    The method Component.get_simpler_components() is used to decompose high-level Components into low-level
+    Components. This can also be used together with the utility function get_supported_components() to transform
+    a set of Components into a set that only contains supported Component types.
+
+    Result attributes are initialized in the high-level Components. When they are transferred to low-level Components,
+    and the results are set by a model like JulES, the results will also appear in the high-level Components.
+
+    Nodes, Flows and Arrows are the main building blocks in FRAM's low-level representation of energy systems.
+    Node represent a point where a commodity can possibly be traded, stored or pass through.
+    Movement between Nodes is represented by Flows and Arrows. Flows represent a commodity flow,
+    and can have Arrows that each describe contribution of the Flow into a Node.
+    The Arrows have direction to determine input or output, and parameters for the contribution of the
+    Flow to the Node (conversion, efficiency and loss).
+    """
+
+    def __init__(self) -> None:
+        """Set mandatory private variables."""
+        self._parent: Component | None = None
+        self._meta: dict[str, Meta] = dict()
+
+    def add_meta(self, key: str, value: Meta) -> None:
+        """Add metadata to component. Overwrite if already exist."""
+        self._check_type(key, str)
+        self._check_type(value, Meta)
+        self._meta[key] = value
+
+    def get_meta(self, key: str) -> Meta | None:
+        """Get metadata from component or return None if not exist."""
+        self._check_type(key, str)
+        return self._meta.get(key, None)
+
+    def get_meta_keys(self) -> Iterable[str]:
+        """Get iterable with all metakeys in component."""
+        return self._meta.keys()
+
+    def get_simpler_components(
+        self,
+        base_name: str,
+    ) -> dict[str, Component]:
+        """
+        Return representation of self as dict of named simpler components.
+
+        The base_name should be unique within a model instance, and should
+        be used to prefix name of all simpler components.
+
+        Insert self as parent in each child.
+
+        Transfer metadata to each child.
+        """
+        self._check_type(base_name, str)
+        components = self._get_simpler_components(base_name)
+        assert base_name not in components, f"base_name: {base_name} should not be in \ncomponent: {self}"
+        components: dict[str, Component]
+        self._check_type(components, dict)
+        for name, c in components.items():
+            self._check_type(name, str)
+            self._check_type(c, Component)
+            self._check_component_not_self(c)
+            c: Component
+            c._parent = self  # noqa: SLF001
+        for key in self.get_meta_keys():
+            value = self.get_meta(key)
+            for c in components.values():
+                c.add_meta(key, value)
+        return components
+
+    def get_parent(self) -> Component | None:
+        """Return parent if any, else None."""
+        self._check_type(self._parent, (Component, type(None)))
+        self._check_component_not_self(self._parent)
+        return self._parent
+
+    def get_parents(self) -> list[Component]:
+        """Return list of all parents, including self."""
+        child = self
+        parent = child.get_parent()
+        parents = [child]
+        while parent is not None:
+            child = parent
+            parent = child.get_parent()
+            parents.append(child)
+        self._check_unique_parents(parents)
+        return parents
+
+    def get_top_parent(self) -> Component:
+        """Return topmost parent. (May be object self)."""
+        parents = self.get_parents()
+        return parents[-1]
+
+    def replace_node(self, old: str, new: str) -> None:
+        """Replace old Node with new. Not error if no match."""
+        self._check_type(old, str)
+        self._check_type(new, str)
+        self._replace_node(old, new)
+
+    def _check_component_not_self(self, other: Component | None) -> None:
+        if not isinstance(other, Component):
+            return
+        if self != other:
+            return
+        message = f"Expected other component than {self}."
+        raise TypeError(message)
+
+    def _check_unique_parents(self, parents: list[Component]) -> None:
+        if len(parents) > len(set(parents)):
+            message = f"Parents for {self} are not unique."
+            raise TypeError(message)
+
+    @abstractmethod
+    def _replace_node(self, old: str, new: str) -> None:
+        pass
+
+    @abstractmethod
+    def _get_simpler_components(self, base_name: str) -> dict[str, Component]:
+        pass

framcore/components/Demand.py

@@ -0,0 +1,144 @@
+"""Demand class."""
+
+from framcore.attributes import Arrow, AvgFlowVolume, Conversion, ElasticDemand, FlowVolume, ReservePrice
+from framcore.components import Component, Flow
+from framcore.expressions import Expr, ensure_expr
+from framcore.timevectors import TimeVector
+
+
+class Demand(Component):
+    """Demand class representing a simple demand with possible reserve price. Subclass of Component."""
+
+    def __init__(
+        self,
+        node: str,
+        capacity: FlowVolume | None = None,
+        reserve_price: ReservePrice | None = None,
+        elastic_demand: ElasticDemand | None = None,
+        temperature_profile: Expr | str | TimeVector | None = None,
+        consumption: AvgFlowVolume | None = None,
+    ) -> None:
+        """
+        Initialize the Demand class.
+
+        Args:
+            node (str): Node which this Demand consumes power on.
+            capacity (FlowVolume | None, optional): Maximum consumption capacity. Defaults to None.
+            reserve_price (ReservePrice | None, optional): Price in node at which the Demand will stop consumption. Defaults to None.
+            elastic_demand (ElasticDemand | None, optional): Describe changes in consumption based on commodity price in node. Defaults to None.
+            temperature_profile (Expr | str | TimeVector | None, optional): Describe changes in consumption based on temperatures. Defaults to None.
+            consumption (AvgFlowVolume | None, optional): Actual calculated consumption. Defaults to None.
+
+        Raises:
+            ValueError: When both reserve_price and elastic_demand is passed as arguments. This is ambiguous.
+
+        """
+        super().__init__()
+        self._check_type(node, str)
+        self._check_type(capacity, (FlowVolume, type(None)))
+        self._check_type(reserve_price, (ReservePrice, type(None)))
+        self._check_type(elastic_demand, (ElasticDemand, type(None)))
+        self._check_type(consumption, (AvgFlowVolume, type(None)))
+
+        if reserve_price is not None and elastic_demand is not None:
+            message = "Cannot have 'reserve_price' and 'elastic_demand' at the same time."
+            raise ValueError(message)
+
+        self._node = node
+        self._capacity = capacity
+        self._reserve_price = reserve_price
+        self._elastic_demand = elastic_demand
+        self._temperature_profile = ensure_expr(temperature_profile, is_profile=True)
+
+        if consumption is None:
+            consumption = AvgFlowVolume()
+
+        self._consumption: AvgFlowVolume = consumption
+
+    def get_capacity(self) -> FlowVolume:
+        """Get the capacity of the demand component."""
+        return self._capacity
+
+    def get_consumption(self) -> AvgFlowVolume:
+        """Get the consumption of the demand component."""
+        return self._consumption
+
+    def get_node(self) -> str:
+        """Get the node of the demand component."""
+        return self._node
+
+    def set_node(self, node: str) -> None:
+        """Set the node of the demand component."""
+        self._check_type(node, str)
+        self.node = node
+
+    def get_reserve_price(self) -> ReservePrice | None:
+        """Get the reserve price level of the demand component."""
+        return self._reserve_price
+
+    def set_reserve_price(self, reserve_price: ReservePrice | None) -> None:
+        """Set the reserve price level of the demand component."""
+        self._check_type(reserve_price, (ReservePrice, type(None)))
+        if self._elastic_demand and reserve_price:
+            message = "Cannot set reserve_price when elastic_demand is not None."
+            raise ValueError(message)
+        self._reserve_price = reserve_price
+
+    def get_elastic_demand(self) -> ElasticDemand | None:
+        """Get the elastic demand of the demand component."""
+        return self._elastic_demand
+
+    def set_elastic_demand(self, elastic_demand: ElasticDemand | None) -> None:
+        """Set the elastic demand of the demand component."""
+        self._check_type(elastic_demand, (ElasticDemand, type(None)))
+        if self._reserve_price is not None and elastic_demand is not None:
+            message = "Cannot set elastic_demand when reserve_price is not None."
+            raise ValueError(message)
+        self._elastic_demand = elastic_demand
+
+    def get_temperature_profile(self) -> Expr | None:
+        """Get the temperature profile of the demand component."""
+        return self._temperature_profile
+
+    def set_temperature_profile(self, temperature_profile: Expr | str | None) -> None:
+        """Set the temperature profile of the demand component."""
+        self._check_type(temperature_profile, (Expr, str, TimeVector, type(None)))
+        self._temperature_profile = ensure_expr(temperature_profile, is_profile=True)
+
+    """Implementation of Component interface"""
+
+    def _replace_node(self, old: str, new: str) -> None:
+        if old == self._node:
+            self._node = new
+        else:
+            message = f"{old} not found in {self}. Expected existing node {self._node}."
+            raise ValueError(message)
+
+    def _get_simpler_components(self, base_name: str) -> dict[str, Component]:
+        return {base_name + "_Flow": self._create_flow()}
+
+    def _create_flow(self) -> Flow:
+        is_exogenous = self._elastic_demand is None and self._reserve_price is None
+
+        flow = Flow(
+            main_node=self._node,
+            max_capacity=self._capacity,
+            min_capacity=self._capacity if is_exogenous else None,
+            volume=self._consumption,
+            arrow_volumes=None,
+            is_exogenous=is_exogenous,
+        )
+
+        power_arrow = Arrow(self._node, False, conversion=Conversion(value=1))
+        flow.add_arrow(power_arrow)
+
+        if self._reserve_price is not None:
+            flow.add_cost_term("reserve_price", self._reserve_price)
+
+        # TODO: Implement correctly when Curve is ready. For now, model as inelastic consumer w. reserve_price
+        elif self._elastic_demand is not None:
+            price = self._elastic_demand.get_max_price()
+            reserve_price = ReservePrice(level=price.get_level(), profile=price.get_profile())
+            flow.add_cost_term("reserve_price", cost_term=reserve_price)
+
+        return flow

framcore/components/Flow.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from framcore.attributes import Arrow, AvgFlowVolume, FlowVolume, ObjectiveCoefficient, StartUpCost
+from framcore.components import Component
+from framcore.fingerprints import Fingerprint
+from framcore.loaders import Loader
+
+if TYPE_CHECKING:
+    from framcore.loaders import Loader
+
+
+class Flow(Component):
+    """
+    Represents a commodity flow in or out of one or more nodes. Can have Attributes and Metadata.
+
+    Main attributes are arrows, main_node, max_capacity, min_capacity, startupcost and if it is exogenous.
+
+    Arrows describes contribution of a Flow into a Node. Has direction to determine input or output,
+    and parameters for the contribution of the Flow to the Node (conversion, efficiency, loss).
+    Nodes, Flows and Arrows are the main building blocks in FRAM's low-level representation of energy systems.
+    """
+
+    def __init__(
+        self,
+        main_node: str,
+        max_capacity: FlowVolume | None = None,
+        min_capacity: FlowVolume | None = None,
+        startupcost: StartUpCost | None = None,
+        volume: AvgFlowVolume | None = None,
+        arrow_volumes: dict[Arrow, AvgFlowVolume] | None = None,
+        is_exogenous: bool = False,
+    ) -> None:
+        """
+        Initialize Flow with main node, capacity, and startup cost.
+
+        Args:
+            main_node (str): Node which the Flow is primarily associated with.
+            max_capacity (FlowVolume | None, optional): Maximum capacity of the Flow. Defaults to None.
+            min_capacity (FlowVolume | None, optional): Minimum capacity of the Flow. Defaults to None.
+            startupcost (StartUpCost | None, optional): Costs associated with starting up this Flow. Defaults to None.
+            volume (AvgFlowVolume | None, optional): The actual volume carried by this Flow at a given moment. Defaults to None.
+            arrow_volumes (dict[Arrow, AvgFlowVolume] | None, optional): Possibility to store a version of volume for each Arrow. Can account for conversion,
+            efficiency and loss to represent the result for different commodities and units. Defaults to None.
+            is_exogenous (bool, optional): Flag denoting if a Solver should calculate the volumes associated with this flow or use its predefined volume.
+                                           Defaults to False.
+
+        """
+        super().__init__()
+        self._check_type(main_node, str)
+        self._check_type(max_capacity, (FlowVolume, type(None)))
+        self._check_type(min_capacity, (FlowVolume, type(None)))
+        self._check_type(startupcost, (StartUpCost, type(None)))
+        self._check_type(volume, (FlowVolume, type(None)))
+        self._check_type(arrow_volumes, (dict, type(None)))
+        self._main_node: str = main_node
+        self._max_capacity = max_capacity
+        self._min_capacity = min_capacity
+        self._startupcost = startupcost
+        self._arrows: set[Arrow] = set()
+        self._cost_terms: dict[str, ObjectiveCoefficient] = dict()
+        self._is_exogenous: bool = is_exogenous
+
+        if not volume:
+            volume = AvgFlowVolume()
+        self._volume: AvgFlowVolume = volume
+
+        if arrow_volumes is None:
+            arrow_volumes = dict()
+        self._arrow_volumes: dict[Arrow, AvgFlowVolume] = arrow_volumes
+
+    def is_exogenous(self) -> bool:
+        """Return True if Flow is exogenous."""
+        return self._is_exogenous
+
+    def set_exogenous(self) -> None:
+        """
+        Treat flow as fixed variable.
+
+        Use volume if it exists.
+        If no volume, then try to use
+        min_capacity and max_capacity, which must
+        be equal. Error if this fails.
+        """
+        self._is_exogenous = True
+
+    def set_endogenous(self) -> None:
+        """
+        Treat flow as decision variable.
+
+        Volume should be updated with results after a solve.
+        """
+        self._is_exogenous = False
+
+    def get_main_node(self) -> str:
+        """Get the main node of the flow."""
+        return self._main_node
+
+    def get_volume(self) -> AvgFlowVolume:
+        """Get the volume of the flow."""
+        return self._volume
+
+    def get_arrow_volumes(self) -> dict[Arrow, AvgFlowVolume]:
+        """Get dict of volume converted to volume at node pointed to by Arrow."""
+        return self._arrow_volumes
+
+    def get_max_capacity(self) -> FlowVolume | None:
+        """Get the maximum capacity of the flow."""
+        return self._max_capacity
+
+    def set_max_capacity(self, capacity: FlowVolume | None) -> None:
+        """Set the maximum capacity of the flow."""
+        self._check_type(capacity, (FlowVolume, type(None)))
+        self._max_capacity = capacity
+
+    def get_min_capacity(self) -> FlowVolume | None:
+        """Get the minimum capacity of the flow."""
+        return self._min_capacity
+
+    def set_min_capacity(self, capacity: FlowVolume | None) -> None:
+        """Set the minimum capacity of the flow."""
+        self._check_type(capacity, (FlowVolume, type(None)))
+        self._min_capacity = capacity
+
+    def get_startupcost(self) -> StartUpCost | None:
+        """Get the startup cost of the flow."""
+        self._check_type(self._startupcost, (StartUpCost, type(None)))
+        return self._startupcost
+
+    def set_startupcost(self, startupcost: StartUpCost | None) -> None:
+        """Set the startup cost of the flow."""
+        self._check_type(startupcost, (StartUpCost, type(None)))
+        self._startupcost = startupcost
+
+    def get_arrows(self) -> set[Arrow]:
+        """Get the arrows of the flow."""
+        return self._arrows
+
+    def add_arrow(self, arrow: Arrow) -> None:
+        """Add an arrow to the flow."""
+        self._check_type(arrow, Arrow)
+        self._arrows.add(arrow)
+
+    def add_cost_term(self, key: str, cost_term: ObjectiveCoefficient) -> None:
+        """Add a cost term to the flow."""
+        self._check_type(key, str)
+        self._check_type(cost_term, ObjectiveCoefficient)
+        self._cost_terms[key] = cost_term
+
+    def get_cost_terms(self) -> dict[str, ObjectiveCoefficient]:
+        """Get the cost terms of the flow."""
+        return self._cost_terms
+
+    def add_loaders(self, loaders: set[Loader]) -> None:
+        """Add loaders stored in attributes to loaders."""
+        from framcore.utils import add_loaders_if
+
+        add_loaders_if(loaders, self.get_volume())
+        add_loaders_if(loaders, self.get_max_capacity())
+        add_loaders_if(loaders, self.get_min_capacity())
+
+        for cost in self.get_cost_terms().values():
+            add_loaders_if(loaders, cost)
+
+        for arrow in self.get_arrows():
+            add_loaders_if(loaders, arrow)
+
+        for volume in self.get_arrow_volumes().values():
+            add_loaders_if(loaders, volume)
+
+    def _replace_node(self, old: str, new: str) -> None:
+        # Component.replace_node does input type check
+        if old == self._main_node:
+            self._main_node = new
+        for a in self._arrows:
+            a: Arrow
+            if a.get_node() == old:
+                a.set_node(new)
+                return
+
+    def _get_simpler_components(self, _: str) -> dict[str, Component]:
+        return dict()
+
+    def _get_fingerprint(self) -> Fingerprint:
+        refs = {}
+        refs["_main_node"] = self._main_node
+
+        return self.get_fingerprint_default()