OpenFreeEnergy · IAlibay · Sep 23, 2025 · Jan 10, 2025 · Jan 13, 2025 · Jan 13, 2025
diff --git a/docs/Makefile b/docs/Makefile
@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?= -W --keep-going
+SPHINXOPTS    ?= -v -W --keep-going
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

diff --git a/docs/conf.py b/docs/conf.py
@@ -66,7 +66,7 @@
     "openeye": ("https://docs.eyesopen.com/toolkits/python/", None),
     "mdtraj": ("https://www.mdtraj.org/1.9.5/", None),
     "openff.units": ("https://docs.openforcefield.org/projects/units/en/stable", None),
-    "gufe": ("https://gufe.readthedocs.io/en/latest/", None),
+    "gufe": ("https://gufe.openfree.energy/en/latest/", None),
 }
 
 autoclass_content = "both"
@@ -102,8 +102,10 @@
 ]
 
 autodoc_mock_imports = [
+    "MDAnalysis",
     "matplotlib",
     "mdtraj",
+    "openfe_analysis",
     "openmmforcefields",
     "openmmtools",
     "pymbar",

diff --git a/docs/guide/protocols/img/septop_cycle.png b/docs/guide/protocols/img/septop_cycle.png
diff --git a/docs/guide/protocols/index.rst b/docs/guide/protocols/index.rst
@@ -8,4 +8,5 @@ Details on the theory and behaviour of different Protocols are listed here.
 .. toctree::
    relativehybridtopology
    absolutesolvation
+   septop
    plainmd
diff --git a/docs/guide/protocols/relativehybridtopology.rst b/docs/guide/protocols/relativehybridtopology.rst
@@ -1,3 +1,5 @@
+.. _userguide_relative_hybrid_topology_protocol:
+
 Relative Hybrid Topology Protocol
 =================================
 

diff --git a/docs/guide/protocols/septop.rst b/docs/guide/protocols/septop.rst
@@ -0,0 +1,131 @@
+Separated Topologies Protocol
+=============================
+
+Overview
+--------
+
+The :class:`SepTopProtocol <.SepTopProtocol>` [1]_, [2]_ calculates the difference in binding free energy between two ligands.
+This protocol essentially performs two absolute binding free energy calculations simultaneously in opposite directions,
+by (alchemically) inserting one ligand into the binding site, while removing the other ligand at the same time.
+In contrast to the :ref:`RelativeHybridTopologyProtocol <userguide_relative_hybrid_topology_protocol>`, the two ligand topologies are
+completely separate (meaning there is no common core), making atom mapping unnecessary and allowing transformations between chemically diverse ligands.
+
+The relative binding free energy is calculated through a thermodynamic cycle by transforming one ligand into the other ligand
+both in the solvent and in the binding site.
+
+Restraints are required to keep the weakly
+coupled and fully decoupled ligand in the binding site region and thereby reduce the phase
+space that needs to be sampled. In the :class:`SepTopProtocol <.SepTopProtocol>`
+we apply orientational, or Boresch-style, restraints, as described below.
+
+In this cycle, the interactions of one molecule are turned off while simultaneously turning on interactions of the other molecule both in the solvent and complex phases.
+The relative binding free energy is then obtained via summation of free energy differences along the thermodynamic cycle.
+
+.. figure:: img/septop_cycle.png
+   :scale: 50%
+
+   Thermodynamic cycle for the SepTop free energy protocol.
+
+Scientific Details
+------------------
+
+Orientational restraints
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Orientational, or Boresch-style, restraints are automaticallly (unless manually specified) applied between three protein and three ligand atoms using one bond,
+two angle, and three dihedral restraints. Reference atoms are picked based on different criteria, such as the root mean squared
+fluctuation of the atoms in a short MD simulation, the secondary structure of the protein, and the distance between atoms, based on heuristics from Baumann et al. [2]_.
+
+Partial annihilation scheme
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the :class:`SepTopProtocol <.SepTopProtocol>` the coulombic interactions of the molecules are fully turned off (annihilated) in the respective non-interacting end states.
+The Lennard-Jones interactions are instead decoupled, meaning the intermolecular interactions are turned off, keeping the intramolecular Lennard-Jones interactions.
+
+The lambda schedule
+~~~~~~~~~~~~~~~~~~~
+
+Molecular interactions are modified along an alchemical path using a discrete set of lambda windows.
+For the transformation of ligand A to ligand B in the binding site, the following steps are carried out, starting with ligand A being fully interacting in the binding site while ligand B is decoupled.
+
+1. Insert the non-interacting dummy ligand B into the binding site and restrain it using orientational restraints. The contribution of the restraints is calculated analytically.
+2. Turn on the van der Waals (vdW) interactions of ligand B while also turning on orientational restraints on ligand A.
+3. Turn on the electrostatic interactions of ligand B while at the same time turning off the electrostatics of ligand A.
+4. Turn off vdW interactions of ligand A while simultaneously releasing restraints on ligand B.
+5. Release the restraints of the now dummy ligand A analytically and transfer the ligand into the solvent.
+
+The lambda schedule in the solvent phase is similar to the one in the complex, except that a single harmonic distance restraint is
+applied between the respective central atom in the two ligands to keep the ligands apart while doing the alchemical transformation.
+A soft-core potential from Beutler et al. [3]_ is applied to the Lennard-Jones potential to avoid instablilites in intermediate lambda windows.
+The lambda schedule is defined in the ``lambda_settings`` objects ``lambda_elec_A``, ``lambda_elec_B``,  ``lambda_vdw_A``, ``lambda_vdw_B``,
+``lambda_restraints_A``, and ``lambda_restraints_B``.
+
+Simulation overview
+~~~~~~~~~~~~~~~~~~~
+
+The :class:`.ProtocolDAG` of the :class:`SepTopProtocol <.SepTopProtocol>` contains :class:`.ProtocolUnit`\ s from both the complex and solvent transformations.
+This means that both legs of the thermodynamic cycle are constructed and run sequentially in the same :class:`.ProtocolDAG`. This is different from the :class:`.RelativeHybridTopologyProtocol` where the :class:`.ProtocolDAG` only runs a single leg of a thermodynamic cycle.
+If multiple ``protocol_repeats`` are run (default: ``protocol_repeats=3``), the :class:`.ProtocolDAG` contains multiple :class:`.ProtocolUnit`\ s of both complex and solvent transformations.
+
+Simulation steps
+""""""""""""""""
+
+Each :class:`.ProtocolUnit` (whether complex or solvent) carries out the following steps:
+
+1. Parameterize the system using `OpenMMForceFields <https://github.com/openmm/openmmforcefields>`_ and `Open Force Field <https://github.com/openforcefield/openff-forcefields>`_.
+2. Equilibrate the fully interacting system using a short MD simulation using the same approach as the :class:`.PlainMDProtocol` (in the solvent leg this will include rounds of NVT and NPT equilibration).
+3. Add restraints to the system: Orientational restraints in the complex, a single harmonic distance restraint in the solvent leg.
+4. Create an alchemical system.
+5. Minimize the alchemical system.
+6. Equilibrate and production simulate the alchemical system using the chosen multistate sampling method (under NPT conditions).
+7. Analyze results for the transformation.
+
+
+.. note:: Three different types of multistate sampling (i.e. replica swapping between lambda states) methods can be chosen; HREX, SAMS, and independent (no lambda swaps attempted).
+          By default the HREX approach is selected, this can be altered using ``solvent_simulation_settings.sampler_method`` or ``complex_simulation_settings.sampler_method`` (default: ``repex``).
+
+
+Simulation details
+""""""""""""""""""
+
+Here are some details of how the simulation is carried out which are not detailed in the :class:`SepTopProtocol <.SepTopProtocol>`:
+
+* The protocol applies a `LangevinMiddleIntegrator <https://openmmtools.readthedocs.io/en/latest/api/generated/openmmtools.mcmc.LangevinDynamicsMove.html>`_ which uses Langevin dynamics, with the LFMiddle discretization [4]_.
+* A `Monte Carlo barostat <https://docs.openmm.org/latest/api-python/generated/openmm.openmm.MonteCarloBarostat.html>`_ is used in the NPT ensemble to maintain constant pressure.
+
+Getting the free energy estimate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The free energy differences are obtained from simulation data using the `MBAR estimator <https://www.alchemistry.org/wiki/Multistate_Bennett_Acceptance_Ratio>`_ (multistate Bennett acceptance ratio estimator) as implemented in the `PyMBAR package <https://pymbar.readthedocs.io/en/master/mbar.html>`_.
+Both the MBAR estimates of the two legs of the thermodynamic cycle, and the overall relative binding free energy (of the entire cycle) are obtained,
+which is different compared to the results in the :class:`.RelativeHybridTopologyProtocol` where results from two legs of the thermodynamic cycle are obtained separately.
+
+In addition to the estimates of the free energy changes and their uncertainty, the protocol also returns some metrics to help assess convergence of the results, these are detailed in the :ref:`multistate analysis section <multistate_analysis>`.
+
+See Also
+--------
+
+**Tutorials**
+
+* :any:`Separated Topologies Free Energies tutorial <../../tutorials/septop_tutorial>`
+
+**Cookbooks**
+
+:ref:`Cookbooks <cookbooks>`
+
+**API Documentation**
+
+* :ref:`OpenMM Protocol Settings <openmm protocol settings api>`
+
+References
+----------
+
+* `pymbar <https://pymbar.readthedocs.io/en/stable/>`_
+* `yank <http://getyank.org/latest/>`_
+* `OpenMMTools <https://openmmtools.readthedocs.io/en/stable/>`_
+* `OpenMM <https://openmm.org/>`_
+
+.. [1] Separated topologies--a method for relative binding free energy calculations using orientational restraints, G. Rocklin, D. Mobley, K. Dill;  Chem Phys, 2013; 138(8):085104. doi: 10.1063/1.4792251.
+.. [2] Broadening the Scope of Binding Free Energy Calculations Using a Separated Topologies Approach, H. Baumann, E. Dybeck, C. McClendon, F. Pickard IV, V. Gapsys, L. Pérez-Benito, D. Hahn, G. Tresadern, A. Mathiowetz, D. Mobley, J. Chem. Theory Comput., 2023, 19, 15, 5058–5076
+.. [3] Avoiding singularities and numerical instabilities in free energy calculations based on molecular simulations, T.C. Beutler, A.E. Mark, R.C. van Schaik, P.R. Greber, and W.F. van Gunsteren, Chem. Phys. Lett., 222 529–539 (1994)
+.. [4] Unified Efficient Thermostat Scheme for the Canonical Ensemble with Holonomic or Isokinetic Constraints via Molecular Dynamics, Zhijun Zhang, Xinzijian Liu, Kangyu Yan, Mark E. Tuckerman, and Jian Liu, J. Phys. Chem. A 2019, 123, 28, 6056-6079
diff --git a/docs/reference/api/index.rst b/docs/reference/api/index.rst
@@ -17,7 +17,8 @@ OpenFE API Reference
     defining_and_executing_simulations
     openmm_rfe
     openmm_solvation_afe
+    openmm_septop
     openmm_md
     openmm_protocol_settings
 
-.. _gufe: https://gufe.readthedocs.io/en/latest/api.html
+.. _gufe: https://gufe.openfree.energy/en/stable/api.html
diff --git a/docs/reference/api/openmm_protocol_settings.rst b/docs/reference/api/openmm_protocol_settings.rst
@@ -10,6 +10,7 @@ can be found on the individual Protocol API reference documentation pages:
 
 * :ref:`OpenMM Absolute Solvation Free Energy <afe solvation protocol api>`
 * :ref:`OpenMM Relative Free Energy <rfe protocol api>`
+* :ref:`OpenMM Relative Free Energy using SepTop <septop protocol api>`
 * :ref:`OpenMM Molecular Dynamics Protocol <md protocol api>`
 
 
@@ -121,6 +122,7 @@ These currently include the following Protocols:
 
 * :ref:`OpenMM Absolute Solvation Free Energy <afe solvation protocol api>`
 * :ref:`OpenMM Relative Free Energy <rfe protocol api>`
+* :ref:`OpenMM Relative Free Energy using SepTop <septop protocol api>`
 
 
 .. autopydantic_model:: MultiStateOutputSettings

diff --git a/docs/reference/api/openmm_septop.rst b/docs/reference/api/openmm_septop.rst
@@ -0,0 +1,83 @@
+OpenMM Separated Topologies Protocol
+====================================
+
+.. _septop protocol api:
+
+This section provides details about the OpenMM Separated Topologies Protocol
+implemented in OpenFE.
+
+Protocol API specification
+--------------------------
+
+.. module:: openfe.protocols.openmm_septop.equil_septop_method
+
+.. autosummary::
+   :nosignatures:
+   :toctree: generated/
+
+   SepTopProtocol
+   SepTopComplexSetupUnit
+   SepTopComplexRunUnit
+   SepTopSolventSetupUnit
+   SepTopSolventRunUnit
+   SepTopProtocolResult
+
+Protocol Settings
+-----------------
+
+Below are the settings which can be tweaked in the protocol. The default settings (accessed using :meth:`SepTopProtocol.default_settings`) will automatically populate settings which we have found to be useful for running a Separated Topologies free energy calculation. There will however be some cases (such as when calculating difficult to converge systems) where you will need to tweak some of the following settings.
+
+
+.. module:: openfe.protocols.openmm_septop.equil_septop_settings
+
+.. autopydantic_model:: SepTopSettings
+   :model-show-json: False
+   :model-show-field-summary: False
+   :model-show-config-member: False
+   :model-show-config-summary: False
+   :model-show-validator-members: False
+   :model-show-validator-summary: False
+   :field-list-validators: False
+   :inherited-members: SettingsBaseModel
+   :exclude-members: get_defaults
+   :member-order: bysource
+
+
+Protocol Specific Settings Classes
+----------------------------------
+
+Below are Settings classes which are unique to the `SepTopProtocol`.
+
+
+.. autopydantic_model:: AlchemicalSettings
+   :model-show-json: False
+   :model-show-field-summary: False
+   :model-show-config-member: False
+   :model-show-config-summary: False
+   :model-show-validator-members: False
+   :model-show-validator-summary: False
+   :field-list-validators: False
+   :inherited-members: SettingsBaseModel
+   :member-order: bysource
+
+.. autopydantic_model:: LambdaSettings
+   :model-show-json: False
+   :model-show-field-summary: False
+   :model-show-config-member: False
+   :model-show-config-summary: False
+   :model-show-validator-members: False
+   :model-show-validator-summary: False
+   :field-list-validators: False
+   :inherited-members: SettingsBaseModel
+   :member-order: bysource
+
+.. autopydantic_model:: SepTopEquilOutputSettings
+   :model-show-json: False
+   :model-show-field-summary: False
+   :model-show-config-member: False
+   :model-show-config-summary: False
+   :model-show-validator-members: False
+   :model-show-validator-summary: False
+   :field-list-validators: False
+   :inherited-members: SettingsBaseModel
+   :member-order: bysource
diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
@@ -20,6 +20,11 @@ Absolute Free Energies
 
 - :any:`Absolute Solvation Free Energy Protocol <ahfe_tutorial>`: A walk-through of calculating the hydration free energy of a benzene ligand.
 
+Relative Free Energies using Separated Topologies
+-------------------------------------------------
+
+- :any:`SepTop Protocol <septop_tutorial>`: A walk-through of calculating the relative binding free energy between TYK2 ligands using a Separated Topologies approach.
+
 Molecular Dynamics (MD)
 -----------------------
 
@@ -45,6 +50,7 @@ Generating Partial Charges
     rbfe_python_tutorial
     rbfe_cli_tutorial
     ahfe_tutorial
+    septop_tutorial
     md_tutorial
     plotting_with_cinnabar
     charge_molecules_cli_tutorial
diff --git a/docs/tutorials/septop_tutorial.nblink b/docs/tutorials/septop_tutorial.nblink
@@ -0,0 +1,6 @@
+{
+   "path": "../ExampleNotebooks/openmm_septop/septop_tutorial.ipynb",
+   "extra-media": [
+      "../ExampleNotebooks/openmm_septop/septop_cycle.png"
+   ]
+}
diff --git a/news/septop_protocol.rst b/news/septop_protocol.rst
@@ -0,0 +1,23 @@
+**Added:**
+
+* Added a new RBFE protocol based on Separated Topologies.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>
diff --git a/openfe/protocols/openmm_septop/__init__.py b/openfe/protocols/openmm_septop/__init__.py
@@ -0,0 +1,29 @@
+# This code is part of OpenFE and is licensed under the MIT license.
+# For details, see https://github.com/OpenFreeEnergy/openfe
+"""
+Run SepTop free energy calculations using OpenMM and OpenMMTools.
+
+"""
+
+from .equil_septop_settings import (
+    SepTopSettings,
+)
+
+from .equil_septop_method import (
+    SepTopProtocol,
+    SepTopProtocolResult,
+    SepTopComplexSetupUnit,
+    SepTopComplexRunUnit,
+    SepTopSolventSetupUnit,
+    SepTopSolventRunUnit,
+)
+
+__all__ = [
+    "SepTopProtocol",
+    "SepTopSettings",
+    "SepTopProtocolResult",
+    "SepTopComplexSetupUnit",
+    "SepTopSolventSetupUnit",
+    "SepTopSolventRunUnit",
+    "SepTopComplexRunUnit",
+]