one-indexed-vec 0.2.0

A one-based (1-indexed) wrapper around Vec<T>: element at position N is accessed via vec[N].
Documentation
//! Chemical kinetics: reaction rates and temperature dependence.

use crate::Vec1;

/// Universal gas constant R in J/(mol*K).
pub const R_GAS: f64 = 8.314_462_618_153_24;

impl Vec1<f64> {
    /// First-order decay: `C(t) = C0 * exp(-k t)`.
    ///
    /// `self` holds time points `t`.
    ///
    /// ```rust
    /// use one_indexed_vec::{vec1, Vec1};
    ///
    /// let t: Vec1<f64> = vec1![0.0, 1.0, 2.0];
    /// let c = t.first_order_decay(1.0, 0.5);
    /// assert!((c[1] - 1.0).abs() < 1e-10);
    /// assert!((c[2] - (-0.5f64).exp()).abs() < 1e-10);
    /// ```
    pub fn first_order_decay(&self, c0: f64, k: f64) -> Vec1<f64> {
        let mut out = Vec1::with_capacity(self.len());
        for i in 1..=self.len() {
            out.push(c0 * libm::exp(-k * self[i]));
        }
        out
    }

    /// Second-order decay (equal initial concentrations):
    /// `1/C(t) = 1/C0 + k t`.
    ///
    /// ```rust
    /// use one_indexed_vec::{vec1, Vec1};
    ///
    /// let t: Vec1<f64> = vec1![0.0, 1.0, 2.0];
    /// let c = t.second_order_decay(1.0, 0.5);
    /// assert!((c[1] - 1.0).abs() < 1e-10);
    /// assert!((c[2] - 1.0 / 1.5).abs() < 1e-10);
    /// ```
    pub fn second_order_decay(&self, c0: f64, k: f64) -> Vec1<f64> {
        assert!(c0 > 0.0, "second_order_decay: c0 must be > 0");
        let mut out = Vec1::with_capacity(self.len());
        for i in 1..=self.len() {
            let inv = 1.0 / c0 + k * self[i];
            out.push(1.0 / inv);
        }
        out
    }

    /// Arrhenius rate constants: `k(T) = A * exp(-Ea / (R T))`.
    ///
    /// `self` holds temperatures in Kelvin.
    ///
    /// ```rust
    /// use one_indexed_vec::{vec1, Vec1};
    ///
    /// let t: Vec1<f64> = vec1![300.0, 400.0, 500.0];
    /// let k = t.arrhenius(1e13, 50000.0);
    /// assert!(k[1] > 0.0);
    /// assert!(k[2] > k[1]);
    /// ```
    pub fn arrhenius(&self, pre_exponential: f64, activation_energy: f64) -> Vec1<f64> {
        assert!(pre_exponential > 0.0, "arrhenius: pre_exponential must be > 0");
        let mut out = Vec1::with_capacity(self.len());
        for i in 1..=self.len() {
            let t = self[i];
            assert!(t > 0.0, "arrhenius: temperature must be > 0");
            out.push(pre_exponential * libm::exp(-activation_energy / (R_GAS * t)));
        }
        out
    }
}

/// Arrhenius rate constant for a single temperature.
///
/// `k(T) = A * exp(-Ea / (R T))`.
///
/// ```rust
/// use one_indexed_vec::chemistry::kinetics::arrhenius_k;
///
/// let k = arrhenius_k(300.0, 1e13, 50000.0);
/// assert!(k > 0.0);
/// ```
pub fn arrhenius_k(temperature: f64, pre_exponential: f64, activation_energy: f64) -> f64 {
    assert!(temperature > 0.0, "arrhenius_k: T must be > 0");
    assert!(pre_exponential > 0.0, "arrhenius_k: pre_exponential must be > 0");
    pre_exponential * libm::exp(-activation_energy / (R_GAS * temperature))
}

/// Half-life of a first-order reaction: `t_half = ln(2) / k`.
///
/// ```rust
/// use one_indexed_vec::chemistry::kinetics::half_life;
///
/// let t = half_life(0.693_147);
/// assert!((t - 1.0).abs() < 1e-4);
/// ```
pub fn half_life(k: f64) -> f64 {
    assert!(k > 0.0, "half_life: k must be > 0");
    core::f64::consts::LN_2 / k
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::vec1;
    #[test]
    fn first_order_decay_basic() {
        let t = vec1![0.0f64, 1.0, 2.0];
        let c = t.first_order_decay(1.0, 0.5);
        assert!((c[1] - 1.0).abs() < 1e-10);
        assert!((c[2] - (-0.5f64).exp()).abs() < 1e-10);
    }

    #[test]
    fn second_order_decay_basic() {
        let t = vec1![0.0f64, 1.0, 2.0];
        let c = t.second_order_decay(1.0, 0.5);
        assert!((c[1] - 1.0).abs() < 1e-10);
        assert!((c[2] - 1.0 / 1.5).abs() < 1e-10);
    }

    #[test]
    fn arrhenius_increases_with_t() {
        let t = vec1![300.0f64, 400.0, 500.0];
        let k = t.arrhenius(1e13, 50000.0);
        assert!(k[2] > k[1]);
        assert!(k[3] > k[2]);
    }

    #[test]
    fn arrhenius_k_basic() {
        let k = arrhenius_k(300.0, 1e13, 50000.0);
        assert!(k > 0.0);
    }

    #[test]
    fn half_life_basic() {
        //let t = half_life(0.693_147);
        let t = half_life(core::f64::consts::LN_2);
        assert!((t - 1.0).abs() < 1e-4);
    }
}