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

framcore/components/HydroModule.py

@@ -0,0 +1,371 @@
+from framcore.attributes import Arrow, AvgFlowVolume, Conversion, FlowVolume, HydroBypass, HydroGenerator, HydroPump, HydroReservoir, WaterValue
+from framcore.components import Component, Flow, Node
+
+
+class HydroModule(Component):
+    """
+    HydroModules represents a physical element in a river system, with its topology and other attributes.
+
+    The hydromodule can contain a HydroReservoir, HydroGenerator, HydroPump, HydroBypass and local inflow, aswell as the topological attributes release_to
+    and spill_to:
+
+    - HydroGenerator uses the release pathway of the HydroModule to generate power, while HydroPump has its own water way that consumes
+      power. Both HydroGenerator and HydroPump connects to power nodes.
+    - HydroBypass also have attributes that define the topology of the river system.
+    - HydroReservoir represents the water storage of the HydroModule.
+    - The hydraulic_coupling attribute is used to identify which HydroModules have hydraulic coupled reservoirs.
+
+
+    Results for the release volume, spill volume and the water value are stored directly in the HydroModule, while the production, pumping,
+    reservoir volume and bypass volume are stored in the attributes.
+
+    HydroModule is compatible with HydroAggregator for aggregation of multiple HydroModules into one.
+
+    """
+
+    # We add this to module name to get corresponding node name
+    _NODE_NAME_POSTFIX = "_node"
+
+    def __init__(
+        self,
+        release_to: str | None = None,  # Must be reference to another HydroModule
+        release_capacity: FlowVolume | None = None,
+        generator: HydroGenerator | None = None,  # attribute
+        pump: HydroPump | None = None,
+        inflow: AvgFlowVolume | None = None,
+        reservoir: HydroReservoir | None = None,  # attribute
+        hydraulic_coupling: int = 0,
+        bypass: HydroBypass | None = None,  # attribute
+        spill_to: str | None = None,  # Must be reference to another HydroModule
+        commodity: str = "Hydro",
+        water_value: WaterValue | None = None,
+        release_volume: AvgFlowVolume | None = None,
+        spill_volume: AvgFlowVolume | None = None,
+    ) -> None:
+        """
+        Initialize the HydroModule with its parameters.
+
+        Args:
+            release_to (str | None, optional): Reference to another HydroModule which recieves the water releases through the main release. Defaults to None.
+            release_capacity (FlowVolume | None): Amount of water which can be released via main release at a given moment. Defaults to None.
+            generator (HydroGenerator | None, optional): Represents generation of electricity from the movement of water through the Modules main release
+                                                        pathway. Defaults to None.
+            pump (HydroPump | None): Pump associated with this Module. Can move water to another using power. Defaults to None.
+            inflow (AvgFlowVolume | None, optional): The local inflow of the HydroModule. Defaults to None.
+            reservoir (HydroReservoir | None, optional): The Modules water storage. Defaults to None.
+            hydraulic_coupling (int): Number other than 0 if the HydroModules reservoir is hydraulic coupled to another reservoir. Defaults to 0.
+                                                        TODO: Replace with HydraulicCoupling class
+            bypass (HydroBypass | None, optional): Bypass water way. Defaults to None.
+            spill_to (str | None): Reference to another Module recieving this ones spill volume. Defaults to None.
+            commodity (str, optional): Commodity of the hydro node. Defaults to "Hydro".
+            water_value (WaterValue | None, optional): Water value of the reservoir in currency per water volume. Defaults to None.
+                                                        TODO: Allow water values with multiple demimensions?
+            release_volume (AvgFlowVolume | None, optional): Volume of water released via main waterway. Defaults to None.
+            spill_volume (AvgFlowVolume | None, optional): Volume of water spilled. Defaults to None.
+
+        """
+        super().__init__()
+        self._check_type(release_to, (str, type(None)))
+        self._check_type(release_capacity, (FlowVolume, type(None)))
+        self._check_type(generator, (HydroGenerator, type(None)))
+        self._check_type(pump, (HydroPump, type(None)))
+        self._check_type(inflow, (AvgFlowVolume, type(None)))
+        self._check_type(reservoir, (HydroReservoir, type(None)))
+        self._check_type(hydraulic_coupling, int)
+        self._check_type(bypass, (HydroBypass, type(None)))
+        self._check_type(spill_to, (str, type(None)))
+        self._check_type(commodity, str)
+        self._check_type(water_value, (WaterValue, type(None)))
+        self._check_type(release_volume, (AvgFlowVolume, type(None)))
+        self._check_type(spill_volume, (AvgFlowVolume, type(None)))
+
+        self._release_to = release_to
+        self._release_capacity = release_capacity
+        self._generator = generator
+        self._pump = pump
+        self._inflow = inflow
+        self._reservoir = reservoir
+        self._hydraulic_coupling = hydraulic_coupling
+        self._bypass = bypass
+        self._spill_to = spill_to
+        self._commodity = commodity
+
+        if not water_value:
+            water_value = WaterValue()
+
+        if not release_volume:
+            release_volume = AvgFlowVolume()
+
+        if not spill_volume:
+            spill_volume = AvgFlowVolume()
+
+        self._water_value: WaterValue = water_value
+        self._release_volume: AvgFlowVolume = release_volume
+        self._spill_volume: AvgFlowVolume = spill_volume
+
+    def get_release_capacity(self) -> FlowVolume | None:
+        """Get the capacity of the thermal unit."""
+        return self._release_capacity
+
+    def get_hydraulic_coupling(self) -> int:
+        """Get the Modules hydraulic code."""
+        return self._hydraulic_coupling
+
+    def get_reservoir(self) -> HydroReservoir | None:
+        """Get the reservoir of the hydro module."""
+        return self._reservoir
+
+    def set_reservoir(self, reservoir: HydroReservoir | None) -> None:
+        """Set the reservoir of the hydro module."""
+        self._check_type(reservoir, (HydroReservoir, type(None)))
+        self._reservoir = reservoir
+
+    def get_pump(self) -> HydroPump | None:
+        """Get the pump of the hydro module."""
+        return self._pump
+
+    def set_pump(self, pump: HydroPump | None) -> None:
+        """Set the pump of the hydro module."""
+        self._check_type(pump, (HydroPump, type(None)))
+        self._pump = pump
+
+    def get_generator(self) -> HydroGenerator | None:
+        """Get the generator of the hydro module."""
+        return self._generator
+
+    def set_generator(self, generator: HydroGenerator | None) -> None:
+        """Set the generator of the hydro module."""
+        self._check_type(generator, (HydroGenerator, type(None)))
+        self._generator = generator
+
+    def get_bypass(self) -> HydroBypass | None:
+        """Get the bypass of the hydro module."""
+        return self._bypass
+
+    def set_bypass(self, bypass: HydroBypass | None) -> None:
+        """Set the bypass of the hydro module."""
+        self._check_type(bypass, (HydroBypass, type(None)))
+        self._bypass = bypass
+
+    def get_inflow(self) -> AvgFlowVolume | None:
+        """Get the inflow of the hydro module."""
+        return self._inflow
+
+    def set_inflow(self, inflow: AvgFlowVolume | None) -> None:
+        """Set the inflow of the hydro module."""
+        self._check_type(inflow, (AvgFlowVolume, type(None)))
+        self._inflow = inflow
+
+    def get_release_to(self) -> str | None:
+        """Get the release_to module of the hydro module."""
+        return self._release_to
+
+    def set_release_to(self, release_to: str | None) -> None:
+        """Set the release_to module of the hydro module."""
+        self._check_type(release_to, (str, type(None)))
+        self._release_to = release_to
+
+    def get_spill_to(self) -> str | None:
+        """Get the spill_to module of the hydro module."""
+        return self._spill_to
+
+    def get_water_value(self) -> WaterValue:
+        """Get water value at the hydro node."""
+        return self._water_value
+
+    def get_release_volume(self) -> FlowVolume:
+        """Get the release_volume volume of the thermal unit."""
+        return self._release_volume
+
+    def get_spill_volume(self) -> FlowVolume:
+        """Get the spill_volume volume of the thermal unit."""
+        return self._spill_volume
+
+    """Implementation of Component interface"""
+
+    def _replace_node(self, old: str, new: str) -> None:
+        if self._pump and old == self._pump.get_power_node():
+            self._pump.set_power_node(new)
+        if self._generator and old == self._generator.get_power_node():
+            self._generator.set_power_node(new)
+
+    def _get_simpler_components(self, module_name: str) -> dict[str, Component]:
+        out: dict[str, Component] = {}
+
+        node_name = module_name + self._NODE_NAME_POSTFIX
+
+        out[node_name] = self._create_hydro_node()
+        out[module_name + "_release_flow"] = self._create_release_flow(node_name)
+        out[module_name + "_spill_flow"] = self._create_spill_flow(node_name)
+
+        if self._inflow is not None:
+            out[module_name + "_inflow_flow"] = self._create_inflow_flow(node_name)
+
+        if self._bypass is not None:
+            out[module_name + "_bypass_flow"] = self._create_bypass_flow(node_name)
+
+        if self._pump is not None:
+            out[module_name + "_pump_flow"] = self._create_pump_flow(node_name)
+
+        return out
+
+    def _create_hydro_node(self) -> Node:
+        return Node(
+            commodity=self._commodity,
+            price=self._water_value,
+            storage=self._reservoir,
+        )
+
+    def _create_release_flow(self, node_name: str) -> Flow:
+        # TODO: pq_curve, nominal_head, tailwater_elevation
+        flow = Flow(
+            main_node=node_name,
+            max_capacity=self._release_capacity,
+            volume=self._release_volume,
+            startupcost=None,
+            arrow_volumes=None,
+            is_exogenous=False,
+        )
+
+        arrow_volumes = flow.get_arrow_volumes()
+
+        outgoing_arrow = Arrow(
+            node=node_name,
+            is_ingoing=False,
+            conversion=Conversion(value=1),
+        )
+
+        flow.add_arrow(outgoing_arrow)
+
+        if self._release_to:
+            flow.add_arrow(
+                Arrow(
+                    node=self._release_to + self._NODE_NAME_POSTFIX,
+                    is_ingoing=True,
+                    conversion=Conversion(value=1),
+                ),
+            )
+
+        if self._generator:
+            production_arrow = Arrow(
+                node=self._generator.get_power_node(),
+                is_ingoing=True,
+                conversion=self._generator.get_energy_equivalent(),
+            )
+            flow.add_arrow(production_arrow)
+            arrow_volumes[production_arrow] = self._generator.get_production()
+
+            if self._generator.get_voc() is not None:
+                flow.add_cost_term("VOC", self._generator.get_voc())
+
+        return flow
+
+    def _create_spill_flow(self, node_name: str) -> Flow:
+        flow = Flow(
+            main_node=node_name,
+            max_capacity=None,
+            volume=self._spill_volume,
+        )
+
+        flow.add_arrow(
+            Arrow(
+                node=node_name,
+                is_ingoing=False,
+                conversion=Conversion(value=1),
+            ),
+        )
+
+        if self._spill_to is not None:
+            flow.add_arrow(
+                Arrow(
+                    node=self._spill_to + self._NODE_NAME_POSTFIX,
+                    is_ingoing=True,
+                    conversion=Conversion(value=1),
+                ),
+            )
+
+        return flow
+
+    def _create_bypass_flow(self, node_name: str) -> Flow:
+        flow = Flow(
+            main_node=node_name,
+            max_capacity=self._bypass.get_capacity(),
+            volume=self._bypass.get_volume(),
+            is_exogenous=False,
+        )
+
+        flow.add_arrow(
+            Arrow(
+                node=node_name,
+                is_ingoing=False,
+                conversion=Conversion(value=1),
+            ),
+        )
+
+        if self._bypass.get_to_module() is not None:
+            flow.add_arrow(
+                Arrow(
+                    node=self._bypass.get_to_module() + self._NODE_NAME_POSTFIX,
+                    is_ingoing=True,
+                    conversion=Conversion(value=1),
+                ),
+            )
+
+        return flow
+
+    def _create_inflow_flow(self, node_name: str) -> Flow:
+        flow = Flow(
+            main_node=node_name,
+            max_capacity=None,
+            volume=self._inflow,
+            is_exogenous=True,
+        )
+
+        flow.add_arrow(
+            Arrow(
+                node=node_name,
+                is_ingoing=True,
+                conversion=Conversion(value=1),
+            ),
+        )
+
+        return flow
+
+    def _create_pump_flow(self, node_name: str) -> Flow:
+        # TODO: add rest of attributes
+
+        arrow_volumes: dict[Arrow, FlowVolume] = dict()
+
+        flow = Flow(
+            main_node=node_name,
+            max_capacity=self._pump.get_water_capacity(),
+            volume=self._pump.get_water_consumption(),
+            arrow_volumes=arrow_volumes,
+            is_exogenous=False,
+        )
+
+        flow.add_arrow(
+            Arrow(
+                node=self._pump.get_to_module() + self._NODE_NAME_POSTFIX,
+                is_ingoing=True,
+                conversion=Conversion(value=1),
+            ),
+        )
+
+        flow.add_arrow(
+            Arrow(
+                node=self._pump.get_from_module() + self._NODE_NAME_POSTFIX,
+                is_ingoing=False,
+                conversion=Conversion(value=1),
+            ),
+        )
+
+        pump_arrow = Arrow(
+            node=self._pump.get_power_node(),
+            is_ingoing=False,
+            conversion=self._pump.get_energy_equivalent(),
+        )
+        flow.add_arrow(pump_arrow)
+        arrow_volumes[pump_arrow] = self._pump.get_power_consumption()
+
+        return flow

framcore/components/Node.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from framcore.attributes import Price, ShadowPrice, Storage
+from framcore.components import Component
+
+if TYPE_CHECKING:
+    from framcore.loaders import Loader
+
+
+class Node(Component):
+    """
+    Represents a point in the energy system where a commodity can possibly be traded, stored or pass through.
+
+    A node is characterized by the commodity it handles, its price, and optionally storage capabilities. If the
+    node is exogenous, the commodity can be bought and sold at a fixed price determined by the user.
+    If the node is endogenous, the price is determined by the market dynamics at the Node.
+
+    Nodes, Flows and Arrows are the main building blocks in FRAM's low-level representation of energy systems.
+    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,
+        commodity: str,
+        is_exogenous: bool = False,  # TODO
+        price: ShadowPrice | None = None,
+        storage: Storage | None = None,
+    ) -> None:
+        """
+        Initialize the Node class.
+
+        Args:
+            commodity (str): Commodity at the Node. Power/electricity, gas, heat, etc.
+            is_exogenous (bool, optional): Flag used to signal Solvers whether they should simulate the node endogenously or use the pre-set price.
+                                           Defaults to False.
+            price (ShadowPrice | None): Actual, calculated price of Commodity in this Node for each moment of simulation. Defaulta to None.
+            storage (Storage | None, optional): The amount of the Commodity stored on this Node. Defaults to None.
+
+        """
+        super().__init__()
+        self._check_type(commodity, str)
+        self._check_type(is_exogenous, bool)
+        self._check_type(price, (ShadowPrice, type(None)))
+        self._check_type(storage, (Storage, type(None)))
+
+        self._commodity = commodity
+        self._is_exogenous = is_exogenous
+
+        self._storage = storage
+
+        if price is None:
+            price = Price()
+
+        self._price: Price = price
+
+    def set_exogenous(self) -> None:
+        """Set the Node to be exogenous."""
+        self._check_type(self._is_exogenous, bool)
+        self._is_exogenous = True
+
+    def set_endogenous(self) -> None:
+        """Set the Node to be endogenous."""
+        self._check_type(self._is_exogenous, bool)
+        self._is_exogenous = False
+
+    def is_exogenous(self) -> bool:
+        """Return True if Node is exogenous (i.e. has fixed prices determined outside the model) else False."""
+        return self._is_exogenous
+
+    def get_price(self) -> ShadowPrice:
+        """Return price."""
+        return self._price
+
+    def get_storage(self) -> Storage | None:
+        """Get Storage if any."""
+        return self._storage
+
+    def get_commodity(self) -> str:
+        """Return commodity."""
+        return self._commodity
+
+    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_price())
+        add_loaders_if(loaders, self.get_storage())
+
+    def _replace_node(self, old: str, new: str) -> None:
+        return None
+
+    def _get_simpler_components(self, _: str) -> dict[str, Component]:
+        return dict()

framcore/components/Thermal.py

@@ -0,0 +1,208 @@
+from framcore.attributes import Arrow, AvgFlowVolume, Conversion, Cost, Efficiency, FlowVolume, StartUpCost
+from framcore.components import Component, Flow
+from framcore.components._PowerPlant import _PowerPlant
+
+
+class Thermal(_PowerPlant):
+    """
+    Represents a thermal power plant, subclassing PowerPlant.
+
+    This class models a thermal power plant with attributes inherited from PowerPlant.
+    Additionally, it includes specific attributes such as:
+
+    - fuel node
+    - efficiency
+    - emission node
+    - emission coefficient
+    - startup costs
+
+
+    This class is compatible with ThermalAggregator.
+    """
+
+    def __init__(
+        self,
+        power_node: str,
+        fuel_node: str,
+        efficiency: Efficiency,
+        max_capacity: FlowVolume,
+        emission_node: str | None = None,
+        emission_coefficient: Conversion | None = None,
+        startupcost: StartUpCost | None = None,
+        min_capacity: FlowVolume | None = None,
+        voc: Cost | None = None,
+        production: AvgFlowVolume | None = None,
+        fuel_demand: AvgFlowVolume | None = None,
+        emission_demand: AvgFlowVolume | None = None,
+    ) -> None:
+        """
+        Initialize a Thermal power plant instance.
+
+        Args:
+            power_node (str): The power node of the plant.
+            fuel_node (str): The fuel node of the plant.
+            efficiency (Efficiency): Efficiency of the plant.
+            emission_node (str | None, optional): Emission node.
+            emission_coefficient (Conversion | None, optional): Emission coefficient.
+            startupcost (StartUpCost | None, optional): Cost associated with starting up the Plant.
+            max_capacity (FlowVolume | None, optional): Maximum production capacity.
+            min_capacity (FlowVolume | None, optional): Minimum production capacity.
+            voc (Cost | None, optional): Variable operating cost.
+            production (AvgFlowVolume | None, optional): Production volume.
+            fuel_demand (AvgFlowVolume | None, optional): Fuel demand.
+            emission_demand (AvgFlowVolume | None, optional): Emission demand.
+
+        """
+        super().__init__(
+            power_node=power_node,
+            max_capacity=max_capacity,
+            min_capacity=min_capacity,
+            voc=voc,
+            production=production,
+        )
+
+        self._check_type(fuel_node, str)
+        self._check_type(emission_node, (str, type(None)))
+        self._check_type(emission_coefficient, (Conversion, type(None)))
+        self._check_type(startupcost, (StartUpCost, type(None)))
+        self._check_type(production, (AvgFlowVolume, type(None)))
+        self._check_type(fuel_demand, (AvgFlowVolume, type(None)))
+        self._check_type(emission_demand, (AvgFlowVolume, type(None)))
+
+        self._fuel_node = fuel_node
+        self._efficiency = efficiency
+        self._emission_node = emission_node
+        self._emission_coefficient = emission_coefficient
+        self._startupcost = startupcost
+
+        if production is None:
+            production = AvgFlowVolume()
+
+        if fuel_demand is None:
+            fuel_demand = AvgFlowVolume()
+
+        if emission_demand is None and emission_node is not None:
+            emission_demand = AvgFlowVolume()
+
+        self._production = production
+        self._fuel_demand = fuel_demand
+        self._emission_demand = emission_demand
+
+    def get_fuel_node(self) -> str:
+        """Get the fuel node of the thermal unit."""
+        return self._fuel_node
+
+    def set_fuel_node(self, fuel_node: str) -> None:
+        """Set the fuel node of the thermal unit."""
+        self._check_type(fuel_node, str)
+        self._fuel_node = fuel_node
+
+    def get_emission_node(self) -> str | None:
+        """Get the emission node of the thermal unit."""
+        return self._emission_node
+
+    def set_emission_node(self, emission_node: str | None) -> None:
+        """Set the emission node of the thermal unit."""
+        self._check_type(emission_node, (str, type(None)))
+        self._emission_node = emission_node
+
+    def get_emission_coefficient(self) -> Conversion | None:
+        """Get the emission coefficient of the thermal unit."""
+        return self._emission_coefficient
+
+    def set_emission_coefficient(self, emission_coefficient: Conversion | None) -> None:
+        """Set the emission coefficient of the thermal unit."""
+        self._check_type(emission_coefficient, (Conversion, type(None)))
+        self._emission_coefficient = emission_coefficient
+
+    def get_fuel_demand(self) -> AvgFlowVolume:
+        """Get the fuel demand of the thermal unit."""
+        return self._fuel_demand
+
+    def get_emission_demand(self) -> AvgFlowVolume | None:
+        """Get the emission demand of the thermal unit."""
+        return self._emission_demand
+
+    def set_emission_demand(self, value: AvgFlowVolume | None) -> None:
+        """Set the emission demand of the thermal unit."""
+        self._check_type(value, (AvgFlowVolume, type(None)))
+        self._emission_demand = value
+
+    def get_efficiency(self) -> Efficiency:
+        """Get the efficiency of the thermal unit."""
+        return self._efficiency
+
+    def get_startupcost(self) -> StartUpCost | None:
+        """Get the startup cost of the thermal unit."""
+        return self._startupcost
+
+    def set_startupcost(self, startupcost: StartUpCost | None) -> None:
+        """Set the startup cost of the thermal unit."""
+        self._check_type(startupcost, (StartUpCost, type(None)))
+        self._startupcost = startupcost
+
+    """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:
+        existing_nodes = [self._power_node, self._fuel_node]
+        existing_nodes = existing_nodes if self._emission_node is None else [*existing_nodes, self._emission_node]
+        if old not in existing_nodes:
+            message = f"{old} not found in {self}. Expected one of the existing nodes {existing_nodes}."
+            raise ValueError(message)
+
+        if self._power_node == old:
+            self._power_node = new
+        if self._fuel_node == old:
+            self._fuel_node = new
+        if (self._emission_node is not None) and (old == self._emission_node):
+            self._emission_node = new
+
+    def _create_flow(self) -> Flow:
+        arrow_volumes: dict[Arrow, AvgFlowVolume] = dict()
+
+        is_exogenous = self._max_capacity == self._min_capacity
+
+        flow = Flow(
+            main_node=self._power_node,
+            max_capacity=self._max_capacity,
+            min_capacity=self._min_capacity,
+            startupcost=self._startupcost,
+            volume=self._production,
+            arrow_volumes=arrow_volumes,
+            is_exogenous=is_exogenous,
+        )
+
+        power_arrow = Arrow(
+            node=self._power_node,
+            is_ingoing=True,
+            conversion=Conversion(value=1),
+        )
+        flow.add_arrow(power_arrow)
+
+        fuel_arrow = Arrow(
+            node=self._fuel_node,
+            is_ingoing=False,
+            efficiency=self._efficiency,
+        )
+        flow.add_arrow(fuel_arrow)
+        arrow_volumes[fuel_arrow] = self._fuel_demand
+
+        if self._emission_node is not None:
+            if self._emission_demand is None:
+                self._emission_demand = AvgFlowVolume()
+            emission_arrow = Arrow(
+                node=self._emission_node,
+                is_ingoing=False,
+                conversion=self._emission_coefficient,
+                efficiency=self._efficiency,
+            )
+            flow.add_arrow(emission_arrow)
+            arrow_volumes[emission_arrow] = self._emission_demand
+
+        if self._voc:
+            flow.add_cost_term("VOC", self._voc)
+
+        return flow