added C and Python support for custom reactant data (#53)

added C and Python support for custom reactant data

Author: markleader

CHANGELOG.md

@@ -5,10 +5,20 @@ All notable user-visible changes to this project are documented here.
 ## [Unreleased]
 
 ### Changed
+- Python `Mixture` input validation now accepts `str` and `cea.Reactant` entries (including mixed lists) and no longer accepts raw `bytes` species names (`#53`).
+- Added SI-focused custom-reactant handling at the Python API layer: `Reactant.temperature` is specified in K and `Reactant.enthalpy` in J/kg (converted internally for core input) (`#53`).
+- Legacy input parsing now supports repeated `outp` dataset keywords (including multiline forms) by merging successive `outp` entries during dataset assembly (`#52`).
 
 ### Fixed
+- Legacy CLI equilibrium/rocket/shock workflows now propagate `include_ions` into generated product mixtures so ionized products are retained when requested (`#52`).
 
 ### Added
+- Added C and Python support for custom reactant data (including species not present in `thermo.lib`) in parity with the main interface workflow used by RP-1311 Example 5 (`#53`).
+- Added new C-API constructors for generating product mixtures from input-reactant payloads:
+  - `cea_mixture_create_products_from_input_reactants` (`#53`).
+  - `cea_mixture_create_products_from_input_reactants_w_ions` (`#53`).
+- Added a shared bindc parser path for `cea_reactant_input -> ReactantInput` conversion to reduce duplicated C-binding logic (`#53`).
+- Added Python `cea.Reactant` and mixed-input `Mixture(...)` support in the Cython binding (`#53`).
 
 ## [3.1.0] - 2026-03-02
 

docs/source/examples/equilibrium/example5.rst

@@ -0,0 +1,54 @@
+Example 5 from RP-1311
+======================
+.. note:: The python script for this example is available in the `source/bind/python/cea/samples` directory of the CEA repository.
+
+Here we describe how to run example 5 from RP-1311 [1]_ using the Python API.
+This is an HP equilibrium problem for a solid propellant blend with five reactants,
+including one custom reactant (``CHOS-Binder``) that is not present in ``thermo.lib``.
+
+First import the required libraries:
+
+.. code-block:: python
+
+    import numpy as np
+    import cea
+
+Define the pressure schedule and reactant composition by weight fraction:
+
+.. code-block:: python
+
+    pressures = np.array([34.473652, 17.236826, 8.618413, 3.447365, 0.344737])
+    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.
+
+.. 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
+
+    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,
+            temperature=298.15,
+        ),
+        "AL(cr)",
+        "MgO(cr)",
+        "H2O(L)",
+    ]
+
+Then build reactant/product mixtures, solve the HP problem, and print the full table output:
+
+.. literalinclude:: ../../../../source/bind/python/cea/samples/rp1311/example5.py
+   :language: python
+
+.. rubric:: References
+
+.. [1] B. J. McBride and S. Gordon, *Computer Program for Calculation of Complex Chemical Equilibrium Compositions and Applications*, NASA RP-1311, 1996.

docs/source/examples/equilibrium_examples.rst

@@ -10,4 +10,5 @@ This section describes how to solve equilibrium problems using the Python interf
    equilibrium/example2
    equilibrium/example3
    equilibrium/example4
-   equilibrium/example14
+   equilibrium/example5
+   equilibrium/example14

docs/source/interfaces/python_api.rst

@@ -9,6 +9,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.
+
+.. autoclass:: cea.Reactant
+   :members:
 
 .. autoclass:: cea.Mixture
    :members:

source/bind/c/CMakeLists.txt

@@ -56,6 +56,15 @@ if (CEA_BUILD_TESTING)
         COMMAND cea_bindc_rp1311_ex3
         WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
     )
+
+    add_executable(cea_bindc_rp1311_ex5 samples/rp1311_example5.c)
+    target_link_libraries(cea_bindc_rp1311_ex5 PRIVATE cea::bindc)
+    add_test(
+        NAME cea_bindc_rp1311_ex5
+        COMMAND cea_bindc_rp1311_ex5
+        WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+    )
+
     add_executable(cea_bindc_rp1311_ex6 samples/rp1311_example6.c)
     target_link_libraries(cea_bindc_rp1311_ex6 PRIVATE cea::bindc)
     add_test(
@@ -89,4 +98,3 @@ if (CEA_BUILD_TESTING)
     )
 
 endif()
-