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

framcore/attributes/Arrow.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore import Base
+from framcore.attributes import Conversion, Efficiency, Loss
+from framcore.querydbs import QueryDB
+from framcore.timeindexes import FixedFrequencyTimeIndex, SinglePeriodTimeIndex, TimeIndex
+
+if TYPE_CHECKING:
+    from framcore import Model
+    from framcore.loaders import Loader
+
+
+class Arrow(Base):
+    """
+    Arrow class is used by Flows to represent contribution of its commodity to Nodes.
+
+    The Arrow has direction to determine input or output (is_ingoing), and parameters for the contribution of the Flow to the Node.
+    The main parameters are conversion, efficiency and loss which together form the coefficient = conversion * (1 / efficiency) * (1 - loss)
+    Arrow has its own implementation of get_scenario_vector and get_data_value to calculate the coefficient shown above.
+    """
+
+    def __init__(
+        self,
+        node: str,
+        is_ingoing: bool,
+        conversion: Conversion | None = None,
+        efficiency: Efficiency | None = None,
+        loss: Loss | None = None,
+    ) -> None:
+        """Initialize the Arrow class."""
+        self._check_type(node, str)
+        self._check_type(is_ingoing, bool)
+        self._check_type(conversion, (Conversion, type(None)))
+        self._check_type(efficiency, (Efficiency, type(None)))
+        self._check_type(loss, (Loss, type(None)))
+        self._node = node
+        self._is_ingoing = is_ingoing
+        self._conversion = conversion
+        self._efficiency = efficiency
+        self._loss = loss
+
+    def get_node(self) -> str:
+        """Get the node the arrow is pointing to."""
+        return self._node
+
+    def set_node(self, node: str) -> None:
+        """Set the node the arrow is pointing to."""
+        self._check_type(node, str)
+        self._node = node
+
+    def is_ingoing(self) -> bool:
+        """
+        Return True if arrow is ingoing.
+
+        Ingoing means the flow variable supplies to node.
+        Outgoing means the flow variable takes out of node.
+        """
+        return self._is_ingoing
+
+    def get_conversion(self) -> Conversion | None:
+        """Get the conversion."""
+        return self._conversion
+
+    def set_conversion(self, value: Conversion | None) -> None:
+        """Set the conversion."""
+        self._check_type(value, Conversion, type(None))
+        self._conversion = value
+
+    def get_efficiency(self) -> Efficiency | None:
+        """Get the efficiency."""
+        return self._efficiency
+
+    def set_efficiency(self, value: Efficiency | None) -> None:
+        """Set the efficiency."""
+        self._check_type(value, Efficiency, type(None))
+        self._efficiency = value
+
+    def get_loss(self) -> Loss | None:
+        """Get the loss."""
+        return self._loss
+
+    def set_loss(self, value: Loss | None) -> None:
+        """Set the loss."""
+        self._check_type(value, Loss, type(None))
+        self._loss = value
+
+    def has_profile(self) -> bool:
+        """Return True if any of conversion, efficiency or loss has profile."""
+        if self._conversion is not None and self._conversion.has_profile():
+            return True
+        if self._efficiency is not None and self._efficiency.has_profile():
+            return True
+        return bool(self._loss is not None and self._loss.has_profile())
+
+    def get_conversion_unit_set(
+        self,
+        db: QueryDB | Model,
+    ) -> set[str]:
+        """Get set of units behind conversion level expr (if any)."""
+        if self._conversion is None:
+            return set()
+        return self._conversion.get_level_unit_set(db)
+
+    def get_profile_timeindex_set(
+        self,
+        db: QueryDB | Model,
+    ) -> set[TimeIndex]:
+        """
+        Get set of timeindexes behind profile.
+
+        Can be used to run optimized queries, i.e. not asking for
+        finer time resolutions than necessary.
+        """
+        if self.has_profile() is None:
+            return set()
+        s = set()
+        if self._conversion is not None:
+            s.update(self._conversion.get_profile_timeindex_set(db))
+        if self._loss is not None:
+            s.update(self._loss.get_profile_timeindex_set(db))
+        if self._efficiency is not None:
+            s.update(self._efficiency.get_profile_timeindex_set(db))
+        return s
+
+    def get_scenario_vector(  # noqa: C901, PLR0915
+        self,
+        db: QueryDB | Model,
+        scenario_horizon: FixedFrequencyTimeIndex,
+        level_period: SinglePeriodTimeIndex,
+        unit: str | None,
+        is_float32: bool = True,
+    ) -> NDArray:
+        """Return vector with values along the given scenario horizon using level over level_period."""
+        conversion_vector = None
+        efficiency_vector = None
+        loss_vector = None
+        conversion_value = None
+        efficiency_value = None
+        loss_value = None
+
+        if self._conversion is not None:
+            if self._conversion.has_profile():
+                conversion_vector = self._conversion.get_scenario_vector(
+                    db=db,
+                    scenario_horizon=scenario_horizon,
+                    level_period=level_period,
+                    unit=unit,
+                    is_float32=is_float32,
+                )
+            elif self._conversion.has_level():
+                conversion_value = self._conversion.get_data_value(
+                    db=db,
+                    scenario_horizon=scenario_horizon,
+                    level_period=level_period,
+                    unit=unit,
+                )
+                conversion_value = float(conversion_value)
+
+        if self._efficiency is not None:
+            if self._efficiency.has_profile():
+                efficiency_vector = self._efficiency.get_scenario_vector(
+                    db=db,
+                    scenario_horizon=scenario_horizon,
+                    level_period=level_period,
+                    unit=None,
+                    is_float32=is_float32,
+                )
+            elif self._efficiency.has_level():
+                efficiency_value = self._efficiency.get_data_value(
+                    db=db,
+                    scenario_horizon=scenario_horizon,
+                    level_period=level_period,
+                    unit=None,
+                )
+                efficiency_value = float(efficiency_value)
+
+        if self._loss is not None:
+            if self._loss.has_profile():
+                loss_vector = self._loss.get_scenario_vector(
+                    db=db,
+                    scenario_horizon=scenario_horizon,
+                    level_period=level_period,
+                    unit=None,
+                    is_float32=is_float32,
+                )
+            elif self._loss.has_level():
+                loss_value = self._loss.get_data_value(
+                    db=db,
+                    scenario_horizon=scenario_horizon,
+                    level_period=level_period,
+                    unit=None,
+                )
+                loss_value = float(loss_value)
+
+        if conversion_value is not None:
+            assert conversion_value >= 0, f"Arrow with invalid conversion ({conversion_value}): {self}"
+            out = conversion_value
+        else:
+            out = 1.0
+
+        if efficiency_value is not None:
+            assert efficiency_value > 0, f"Arrow with invalid efficiency ({efficiency_value}): {self}"
+            out = out / efficiency_value
+
+        if loss_value is not None:
+            assert loss_value >= 0 or loss_value < 1, f"Arrow with invalid loss ({loss_value}): {self}"
+            out = out - out * loss_value
+
+        if conversion_vector is not None:
+            np.multiply(conversion_vector, out, out=conversion_vector)
+            out = conversion_vector
+
+        if efficiency_vector is not None:
+            if isinstance(out, float):
+                np.divide(out, efficiency_vector, out=efficiency_vector)
+                out = efficiency_vector
+            else:
+                np.divide(out, efficiency_vector, out=out)
+
+        if loss_vector is not None:
+            if isinstance(out, float):
+                np.multiply(out, loss_vector, out=loss_vector)
+                np.subtract(out, loss_vector, out=loss_vector)
+                out = loss_vector
+            else:
+                np.multiply(out, loss_vector, out=loss_vector)
+                np.subtract(out, loss_vector, out=out)
+
+        if isinstance(out, float):
+            num_periods = scenario_horizon.get_num_periods()
+            vector = np.ones(num_periods, dtype=np.float32 if is_float32 else np.float64)
+            vector.fill(out)
+            return vector
+
+        return out
+
+    def get_data_value(
+        self,
+        db: QueryDB | Model,
+        scenario_horizon: FixedFrequencyTimeIndex,
+        level_period: SinglePeriodTimeIndex,
+        unit: str | None,
+        is_max_level: bool = False,
+    ) -> float:
+        """Return float for level_period."""
+        conversion_value = None
+        efficiency_value = None
+        loss_value = None
+
+        if self._conversion is not None and self._conversion.has_level():
+            conversion_value = self._conversion.get_data_value(
+                db=db,
+                scenario_horizon=scenario_horizon,
+                level_period=level_period,
+                unit=unit,
+                is_max_level=is_max_level,
+            )
+            conversion_value = float(conversion_value)
+
+        if self._efficiency is not None and self._efficiency.has_level():
+            efficiency_value = self._efficiency.get_data_value(
+                db=db,
+                scenario_horizon=scenario_horizon,
+                level_period=level_period,
+                unit=None,
+                is_max_level=is_max_level,
+            )
+            efficiency_value = float(efficiency_value)
+
+        if self._loss is not None and self._loss.has_level():
+            loss_value = self._loss.get_data_value(
+                db=db,
+                scenario_horizon=scenario_horizon,
+                level_period=level_period,
+                unit=None,
+                is_max_level=is_max_level,
+            )
+            loss_value = float(loss_value)
+
+        if conversion_value is not None:
+            assert conversion_value >= 0, f"Arrow with invalid conversion ({conversion_value}): {self}"
+            out = conversion_value
+        else:
+            out = 1.0
+
+        if efficiency_value is not None:
+            assert efficiency_value > 0, f"Arrow with invalid efficiency ({efficiency_value}): {self}"
+            out = out / efficiency_value
+
+        if loss_value is not None:
+            assert loss_value >= 0 or loss_value < 1, f"Arrow with invalid loss ({loss_value}): {self}"
+            out = out - out * loss_value
+
+        return out
+
+    def add_loaders(self, loaders: set[Loader]) -> None:
+        """Add all loaders stored in attributes to loaders."""
+        from framcore.utils import add_loaders_if
+
+        add_loaders_if(loaders, self.get_conversion())
+        add_loaders_if(loaders, self.get_loss())
+        add_loaders_if(loaders, self.get_efficiency())

framcore/attributes/ElasticDemand.py

@@ -0,0 +1,90 @@
+"""ElasticDemand attribute class."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from framcore import Base
+from framcore.attributes import Elasticity, Price
+
+# TODO: Discuss price interval validation. Should we check in init? How?
+
+if TYPE_CHECKING:
+    from framcore.loaders import Loader
+
+
+class ElasticDemand(Base):
+    """ElasticDemand class representing the price elasticity of a demand Component."""
+
+    def __init__(
+        self,
+        price_elasticity: Elasticity,
+        min_price: Price,
+        normal_price: Price,
+        max_price: Price,
+    ) -> None:
+        """
+        Initialize the ElasticDemand class.
+
+        Args:
+            price_elasticity (Elasticity): The price elasticity factor of the demand consumer.
+            min_price (Price): Lower limit for price elasticity.
+            normal_price (Price): Price for which the demand is inelastic. If it deviates from this price, the consumer will adjust
+                                  it's consumption according to the _price_elasticity factor.
+            max_price (Price): Upper limit for price elasticity / reservation price level.
+
+        """
+        self._check_type(price_elasticity, Elasticity)
+        self._check_type(min_price, Price)
+        self._check_type(normal_price, Price)
+        self._check_type(max_price, Price)
+
+        self._price_elasticity = price_elasticity
+        self._min_price = min_price
+        self._normal_price = normal_price
+        self._max_price = max_price
+
+    def get_price_elasticity(self) -> Elasticity:
+        """Get the price elasticity."""
+        return self._price_elasticity
+
+    def set_price_elasticity(self, elasticity: Price) -> None:
+        """Set the price elasticity."""
+        self._check_type(elasticity, Elasticity)
+        self._price_elasticity = elasticity
+
+    def get_min_price(self) -> Price:
+        """Get the minimum price."""
+        return self._min_price
+
+    def set_min_price(self, min_price: Price) -> None:
+        """Set the minimum price."""
+        self._check_type(min_price, Price)
+        self._min_price = min_price
+
+    def get_normal_price(self) -> Price:
+        """Get the normal price."""
+        return self._normal_price
+
+    def set_normal_price(self, normal_price: Price) -> None:
+        """Set the normal price."""
+        self._check_type(normal_price, Price)
+        self._normal_price = normal_price
+
+    def get_max_price(self) -> Price:
+        """Get the maximum price."""
+        return self._max_price
+
+    def set_max_price(self, max_price: Price) -> None:
+        """Set the maximum price."""
+        self._check_type(max_price, Price)
+        self._max_price = max_price
+
+    def add_loaders(self, loaders: set[Loader]) -> None:
+        """Add all loaders stored in attributes to loaders."""
+        from framcore.utils import add_loaders_if
+
+        add_loaders_if(loaders, self._normal_price)
+        add_loaders_if(loaders, self._price_elasticity)
+        add_loaders_if(loaders, self._max_price)
+        add_loaders_if(loaders, self._min_price)

framcore/attributes/ReservoirCurve.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from framcore import Base
+
+if TYPE_CHECKING:
+    from framcore.loaders import Loader
+
+
+class ReservoirCurve(Base):
+    """Water level elevation to water volume characteristics for HydroStorage."""
+
+    # TODO: Implement and comment, also too generic name
+
+    def __init__(self, value: str | None) -> None:
+        """Initialize a ReservoirCurve instance."""
+        self._check_type(value, (str, type(None)))
+        self._value = value
+
+    def add_loaders(self, loaders: set[Loader]) -> None:
+        """Add all loaders stored in attributes to loaders."""
+        return

framcore/attributes/SoftBound.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from framcore.loaders import Loader
+
+
+class SoftBound:
+    """Represents a soft bound attribute. Penalty applied if the bound is violated."""
+
+    # TODO: Implement and comment
+
+    def add_loaders(self, loaders: set[Loader]) -> None:
+        """Add all loaders stored in attributes to loaders."""
+        return

framcore/attributes/StartUpCost.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from framcore import Base
+from framcore.attributes import Cost, Efficiency, Hours, Proportion
+from framcore.fingerprints import Fingerprint
+
+if TYPE_CHECKING:
+    from framcore.loaders import Loader
+
+
+class StartUpCost(Base):
+    """Represent the costs associated with starting up the operation of a Component."""
+
+    # TODO: Complete description
+
+    def __init__(
+        self,
+        startup_cost: Cost,
+        min_stable_load: Proportion,
+        start_hours: Hours,
+        part_load_efficiency: Efficiency,
+    ) -> None:
+        """
+        Initialize the StartUpCost class.
+
+        Args:
+            startup_cost (Cost): _description_
+            min_stable_load (Proportion): _description_
+            start_hours (Hours): _description_
+            part_load_efficiency (Efficiency): _description_
+
+        """
+        self._check_type(startup_cost, Cost)
+        self._check_type(min_stable_load, Proportion)
+        self._check_type(start_hours, Hours)
+        self._check_type(part_load_efficiency, Efficiency)
+
+        self._startup_cost = startup_cost
+        self._min_stable_load = min_stable_load
+        self._start_hours = start_hours
+        self._part_load_efficiency = part_load_efficiency
+
+    def get_startupcost(self) -> Cost:
+        """Get the startup cost."""
+        return self._startup_cost
+
+    def set_startupcost(self, startupcost: Cost) -> None:
+        """Set the startup cost."""
+        self._check_type(startupcost, Cost)
+        self._startup_cost = startupcost
+
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the fingerprint of the startup cost."""
+        return self.get_fingerprint_default()
+
+    def add_loaders(self, loaders: set[Loader]) -> None:
+        """Get all loaders stored in attributes."""
+        from framcore.utils import add_loaders_if
+
+        add_loaders_if(loaders, self.get_startupcost())
+        add_loaders_if(loaders, self._start_hours)
+        add_loaders_if(loaders, self._min_stable_load)
+        add_loaders_if(loaders, self._part_load_efficiency)

framcore/attributes/Storage.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from framcore import Base
+from framcore.attributes import Loss, ObjectiveCoefficient, ReservoirCurve, SoftBound, StockVolume, TargetBound
+
+if TYPE_CHECKING:
+    from framcore.loaders import Loader
+
+
+class Storage(Base):
+    """
+    Represents all types of storage this system supports.
+
+    Subclasses are supposed to restrict which attributes that are used, not add more.
+    """
+
+    def __init__(
+        self,
+        capacity: StockVolume,
+        volume: StockVolume | None = None,
+        loss: Loss | None = None,  # TODO: Should be loss percentage per time.
+        reservoir_curve: ReservoirCurve | None = None,
+        max_soft_bound: SoftBound | None = None,
+        min_soft_bound: SoftBound | None = None,
+        target_bound: TargetBound | None = None,
+        initial_storage_percentage: float | None = None,
+    ) -> None:
+        """
+        Create new storage.
+
+        Args:
+            capacity (StockVolume): Storage capacity.
+            volume (StockVolume | None, optional): Storage filling (actual/result). Defaults to None.
+            loss (Loss | None, optional): Loss percentage per time. Defaults to None.
+            reservoir_curve (ReservoirCurve | None, optional): Water level elevation to water volume for HydroStorage. Defaults to None.
+            max_soft_bound (SoftBound | None, optional): Upper soft boundary that is penalized if broken. Defaults to None.
+            min_soft_bound (SoftBound | None, optional): Lower soft boundary that is penalized if broken. Defaults to None.
+            target_bound (TargetBound | None, optional): Target filling, can be penalized if deviation. Defaults to None.
+            initial_storage_percentage (float | None, optional): Initial storage filling percentage at start of simulation. Defaults to None.
+
+        """
+        super().__init__()
+
+        self._check_type(capacity, StockVolume)
+        self._check_type(volume, (StockVolume, type(None)))
+        self._check_type(loss, (StockVolume, type(None)))
+        self._check_type(reservoir_curve, (ReservoirCurve, type(None)))
+        self._check_type(max_soft_bound, (SoftBound, type(None)))
+        self._check_type(min_soft_bound, (SoftBound, type(None)))
+        self._check_type(target_bound, (TargetBound, type(None)))
+        self._check_type(initial_storage_percentage, (float, type(None)))
+
+        if initial_storage_percentage is not None:
+            self._check_float(initial_storage_percentage, lower_bound=0.0, upper_bound=1.0)
+
+        self._capacity = capacity
+
+        self._loss = loss
+        self._reservoir_curve = reservoir_curve
+        self._max_soft_bound = max_soft_bound
+        self._min_soft_bound = min_soft_bound
+        self._target_bound = target_bound
+        self._initial_storage_percentage = initial_storage_percentage
+
+        self._cost_terms: dict[str, ObjectiveCoefficient] = dict()
+
+        if volume is None:
+            volume = StockVolume()
+        self._volume = volume
+
+    def get_capacity(self) -> StockVolume:
+        """Get the capacity."""
+        return self._capacity
+
+    def get_volume(self) -> StockVolume:
+        """Get the volume."""
+        return self._volume
+
+    def add_cost_term(self, key: str, cost_term: ObjectiveCoefficient) -> None:
+        """Add a cost term."""
+        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."""
+        return self._cost_terms
+
+    def get_loss(self) -> Loss | None:
+        """Get the loss."""
+        return self._loss
+
+    def set_loss(self, value: Loss | None) -> None:
+        """Set the loss."""
+        self._check_type(value, (Loss, type(None)))
+        self._loss = value
+
+    def get_reservoir_curve(self) -> ReservoirCurve | None:
+        """Get the reservoir curve."""
+        return self._reservoir_curve
+
+    def set_reservoir_curve(self, value: ReservoirCurve | None) -> None:
+        """Set the reservoir curve."""
+        self._check_type(value, (ReservoirCurve, type(None)))
+        self._reservoir_curve = value
+
+    def get_max_soft_bound(self) -> SoftBound | None:
+        """Get the max soft bound."""
+        return self._max_soft_bound
+
+    def set_max_soft_bound(self, value: SoftBound | None) -> None:
+        """Set the max soft bound."""
+        self._check_type(value, (SoftBound, type(None)))
+        self._max_soft_bound = value
+
+    def get_min_soft_bound(self) -> SoftBound | None:
+        """Get the min soft bound."""
+        return self._min_soft_bound
+
+    def set_min_soft_bound(self, value: SoftBound | None) -> None:
+        """Set the min soft bound."""
+        self._check_type(value, (SoftBound, type(None)))
+        self._min_soft_bound = value
+
+    def get_target_bound(self) -> TargetBound | None:
+        """Get the target bound."""
+        return self._target_bound
+
+    def set_target_bound(self, value: TargetBound | None) -> None:
+        """Set the target bound."""
+        self._check_type(value, (TargetBound, type(None)))
+        self._target_bound = value
+
+    def get_initial_storage_percentage(self) -> float | None:
+        """Get the initial storage percentage (float in [0, 1])."""
+        return self._initial_storage_percentage
+
+    def set_initial_storage_percentage(self, value: float) -> None:
+        """Set the initial storage percentage (float in [0, 1])."""
+        self._check_float(value, lower_bound=0.0, upper_bound=1.0)
+        self._initial_storage_percentage = value
+
+    def add_loaders(self, loaders: set[Loader]) -> None:
+        """Add all loaders stored in attributes to loaders."""
+        from framcore.utils import add_loaders_if
+
+        add_loaders_if(loaders, self.get_capacity())
+        add_loaders_if(loaders, self.get_loss())
+        add_loaders_if(loaders, self.get_volume())
+        add_loaders_if(loaders, self.get_max_soft_bound())
+        add_loaders_if(loaders, self.get_min_soft_bound())
+        add_loaders_if(loaders, self.get_reservoir_curve())
+        add_loaders_if(loaders, self.get_target_bound())
+
+        for cost in self.get_cost_terms().values():
+            add_loaders_if(loaders, cost)

framcore/attributes/TargetBound.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from framcore.loaders import Loader
+
+
+class TargetBound:
+    """Target boundary attribute. Can be penalized if deviation from target."""
+
+    # TODO: Implement and comment
+
+    def add_loaders(self, loaders: set[Loader]) -> None:
+        """Add all loaders stored in attributes to loaders."""
+        return