From fd9476d18a0e77f5adc5486714676ee239e5cec0 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 9 Nov 2026 13:56:47 +0100 Subject: [PATCH 1/4] Add simulation visualization notebook to how-to guides --- docs/conf.py | 2 +- docs/guide/protocols/absolutebinding.rst | 7 +++---- docs/guide/protocols/absolutesolvation.rst | 9 ++++----- docs/guide/protocols/relativehybridtopology.rst | 7 +++---- docs/guide/protocols/septop.rst | 7 +++---- docs/guide/results/index.rst | 4 ++-- docs/guide/results/working_with_results.rst | 1 + docs/how_to_guides/index.rst | 3 +-- docs/how_to_guides/simulation_visualization.nblink | 3 +++ 9 files changed, 21 insertions(+), 22 deletions(-) create mode 100644 docs/how_to_guides/simulation_visualization.nblink diff --git a/docs/conf.py b/docs/conf.py index 9a471e9a2..f06c3c7c0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -195,7 +195,7 @@ else: repo = git.Repo.clone_from( "https://github.com/OpenFreeEnergy/ExampleNotebooks.git", - branch="main", + branch="prep-analysis-for-howto", to_path=example_notebooks_path, ) except Exception as e: diff --git a/docs/guide/protocols/absolutebinding.rst b/docs/guide/protocols/absolutebinding.rst index c9986f433..ddc8504aa 100644 --- a/docs/guide/protocols/absolutebinding.rst +++ b/docs/guide/protocols/absolutebinding.rst @@ -129,10 +129,9 @@ Because the ligand is held in place by orientational restraints in the complex leg, also check that the restraint geometry stays well defined; see the `Boresch restraint analysis tutorial `_. -The multistate trajectory (``simulation.nc``) and its topology -(``alchemical_system.pdb``) can be analysed further using `openfe_analysis`_. - -.. TODO: Link to the trajectory visualisation how_to_guide when published. +The multistate trajectory (``simulation.nc``) and its topology (``alchemical_system.pdb``) +can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, +or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also -------- diff --git a/docs/guide/protocols/absolutesolvation.rst b/docs/guide/protocols/absolutesolvation.rst index bdd10fc5e..b5de708fe 100644 --- a/docs/guide/protocols/absolutesolvation.rst +++ b/docs/guide/protocols/absolutesolvation.rst @@ -111,11 +111,10 @@ The frame stride can be set through ``analysis_settings.skip`` in :class:`.AbsoluteSolvationSettings` (by default, about 500 frames are analysed per state). The ligand atoms must be included in the trajectory output, through ``output_indices`` in ``solvent_output_settings``; otherwise -the structural analysis is skipped. The multistate trajectories -(``solvent.nc`` and ``vacuum.nc``) can be analysed further using -`openfe_analysis`_. - -.. TODO: Link to the trajectory visualisation how_to_guide when published. +the structural analysis is skipped. +The multistate trajectories (``solvent.nc`` and ``vacuum.nc``) can be loaded with `openfe_analysis`_ to visualize +the simulation, extract the trajectories of the end states, +or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also diff --git a/docs/guide/protocols/relativehybridtopology.rst b/docs/guide/protocols/relativehybridtopology.rst index b8dee3515..7faf68b45 100644 --- a/docs/guide/protocols/relativehybridtopology.rst +++ b/docs/guide/protocols/relativehybridtopology.rst @@ -198,10 +198,9 @@ the interacting part of the ligand remains in its binding pose. Inspect the trajectory before interpreting a high RMSD as evidence of ligand displacement. -The multistate trajectory (``simulation.nc``) and the hybrid topology -(``hybrid_system.pdb``) can be analysed further using `openfe_analysis`_. - -.. TODO: Link to the trajectory visualisation how_to_guide when published. +The multistate trajectory (``simulation.nc``) and the hybrid topology (``hybrid_system.pdb``) +can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, +or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also diff --git a/docs/guide/protocols/septop.rst b/docs/guide/protocols/septop.rst index de10a567b..8485757fb 100644 --- a/docs/guide/protocols/septop.rst +++ b/docs/guide/protocols/septop.rst @@ -141,10 +141,9 @@ Because both ligands are held in place by orientational restraints in the complex leg, also check that the restraint geometry stays well defined; see the `Boresch restraint analysis tutorial `_. -The multistate trajectory (``simulation.nc``) and its topology -(``alchemical_system.pdb``) can be analysed further using `openfe_analysis`_. - -.. TODO: Link to the trajectory visualisation how_to_guide when published. +The multistate trajectory (``simulation.nc``) and its topology (``alchemical_system.pdb``) +can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, +or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also -------- diff --git a/docs/guide/results/index.rst b/docs/guide/results/index.rst index 33879bc12..115a26795 100644 --- a/docs/guide/results/index.rst +++ b/docs/guide/results/index.rst @@ -16,7 +16,7 @@ and entire networks of results analysed. * :doc:`/how_to_guides/dumping_transformation` * :doc:`/how_to_guides/gather_results` + * :doc:`/how_to_guides/plotting_with_cinnabar` * :doc:`/how_to_guides/load_results` + * :doc:`/how_to_guides/simulation_visualization` * :doc:`/how_to_guides/jq_inspection` - -.. TODO: add cinnabar and openfe_analysis how-tos. diff --git a/docs/guide/results/working_with_results.rst b/docs/guide/results/working_with_results.rst index a608f680a..109b7c835 100644 --- a/docs/guide/results/working_with_results.rst +++ b/docs/guide/results/working_with_results.rst @@ -57,6 +57,7 @@ and the uncertainty is their standard deviation. .. admonition:: How-to guides * :doc:`/how_to_guides/load_results` + * :doc:`/how_to_guides/simulation_visualization` * :doc:`/how_to_guides/jq_inspection` See Also diff --git a/docs/how_to_guides/index.rst b/docs/how_to_guides/index.rst index b9834a625..41af51270 100644 --- a/docs/how_to_guides/index.rst +++ b/docs/how_to_guides/index.rst @@ -62,10 +62,9 @@ For the concepts behind each step, see the :doc:`User Guide `. gather_results plotting_with_cinnabar load_results + simulation_visualization jq_inspection -.. TODO: Add Analyze an RBFE network with cinnabar" (from - guide/results/working_with_networks) and "Visualize trajectories with openfe_analysis". .. TODO: merge dumping_transformation and jq_inspection into a single "Save and inspect OpenFE JSON files" how-to. diff --git a/docs/how_to_guides/simulation_visualization.nblink b/docs/how_to_guides/simulation_visualization.nblink new file mode 100644 index 000000000..ed4371791 --- /dev/null +++ b/docs/how_to_guides/simulation_visualization.nblink @@ -0,0 +1,3 @@ +{ + "path": "../ExampleNotebooks/simulation_visualization/simulation_visualization.ipynb" +} From f521b126eabedb09eba38a4aef7b66c0a95ef8d6 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 9 Nov 2026 14:35:13 +0100 Subject: [PATCH 2/4] Point to new folder --- docs/how_to_guides/simulation_visualization.nblink | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to_guides/simulation_visualization.nblink b/docs/how_to_guides/simulation_visualization.nblink index ed4371791..195a78ab5 100644 --- a/docs/how_to_guides/simulation_visualization.nblink +++ b/docs/how_to_guides/simulation_visualization.nblink @@ -1,3 +1,3 @@ { - "path": "../ExampleNotebooks/simulation_visualization/simulation_visualization.ipynb" + "path": "../ExampleNotebooks/cookbook/simulation_visualization.ipynb" } From 3ca26293923dcc380ec45dac12925a89c314baa3 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Tue, 10 Nov 2026 15:02:41 +0100 Subject: [PATCH 3/4] address review comment --- docs/guide/protocols/absolutebinding.rst | 17 ++++++++++-- docs/guide/protocols/absolutesolvation.rst | 16 +++++++++++- .../protocols/relativehybridtopology.rst | 26 +++++++++++++++++-- docs/guide/protocols/septop.rst | 22 ++++++++++++++-- 4 files changed, 74 insertions(+), 7 deletions(-) diff --git a/docs/guide/protocols/absolutebinding.rst b/docs/guide/protocols/absolutebinding.rst index ddc8504aa..acb5d380b 100644 --- a/docs/guide/protocols/absolutebinding.rst +++ b/docs/guide/protocols/absolutebinding.rst @@ -129,8 +129,21 @@ Because the ligand is held in place by orientational restraints in the complex leg, also check that the restraint geometry stays well defined; see the `Boresch restraint analysis tutorial `_. -The multistate trajectory (``simulation.nc``) and its topology (``alchemical_system.pdb``) -can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, + +.. _abfe_trajectory_output: + +Trajectory output +""""""""""""""""" + +Each leg writes a multistate trajectory (``complex.nc`` and ``solvent.nc``) with its topology +(``alchemical_system.pdb``). The trajectory stores the positions of every replica, together with the λ state each +replica was in at each iteration. A trajectory can therefore be read in two ways: at a fixed λ **state**, combining +frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states. +This applies to the default replica exchange sampler (``sampler_method = "repex"``). +With ``"independent"`` sampling, replicas never change state, so both give the same trajectory; +with ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible. +Only the atoms selected by ``output_indices`` are saved, which by default excludes water. +Both files can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also diff --git a/docs/guide/protocols/absolutesolvation.rst b/docs/guide/protocols/absolutesolvation.rst index b5de708fe..1e89be702 100644 --- a/docs/guide/protocols/absolutesolvation.rst +++ b/docs/guide/protocols/absolutesolvation.rst @@ -112,7 +112,21 @@ The frame stride can be set through ``analysis_settings.skip`` in analysed per state). The ligand atoms must be included in the trajectory output, through ``output_indices`` in ``solvent_output_settings``; otherwise the structural analysis is skipped. -The multistate trajectories (``solvent.nc`` and ``vacuum.nc``) can be loaded with `openfe_analysis`_ to visualize + +.. _ahfe_trajectory_output: + +Trajectory output +""""""""""""""""" + +Each leg writes a multistate trajectory (``solvent.nc`` and ``vacuum.nc``) with its topology +(``hybrid_system.pdb``). The trajectory stores the positions of every replica, together with the λ state each +replica was in at each iteration. A trajectory can therefore be read in two ways: at a fixed λ **state**, combining +frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states. +This applies to the default replica exchange sampler (``sampler_method = "repex"``). +With ``"independent"`` sampling, replicas never change state, so both give the same trajectory; +with ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible. +Only the atoms selected by ``output_indices`` are saved, which by default excludes water. +Both files can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. diff --git a/docs/guide/protocols/relativehybridtopology.rst b/docs/guide/protocols/relativehybridtopology.rst index 7faf68b45..6a384ffb2 100644 --- a/docs/guide/protocols/relativehybridtopology.rst +++ b/docs/guide/protocols/relativehybridtopology.rst @@ -198,8 +198,30 @@ the interacting part of the ligand remains in its binding pose. Inspect the trajectory before interpreting a high RMSD as evidence of ligand displacement. -The multistate trajectory (``simulation.nc``) and the hybrid topology (``hybrid_system.pdb``) -can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, +.. _rbfe_trajectory_output: + +Trajectory output +""""""""""""""""" + +The multistate trajectory (``simulation.nc``) stores the positions of every replica, together with the λ state each +replica was in at each iteration. A trajectory can therefore be read in two ways: at a fixed λ **state**, combining +frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states. +This applies to the default replica exchange sampler (``sampler_method = "repex"``). +With ``"independent"`` sampling, replicas never change state, so both give the same trajectory; +with ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible. +Only the atoms selected by ``output_settings.output_indices`` are saved, which by default excludes water. + +The accompanying topology (``hybrid_system.pdb``) contains the hybrid ligand, in which the core atoms are shared +between both end states. Its temperature factors record which end state each atom belongs to: + +* ``0.0``: environment atoms (protein, ions and any saved solvent) +* ``0.25``: atoms unique to ligand A +* ``0.5``: core atoms, present in both end states +* ``0.75``: atoms unique to ligand B + +The atoms of end state A are therefore those with a temperature factor of ``0.5`` or lower, +and the atoms of end state B are those with ``0.0``, ``0.5`` or ``0.75``. +Both files can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. diff --git a/docs/guide/protocols/septop.rst b/docs/guide/protocols/septop.rst index 8485757fb..2a14130eb 100644 --- a/docs/guide/protocols/septop.rst +++ b/docs/guide/protocols/septop.rst @@ -141,8 +141,26 @@ Because both ligands are held in place by orientational restraints in the complex leg, also check that the restraint geometry stays well defined; see the `Boresch restraint analysis tutorial `_. -The multistate trajectory (``simulation.nc``) and its topology (``alchemical_system.pdb``) -can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, + +.. _septop_trajectory_output: + +Trajectory output +""""""""""""""""" + +Each leg writes a multistate trajectory (``complex.nc`` and ``solvent.nc``) with its topology +(``alchemical_system.pdb``). The trajectory stores the positions of every replica, together with the λ state each +replica was in at each iteration. A trajectory can therefore be read in two ways: at a fixed λ **state**, combining +frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states. +This applies to the default replica exchange sampler (``sampler_method = "repex"``). +With ``"independent"`` sampling, replicas never change state, so both give the same trajectory; +with ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible. +Only the atoms selected by ``output_indices`` are saved, which by default excludes water. + +Unlike the hybrid topology, both ligands are present with their own atoms in every λ state; what changes along +the λ schedule is how strongly each ligand interacts with its environment. In the first λ state, ligand A is fully +interacting and ligand B is decoupled; in the last λ state, the reverse is true. The atoms of each end state are +therefore the environment atoms together with the atoms of the respective ligand. +Both files can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also From 2e48f658faa5e8a02da3c33f11dfad4923380e18 Mon Sep 17 00:00:00 2001 From: Hannah Baumann <43765638+hannahbaumann@users.noreply.github.com> Date: Tue, 10 Nov 2026 17:38:42 +0100 Subject: [PATCH 4/4] Update showcase assets (#2307) * Update showcase assets * Look at showcase updates * Apply suggestion from @hannahbaumann --- docs/tutorials/showcase_notebook.nblink | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/tutorials/showcase_notebook.nblink b/docs/tutorials/showcase_notebook.nblink index b4b180ee5..50ebe5cc3 100644 --- a/docs/tutorials/showcase_notebook.nblink +++ b/docs/tutorials/showcase_notebook.nblink @@ -1,8 +1,7 @@ { "path": "../ExampleNotebooks/showcase/openfe_showcase.ipynb", "extra-media": [ - "../ExampleNotebooks/showcase/tyk2.png", - "../ExampleNotebooks/showcase/OFE-color-horizontal.png", + "../ExampleNotebooks/showcase/images", "../ExampleNotebooks/showcase/inputs" ] }