exerpy 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

exerpy/components/__init__.py

@@ -4,10 +4,13 @@ from .heat_exchanger.condenser import Condenser
 from .heat_exchanger.simple import SimpleHeatExchanger
 from .heat_exchanger.steam_generator import SteamGenerator
 from .helpers.cycle_closer import CycleCloser
+from .helpers.power_bus import PowerBus
 from .nodes.deaerator import Deaerator
 from .nodes.drum import Drum
 from .nodes.flash_tank import FlashTank
 from .nodes.mixer import Mixer
+from .nodes.splitter import Splitter
+from .nodes.storage import Storage
 from .piping.valve import Valve
 from .power_machines.generator import Generator
 from .power_machines.motor import Motor

exerpy/components/combustion/base.py

@@ -1,9 +1,6 @@
 import logging
 
-import numpy as np
-
-from exerpy.components.component import Component
-from exerpy.components.component import component_registry
+from exerpy.components.component import Component, component_registry
 
 
 @component_registry
@@ -16,12 +13,6 @@ class CombustionChamber(Component):
     The exergy product is defined based on thermal and mechanical exergy differences,
     while the exergy fuel is based on chemical exergy differences.
 
-    Parameters
-    ----------
-    **kwargs : dict
-        Arbitrary keyword arguments passed to parent class.
-        Optional parameter 'Z_costs' (float): Investment cost rate of the component in currency/h.
-
     Attributes
     ----------
     E_F : float
@@ -38,79 +29,92 @@ class CombustionChamber(Component):
         Dictionary containing outlet stream data with mass flows and specific exergies.
     Z_costs : float
         Investment cost rate of the component in currency/h.
+    C_P : float
+        Cost of product stream :math:`\dot{C}_P` in currency/h.
+    C_F : float
+        Cost of fuel stream :math:`\dot{C}_F` in currency/h.
+    C_D : float
+        Cost of exergy destruction :math:`\dot{C}_D` in currency/h.
+    c_P : float
+        Specific cost of product stream (currency per unit exergy).
+    c_F : float
+        Specific cost of fuel stream (currency per unit exergy).
+    r : float
+        Relative cost difference, :math:`(c_P - c_F)/c_F`.
+    f : float
+        Exergoeconomic factor, :math:`\dot{Z}/(\dot{Z} + \dot{C}_D)`.
+    Ex_C_col : dict
+        Custom cost coefficients collection passed via `kwargs`.
 
     Notes
     -----
-    The exergy analysis considers the following definitions:
-
-    .. math::
-        \dot{E}_\mathrm{P} &= \sum_{out} \dot{m}_{out} \cdot e^\mathrm{T}_{out}
-        + \sum_{out} \dot{m}_{out} \cdot e^\mathrm{M}_{out}
-        - \sum_{in} \dot{m}_{in} \cdot e^\mathrm{T}_{in}
-        - \sum_{in} \dot{m}_{in} \cdot e^\mathrm{M}_{in}
-
-    .. math::
-        \dot{E}_\mathrm{F} &= \sum_{in} \dot{m}_{in} \cdot e^\mathrm{CH}_{in}
-        - \sum_{out} \dot{m}_{out} \cdot e^\mathrm{CH}_{out}
-
-    The exergetic efficiency is calculated as:
-
-    .. math::
-        \varepsilon = \frac{\dot{E}_\mathrm{P}}{\dot{E}_\mathrm{F}}
-
-    The exergy destruction follows from the exergy balance:
-
-    .. math::
-        \dot{E}_\mathrm{D} = \dot{E}_\mathrm{F} - \dot{E}_\mathrm{P}
+    This component requires the calculation of both physical and chemical exergy.
     """
 
     def __init__(self, **kwargs):
-        r"""Initialize combustion chamber component with given parameters."""
+        r"""
+        Initialize the combustion chamber component.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Arbitrary keyword arguments. Recognized keys:
+            - Ex_C_col (dict): custom cost coefficients, default {}
+            - Z_costs (float): investment cost rate (currency/h), default 0.0
+        """
         super().__init__(**kwargs)
         # Initialize additional attributes if necessary
-        self.Ex_C_col = kwargs.get('Ex_C_col', {})
-        self.Z_costs = kwargs.get('Z_costs', 0.0)  # Cost rate in currency/h
+        self.Ex_C_col = kwargs.get("Ex_C_col", {})
+        self.Z_costs = kwargs.get("Z_costs", 0.0)  # Cost rate in currency/h
 
     def calc_exergy_balance(self, T0: float, p0: float, split_physical_exergy) -> None:
         r"""
-        Calculate the exergy balance of the combustion chamber.
+        Compute the exergy balance of the combustion chamber.
+
+        .. math::
+            \dot{E}_P = \dot{E}^{\mathrm{PH}}_{\text{out}}
+                      - \bigl(\dot{E}^{\mathrm{PH}}_{\text{in},1}
+                              + \dot{E}^{\mathrm{PH}}_{\text{in},2}\bigr)
 
-        Performs exergy balance calculations considering both physical and chemical
-        exergy flows. The exergy product is based on physical exergy differences,
-        while the exergy fuel is based on chemical exergy differences.
+        .. math::
+            \dot{E}_F = \dot{E}^{\mathrm{CH}}_{\text{in},1}
+                      + \dot{E}^{\mathrm{CH}}_{\text{in},2}
+                      - \dot{E}^{\mathrm{CH}}_{\text{out}}
 
         Parameters
         ----------
         T0 : float
-            Ambient temperature in :math:`\mathrm{K}`.
+            Ambient temperature (K).
         p0 : float
-            Ambient pressure in :math:`\mathrm{Pa}`.
+            Ambient pressure (Pa).
+        split_physical_exergy : bool
+            Whether to split thermal and mechanical exergy.
 
         Raises
         ------
         ValueError
-            If the required inlet and outlet streams are not properly defined.
+            If fewer than two inlets or no outlets are defined.
         """
         # Check for necessary inlet and outlet data
-        if not hasattr(self, 'inl') or not hasattr(self, 'outl') or len(self.inl) < 2 or len(self.outl) < 1:
+        if not hasattr(self, "inl") or not hasattr(self, "outl") or len(self.inl) < 2 or len(self.outl) < 1:
             msg = "CombustionChamber requires at least two inlets (air and fuel) and one outlet (exhaust)."
             logging.error(msg)
             raise ValueError(msg)
 
         # Calculate total physical exergy of outlets
-        total_E_P_out = sum(outlet['m'] * outlet['e_PH'] for outlet in self.outl.values())
+        total_E_P_out = sum(outlet["m"] * outlet["e_PH"] for outlet in self.outl.values())
 
         # Calculate total physical exergy of inlets
-        total_E_P_in = sum(inlet['m'] * inlet['e_PH'] for inlet in self.inl.values())
+        total_E_P_in = sum(inlet["m"] * inlet["e_PH"] for inlet in self.inl.values())
 
         # Exergy Product (E_P)
         self.E_P = total_E_P_out - total_E_P_in
 
         # Calculate total chemical exergy of inlets
-        total_E_F_in = sum(inlet['m'] * inlet['e_CH'] for inlet in self.inl.values())
+        total_E_F_in = sum(inlet["m"] * inlet["e_CH"] for inlet in self.inl.values())
 
         # Calculate total chemical exergy of outlets
-        total_E_F_out = sum(outlet['m'] * outlet['e_CH'] for outlet in self.outl.values())
+        total_E_F_out = sum(outlet["m"] * outlet["e_CH"] for outlet in self.outl.values())
 
         # Exergy Fuel (E_F)
         self.E_F = total_E_F_in - total_E_F_out
@@ -123,126 +127,165 @@ class CombustionChamber(Component):
 
         # Log the results
         logging.info(
-            f"CombustionChamber exergy balance calculated: "
+            f"Exergy balance of CombustionChamber {self.name} calculated: "
             f"E_P={self.E_P:.2f}, E_F={self.E_F:.2f}, E_D={self.E_D:.2f}, "
             f"Efficiency={self.epsilon:.2%}"
         )
 
-
     def aux_eqs(self, A, b, counter, T0, equations, chemical_exergy_enabled):
-        """
-        Auxiliary equations for the combustion chamber.
-        
-        This function adds rows to the cost matrix A and the right-hand-side vector b to enforce
-        the following auxiliary cost relations:
-        
-        (1) For mechanical exergy:
-            - When all streams have non-zero mechanical exergy:
-              c_M(outlet)/E_M(outlet) = weighted average of inlet specific mechanical exergy costs
-            - When pressure can only decrease: c_M(outlet) is directly set
-            
-        (2) For chemical exergy:
-            - When all streams have non-zero chemical exergy:
-              c_CH(outlet)/E_CH(outlet) = weighted average of inlet specific chemical exergy costs
-            - When an inlet has zero chemical exergy: its specific cost is directly set
-        
+        r"""
+        Add auxiliary cost equations for the combustion chamber.
+
+        This method appends two rows to the cost matrix to enforce:
+
+        1. F rule for mechanical exergy:
+
+        .. math::
+            -\frac{1}{\dot{E}^{\mathrm{M}}_{\text{out}}}\,\dot{C}^{\mathrm{M}}_{\text{out}}
+            + \frac{\dot m_{1}}{\dot m_{1} + \dot m_{2}}
+              \frac{1}{\dot{E}^{\mathrm{M}}_{\text{in},1}}\,\dot{C}^{\mathrm{M}}_{\text{in},1}
+            + \frac{\dot m_{2}}{\dot m_{1} + \dot m_{2}}
+              \frac{1}{\dot{E}^{\mathrm{M}}_{\text{in},2}}\,\dot{C}^{\mathrm{M}}_{\text{in},2}
+            = 0
+
+        2. F rule for chemical exergy:
+
+        .. math::
+            -\frac{1}{\dot{E}^{\mathrm{CH}}_{\text{out}}}\,\dot{C}^{\mathrm{CH}}_{\text{out}}{}
+            + \frac{\dot m_{1}}{\dot m_{1} + \dot m_{2}}
+              \frac{1}{\dot{E}^{\mathrm{CH}}_{\text{in},1}}\,\dot{C}^{\mathrm{CH}}_{\text{in},1}
+            + \frac{\dot m_{2}}{\dot m_{1} + \dot m_{2}}
+              \frac{1}{\dot{E}^{\mathrm{CH}}_{\text{in},2}}\,\dot{C}^{\mathrm{CH}}_{\text{in},2}
+            = 0
+
         Parameters
         ----------
         A : numpy.ndarray
-            The current cost matrix.
+            Current cost matrix.
         b : numpy.ndarray
-            The current right-hand-side vector.
+            Current RHS vector.
         counter : int
-            The current row index in the matrix.
+            Starting row index.
         T0 : float
             Ambient temperature.
         equations : dict or list
-            Data structure for storing equation labels.
+            Structure for equation labels.
         chemical_exergy_enabled : bool
-            Flag indicating whether chemical exergy is enabled.
-        
+            Must be True to include chemical exergy mixing.
+
         Returns
         -------
         A : numpy.ndarray
-            The updated cost matrix.
+            Updated cost matrix.
         b : numpy.ndarray
-            The updated right-hand-side vector.
+            Updated RHS vector.
         counter : int
-            The updated row index (counter + 2).
+            Updated row index.
         equations : dict or list
-            Updated structure with equation labels.
-            
+            Updated labels.
+
         Raises
         ------
         ValueError
-            If chemical exergy is not enabled, which is mandatory for combustion chambers.
+            If chemical_exergy_enabled is False.
         """
         # For the combustion chamber, chemical exergy is mandatory.
         if not chemical_exergy_enabled:
-            raise ValueError("Chemical exergy is mandatory for the combustion chamber!",
-                             "Please make sure that your exergy analysis consider the chemical exergy.")
+            raise ValueError(
+                "Chemical exergy is mandatory for the combustion chamber!",
+                "Please make sure that your exergy analysis consider the chemical exergy.",
+            )
 
         # Convert inlet and outlet dictionaries to lists for ordered access.
         inlets = list(self.inl.values())
         outlets = list(self.outl.values())
 
         # --- Mechanical cost auxiliary equation ---
-        if (outlets[0]["e_M"] != 0 and inlets[0]["e_M"] != 0 and inlets[1]["e_M"] != 0):
+        if outlets[0]["e_M"] != 0 and inlets[0]["e_M"] != 0 and inlets[1]["e_M"] != 0:
             A[counter, outlets[0]["CostVar_index"]["M"]] = -1 / outlets[0]["E_M"]
-            A[counter, inlets[0]["CostVar_index"]["M"]] = (1 / inlets[0]["E_M"]) * inlets[0]["m"] / (inlets[0]["m"] + inlets[1]["m"])
-            A[counter, inlets[1]["CostVar_index"]["M"]] = (1 / inlets[1]["E_M"]) * inlets[1]["m"] / (inlets[0]["m"] + inlets[1]["m"])
+            A[counter, inlets[0]["CostVar_index"]["M"]] = (
+                (1 / inlets[0]["E_M"]) * inlets[0]["m"] / (inlets[0]["m"] + inlets[1]["m"])
+            )
+            A[counter, inlets[1]["CostVar_index"]["M"]] = (
+                (1 / inlets[1]["E_M"]) * inlets[1]["m"] / (inlets[0]["m"] + inlets[1]["m"])
+            )
         else:  # pressure can only decrease in the combustion chamber (case with p_inlet = p0 and p_outlet < p0 NOT considered)
             A[counter, outlets[0]["CostVar_index"]["M"]] = 1
         equations[counter] = f"aux_mixing_mech_{self.outl[0]['name']}"
+        equations[counter] = {
+            "kind": "aux_mixing",
+            "objects": [self.name, self.inl[0]["name"], self.inl[1]["name"], self.outl[0]["name"]],
+            "property": "c_M",
+        }
 
         # --- Chemical cost auxiliary equation ---
-        if (outlets[0]["e_CH"] != 0 and inlets[0]["e_CH"] != 0 and inlets[1]["e_CH"] != 0):
-            A[counter+1, outlets[0]["CostVar_index"]["CH"]] = -1 / outlets[0]["E_CH"]
-            A[counter+1, inlets[0]["CostVar_index"]["CH"]] = (1 / inlets[0]["E_CH"]) * inlets[0]["m"] / (inlets[0]["m"] + inlets[1]["m"])
-            A[counter+1, inlets[1]["CostVar_index"]["CH"]] = (1 / inlets[1]["E_CH"]) * inlets[1]["m"] / (inlets[0]["m"] + inlets[1]["m"])
+        if outlets[0]["e_CH"] != 0 and inlets[0]["e_CH"] != 0 and inlets[1]["e_CH"] != 0:
+            A[counter + 1, outlets[0]["CostVar_index"]["CH"]] = -1 / outlets[0]["E_CH"]
+            A[counter + 1, inlets[0]["CostVar_index"]["CH"]] = (
+                (1 / inlets[0]["E_CH"]) * inlets[0]["m"] / (inlets[0]["m"] + inlets[1]["m"])
+            )
+            A[counter + 1, inlets[1]["CostVar_index"]["CH"]] = (
+                (1 / inlets[1]["E_CH"]) * inlets[1]["m"] / (inlets[0]["m"] + inlets[1]["m"])
+            )
         elif inlets[0]["e_CH"] == 0:
-            A[counter+1, inlets[0]["CostVar_index"]["CH"]] = 1
+            A[counter + 1, inlets[0]["CostVar_index"]["CH"]] = 1
         elif inlets[1]["e_CH"] == 0:
-            A[counter+1, inlets[1]["CostVar_index"]["CH"]] = 1
-        equations[counter+1] = f"aux_mixing_chem_{self.outl[0]['name']}"
+            A[counter + 1, inlets[1]["CostVar_index"]["CH"]] = 1
+        equations[counter] = {
+            "kind": "aux_mixing",
+            "objects": [self.name, self.inl[0]["name"], self.inl[1]["name"], self.outl[0]["name"]],
+            "property": "c_CH",
+        }
 
         # Set the right-hand side entries to zero.
-        b[counter]   = 0
-        b[counter+1] = 0
+        b[counter] = 0
+        b[counter + 1] = 0
 
         return [A, b, counter + 2, equations]
 
-    def exergoeconomic_balance(self, T0):
-        """
-        Perform exergoeconomic balance calculations for the combustion chamber.
-        
-        This method calculates various exergoeconomic parameters including:
-        - Cost rates of product (C_P) and fuel (C_F)
-        - Specific cost of product (c_P) and fuel (c_F)
-        - Cost rate of exergy destruction (C_D)
-        - Relative cost difference (r)
-        - Exergoeconomic factor (f)
-        
+    def exergoeconomic_balance(self, T0, chemical_exergy_enabled=False):
+        r"""
+        Perform exergoeconomic cost balance for the combustion chamber.
+
+        .. math::
+            \dot{C}^{\mathrm{PH}}_{\text{in},1} + \dot{C}^{\mathrm{CH}}_{\text{in},1}
+            + \dot{C}^{\mathrm{CH}}_{\text{in},2} + \dot{C}^{\mathrm{PH}}_{\text{in},2}
+            - \dot{C}^{\mathrm{PH}}_{\text{out}} - \dot{C}^{\mathrm{CH}}_{\text{out}}
+            + \dot{Z} = 0
+
+        This method computes cost coefficients and ratios:
+
+        .. math::
+            \dot{C}_P = \dot{C}^{\mathrm{T}}_{\text{out}}
+                      - \bigl(\dot{C}^{\mathrm{T}}_{\text{in},1}
+                              + \dot{C}^{\mathrm{T}}_{\text{in},2}\bigr)
+
+        .. math::
+            \dot{C}_F = \dot{C}^{\mathrm{CH}}_{\text{in},1}
+                      + \dot{C}^{\mathrm{CH}}_{\text{in},2}
+                      - \dot{C}^{\mathrm{CH}}_{\text{out}}
+                      + \dot{C}^{\mathrm{M}}_{\text{in},1}
+                      + \dot{C}^{\mathrm{M}}_{\text{in},2}
+                      - \dot{C}^{\mathrm{M}}_{\text{out}}
+
         Parameters
         ----------
         T0 : float
-            Ambient temperature
-            
-        Notes
-        -----
-        The exergoeconomic balance considers thermal (T), chemical (CH),
-        and mechanical (M) exergy components for the inlet and outlet streams.
+            Ambient temperature (K).
+        chemical_exergy_enabled : bool, optional
+            If True, chemical exergy is considered in the calculations.
         """
-        self.C_P = self.outl[0]["C_T"] - (
-                self.inl[0]["C_T"] + self.inl[1]["C_T"]
-        )
+        self.C_P = self.outl[0]["C_T"] - (self.inl[0]["C_T"] + self.inl[1]["C_T"])
         self.C_F = (
-                self.inl[0]["C_CH"] + self.inl[1]["C_CH"] -
-                self.outl[0]["C_CH"] + self.inl[0]["C_M"] +
-                self.inl[1]["C_M"] - self.outl[0]["C_M"]
+            self.inl[0]["C_CH"]
+            + self.inl[1]["C_CH"]
+            - self.outl[0]["C_CH"]
+            + self.inl[0]["C_M"]
+            + self.inl[1]["C_M"]
+            - self.outl[0]["C_M"]
         )
         self.c_F = self.C_F / self.E_F
         self.c_P = self.C_P / self.E_P
         self.C_D = self.c_F * self.E_D
         self.r = (self.c_P - self.c_F) / self.c_F
-        self.f = self.Z_costs / (self.Z_costs + self.C_D)
+        self.f = self.Z_costs / (self.Z_costs + self.C_D)

exerpy/components/component.py

@@ -20,7 +20,7 @@ class Component:
     Base class for all ExerPy components.
 
     This class serves as the parent class for all exergy analysis components. It provides
-    the basic structure and methods for exergy analysis calculations including the 
+    the basic structure and methods for exergy analysis calculations including the
     calculation of exergetic efficiency and exergy balance.
 
     Parameters
@@ -41,7 +41,7 @@ class Component:
 
     Notes
     -----
-    The exergetic efficiency is calculated as the ratio of exergy product to 
+    The exergetic efficiency is calculated as the ratio of exergy product to
     exergy fuel:
 
     .. math::
@@ -84,14 +84,14 @@ class Component:
         r"""
         Calculate the exergetic efficiency of the component.
 
-        The exergetic efficiency is defined as the ratio of exergy product to 
-        exergy fuel. If the exergy fuel is zero, the function returns NaN to 
+        The exergetic efficiency is defined as the ratio of exergy product to
+        exergy fuel. If the exergy fuel is zero, the function returns NaN to
         avoid division by zero.
 
         Returns
         -------
         float or nan
-            Exergetic efficiency :math:`\varepsilon = \frac{\dot{E}_\mathrm{P}}{\dot{E}_\mathrm{F}}` 
+            Exergetic efficiency :math:`\varepsilon = \frac{\dot{E}_\mathrm{P}}{\dot{E}_\mathrm{F}}`
             or NaN if :math:`\dot{E}_\mathrm{F} = 0`.
 
         Notes
@@ -106,9 +106,8 @@ class Component:
             return np.nan
         else:
             return self.E_P / self.E_F
-        
 
-    def exergoeconomic_balance(self, T0):
+    def exergoeconomic_balance(self, T0, chemical_exergy_enabled=False):
         r"""
         Placeholder method for exergoeconomic balance.
 
@@ -121,6 +120,7 @@ class Component:
         ----------
         T0 : float
             Ambient temperature in :math:`\mathrm{K}`.
+        chemical_exergy_enabled : bool, optional
+            If True, chemical exergy is considered in the calculations.
         """
         return
-