use crate::device::WgpuDevice;
use crate::device::compute_pipeline::ComputeDispatch;
use crate::error::Result;
use std::sync::Arc;
pub struct SphericalHarmonicsF64 {
device: Arc<WgpuDevice>,
}
#[expect(
dead_code,
reason = "public API — exercised by tests, available to downstream consumers"
)]
impl SphericalHarmonicsF64 {
pub fn new(device: Arc<WgpuDevice>) -> Result<Self> {
Ok(Self { device })
}
fn wgsl_shader() -> &'static str {
include_str!("../shaders/special/spherical_harmonics_f64.wgsl")
}
pub fn ylm(&self, theta_phi: &[f64], l: u32, m: i32) -> Result<Vec<f64>> {
if theta_phi.is_empty() || !theta_phi.len().is_multiple_of(2) {
return Ok(vec![]);
}
let size = theta_phi.len() / 2;
let abs_m = m.unsigned_abs();
if abs_m > l {
return Ok(vec![0.0; size]);
}
self.ylm_gpu(theta_phi, l, m)
}
fn ylm_cpu(&self, theta_phi: &[f64], l: u32, m: i32) -> Vec<f64> {
let size = theta_phi.len() / 2;
let _ = m.unsigned_abs(); let mut result = Vec::with_capacity(size);
for i in 0..size {
let theta = theta_phi[i * 2];
let phi = theta_phi[i * 2 + 1];
result.push(Self::ylm_scalar(l, m, theta, phi));
}
result
}
fn factorial(n: u32) -> f64 {
match n {
0 | 1 => 1.0,
_ => (2..=n).map(|i| i as f64).product(),
}
}
fn double_factorial(m: u32) -> f64 {
if m == 0 {
return 1.0;
}
(1..=m).map(|k| (2 * k - 1) as f64).product()
}
fn assoc_legendre(l: u32, m: u32, x: f64) -> f64 {
if m > l {
return 0.0;
}
let t = x.mul_add(-x, 1.0);
if t <= 0.0 {
if m == 0 {
return if x > 0.0 || l.is_multiple_of(2) {
1.0
} else {
-1.0
};
}
return 0.0;
}
let mut pm = Self::double_factorial(m) * t.sqrt().powf(m as f64);
if m % 2 == 1 {
pm = -pm;
}
if l == m {
return pm;
}
let pmp1 = (2 * m + 1) as f64 * x * pm;
if l == m + 1 {
return pmp1;
}
let (mut pl_m2, mut pl_m1) = (pm, pmp1);
for ll in (m + 2)..=l {
let pl = ((2 * ll - 1) as f64 * x).mul_add(pl_m1, -((ll + m - 1) as f64 * pl_m2))
/ (ll - m) as f64;
pl_m2 = pl_m1;
pl_m1 = pl;
}
pl_m1
}
fn ylm_scalar(l: u32, m: i32, theta: f64, phi: f64) -> f64 {
let abs_m = m.unsigned_abs();
if abs_m > l {
return 0.0;
}
let x = theta.cos();
let plm = Self::assoc_legendre(l, abs_m, x);
let angular = if abs_m == 0 {
1.0
} else if m > 0 {
(abs_m as f64 * phi).cos()
} else {
(abs_m as f64 * phi).sin()
};
let num = Self::factorial(l - abs_m);
let den = Self::factorial(l + abs_m);
let pre = ((2 * l + 1) as f64) / (4.0 * std::f64::consts::PI);
let n_lm = (pre * num / den).sqrt();
let mut y_lm = n_lm * plm * angular;
if abs_m != 0 {
y_lm *= 2.0_f64.sqrt();
}
y_lm
}
fn ylm_gpu(&self, theta_phi: &[f64], l: u32, m: i32) -> Result<Vec<f64>> {
let size = theta_phi.len() / 2;
let abs_m = m.unsigned_abs();
let m_is_positive = u32::from(m >= 0);
let input_buf = self
.device
.device
.create_buffer_init(&wgpu::util::BufferInitDescriptor {
label: Some("SH f64 Input"),
contents: bytemuck::cast_slice(theta_phi),
usage: wgpu::BufferUsages::STORAGE,
});
let output_buf = self.device.device.create_buffer(&wgpu::BufferDescriptor {
label: Some("SH f64 Output"),
size: (size * std::mem::size_of::<f64>()) as u64,
usage: wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_SRC,
mapped_at_creation: false,
});
#[repr(C)]
#[derive(Copy, Clone, bytemuck::Pod, bytemuck::Zeroable)]
struct Params {
size: u32,
l: u32,
abs_m: u32,
m_is_positive: u32,
}
let params = Params {
size: size as u32,
l,
abs_m,
m_is_positive,
};
let params_buf = self
.device
.device
.create_buffer_init(&wgpu::util::BufferInitDescriptor {
label: Some("SH f64 Params"),
contents: bytemuck::bytes_of(¶ms),
usage: wgpu::BufferUsages::UNIFORM,
});
ComputeDispatch::new(self.device.as_ref(), "SH f64")
.shader(Self::wgsl_shader(), "main")
.f64()
.storage_read(0, &input_buf)
.storage_rw(1, &output_buf)
.uniform(2, ¶ms_buf)
.dispatch_1d(size as u32)
.submit()?;
let result: Vec<f64> = self.device.read_buffer_f64(&output_buf, size)?;
Ok(result)
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::f64::consts::PI;
fn create_test_device() -> Option<Arc<crate::device::WgpuDevice>> {
crate::device::test_pool::get_test_device_if_f64_gpu_available_sync()
}
#[test]
fn test_y00() -> Result<()> {
let Some(device) = create_test_device() else {
return Ok(());
};
let sh = SphericalHarmonicsF64::new(device)?;
let theta_phi = vec![0.0, 0.0, PI / 2.0, 0.0, PI, PI];
let result = sh.ylm(&theta_phi, 0, 0)?;
let expected = 1.0 / (4.0 * PI).sqrt();
for val in result {
assert!(
(val - expected).abs() < 1e-10,
"Y₀⁰ = {val}, expected {expected}"
);
}
Ok(())
}
#[test]
fn test_y10() -> Result<()> {
let Some(device) = create_test_device() else {
return Ok(());
};
let sh = SphericalHarmonicsF64::new(device)?;
let theta_phi = vec![0.0, 0.0, PI / 2.0, 0.0, PI, 0.0];
let result = sh.ylm(&theta_phi, 1, 0)?;
let norm = (3.0 / (4.0 * PI)).sqrt();
assert!(
(result[0] - norm * 1.0).abs() < 1e-8,
"Y10(0) = {}",
result[0]
); assert!((result[1]).abs() < 1e-8, "Y10(π/2) = {}", result[1]); assert!(
(result[2] + norm).abs() < 1e-8,
"Y10(π) = {}, expected {}",
result[2],
-norm
); Ok(())
}
#[test]
fn test_orthonormality_y00_y10() -> Result<()> {
let Some(device) = create_test_device() else {
return Ok(());
};
let sh = SphericalHarmonicsF64::new(device)?;
let theta_phi = vec![PI / 4.0, 0.0, PI / 2.0, PI / 4.0, 3.0 * PI / 4.0, PI / 2.0];
let y00 = sh.ylm(&theta_phi, 0, 0)?;
let y10 = sh.ylm(&theta_phi, 1, 0)?;
for i in 0..3 {
assert!(y00[i].is_finite(), "Y₀⁰ should be finite");
assert!(y10[i].is_finite(), "Y₁⁰ should be finite");
}
Ok(())
}
}