Skip to main content

vibe/physics/
quantum_3d.rs

1//! 3D Hydrogenic Quantum Orbitals and Real Spherical Harmonics.
2//!
3//! Provides zero-heap analytical evaluators for Hydrogenic wavefunctions $\psi_{nlm}(r, \theta, \phi)$,
4//! generalized Laguerre polynomials $L_{n-l-1}^{2l+1}(\rho)$, associated Legendre polynomials
5//! $P_l^m(\cos\theta)$, and real spherical harmonics $Y_l^m(\theta, \phi)$.
6//!
7//! Reference: `AGENTS.md` Workstream W5 (ยง5.5).
8
9use std::f64::consts::PI;
10
11/// Evaluates generalized Laguerre polynomial $L_p^k(x)$ using an iterative three-term recurrence.
12///
13/// $$(i + 1) L_{i+1}^k(x) = (2i + 1 + k - x) L_i^k(x) - (i + k) L_{i-1}^k(x)$$
14///
15/// Completely zero-heap and non-recursive.
16pub fn associated_laguerre(p: u32, k: u32, x: f64) -> f64 {
17    if p == 0 {
18        return 1.0;
19    }
20    let k_f = k as f64;
21    let mut l_prev = 1.0; // L_0^k
22    let mut l_curr = 1.0 + k_f - x; // L_1^k
23    if p == 1 {
24        return l_curr;
25    }
26
27    for i in 1..p {
28        let i_f = i as f64;
29        let l_next = ((2.0 * i_f + 1.0 + k_f - x) * l_curr - (i_f + k_f) * l_prev) / (i_f + 1.0);
30        l_prev = l_curr;
31        l_curr = l_next;
32    }
33
34    l_curr
35}
36
37/// Evaluates associated Legendre polynomial $P_l^m(\cos\theta)$ for $0 \le m \le l$.
38///
39/// Includes the standard Condon-Shortley phase $(-1)^m$. Non-recursive and zero-heap.
40pub fn associated_legendre(l: u32, m_abs: u32, cos_theta: f64) -> f64 {
41    if m_abs > l {
42        return 0.0;
43    }
44
45    let x = cos_theta.clamp(-1.0, 1.0);
46    let sin_theta = (1.0 - x * x).max(0.0).sqrt();
47
48    // Compute P_m^m(x) = (-1)^m * (2m - 1)!! * (1 - x^2)^(m / 2)
49    let mut pmm = 1.0;
50    let mut fact = 1.0;
51    for _ in 1..=m_abs {
52        pmm *= -fact * sin_theta;
53        fact += 2.0;
54    }
55
56    if l == m_abs {
57        return pmm;
58    }
59
60    // Compute P_{m+1}^m(x) = x * (2m + 1) * P_m^m(x)
61    let mut pmmp1 = x * (2.0 * (m_abs as f64) + 1.0) * pmm;
62    if l == m_abs + 1 {
63        return pmmp1;
64    }
65
66    // Upward recurrence for l >= m + 2
67    for ll in (m_abs + 2)..=l {
68        let ll_f = ll as f64;
69        let m_f = m_abs as f64;
70        let pll = (x * (2.0 * ll_f - 1.0) * pmmp1 - (ll_f + m_f - 1.0) * pmm) / (ll_f - m_f);
71        pmm = pmmp1;
72        pmmp1 = pll;
73    }
74
75    pmmp1
76}
77
78/// Evaluates real spherical harmonic $Y_l^m(\theta, \phi)$ for $l \ge 0, -l \le m \le l$.
79///
80/// Normalized such that $\int_{0}^{2\pi}\int_{0}^{\pi} |Y_l^m|^2 \sin\theta \, d\theta d\phi = 1.0$.
81pub fn real_spherical_harmonic(l: u32, m: i32, theta: f64, phi: f64) -> f64 {
82    let m_abs = m.unsigned_abs();
83    if m_abs > l {
84        return 0.0;
85    }
86
87    let cos_theta = theta.cos();
88    let plm = associated_legendre(l, m_abs, cos_theta);
89
90    // Compute ratio (l - m)! / (l + m)! without factorial overflow
91    let mut ratio = 1.0;
92    for k in (l - m_abs + 1)..=(l + m_abs) {
93        ratio /= k as f64;
94    }
95
96    let norm = (((2.0 * (l as f64) + 1.0) / (4.0 * PI)) * ratio).sqrt();
97
98    if m == 0 {
99        norm * plm
100    } else {
101        let sqrt2 = std::f64::consts::SQRT_2;
102        // (-1)^m_abs cancels Condon-Shortley phase for positive lobes along coordinate axes
103        let phase = if m_abs % 2 == 1 { -1.0 } else { 1.0 };
104        let base = sqrt2 * norm * phase * plm;
105
106        if m > 0 {
107            base * (m as f64 * phi).cos()
108        } else {
109            base * (m_abs as f64 * phi).sin()
110        }
111    }
112}
113
114/// Evaluates radial hydrogenic wavefunction $R_{nl}(r)$ in atomic units ($a_0 = 1$).
115///
116/// $$R_{nl}(r) = \sqrt{ \left(\frac{2Z}{n}\right)^3 \frac{(n - l - 1)!}{2n (n + l)!} } \cdot e^{-\rho / 2} \cdot \rho^l \cdot L_{n-l-1}^{2l+1}(\rho)$$
117/// where $\rho = \frac{2 Z r}{n}$.
118pub fn hydrogenic_radial_wavefunction(n: u32, l: u32, z_atomic: f64, r_bohr: f64) -> f64 {
119    if n == 0 || l >= n || z_atomic <= 0.0 || r_bohr < 0.0 {
120        return 0.0;
121    }
122
123    let n_f = n as f64;
124    let rho = (2.0 * z_atomic * r_bohr) / n_f;
125
126    let p = n - l - 1;
127    let k = 2 * l + 1;
128    let lag = associated_laguerre(p, k, rho);
129
130    // Evaluate (n - l - 1)! / (n + l)!
131    let mut denom = 2.0 * n_f;
132    for k_val in (n - l)..=(n + l) {
133        denom *= k_val as f64;
134    }
135
136    let prefactor = (((2.0 * z_atomic / n_f).powi(3)) / denom).sqrt();
137    let rho_l = if l == 0 { 1.0 } else { rho.powi(l as i32) };
138    let exp_term = (-0.5 * rho).exp();
139
140    prefactor * exp_term * rho_l * lag
141}
142
143/// Evaluates exact 3D Hydrogenic quantum orbital amplitude, probability density, and phase sign.
144///
145/// Returns `(psi, probability_density_psi_sq, phase_sign)`.
146/// - `psi`: Amplitude $\psi_{nlm}(r, \theta, \phi) = R_{nl}(r) \cdot Y_l^m(\theta, \phi)$.
147/// - `probability_density_psi_sq`: Probability density $|\psi|^2$.
148/// - `phase_sign`: `+1` (positive lobe), `-1` (negative lobe), or `0` (nodal surface).
149pub fn evaluate_hydrogenic_orbital_3d(
150    n: u32,
151    l: u32,
152    m: i32,
153    z_atomic: f64,
154    xyz_bohr: [f64; 3],
155) -> (f64, f64, i8) {
156    let x = xyz_bohr[0];
157    let y = xyz_bohr[1];
158    let z = xyz_bohr[2];
159
160    let r = (x * x + y * y + z * z).sqrt();
161    let (theta, phi) = if r < 1e-15 {
162        (0.0, 0.0)
163    } else {
164        let cos_theta = (z / r).clamp(-1.0, 1.0);
165        (cos_theta.acos(), y.atan2(x))
166    };
167
168    let r_nl = hydrogenic_radial_wavefunction(n, l, z_atomic, r);
169    let y_lm = real_spherical_harmonic(l, m, theta, phi);
170    let psi = r_nl * y_lm;
171    let prob_sq = psi * psi;
172
173    let phase_sign = if psi > 1e-12 {
174        1i8
175    } else if psi < -1e-12 {
176        -1i8
177    } else {
178        0i8
179    };
180
181    (psi, prob_sq, phase_sign)
182}
183
184#[cfg(test)]
185mod tests {
186    use super::*;
187
188    #[test]
189    fn test_laguerre_and_legendre_polynomials() {
190        // L_0^k(x) = 1
191        assert_eq!(associated_laguerre(0, 1, 5.0), 1.0);
192        // L_1^1(x) = 1 + 1 - x = 2 - x
193        assert_eq!(associated_laguerre(1, 1, 2.0), 0.0);
194        assert_eq!(associated_laguerre(1, 1, 0.0), 2.0);
195
196        // P_0^0(x) = 1
197        assert_eq!(associated_legendre(0, 0, 0.5), 1.0);
198        // P_1^0(x) = x
199        assert!((associated_legendre(1, 0, 0.5) - 0.5).abs() < 1e-9);
200        // P_2^0(x) = 0.5 * (3x^2 - 1) -> at x = 1, P_2^0 = 1
201        assert!((associated_legendre(2, 0, 1.0) - 1.0).abs() < 1e-9);
202    }
203
204    #[test]
205    fn test_hydrogen_1s_orbital() {
206        // 1s state: n=1, l=0, m=0, Z=1
207        let (psi_0, prob_0, sign_0) = evaluate_hydrogenic_orbital_3d(1, 0, 0, 1.0, [0.0, 0.0, 0.0]);
208        // Theoretical psi(0) = 1 / sqrt(pi) ~ 0.56418958
209        let expected_psi0 = 1.0 / (PI.sqrt());
210        assert!((psi_0 - expected_psi0).abs() < 1e-6);
211        assert!((prob_0 - expected_psi0 * expected_psi0).abs() < 1e-6);
212        assert_eq!(sign_0, 1);
213
214        // 1s has no angular nodes: always positive everywhere
215        let (psi_r, _, sign_r) = evaluate_hydrogenic_orbital_3d(1, 0, 0, 1.0, [1.5, 0.0, 0.0]);
216        assert!(psi_r > 0.0);
217        assert_eq!(sign_r, 1);
218
219        // Radial normalization: integral_0^inf R_{10}(r)^2 r^2 dr == 1.0
220        let mut sum_norm = 0.0;
221        let dr = 0.005;
222        let mut r = 0.5 * dr;
223        while r < 20.0 {
224            let rnl = hydrogenic_radial_wavefunction(1, 0, 1.0, r);
225            sum_norm += rnl * rnl * r * r * dr;
226            r += dr;
227        }
228        assert!((sum_norm - 1.0).abs() < 1e-3);
229    }
230
231    #[test]
232    fn test_hydrogen_2pz_nodal_plane() {
233        // 2p_z state: n=2, l=1, m=0, Z=1
234        // Nodal plane at z = 0
235        let (psi_node, prob_node, sign_node) =
236            evaluate_hydrogenic_orbital_3d(2, 1, 0, 1.0, [1.5, 2.0, 0.0]);
237        assert!(psi_node.abs() < 1e-12);
238        assert!(prob_node < 1e-20);
239        assert_eq!(sign_node, 0);
240
241        // Upper lobe: z > 0 => positive phase
242        let (psi_pos, _, sign_pos) =
243            evaluate_hydrogenic_orbital_3d(2, 1, 0, 1.0, [0.0, 0.0, 2.0]);
244        assert!(psi_pos > 0.0);
245        assert_eq!(sign_pos, 1);
246
247        // Lower lobe: z < 0 => negative phase
248        let (psi_neg, _, sign_neg) =
249            evaluate_hydrogenic_orbital_3d(2, 1, 0, 1.0, [0.0, 0.0, -2.0]);
250        assert!(psi_neg < 0.0);
251        assert_eq!(sign_neg, -1);
252
253        // Anti-symmetry along z-axis
254        assert!((psi_pos + psi_neg).abs() < 1e-12);
255    }
256
257    #[test]
258    fn test_hydrogen_3dz2_nodal_cones() {
259        // 3d_z2 state: n=3, l=2, m=0, Z=1
260        // Nodal surfaces where 3*cos^2(theta) - 1 = 0 => cos(theta) = 1 / sqrt(3)
261        let r = 4.0;
262        let cos_node = 1.0 / (3.0f64.sqrt());
263        let sin_node = (2.0f64 / 3.0).sqrt();
264        let z_node = r * cos_node;
265        let x_node = r * sin_node;
266
267        let (psi_cone, prob_cone, sign_cone) =
268            evaluate_hydrogenic_orbital_3d(3, 2, 0, 1.0, [x_node, 0.0, z_node]);
269        assert!(psi_cone.abs() < 1e-10, "psi on nodal cone: {}", psi_cone);
270        assert!(prob_cone < 1e-18);
271        assert_eq!(sign_cone, 0);
272
273        // Along z-axis: cos^2(theta) = 1 => 3(1) - 1 = 2 > 0 (positive lobe)
274        let (psi_z, _, sign_z) = evaluate_hydrogenic_orbital_3d(3, 2, 0, 1.0, [0.0, 0.0, r]);
275        assert!(psi_z > 0.0);
276        assert_eq!(sign_z, 1);
277
278        // In xy-plane: cos^2(theta) = 0 => 3(0) - 1 = -1 < 0 (negative equatorial donut)
279        let (psi_xy, _, sign_xy) = evaluate_hydrogenic_orbital_3d(3, 2, 0, 1.0, [r, 0.0, 0.0]);
280        assert!(psi_xy < 0.0);
281        assert_eq!(sign_xy, -1);
282    }
283}