Add Heater block for duty-specified heating/cooling

Author: milanofthe

src/pathsim_chem/process/__init__.py

@@ -10,3 +10,7 @@
 from .distillation import *
 from .multicomponent_flash import *
 from .pfr import *
+from .mixer import *
+from .stream_splitter import *
+from .valve import *
+from .heater import *

src/pathsim_chem/process/heater.py

@@ -0,0 +1,63 @@
+#########################################################################################
+##
+##                              Duty-Specified Heater/Cooler Block
+##
+#########################################################################################
+
+# IMPORTS ===============================================================================
+
+from pathsim.blocks.function import Function
+
+# BLOCKS ================================================================================
+
+class Heater(Function):
+    """Algebraic duty-specified heater/cooler with no thermal mass.
+
+    Raises or lowers the stream temperature by a specified heat duty.
+    Flow passes through unchanged.
+
+    Mathematical Formulation
+    -------------------------
+    .. math::
+
+        T_{out} = T_{in} + \\frac{Q}{F \\, \\rho \\, C_p}
+
+    .. math::
+
+        F_{out} = F_{in}
+
+    Parameters
+    ----------
+    rho : float
+        Fluid density [kg/m³].
+    Cp : float
+        Fluid heat capacity [J/(kg·K)].
+    """
+
+    input_port_labels = {
+        "F":   0,
+        "T_in": 1,
+        "Q":   2,
+    }
+
+    output_port_labels = {
+        "F_out": 0,
+        "T_out": 1,
+    }
+
+    def __init__(self, rho=1000.0, Cp=4184.0):
+        if rho <= 0:
+            raise ValueError(f"'rho' must be positive but is {rho}")
+        if Cp <= 0:
+            raise ValueError(f"'Cp' must be positive but is {Cp}")
+
+        self.rho = rho
+        self.Cp = Cp
+        super().__init__(func=self._eval)
+
+    def _eval(self, F, T_in, Q):
+        if F > 0:
+            T_out = T_in + Q / (F * self.rho * self.Cp)
+        else:
+            T_out = T_in
+        return (F, T_out)

tests/process/test_heater.py

@@ -0,0 +1,117 @@
+########################################################################################
+##
+##                                  TESTS FOR
+##                            'process.heater.py'
+##
+########################################################################################
+
+# IMPORTS ==============================================================================
+
+import unittest
+
+from pathsim_chem.process import Heater
+
+
+# TESTS ================================================================================
+
+class TestHeater(unittest.TestCase):
+    """Test the duty-specified heater/cooler block."""
+
+    def test_init_default(self):
+        """Test default parameters."""
+        H = Heater()
+        self.assertEqual(H.rho, 1000.0)
+        self.assertEqual(H.Cp, 4184.0)
+
+    def test_init_custom(self):
+        """Test custom parameters."""
+        H = Heater(rho=800.0, Cp=3000.0)
+        self.assertEqual(H.rho, 800.0)
+        self.assertEqual(H.Cp, 3000.0)
+
+    def test_init_validation(self):
+        """Test input validation."""
+        with self.assertRaises(ValueError):
+            Heater(rho=0)
+        with self.assertRaises(ValueError):
+            Heater(rho=-1)
+        with self.assertRaises(ValueError):
+            Heater(Cp=0)
+        with self.assertRaises(ValueError):
+            Heater(Cp=-1)
+
+    def test_port_labels(self):
+        """Test port label definitions."""
+        self.assertEqual(Heater.input_port_labels["F"], 0)
+        self.assertEqual(Heater.input_port_labels["T_in"], 1)
+        self.assertEqual(Heater.input_port_labels["Q"], 2)
+        self.assertEqual(Heater.output_port_labels["F_out"], 0)
+        self.assertEqual(Heater.output_port_labels["T_out"], 1)
+
+    def test_heating(self):
+        """Positive Q should increase temperature."""
+        H = Heater(rho=1000.0, Cp=4184.0)
+        F = 0.1  # m³/s
+        T_in = 300.0
+        Q = 41840.0  # W
+
+        H.inputs[0] = F
+        H.inputs[1] = T_in
+        H.inputs[2] = Q
+
+        H.update(None)
+
+        # dT = Q / (F * rho * Cp) = 41840 / (0.1 * 1000 * 4184) = 0.1 K
+        expected_T = T_in + Q / (F * 1000.0 * 4184.0)
+        self.assertAlmostEqual(H.outputs[1], expected_T, places=6)
+
+    def test_cooling(self):
+        """Negative Q should decrease temperature."""
+        H = Heater(rho=1000.0, Cp=4184.0)
+        H.inputs[0] = 0.1
+        H.inputs[1] = 350.0
+        H.inputs[2] = -41840.0
+
+        H.update(None)
+
+        self.assertLess(H.outputs[1], 350.0)
+
+    def test_zero_duty(self):
+        """Q=0 should pass temperature through unchanged."""
+        H = Heater()
+        H.inputs[0] = 0.1
+        H.inputs[1] = 350.0
+        H.inputs[2] = 0.0
+
+        H.update(None)
+
+        self.assertAlmostEqual(H.outputs[1], 350.0)
+
+    def test_flow_passthrough(self):
+        """F_out should equal F_in."""
+        H = Heater()
+        H.inputs[0] = 0.5
+        H.inputs[1] = 300.0
+        H.inputs[2] = 10000.0
+
+        H.update(None)
+
+        self.assertAlmostEqual(H.outputs[0], 0.5)
+
+    def test_zero_flow(self):
+        """With zero flow, temperature should remain unchanged."""
+        H = Heater()
+        H.inputs[0] = 0.0
+        H.inputs[1] = 350.0
+        H.inputs[2] = 10000.0
+
+        H.update(None)
+
+        self.assertAlmostEqual(H.outputs[0], 0.0)
+        self.assertAlmostEqual(H.outputs[1], 350.0)
+
+
+# RUN TESTS LOCALLY ====================================================================
+
+if __name__ == '__main__':
+    unittest.main(verbosity=2)