[us-commits] [ehb54/ultrascan3] 579add: Perceive hybridization/vdW radius/electron count f...

[emre brookes]

  Branch: refs/heads/ehb54-issue-978
  Home:   https://github.com/ehb54/ultrascan3
  Commit: 579add03864b4311b5016d778c65e660dd753e77
      https://github.com/ehb54/ultrascan3/commit/579add03864b4311b5016d778c65e660dd753e77
  Author: ehb54 <brookes at uthscsa.edu>
  Date:   2026-07-20 (Mon, 20 Jul 2026)

  Changed paths:
    A us_somo/develop/include/us_hydrodyn_perceive.h
    A us_somo/develop/include/us_hydrodyn_perceive_elements.h
    A us_somo/develop/include/us_hydrodyn_perceive_hybrid.h
    A us_somo/develop/include/us_hydrodyn_perceive_saxs.h
    A us_somo/develop/include/us_hydrodyn_perceive_somo.h
    M us_somo/develop/libus_somo.pro
    A us_somo/develop/perceiver/.gitignore
    A us_somo/develop/perceiver/DECISIONS.md
    A us_somo/develop/perceiver/README.md
    A us_somo/develop/perceiver/data/ref/f0_WaasKirf.dat
    A us_somo/develop/perceiver/data/ref/it1992.cpp
    A us_somo/develop/perceiver/data/ref/somo.saxs_atoms.generated
    A us_somo/develop/perceiver/pdb_lite.h
    A us_somo/develop/perceiver/residue_oracle.h
    A us_somo/develop/perceiver/tests/coverage.cpp
    A us_somo/develop/perceiver/tests/emit_residue.cpp
    A us_somo/develop/perceiver/tests/regression.cpp
    A us_somo/develop/perceiver/tests/tests_unit.cpp
    A us_somo/develop/perceiver/tinytest.h
    A us_somo/develop/perceiver/tools/gen_saxs_entries.py
    A us_somo/develop/src/us_hydrodyn_perceive.cpp
    A us_somo/develop/src/us_hydrodyn_perceive_somo.cpp
    M us_somo/develop/src/us_hydrodyn_script.cpp

  Log Message:
  -----------
  Perceive hybridization/vdW radius/electron count for non-coded residues

Phases A and B of ehb54/ultrascan-tickets#978.

SOMO needs an atom's hybridization, vdW radius and electron count to build a
bead model, and today they come only from the hand-curated somo.residue. For a
residue that table does not code, SOMO synthesises a "<RESNAME>_NC<n>"
placeholder and models it as a generic ABB average bead. This adds a chemical
perceiver that derives the real per-atom chemistry from element + coordinates,
so such a residue can be given a proper entry instead of an averaged one.

somo.residue remains the master: perception runs only for residues SOMO itself
recorded in unknown_residues.

Phase A - core compiled into libus_somo:
  include/us_hydrodyn_perceive{,_elements,_hybrid,_saxs}.h
  src/us_hydrodyn_perceive.cpp
Pipeline: spatial-grid bond perception (honouring CONECT where present, and
H-/ion-agnostic so implicit-H inference is identical with or without explicit
hydrogens) -> ring detection + planarity aromaticity -> Kekule bond orders ->
per-element classification -> emit a somo.residue block plus any somo.hybrid
rows for novel types.

The core is deliberately Qt-free, so the standalone harness in
us_somo/develop/perceiver builds the very same sources without Qt: 23 unit
tests plus a regression that takes residues somo.residue DOES code, pretends
they are unknown, and checks they are reproduced - 41,219 atoms over 8 demo
structures, 99.83% geometric perception, 0.17% genuine error. The residual is
protonation/tautomer state, which heavy-atom geometry cannot resolve in
principle. The harness reads us_somo/etc directly so it cannot drift from the
real tables.

us_hydrodyn_perceive_somo.{h,cpp} is the only Qt-aware layer: it converts
PDB_model/PDB_chain/PDB_atom, reads CONECT and HETNAM from the source file,
and returns tentative entries. It converts the whole model rather than one
residue because bond perception needs surrounding context (peptide links,
disulfides, metal coordination) to get coordination numbers, and hence
implicit-H counts, right. Instances are de-duplicated back to the base residue
name so one confirmation covers all instances of the same chemistry.

Phase B - headless "perceive <pdbfile>" gui_script command, so the whole path
is exercisable against real structures with no GUI:
  us3_somo _pad -I -g <script>
Entries carry a REVIEW block naming every atom whose perception was uncertain
(ambiguous protonation, assumed oxidation state, estimated vbar), which is what
the confirmation UI in ehb54/ultrascan-tickets#979 will present to the user.

No existing behaviour changes: nothing calls the perceiver outside the new
command.

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


  Commit: 3e3fd3f51164a3220ab3b6d3d51b724d747040db
      https://github.com/ehb54/ultrascan3/commit/3e3fd3f51164a3220ab3b6d3d51b724d747040db
  Author: ehb54 <brookes at uthscsa.edu>
  Date:   2026-07-20 (Mon, 20 Jul 2026)

  Changed paths:
    M us_somo/develop/include/us_hydrodyn_perceive_somo.h
    M us_somo/develop/perceiver/README.md
    A us_somo/develop/perceiver/examples/perceive.somo
    M us_somo/develop/src/us_hydrodyn_perceive_somo.cpp
    M us_somo/develop/src/us_hydrodyn_script.cpp

  Log Message:
  -----------
  Add "perceive compare" hand-testing sub-command

Part of ehb54/ultrascan-tickets#978.

"perceive compare <pdb>" runs perception over the residues somo.residue DOES
code and diffs the result against the curated types, reporting exact-match and
physics-match rates, a curated->perceived difference histogram, and the first
differing atoms. It is the interactive equivalent of the standalone regression
harness, but run inside SOMO against the user's own installed ~/ultrascan/etc
tables - so it also reveals when an installed table is out of date.

Cross-validation on 1HEL: the in-SOMO path and the standalone harness agree
exactly (1000 atoms scored, 984 exact 98.40%, 995 physics 99.50%), despite
using different PDB parsers and different copies of the tables. The five
physics differences are all known, explainable categories: the chain
N-terminus (a real -NH3+, where the perceiver is chemically right and the
residue template cannot know), the His tautomer and its charge, and the
Asp carboxylate protonation convention.

Also adds examples/perceive.somo documenting the invocation, including the
gotchas that cost time otherwise: the throwaway "_pad" argument is required on
macOS and must be omitted on Linux, "-I" avoids blocking config dialogs, and
the first run after rebuilding libus_somo only re-installs configs and exits,
so it must be run twice.

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


  Commit: eb57f12bd7b373cf3efba41e691eb607024cafc3
      https://github.com/ehb54/ultrascan3/commit/eb57f12bd7b373cf3efba41e691eb607024cafc3
  Author: ehb54 <brookes at uthscsa.edu>
  Date:   2026-07-20 (Mon, 20 Jul 2026)

  Changed paths:
    M us_somo/develop/perceiver/README.md

  Log Message:
  -----------
  Correct perceiver README: tables are read from us_somo/etc, not copied

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


Compare: https://github.com/ehb54/ultrascan3/compare/579add03864b%5E...eb57f12bd7b3

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