hannahbaumann · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026 · Nov 10, 2026
diff --git 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="rename-cinnabar-howto",
+            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
@@ -129,10 +129,22 @@ 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
 <https://openfe-analysis.openfree.energy/en/latest/tutorials/boresch_analysis.html>`_.
-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.
+.. _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,
-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,
+Each leg writes:
+  -  a multistate trajectory (``complex.nc`` and ``solvent.nc``)
+  -  the trajectory's corresponding topology (``alchemical_system.pdb``)
+
+For the default replica exchange sampler (``sampler_method = "repex"``), the trajectory stores the positions of every replica, together with the λ state each replica was in at each iteration.
+A ``repex`` 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.
+
+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,
-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,
+Each leg writes:
+  -  a multistate trajectory (``complex.nc`` and ``solvent.nc``)
+  -  the trajectory's corresponding topology (``alchemical_system.pdb``)
+
+For the default replica exchange sampler (``sampler_method = "repex"``), the trajectory stores the positions of every replica, together with the λ state each replica was in at each iteration.
+A ``repex`` 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.
+
+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
@@ -111,11 +111,24 @@ 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.
+
+.. _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`.
 
 
 See Also

diff --git a/docs/guide/protocols/relativehybridtopology.rst b/docs/guide/protocols/relativehybridtopology.rst
@@ -198,10 +198,31 @@ 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.
+.. _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`.
 
 
 See Also

diff --git a/docs/guide/protocols/septop.rst b/docs/guide/protocols/septop.rst
@@ -141,10 +141,27 @@ 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
 <https://openfe-analysis.openfree.energy/en/latest/tutorials/boresch_analysis.html>`_.
-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.
+.. _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
 --------

diff --git a/docs/guide/results/index.rst b/docs/guide/results/index.rst
@@ -18,6 +18,5 @@ and entire networks of results analysed.
    * :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 openfe_analysis how-to.
diff --git 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
@@ -62,10 +62,9 @@ For the concepts behind each step, see the :doc:`User Guide </guide/index>`.
    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
@@ -0,0 +1,3 @@
+{
+   "path": "../ExampleNotebooks/cookbook/simulation_visualization.ipynb"
+}
diff --git 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"
    ]
 }