Skip to main content

tpt_sci_kinetics/
lib.rs

1//! # tpt-sci-kinetics
2//!
3//! Heterogeneous and surface **chemical kinetics** for the `tpt-science` pillar,
4//! built from scratch on top of [`tpt_sci_reaction_network`]'s mass-action
5//! engine ([`tpt_sci_ode`] backend).
6//!
7//! The crate adds the two kinetic building blocks most often needed for
8//! catalysis / reactor modelling that plain mass-action CRNs lack:
9//!
10//! * **Arrhenius temperature dependence.** Each reaction carries a pre-exponential
11//!   factor `A` and activation energy `Ea`; its rate constant follows
12//!   `k(T) = A·exp(-Ea / (R·T))` ([`ArrheniusRate`]).
13//! * **Langmuir–Hinshelwood adsorption / surface coverage.** A small site-balance
14//!   solver computes fractional surface coverages `θ_i` from gas-phase partial
15//!   pressures and adsorption equilibria, feeding surface-reaction rates that are
16//!   first order in coverage rather than in gas concentration
17//!   ([`langmuir_hinshelwood_coverages`]), generalized to multiple independent
18//!   site types via [`multi_site_langmuir_hinshelwood_coverages`].
19//! * **Eley–Rideal mechanism.** [`EleyRideal`] models a step where one
20//!   reactant is adsorbed (subject to LH coverage) and the other reacts
21//!   directly from the gas phase, `r = k·θ_adsorbed·[gas_phase]`, pluggable
22//!   into a `ReactionSystem` via [`EleyRideal::into_rate_law`].
23//! * **Coverage-dependent activation energy.** [`CoverageDependentArrheniusRate`]
24//!   extends the Arrhenius law with a linear Brønsted–Evans–Polanyi-style
25//!   dependence `Ea(θ) = Ea0 + α·θ`, giving `k(T, θ) = A·exp(-Ea(θ)/(R·T))`.
26//!
27//! An [`KineticsProblem`] ties an Arrhenius-rate
28//! [`ReactionSystem`](tpt_sci_reaction_network::ReactionSystem) to a
29//! temperature profile and integrates it with `tpt-sci-ode`.
30//!
31//! # Example
32//!
33//! ```
34//! use tpt_sci_kinetics::{ArrheniusRate, langmuir_hinshelwood_coverages};
35//!
36//! // Unimolecular decay with A = 1e13, Ea = 80 kJ/mol.
37//! let r = ArrheniusRate::new(1.0e13, 80_000.0).unwrap();
38//! let k = r.rate_constant(800.0); // T = 800 K
39//! assert!(k > 0.0 && k.is_finite());
40//!
41//! // Two competing adsorbates on a single site type; coverages sum to <= 1.
42//! let theta = langmuir_hinshelwood_coverages(&[1.0, 2.0], &[0.5, 1.0]).unwrap();
43//! let sum: f64 = theta.iter().sum();
44//! assert!(sum <= 1.0 + 1e-9 && sum > 0.0);
45//! ```
46#![forbid(unsafe_code)]
47
48mod error;
49
50pub use error::KineticsError;
51
52mod arrhenius;
53mod constants;
54mod coverage;
55mod coverage_dependent;
56mod eley_rideal;
57mod problem;
58
59pub use arrhenius::ArrheniusRate;
60pub use constants::R_GAS;
61pub use coverage::{langmuir_hinshelwood_coverages, multi_site_langmuir_hinshelwood_coverages};
62pub use coverage_dependent::CoverageDependentArrheniusRate;
63pub use eley_rideal::EleyRideal;
64pub use problem::KineticsProblem;
65
66#[cfg(test)]
67mod tests {
68    use super::*;
69    use approx::assert_abs_diff_eq;
70
71    #[test]
72    fn arrhenius_rises_with_temperature() {
73        let r = ArrheniusRate::new(1.0e13, 80_000.0).unwrap();
74        let k_low = r.rate_constant(600.0);
75        let k_high = r.rate_constant(900.0);
76        assert!(k_high > k_low);
77        assert!(k_low.is_finite() && k_high.is_finite());
78    }
79
80    #[test]
81    fn arrhenius_rejects_invalid() {
82        assert!(ArrheniusRate::new(0.0, 1.0).is_err());
83        assert!(ArrheniusRate::new(1.0, -1.0).is_err());
84    }
85
86    #[test]
87    fn langmuir_hinshelwood_sums_to_one() {
88        let theta = langmuir_hinshelwood_coverages(&[2.0, 3.0], &[1.0, 1.0]).unwrap();
89        // Adsorbed coverages sum to <= 1; the remainder is bare surface.
90        let sum: f64 = theta.iter().sum();
91        assert!(sum <= 1.0 + 1e-12);
92        assert_abs_diff_eq!(sum, 5.0 / 6.0, epsilon = 1e-12);
93        // Stronger adsorber (K=3) takes more coverage.
94        assert!(theta[1] > theta[0]);
95    }
96
97    #[test]
98    fn langmuir_hinshelwood_empty_sites() {
99        // Zero pressure => zero coverage, bare site = 1.
100        let theta = langmuir_hinshelwood_coverages(&[5.0], &[0.0]).unwrap();
101        assert_abs_diff_eq!(theta[0], 0.0, epsilon = 1e-12);
102    }
103
104    #[test]
105    fn kinetics_problem_resolves_constants() {
106        let prob = KineticsProblem::new(vec![
107            ArrheniusRate::new(1.0e13, 80_000.0).unwrap(),
108            ArrheniusRate::new(1.0e10, 40_000.0).unwrap(),
109        ])
110        .unwrap();
111        let ks = prob.rate_constants(800.0);
112        assert_eq!(ks.len(), 2);
113        assert!(ks[0] > 0.0 && ks[1] > 0.0);
114        assert!(KineticsProblem::new(vec![]).is_err());
115    }
116
117    #[test]
118    fn multi_site_reduces_to_single_site() {
119        // All species on the same site type => identical to the single-site fn.
120        let ks = [2.0, 3.0];
121        let ps = [1.0, 1.0];
122        let single = langmuir_hinshelwood_coverages(&ks, &ps).unwrap();
123        let multi = multi_site_langmuir_hinshelwood_coverages(&ks, &ps, &[0, 0]).unwrap();
124        for (s, m) in single.iter().zip(multi.iter()) {
125            assert_abs_diff_eq!(s, m, epsilon = 1e-12);
126        }
127    }
128
129    #[test]
130    fn multi_site_normalizes_independently_per_site_type() {
131        // Species 0,1 on site type 0; species 2 alone on site type 1.
132        let theta = multi_site_langmuir_hinshelwood_coverages(
133            &[2.0, 3.0, 5.0],
134            &[1.0, 1.0, 1.0],
135            &[0, 0, 1],
136        )
137        .unwrap();
138        // Site type 0: theta_i = K_i / (1 + 2 + 3) = K_i / 6.
139        assert_abs_diff_eq!(theta[0], 2.0 / 6.0, epsilon = 1e-12);
140        assert_abs_diff_eq!(theta[1], 3.0 / 6.0, epsilon = 1e-12);
141        // Site type 1: single adsorbate, theta_2 = 5 / (1 + 5) = 5/6, unaffected
142        // by site-type-0 occupancy.
143        assert_abs_diff_eq!(theta[2], 5.0 / 6.0, epsilon = 1e-12);
144        let site0_sum = theta[0] + theta[1];
145        assert!(site0_sum <= 1.0 + 1e-12);
146        assert!(theta[2] <= 1.0 + 1e-12);
147    }
148
149    #[test]
150    fn multi_site_rejects_mismatched_lengths_and_bad_values() {
151        assert!(multi_site_langmuir_hinshelwood_coverages(&[1.0], &[1.0, 2.0], &[0, 0]).is_err());
152        assert!(multi_site_langmuir_hinshelwood_coverages(&[-1.0], &[1.0], &[0]).is_err());
153        assert!(multi_site_langmuir_hinshelwood_coverages(&[1.0], &[-1.0], &[0]).is_err());
154    }
155
156    #[test]
157    fn eley_rideal_zero_when_either_factor_zero() {
158        let er = EleyRideal::new(3.0).unwrap();
159        assert_eq!(er.rate(0.0, 5.0), 0.0);
160        assert_eq!(er.rate(0.5, 0.0), 0.0);
161        assert_eq!(er.rate(0.0, 0.0), 0.0);
162    }
163
164    #[test]
165    fn eley_rideal_linear_in_gas_phase_concentration() {
166        let er = EleyRideal::new(2.0).unwrap();
167        let r1 = er.rate(0.4, 1.0);
168        let r2 = er.rate(0.4, 3.0);
169        // Linear in gas-phase concentration for fixed coverage.
170        assert_abs_diff_eq!(r2, 3.0 * r1, epsilon = 1e-12);
171        assert_abs_diff_eq!(r1, 2.0 * 0.4 * 1.0, epsilon = 1e-12);
172    }
173
174    #[test]
175    fn eley_rideal_rejects_invalid_rate() {
176        assert!(EleyRideal::new(-1.0).is_err());
177        assert!(EleyRideal::new(f64::NAN).is_err());
178    }
179
180    #[test]
181    fn eley_rideal_into_rate_law_matches_direct_rate() {
182        use tpt_sci_reaction_network::ReactionNetwork;
183
184        let er = EleyRideal::new(1.5).unwrap();
185        let mut net = ReactionNetwork::new();
186        let theta_a = net.species("theta_A");
187        let gas_b = net.species("B_gas");
188        let c = net.species("C");
189        net.reaction(
190            &[(theta_a, 1.0), (gas_b, 1.0)],
191            &[(c, 1.0)],
192            er.into_rate_law(0, 1),
193        );
194        let sys = net.build().unwrap();
195        let y = [0.3, 2.0, 0.0];
196        let rates = sys.reaction_rates(&y);
197        assert_abs_diff_eq!(rates[0], er.rate(0.3, 2.0), epsilon = 1e-12);
198    }
199
200    #[test]
201    fn coverage_dependent_matches_plain_arrhenius_when_alpha_zero() {
202        let plain = ArrheniusRate::new(1.0e13, 80_000.0).unwrap();
203        let cov = CoverageDependentArrheniusRate::new(1.0e13, 80_000.0, 0.0).unwrap();
204        for theta in [0.0, 0.3, 1.0] {
205            assert_abs_diff_eq!(
206                cov.rate_constant(800.0, theta),
207                plain.rate_constant(800.0),
208                epsilon = 1e-6
209            );
210        }
211    }
212
213    #[test]
214    fn coverage_dependent_rate_constant_monotonic_in_theta() {
215        // alpha > 0: Ea increases with theta => k decreases with theta.
216        let repulsive = CoverageDependentArrheniusRate::new(1.0e13, 80_000.0, 20_000.0).unwrap();
217        let k_low = repulsive.rate_constant(800.0, 0.0);
218        let k_high = repulsive.rate_constant(800.0, 1.0);
219        assert!(k_high < k_low);
220
221        // alpha < 0: Ea decreases with theta => k increases with theta.
222        let promoting = CoverageDependentArrheniusRate::new(1.0e13, 80_000.0, -20_000.0).unwrap();
223        let k_low = promoting.rate_constant(800.0, 0.0);
224        let k_high = promoting.rate_constant(800.0, 1.0);
225        assert!(k_high > k_low);
226    }
227
228    #[test]
229    fn coverage_dependent_rejects_invalid() {
230        assert!(CoverageDependentArrheniusRate::new(0.0, 1.0, 0.0).is_err());
231        assert!(CoverageDependentArrheniusRate::new(1.0, -1.0, 0.0).is_err());
232        assert!(CoverageDependentArrheniusRate::new(1.0, 1.0, f64::NAN).is_err());
233    }
234}