added enthalpy_units argument (#66)

Author: markleader

CHANGELOG.md

@@ -5,10 +5,16 @@ All notable user-visible changes to this project are documented here.
 ## [Unreleased]
 
 ### Changed
+- Python `cea.Reactant` now supports explicit `enthalpy_units` for custom reactant enthalpy input (`J/kg`, `kJ/kg`, `cal/kg`, `kcal/kg`, `J/mol`, `kJ/mol`, `cal/mol`, `kcal/mol`; `/mol` and `/mole` spellings accepted).
+- Backward-compatible behavior is preserved when `Reactant.enthalpy` is provided without `enthalpy_units`: the legacy default (`J/kg`) is still used, but this now emits a `FutureWarning` directing users to pass `enthalpy_units` explicitly.
+- Weight-based enthalpy units (`*/kg`) now require `Reactant.molecular_weight` for conversion, while molar units (`*/mol`) do not require molecular weight for enthalpy interpretation.
+- Python docs and examples were updated to pass explicit `enthalpy_units` for custom reactants (including RP-1311 Example 5) instead of relying on implicit defaults.
+- **Compatibility notice:** a future **minor** version increment will require `enthalpy_units` whenever `Reactant.enthalpy` is defined. Code that currently relies on implicit enthalpy units may break until updated.
 
 ### Fixed
 
 ### Added
+- Added Python regression coverage for `Reactant` enthalpy-unit handling, including omitted-units warning behavior, explicit molar/weight units, molecular-weight requirements for weight units, and accepted unit spellings.
 
 ## [3.1.2] - 2026-03-23
 

docs/source/examples/equilibrium/example5.rst

@@ -21,22 +21,22 @@ Define the pressure schedule and reactant composition by weight fraction:
     weights = np.array([0.7206, 0.1858, 0.09, 0.002, 0.0016], dtype=np.float64)
     T_reac = np.array([298.15, 298.15, 298.15, 298.15, 298.15], dtype=np.float64)
 
-Create a :class:`~cea.Reactant` for ``CHOS-Binder`` using SI values.
-In the Python API, custom reactant ``enthalpy`` is in J/kg and ``temperature`` is in K.
-Use :mod:`cea.units` helpers for pre-conversion as needed.
+Create a :class:`~cea.Reactant` for ``CHOS-Binder`` using explicit enthalpy units.
+For backward compatibility, omitting ``enthalpy_units`` still defaults to ``J/kg`` for now,
+but that implicit behavior is deprecated and emits a warning.
 
 .. code-block:: python
 
-    chos_binder_mw_kg_per_mol = 14.6652984484e-3
-    chos_binder_h_si = cea.units.cal_to_joule(-2999.082) / chos_binder_mw_kg_per_mol
+    chos_binder_h_cal_per_mol = -2999.082
 
     reactants = [
         "NH4CLO4(I)",
         cea.Reactant(
             name="CHOS-Binder",
             formula={"C": 1.0, "H": 1.86955, "O": 0.031256, "S": 0.008415},
             molecular_weight=14.6652984484,
-            enthalpy=chos_binder_h_si,
+            enthalpy=chos_binder_h_cal_per_mol,
+            enthalpy_units="cal/mol",
             temperature=298.15,
         ),
         "AL(cr)",

docs/source/interfaces/python_api.rst

@@ -10,7 +10,11 @@ Mixture
 The :class:`~cea.Mixture` class is used to define a mixture of product or reactant species. It allows the user to specify the composition of the mixture and provides methods to compute thermodynamic curve fit properties.
 The instances of this class are then passed as inputs to the available solver classes (e.g., :class:`~cea.EqSolver`, :class:`~cea.RocketSolver`, :class:`~cea.ShockSolver`, or :class:`~cea.DetonationSolver`).
 Custom reactants can be provided through :class:`~cea.Reactant` objects (including mixed lists of strings and Reactant objects).
-For :class:`~cea.Reactant`, ``enthalpy`` and ``temperature`` are SI-only in the Python API (J/kg and K, respectively); use :mod:`cea.units` helpers for pre-conversion.
+For :class:`~cea.Reactant`, ``temperature`` is in K, and ``enthalpy`` must be paired with explicit
+``enthalpy_units`` (for example ``"J/kg"`` or ``"kJ/mol"``). Omitting ``enthalpy_units`` while
+providing ``enthalpy`` preserves the legacy default (``J/kg``) for backward compatibility, but this
+is deprecated and emits a ``FutureWarning``. A future minor version will require explicit
+``enthalpy_units``.
 
 .. autoclass:: cea.Reactant
    :members:

source/bind/python/CEA.pyx

@@ -530,22 +530,45 @@ cdef class Reactant:
     molecular_weight : float, optional
         Molecular weight in kg/kmol (numerically equivalent to g/mol).
     enthalpy : float, optional
-        Reference enthalpy in SI units (J/kg).
+        Reference enthalpy value interpreted according to ``enthalpy_units``.
+    enthalpy_units : str, optional
+        Units for ``enthalpy``. Supported values (case-insensitive):
+        ``J/kg``, ``kJ/kg``, ``cal/kg``, ``kcal/kg``, ``J/mol``, ``kJ/mol``,
+        ``cal/mol``, ``kcal/mol`` (``/mole`` spellings are also accepted).
+        If omitted while ``enthalpy`` is provided, the legacy default ``J/kg``
+        is used for backward compatibility and a ``FutureWarning`` is emitted.
+        Future minor versions will require explicit ``enthalpy_units``.
     temperature : float, optional
         Reference temperature in SI units (K).
 
     Notes
     -----
-    Python Reactant inputs are SI-only. Use :mod:`cea.units` helpers to pre-convert
-    non-SI values before constructing a Reactant.
+    Weight-based enthalpy inputs (``*/kg``) require ``molecular_weight`` to
+    convert to the core molar convention. Molar enthalpy inputs (``*/mol``)
+    do not require ``molecular_weight`` for enthalpy interpretation.
     """
     cdef public object name
     cdef public object formula
     cdef public object molecular_weight
     cdef public object enthalpy
+    cdef public object enthalpy_units
     cdef public object temperature
+    cdef object _enthalpy_core_units
+    cdef object _enthalpy_is_weight_units
+
+    def __init__(
+        self,
+        name,
+        formula=None,
+        molecular_weight=None,
+        enthalpy=None,
+        enthalpy_units=None,
+        temperature=None,
+    ):
+        cdef object normalized_enthalpy_units = None
+        cdef object enthalpy_core_units = None
+        cdef bint enthalpy_is_weight_units = False
 
-    def __init__(self, name, formula=None, molecular_weight=None, enthalpy=None, temperature=None):
         if not isinstance(name, str) or len(name.strip()) == 0:
             raise TypeError("Reactant name must be a non-empty str")
 
@@ -575,14 +598,80 @@ cdef class Reactant:
                 raise TypeError(f"Reactant {field_name} must be numeric")
             if not np.isfinite(fval):
                 raise ValueError(f"Reactant {field_name} must be finite")
-        if enthalpy is not None and molecular_weight is None:
-            raise ValueError("Reactant molecular_weight is required when enthalpy is specified")
+
+        if enthalpy is not None:
+            if enthalpy_units is None:
+                warnings.warn(
+                    "Reactant enthalpy without explicit enthalpy_units is deprecated; "
+                    "using legacy default J/kg for backward compatibility. "
+                    "Future minor versions will require explicit enthalpy_units. "
+                    "Pass enthalpy_units='J/kg' or enthalpy_units='kJ/mol'.",
+                    FutureWarning,
+                )
+                normalized_enthalpy_units = "j/kg"
+                enthalpy_core_units = "j/mole"
+                enthalpy_is_weight_units = True
+            else:
+                (
+                    normalized_enthalpy_units,
+                    enthalpy_core_units,
+                    enthalpy_is_weight_units,
+                ) = _normalize_enthalpy_units(enthalpy_units)
+            if enthalpy_is_weight_units and molecular_weight is None:
+                raise ValueError(
+                    "Reactant molecular_weight is required when enthalpy_units is weight-based "
+                    "(J/kg, kJ/kg, cal/kg, or kcal/kg)"
+                )
+        elif enthalpy_units is not None:
+            normalized_enthalpy_units, _, _ = _normalize_enthalpy_units(enthalpy_units)
 
         self.name = name
         self.formula = formula
         self.molecular_weight = molecular_weight
         self.enthalpy = enthalpy
+        self.enthalpy_units = normalized_enthalpy_units
         self.temperature = temperature
+        self._enthalpy_core_units = enthalpy_core_units
+        self._enthalpy_is_weight_units = bool(enthalpy_is_weight_units)
+
+
+cdef tuple _normalize_enthalpy_units(object enthalpy_units):
+    cdef str units_text
+    cdef dict canonical_map
+    cdef tuple normalized
+    cdef object key
+
+    if isinstance(enthalpy_units, bytes):
+        units_text = (<bytes>enthalpy_units).decode("utf-8", "strict")
+    elif isinstance(enthalpy_units, str):
+        units_text = <str>enthalpy_units
+    else:
+        raise TypeError("Reactant enthalpy_units must be str when provided")
+
+    units_text = "".join(units_text.split()).lower()
+
+    canonical_map = {
+        "j/kg": ("j/kg", "j/mole", True),
+        "kj/kg": ("kj/kg", "kj/mole", True),
+        "cal/kg": ("cal/kg", "cal/mole", True),
+        "kcal/kg": ("kcal/kg", "kcal/mole", True),
+        "j/mol": ("j/mole", "j/mole", False),
+        "j/mole": ("j/mole", "j/mole", False),
+        "kj/mol": ("kj/mole", "kj/mole", False),
+        "kj/mole": ("kj/mole", "kj/mole", False),
+        "cal/mol": ("cal/mole", "cal/mole", False),
+        "cal/mole": ("cal/mole", "cal/mole", False),
+        "kcal/mol": ("kcal/mole", "kcal/mole", False),
+        "kcal/mole": ("kcal/mole", "kcal/mole", False),
+    }
+
+    if units_text not in canonical_map:
+        raise ValueError(
+            "Reactant enthalpy_units must be one of: "
+            "J/kg, kJ/kg, cal/kg, kcal/kg, J/mol, kJ/mol, cal/mol, or kcal/mol"
+        )
+    normalized = canonical_map[units_text]
+    return normalized
 
 
 cdef class Mixture:
@@ -638,7 +727,6 @@ cdef class Mixture:
         cdef list _reactant_keepalive = []
         cdef list _element_ptr_buffers = []
         cdef list _coeff_ptr_buffers = []
-        cdef _CString _enthalpy_units
         cdef _CString _temperature_units
 
         if species is None:
@@ -649,7 +737,6 @@ cdef class Mixture:
             raise TypeError("Mixture species must be a list")
         if type(omit) is not list:
             raise TypeError("Mixture omit must be a list")
-        _enthalpy_units = _CString("j/mole", "Reactant enthalpy units")
         _temperature_units = _CString("k", "Reactant temperature units")
 
         self.num_species = <int>len(species)
@@ -737,9 +824,14 @@ cdef class Mixture:
                         cea_reactants[i].molecular_weight = float(reactant.molecular_weight)
 
                     if reactant.enthalpy is not None:
+                        _encoded = _CString(reactant._enthalpy_core_units, "Reactant enthalpy units")
+                        _reactant_keepalive.append(_encoded)
                         cea_reactants[i].has_enthalpy = 1
-                        cea_reactants[i].enthalpy = float(reactant.enthalpy) * float(reactant.molecular_weight) / 1000.0
-                        cea_reactants[i].enthalpy_units = _enthalpy_units.ptr
+                        if reactant._enthalpy_is_weight_units:
+                            cea_reactants[i].enthalpy = float(reactant.enthalpy) * float(reactant.molecular_weight) / 1000.0
+                        else:
+                            cea_reactants[i].enthalpy = float(reactant.enthalpy)
+                        cea_reactants[i].enthalpy_units = _encoded.ptr
 
                     if reactant.temperature is not None:
                         cea_reactants[i].has_temperature = 1

source/bind/python/cea/samples/rp1311/example5.py

@@ -34,17 +34,17 @@
     "(HCOOH)2", "C6H6(L)", "C7H8(L)", "C8H18(L),n-octa", "Jet-A(L)", "H2O(s)", "H2O(L)",
 ]
 
-# Convert h,cal = -2999.082 cal/mol to SI J/kg for Python Reactant input.
-chos_binder_mw_kg_per_mol = 14.6652984484e-3
-chos_binder_h_si = cea.units.cal_to_joule(-2999.082) / chos_binder_mw_kg_per_mol
+# CHOS-Binder reference enthalpy from RP-1311 example input.
+chos_binder_h_cal_per_mol = -2999.082
 
 reactants = [
     "NH4CLO4(I)",
     cea.Reactant(
         name="CHOS-Binder",
         formula={"C": 1.0, "H": 1.86955, "O": 0.031256, "S": 0.008415},
         molecular_weight=14.6652984484,
-        enthalpy=chos_binder_h_si,
+        enthalpy=chos_binder_h_cal_per_mol,
+        enthalpy_units="cal/mol",
         temperature=298.15,
     ),
     "AL(cr)",