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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
//! E4 – Experimental Module Validation & Retention Criteria
//!
//! This module documents which experimental methods remain gated behind
//! feature flags and the criteria required for eventual promotion to core.
//!
//! ## Promoted to Core (E3)
//!
//! | Module | Core path | Justification |
//! |--------|-----------|---------------|
//! | EEQ charges | `charges_eeq` | Topology-free partial charges, O(N²), validated vs Gasteiger |
//! | D4 dispersion | `dispersion` | BJ-damped DFT-D4 energy, complements UFF/MMFF94 |
//! | ALPB solvation | `solvation_alpb` | Klamt-corrected solvation, improves over plain GB |
//! | sTDA UV-Vis | `spectroscopy::stda_uvvis` | CIS-like excitations from monopole charges, ~1000× faster than full CI |
//! | GIAO NMR | `spectroscopy::giao_nmr` | Multi-nucleus NMR shieldings, complements empirical HOSE |
//!
//! ---
//!
//! ## Retained as Experimental (E4)
//!
//! ### EXP-201: Kernel Polynomial Method (KPM)
//!
//! **Feature flag:** `experimental-kpm`
//! **Location:** `experimental/kpm/` (chebyshev.rs, density.rs)
//!
//! KPM approximates the density of states via Chebyshev expansion of the
//! spectral function. Useful for very large systems (10k+ atoms) but the
//! current implementation lacks:
//!
//! - Adaptive polynomial order selection
//! - Sparse-matrix backend for O(N) scaling
//! - Benchmarks against direct diagonalization for <500 atoms
//!
//! **Promotion criteria:**
//! 1. Demonstrate wall-clock advantage over direct DOS for >2000 atoms
//! 2. Validate spectral accuracy within 0.1 eV of full diagonalization
//! 3. Add sparse matrix support (nalgebra-sparse or sprs)
//!
//! ### EXP-202: Multi-Basin Hopping (MBH)
//!
//! **Feature flag:** `experimental-mbh`
//! **Location:** `experimental/mbh/` (blocks.rs, hessian.rs)
//!
//! Block-diagonal Hessian approach for exploring conformational basins.
//! Intended for global optimization of flexible molecules.
//!
//! **Current limitations:**
//! - No energy evaluator integration (needs UFF/MMFF94 coupling)
//! - Block decomposition heuristic is molecule-size dependent
//! - Missing Metropolis acceptance criterion
//!
//! **Promotion criteria:**
//! 1. Integrate with `forcefield` module for energy evaluation
//! 2. Reproduce known global minima for test molecules (alanine dipeptide, etc.)
//! 3. Compare basin-hopping yield vs multi-seed ETKDG
//!
//! ### EXP-203: Randomized Numerical Linear Algebra (RandNLA)
//!
//! **Feature flag:** `experimental-randnla`
//! **Location:** `experimental/rand_nla/` (nystrom.rs, solver.rs)
//!
//! Nyström approximation and randomized eigensolvers for large overlap/Fock
//! matrices. Currently a backend alternative, not a user-facing feature.
//!
//! **Current limitations:**
//! - Rank selection requires manual tuning
//! - No automatic accuracy estimation
//! - Not yet wired into SCF or EHT solvers
//!
//! **Promotion criteria:**
//! 1. Wire into EHT/SCF as optional backend with feature flag
//! 2. Show <1% error in eigenvalues for rank = N/4
//! 3. Demonstrate speedup for N>500 basis functions
//!
//! ### EXP-204: Spectral Dimensionality Reduction (SDR)
//!
//! **Feature flag:** `experimental-sdr`
//! **Location:** `experimental/sdr/` (embedding.rs, projections.rs)
//!
//! Diffusion-map and spectral embedding for chemical space visualization.
//! Alternative to fingerprint-based Tanimoto similarity.
//!
//! **Current limitations:**
//! - Kernel bandwidth selection is fixed
//! - No out-of-sample extension (Nyström embedding)
//! - Limited to datasets fitting in memory
//!
//! **Promotion criteria:**
//! 1. Validate embeddings preserve known SAR relationships
//! 2. Add adaptive bandwidth selection
//! 3. Compare clustering quality vs Butina (Tanimoto)
//!
//! ### EXP-205a: Conformal Geometric Algebra (CGA)
//!
//! **Feature flag:** `experimental-cga`
//! **Location:** `experimental/cga/` (multivector.rs, motor.rs, conformer.rs, materials.rs)
//!
//! CGA representation of molecular geometry: motors for rigid transforms,
//! conformal points for distance geometry. Research-stage alternative to
//! Cartesian coordinate manipulation.
//!
//! **Current limitations:**
//! - 5D multivector operations have overhead vs 3D rotations
//! - Conformer pipeline not competitive with ETKDG
//! - Materials assembly untested with real MOF structures
//!
//! **Promotion criteria:**
//! 1. Demonstrate advantage in distance geometry constraint handling
//! 2. Benchmark CGA conformer vs ETKDG quality and speed
//! 3. Show utility for symmetry-constrained crystal assembly
//!
//! ### EXP-205b: Growing String Method (GSM)
//!
//! **Feature flag:** `experimental-gsm`
//! **Location:** `experimental/gsm/` (string.rs, saddle.rs)
//!
//! Reaction path finding via growing string interpolation between
//! reactant and product geometries. Identifies transition states.
//!
//! **Current limitations:**
//! - No gradient source (needs coupled PES evaluation)
//! - String convergence criteria incomplete
//! - Saddle point refinement not validated
//!
//! **Promotion criteria:**
//! 1. Couple with PM3 or xTB gradient evaluation
//! 2. Reproduce known barrier heights (SN2, Diels-Alder)
//! 3. Compare path energy profiles vs NEB reference
//!
//! ### EXP-205c: Continuous Phase Methods (CPM)
//!
//! **Feature flag:** `experimental-cpm`
//! **Location:** `experimental/cpm/` (surface.rs, grand_potential.rs)
//!
//! Phase-field and grand potential methods for crystal surface
//! thermodynamics and phase boundary determination.
//!
//! **Current limitations:**
//! - Grand potential formulation needs thermodynamic data
//! - Surface energy calculations untested for ternary systems
//! - No integration with `materials` module
//!
//! **Promotion criteria:**
//! 1. Validate surface energies against DFT reference for binary alloys
//! 2. Integrate with `materials::UnitCell` for consistent crystal handling
//! 3. Add Wulff construction for equilibrium crystal shapes
// This module is documentation-only; no runtime code.
// The experimental modules remain behind their respective feature flags.