dreid_kernel/
traits.rs

1use crate::math::Real;
2use crate::types::{EnergyDiff, HybridEnergyDiff};
3
4// ============================================================================
5// 1. Pair Potential (2-Body Interaction)
6// ============================================================================
7
8/// Trait for 2-body potentials (Bond Stretch, Van der Waals, Coulomb).
9///
10/// Models interaction energy as a function of squared distance $r^2$.
11///
12/// # Mathematical Contract
13/// - **Input**: Squared distance $r^2$ (to avoid unnecessary square roots in cutoff checks).
14/// - **Output (Diff)**: The radial force pre-factor $D$ defined as:
15///   $$ D = -\frac{1}{r} \frac{dE}{dr} $$
16pub trait PairKernel<T: Real> {
17    /// Associated constants/parameters required by the potential (e.g., $k, r_0$).
18    type Params: Copy;
19
20    /// Computes only the potential energy.
21    fn energy(r_sq: T, params: Self::Params) -> T;
22
23    /// Computes only the force pre-factor $D$.
24    fn diff(r_sq: T, params: Self::Params) -> T;
25
26    /// Computes both energy and force pre-factor efficiently.
27    /// Should share intermediate calculations (e.g., `sqrt`, `exp`) where possible.
28    fn compute(r_sq: T, params: Self::Params) -> EnergyDiff<T>;
29}
30
31// ============================================================================
32// 2. Angle Potential (3-Body / 4-Body Planar Interaction)
33// ============================================================================
34
35/// Trait for bending potentials (Angle) and inversion potentials (Improper).
36///
37/// Models interaction energy as a function of the cosine of an angle $\theta$ or $\psi$.
38///
39/// # Mathematical Contract
40/// - **Input**: Cosine of the angle ($\cos\theta$).
41///   - For Angles: $\cos\theta = \hat{r}\_{ji} \cdot \hat{r}\_{jk}$
42///   - For Inversions: $\cos\psi = \hat{n}\_{jik} \cdot \hat{r}\_{il}$
43/// - **Output (Diff)**: The torque-like factor $\Gamma$ defined as:
44///   $$ \Gamma = \frac{dE}{d(\cos\theta)} $$
45pub trait AngleKernel<T: Real> {
46    /// Associated constants/parameters required by the potential (e.g., $k, \theta_0$).
47    type Params: Copy;
48
49    /// Computes only the potential energy.
50    fn energy(cos_angle: T, params: Self::Params) -> T;
51
52    /// Computes only the torque-like factor $\Gamma$.
53    fn diff(cos_angle: T, params: Self::Params) -> T;
54
55    /// Computes both energy and torque-like factor efficiently.
56    /// Should share intermediate calculations where possible.
57    fn compute(cos_angle: T, params: Self::Params) -> EnergyDiff<T>;
58}
59
60// ============================================================================
61// 3. Torsion Potential (4-Body Interaction)
62// ============================================================================
63
64/// Trait for torsional potentials (Dihedrals).
65///
66/// Models interaction energy as a function of the dihedral angle $\phi$.
67///
68/// # Mathematical Contract
69/// - **Input**: Both $\cos\phi$ and $\sin\phi$ are required to determine phase and
70///   compute multi-term expansions (e.g., $\cos(n\phi)$) without `acos`.
71/// - **Output (Diff)**: The pure torque $T$ defined as:
72///   $$ T = \frac{dE}{d\phi} $$
73pub trait TorsionKernel<T: Real> {
74    /// Associated constants/parameters required by the potential (e.g., $V, n$).
75    type Params: Copy;
76
77    /// Computes only the potential energy.
78    fn energy(cos_phi: T, sin_phi: T, params: Self::Params) -> T;
79
80    /// Computes only the pure torque $T$.
81    fn diff(cos_phi: T, sin_phi: T, params: Self::Params) -> T;
82
83    /// Computes both energy and pure torque efficiently.
84    /// Should share intermediate calculations where possible.
85    fn compute(cos_phi: T, sin_phi: T, params: Self::Params) -> EnergyDiff<T>;
86}
87
88// ============================================================================
89// 4. Hybrid Potential (Mixed Interaction)
90// ============================================================================
91
92/// Trait for potentials dependent on both distance and angle (e.g., H-Bonds).
93///
94/// Models interaction energy as a function of squared distance $r^2$ and
95/// cosine of angle $\cos\theta$.
96///
97/// # Mathematical Contract
98/// - **Input**: Squared distance $r^2$ and cosine of angle $\cos\theta$.
99/// - **Output**: Two derivative factors:
100///   1. `force_factor_rad`: Radial part ($- \frac{1}{r} \frac{dE}{dr}$).
101///   2. `force_factor_ang`: Angular part ($ \frac{dE}{d(\cos\theta)}$).
102pub trait HybridKernel<T: Real> {
103    /// Associated constants/parameters required by the potential.
104    type Params: Copy;
105
106    /// Computes only the potential energy.
107    fn energy(r_sq: T, cos_theta: T, params: Self::Params) -> T;
108
109    /// Computes only the derivative factors `(force_factor_rad, force_factor_ang)`.
110    fn diff(r_sq: T, cos_theta: T, params: Self::Params) -> (T, T);
111
112    /// Computes both energy and derivative factors efficiently.
113    /// Should share intermediate calculations where possible.
114    fn compute(r_sq: T, cos_theta: T, params: Self::Params) -> HybridEnergyDiff<T>;
115}
dreid_kernel/traits.rs

dreid_kernel/
traits.rs
