use std::io::Cursor;
use std::sync::LazyLock;
use tract_onnx::prelude::*;
const MODEL: &[u8] = include_bytes!("../assets/espaloma_charge.onnx");
static PLAN: LazyLock<TypedRunnableModel<TypedModel>> = LazyLock::new(|| {
tract_onnx::onnx()
.model_for_read(&mut Cursor::new(MODEL))
.expect("read espaloma onnx")
.into_optimized()
.expect("optimize")
.into_runnable()
.expect("runnable")
});
pub(crate) fn run_gnn(features: &[f32], adj_mean: &[f32], n: usize) -> TractResult<(Vec<f32>, Vec<f32>)> {
let f = Tensor::from_shape(&[n, 116], features)?;
let a = Tensor::from_shape(&[n, n], adj_mean)?;
let out = PLAN.run(tvec!(f.into(), a.into()))?;
let e = out[0].to_array_view::<f32>()?.iter().copied().collect();
let s = out[1].to_array_view::<f32>()?.iter().copied().collect();
Ok((e, s))
}
fn mass_by_z(z: u8) -> f32 {
match z {
1 => 1.008, 6 => 12.011, 7 => 14.007, 8 => 15.999, 9 => 18.998,
15 => 30.974, 16 => 32.06, 17 => 35.45, 35 => 79.904, 53 => 126.904,
_ => 0.0,
}
}
fn hybridization(z: u8, degree: usize, n_double: u32, n_triple: u32, aromatic: bool, neighbor_conj: bool) -> Option<usize> {
if z == 1 {
return None;
}
if aromatic {
return Some(1); }
if degree >= 6 {
return Some(4); }
if degree == 5 {
return Some(3); }
if degree == 4 {
return Some(2); }
if n_triple >= 1 || n_double >= 2 {
return Some(0); }
if n_double == 1 {
return Some(1); }
if neighbor_conj && ((z == 7 && degree == 3) || (z == 8 && degree <= 2)) {
return Some(1); }
Some(2) }
fn n_outer_elec(z: u8) -> i32 {
match z {
1 => 1, 6 => 4, 7 => 5, 8 => 6, 9 => 7, 15 => 5, 16 => 6, 17 => 7, 35 => 7, 53 => 7,
_ => 0,
}
}
fn electronegativity(z: u8) -> f32 {
match z {
1 => 2.20, 6 => 2.55, 7 => 3.04, 8 => 3.44, 9 => 3.98, 15 => 2.19, 16 => 2.58,
17 => 3.16, 35 => 2.96, 53 => 2.66, _ => 0.0,
}
}
fn aromatic_atoms(z: &[u8], fc: &[i32], bonds: &[crate::gaff::LocalBond], rings: &[Vec<usize>]) -> Vec<bool> {
let n = z.len();
let mut inc: Vec<Vec<(usize, u8)>> = vec![Vec::new(); n];
for b in bonds {
inc[b.i].push((b.j, b.order));
inc[b.j].push((b.i, b.order));
}
let mut in_ring = vec![false; n];
for r in rings {
for &a in r {
in_ring[a] = true;
}
}
let contrib: Vec<Option<i32>> = (0..n)
.map(|a| {
let sigma = inc[a].len() as i32;
if sigma >= 4 || inc[a].iter().any(|&(j, o)| o == 3 && in_ring[j]) {
return None;
}
let mut exocyclic_zero = false;
for &(j, o) in &inc[a] {
if o >= 2 && !in_ring[j] {
if electronegativity(z[j]) > electronegativity(z[a]) {
exocyclic_zero = true;
} else {
return None; }
}
}
if exocyclic_zero {
return Some(0);
}
let avail = n_outer_elec(z[a]) - fc[a] - sigma;
Some(if avail <= 0 { 0 } else if avail % 2 == 1 { 1 } else { 2 })
})
.collect();
let huckel = |atoms: &[usize]| -> bool {
let mut pi = 0;
for &a in atoms {
match contrib[a] {
Some(c) => pi += c,
None => return false,
}
}
pi % 4 == 2
};
let mut arom = vec![false; n];
for ring in rings {
if huckel(ring) {
for &a in ring {
arom[a] = true;
}
}
}
let mut parent: Vec<usize> = (0..rings.len()).collect();
fn find(parent: &mut [usize], x: usize) -> usize {
let mut r = x;
while parent[r] != r {
r = parent[r];
}
let mut c = x;
while parent[c] != r {
let next = parent[c];
parent[c] = r;
c = next;
}
r
}
for i in 0..rings.len() {
for j in (i + 1)..rings.len() {
if rings[i].iter().filter(|a| rings[j].contains(a)).count() >= 2 {
let (ri, rj) = (find(&mut parent, i), find(&mut parent, j));
parent[ri] = rj;
}
}
}
let mut systems: std::collections::BTreeMap<usize, std::collections::BTreeSet<usize>> =
Default::default();
for i in 0..rings.len() {
let root = find(&mut parent, i);
systems.entry(root).or_default().extend(rings[i].iter().copied());
}
for atoms in systems.values() {
let atoms: Vec<usize> = atoms.iter().copied().collect();
if huckel(&atoms) {
for &a in &atoms {
arom[a] = true;
}
}
}
arom
}
pub(crate) fn featurize(z: &[u8], fc: &[i32], bonds: &[crate::gaff::LocalBond]) -> (Vec<f32>, Vec<f32>) {
let n = z.len();
let bond_adj = molar::prelude::BondAdjacency::build(n, bonds.iter().map(|b| [b.i, b.j]));
let rings = molar::prelude::sssr_rings(&bond_adj);
let mut rg = vec![[false; 11]; n]; for r in &rings {
let sz = r.len().min(10);
for &a in r {
rg[a][sz] = true;
}
}
let (mut nd, mut nt, mut val) = (vec![0u32; n], vec![0u32; n], vec![0u32; n]);
for b in bonds {
val[b.i] += b.order as u32;
val[b.j] += b.order as u32;
if b.order == 2 {
nd[b.i] += 1;
nd[b.j] += 1;
} else if b.order == 3 {
nt[b.i] += 1;
nt[b.j] += 1;
}
}
let aromatic = aromatic_atoms(z, fc, bonds, &rings);
let neighbor_conj: Vec<bool> = (0..n)
.map(|i| {
bond_adj.neighbors(i).iter().any(|nb| {
let j = nb.atom();
aromatic[j] || ((nd[j] > 0 || nt[j] > 0) && matches!(z[j], 6 | 7))
})
})
.collect();
let mut feat = vec![0f32; n * 116];
for i in 0..n {
let o = i * 116;
if (z[i] as usize) < 100 {
feat[o + z[i] as usize] = 1.0; }
let degree = bond_adj.neighbors(i).len();
feat[o + 100] = degree as f32; feat[o + 101] = val[i] as f32; feat[o + 102] = val[i] as f32; feat[o + 103] = if aromatic[i] { 1.0 } else { 0.0 };
feat[o + 104] = mass_by_z(z[i]);
for (k, sz) in (3..=8).enumerate() {
feat[o + 105 + k] = if rg[i][sz] { 1.0 } else { 0.0 };
}
if let Some(h) = hybridization(z[i], degree, nd[i], nt[i], aromatic[i], neighbor_conj[i]) {
feat[o + 111 + h] = 1.0;
}
}
let mut adj = vec![0f32; n * n];
for b in bonds {
adj[b.i * n + b.j] = 1.0;
adj[b.j * n + b.i] = 1.0;
}
for i in 0..n {
let deg: f32 = adj[i * n..(i + 1) * n].iter().sum();
if deg > 0.0 {
for x in &mut adj[i * n..(i + 1) * n] {
*x /= deg;
}
}
}
(feat, adj)
}
pub(crate) fn espaloma_e_s(
z: &[u8],
fc: &[i32],
bonds: &[crate::gaff::LocalBond],
) -> TractResult<(Vec<f32>, Vec<f32>)> {
let (feat, adj) = featurize(z, fc, bonds);
run_gnn(&feat, &adj, z.len())
}
pub(crate) fn espaloma_charges(z: &[u8], fc: &[i32], bonds: &[crate::gaff::LocalBond]) -> TractResult<Vec<f32>> {
let (e, s) = espaloma_e_s(z, fc, bonds)?;
Ok(equilibrate(&e, &s, fc.iter().sum::<i32>() as f32))
}
pub(crate) fn equilibrate(e: &[f32], s: &[f32], q_total: f32) -> Vec<f32> {
let inv: Vec<f32> = s.iter().map(|x| 1.0 / x).collect();
let sum_inv: f32 = inv.iter().sum();
let sum_eos: f32 = e.iter().zip(&inv).map(|(a, b)| a * b).sum();
let lam = (q_total + sum_eos) / sum_inv;
e.iter().zip(&inv).map(|(a, b)| -a * b + b * lam).collect()
}
#[cfg(test)]
mod tests {
use super::*;
fn rows_f32(v: &serde_json::Value) -> Vec<f32> {
v.as_array()
.unwrap()
.iter()
.flat_map(|row| row.as_array().unwrap().iter().map(|x| x.as_f64().unwrap() as f32))
.collect()
}
fn col_f32(v: &serde_json::Value) -> Vec<f32> {
v.as_array().unwrap().iter().map(|x| x.as_f64().unwrap() as f32).collect()
}
#[test]
fn tract_matches_python_fixture() {
let txt = std::fs::read_to_string("tests/data/espaloma_fixture.json").unwrap();
let v: serde_json::Value = serde_json::from_str(&txt).unwrap();
let n = v["n"].as_u64().unwrap() as usize;
let feats = rows_f32(&v["features"]);
let adj = rows_f32(&v["adjacency_mean"]);
let exp_e = col_f32(&v["e"]);
let exp_q = col_f32(&v["charges"]);
let (e, s) = run_gnn(&feats, &adj, n).expect("tract run");
let de = e.iter().zip(&exp_e).map(|(a, b)| (a - b).abs()).fold(0.0f32, f32::max);
let q = equilibrate(&e, &s, 0.0);
let dq = q.iter().zip(&exp_q).map(|(a, b)| (a - b).abs()).fold(0.0f32, f32::max);
println!("tract vs python fixture: max|Δe|={de:.2e} max|Δq|={dq:.2e}");
assert!(de < 1e-4, "electronegativity mismatch: {de}");
assert!(dq < 1e-4, "charge mismatch: {dq}");
}
#[test]
fn corpus_rmse_vs_reference() {
use molar::prelude::*;
#[derive(serde::Deserialize)]
struct RefFile {
molecules: Vec<RefMol>,
}
#[derive(serde::Deserialize)]
struct RefMol {
name: String,
charges: Vec<f32>,
}
let txt = std::fs::read_to_string("tests/data/gaff_ref/references_espaloma.json").unwrap();
let refs: RefFile = serde_json::from_str(&txt).unwrap();
let (mut se, mut nat, mut maxd) = (0f64, 0usize, 0f32);
let (mut worst, mut load_err) = (String::new(), 0usize);
for mol in &refs.molecules {
let path = format!("tests/data/gaff_ref/sdf/{}.sdf", mol.name);
let sys = match System::from_file(&path) {
Ok(s) => s,
Err(_) => {
load_err += 1;
continue;
}
};
let z: Vec<u8> = sys.iter_atoms().map(|a| a.get_atomic_number()).collect();
let fc: Vec<i32> = sys.iter_atoms().map(|a| a.get_formal_charge().unwrap_or(0)).collect();
let mut bonds = Vec::new();
for b in sys.iter_bonds() {
let order = match b.order() {
BondOrder::Double => 2,
BondOrder::Triple => 3,
_ => 1,
};
bonds.push(crate::gaff::LocalBond { i: b.i1(), j: b.i2(), order });
}
let (e, s) = espaloma_e_s(&z, &fc, &bonds).unwrap();
let q = equilibrate(&e, &s, 0.0);
if q.len() != mol.charges.len() {
continue;
}
for (i, (a, b)) in q.iter().zip(&mol.charges).enumerate() {
let d = (a - b).abs();
se += (d as f64) * (d as f64);
nat += 1;
if d > maxd {
maxd = d;
worst = format!("{} atom={i} z={} (mine={a:.3} ref={b:.3})", mol.name, z[i]);
}
}
}
let rmse = (se / nat as f64).sqrt();
println!("espaloma Rust vs reference: RMSE={rmse:.4}e max|Δq|={maxd:.4}e worst={worst} atoms={nat} load_err={load_err}");
assert_eq!(load_err, 0);
assert!(rmse < 5e-4, "espaloma charge RMSE {rmse} regressed");
}
#[derive(serde::Deserialize)]
struct RefFile {
molecules: Vec<RefMol>,
}
#[derive(serde::Deserialize)]
struct RefMol {
name: String,
charges: Vec<f32>,
}
fn load_refs() -> Vec<RefMol> {
let txt = std::fs::read_to_string("tests/data/gaff_ref/references_espaloma.json").unwrap();
serde_json::from_str::<RefFile>(&txt).unwrap().molecules
}
#[test]
fn apply_charges_public_api() {
use crate::{ApplyCharges, ChargeModel};
use molar::prelude::*;
let refs = load_refs();
let (mol, mut sys) = refs
.iter()
.find_map(|m| {
let sys =
System::from_file(format!("tests/data/gaff_ref/sdf/{}.sdf", m.name)).ok()?;
let q_total: i32 =
sys.iter_atoms().map(|a| a.get_formal_charge().unwrap_or(0)).sum();
(q_total == 0).then_some((m, sys))
})
.expect("corpus must contain a neutral molecule");
sys.apply_charges(ChargeModel::Espaloma).unwrap();
let got: Vec<f32> = sys.iter_atoms().map(|a| a.get_charge() as f32).collect();
let maxd = got.iter().zip(&mol.charges).map(|(a, b)| (a - b).abs()).fold(0.0f32, f32::max);
let sum: f32 = got.iter().sum();
println!("apply_charges({}): max|Δ|={maxd:.2e} Σq={sum:.2e}", mol.name);
assert!(maxd < 1e-3, "apply_charges disagrees with reference: {maxd}");
assert!(sum.abs() < 1e-3, "charges should sum to ~0: {sum}");
}
#[test]
fn total_formal_charge_is_preserved() {
use crate::{ApplyCharges, ChargeModel};
use molar::prelude::*;
let (mut n_charged, mut n_neutral, mut worst) = (0usize, 0usize, 0f32);
let mut worst_name = String::new();
for m in load_refs() {
let mut sys = match System::from_file(format!("tests/data/gaff_ref/sdf/{}.sdf", m.name))
{
Ok(s) => s,
Err(_) => continue,
};
let q_total: i32 = sys.iter_atoms().map(|a| a.get_formal_charge().unwrap_or(0)).sum();
sys.apply_charges(ChargeModel::Espaloma).unwrap();
let sum: f32 = sys.iter_atoms().map(|a| a.get_charge() as f32).sum();
let d = (sum - q_total as f32).abs();
if d > worst {
worst = d;
worst_name = format!("{} (Q={q_total} Σq={sum:.4})", m.name);
}
if q_total == 0 {
n_neutral += 1;
} else {
n_charged += 1;
}
}
println!(
"Σq vs Σfc: {n_charged} charged + {n_neutral} neutral molecules, \
max|Σq − Q|={worst:.2e} worst={worst_name}"
);
assert!(n_charged > 0, "corpus must contain charged molecules to exercise this path");
assert!(worst < 1e-3, "total charge not preserved: max deviation {worst} ({worst_name})");
}
#[test]
fn aromatic_input_is_kekulized_not_rejected() {
use crate::{ApplyCharges, ChargeModel};
use molar::prelude::*;
let mut checked = 0usize;
let mut worst = 0f32;
let mut worst_name = String::new();
for m in load_refs().iter().take(80) {
let path = format!("tests/data/gaff_ref/sdf/{}.sdf", m.name);
let Ok(mut kek) = System::from_file(&path) else { continue };
let Ok(mut arom) = System::from_file(&path) else { continue };
arom.perceive();
if !arom.iter_bonds().any(|b| b.order() == BondOrder::Aromatic) {
continue;
}
kek.apply_charges(ChargeModel::Espaloma).unwrap();
arom.apply_charges(ChargeModel::Espaloma)
.unwrap_or_else(|e| panic!("{}: aromatic input rejected: {e}", m.name));
let d = kek
.iter_atoms()
.zip(arom.iter_atoms())
.map(|(a, b)| (a.get_charge() as f32 - b.get_charge() as f32).abs())
.fold(0.0f32, f32::max);
if d > worst {
worst = d;
worst_name = m.name.clone();
}
checked += 1;
}
println!("aromatic vs Kekulé charges over {checked} molecules: max|Δ|={worst:.2e} ({worst_name})");
assert!(checked > 10, "corpus should supply aromatic molecules to check");
assert!(worst < 1e-3, "aromatic path disagrees with Kekulé: {worst} ({worst_name})");
}
#[test]
fn equilibration_is_affine_in_total_charge() {
let e = [0.3f32, -0.7, 1.1, 0.05, -0.2];
let s = [1.7f32, 2.3, 0.9, 3.1, 1.2];
let inv_sum: f32 = s.iter().map(|x| 1.0 / x).sum();
let q0 = equilibrate(&e, &s, 0.0);
for &q_total in &[-2.0f32, -1.0, 1.0, 3.0] {
let q = equilibrate(&e, &s, q_total);
let sum: f32 = q.iter().sum();
assert!((sum - q_total).abs() < 1e-5, "Σq={sum} != Q={q_total}");
for i in 0..e.len() {
let expected = q0[i] + q_total * (1.0 / s[i]) / inv_sum;
assert!(
(q[i] - expected).abs() < 1e-5,
"atom {i}: {} != {expected} at Q={q_total}",
q[i]
);
}
}
}
}