ct.Reaction(reactants=..., products=...) treats species appearing on both sides as a third-body collider

[rwest]

Problem description

When constructing a ct.Reaction using the reactants/products dict form, any species that appears in both dicts with equal stoichiometry (a net spectator or surface catalyst — one that is consumed and immediately regenerated) is silently re-interpreted as a third-body collider. This corrupts the reaction's input_data: the equation string has the spectator's stoichiometry doubled, and a spurious efficiencies entry is added. The corrupted input_data cannot be round-tripped — writing it to YAML and loading it back raises a CanteraError.

The bug affects ArrheniusRate, InterfaceArrheniusRate, and StickingArrheniusRate (tested on 3.1.0 and 3.2.0).

Steps to reproduce

Run the following script (also attached):

import cantera as ct

print(f"Cantera version: {ct.__version__}")

# A + B <=> C + B   (B is a net spectator: appears once on each side)
rxn = ct.Reaction(
    reactants={"A": 1, "B": 1},
    products={"C": 1, "B": 1},
    rate=ct.InterfaceArrheniusRate(1e13, 0, 0),
)
print(dict(rxn.input_data))

Behavior

Actual output:

Cantera version: 3.2.0
{'equation': 'A + B + B <=> B + C + B',
 'rate-constant': {'A': 10000000000000.0, 'b': 0.0, 'Ea': 0.0},
 'efficiencies': {'B': 1.0}}

Expected output (no change to stoichiometry, no efficiencies key):

{'equation': 'A + B <=> C + B',
 'rate-constant': {'A': 10000000000000.0, 'b': 0.0, 'Ea': 0.0}}

B has been added an extra time on each side (stoichiometry incorrectly doubled) and a spurious efficiencies: {B: 1.0} entry has appeared. The same behaviour occurs with ArrheniusRate and StickingArrheniusRate. For higher stoichiometry — e.g. reactants={"A": 1, "B": 2}, products={"C": 1, "B": 2} — the collider is always added with stoichiometry 1 regardless, giving A + 2 B + B <=> 2 B + C + B.

Workaround: passing the same reaction as an equation string produces correct output:

rxn = ct.Reaction(
    equation="A + B <=> C + B",
    rate=ct.InterfaceArrheniusRate(1e13, 0, 0),
)
# {'equation': 'A + B <=> B + C', 'rate-constant': {...}}  ✓

Round-trip failure: writing the corrupted input_data to a YAML file and loading it back raises:

CanteraError: Reaction '2 B + A <=> C + 2 B' specifies efficiency parameters
but does not involve third body colliders.

(For surface reactions. Gas-phase reactions fail similarly because the dict simultaneously contains rate-constant and efficiencies, which are mutually exclusive.)

System information

• Cantera version: 3.1.0 and 3.2.0 (both affected)
• OS: macOS 15.3 (darwin)
• Python version: 3.11

Attachments

See attached cantera_spectator_bug.py for a complete script covering all affected rate types and demonstrating the workaround.

Additional context

We encountered this while writing a Cantera YAML serialiser for RMG-Py (Reaction Mechanism Generator). Surface reactions from the Surface_Abstraction_Beta kinetics family involve a hydrogen-donor species that is regenerated, so it appears on both sides of the equation — e.g. XCOH + XCHOH <=> XCHO + XCHOH. This triggered the misclassification for every such reaction, and the resulting YAML files could not be loaded by Cantera. We have applied a workaround in the RMG writer layer, but it would be cleaner to fix this in the ct.Reaction constructor.

cantera_spectator_bug.py

Issue drafted in collaboration with Claude Code

[rwest]

Follow-up: the equation-string workaround isn't always enough

Working on the RMG writer we hit a second case where this misclassification reappears even with the equation-string form. Once the reaction has three or more distinct species (or stoichiometric items) on one side, a spectator on both sides is still flagged as a third-body collider.

Minimal reproducer on Cantera 3.2.0:

import cantera as ct

# 2 species each side, spectator B  -- workaround works
r1 = ct.Reaction(equation="A + B <=> C + B", rate=ct.InterfaceArrheniusRate())
print(r1.reaction_type, dict(r1.input_data))
# interface-Arrhenius  {'equation': 'A + B <=> B + C'}   ✓

# 3 distinct species on one side, spectator B  -- bug returns
r2 = ct.Reaction(equation="A + B <=> C + D + B", rate=ct.InterfaceArrheniusRate())
print(r2.reaction_type, dict(r2.input_data))
# three-body-interface-Arrhenius  {'equation': 'B + A <=> C + D + B', 'efficiencies': {'B': 1.0}}   ✗

# Three *stoichiometric* items on one side is also enough
r3 = ct.Reaction(equation="A + B <=> 2 X + B", rate=ct.InterfaceArrheniusRate())
print(r3.reaction_type, dict(r3.input_data))
# three-body-interface-Arrhenius  {'equation': 'A + B <=> B + 2 X', 'efficiencies': {'B': 1.0}}   ✗

So the trigger is broader than "spectator with 2-and-2": any spectator with ≥3 stoich items on either side is reclassified.

We hit this in the wild on a balanced surface reaction:

COOH_X(54) + vacantX(6) <=> CO2(2) + HX(20) + vacantX(6)

vacantX is a true spectator (stoichiometry 1 on each side), but the right side has three distinct species, so Cantera classifies the reaction as three-body-interface-Arrhenius and input_data gains efficiencies: {vacantX(6): 1.0}. The resulting YAML is then rejected on load with

CanteraError: Reaction '...' specifies efficiency parameters but does not involve third body colliders.

Stripping the efficiencies is enough to make the YAML round-trip cleanly. We've applied that as a writer-side workaround in RMG, but the underlying misclassification is the same one this issue describes; just under a different trigger.

[ischoegl]

Thanks for reporting, @rwest. This is clearly a case where inherited logic from the ArrheniusRate context does not extrapolate to interface reactions. For gas-phase, the automatic identification of species occurring on both sides as third-body colliders is imho legit. I agree that this should be fixed in Cantera rather than being patched in RMG.

[speth]

It looks like there are several problematic going on here related to the third-body handling. Some of these are just plain incorrect, while others may be things where we have to make a choice about what we want the behavior to be.

Some of these example reactions (A + B = C + B) shouldn't trigger the three-body handling at all, because they don't satisfy the requirement "The sum of the stoichiometric coefficients for either the reactants or products is 3."

In any case where we do decide that B is a third body, the stoichiometry should be automatically adjusted. The duplication behavior seen here is simply incorrect.

Reaction::setEquation(const string& equation, const Kinetics* kin) implements most of the logic involved here. This function is invoked with a valid Kinetics object when constructing reactions from YAML input, and this is of course the most-used and most-tested route. One problem that shows up in these examples is that creating a Reaction from an equation without a Kinetics object means that we can't skip the third-body logic for interface phases on that basis, since we have no idea what kind of phase this reaction is associated with.

The constructor Reaction::Reaction(const Composition& reactants_, const Composition& products_, shared_ptr<ReactionRate> rate_, shared_ptr<ThirdBody> tbody_) on the other hand has only a subset of the third-body logic implemented.

Suggested resolution:
I think we could mostly resolve this issue by deciding that when a Reaction is explicitly constructed from reactants and products dictionaries, that these species should not be handled as third-bodies. If the user wants to specify a specific third body, there is an argument available for that purpose. The one tricky thing here will be making sure that such reactions are serialized to YAML in a way that preserves this behavior. I think this might require a new YAML flag.

To deal with cases like ct.Reaction(equation="A + B <=> 2 X + B", rate=ct.InterfaceArrheniusRate()), I think we can change the logic for detecting interface reactions by looking at the type of the supplied rate object. Unlike the Kinetics object, this is a required argument when constructing the reaction from either reactants/products or from an equation.