Skip to content

Stop _overlayPoints from returning a mirror image - #355

Open
awjdean wants to merge 1 commit into
openmm:masterfrom
awjdean:fix-overlay-reflection
Open

awjdean wants to merge 1 commit into
openmm:masterfrom
awjdean:fix-overlay-reflection

Conversation

@awjdean

@awjdean awjdean commented Oct 23, 2026 •

Copy link
Copy Markdown

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. _overlayPoints does the lining up.

_overlayPoints is 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

_overlayPoints uses 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:

(u, _, vh) = lin.svd(R)
d = np.sign(lin.det(u)*lin.det(vh))
rotate = np.dot(np.dot(u, np.diag([1, 1, d])), vh).transpose()

d is +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 of u, 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. When d is +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 put diag(1, 1, d) between the two SVD factors. The code transposes the result at the end because PDBFixer's R is the transpose of the matrix H used 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_overlayPointsRecoversRotation tests _overlayPoints directly. It turns a thin slab of points by a known rotation and checks that _overlayPoints recovers 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_addedCBChirality tests the whole addMissingAtoms() 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:

Residues with the CB on the wrong side master this PR
After placing the template, before minimization 47 22
In the final output 40 17

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

  • The minimization can still flip a residue. After placing new atoms, PDBFixer minimizes the energy using soft.xml. If new atoms end up too close together, it also runs a short burst of molecular dynamics. Nothing in soft.xml keeps 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.
  • The backbone O can still pull the CB to the wrong side. The 22 wrong placements that remain are real rotations, not mirror images. The fit includes the backbone O, whose position depends on the residue's ψ angle, and the template's ψ is often different. The best fit over N, CA, C and O (0.5–0.6 Å RMSD) can then tilt the template enough to put the CB on the wrong side. Fitting on N, CA and C alone puts the CB on the correct side in all 22 cases. This is tracked in Added side chains can face the wrong way because the template fit includes the backbone O #356.

Testing

  • pytest pdbfixer: 27 passed (OpenMM 8.6.1, NumPy 2.5.4, Python 3.13, macOS arm64).

_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
awjdean force-pushed the fix-overlay-reflection branch from 43eea08 to 9b6c8f2 Compare October 23, 2026 15:47
@awjdean
awjdean marked this pull request as ready for review October 23, 2026 16:46
@awjdean
awjdean marked this pull request as draft October 23, 2026 16:47
@awjdean
awjdean marked this pull request as ready for review October 23, 2026 17:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant