kimiya 1.1.1

Kimiya — chemistry engine for elements, molecules, reactions, kinetics, and thermochemistry
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

use crate::element::GAS_CONSTANT;
use crate::error::{KimiyaError, Result};

/// Gibbs free energy: ΔG = ΔH - TΔS
///
/// All values in SI: ΔH in J/mol, T in Kelvin, ΔS in J/(mol·K).
///
/// # Errors
///
/// Returns [`KimiyaError::InvalidTemperature`] if temperature is not positive.
#[inline]
pub fn gibbs_free_energy(enthalpy_j: f64, temperature_k: f64, entropy_j_per_k: f64) -> Result<f64> {
    if temperature_k <= 0.0 {
        return Err(KimiyaError::InvalidTemperature(
            "temperature must be positive".into(),
        ));
    }
    Ok(enthalpy_j - temperature_k * entropy_j_per_k)
}

/// Equilibrium constant from Gibbs free energy: K = exp(-ΔG / (R·T))
///
/// # Errors
///
/// Returns [`KimiyaError::InvalidTemperature`] if temperature is not positive.
#[inline]
pub fn equilibrium_constant(delta_g_j: f64, temperature_k: f64) -> Result<f64> {
    if temperature_k <= 0.0 {
        return Err(KimiyaError::InvalidTemperature(
            "temperature must be positive".into(),
        ));
    }
    Ok((-delta_g_j / (GAS_CONSTANT * temperature_k)).exp())
}

/// Check if a reaction is spontaneous (ΔG < 0).
#[must_use]
#[inline]
pub fn is_spontaneous(delta_g: f64) -> bool {
    delta_g < 0.0
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn gibbs_basic() {
        let dg = gibbs_free_energy(-100_000.0, 298.0, -200.0).unwrap();
        assert!(
            (dg - (-40400.0)).abs() < 1.0,
            "ΔG should be ~-40400, got {dg}"
        );
    }

    #[test]
    fn gibbs_zero_temp_is_error() {
        assert!(gibbs_free_energy(-100_000.0, 0.0, -200.0).is_err());
    }

    #[test]
    fn equilibrium_constant_negative_dg() {
        let k = equilibrium_constant(-5000.0, 298.0).unwrap();
        assert!(k > 1.0, "negative ΔG should give K > 1, got {k}");
    }

    #[test]
    fn equilibrium_constant_positive_dg() {
        let k = equilibrium_constant(5000.0, 298.0).unwrap();
        assert!(k < 1.0, "positive ΔG should give K < 1, got {k}");
    }

    #[test]
    fn equilibrium_constant_zero_dg() {
        let k = equilibrium_constant(0.0, 298.0).unwrap();
        assert!(
            (k - 1.0).abs() < 0.001,
            "zero ΔG should give K = 1, got {k}"
        );
    }

    #[test]
    fn equilibrium_constant_zero_temp_is_error() {
        assert!(equilibrium_constant(0.0, 0.0).is_err());
    }

    #[test]
    fn spontaneous_check() {
        assert!(is_spontaneous(-100.0));
        assert!(!is_spontaneous(100.0));
        assert!(!is_spontaneous(0.0));
    }
}