Reactions

Reaction{NRin, NRout, Ph<:AbstractPropertyFunction} <: AbstractReaction

A single decomposition reaction with Arrhenius kinetics, n-ary in both reactants and products.

The reaction rate is computed as:

r = A * exp(-E/RT) * ∏_i ξ_{r_i}^{n_i} * H(T - T_min) * H(T_max - T)

where the product runs over reactants. Per unit reaction extent, the first reactant is consumed with mass stoichiometry 1.0; products are produced with their per-product stoich from the products tuple.

Reaction orders must be n ≥ 0 (enforced at construction; a negative order makes the rate singular at reactant depletion). At runtime each reactant also contributes a smooth tanh(ξ/ξ_th) depletion factor to the rate, and the hard temperature gates H(·) are realized as smooth tanh ramps — see Pyrolysis.Physics.reaction_rate and DepletionLimiter.

Type Parameters

• NRin: Number of reactants
• NRout: Number of products
• Ph: Heat-of-reaction property type

Fields

• name::Symbol: Reaction identifier
• reactants::NTuple{NRin, Tuple{Int, Float64}}: (component_idx, reaction_order) per reactant.
• products::NTuple{NRout, Tuple{Int, Float64}}: (component_idx, mass_stoich) per product.
• A::Float64: Pre-exponential factor [s⁻¹] or [m³/(kg·s)]
• E::Float64: Activation energy [J/mol]
• heat::Ph: Heat of reaction [J/kg of reactant₁]
• T_min::Float64: Minimum temperature for reaction [K]
• T_max::Float64: Maximum temperature for reaction [K]

Mass-balance convention

For multi-reactant reactions (NRin > 1), additional reactant mass stoichiometries would be required; the current shape supports the single-reactant case used throughout the existing models (NRin == 1, mass consumed = 1·r). Multi-reactant support can extend the per-reactant tuple to 3-ary (idx, order, mass_stoich) without changing this struct's outer shape.

For single-reactant reactions, mass conservation requires Σ stoich(products) == 1.0.

Heat of Reaction Convention

• h > 0: Endothermic (absorbs heat, cools material)
• h < 0: Exothermic (releases heat, heats material)

ReactionSet{NR, RT <: Tuple}

A collection of reactions for a material. The reactions tuple type RT is preserved exactly so heterogeneous reactions (different NRin/NRout/Ph) can coexist without Union allocations in the consumer's iteration.

Type Parameters

• NR: Number of reactions
• RT: Concrete tuple type holding the reactions

Fields

• reactions::RT: Tuple of reactions

Depletion limiter settings for reaction rate computation.

The depletion limiter removes the numerical stiffness of near-zero reactant concentrations by multiplying the reaction rate with a smooth tanh(ξ/threshold) factor per reactant.

Fields

• threshold::Float64: Concentration scale of the rate roll-off [kg/m³]
• enabled::Bool: If false, no limiting is applied (may cause numerical issues)

Behavior

The factor tanh(ξ/threshold) is applied to the rate (not the power-law base) and is C^∞ in ξ — there is no threshold branch, so neither the rate nor its derivative jumps anywhere:

• ξ ≫ threshold: factor → 1 double-exponentially (relative deficit 2e^(-2ξ/threshold): < 4% at 2·threshold, < 5e-9 at 10·threshold) — the bare Arrhenius rate is recovered.
• ξ → 0: the rate vanishes ∝ ξ^(n+1) with bounded ∂r/∂ξ for every reaction order n ≥ 0 — including n = 0, where the unlimited rate would stay at k(T) through ξ = 0 and drive the concentration negative without bound.

Usage

Each Material carries its own limiter; pass a custom one at construction:

Material(name = ..., components = ..., reactions = ...,
         depletion_limiter = DepletionLimiter(threshold = 0.1))

The solver's kinetics path (Pyrolysis.Physics.evaluate_reactions!) reads material.depletion_limiter for every rate evaluation.

Notes

Lower thresholds are more physically accurate but may cause numerical stiffness. For validation studies, temporarily disable with enabled=false. Disabling removes the only depletion guard: order n = 0 reactions then consume reactant at full rate through ξ = 0 (unbounded negative ξ), and orders 0 < n < 1 have a singular ∂r/∂ξ as ξ → 0.