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

framcore/attributes/__init__.py

@@ -0,0 +1,63 @@
+from framcore.attributes.level_profile_attributes import (
+    AvgFlowVolume,
+    Coefficient,
+    Conversion,
+    Cost,
+    Efficiency,
+    Elasticity,
+    FlowVolume,
+    Hours,
+    LevelProfile,
+    Loss,
+    MaxFlowVolume,
+    ObjectiveCoefficient,
+    Price,
+    Proportion,
+    ReservePrice,
+    ShadowPrice,
+    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",
+    "ShadowPrice",
+    "SoftBound",
+    "StartUpCost",
+    "StockVolume",
+    "Storage",
+    "TargetBound",
+    "WaterValue",
+]

framcore/attributes/hydro/HydroBypass.py

@@ -0,0 +1,49 @@
+from framcore import Base
+from framcore.attributes import AvgFlowVolume, FlowVolume
+from framcore.fingerprints import Fingerprint
+
+
+class HydroBypass(Base):
+    """HydroBypass represents a controlled water way from a HydroModule. Used to bypass main release of the HydroModule."""
+
+    def __init__(
+        self,
+        to_module: str | None,
+        capacity: FlowVolume | None = None,
+    ) -> None:
+        """
+        Initialize object.
+
+        Args:
+            to_module (str | None): Name of the HydroModule the water is released to.
+            capacity (FlowVolume | None, optional): Restrictions on the volume of water which can pass through the bypass at a given moment. Defaults to None.
+
+        """
+        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,100 @@
+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):
+    """
+    Produces power from the main release of a HydroModule.
+
+    Produces to a power node, and can have variable costs associated with operation. Other attributes are energy equivalent, PQ curve, nominal head
+    and tailwater elevation.
+
+    """
+
+    def __init__(
+        self,
+        power_node: str,
+        energy_equivalent: 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 HydroGenerator with parameters.
+
+        Args:
+            power_node (str): Node to supply power to.
+            energy_equivalent (Conversion): Conversion factor of power produced to water released.
+            pq_curve (Expr | str | Curve | None, optional): Expression or curve describing the relationship produced power and water released. Defaults to None.
+            nominal_head (Expr | str | TimeVector | None, optional): Vertical distance between upstream and dowstream water level. Defaults to None.
+            tailwater_elevation (Expr | str | TimeVector | None, optional): Elevation at the surface where the water exits the turbine. Defaults to None.
+            voc (Cost | None, optional): Variable operational costs. Defaults to None.
+            production (AvgFlowVolume | None, optional): Result of power volume produced. Defaults to None.
+
+        """
+        super().__init__()
+
+        self._check_type(power_node, str)
+        self._check_type(energy_equivalent, 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_equivalent
+        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
+
+    def get_energy_equivalent(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,178 @@
+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):
+    """
+    Represent a pump associated with a HydroModule.
+
+    The HydroPump can consume power from a power Node to move water upstream between two HydroModules. It has a max power capacity, and mean energy
+    equivalent and water capacity. It can also describe the relationship between head and flow (Q), with min and max head and flow.
+
+    Results for water and power consumption are stored as AvgFlowVolume attributes.
+
+    """
+
+    def __init__(
+        self,
+        power_node: str,
+        from_module: str,
+        to_module: str,
+        water_capacity: FlowVolume,
+        energy_equivalent: 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 HydroPump object parameters.
+
+        Args:
+            power_node (str): Node to take power from when operating.
+            from_module (str): Source HydroModule to move water from.
+            to_module (str): Destination HydroModule to move water to.
+            water_capacity (FlowVolume): Max pumped water volume given the mean energy equivalent and power capacity.
+            energy_equivalent (Conversion): Mean conversion factor between power consumed and volume of water moved.
+            power_capacity (FlowVolume | None, optional): Max power consumed. Defaults to None.
+            head_min (Expr | str | TimeVector | None, optional): Minimum elevation difference between upstream and downstream water level. Defaults to None.
+            head_max (Expr | str | TimeVector | None, optional): Maximum elevation difference between upstream and downstream water level. Defaults to None.
+            q_min (Expr | str | TimeVector | None, optional): Maximum water flow at head_min. Defaults to None.
+            q_max (Expr | str | TimeVector | None, optional): Maximum water flow at head_max. Defaults to None.
+
+        """
+        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, type(None)))
+        self._check_type(energy_equivalent, 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_equivalent
+        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()
+
+    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? Keep in mind we check that the to and from modules are not the same. So if we split this user might run into issues if
+    # trying to first set from_module to to_module then change to_module.
+    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
+    def get_energy_equivalent(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):
+    """Represent a hydro reservoir of a HydroModule."""
+
+    def __init__(
+        self,
+        capacity: StockVolume,
+        reservoir_curve: ReservoirCurve = None,
+        volume: StockVolume | None = None,
+    ) -> None:
+        """
+        Initialize a HydroReservoir instance.
+
+        Args:
+            capacity (StockVolume): The maximum storage capacity of the reservoir.
+            reservoir_curve (ReservoirCurve, optional): The curve describing water level elevation to volume characteristics.
+            volume (StockVolume, optional): 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",
+# ]