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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
// SPDX-License-Identifier: AGPL-3.0-or-later
//! Long-Range Electrostatics (PPPM/Ewald)
//!
//! **Purpose**: Accurate Coulomb interactions for periodic systems
//!
//! **Algorithm**: Particle-Particle Particle-Mesh (PPPM)
//!
//! PPPM splits Coulomb interactions into two parts:
//! 1. **Short-range (PP)**: Direct Coulomb with erfc damping
//! 2. **Long-range (PM)**: FFT-based mesh solve for k > 0
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────┐
//! │ PPPM Electrostatics │
//! ├─────────────────────────────────────────────────────────────────┤
//! │ │
//! │ 1. Charge Spreading (particles → mesh) │
//! │ └── B-spline interpolation to mesh nodes │
//! │ │
//! │ 2. Forward FFT (mesh → k-space) │
//! │ └── Uses existing Fft3D infrastructure │
//! │ │
//! │ 3. Green's Function (k-space multiplication) │
//! │ └── ρ̃(k) × G(k) where G(k) = 4π/k² × influence function │
//! │ │
//! │ 4. Backward FFT (k-space → mesh) │
//! │ └── Get mesh potential φ(r) │
//! │ │
//! │ 5. Force Interpolation (mesh → particles) │
//! │ └── B-spline gradient interpolation │
//! │ │
//! │ 6. Short-Range Correction │
//! │ └── erfc-damped direct Coulomb for nearby pairs │
//! │ │
//! └─────────────────────────────────────────────────────────────────┘
//! ```
//!
//! # Ewald Splitting
//!
//! The Coulomb potential 1/r is split using:
//! ```text
//! 1/r = erfc(αr)/r + erf(αr)/r
//! \_________/ \________/
//! short-range long-range
//! (real space) (k-space via FFT)
//! ```
//!
//! The splitting parameter α controls the crossover:
//! - Large α → more work in k-space (fewer mesh modes needed)
//! - Small α → more work in real space (larger cutoff needed)
//!
//! Optimal α balances real-space cutoff and mesh size.
//!
//! # PPPM Parameters
//!
//! | Parameter | Symbol | Typical Value | Notes |
//! |-----------|--------|---------------|-------|
//! | Splitting | α | `box_side/6` | Balances PP/PM work |
//! | Mesh size | Kx,Ky,Kz | 32-128 | Power of 2 for FFT |
//! | Interpolation order | p | 4-7 | Higher = more accurate |
//! | Real cutoff | rc | `box_side/4` | Works with cell-list |
//! | Accuracy | δ | 1e-5 | Force relative error |
//!
//! # Implementation Status
//!
//! | Component | Status | Notes |
//! |-----------|--------|-------|
//! | `Fft3D` (f32) | ✅ Done | |
//! | `Fft1D` (f64) | ✅ Done | For PPPM precision |
//! | B-spline functions | ✅ Done | Cardinal B-splines with derivatives |
//! | Charge spreading | ✅ Done | CPU implementation |
//! | Green's function | ✅ Done | Precomputed with influence correction |
//! | Force interpolation | ✅ Done | B-spline gradient method |
//! | erfc short-range | ✅ Done | With self-energy and dipole corrections |
//! | Combined PPPM | ✅ Done | CPU reference impl, GPU FFT ready |
//! | **GPU PPPM** | ✅ Done | Universal WGSL shaders |
//!
//! # WGSL Shaders (Universal)
//!
//! All PPPM math is implemented in WGSL for hardware-agnostic execution:
//! - `bspline.wgsl` - B-spline evaluation kernel
//! - `charge_spread.wgsl` - Particle → mesh spreading
//! - `greens_apply.wgsl` - K-space Green's function
//! - `force_interp.wgsl` - Mesh → particle interpolation
//! - `erfc_forces.wgsl` - Real-space short-range forces
//!
//! # References
//!
//! - Essmann et al., JCP 103 (1995) - Smooth PME algorithm
//! - Deserno & Holm, JCP 109 (1998) - PPPM accuracy analysis
//! - LAMMPS PPPM implementation (BSD-3-Clause)
pub
pub
pub
// EVOLVED: Extracted for modularity (Feb 14, 2026)
// EVOLVED: Extracted for modularity (Feb 14, 2026)
// CPU reference implementation
pub use ;
pub use ;
pub use ;
// WGSL shader sources (for custom GPU pipelines)
pub use WGSL_BSPLINE_F64;
pub use WGSL_CHARGE_SPREAD_F64;
pub use WGSL_FORCE_INTERPOLATION_F64;
pub use GreensFunction;
pub use ;
pub use ;
pub use ;
// GPU universal implementation (WGSL shaders)
pub use PppmGpu;
// GPU helpers (for advanced users)
pub use ;
pub use ;