#![forbid(unsafe_code)]
mod error;
pub use error::KineticsError;
pub const R_GAS: f64 = 8.314_462_618;
#[derive(Debug, Clone, Copy)]
pub struct ArrheniusRate {
pub a: f64,
pub ea: f64,
}
impl ArrheniusRate {
pub fn new(a: f64, ea: f64) -> Result<Self, KineticsError> {
if a <= 0.0 {
return Err(KineticsError::InvalidRate(format!(
"pre-exponential A must be > 0, got {a}"
)));
}
if ea < 0.0 {
return Err(KineticsError::InvalidRate(format!(
"activation energy Ea must be >= 0, got {ea}"
)));
}
Ok(Self { a, ea })
}
#[must_use]
pub fn rate_constant(&self, t: f64) -> f64 {
if t <= 0.0 {
return 0.0;
}
self.a * (-self.ea / (R_GAS * t)).exp()
}
}
pub fn langmuir_hinshelwood_coverages(
ks: &[f64],
pressures: &[f64],
) -> Result<Vec<f64>, KineticsError> {
if ks.len() != pressures.len() {
return Err(KineticsError::CoverageError(format!(
"K/pressure length mismatch ({} vs {})",
ks.len(),
pressures.len()
)));
}
let mut denom = 1.0;
for (&k, &p) in ks.iter().zip(pressures.iter()) {
if !k.is_finite() || k < 0.0 {
return Err(KineticsError::CoverageError(format!(
"non-finite/negative adsorption constant {k}"
)));
}
if !p.is_finite() || p < 0.0 {
return Err(KineticsError::CoverageError(format!(
"non-finite/negative pressure {p}"
)));
}
denom += k * p;
}
if denom <= 0.0 {
return Err(KineticsError::CoverageError(
"non-positive site denominator".into(),
));
}
Ok(ks
.iter()
.zip(pressures.iter())
.map(|(&k, &p)| k * p / denom)
.collect())
}
pub fn multi_site_langmuir_hinshelwood_coverages(
ks: &[f64],
pressures: &[f64],
site_of: &[usize],
) -> Result<Vec<f64>, KineticsError> {
if ks.len() != pressures.len() || ks.len() != site_of.len() {
return Err(KineticsError::CoverageError(format!(
"K/pressure/site-type length mismatch ({} vs {} vs {})",
ks.len(),
pressures.len(),
site_of.len()
)));
}
for (&k, &p) in ks.iter().zip(pressures.iter()) {
if !k.is_finite() || k < 0.0 {
return Err(KineticsError::CoverageError(format!(
"non-finite/negative adsorption constant {k}"
)));
}
if !p.is_finite() || p < 0.0 {
return Err(KineticsError::CoverageError(format!(
"non-finite/negative pressure {p}"
)));
}
}
let n_sites = site_of.iter().copied().max().map_or(0, |m| m + 1);
let mut denoms = vec![1.0_f64; n_sites];
for ((&k, &p), &site) in ks.iter().zip(pressures.iter()).zip(site_of.iter()) {
denoms[site] += k * p;
}
for (site, &denom) in denoms.iter().enumerate() {
if denom <= 0.0 {
return Err(KineticsError::CoverageError(format!(
"non-positive site denominator for site type {site}"
)));
}
}
Ok(ks
.iter()
.zip(pressures.iter())
.zip(site_of.iter())
.map(|((&k, &p), &site)| k * p / denoms[site])
.collect())
}
#[derive(Debug, Clone, Copy)]
pub struct EleyRideal {
pub k: f64,
}
impl EleyRideal {
pub fn new(k: f64) -> Result<Self, KineticsError> {
if !k.is_finite() || k < 0.0 {
return Err(KineticsError::InvalidRate(format!(
"Eley-Rideal rate constant must be finite and >= 0, got {k}"
)));
}
Ok(Self { k })
}
#[must_use]
pub fn rate(&self, theta_adsorbed: f64, gas_phase_concentration: f64) -> f64 {
if theta_adsorbed <= 0.0 || gas_phase_concentration <= 0.0 {
return 0.0;
}
self.k * theta_adsorbed * gas_phase_concentration
}
#[must_use]
pub fn into_rate_law(
self,
theta_index: usize,
gas_index: usize,
) -> tpt_sci_reaction_network::RateLaw {
tpt_sci_reaction_network::RateLaw::custom(move |y: &[f64], _p: &[f64]| {
let theta = y.get(theta_index).copied().unwrap_or(0.0);
let gas = y.get(gas_index).copied().unwrap_or(0.0);
self.rate(theta, gas)
})
}
}
#[derive(Debug, Clone, Copy)]
pub struct CoverageDependentArrheniusRate {
pub a: f64,
pub ea0: f64,
pub alpha: f64,
}
impl CoverageDependentArrheniusRate {
pub fn new(a: f64, ea0: f64, alpha: f64) -> Result<Self, KineticsError> {
if a <= 0.0 {
return Err(KineticsError::InvalidRate(format!(
"pre-exponential A must be > 0, got {a}"
)));
}
if ea0 < 0.0 {
return Err(KineticsError::InvalidRate(format!(
"zero-coverage activation energy Ea0 must be >= 0, got {ea0}"
)));
}
if !alpha.is_finite() {
return Err(KineticsError::InvalidRate(format!(
"coverage coefficient alpha must be finite, got {alpha}"
)));
}
Ok(Self { a, ea0, alpha })
}
#[must_use]
pub fn activation_energy(&self, theta: f64) -> f64 {
self.ea0 + self.alpha * theta
}
#[must_use]
pub fn rate_constant(&self, t: f64, theta: f64) -> f64 {
if t <= 0.0 {
return 0.0;
}
let ea = self.activation_energy(theta).max(0.0);
self.a * (-ea / (R_GAS * t)).exp()
}
}
#[derive(Debug, Clone)]
pub struct KineticsProblem {
pub rates: Vec<ArrheniusRate>,
}
impl KineticsProblem {
pub fn new(rates: Vec<ArrheniusRate>) -> Result<Self, KineticsError> {
if rates.is_empty() {
return Err(KineticsError::InvalidRate("no rates supplied".into()));
}
Ok(Self { rates })
}
#[must_use]
pub fn rate_constants(&self, t: f64) -> Vec<f64> {
self.rates.iter().map(|r| r.rate_constant(t)).collect()
}
}
#[cfg(test)]
mod tests {
use super::*;
use approx::assert_abs_diff_eq;
#[test]
fn arrhenius_rises_with_temperature() {
let r = ArrheniusRate::new(1.0e13, 80_000.0).unwrap();
let k_low = r.rate_constant(600.0);
let k_high = r.rate_constant(900.0);
assert!(k_high > k_low);
assert!(k_low.is_finite() && k_high.is_finite());
}
#[test]
fn arrhenius_rejects_invalid() {
assert!(ArrheniusRate::new(0.0, 1.0).is_err());
assert!(ArrheniusRate::new(1.0, -1.0).is_err());
}
#[test]
fn langmuir_hinshelwood_sums_to_one() {
let theta = langmuir_hinshelwood_coverages(&[2.0, 3.0], &[1.0, 1.0]).unwrap();
let sum: f64 = theta.iter().sum();
assert!(sum <= 1.0 + 1e-12);
assert_abs_diff_eq!(sum, 5.0 / 6.0, epsilon = 1e-12);
assert!(theta[1] > theta[0]);
}
#[test]
fn langmuir_hinshelwood_empty_sites() {
let theta = langmuir_hinshelwood_coverages(&[5.0], &[0.0]).unwrap();
assert_abs_diff_eq!(theta[0], 0.0, epsilon = 1e-12);
}
#[test]
fn kinetics_problem_resolves_constants() {
let prob = KineticsProblem::new(vec![
ArrheniusRate::new(1.0e13, 80_000.0).unwrap(),
ArrheniusRate::new(1.0e10, 40_000.0).unwrap(),
])
.unwrap();
let ks = prob.rate_constants(800.0);
assert_eq!(ks.len(), 2);
assert!(ks[0] > 0.0 && ks[1] > 0.0);
assert!(KineticsProblem::new(vec![]).is_err());
}
#[test]
fn multi_site_reduces_to_single_site() {
let ks = [2.0, 3.0];
let ps = [1.0, 1.0];
let single = langmuir_hinshelwood_coverages(&ks, &ps).unwrap();
let multi = multi_site_langmuir_hinshelwood_coverages(&ks, &ps, &[0, 0]).unwrap();
for (s, m) in single.iter().zip(multi.iter()) {
assert_abs_diff_eq!(s, m, epsilon = 1e-12);
}
}
#[test]
fn multi_site_normalizes_independently_per_site_type() {
let theta = multi_site_langmuir_hinshelwood_coverages(
&[2.0, 3.0, 5.0],
&[1.0, 1.0, 1.0],
&[0, 0, 1],
)
.unwrap();
assert_abs_diff_eq!(theta[0], 2.0 / 6.0, epsilon = 1e-12);
assert_abs_diff_eq!(theta[1], 3.0 / 6.0, epsilon = 1e-12);
assert_abs_diff_eq!(theta[2], 5.0 / 6.0, epsilon = 1e-12);
let site0_sum = theta[0] + theta[1];
assert!(site0_sum <= 1.0 + 1e-12);
assert!(theta[2] <= 1.0 + 1e-12);
}
#[test]
fn multi_site_rejects_mismatched_lengths_and_bad_values() {
assert!(multi_site_langmuir_hinshelwood_coverages(&[1.0], &[1.0, 2.0], &[0, 0]).is_err());
assert!(multi_site_langmuir_hinshelwood_coverages(&[-1.0], &[1.0], &[0]).is_err());
assert!(multi_site_langmuir_hinshelwood_coverages(&[1.0], &[-1.0], &[0]).is_err());
}
#[test]
fn eley_rideal_zero_when_either_factor_zero() {
let er = EleyRideal::new(3.0).unwrap();
assert_eq!(er.rate(0.0, 5.0), 0.0);
assert_eq!(er.rate(0.5, 0.0), 0.0);
assert_eq!(er.rate(0.0, 0.0), 0.0);
}
#[test]
fn eley_rideal_linear_in_gas_phase_concentration() {
let er = EleyRideal::new(2.0).unwrap();
let r1 = er.rate(0.4, 1.0);
let r2 = er.rate(0.4, 3.0);
assert_abs_diff_eq!(r2, 3.0 * r1, epsilon = 1e-12);
assert_abs_diff_eq!(r1, 2.0 * 0.4 * 1.0, epsilon = 1e-12);
}
#[test]
fn eley_rideal_rejects_invalid_rate() {
assert!(EleyRideal::new(-1.0).is_err());
assert!(EleyRideal::new(f64::NAN).is_err());
}
#[test]
fn eley_rideal_into_rate_law_matches_direct_rate() {
use tpt_sci_reaction_network::ReactionNetwork;
let er = EleyRideal::new(1.5).unwrap();
let mut net = ReactionNetwork::new();
let theta_a = net.species("theta_A");
let gas_b = net.species("B_gas");
let c = net.species("C");
net.reaction(
&[(theta_a, 1.0), (gas_b, 1.0)],
&[(c, 1.0)],
er.into_rate_law(0, 1),
);
let sys = net.build().unwrap();
let y = [0.3, 2.0, 0.0];
let rates = sys.reaction_rates(&y);
assert_abs_diff_eq!(rates[0], er.rate(0.3, 2.0), epsilon = 1e-12);
}
#[test]
fn coverage_dependent_matches_plain_arrhenius_when_alpha_zero() {
let plain = ArrheniusRate::new(1.0e13, 80_000.0).unwrap();
let cov = CoverageDependentArrheniusRate::new(1.0e13, 80_000.0, 0.0).unwrap();
for theta in [0.0, 0.3, 1.0] {
assert_abs_diff_eq!(
cov.rate_constant(800.0, theta),
plain.rate_constant(800.0),
epsilon = 1e-6
);
}
}
#[test]
fn coverage_dependent_rate_constant_monotonic_in_theta() {
let repulsive = CoverageDependentArrheniusRate::new(1.0e13, 80_000.0, 20_000.0).unwrap();
let k_low = repulsive.rate_constant(800.0, 0.0);
let k_high = repulsive.rate_constant(800.0, 1.0);
assert!(k_high < k_low);
let promoting = CoverageDependentArrheniusRate::new(1.0e13, 80_000.0, -20_000.0).unwrap();
let k_low = promoting.rate_constant(800.0, 0.0);
let k_high = promoting.rate_constant(800.0, 1.0);
assert!(k_high > k_low);
}
#[test]
fn coverage_dependent_rejects_invalid() {
assert!(CoverageDependentArrheniusRate::new(0.0, 1.0, 0.0).is_err());
assert!(CoverageDependentArrheniusRate::new(1.0, -1.0, 0.0).is_err());
assert!(CoverageDependentArrheniusRate::new(1.0, 1.0, f64::NAN).is_err());
}
}