Skip to content

Add enthalpy_units optional argument to Reactant in Python API#66

Merged
markleader merged 2 commits intonasa:mainfrom
markleader:fix/python-legacy-div
Mar 23, 2026
Merged

Add enthalpy_units optional argument to Reactant in Python API#66
markleader merged 2 commits intonasa:mainfrom
markleader:fix/python-legacy-div

Conversation

@markleader
Copy link
Contributor

@markleader markleader commented Mar 23, 2026

Summary

Add explicit enthalpy_units support to the Python cea.Reactant API with a backward-compatible transition path.
Current implicit behavior is preserved for now (enthalpy defaults to J/kg), but omission now emits a deprecation-style FutureWarning and documentation/examples are updated to use explicit units. Thanks to @minh-dng for flagging the issue. Partial fix for #65.

Changes

  • Python API (source/bind/python/CEA.pyx)

    • Added enthalpy_units argument to Reactant(...).
    • Added normalization/validation for enthalpy units (case-insensitive, whitespace-tolerant).
    • Supported units:
      • Weight-based: J/kg, kJ/kg, cal/kg, kcal/kg
      • Molar-based: J/mol, kJ/mol, cal/mol, kcal/mol
      • /mol and /mole spellings accepted and normalized.
    • If enthalpy is provided and enthalpy_units is omitted:
      • preserve legacy default behavior (J/kg)
      • emit FutureWarning recommending explicit enthalpy_units.
    • Enforced molecular-weight requirement only for weight-based enthalpy units (*/kg).
    • Updated Mixture reactant bridging logic to use per-reactant enthalpy units and conversion path:
      • weight-based inputs convert with molecular weight
      • core-facing units remain molar (*/mole).
  • Docs and examples

    • Updated:
      • docs/source/interfaces/python_api.rst
      • docs/source/examples/equilibrium/example5.rst
      • source/bind/python/cea/samples/rp1311/example5.py
    • All updated examples now pass explicit enthalpy_units.
  • Tests (source/bind/python/tests/test_rp1311_samples.py)

    • Updated Example 5 custom-reactant test to explicit enthalpy_units.
    • Added targeted coverage for:
      • omitted enthalpy_units warning + behavior preservation
      • explicit molar units without MW requirement
      • explicit weight units with MW requirement
      • weight-without-MW error path
      • accepted unit spellings across required set
      • molar/weight equivalence for same physical enthalpy input

Testing

  • ctest -R cea_core_test -V
  • python -m pytest

Compatibility / Numerical behavior

  • No expected changes to numerical results
  • Expected changes (explain and provide validation)

Expected behavior changes are API-facing (validation/warnings):

  • New FutureWarning when Reactant.enthalpy is given without enthalpy_units.
  • New ValueError when weight-based enthalpy units are used without molecular_weight.
  • Existing omitted-units numerics are intentionally preserved in this PR (legacy default remains J/kg).

@markleader markleader merged commit a9d72b3 into nasa:main Mar 23, 2026
21 checks passed
@markleader markleader deleted the fix/python-legacy-div branch March 23, 2026 17:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant