Residue-resolved hydration shell: weight Voronoi/SASA water dummies by MD-derived per-amino-acid affinity

[mlund]

Summary

Generalise the Voronoi (and SASA) hydration-shell dummy weights from pure
geometry to a residue-resolved hydration contrast, seeded from
MD-derived per-amino-acid hydration data.

Motivation

All current SAXS calculators (CRYSOL, FoXS, Pepsi-SAXS, AUSAXS) — and
pripps today — model the hydration shell with a single uniform contrast
parameter (c2 / contrast_density). But the first water layer is not
uniform: Linse, Fischbach & Hub (bioRxiv 2025.06.10.658889) rank the 20
amino acids by hydration-shell density and find acidic residues
(Asp/Glu) generate the strongest excess (~+1 to +1.5 waters relative to
Ala), cationic/polar residues a milder excess, and apolar residues a
depletion layer (locally below bulk). This chemical texture is exactly
what a uniform shell cannot represent.

Proposal

Generalise the per-dummy weight:

weight_i = (V_i / V_water) * a(residue_i)

where a(·) is a per-residue (or per-atom-kind) hydration affinity:
a > 1 for acidic, mild > 1 for cationic/polar, a < 1 (toward local
negative contrast) for apolar; anchor a(ALA) = 1. Seed the default table
from Linse et al. 2025.

Parameter economy (important): fix the relative table and keep the
single global c2 as the overall scale. The shell becomes chemically
textured at no extra fitted parameter — this is not a 20-dim free
vector (that would overfit).

Why it fits pripps specifically

• The Voronoi hydration dummies already carry parent_index
  (voronota-ltr SolventSphere), and pripps atom kinds already encode
  residue context (e.g. ASP:OD, LYS:NZ). Each surface water already
  knows its residue — the hook exists, it just isn't used in
  src/solvent/voronoi_hydration.rs (weights are currently
  s.weight / WATER_VOLUME only).
• Natural API: optional hydration_weight: 1.0 field per species in the
  form-factor YAML, read by the Voronoi/SASA hydration models. Keeps the
  user-editable ethos and extends to CG (per-bead Martini hydration
  affinities).
• Geometric Voronoi placement answers where the water sits and how much
  volume it occupies; the Linse table answers how strongly it deviates
  from bulk. FoXS atom-centred SASA dummies / Pepsi grid cells lack a
  clean per-surface-water residue handle; the discrete Voronoi waters have
  it — so the two ideas compound.

Validation before claiming anything

• Compare uniform-c2 Voronoi shell vs Linse-weighted Voronoi shell on the
  SASBDB benchmark; report χ² improvement and where it concentrates
  (highly charged proteins, IDPs such as Hub's XAO peptide).
• Demonstrate the weighted shell uses the same single fitted c2 — any
  improvement comes from chemistry, not extra free parameters.

Caveats

• Linse scores are explicit-solvent, water-model- and force-field-dependent,
  and defined relative to alanine; transferring them to a dummy-contrast
  amplitude is an approximation that needs calibration, not a
  first-principles mapping.
• Source is currently a preprint — recheck for the peer-reviewed version.

References

• Linse, J.-B., Fischbach, T. M. & Hub, J. S. (2025). Hydration shells of
  globular and intrinsically disordered proteins… bioRxiv
  2025.06.10.658889.

[mlund]

Follow-up notes: sign convention, numerical guardrails, and validation

1. Affinity is a signed excess centred on bulk (corrects the wording above)

SAXS sees contrast, so a hydration dummy represents excess electron density over bulk:
amplitude_i ∝ (ρ_shell,i − ρ_bulk)·V_i = ρ_bulk·δ_i·V_i. The per-residue factor
must therefore be signed, not a positive multiplier:

Shell vs bulk	δ_i	dummy
enhanced (Asp/Glu)	> 0	positive
at bulk	= 0	none — invisible, omit
depleted (apolar)	< 0	negative (sign-flipped)

So the earlier "anchor a(ALA)=1, a<1 for apolar" is imprecise. Use
sign(a_i) = sign(δ_i); a_i = 0 means indistinguishable from bulk and the
dummy can be dropped at placement time (fewer scatterers → cheaper multipole
expansion). Depletion is negative contrast, not zero contrast — those dummies
stay, with a flipped sign.

2. Physical floor: clamp δ_i ≥ −1

You cannot remove more water than is present, so ρ_shell = ρ_bulk(1 + δ_i) ≥ 0,
i.e. δ_i ≥ −1. Clamp the affinity table accordingly. In practice depletion is
mild (δ ≈ −0.1…−0.2), so this rarely binds, but it guards against a runaway
negative shell and keeps the contrast-match crossing physical.

3. Negative contrast is fine in Debye and Multipole — but watch cancellation

No correctness issue: both kernels are linear in the per-scatterer factors and
return I(q) as a sum of squared moduli (Debye = exact identity; multipole =
2π²Σ_l Σ_m |A_lm|², ≥ 0 even when truncated). Negative scatterers already exist
(the excluded-volume term subtracts) and are routine in SANS (H has b < 0). In the
cached MultipoleModel, contrast is a linear recombination weight, so a sign flip
is free — no basis rebuild.

The real risk is catastrophic cancellation near form-factor minima and
contrast-match, where net I(q) is a small difference of larger ± amplitudes:

• Debye: roundoff at the dips (f64 mitigates).
• Multipole: atomic vs dummy truncation residuals don't cancel, amplifying the
  relative error in the small net I(q). The conservative auto-L handles it, but
  an aggressive hand-set --lmax can under-converge exactly there.

Cross-check: under strong negative contrast, confirm multipole agrees with
Debye (the exact reference) at the minima. Agreement proves auto-L is high
enough; divergence flags truncation → raise --lmax.

4. Validation against the WAXSiS shell contribution (preferred)

Rather than only fitting total experimental curves (where shell, excluded volume,
and form-factor errors are entangled), validate the dummy hydration term directly
against the explicit-solvent hydration-shell I(q) that WAXSiS isolates. WAXSiS
(Knight & Hub 2015) computes SWAXS from MD over a solvent envelope and can return
the shell-only contribution — a per-component ground truth.

Proposed protocol:

1. Run WAXSiS on a test protein; extract the hydration-shell contribution to I(q)
   (the explicit-solvent excess over bulk).
2. Build the pripps Voronoi dummy shell on the same structure; compute the
   shell-only I(q) (the .hydration channel already exposed per-contribution).
3. Compare uniform-c2 vs Linse-weighted (signed) dummy shell against the WAXSiS
   shell — directly, no full-curve fit. The Linse-weighted shell should track the
   explicit-solvent shell better, most on charged proteins and IDPs (e.g. Hub's
   XAO) where the shell is most heterogeneous.
4. Same single fitted c2 for both dummy variants → any improvement is chemistry,
   not extra free parameters.

This makes the validation a clean per-component comparison (dummy shell vs
explicit-solvent shell) rather than an indirect inference from a total-intensity fit.

[mlund]

Generalised in #10 — a morphometric, geometry-derived hydration contrast (chemical-type-resolved contact area + two-probe curvature, trained on WAXSiS shell decompositions) that aims to be universal across folded proteins and IDPs. This issue (#9, fixed per-residue Linse table) is the simpler fallback.