[us-commits] [ehb54/ultrascan3] 53cb46: Native grid volume + analysis tools for vbar/molvo...

[emre brookes]

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

  Changed paths:
    A us_somo/develop/include/us_hydrodyn_grid_volume.h
    M us_somo/develop/perceiver/DECISIONS.md
    A us_somo/develop/perceiver/Makefile
    M us_somo/develop/perceiver/README.md
    A us_somo/develop/perceiver/tests/grid_volume.cpp
    A us_somo/develop/perceiver/tools/calibrate_3v_context.py
    A us_somo/develop/perceiver/tools/hydration_table.py
    A us_somo/develop/perceiver/tools/psv_durchschlag.py
    A us_somo/develop/perceiver/tools/recalc_ligand_volumes.py
    A us_somo/develop/src/us_hydrodyn_grid_volume.cpp

  Log Message:
  -----------
  Native grid volume + analysis tools for vbar/molvol/hydration

Groundwork for filling the three fields a generated residue entry currently
leaves at zero: psv (vbar), anhydrous molar volume, and hydration.

Native grid volume (us_hydrodyn_grid_volume.h/.cpp, Qt-free)

  accessible A = { v : |v - c_i| > r_i + probe for every atom i }
  excluded   E = { v : v not in A, and dist(v, A) > probe }
  volume       = |E| * grid^3

probe 0 gives the bare van der Waals union, probe 1.4 the solvent-excluded
volume. Interior cavities are deliberately not counted, which is what lets
V(complex) - V(complex minus ligand) measure a bound ligand in context. Only
the accessible/blocked boundary is dilated -- the nearest accessible voxel to
any blocked voxel is always a boundary one -- so the cost is a surface rather
than a volume, and a 0.25 A grid runs in about a second for a 1300-atom
protein.

This removes what would otherwise be a new external dependency on 3V
(vossvolvox). 3V is retained only as the validation oracle: tests/grid_volume.cpp
reproduces Volume.exe to within 0.8% on an isolated residue, a whole protein,
and a bound-ligand difference, and adds analytic checks (single sphere,
coincident spheres, and a sealed hollow shell whose cavity must not be counted).
10 checks, 0 failures.

Analysis tools (prototypes, not built into libus_somo)

  psv_durchschlag.py      Durchschlag & Zipper atomic volume increments, no
                          fitting. Self-tests against the papers' own worked
                          values before reporting anything.
  hydration_table.py      derives a hybrid-type -> waters lookup from
                          somo.residue; 36 of 48 types unanimous, 7 weak and
                          flagged for review rather than silently defaulted.
  calibrate_3v_context.py calibrates the in-context difference method against
                          residues whose volume we already know.
  recalc_ligand_volumes.py recomputes prosthetic-group volumes, guarded on
                          elemental formula and on reproducing the stored value.

DECISIONS.md records the findings behind these, including why the anhydrous
volume field wants a 1.4 A probe rather than 0, and the measured-versus-
calculated trap in the Durchschlag 1986 tables.

The perceiver's hand-written test Makefile is force-added: the repository root
ignores "Makefile" for the qmake-generated ones, which left the documented
"make unit" impossible from a fresh clone.

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