[us-commits] [ehb54/ultrascan3] eb2fff: Add the Durchschlag & Zipper psv engine

[emre brookes]

  Branch: refs/heads/ehb54-issue-980
  Home:   https://github.com/ehb54/ultrascan3
  Commit: eb2fffb9b195733f5c397d8502e880d37c8be907
      https://github.com/ehb54/ultrascan3/commit/eb2fffb9b195733f5c397d8502e880d37c8be907
  Author: ehb54 <brookes at uthscsa.edu>
  Date:   2026-08-08 (Sat, 08 Aug 2026)

  Changed paths:
    A us_somo/develop/include/us_hydrodyn_psv.h
    M us_somo/develop/perceiver/DECISIONS.md
    M us_somo/develop/perceiver/Makefile
    A us_somo/develop/perceiver/tests/psv.cpp
    A us_somo/develop/src/us_hydrodyn_psv.cpp

  Log Message:
  -----------
  Add the Durchschlag & Zipper psv engine

Computes partial specific volume from published atomic volume increments,
consuming the perceived atoms and the bond/ring graph added in the previous
commit. Returns molar volume, vbar and a labelled decomposition -- atomic sum,
covolume, ring decrement, electrostriction, ring and charge counts -- so a
value can be audited rather than taken on trust. Atoms whose environment
cannot be classified are reported for review rather than guessed.

The covolume defaults off, since a residue is a monomeric unit and SOMO
already adds one structure-level covolume in calc_vbar_updated; a flag turns
it on for a standalone molecule. Only rings lying entirely inside the residue
are charged, which is both correct chemistry and immunity to the spurious
cross-residue rings that clashing coordinates produce.

Two rules a naive implementation gets wrong, both verified against the
published tables:

  The hydroxyl increment is topological, not a running count. A second
  NEIGHBOURING hydroxyl takes 0.4 but an isolated one is a fresh 2.3, so
  hydroxyls are clustered by whether their carrier atoms are bonded.
  1,2-ethanediol comes out at 53.5 and 1,8-octanediol at 152.0, exactly the
  published calculated volumes; a running count reproduces neither.

  Guanidinium charges only the terminal nitrogens. Table 1's footnote limits
  the 8.0 increment "in Arg only to the two terminal N", so arginine's NE
  takes the amine value.

Tests reproduce urea 44.2, glycerol 70.0 and all seven published group
increments exactly, and give mean absolute error of 1.64% against the stored
somo.residue vbar over the fifteen charge-neutral amino acids, none worse
than 6%.

Arginine and histidine sit outside that: the perceiver assigns them no formal
charge while somo.residue stores them protonated, so they lose an
electrostriction term. Arginine is essentially always protonated at
physiological pH, so that is a perception gap for the deferred pH layer rather
than ambiguous chemistry.

Refs ehb54/ultrascan-tickets#980

Co-Authored-By: Claude Opus 4.8 <noreply at anthropic.com>



To unsubscribe from these emails, change your notification settings at https://github.com/ehb54/ultrascan3/settings/notifications