Fix residue naming by hannahbaumann · Pull Request #2042 · OpenFreeEnergy/openfe

hannahbaumann · 2026-06-25T13:59:26Z

Checklist

All new code is appropriately documented (user-facing code must have complete docstrings).
Added a news entry, or the changes are not user-facing.
Ran pre-commit: you can run pre-commit locally or comment on this PR with pre-commit.ci autofix.

Manual Tests: these are slow so don't need to be run every commit, only before merging and when relevant changes are made (generally at reviewer-discretion).

GPU integration tests
example notebook testing
packaging tests: run this for any large feature PRs or PRs that add test data.

Developers certificate of origin

I certify that this contribution is covered by the MIT License here and the Developer Certificate of Origin at https://developercertificate.org/.

hannahbaumann · 2026-06-29T08:12:43Z

pre-commit.ci autofix

for more information, see https://pre-commit.ci

codecov · 2026-06-29T10:21:36Z

Codecov Report

❌ Patch coverage is 99.20635% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 90.69%. Comparing base (97bef39) to head (c68b88e).

Files with missing lines	Patch %	Lines
...s/protocols/openmm_rfe/test_hybrid_top_protocol.py	98.63%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2042      +/-   ##
==========================================
- Coverage   95.01%   90.69%   -4.33%     
==========================================
  Files         212      213       +1     
  Lines       20572    20693     +121     
==========================================
- Hits        19546    18767     -779     
- Misses       1026     1926     +900

Flag	Coverage Δ
fast-tests	`90.69% <99.20%> (?)`
slow-tests	`?`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

hannahbaumann · 2026-06-29T12:10:12Z

pre-commit.ci autofix

for more information, see https://pre-commit.ci

IAlibay

This looks good thanks! - couple of things to fix but otherwise should be fine.

After this PR, will you be able to do the same for PlainMD, AFE, and SepTop?

IAlibay · 2026-07-01T11:23:58Z

+
+**Changed:**
+
+* Small molecules in RelativeHybridTopology topologies (including the output PDB) are now named LIG (alchemical ligand) and CF1, CF2… (cofactors) instead of UNK.


What about if a residue name was already assigned?

Added something!

IAlibay · 2026-07-01T11:24:56Z

I would call this "offmolecule_utils" so that we know it's utilities for openff molecules and not rdkit molecules

IAlibay · 2026-07-01T11:26:43Z

+    assert set(lig.indices).isdisjoint(cof.indices)
+
+
+def test_get_metadata_inconsistent_warns(caplog):


Can you move this and the next one to test_openmmutils instead?

IAlibay · 2026-07-01T13:19:37Z


        try:
-            data = rmsd.gather_rms_data(pdb_file, trj_file)
+            data = rmsd.gather_rms_data(pdb_file, trj_file, ligand_selection="resname LIG")


This will fail is someone provides their own residue names ahead of time (which is something we should encourage - i.e. power users should be rewarded not punished).

There are two potential solutions here:

(lowest cost / temporary fix) We just store the alchemical residue names in the output of the setup unit and then fetch them in the analysis unit.

(higher cost / more complicated) We pass in the alchemical components & the comp resids through all the way to the analysis unit and then extract the relevant residue names from that.

For now, I would suggest we just pass the residue names and have the residue name kwarg be optional and/or have a default of LIG, that way we don't break backwards compatibility.

We can clean up after the fact.

Note that for hybrid toplogy, it's technically possible for both endstate molecules to have different names, so we should check that it works properly.

I think a 3rd option might be best, where we do away with tracking the residue names and just keep the alchemical atom indices around. This would mean moving away from the gather_rms_data function and using the new openfe-analaysis API but we plan on doing that anyway, so this could be a good time to do it?

This would fix the case pointed out above and the fact that if a user sets the alchemical ligands and the cofactors to have the same residue name (LIG), we will still have the same issue in the analysis unit.

I wouldn't consider the above blocking though we could have this as a temp fix and move to indices when we change the analysis for this protocol?

Yes, I like the 3rd option as the long term fix, for now I went ahead with option 1, but happy to change it to a longer term fix.

Re two ligands different residue names: I tested this out and it assigns the residue name from the stateA ligand to the hybrid topology (in the HTF). We could still check for both residue names since it wouldn't hurt, but may also confuse the user?

I think a 3rd option might be best, where we do away with tracking the residue names and just keep the alchemical atom indices around.

This somewhat fits within the longer term idea of switching comp_resids to just comp_indices (where you track the indices of each component in the system). However, that's a lot bigger lift.

I don't mind just tracking the alchemical indices in the setup results - that's something we nearly already do in the AFE Protocol. But yeah, for the sake of incremental PRs = faster velocity, I would vote for the quick fix now, then the medium/long term fix after.

Co-authored-by: Irfan Alibay <IAlibay@users.noreply.github.com>

jthorton · 2026-07-02T09:35:21Z

Not blocking: Does a user have a way of setting the residue_name via a CLI input? It seems like the atom metadata fields are not preserved on writing an openff molecule to file?

hannahbaumann · 2026-07-02T09:53:30Z

pre-commit.ci autofix

for more information, see https://pre-commit.ci

github-actions · 2026-07-02T09:54:44Z

No API break detected ✅

View workflow run

Griffe output

$ griffe check "openfe" -s src --no-inspection --no-color --verbose -a origin/main

$ griffe check "openfecli" -s src --no-inspection --no-color --verbose -a origin/main

IAlibay · 2026-07-02T10:26:00Z

Not blocking: Does a user have a way of setting the residue_name via a CLI input? It seems like the atom metadata fields are not preserved on writing an openff molecule to file?

I had forgotten that this was still an issue...

The problem is that residue name is a per atom PDBResidueInfo property in rdkit molecules, and a) gufe SMCs don't serialize that, and b) it doesn't get written out when you write out an SDF file. See: OpenFreeEnergy/gufe#327

Initial change of lig and cofactor resname

e7882f0

jameseastwood assigned hannahbaumann Jun 25, 2026

Merge branch 'main' into fix_residue_naming

cb4ece2

[pre-commit.ci] auto fixes from pre-commit.com hooks

a32cf02

for more information, see https://pre-commit.ci

hannahbaumann mentioned this pull request Jun 29, 2026

Fix ligand selection when cofactors share resname UNK OpenFreeEnergy/openfe_analysis#119

Open

Fix tests

369f9d5

hannahbaumann added 2 commits June 29, 2026 13:48

Add news entry

69a6a08

Add more tests

2609bc4

[pre-commit.ci] auto fixes from pre-commit.com hooks

0844937

for more information, see https://pre-commit.ci

hannahbaumann changed the title ~~[WIP] Fix residue naming~~ Fix residue naming Jun 29, 2026

hannahbaumann requested review from IAlibay and jthorton June 29, 2026 12:14

hannahbaumann linked an issue Jun 29, 2026 that may be closed by this pull request

Change ligand and cofactor residue names in the topology #2050

Open

hannahbaumann and others added 2 commits June 29, 2026 14:58

Merge branch 'main' into fix_residue_naming

91fde04

Merge branch 'main' into fix_residue_naming

d7a36cd

IAlibay requested changes Jul 1, 2026

View reviewed changes

Update src/openfe/tests/protocols/openmm_rfe/test_hybrid_top_protocol.py

11b9c2c

Co-authored-by: Irfan Alibay <IAlibay@users.noreply.github.com>

Address review comments

12b9840

[pre-commit.ci] auto fixes from pre-commit.com hooks

c68b88e

for more information, see https://pre-commit.ci

jameseastwood assigned IAlibay and hannahbaumann and unassigned hannahbaumann Jul 2, 2026


		Changed:

		* Small molecules in RelativeHybridTopology topologies (including the output PDB) are now named LIG (alchemical ligand) and CF1, CF2… (cofactors) instead of UNK.

		assert set(lig.indices).isdisjoint(cof.indices)


		def test_get_metadata_inconsistent_warns(caplog):

Uh oh!

Conversation

hannahbaumann commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Developers certificate of origin

Uh oh!

hannahbaumann commented Jun 29, 2026

Uh oh!

codecov Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

hannahbaumann commented Jun 29, 2026

Uh oh!

IAlibay left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jthorton commented Jul 2, 2026

Uh oh!

hannahbaumann commented Jul 2, 2026

Uh oh!

github-actions Bot commented Jul 2, 2026

Uh oh!

IAlibay commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hannahbaumann commented Jun 25, 2026 •

edited

Loading

codecov Bot commented Jun 29, 2026 •

edited

Loading