Reactions & kinetics¶

Reaction stoichiometry and standard-state thermochemistry, chemical-reaction equilibrium, and differentiable rate laws.

See the reactions & reactors guide for worked examples.

Stoichiometry & thermochemistry¶

reactions ¶

Reaction stoichiometry and standard-state thermochemistry.

This module turns a chemical reaction into the temperature-dependent quantities that govern chemical equilibrium:

the standard enthalpy of reaction delta_h_rxn (DH_rxn(T)),
the standard entropy of reaction delta_s_rxn (DS_rxn(T)),
the standard Gibbs energy of reaction delta_g_rxn (DG_rxn(T)), and
the thermodynamic equilibrium constant equilibrium_constant (K(T) = exp(-DG_rxn / R T)).

All four follow from the component standard formation properties (hform_ig and gform_ig, the ideal-gas enthalpy and Gibbs energy of formation at 298.15 K) corrected to the reaction temperature with Kirchhoff's law, integrating the ideal-gas heat capacities (fugacio.thermo.ideal.enthalpy_ig / entropy_ig)::

DH_rxn(T) = sum_i nu_i [ Hf_i + integral_{T0}^{T} Cp_i dT ]
DS_rxn(T) = DS_rxn(T0) + sum_i nu_i integral_{T0}^{T} (Cp_i / T) dT
DG_rxn(T) = DH_rxn(T) - T DS_rxn(T)

with DS_rxn(T0) = (DH_rxn(T0) - DG_rxn(T0)) / T0. Everything is written in jax.numpy, so K(T) is differentiable in temperature and in the underlying formation/heat-capacity parameters (handy for data regression and for sensitivity of conversion to thermochemistry).

The standard state is the ideal gas at P_REF (1 bar), matching the tabulated formation data; the equilibrium constant is therefore in terms of fugacities referenced to 1 bar (see fugacio.thermo.reaction_equilibrium).

Classes:

Name	Description
`Reaction`	A chemical reaction: a stoichiometric vector over an ordered component list.
`ReactionProperties`	Standard-state reaction properties at a temperature.

Functions:

Name	Description
`stoichiometry`	Build a stoichiometric vector aligned with `components`.
`parse_reaction`	Parse a reaction string such as `"nitrogen + 3 hydrogen = 2 ammonia"`.
`reaction_arrays`	Standard formation data for `components` from the curated database.
`delta_h_rxn`	Standard enthalpy of reaction `DH_rxn(T)` (J/mol), via Kirchhoff's law.
`delta_s_rxn`	Standard entropy of reaction `DS_rxn(T)` (J/mol/K).
`delta_g_rxn`	Standard Gibbs energy of reaction `DG_rxn(T) = DH_rxn - T DS_rxn` (J/mol).
`equilibrium_constant`	Thermodynamic equilibrium constant `K(T) = exp(-DG_rxn / R T)`.
`reaction_properties`	All standard reaction properties at `t` for a `Reaction`.
`equilibrium_constant_of`	Equilibrium constant `K(T)` for a `Reaction` (database-resolved).

Reaction `dataclass` ¶

Reaction(components: tuple[str, ...], nu: Array)

A chemical reaction: a stoichiometric vector over an ordered component list.

Attributes:

Name	Type	Description
`components`	`tuple[str, ...]`	Ordered component names (the alignment of `nu`).
`nu`	`Array`	Stoichiometric coefficients (negative reactants, positive products).

Methods:

Name	Description
`of`	Build a reaction from reactant/product coefficient maps.
`parse`	Build a reaction from an equation string (see `parse_reaction`).

reactants `property` ¶

reactants: dict[str, float]

{name: coefficient} for the consumed species (positive coefficients).

products `property` ¶

products: dict[str, float]

{name: coefficient} for the produced species (positive coefficients).

delta_n `property` ¶

delta_n: float

Change in moles sum(nu) (mole change of the gas phase per extent).

of `staticmethod` ¶

of(
    components: Sequence[str],
    reactants: Mapping[str, float],
    products: Mapping[str, float],
) -> Reaction

Build a reaction from reactant/product coefficient maps.

parse `staticmethod` ¶

parse(equation: str, components: Sequence[str]) -> Reaction

Build a reaction from an equation string (see parse_reaction).

ReactionProperties ¶

Bases: NamedTuple

Standard-state reaction properties at a temperature.

Attributes:

Name	Type	Description
`delta_h`	`Array`	Standard enthalpy of reaction `DH_rxn(T)` (J/mol).
`delta_s`	`Array`	Standard entropy of reaction `DS_rxn(T)` (J/mol/K).
`delta_g`	`Array`	Standard Gibbs energy of reaction `DG_rxn(T)` (J/mol).
`ln_k`	`Array`	Natural log of the equilibrium constant.
`k`	`Array`	Equilibrium constant `exp(-DG_rxn / R T)` (dimensionless).

stoichiometry ¶

stoichiometry(
    components: Sequence[str],
    reactants: Mapping[str, float],
    products: Mapping[str, float],
) -> Array

Build a stoichiometric vector aligned with components.

Reactant coefficients are stored negative, products positive. Coefficients are summed, so a species appearing on both sides nets out.

Parameters:

Name	Type	Description	Default
`components`	`Sequence[str]`	The ordered component names the vector is aligned to.	required
`reactants`	`Mapping[str, float]`	`{name: coefficient}` consumed by the reaction (positive).	required
`products`	`Mapping[str, float]`	`{name: coefficient}` produced by the reaction (positive).	required

Returns:

Type	Description
`Array`	The stoichiometric coefficient array `nu` of shape `(len(components),)`.

parse_reaction ¶

parse_reaction(
    equation: str, components: Sequence[str]
) -> Array

Parse a reaction string such as "nitrogen + 3 hydrogen = 2 ammonia".

Sides are separated by = (also ->, <=>, ⇌); terms by +. Each term is an optional numeric coefficient followed by a component name exactly as it appears in components (names may contain spaces). Matching is case-insensitive.

Returns:

Type	Description
`Array`	The stoichiometric vector aligned with `components`.

Raises:

Type	Description
`ValueError`	if the string has no side separator or names an unknown species.

reaction_arrays ¶

reaction_arrays(
    components: Sequence[str],
) -> tuple[Array, Array, CpCoeffs]

Standard formation data for components from the curated database.

Returns:

Type	Description
`Array`	`(hf, gf, (a, b, c, d, e))`: ideal-gas formation enthalpies and Gibbs
`Array`	energies (J/mol at 298.15 K) and the stacked ideal-gas `Cp` coefficients.

Raises:

Type	Description
`ValueError`	if any component lacks formation or heat-capacity data.

delta_h_rxn ¶

delta_h_rxn(
    nu: Array,
    t: ArrayLike,
    hf: Array,
    a: Array,
    b: Array,
    c: Array,
    d: Array,
    e: Array,
) -> Array

Standard enthalpy of reaction DH_rxn(T) (J/mol), via Kirchhoff's law.

delta_s_rxn ¶

delta_s_rxn(
    nu: Array,
    t: ArrayLike,
    hf: Array,
    gf: Array,
    a: Array,
    b: Array,
    c: Array,
    d: Array,
    e: Array,
) -> Array

Standard entropy of reaction DS_rxn(T) (J/mol/K).

delta_g_rxn ¶

delta_g_rxn(
    nu: Array,
    t: ArrayLike,
    hf: Array,
    gf: Array,
    a: Array,
    b: Array,
    c: Array,
    d: Array,
    e: Array,
) -> Array

Standard Gibbs energy of reaction DG_rxn(T) = DH_rxn - T DS_rxn (J/mol).

equilibrium_constant ¶

equilibrium_constant(
    nu: Array,
    t: ArrayLike,
    hf: Array,
    gf: Array,
    a: Array,
    b: Array,
    c: Array,
    d: Array,
    e: Array,
) -> Array

Thermodynamic equilibrium constant K(T) = exp(-DG_rxn / R T).

reaction_properties ¶

reaction_properties(
    reaction: Reaction, t: ArrayLike
) -> ReactionProperties

All standard reaction properties at t for a Reaction.

Resolves the component formation/heat-capacity data from the curated database and evaluates delta_h_rxn, delta_s_rxn, delta_g_rxn, and equilibrium_constant.

equilibrium_constant_of ¶

equilibrium_constant_of(
    reaction: Reaction, t: ArrayLike
) -> Array

Equilibrium constant K(T) for a Reaction (database-resolved).

Reaction equilibrium¶

reaction_equilibrium ¶

Chemical-reaction equilibrium: solve for the equilibrium composition.

Given one or more reactions, a feed (in moles), and (T, P), this module finds the extents of reaction that make each reaction's activity quotient equal to its equilibrium constant K_j(T) (from fugacio.thermo.reactions). For a gas phase the activity of species i is

a_i = y_i P / P_ref for an ideal gas (basis="ideal-gas"), or
a_i = y_i phi_i P / P_ref for a real gas, with fugacity coefficients phi_i from the cubic EOS (basis="phi"),

so the equilibrium condition for reaction j is sum_i nu_ij ln a_i = ln K_j(T).

The unknowns are the reaction extents xi (one per reaction); the full composition is n = n_feed + xi . Nu. A single reaction is solved by a robust bracketed root over the physically feasible extent range; several simultaneous reactions are solved by a damped Newton system. Both solvers differentiate the converged extent with respect to T, P, and the feed by implicit differentiation (see fugacio.thermo.implicit), so conversions and yields carry exact gradients.

The standard state is the ideal gas at P_ref (1 bar), matching the tabulated formation data used to build K(T).

Classes:

Name	Description
`EquilibriumResult`	Outcome of a reaction-equilibrium calculation.

Functions:

Name	Description
`equilibrium`	Solve for the equilibrium composition of a reacting gas mixture.
`conversion`	Fractional conversion of a feed component, `(n0 - n_eq) / n0`.

EquilibriumResult ¶

Bases: NamedTuple

Outcome of a reaction-equilibrium calculation.

Attributes:

Name	Type	Description
`extent`	`Array`	Equilibrium extent of each reaction (mol), shape `(R,)`.
`moles`	`Array`	Equilibrium moles of each component, shape `(n,)`.
`y`	`Array`	Equilibrium mole fractions, shape `(n,)`.
`k`	`Array`	Equilibrium constant of each reaction at `T`, shape `(R,)`.

equilibrium ¶

equilibrium(
    reactions: Reaction | Sequence[Reaction],
    n_feed: Array,
    t: ArrayLike,
    p: ArrayLike,
    *,
    basis: str = "ideal-gas",
    eos: CubicEOS = PR,
    tc: Array | None = None,
    pc: Array | None = None,
    omega: Array | None = None,
    kij: Array | None = None,
    tol: float = 1e-11,
    max_iter: int = 60,
) -> EquilibriumResult

Solve for the equilibrium composition of a reacting gas mixture.

Parameters:

Name	Type	Description	Default
`reactions`	`Reaction \| Sequence[Reaction]`	A single `Reaction` or several sharing the same component ordering.	required
`n_feed`	`Array`	Feed amounts per component (mol), shape `(n,)`.	required
`t`	`ArrayLike`	Temperature (K).	required
`p`	`ArrayLike`	Pressure (Pa).	required
`basis`	`str`	`"ideal-gas"` (`a_i = y_i P/P_ref`) or `"phi"` (EOS fugacity coefficients).	`'ideal-gas'`
`eos`	`CubicEOS`	Cubic EOS used when `basis="phi"`.	`PR`
`tc`	`Array \| None`	Component critical temperatures (K), required for `"phi"`.	`None`
`pc`	`Array \| None`	Component critical pressures (Pa), required for `"phi"`.	`None`
`omega`	`Array \| None`	Component acentric factors, required for `"phi"`.	`None`
`kij`	`Array \| None`	Optional binary interaction matrix for the EOS.	`None`
`tol`	`float`	Convergence tolerance on the reaction extents.	`1e-11`
`max_iter`	`int`	Maximum number of solver iterations.	`60`

Returns:

Type	Description
`EquilibriumResult`	An `EquilibriumResult` with extents, moles, mole fractions, and
`EquilibriumResult`	`K(T)`. Differentiable in `t`, `p`, and `n_feed`.

conversion ¶

conversion(
    result: EquilibriumResult,
    n_feed: Array,
    component_index: int,
) -> Array

Fractional conversion of a feed component, (n0 - n_eq) / n0.

Kinetics¶

kinetics ¶

Differentiable reaction-rate laws.

A rate law maps the local state of a reacting mixture, temperature T and the concentration vector c (mol/m^3, aligned with a component list), to the intensive rate of one reaction r (mol/m^3/s). The reactor models in fugacio.sim.reactors multiply that rate by the stoichiometry of a Reaction to get species production rates.

Every rate law here is a small frozen dataclass registered as a JAX pytree, so its kinetic parameters (pre-exponential factors, activation energies, reaction orders, adsorption constants) are differentiable leaves. That makes rate constants fittable from data by the same machinery as the thermodynamic models (fugacio.thermo.regression) and lets reactor outputs be differentiated with respect to the kinetics.

Provided laws:

arrhenius / Arrhenius: the rate constant k(T) = A exp(-Ea/RT);
PowerLaw: an irreversible power-law rate k(T) * prod_i c_i^{m_i};
MassActionReversible: an elementary reversible rate k_f prod_{reactants} c^{|nu|} - k_r prod_{products} c^{nu};
LHHW: a Langmuir-Hinshelwood / Hougen-Watson rate with an adsorption inhibition term in the denominator.

Concentrations are clipped at zero before being raised to (possibly fractional) powers, so a depleted species contributes a finite, well-behaved zero rate.

Classes:

Name	Description
`Arrhenius`	An Arrhenius rate constant `k(T) = a exp(-ea / R T)`.
`PowerLaw`	Irreversible power-law rate `r = k(T) * prod_i c_i^{orders_i}`.
`MassActionReversible`	Elementary reversible mass-action rate.
`LHHW`	Langmuir-Hinshelwood / Hougen-Watson rate with adsorption inhibition.

Functions:

Name	Description
`arrhenius`	Arrhenius rate constant `k(T) = A exp(-Ea / R T)`.
`arrhenius_ref`	Reference-temperature Arrhenius form `k(T) = k_ref exp(-Ea/R (1/T - 1/T_ref))`.

Arrhenius `dataclass` ¶

Arrhenius(a: Array, ea: Array)

An Arrhenius rate constant k(T) = a exp(-ea / R T).

Attributes:

Name	Type	Description
`a`	`Array`	Pre-exponential factor.
`ea`	`Array`	Activation energy (J/mol).

Methods:

Name	Description
`k`	Rate constant at temperature `t`.

k ¶

k(t: ArrayLike) -> Array

Rate constant at temperature t.

PowerLaw `dataclass` ¶

PowerLaw(a: Array, ea: Array, orders: Array)

Irreversible power-law rate r = k(T) * prod_i c_i^{orders_i}.

Attributes:

Name	Type	Description
`a`	`Array`	Pre-exponential factor of the Arrhenius rate constant.
`ea`	`Array`	Activation energy (J/mol).
`orders`	`Array`	Reaction order in each component's concentration (aligned with `c`); typically zero for species that do not appear in the rate.

Methods:

Name	Description
`rate`	Reaction rate (mol/m^3/s) at temperature `t` and concentrations `c`.

rate ¶

rate(t: ArrayLike, c: Array) -> Array

Reaction rate (mol/m^3/s) at temperature t and concentrations c.

MassActionReversible `dataclass` ¶

MassActionReversible(
    a_f: Array,
    ea_f: Array,
    a_r: Array,
    ea_r: Array,
    nu: Array,
)

Elementary reversible mass-action rate.

r = k_f(T) prod_{reactants} c_i^{|nu_i|} - k_r(T) prod_{products} c_i^{nu_i}

with both rate constants in Arrhenius form. The stoichiometric vector nu (negative reactants, positive products) sets the concentration orders, so the law is thermodynamically consistent: at equilibrium r = 0 implies the concentration quotient equals k_f / k_r = K_c.

Attributes:

Name	Type	Description
`a_f,`	`ea_f`	Forward pre-exponential and activation energy (J/mol).
`a_r,`	`ea_r`	Reverse pre-exponential and activation energy (J/mol).
`nu`	`Array`	Stoichiometric coefficients (negative reactants, positive products).

Methods:

Name	Description
`rate`	Net reaction rate (mol/m^3/s) at temperature `t` and concentrations `c`.

rate ¶

rate(t: ArrayLike, c: Array) -> Array

Net reaction rate (mol/m^3/s) at temperature t and concentrations c.

LHHW `dataclass` ¶

LHHW(
    a: Array,
    ea: Array,
    orders: Array,
    k_ads: Array,
    ads_orders: Array,
    sites: float = 1.0,
)

Langmuir-Hinshelwood / Hougen-Watson rate with adsorption inhibition.

r = k(T) * prod_i c_i^{orders_i} / (1 + sum_i k_ads_i c_i^{ads_orders_i})^n

The numerator is a power-law driving force; the denominator captures competitive adsorption on a catalyst surface. n is the (static) number of active sites in the rate-determining step.

Attributes:

Name	Type	Description
`a,`	`ea`	Arrhenius parameters of the surface rate constant.
`orders`	`Array`	Concentration orders of the driving-force numerator.
`k_ads`	`Array`	Adsorption equilibrium constants per component (0 for inert/non-adsorbing).
`ads_orders`	`Array`	Concentration orders inside the adsorption sum.
`sites`	`float`	Denominator exponent `n` (number of sites; static).

Methods:

Name	Description
`rate`	Reaction rate (mol/m^3/s) at temperature `t` and concentrations `c`.

rate ¶

rate(t: ArrayLike, c: Array) -> Array

Reaction rate (mol/m^3/s) at temperature t and concentrations c.

arrhenius ¶

arrhenius(
    t: ArrayLike, a: ArrayLike, ea: ArrayLike
) -> Array

Arrhenius rate constant k(T) = A exp(-Ea / R T).

Parameters:

Name	Type	Description	Default
`t`	`ArrayLike`	Temperature (K).	required
`a`	`ArrayLike`	Pre-exponential factor (same units as the returned `k`).	required
`ea`	`ArrayLike`	Activation energy (J/mol).	required

arrhenius_ref ¶

arrhenius_ref(
    t: ArrayLike,
    k_ref: ArrayLike,
    ea: ArrayLike,
    t_ref: float = T_REF,
) -> Array

Reference-temperature Arrhenius form k(T) = k_ref exp(-Ea/R (1/T - 1/T_ref)).

Numerically better conditioned than arrhenius for regression, because k_ref is the rate constant at t_ref (an O(1)-scaled quantity) rather than the extrapolated intercept A.

Reactions & kinetics¶

Stoichiometry & thermochemistry¶

reactions ¶

Reaction dataclass ¶

reactants property ¶

products property ¶

delta_n property ¶

of staticmethod ¶

parse staticmethod ¶

ReactionProperties ¶

stoichiometry ¶

parse_reaction ¶

reaction_arrays ¶

delta_h_rxn ¶

delta_s_rxn ¶

delta_g_rxn ¶

equilibrium_constant ¶

reaction_properties ¶

equilibrium_constant_of ¶

Reaction equilibrium¶

reaction_equilibrium ¶

EquilibriumResult ¶

equilibrium ¶

conversion ¶

Kinetics¶

kinetics ¶

Arrhenius dataclass ¶

k ¶

PowerLaw dataclass ¶

rate ¶

MassActionReversible dataclass ¶

rate ¶

LHHW dataclass ¶

rate ¶

arrhenius ¶

arrhenius_ref ¶

Reaction `dataclass` ¶

reactants `property` ¶

products `property` ¶

delta_n `property` ¶

of `staticmethod` ¶

parse `staticmethod` ¶

Arrhenius `dataclass` ¶

PowerLaw `dataclass` ¶

MassActionReversible `dataclass` ¶

LHHW `dataclass` ¶