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

exerpy/components/power_machines/generator.py

@@ -1,7 +1,6 @@
 import logging
 
-from exerpy.components.component import Component
-from exerpy.components.component import component_registry
+from exerpy.components.component import Component, component_registry
 
 
 @component_registry
@@ -9,8 +8,8 @@ class Generator(Component):
     r"""
     Class for exergy analysis of generators.
 
-    This class performs exergy analysis calculations for generators, converting mechanical 
-    or thermal energy flow into electrical energy. The exergy product is defined as 
+    This class performs exergy analysis calculations for generators, converting mechanical
+    or thermal energy flow into electrical energy. The exergy product is defined as
     the electrical power output, while the exergy fuel is the input energy flow.
 
     Parameters
@@ -73,23 +72,22 @@ class Generator(Component):
         split_physical_exergy : bool
             Flag indicating whether physical exergy is split into thermal and mechanical components.
 
-        """      
+        """
         # Exergy product is the electrical power output
-        self.E_P = self.outl[0]['energy_flow']
-        
+        self.E_P = self.outl[0]["energy_flow"]
+
         # Exergy fuel is the input power
-        self.E_F = self.inl[0]['energy_flow']
-        
+        self.E_F = self.inl[0]["energy_flow"]
+
         # Calculate exergy destruction
         self.E_D = self.E_F - self.E_P
-        
+
         # Calculate exergy efficiency
         self.epsilon = self.calc_epsilon()
-        
+
         # Log the results
         logging.info(
-            f"Generator exergy balance calculated: "
-            f"Generator exergy balance calculated: "
+            f"Exergy balance of Generator {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%}"
         )
@@ -97,14 +95,14 @@ class Generator(Component):
     def aux_eqs(self, A, b, counter, T0, equations, chemical_exergy_enabled):
         """
         Auxiliary equations for the generator.
-        
+
         This function adds rows to the cost matrix A and the right-hand-side vector b to enforce
         the auxiliary cost relations for the generator. Since the generator converts mechanical
         or thermal energy to electrical energy, the auxiliary equations typically enforce:
-        
-        - No additional auxiliary equations are needed for generators as electrical energy 
+
+        - No additional auxiliary equations are needed for generators as electrical energy
           is pure exergy and the cost balance equations are sufficient.
-        
+
         Parameters
         ----------
         A : numpy.ndarray
@@ -119,7 +117,7 @@ class Generator(Component):
             Dictionary for storing equation labels.
         chemical_exergy_enabled : bool
             Flag indicating whether chemical exergy auxiliary equations should be added.
-        
+
         Returns
         -------
         A : numpy.ndarray
@@ -131,38 +129,107 @@ class Generator(Component):
         equations : dict
             Updated dictionary with equation labels.
         """
-        
+
         return [A, b, counter, equations]
-    
-    def exergoeconomic_balance(self, T0):
-        """
-        Perform exergoeconomic balance calculations for the generator.
-        
-        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 generator (power-producing component).
+
+        The generator is a power-producing component (e.g., electrical generator, turbine)
+        where mechanical/electrical work is extracted from a flowing stream. The general
+        exergoeconomic balance equation is:
+
+        .. math::
+            \dot{C}_{\mathrm{in}}^{\mathrm{TOT}} - \dot{C}_{\mathrm{out}}^{\mathrm{TOT}}
+            - \dot{C}_{\mathrm{P}} + \dot{Z} = 0
+
+        For a generator, the product is the power output (electrical or mechanical),
+        and the fuel is the exergy decrease in the working fluid:
+
+        .. math::
+            \dot{C}_{\mathrm{P}} = \dot{C}_{\mathrm{out}}^{\mathrm{TOT}}
+
+        .. math::
+            \dot{C}_{\mathrm{F}} = \dot{C}_{\mathrm{in}}^{\mathrm{TOT}}
+
+        **Calculated exergoeconomic indicators:**
+
+        Specific cost of fuel:
+
+        .. math::
+            c_{\mathrm{F}} = \frac{\dot{C}_{\mathrm{F}}}{\dot{E}_{\mathrm{F}}}
+
+        Specific cost of product:
+
+        .. math::
+            c_{\mathrm{P}} = \frac{\dot{C}_{\mathrm{P}}}{\dot{E}_{\mathrm{P}}}
+
+        Cost rate of exergy destruction:
+
+        .. math::
+            \dot{C}_{\mathrm{D}} = c_{\mathrm{F}} \cdot \dot{E}_{\mathrm{D}}
+
+        Relative cost difference:
+
+        .. math::
+            r = \frac{\dot{C}_{\mathrm{P}} - \dot{C}_{\mathrm{F}}}{\dot{C}_{\mathrm{F}}}
+
+        Exergoeconomic factor:
+
+        .. math::
+            f = \frac{\dot{Z}}{\dot{Z} + \dot{C}_{\mathrm{D}}}
+
         Parameters
         ----------
         T0 : float
-            Ambient temperature
-            
+            Ambient temperature (K).
+        chemical_exergy_enabled : bool, optional
+            If True, chemical exergy is considered in the calculations.
+            Default is False.
+
+        Attributes Set
+        --------------
+        C_P : float
+            Cost rate of product (currency/time).
+        C_F : float
+            Cost rate of fuel (currency/time).
+        c_P : float
+            Specific cost of product (currency/energy).
+        c_F : float
+            Specific cost of fuel (currency/energy).
+        C_D : float
+            Cost rate of exergy destruction (currency/time).
+        r : float
+            Relative cost difference (dimensionless).
+        f : float
+            Exergoeconomic factor (dimensionless).
+
+        Raises
+        ------
+        ValueError
+            If E_P or E_F is zero, preventing computation of specific costs.
+
         Notes
         -----
-        The exergoeconomic balance considers thermal (T), chemical (CH),
-        and mechanical (M) exergy components for the inlet and outlet streams.
+        Unlike other components, the generator does not add Z_costs to close the
+        cost balance in the C_P calculation. The cost balance is determined by
+        the total exergy costs of inlet and outlet streams.
+
+        The relative cost difference r is calculated using total cost rates
+        (C_P and C_F) rather than specific costs (c_P and c_F), which is
+        mathematically equivalent for this component type.
+
+        The exergy destruction E_D must be computed prior to calling this method.
         """
         self.C_P = self.outl[0].get("C_TOT", 0)
         self.C_F = self.inl[0].get("C_TOT", 0)
-        
+
         if self.E_P == 0 or self.E_F == 0:
             raise ValueError(f"E_P or E_F is zero; cannot compute specific costs for component: {self.name}.")
-        
+
         self.c_P = self.C_P / self.E_P
         self.c_F = self.C_F / self.E_F
-        self.C_D = self.c_F * self.E_D   # Ensure that self.E_D is computed beforehand.
+        self.C_D = self.c_F * self.E_D  # Ensure that self.E_D is computed beforehand.
         self.r = (self.C_P - self.C_F) / self.C_F
         self.f = self.Z_costs / (self.Z_costs + self.C_D) if (self.Z_costs + self.C_D) != 0 else 0

exerpy/components/power_machines/motor.py

@@ -1,7 +1,6 @@
 import logging
 
-from exerpy.components.component import Component
-from exerpy.components.component import component_registry
+from exerpy.components.component import Component, component_registry
 
 
 @component_registry
@@ -10,7 +9,7 @@ class Motor(Component):
     Class for exergy analysis of motors.
 
     This class performs exergy analysis calculations for motors, converting electrical
-    energy into mechanical energy. The exergy product is defined as the mechanical 
+    energy into mechanical energy. The exergy product is defined as the mechanical
     power output, while the exergy fuel is the electrical power input.
 
     Parameters
@@ -59,7 +58,7 @@ class Motor(Component):
         r"""
         Calculate the exergy balance of the motor.
 
-        Calculates the exergy product (mechanical power output), exergy fuel 
+        Calculates the exergy product (mechanical power output), exergy fuel
         (electrical power input), and the resulting exergy destruction and efficiency.
 
         Parameters
@@ -71,46 +70,45 @@ class Motor(Component):
         split_physical_exergy : bool
             Flag indicating whether physical exergy is split into thermal and mechanical components.
 
-        """      
+        """
 
-        if self.outl[0]['energy_flow'] > self.inl[0]['energy_flow']:
-            pruduct = self.inl[0]['energy_flow']
-            fuel = self.outl[0]['energy_flow']
+        if self.outl[0]["energy_flow"] > self.inl[0]["energy_flow"]:
+            pruduct = self.inl[0]["energy_flow"]
+            fuel = self.outl[0]["energy_flow"]
         else:
-            pruduct = self.outl[0]['energy_flow']
-            fuel = self.inl[0]['energy_flow']
+            pruduct = self.outl[0]["energy_flow"]
+            fuel = self.inl[0]["energy_flow"]
 
         # Exergy product is the mechanical power output
         self.E_P = pruduct
-        
+
         # Exergy fuel is the electrical power input
         self.E_F = fuel
-        
+
         # Calculate exergy destruction
         self.E_D = self.E_F - self.E_P
-        
+
         # Calculate exergy efficiency
         self.epsilon = self.calc_epsilon()
 
         # Log the results
         logging.info(
-            f"Motor exergy balance calculated: "
+            f"Exergy balance of Motor {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 motor.
-        
+
         This function adds rows to the cost matrix A and the right-hand-side vector b to enforce
         the auxiliary cost relations for the motor. Since the motor converts mechanical
         or thermal energy to electrical energy, the auxiliary equations typically enforce:
-        
-        - No additional auxiliary equations are needed for motors as electrical energy 
+
+        - No additional auxiliary equations are needed for motors as electrical energy
           is pure exergy and the cost balance equations are sufficient.
-        
+
         Parameters
         ----------
         A : numpy.ndarray
@@ -125,7 +123,7 @@ class Motor(Component):
             Dictionary for storing equation labels.
         chemical_exergy_enabled : bool
             Flag indicating whether chemical exergy auxiliary equations should be added.
-        
+
         Returns
         -------
         A : numpy.ndarray
@@ -138,36 +136,110 @@ class Motor(Component):
             Updated dictionary with equation labels.
         """
         return [A, b, counter, equations]
-    
-    def exergoeconomic_balance(self, T0):
-        """
-        Perform exergoeconomic balance calculations for the motor.
-        
-        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 motor (power-consuming component).
+
+        The motor is a power-consuming component (e.g., electric motor, pump motor)
+        where mechanical/electrical work is consumed to drive a process. The general
+        exergoeconomic balance equation is:
+
+        .. math::
+            \dot{C}_{\mathrm{in}}^{\mathrm{TOT}} - \dot{C}_{\mathrm{out}}^{\mathrm{TOT}}
+            + \dot{C}_{\mathrm{W}} + \dot{Z} = 0
+
+        For a motor, the fuel is the input stream (typically electrical power),
+        and the product is the output stream (mechanical work or driven fluid):
+
+        .. math::
+            \dot{C}_{\mathrm{F}} = \dot{C}_{\mathrm{in}}^{\mathrm{TOT}}
+
+        .. math::
+            \dot{C}_{\mathrm{P}} = \dot{C}_{\mathrm{out}}^{\mathrm{TOT}}
+
+        **Calculated exergoeconomic indicators:**
+
+        Specific cost of fuel:
+
+        .. math::
+            c_{\mathrm{F}} = \frac{\dot{C}_{\mathrm{F}}}{\dot{E}_{\mathrm{F}}}
+
+        Specific cost of product:
+
+        .. math::
+            c_{\mathrm{P}} = \frac{\dot{C}_{\mathrm{P}}}{\dot{E}_{\mathrm{P}}}
+
+        Cost rate of exergy destruction:
+
+        .. math::
+            \dot{C}_{\mathrm{D}} = c_{\mathrm{F}} \cdot \dot{E}_{\mathrm{D}}
+
+        Relative cost difference:
+
+        .. math::
+            r = \frac{\dot{C}_{\mathrm{P}} - \dot{C}_{\mathrm{F}}}{\dot{C}_{\mathrm{F}}}
+
+        Exergoeconomic factor:
+
+        .. math::
+            f = \frac{\dot{Z}}{\dot{Z} + \dot{C}_{\mathrm{D}}}
+
         Parameters
         ----------
         T0 : float
-            Ambient temperature
-            
+            Ambient temperature (K).
+        chemical_exergy_enabled : bool, optional
+            If True, chemical exergy is considered in the calculations.
+            Default is False.
+
+        Attributes Set
+        --------------
+        C_P : float
+            Cost rate of product (currency/time).
+        C_F : float
+            Cost rate of fuel (currency/time).
+        c_P : float
+            Specific cost of product (currency/energy).
+        c_F : float
+            Specific cost of fuel (currency/energy).
+        C_D : float
+            Cost rate of exergy destruction (currency/time).
+        r : float
+            Relative cost difference (dimensionless).
+        f : float
+            Exergoeconomic factor (dimensionless).
+
+        Raises
+        ------
+        ValueError
+            If E_P or E_F is zero, preventing computation of specific costs.
+
         Notes
         -----
-        The exergoeconomic balance considers thermal (T), chemical (CH),
-        and mechanical (M) exergy components for the inlet and outlet streams.
+        The motor is a power-consuming component, opposite in function to a generator.
+        Unlike heat exchangers or pumps, the motor does not add Z_costs to close the
+        cost balance in the C_P calculation. The cost balance is determined by
+        the total exergy costs of inlet and outlet streams.
+
+        The relative cost difference r is calculated using total cost rates
+        (C_P and C_F) rather than specific costs (c_P and c_F), which is
+        mathematically equivalent for this component type.
+
+        The exergy destruction E_D must be computed prior to calling this method.
+
+        For motors coupled with pumps or compressors, the fuel is typically the
+        electrical energy consumed, and the product is the mechanical work delivered
+        to the driven equipment.
         """
         self.C_P = self.outl[0].get("C_TOT", 0)
         self.C_F = self.inl[0].get("C_TOT", 0)
-        
+
         if self.E_P == 0 or self.E_F == 0:
             raise ValueError(f"E_P or E_F is zero; cannot compute specific costs for component: {self.name}.")
-        
+
         self.c_P = self.C_P / self.E_P
         self.c_F = self.C_F / self.E_F
-        self.C_D = self.c_F * self.E_D   # Ensure that self.E_D is computed beforehand.
+        self.C_D = self.c_F * self.E_D  # Ensure that self.E_D is computed beforehand.
         self.r = (self.C_P - self.C_F) / self.C_F
         self.f = self.Z_costs / (self.Z_costs + self.C_D) if (self.Z_costs + self.C_D) != 0 else 0