Skip to content

Jflat06/opt h backprop - #649

Open
jflat06 wants to merge 7 commits into
masterfrom
jflat06/optH-backprop
Open

jflat06 wants to merge 7 commits into
masterfrom
jflat06/optH-backprop

Conversation

@jflat06

@jflat06 jflat06 commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Summary

Makes hydrogen optimization (optH) differentiable and turns it on by default for atom37 inputs. A new option, backprop_compatible_rebuild, says whether the caller needs gradients through pose construction.

Features

  • Differentiable optH (tmol/io/details/_optimize_hydrogens.py): the packer still chooses proton chis (and NHQ flips) without gradients. The moved atoms are then rebuilt from the input coordinates with the leaf-atom builder, using the dihedrals the packer chose. Optimized hydrogens therefore carry gradients to the atoms they are built from. The rebuild matches the packer's placement to within 1e-3 Å.
  • backprop_compatible_rebuild:
    • True: optH runs differentiably. A residue missing heavy atoms raises a ValueError naming the residue and its atoms, because the packer would build them without gradients.
    • False: master's behavior, a single no-grad packing run that builds missing heavy atoms and optimizes hydrogens.
  • Optional proton-chi minimization (optH_minimize / opt_h_minimize): a torsion-space minimization of proton chis after packing.

Interface changes

  • New option backprop_compatible_rebuild on:
    • pose_stack_from_atom_array / pose_stack_from_file: defaults to True only when atom37_coords is given;
    • pose_stack_from_atom37, pose_stack_from_atom37_and_topology, pose_stack_from_canonical_aa_atom37 and PreparedAtom37PoseBuilder.__call__: defaults to True.
  • optH on by default for atom37 inputs: no_optH=False and opt_h=True. Pass no_optH=True / opt_h=False for the previous behavior.
  • Missing heavy atoms in atom37 inputs now raise by default. Pass backprop_compatible_rebuild=False to have them packed as before.
  • pose_stack_from_canonical_aa_atom37 gains no_optH and now goes through _pose_stack_from_canonical_form_and_context like the other atom37 entry points.
  • _build_missing_sidechains gains flip_NHQ (default True).
  • The native gen_pose_leaf_atoms op takes an optional per-atom dihedral override (NaN or an empty tensor keeps the stored value).
  • The coincident-atom check is removed (tmol/io/_input_geometry.py).

Design decisions

  • Raise rather than return bad gradients. Packed heavy atoms have no gradient, so a caller asking for gradients gets an error instead of a silently broken chain of derivatives.
  • No ASN/GLN/HIS flips on atom37 paths. Block types, heavy atoms and the atom layout stay exactly the input's. This keeps the cached topology and atom mapping valid. Given atom37 coordinates, hydrogens included, keep their input values through master's copy-back. File loads still flip.
  • optH stays in _pose_stack_from_canonical_form_and_context, which owns the build context and its optH score function.
  • Packer sampling rate and min options. Hydrogens are now sampled every 10 degrees instead of every 20, and the optH minimizer uses atol=0.05 and patience=2 to increase performance with minimal impact on resulting score.

jflat06 and others added 7 commits November 9, 2026 14:38
Hydrogen optimization used to run after construction as a packing pass,
which detached coordinates; the atom37 path then copied finite inputs
back, so optimized hydrogens carried no gradient. optH now runs inside
_pose_stack_from_canonical_form in two steps:

1. Pack proton chis without gradients and measure the dihedral each
   moved hydrogen has in its build frame.
2. Rebuild those hydrogens from the input coordinates with the leaf-atom
   builder, passing the measured dihedrals.

Gradients reach optimized hydrogens through the atoms they are built
from. The prepared atom37 builder uses the same path.

- gen_pose_leaf_atoms takes an optional per-atom dihedral that replaces
  the stored phi for atoms built from their primary ancestors; NaN keeps
  the stored value. Exposed as _build_coords_from_icoors(dihedrals=...).
- Loading no longer performs NHQ flips: ASN/GLN/HIS keep their input
  conformation and histidine its tautomer.
- optH_minimize (opt_h_minimize on the prepared builder) minimizes the
  proton chis in torsion space after packing.
- rebuild_hydrogens (default False): when False, hydrogens given in the
  input keep their coordinates and optH skips residues whose proton-chi
  hydrogens are given; when True, all buildable hydrogens are rebuilt
  from ideal geometry and then optimized.

Poses with missing heavy atoms or unjoined ligand fragments still pack
optH together with side-chain building, without gradients through the
optimized hydrogens.

Validated on CPU only; CUDA was unavailable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…37 optH on

Hydrogen optimization now matches master, except that the atoms it places
stay differentiable:

- File and AtomArray loads pack every residue OptH supports, with
  ASN/GLN/HIS flips, and every hydrogen optH moves takes its placement.
  A flipped side chain is rebuilt from its frame with the packer's
  dihedrals (matching the packer to ~1e-5 A), and a histidine whose
  tautomer changes takes the packed block type, with the atom mapping
  updated to follow.
- Atom37 paths do not flip, so heavy atoms, block types and the atom
  layout stay the input's. Input hydrogens keep their coordinates, which
  master achieved by copying finite inputs back after packing; only
  missing hydrogens take optH's placement.

Interface changes:

- _pose_stack_from_canonical_form gains opth_flip_NHQ (default True) and
  opth_keep_input_hydrogens (default False). The atom37 paths turn the
  first off and the second on.
- _build_missing_sidechains gains flip_NHQ (default True, as on master).
- optH is on by default for atom37: pose_stack_from_atom37 and
  pose_stack_from_atom37_and_topology default to no_optH=False, and
  PreparedAtom37PoseBuilder to opt_h=True. pose_stack_from_canonical_aa_atom37
  gains no_optH (default False) and takes its score function from a
  cached atomworks build context.

Removed:

- The rebuild_hydrogens option.
- The coincident-atom repair: tmol/io/_input_geometry.py and its
  _rebuild_coincident_hydrogens. Hydrogens on their bonded parent are no
  longer rebuilt, and coincident heavy atoms no longer raise.

Tests:

- New tests cover flips, the atom mapping, atom37 keeping input
  hydrogens, master-equivalent file loads and the canonical AA atom37
  default.
- Master's histidine ring-flip test is restored; the coincident-atom
  tests are removed.
- Added a whole-load benchmark comparing no optH, optH, and optH with
  minimization.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
OptH flips ASN/GLN/HIS again on file loads, so the comment on the terms the
optH score function zeroes goes back to master's wording: OptH changes
proton chis and terminal NHQ groups.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ontext

_pose_stack_from_canonical_form is back to master's version: it builds
geometry only and takes no score function or optH options. The
differentiable optH now runs in _pose_stack_from_canonical_form_and_context,
which owns the build context and its optH score function.

- optH runs after construction, and after ligand fragments are joined,
  whenever no block is missing heavy atoms. Fragmented ligand poses now get
  the differentiable optH too.
- On file loads it flips ASN/GLN/HIS. When a histidine is retyped,
  _remap_atom_mapping points the returned atom mapping at the new layout.
- On atom37 paths it does not flip, and master's copy-back of finite input
  coordinates follows, so given hydrogens keep their coordinates with
  gradients. This replaces the given-hydrogen mask, which is removed from
  _optimize_hydrogens and from the prepared builder's pose_from_canonical.
- The prepared builder's replay optimizes and then copies inputs back, as
  master did, now with the differentiable optH.
- pose_stack_from_canonical_aa_atom37 calls construction directly, so it
  runs optH and the copy-back itself. It takes optH_minimize and
  packer_seed as explicit options.

The construction-level optH tests now go through
_pose_stack_from_canonical_form_and_context.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rm_and_context

pose_stack_from_canonical_aa_atom37 called _pose_stack_from_canonical_form
directly, so it carried its own copy of the optH and input copy-back logic.
It now hands its canonical form to _pose_stack_from_canonical_form_and_context
with the cached atomworks build context, like every other atom37 entry point.

optH_minimize and packer_seed now pass through **kwargs, as on the other
atom37 paths, instead of being explicit arguments. The path also takes on the
other atom37 defaults: missing side-chain heavy atoms are packed instead of
raising, and the geometric disulfide and cyclic-closure searches are off unless
requested.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
backprop_compatible_rebuild tells pose construction that the caller will use
gradients through it. It is on _pose_stack_from_canonical_form_and_context
and every entry point that calls it.

- True: optH rebuilds the atoms it moves differentiably from the input atoms
  (_optimize_hydrogens). A residue missing heavy atoms raises ValueError,
  naming each residue and its missing atoms: only the packer can build them,
  and packed coordinates carry no gradient.
- False: master's path, one packing run without gradients that builds
  missing heavy atoms and optimizes hydrogens. It is moved into
  _pack_after_construction.

Atom37 paths copy finite input coordinates back either way.

Defaults: True for pose_stack_from_atom37_and_topology, pose_stack_from_atom37,
pose_stack_from_canonical_aa_atom37 and PreparedAtom37PoseBuilder; for
pose_stack_from_atom_array, pose_stack_from_file and
_pose_stack_from_canonical_form_and_context, True with atom37_coords and False
otherwise. File loads therefore behave as on master again. The prepared
builder's replay runs the differentiable optH when set, and master's packing
run otherwise.

Also:
- pose_from_canonical calls _gen_pose_leaf_atoms directly again, as on
  master, passing an empty tensor for the new dihedral argument.
- Hydrogen docstrings now say that without optH, input hydrogens keep their
  input positions and missing ones are built from ideal geometry.

Tests: the atom37 and file paths raise on missing heavy atoms with the option
set and build without it; the packed atoms carry no gradient while given atoms
do. The file-path tests of differentiable optH now set the option.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- SER/THR proton chis are sampled every 10 degrees instead of 20; TYR's
  expansions around 0/180 become +/-10 and +/-20. d_amino_acids.yaml is
  regenerated from chemical.yaml to match. On 50 PDB structures (GPU),
  10-degree sampling lowered the median total score by 0.70 relative to
  20 degrees, for about 20 ms more optH time per structure.
- The optional proton-chi minimization (optH_minimize, off by default)
  uses atol=0.05, patience=2 instead of the LBFGS_Armijo defaults
  (0.01, 5). This cut its time from 58 to 32 ms per structure, raising
  the median total score by 0.03 (at most 0.14) relative to the defaults.
- gold_repack_1ubq_rotamers.pdb is regenerated for the added rotamers;
  other rotamers differ only in last-digit rounding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
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