1use std::f64::consts::PI;
10
11pub 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; let mut l_curr = 1.0 + k_f - x; 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
37pub 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 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 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 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
78pub 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 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 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
114pub 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 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
143pub 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 assert_eq!(associated_laguerre(0, 1, 5.0), 1.0);
192 assert_eq!(associated_laguerre(1, 1, 2.0), 0.0);
194 assert_eq!(associated_laguerre(1, 1, 0.0), 2.0);
195
196 assert_eq!(associated_legendre(0, 0, 0.5), 1.0);
198 assert!((associated_legendre(1, 0, 0.5) - 0.5).abs() < 1e-9);
200 assert!((associated_legendre(2, 0, 1.0) - 1.0).abs() < 1e-9);
202 }
203
204 #[test]
205 fn test_hydrogen_1s_orbital() {
206 let (psi_0, prob_0, sign_0) = evaluate_hydrogenic_orbital_3d(1, 0, 0, 1.0, [0.0, 0.0, 0.0]);
208 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 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 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 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 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 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 assert!((psi_pos + psi_neg).abs() < 1e-12);
255 }
256
257 #[test]
258 fn test_hydrogen_3dz2_nodal_cones() {
259 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 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 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}