[us-commits] [ehb54/ultrascan3] 12fa3e: somo/grpy: self-validating shell reduction with re...

[emre brookes]

  Branch: refs/heads/ehb54-issue-984
  Home:   https://github.com/ehb54/ultrascan3
  Commit: 12fa3ee4567ed094364a5348644cc3fc2fb58b44
      https://github.com/ehb54/ultrascan3/commit/12fa3ee4567ed094364a5348644cc3fc2fb58b44
  Author: ehb54 <brookes at uthscsa.edu>
  Date:   2026-08-06 (Thu, 06 Aug 2026)

  Changed paths:
    M us_somo/develop/grpy/README.md
    A us_somo/develop/grpy/grpy_exposure.hpp
    A us_somo/develop/grpy/grpy_shell.hpp
    M us_somo/develop/grpy/tests/run.sh
    A us_somo/develop/grpy/tests/test_shell.cpp
    M us_somo/develop/libus_somo.pro

  Log Message:
  -----------
  somo/grpy: self-validating shell reduction with reported error bars

GRPY costs O((11N)^3), so the bead count dominates. A dense bead packing is
hydrodynamically screened -- interior beads sit in near-stagnant fluid and carry
almost no force -- so the exact calculation can run on a surface-enriched subset.
This generalizes the existing binary ASA buried-bead exclusion into a convergence
test that reports the error it introduced.

Method: Shrake-Rupley exposure per bead (1.4 A probe), keep the most-exposed
ceil(f*N), solve on a doubling ladder of bead fractions, stop when the reported
bar drops below tolerance. Three rungs give the convergence order from the ratio
of successive gaps, so the remaining error is Richardson-extrapolated per
observable. The ladder is geometric against O(N^3) and costs ~1.14x its final
rung, so the check is nearly free; its final rung is the unreduced model, so an
unreducible structure degrades to exactly today's behaviour.

The bar bounds the true error: verified 92/92 (translational, 23 models,
N=204-4068) and 252/252 (7 observables x 12 models x 3 tolerances) against
unreduced exact GRPY. The observed convergence order (median 1.83) matches a
value predicted independently by a raw reduction sweep, so the error model is
derived rather than fitted.

Selection is by target bead FRACTION, not a fixed exposure threshold: the buried
fraction ranges ~1%-50% across model types, so one threshold gives wildly
different cost per model while a fraction controls O(N^3) directly.

Observables do not share a reduction frontier. Median error relative to D_t at
equal reduction is 1.77x for D_r but 3.34x for intrinsic viscosity, which drove
the stopping decision in 36/36 test cases. ShellOptions::require therefore lets
the caller choose what must converge, and ShellReport::viscosity_unreliable tells
the caller to withhold viscosity and the viscosity-derived Einstein radius when
it was not converged; the values stay in the report for the record, with a
warning appended.

Known failure mode, guarded: on a degenerate exposure distribution (a perfect
cubic lattice realizes ~9 distinct values over 216 beads) rungs swallow whole
symmetry shells instead of refining, the estimated order comes out spuriously
high, and the bar understated by ~1.4x. A floor caps extrapolation tightening at
2x the raw gap. That restores honesty on the lattice and is slack on every real
model tested -- identical honesty, no speedup cost. The lattice is kept as a
regression in tests/test_shell.cpp.

MW and Rg are pinned to full-model values. Re-derived from a reduced bead list,
MW would fall with the dropped beads (corrupting sedimentation and both
viscosities, which are mass-normalized) and Rg would rise (a hollow shell has a
larger radius of gyration than the solid body). Both are regression-tested.

Disabled by default: with enabled=false the result is byte-identical to
Solver::run, so results never move silently.

On speed, honestly: against an unreduced model the gain reaches ~120x, but SOMO
defaults to ASA buried-bead exclusion, which already removes most dead beads.
Measured on that production baseline the incremental gain is ~2-3x, rising with
model size. The durable contribution is the error bar -- the existing exclusion
reports no uncertainty at all.

Module only; the SOMO call site and GUI control follow separately.

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



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