User guide updates membrane by hannahbaumann · Pull Request #1933 · OpenFreeEnergy/openfe

hannahbaumann · 2026-04-09T12:51:36Z

Adds ProteinMembraneComponent explanation, including example code of creating a ChemicalSystem for the complex leg of protein-membrane simulations.
Adds _adaptive_settings to the user guide
Adds mentioning of the differences in defining ChemicalSystems in ABFE and SepTop vs HybTop protocols.
Update CLI user guide to add the --protein-membrane flag

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/.

…y/openfe into membrane_prototype

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

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

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

github-actions · 2026-04-09T12:52:01Z

No API break detected ✅

IAlibay

I think we've historically been missing some exposition here, so my question would be if it would be reasonable to add it or if it would end up being too much work (or if it should be elsewhere)?

IAlibay · 2026-04-15T12:17:57Z

+.. warning::
+
+  The ``_adaptive_settings()`` method is experimental and subject to change.


This is great. As a small nit, it might be good to move that to the top so that it's the first thing folks read.

IAlibay · 2026-04-15T12:20:14Z

+For some protocols, such as :class:`.SepTopProtocol` and :class:`.AbsoluteBindingProtocol`, a single
+:class:`.ChemicalSystem` is used to represent both legs of the thermodynamic cycle (complex and solvent).
+This is in contrast to the :class:`.RelativeHybridTopologyProtocol`, where each leg is defined by
+separate :class:`.ChemicalSystem`\s.


Maybe put this in a .. note: section? It would be good to say that this is subject to change too.

IAlibay · 2026-04-15T12:46:12Z

+  # ligand_B + solvent
  ligand_B_solvent = openfe.ChemicalSystem(components={'ligand': ligand_B, 'solvent': solvent})

+For a protein-membrane complex, the `ligand_A_complex` would instead use a


Thinking about it a bit more - will the code changes work for just any ExplicitPDBComponent? I.e. could this be reduced to just "if you explicitly defined the system components, e.g. with a protein membrane" and then "here is an example using a ProteinMembraneComponent".

Changed this!

IAlibay · 2026-04-15T12:56:54Z

 2. components can be reused to compose different systems.
 3. :class:`.Protocol`\s can have component-specific behavior. E.g. different force fields for each component.

+When dealing with membrane-protein systems, the protein is represented using an explicitly solvated


The content of what is being added looks good, but there's a "missing link".

What I think we've been missing (since before membrane support) is the idea that the Components are composable. What would you think about something like this:

These Components are additively added into a ChemicalSystem, which will define the chemical composition of the simulated system.

For a conventional protein-ligand complex in water, this would look like [add protein, small and solvent components]

Some mention that the protein component handles crystallographic waters and also can define SSBONDs via the CONECT records.

For membrane proteins: what you have here

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

codecov · 2026-04-15T14:14:07Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (membrane_prototype@d6bce0f). Learn more about missing BASE report.

Additional details and impacted files

@@                  Coverage Diff                  @@
##             membrane_prototype    #1933   +/-   ##
=====================================================
  Coverage                      ?   90.57%           
=====================================================
  Files                         ?      206           
  Lines                         ?    18757           
  Branches                      ?        0           
=====================================================
  Hits                          ?    16990           
  Misses                        ?     1767           
  Partials                      ?        0

Flag	Coverage Δ
fast-tests	`90.57% <ø> (?)`

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

☔ View full report in Codecov by Sentry.
📢 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.

jthorton · 2026-04-15T15:15:40Z


 Examples of components include:

 * :class:`.ProteinComponent`: an entire biological assembly, typically the contents of a PDB file.


we could hint here that the ProteinComponent can also contain crystal waters.

Added this!

jthorton · 2026-04-15T15:16:44Z

+
+   Box vectors can be estimated from the atomic coordinates in the PDB file.
+
+   Caveat: This approach can be inaccurate if the PDB comes from a previous simulation and some atoms are positioned in periodic images.


I would use a warning box for this to make it clear this should be a last resort.

Added a warning box.

hannahbaumann and others added 30 commits October 9, 2025 16:36

Membrane support prototype start

4e6617e

Merge branch 'main' into membrane_prototype

ac9862a

Point to corresponding branch in gufe

8ea145a

Merge branch 'membrane_prototype' of https://github.com/OpenFreeEnerg…

587a1bf

…y/openfe into membrane_prototype

Merge branch 'main' into membrane_prototype

b7c63d6

Make plain md protocol membrane ready

24f3d58

Merge branch 'membrane_prototype' of https://github.com/OpenFreeEnerg…

617ac8c

…y/openfe into membrane_prototype

Merge branch 'main' into membrane_prototype

7fd5ca9

Dry run for membrane system for debugging

18db828

Merge branch 'membrane_prototype' of https://github.com/OpenFreeEnerg…

1ee6fd7

…y/openfe into membrane_prototype

Merge branch 'main' into membrane_prototype

238b36b

Merge branch 'main' into membrane_prototype

6945805

Merge branch 'membrane_prototype' of https://github.com/OpenFreeEnerg…

646ebbe

…y/openfe into membrane_prototype

Add box vectors to modeller

abf0007

Adapt htf to allow for membrane barostat

96fa49a

Fix test

b70e5b2

Add test files membrane

481ff35

Merge branch 'main' into membrane_prototype

4d28281

Change test to cpu

eff1958

Merge branch 'membrane_prototype' of https://github.com/OpenFreeEnerg…

1456a99

…y/openfe into membrane_prototype

Merge branch 'main' into membrane_prototype

0cdde55

Prints for debugging

5bfd1c9

Some more debugginh stuff, remove later

ce29130

Merge branch 'main' into membrane_prototype

c53fd60

Small fix

5c313b1

Merge conflicts

9dce0e0

Temporarily use branches for openmmtools and openmmforcefield

080d93e

Small fixes

48a7844

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

b492de0

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

support membrane in gather

2913994

hannahbaumann and others added 7 commits April 9, 2026 13:44

Merge conflicts

d8177ac

Update src/openfe/tests/protocols/openmm_abfe/test_abfe_protocol.py

427ce2b

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

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

0662d60

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

Fix merge conflict

0a0f29c

Forgot another one

5943aed

Move box roundtrip to _pre_equilibrate

d6bce0f

First go at modifying the user guide for membranes and ABFE and SepTop

7ed71b0

hannahbaumann changed the base branch from main to membrane_prototype April 9, 2026 12:51

some small fixes

002d321

atravitz added this to the 1.11.0 milestone Apr 9, 2026

hannahbaumann added 6 commits April 10, 2026 10:24

Add adaptive_settings to user guide

2411b5d

Add example code loading protein membrane

87735e9

Add box vector explanation

d1b70a1

Some smaller changes

c54c699

Make adaptive settings subheading

02e7a93

Some more changes

4935166

hannahbaumann changed the title ~~[WIP] User guide updates membrane~~ User guide updates membrane Apr 10, 2026

hannahbaumann requested review from IAlibay and jthorton April 10, 2026 09:10

Add warning adaptive settings

52b8e3c

IAlibay requested changes Apr 15, 2026

View reviewed changes

Update docs/guide/setup/defining_protocols.rst

eea1967

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

jthorton reviewed Apr 15, 2026

View reviewed changes

hannahbaumann added 3 commits April 16, 2026 14:08

Addressing review comments

60678df

some more updates

7babe21

Test out subheadings

7d5750b

Base automatically changed from membrane_prototype to main April 16, 2026 18:06

		.. warning::

		The ``_adaptive_settings()`` method is experimental and subject to change.


		Examples of components include:

		* :class:`.ProteinComponent`: an entire biological assembly, typically the contents of a PDB file.


		Box vectors can be estimated from the atomic coordinates in the PDB file.

		Caveat: This approach can be inaccurate if the PDB comes from a previous simulation and some atoms are positioned in periodic images.

Conversation

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

Uh oh!

Developers certificate of origin

Uh oh!

github-actions bot commented Apr 9, 2026

Uh oh!

IAlibay left a comment

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!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hannahbaumann commented Apr 9, 2026 •

edited

Loading

codecov bot commented Apr 15, 2026 •

edited

Loading