Repository navigation
Conversation
awjdean
force-pushed
the
fix-overlay-reflection
branch
from
October 23, 2026 10:56
344d604 to
6ff76c0
Compare
awjdean
marked this pull request as ready for review
October 23, 2026 10:58
This was referenced Oct 23, 2026
awjdean
marked this pull request as draft
October 23, 2026 13:32
_overlayPoints lines a residue template up with atoms that are already present. addMissingAtoms uses it to copy missing atoms from the template, and addMissingResidues uses it to orient each residue it builds. It uses the Kabsch algorithm but left out the step that rules out reflections. When the atoms being lined up are nearly flat, for example just N, CA, C and O, the best fit is often a reflection, and the new atoms then make an L amino acid into its D mirror image. If the fit would be a reflection, flip the sign of the column of u that goes with the smallest singular value. This gives the best fit that is a true rotation. Fits that were already rotations are unchanged. The new unit test builds a mirror image whose best proper rotation is known exactly, so it checks the whole correction rather than only the sign of the determinant. The other new test deletes every alanine CB in 1BHL and checks that each one comes back with its original handedness. Both fail without the fix. Part of openmm#352, which proposed this fix. Co-authored-by: Sahil Athalye <89952559+Sahil-Athalye@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
awjdean
force-pushed
the
fix-overlay-reflection
branch
from
October 23, 2026 15:47
43eea08 to
9b6c8f2
Compare
awjdean
marked this pull request as ready for review
October 23, 2026 16:46
awjdean
marked this pull request as draft
October 23, 2026 16:47
awjdean
marked this pull request as ready for review
October 23, 2026 17:21
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes a bug where _overlayPoints could reflect a residue template when placing missing atoms (as described in #352).
AI-generated material
Part of #352. This is the first of the two fixes @Sahil-Athalye proposed there. During review I rewrote their code in the textbook form shown below; it gives exactly the same results. I added the tests and the measurements below.
The problem
When a residue is missing atoms,
addMissingAtoms()takes a template of that residue, lines it up with the atoms that are present, and copies the missing atoms from the template._overlayPointsdoes the lining up._overlayPointsis meant to return a rotation, but sometimes it returns a mirror image (a reflection) instead. A mirrored template turns an L amino acid into a D amino acid. This happens most often when the atoms being lined up lie almost in one plane, for example a residue that only has N, CA, C and O left.The fix
_overlayPointsuses the Kabsch algorithm, which finds the best fit with an SVD. The full algorithm has one extra step that rules out mirror images, and this code was missing it. This PR adds that step:dis +1 when the best fit is already a rotation, and −1 when it would be a mirror image. When it is −1, the code flips the sign of the last column ofu, which gives the best fit that is a real rotation. The last column is the one to flip because doing so changes the fit the least. Whendis +1 nothing changes, so fits that were already rotations stay exactly the same.Kabsch covers this step in his 1978 follow-up paper (Acta Cryst. A34, 827–828). For a quick summary, see the optimal rotation section of the Wikipedia article. It describes the same step: compute
d = det(U)·det(V), then putdiag(1, 1, d)between the two SVD factors. The code transposes the result at the end because PDBFixer'sRis the transpose of the matrixHused there.Tests
Both new tests pass with this PR. On current master the CB test fails, and so does the mirrored case of the unit test.
test_overlayPointsRecoversRotationtests_overlayPointsdirectly. It turns a thin slab of points by a known rotation and checks that_overlayPointsrecovers exactly that rotation and the matching translation. In the "mirrored" case the slab is also mirrored first, so a reflection would fit best; the slab's shape means the best true rotation is still known exactly. On master that case returns a reflection instead. The "rotated" case also passes on master and checks ordinary fits.test_addedCBChiralitytests the wholeaddMissingAtoms()path. It records the handedness of the 14 alanines in 1BHL, deletes every alanine CB, adds them back, and checks that each alanine has the same handedness as before. On master, 10 of the 14 come back as D.Follow-ups
The test and docstring tidy-ups from earlier versions of this PR will come as separate PRs, so this one now contains only the fix.
How much it helps
I removed the side chain of each residue in 1BHL, one residue at a time (120 residues), and rebuilt it with
addMissingAtoms(seed=1). Then I counted how many residues had the CB on the wrong side:Some residues get worse. On master their CB is placed almost flat, and the minimization happens to push it to the correct side. With this PR it is placed on the wrong side (for the backbone O reason below) and stays there. In my run this happened to three residues: THR112, THR115 and ARG187.
Removing all the side chains at once gives a different result. Placement improves by the same amount, but the final output doesn't: 47–66 residues end up wrong on master, and 55–62 with this PR (seeds 1, 42 and 777). The extra errors come from the minimization step, described below. #352 reports the same thing for loop building.
I measured these numbers on Linux (OpenMM 8.6.1, CPU platform). Other machines give slightly different numbers, mostly because the minimization doesn't come out exactly the same. On macOS with the same versions, I get 48 and 22 after placement, 39 and 19 in the final output, and 58–67 and 54–58 when removing all the side chains at once. The pattern is the same, but 12 residues get worse instead of 3. Half of those 12 are only barely on the correct side on master, so they are almost flat there too.
What this PR does not fix
soft.xml. If new atoms end up too close together, it also runs a short burst of molecular dynamics. Nothing insoft.xmlkeeps a carbon's handedness. Mixed chirality residues produced when loop building #352 proposes a second patch that adds a chirality restraint during minimization. That is a bigger design decision, so it is left for a separate PR.Testing
pytest pdbfixer: 27 passed (OpenMM 8.6.1, NumPy 2.5.4, Python 3.13, macOS arm64).