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

framcore/attributes/__init__.py

@@ -0,0 +1,65 @@
+# ruff: noqa: I001
+
+from framcore.attributes.level_profile_attributes import (
+    AvgFlowVolume,
+    Coefficient,
+    Conversion,
+    Cost,
+    Efficiency,
+    Elasticity,
+    FlowVolume,
+    Hours,
+    LevelProfile,
+    Loss,
+    MaxFlowVolume,
+    ObjectiveCoefficient,
+    Price,
+    Proportion,
+    ReservePrice,
+    ShaddowPrice,
+    StockVolume,
+    WaterValue,
+)
+from framcore.attributes.Arrow import Arrow
+from framcore.attributes.ElasticDemand import ElasticDemand
+from framcore.attributes.ReservoirCurve import ReservoirCurve
+from framcore.attributes.SoftBound import SoftBound
+from framcore.attributes.StartUpCost import StartUpCost
+from framcore.attributes.TargetBound import TargetBound
+from framcore.attributes.Storage import Storage
+from framcore.attributes.hydro.HydroBypass import HydroBypass
+from framcore.attributes.hydro.HydroGenerator import HydroGenerator
+from framcore.attributes.hydro.HydroPump import HydroPump
+from framcore.attributes.hydro.HydroReservoir import HydroReservoir
+
+__all__ = [
+    "Arrow",
+    "AvgFlowVolume",
+    "Coefficient",
+    "Conversion",
+    "Cost",
+    "Efficiency",
+    "ElasticDemand",
+    "Elasticity",
+    "FlowVolume",
+    "Hours",
+    "HydroBypass",
+    "HydroGenerator",
+    "HydroPump",
+    "HydroReservoir",
+    "LevelProfile",
+    "Loss",
+    "MaxFlowVolume",
+    "ObjectiveCoefficient",
+    "Price",
+    "Proportion",
+    "ReservePrice",
+    "ReservoirCurve",
+    "ShaddowPrice",
+    "SoftBound",
+    "StartUpCost",
+    "StockVolume",
+    "Storage",
+    "TargetBound",
+    "WaterValue",
+]

framcore/attributes/hydro/HydroBypass.py

@@ -0,0 +1,42 @@
+from framcore import Base
+from framcore.attributes import AvgFlowVolume, FlowVolume
+from framcore.fingerprints import Fingerprint
+
+
+class HydroBypass(Base):
+    """Bypass class representing a hydro bypass attribute."""
+
+    def __init__(
+        self,
+        to_module: str | None,
+        capacity: FlowVolume | None = None,
+    ) -> None:
+        """Initialize Bypass."""
+        super().__init__()
+
+        self._check_type(to_module, (str, type(None)))
+        self._check_type(capacity, (FlowVolume, type(None)))
+
+        self._to_module = to_module
+        self._capacity = capacity
+        self._volume = AvgFlowVolume()
+
+    def get_to_module(self) -> str | None:
+        """Get the name of the module to which the bypass leads."""
+        return self._to_module
+
+    def set_to_module(self, to_module: str) -> None:
+        """Set the name of the module to which the bypass leads."""
+        self._check_type(to_module, str)
+        self._to_module = to_module
+
+    def get_capacity(self) -> FlowVolume | None:
+        """Get the capacity of the bypass."""
+        return self._capacity
+
+    def get_volume(self) -> AvgFlowVolume:
+        """Get the volume of the bypass."""
+        return self._volume
+
+    def _get_fingerprint(self) -> Fingerprint:
+        return self.get_fingerprint_default(refs={"to_module": self._to_module})

framcore/attributes/hydro/HydroGenerator.py

@@ -0,0 +1,83 @@
+from framcore import Base
+from framcore.attributes import AvgFlowVolume, Conversion, Cost
+from framcore.curves import Curve
+from framcore.expressions import Expr, ensure_expr
+from framcore.fingerprints import Fingerprint
+from framcore.timevectors import TimeVector
+
+
+class HydroGenerator(Base):
+    """Generator class representing a hydro generator component."""
+
+    def __init__(
+        self,
+        power_node: str,
+        energy_eq: Conversion,  # energy equivalent
+        pq_curve: Expr | str | Curve | None = None,
+        nominal_head: Expr | str | TimeVector | None = None,
+        tailwater_elevation: Expr | str | TimeVector | None = None,
+        voc: Cost | None = None,
+        production: AvgFlowVolume | None = None,
+    ) -> None:
+        """Initialize a hydro generator with power node, energy equivalent, and optional parameters."""
+        super().__init__()
+
+        self._check_type(power_node, str)
+        self._check_type(energy_eq, Conversion)
+        self._check_type(pq_curve, (Expr, str, Curve, type(None)))
+        self._check_type(nominal_head, (Expr, str, TimeVector, type(None)))
+        self._check_type(tailwater_elevation, (Expr, str, TimeVector, type(None)))
+        self._check_type(voc, (Cost, type(None)))
+
+        self._power_node = power_node
+        self._energy_eq = energy_eq
+        self._pq_curve = ensure_expr(pq_curve)
+        self._nominal_head = ensure_expr(nominal_head, is_level=True)
+        self._tailwater_elevation = ensure_expr(tailwater_elevation, is_level=True)
+        self._voc = voc
+
+        if production is None:
+            production = AvgFlowVolume()
+        self._production: AvgFlowVolume = production
+
+    def get_power_node(self) -> str:
+        """Get the power node of the hydro generator."""
+        return self._power_node
+
+    def set_power_node(self, power_node: str) -> None:
+        """Set the power node of the pump unit."""
+        self._check_type(power_node, str)
+        self._power_node = power_node
+
+    # TODO: change from eq to equivalent
+    def get_energy_eq(self) -> Conversion:
+        """Get the energy equivalent of the hydro generator."""
+        return self._energy_eq
+
+    def get_pq_curve(self) -> Expr | None:
+        """Get the PQ curve of the hydro generator."""
+        return self._pq_curve
+
+    def get_nominal_head(self) -> Expr | None:
+        """Get the nominal head of the hydro generator."""
+        return self._nominal_head
+
+    def get_tailwater_elevation(self) -> Expr | None:
+        """Get the tailwater elevation of the hydro generator."""
+        return self._tailwater_elevation
+
+    def get_voc(self) -> Cost | None:
+        """Get the variable operation and maintenance cost of the hydro generator."""
+        return self._voc
+
+    def set_voc(self, voc: Cost) -> None:
+        """Set the variable operation and maintenance cost of the hydro generator."""
+        self._check_type(voc, Cost)
+        self._voc = voc
+
+    def get_production(self) -> AvgFlowVolume:
+        """Get the generation of the hydro generator."""
+        return self._production
+
+    def _get_fingerprint(self) -> Fingerprint:
+        raise self.get_fingerprint_default(refs={"power_node": self._power_node})

framcore/attributes/hydro/HydroPump.py

@@ -0,0 +1,156 @@
+from framcore import Base
+from framcore.attributes import AvgFlowVolume, Conversion, FlowVolume
+from framcore.expressions import Expr, ensure_expr
+from framcore.fingerprints import Fingerprint
+from framcore.timevectors import TimeVector
+
+
+class HydroPump(Base):
+    """Pump class representing a hydro pump component."""
+
+    def __init__(
+        self,
+        power_node: str,
+        from_module: str,
+        to_module: str,
+        water_capacity: FlowVolume,
+        energy_eq: Conversion,
+        power_capacity: FlowVolume | None = None,
+        head_min: Expr | str | TimeVector | None = None,
+        head_max: Expr | str | TimeVector | None = None,
+        q_min: Expr | str | TimeVector | None = None,
+        q_max: Expr | str | TimeVector | None = None,
+    ) -> None:
+        """Initialize a hydro pump with power node, modules, capacity, energy equivalent, and optional parameters."""
+        super().__init__()
+        self._check_type(power_node, str)
+        self._check_modules(from_module, to_module)  # checks types and that they are not the same.
+        self._check_type(water_capacity, FlowVolume)
+        self._check_type(power_capacity, FlowVolume)
+        self._check_type(energy_eq, Conversion)
+        self._check_type(head_min, (Expr, str, TimeVector, type(None)))
+        self._check_type(head_max, (Expr, str, TimeVector, type(None)))
+        self._check_type(q_min, (Expr, str, TimeVector, type(None)))
+        self._check_type(q_max, (Expr, str, TimeVector, type(None)))
+
+        self._power_node = power_node
+        self._from_module = from_module
+        self._to_module = to_module
+        self._water_capacity = water_capacity
+        self._energy_eq = energy_eq
+        self._power_capacity = power_capacity
+
+        self._hmin = ensure_expr(head_min, is_level=True)
+        self._hmax = ensure_expr(head_max, is_level=True)
+        self._qmin = ensure_expr(q_min, is_flow=True, is_level=True)
+        self._qmax = ensure_expr(q_max, is_flow=True, is_level=True)
+
+        self._water_consumption = AvgFlowVolume()
+        self._power_consumption = AvgFlowVolume()
+
+    # TODO: change to water capacity
+    def get_water_capacity(self) -> FlowVolume:
+        """Get the capacity of the pump unit."""
+        return self._water_capacity
+
+    def get_power_capacity(self) -> FlowVolume:
+        """Get the capacity of the pump unit."""
+        return self._power_capacity
+
+    def get_power_node(self) -> str:
+        """Get the power node of the pump unit."""
+        return self._power_node
+
+    def set_power_node(self, power_node: str) -> None:
+        """Set the power node of the pump unit."""
+        self._check_type(power_node, str)
+        self._power_node = power_node
+
+    def get_from_module(self) -> str:
+        """Get the module from which the pump unit is pumping."""
+        return self._from_module
+
+    def get_to_module(self) -> str:
+        """Get the module to which the pump unit is pumping."""
+        return self._to_module
+
+    # TODO: should be split in two
+    def set_modules(self, from_module: str, to_module: str) -> None:
+        """Set the modules for the pump unit."""
+        self._check_modules(from_module, to_module)
+        self._from_module = from_module
+        self._to_module = to_module
+
+    def get_water_consumption(self) -> FlowVolume:
+        """Get the water consumption of the pump unit."""
+        return self._water_consumption
+
+    def get_power_consumption(self) -> FlowVolume:
+        """Get the power consumption of the pump unit."""
+        return self._power_consumption
+
+    def _check_modules(self, from_module: str, to_module: str) -> None:
+        self._check_type(from_module, str)
+        self._check_type(to_module, str)
+        if from_module == to_module:
+            message = f"{self} cannot pump to and from the same module. Got {from_module} for both from_module and to_module."
+            raise ValueError(message)
+
+    def _check_base_module_name(self, base_name: str) -> None:
+        if base_name not in (self._from_module, self._to_module):
+            message = (
+                f"Module {base_name} has not been coupled correctly to its pump {self}. Pump is coupled to modules {self._from_module} and {self._to_module}"
+            )
+            raise RuntimeError(message)
+
+    # other parameters
+    # TODO: change from eq to equivalent
+    def get_energy_eq(self) -> Conversion:
+        """Get the energy equivalent of hydro pump."""
+        return self._energy_eq
+
+    def set_energy_eq(self, energy_eq: Conversion) -> None:
+        """Set the energy equivalent."""
+        self._check_type(energy_eq, Conversion)
+        self._energy_eq = energy_eq
+
+    def get_head_min(self) -> Expr:
+        """Get min fall height of hydro pump."""
+        return self._head_min
+
+    def set_head_min(self, head_min: Expr | str | None) -> None:
+        """Set min fall height."""
+        self._head_min = ensure_expr(head_min)
+
+    def get_head_max(self) -> Expr:
+        """Get max fall height of hydro pump."""
+        return self._hmax
+
+    def set_head_max(self, hmax: Expr | str | None) -> None:
+        """Set max fall height."""
+        self._hmax = ensure_expr(hmax)
+
+    def get_q_min(self) -> Expr:
+        """Get Q min of hydro pump."""
+        return self._q_min
+
+    def set_qmin(self, q_min: Expr | str | None) -> None:
+        """Set Q min."""
+        self._q_min = ensure_expr(q_min)
+
+    def get_q_max(self) -> Expr:
+        """Get Q max of hydro pump."""
+        return self._q_max
+
+    def set_qmax(self, q_max: Expr | str | None) -> None:
+        """Set Q max."""
+        self._q_max = ensure_expr(q_max)
+
+    def _get_fingerprint(self) -> Fingerprint:
+        return self.get_fingerprint_default(
+            refs={
+                "power_node": self._power_node,
+                "from_module": self._from_module,
+                "to_module": self._to_module,
+            },
+        )

framcore/attributes/hydro/HydroReservoir.py

@@ -0,0 +1,27 @@
+from framcore.attributes import ReservoirCurve, StockVolume
+from framcore.attributes.Storage import Storage
+
+
+class HydroReservoir(Storage):
+    """Reservoir class representing a hydro reservoir attribute."""
+
+    def __init__(
+        self,
+        capacity: StockVolume,
+        reservoir_curve: ReservoirCurve = None,
+        volume: StockVolume | None = None,
+    ) -> None:
+        """
+        Initialize a HydroReservoir instance.
+
+        Args:
+            capacity (StockVolume): The total storage capacity of the reservoir.
+            reservoir_curve (ReservoirCurve, optional): The curve describing reservoir characteristics.
+            volume (StockVolume, optional): The current volume of water in the reservoir.
+
+        """
+        super().__init__(
+            capacity=capacity,
+            reservoir_curve=reservoir_curve,
+            volume=volume,
+        )

framcore/attributes/hydro/__init__.py

@@ -0,0 +1,13 @@
+# from framcore.attributes.hydro.Bypass import Bypass
+# from framcore.attributes.hydro.Generator import Generator
+# from framcore.attributes.hydro.Inflow import Inflow
+# from framcore.attributes.hydro.Pump import Pump
+# from framcore.attributes.hydro.Reservoir import Reservoir
+
+# __all__ = [
+#     "Bypass",
+#     "Generator",
+#     "Inflow",
+#     "Pump",
+#     "Reservoir",
+# ]