From 97a0a289cfe3c76041704a0ecd29e19dfb75f60f Mon Sep 17 00:00:00 2001 From: Josh Horton Date: Thu, 22 Oct 2026 11:40:46 +0100 Subject: [PATCH 1/5] exploring rbfe settings --- cookbook/exploring_rbfe_settings.ipynb | 292 +++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 cookbook/exploring_rbfe_settings.ipynb diff --git a/cookbook/exploring_rbfe_settings.ipynb b/cookbook/exploring_rbfe_settings.ipynb new file mode 100644 index 0000000..d4d6b94 --- /dev/null +++ b/cookbook/exploring_rbfe_settings.ipynb @@ -0,0 +1,292 @@ +{ + "cells": [ + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "# Exploring HybridTopologyProtocol settings\n", + "\n", + "The `HybridTopologyProtocol` exposes a number of simulation settings that can be used to control the behavior of an alchemical transformation. In this notebook, we will explore changes to common settings, explaining when you might want to\n", + "consider changing them, the expected effect of changing them, and how to change them in practice.\n", + "\n", + "## Inspecting the default settings\n", + "\n", + "The default settings for the `HybridTopologyProtocol` are designed to be a good starting point for most alchemical transformations. However, depending on the specific system and transformation being studied, you may want to adjust these settings to improve convergence or precision.\n", + "\n", + "The default settings can be inspected by:" + ], + "id": "a3f965b58be21979" + }, + { + "metadata": { + "ExecuteTime": { + "end_time": "2026-10-21T17:14:24.838663Z", + "start_time": "2026-10-21T17:14:24.718322Z" + } + }, + "cell_type": "code", + "source": [ + "from openfe.protocols.openmm_rfe import RelativeHybridTopologyProtocol\n", + "\n", + "settings = RelativeHybridTopologyProtocol.default_settings()" + ], + "id": "5690f07a5cd27245", + "outputs": [], + "execution_count": 10 + }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "For a complete explanation of each setting and how to customize the object see [Choose and Configure a Protocol](https://docs.openfree.energy/en/latest/cookbook/choose_protocol.html).\n", + "\n", + "The main parameters that determine the amount of sampling performed and the associated cost for the hybrid topology protocol are:\n", + "\n", + "- **Lambda windows**: the number of discrete alchemical states simulated during the transformation.\n", + "- **Production length**: the length of the production simulation performed at each lambda window.\n", + "- **Equilibration length**: the length of the equilibration simulation performed at each lambda window.\n", + "- **Protocol repeats**: the number of independent executions of the protocol.\n", + "\n", + "These parameters can be adjusted to increase the amount of sampling performed, which can improve convergence and precision, but will also increase the computational cost of the simulation. The following example retrieves them from the default settings:" + ], + "id": "94c914fc75cd8fcb" + }, + { + "metadata": { + "ExecuteTime": { + "end_time": "2026-10-21T17:14:25.858033Z", + "start_time": "2026-10-21T17:14:25.812345Z" + } + }, + "cell_type": "code", + "source": [ + "n_repeats = settings.protocol_repeats\n", + "n_windows = settings.lambda_settings.lambda_windows\n", + "production_length = settings.simulation_settings.production_length\n", + "equilibration_length = settings.simulation_settings.equilibration_length\n", + "\n", + "print(f\"Lambda windows: {n_windows}\")\n", + "print(f\"Production length per state: {production_length}\")\n", + "print(f\"Equilibration length per state: {equilibration_length}\")\n", + "print(f\"Independent repeats: {n_repeats}\")" + ], + "id": "3c2f7354aadac1e8", + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Lambda windows: 11\n", + "Production length per state: 5.0 nanosecond\n", + "Equilibration length per state: 1.0 nanosecond\n", + "Independent repeats: 3\n" + ] + } + ], + "execution_count": 11 + }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "## Estimating the computational cost of a protocol\n", + "\n", + "A useful first approximation of the computational cost of a protocol execution is the total simulation time in nanoseconds across all lambda windows and repeats. This can be calculated as:\n", + "\n", + "$$T_{total} = N_{repeats} \\times N_{\\lambda windows} \\times (T_{production} + T_{equilibration})$$\n", + "\n", + "So for the default settings the total simulation time is:" + ], + "id": "704d5dc6e6f895f5" + }, + { + "metadata": { + "ExecuteTime": { + "end_time": "2026-10-21T17:14:27.457661Z", + "start_time": "2026-10-21T17:14:27.409115Z" + } + }, + "cell_type": "code", + "source": [ + "total_sim_time = n_repeats * n_windows * (production_length + equilibration_length)\n", + "print(f\"Total simulation time: {total_sim_time} ns\")" + ], + "id": "fd81e13e2c34684d", + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Total simulation time: 198.0 nanosecond ns\n" + ] + } + ], + "execution_count": 12 + }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "The HybridTopologyProtocol simulates the complex and solvent legs of a transformation independently, so if both use the same settings the total cost of the protocol is double the above estimate. It is useful to consider this estimate when deciding how to adjust the settings for a given transformation.\n", + "\n", + "# Increasing simulation length\n", + "\n", + "This section describes how to increase the amount of production simulation performed at each lambda window and estimate the increase in computational cost.\n", + "\n", + "## When to increase simulation length\n", + "\n", + "Consider increasing the simulation length when:\n", + "\n", + "- Free-energy estimates differ substantially between independent repeats of the protocol.\n", + "- Forward and reverse free-energy estimates disagree by more than 1kbT 50% of the simulation length and their uncertainties do not overlap.\n", + "- A large number of samples are discarded during analysis due to the automated equilibration and decorrelation methods.\n", + "- Replica exchange or MBAR analysis indicates that alchemical overlap or replica mixing is poor between lambda windows.\n", + "- The transformation involves large structural changes due to for example changes in formal charge.\n", + "\n", + "This information is available through the automated analysis performed by the `HybridTopologyProtocol` see the list of available [analysis metrics](https://docs.openfree.energy/en/latest/guide/protocols/relativehybridtopology.html#analysis) for more information, it is recommended to review the analysis metrics before deciding to increase the simulation length.\n", + "\n", + "## When not to increase simulation length\n", + "\n", + "Increasing the simulation length is not always the best solution. For example poor overlap between neighboring lambda windows may require changes to the number of lambda windows or the spacing between them.\n", + "\n", + "## Changing the production length\n", + "\n", + "The following example shows how to change the production length for a `HybridTopologyProtocol` object. In this example, we will double the production length from `5 ns` to `10 ns` per lambda window. Note the use of units from the `openff.units` package to specify the value is in nanoseconds. We will then calculate the new total simulation time and compare it to the default settings.\n" + ], + "id": "3ab10c2ecebbd3df" + }, + { + "metadata": { + "ExecuteTime": { + "end_time": "2026-10-22T10:36:48.805701Z", + "start_time": "2026-10-22T10:36:48.498120Z" + } + }, + "cell_type": "code", + "source": [ + "from openff.units import unit\n", + "\n", + "long_settings = RelativeHybridTopologyProtocol.default_settings()\n", + "\n", + "# Increase the production length to 10 ns\n", + "long_settings.simulation_settings.production_length = 10 * unit.nanoseconds\n", + "\n", + "# Create a new protocol object with the updated settings\n", + "protocol = RelativeHybridTopologyProtocol(settings=long_settings)\n", + "\n", + "print(f\"Updated production length: {protocol.settings.simulation_settings.production_length}\")\n", + "\n", + "# Calculate the new total simulation time\n", + "new_total_sim_time = n_repeats * n_windows * (protocol.settings.simulation_settings.production_length + protocol.settings.simulation_settings.equilibration_length)\n", + "print(f\"New total simulation time: {new_total_sim_time} ns\")\n", + "\n", + "# Print the percentage increase in total simulation time\n", + "percentage_increase = ((new_total_sim_time - total_sim_time) / total_sim_time) * 100\n", + "print(f\"Percentage increase in total simulation time: {percentage_increase.m:.2f}%\")" + ], + "id": "2cf9b3c7030df36f", + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Updated production length: 10 nanosecond\n", + "New total simulation time: 363.0 nanosecond ns\n", + "Percentage increase in total simulation time: 83.33%\n" + ] + } + ], + "execution_count": 22 + }, + { + "metadata": {}, + "cell_type": "markdown", + "source": [ + "# Increasing the number of lambda windows\n", + "\n", + "Increasing the number of lambda windows introduces additional intermediate alchemical states along the transformation which can make the pathway easier to traverse and improve the overlap between neighboring states. This section describes how to increase the number of lambda windows and estimate the increase in computational cost.\n", + "\n", + "## When to increase the number of lambda windows\n", + "\n", + "Consider increasing the number of lambda windows **before** running the simulation when:\n", + "\n", + "- The transformation involves a change in net formal charge or substantial redistribution of charge.\n", + "\n", + "Consider increasing the number of lambda windows **after** running the simulation when:\n", + "\n", + "- Neighboring lambda windows have poor phase-space overlap or replica mixing statistics.\n", + "\n", + "## When not to increase the number of lambda windows\n", + "\n", + "Increasing the number of lambda windows is not always the best solution, slow changes in ligand conformation or binding site rearrangements may require longer simulation lengths to achieve convergence. In these cases, increasing the number of lambda windows may not improve convergence and will increase the computational cost of the protocol.\n", + "\n", + "## Changing the number of lambda windows\n", + "\n", + "The following example shows how to change the number of lambda windows for a `HybridTopologyProtocol` object. In this example, we will double the number of lambda windows from `11` to `22`. We will then calculate the new total simulation time and compare it to the default settings. Note the `lambda_windows` setting only accepts integer values and generates a uniform spacing of lambda values between `0` and `1`.\n" + ], + "id": "3d6bb208a91ce6d0" + }, + { + "metadata": { + "ExecuteTime": { + "end_time": "2026-10-22T10:38:21.632585Z", + "start_time": "2026-10-22T10:38:21.575761Z" + } + }, + "cell_type": "code", + "source": [ + "more_window_settings = RelativeHybridTopologyProtocol.default_settings()\n", + "\n", + "# Increase the number of lambda windows to 22\n", + "more_window_settings.lambda_settings.lambda_windows = 22\n", + "\n", + "# Create a new protocol object with the updated settings\n", + "protocol = RelativeHybridTopologyProtocol(settings=more_window_settings)\n", + "\n", + "print(f\"Updated number of lambda windows: {protocol.settings.lambda_settings.lambda_windows}\")\n", + "\n", + "# Calculate the new total simulation time\n", + "new_total_sim_time = n_repeats * protocol.settings.lambda_settings.lambda_windows * (protocol.settings.simulation_settings.production_length + protocol.settings.simulation_settings.equilibration_length)\n", + "print(f\"New total simulation time: {new_total_sim_time} ns\")\n", + "\n", + "# Print the percentage increase in total simulation time\n", + "percentage_increase = ((new_total_sim_time - total_sim_time) / total_sim_time) * 100\n", + "print(f\"Percentage increase in total simulation time: {percentage_increase.m:.2f}%\")" + ], + "id": "a8a0a2b5ba644eb4", + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Updated number of lambda windows: 22\n", + "New total simulation time: 396.0 nanosecond ns\n", + "Percentage increase in total simulation time: 100.00%\n" + ] + } + ], + "execution_count": 23 + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 2 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython2", + "version": "2.7.6" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} From 5c447f3fb8063aebfdb9c33e2f56aca25e5a0f3d Mon Sep 17 00:00:00 2001 From: Josh Horton Date: Thu, 22 Oct 2026 11:46:42 +0100 Subject: [PATCH 2/5] small format update --- cookbook/exploring_rbfe_settings.ipynb | 40 ++++++++++++++------------ 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/cookbook/exploring_rbfe_settings.ipynb b/cookbook/exploring_rbfe_settings.ipynb index d4d6b94..241985d 100644 --- a/cookbook/exploring_rbfe_settings.ipynb +++ b/cookbook/exploring_rbfe_settings.ipynb @@ -6,6 +6,7 @@ "source": [ "# Exploring HybridTopologyProtocol settings\n", "\n", + "\n", "The `HybridTopologyProtocol` exposes a number of simulation settings that can be used to control the behavior of an alchemical transformation. In this notebook, we will explore changes to common settings, explaining when you might want to\n", "consider changing them, the expected effect of changing them, and how to change them in practice.\n", "\n", @@ -20,8 +21,8 @@ { "metadata": { "ExecuteTime": { - "end_time": "2026-10-21T17:14:24.838663Z", - "start_time": "2026-10-21T17:14:24.718322Z" + "end_time": "2026-10-22T10:46:22.362791Z", + "start_time": "2026-10-22T10:46:22.275865Z" } }, "cell_type": "code", @@ -32,7 +33,7 @@ ], "id": "5690f07a5cd27245", "outputs": [], - "execution_count": 10 + "execution_count": 24 }, { "metadata": {}, @@ -54,8 +55,8 @@ { "metadata": { "ExecuteTime": { - "end_time": "2026-10-21T17:14:25.858033Z", - "start_time": "2026-10-21T17:14:25.812345Z" + "end_time": "2026-10-22T10:46:22.931214Z", + "start_time": "2026-10-22T10:46:22.867745Z" } }, "cell_type": "code", @@ -83,7 +84,7 @@ ] } ], - "execution_count": 11 + "execution_count": 25 }, { "metadata": {}, @@ -102,8 +103,8 @@ { "metadata": { "ExecuteTime": { - "end_time": "2026-10-21T17:14:27.457661Z", - "start_time": "2026-10-21T17:14:27.409115Z" + "end_time": "2026-10-22T10:46:23.520808Z", + "start_time": "2026-10-22T10:46:23.480068Z" } }, "cell_type": "code", @@ -121,7 +122,7 @@ ] } ], - "execution_count": 12 + "execution_count": 26 }, { "metadata": {}, @@ -135,13 +136,16 @@ "\n", "## When to increase simulation length\n", "\n", - "Consider increasing the simulation length when:\n", + "Consider increasing the simulation length **before** running the simulation when:\n", + "\n", + "- The transformation involves large structural changes due to for example changes in formal charge, you may also need to consider increasing the number of lambda windows see the next section for more information.\n", + "\n", + "Consider increasing the simulation length **after** running the simulation when:\n", "\n", "- Free-energy estimates differ substantially between independent repeats of the protocol.\n", "- Forward and reverse free-energy estimates disagree by more than 1kbT 50% of the simulation length and their uncertainties do not overlap.\n", "- A large number of samples are discarded during analysis due to the automated equilibration and decorrelation methods.\n", "- Replica exchange or MBAR analysis indicates that alchemical overlap or replica mixing is poor between lambda windows.\n", - "- The transformation involves large structural changes due to for example changes in formal charge.\n", "\n", "This information is available through the automated analysis performed by the `HybridTopologyProtocol` see the list of available [analysis metrics](https://docs.openfree.energy/en/latest/guide/protocols/relativehybridtopology.html#analysis) for more information, it is recommended to review the analysis metrics before deciding to increase the simulation length.\n", "\n", @@ -158,8 +162,8 @@ { "metadata": { "ExecuteTime": { - "end_time": "2026-10-22T10:36:48.805701Z", - "start_time": "2026-10-22T10:36:48.498120Z" + "end_time": "2026-10-22T10:46:24.174430Z", + "start_time": "2026-10-22T10:46:24.112991Z" } }, "cell_type": "code", @@ -196,7 +200,7 @@ ] } ], - "execution_count": 22 + "execution_count": 27 }, { "metadata": {}, @@ -210,7 +214,7 @@ "\n", "Consider increasing the number of lambda windows **before** running the simulation when:\n", "\n", - "- The transformation involves a change in net formal charge or substantial redistribution of charge.\n", + "- The transformation involves a change in net formal charge or substantial redistribution of charge, you may also need to consider increasing the simulation length see the previous section for more information.\n", "\n", "Consider increasing the number of lambda windows **after** running the simulation when:\n", "\n", @@ -229,8 +233,8 @@ { "metadata": { "ExecuteTime": { - "end_time": "2026-10-22T10:38:21.632585Z", - "start_time": "2026-10-22T10:38:21.575761Z" + "end_time": "2026-10-22T10:46:24.818876Z", + "start_time": "2026-10-22T10:46:24.776710Z" } }, "cell_type": "code", @@ -265,7 +269,7 @@ ] } ], - "execution_count": 23 + "execution_count": 28 } ], "metadata": { From 4653a6e4f547f4c41f089af4d383babaf5c180c8 Mon Sep 17 00:00:00 2001 From: Josh Horton Date: Thu, 22 Oct 2026 12:33:06 +0100 Subject: [PATCH 3/5] clean up units and some text --- cookbook/exploring_rbfe_settings.ipynb | 49 +++++++++++++------------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/cookbook/exploring_rbfe_settings.ipynb b/cookbook/exploring_rbfe_settings.ipynb index 241985d..01076f2 100644 --- a/cookbook/exploring_rbfe_settings.ipynb +++ b/cookbook/exploring_rbfe_settings.ipynb @@ -7,12 +7,11 @@ "# Exploring HybridTopologyProtocol settings\n", "\n", "\n", - "The `HybridTopologyProtocol` exposes a number of simulation settings that can be used to control the behavior of an alchemical transformation. In this notebook, we will explore changes to common settings, explaining when you might want to\n", - "consider changing them, the expected effect of changing them, and how to change them in practice.\n", + "The `HybridTopologyProtocol` exposes a number of simulation settings that can effect the convergence properties, accuracy and precision of an alchemical transformation. In this notebook, we will explore changes to common settings, explaining when you might want to consider changing them, the expected effect of changing them, and how to change them in practice.\n", "\n", "## Inspecting the default settings\n", "\n", - "The default settings for the `HybridTopologyProtocol` are designed to be a good starting point for most alchemical transformations. However, depending on the specific system and transformation being studied, you may want to adjust these settings to improve convergence or precision.\n", + "The default settings for the `HybridTopologyProtocol` are designed to be a good starting point for most alchemical transformations. However, depending on the specific system and transformation being studied, you may want to adjust these settings to improve convergence or precision of the estimation.\n", "\n", "The default settings can be inspected by:" ], @@ -48,15 +47,15 @@ "- **Equilibration length**: the length of the equilibration simulation performed at each lambda window.\n", "- **Protocol repeats**: the number of independent executions of the protocol.\n", "\n", - "These parameters can be adjusted to increase the amount of sampling performed, which can improve convergence and precision, but will also increase the computational cost of the simulation. The following example retrieves them from the default settings:" + "The appropriate changes to these settings are transformation dependent with no single setting guarantying sufficient convergence or accuracy in general. These settings are good starting point to investigate the effect of additional sampling on the transformation under study however, but will also increase the computational cost of the simulation. The following example retrieves them from the default settings:" ], "id": "94c914fc75cd8fcb" }, { "metadata": { "ExecuteTime": { - "end_time": "2026-10-22T10:46:22.931214Z", - "start_time": "2026-10-22T10:46:22.867745Z" + "end_time": "2026-10-22T11:21:12.003187Z", + "start_time": "2026-10-22T11:21:11.965473Z" } }, "cell_type": "code", @@ -67,8 +66,8 @@ "equilibration_length = settings.simulation_settings.equilibration_length\n", "\n", "print(f\"Lambda windows: {n_windows}\")\n", - "print(f\"Production length per state: {production_length}\")\n", - "print(f\"Equilibration length per state: {equilibration_length}\")\n", + "print(f\"Production length per state: {production_length.m} ns\")\n", + "print(f\"Equilibration length per state: {equilibration_length.m} ns\")\n", "print(f\"Independent repeats: {n_repeats}\")" ], "id": "3c2f7354aadac1e8", @@ -78,13 +77,13 @@ "output_type": "stream", "text": [ "Lambda windows: 11\n", - "Production length per state: 5.0 nanosecond\n", - "Equilibration length per state: 1.0 nanosecond\n", + "Production length per state: 5.0 ns\n", + "Equilibration length per state: 1.0 ns\n", "Independent repeats: 3\n" ] } ], - "execution_count": 25 + "execution_count": 32 }, { "metadata": {}, @@ -103,14 +102,14 @@ { "metadata": { "ExecuteTime": { - "end_time": "2026-10-22T10:46:23.520808Z", - "start_time": "2026-10-22T10:46:23.480068Z" + "end_time": "2026-10-22T11:20:41.651615Z", + "start_time": "2026-10-22T11:20:41.533380Z" } }, "cell_type": "code", "source": [ "total_sim_time = n_repeats * n_windows * (production_length + equilibration_length)\n", - "print(f\"Total simulation time: {total_sim_time} ns\")" + "print(f\"Total simulation time: {total_sim_time.m} ns\")" ], "id": "fd81e13e2c34684d", "outputs": [ @@ -118,11 +117,11 @@ "name": "stdout", "output_type": "stream", "text": [ - "Total simulation time: 198.0 nanosecond ns\n" + "Total simulation time: 198.0 ns\n" ] } ], - "execution_count": 26 + "execution_count": 29 }, { "metadata": {}, @@ -143,9 +142,9 @@ "Consider increasing the simulation length **after** running the simulation when:\n", "\n", "- Free-energy estimates differ substantially between independent repeats of the protocol.\n", - "- Forward and reverse free-energy estimates disagree by more than 1kbT 50% of the simulation length and their uncertainties do not overlap.\n", + "- Forward and reverse free-energy estimates disagree by more than 1kbT at 50% of the simulation length and their uncertainties do not overlap.\n", "- A large number of samples are discarded during analysis due to the automated equilibration and decorrelation methods.\n", - "- Replica exchange or MBAR analysis indicates that alchemical overlap or replica mixing is poor between lambda windows.\n", + "- Replica exchange or MBAR analysis indicates that alchemical overlap or replica mixing is poor between lambda windows, you may also need to consider increasing the number of lambda windows see the next section for more information.\n", "\n", "This information is available through the automated analysis performed by the `HybridTopologyProtocol` see the list of available [analysis metrics](https://docs.openfree.energy/en/latest/guide/protocols/relativehybridtopology.html#analysis) for more information, it is recommended to review the analysis metrics before deciding to increase the simulation length.\n", "\n", @@ -162,8 +161,8 @@ { "metadata": { "ExecuteTime": { - "end_time": "2026-10-22T10:46:24.174430Z", - "start_time": "2026-10-22T10:46:24.112991Z" + "end_time": "2026-10-22T11:21:00.199353Z", + "start_time": "2026-10-22T11:21:00.150806Z" } }, "cell_type": "code", @@ -178,11 +177,11 @@ "# Create a new protocol object with the updated settings\n", "protocol = RelativeHybridTopologyProtocol(settings=long_settings)\n", "\n", - "print(f\"Updated production length: {protocol.settings.simulation_settings.production_length}\")\n", + "print(f\"Updated production length: {protocol.settings.simulation_settings.production_length.m} ns\")\n", "\n", "# Calculate the new total simulation time\n", "new_total_sim_time = n_repeats * n_windows * (protocol.settings.simulation_settings.production_length + protocol.settings.simulation_settings.equilibration_length)\n", - "print(f\"New total simulation time: {new_total_sim_time} ns\")\n", + "print(f\"New total simulation time: {new_total_sim_time.m} ns\")\n", "\n", "# Print the percentage increase in total simulation time\n", "percentage_increase = ((new_total_sim_time - total_sim_time) / total_sim_time) * 100\n", @@ -194,13 +193,13 @@ "name": "stdout", "output_type": "stream", "text": [ - "Updated production length: 10 nanosecond\n", - "New total simulation time: 363.0 nanosecond ns\n", + "Updated production length: 10 ns\n", + "New total simulation time: 363.0 ns\n", "Percentage increase in total simulation time: 83.33%\n" ] } ], - "execution_count": 27 + "execution_count": 31 }, { "metadata": {}, From ded8d29c3bc6bfa46ef886e9ccc3b8f4758bbd19 Mon Sep 17 00:00:00 2001 From: Josh Horton Date: Thu, 22 Oct 2026 12:35:18 +0100 Subject: [PATCH 4/5] more intro --- cookbook/exploring_rbfe_settings.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/exploring_rbfe_settings.ipynb b/cookbook/exploring_rbfe_settings.ipynb index 01076f2..8abaee5 100644 --- a/cookbook/exploring_rbfe_settings.ipynb +++ b/cookbook/exploring_rbfe_settings.ipynb @@ -11,7 +11,7 @@ "\n", "## Inspecting the default settings\n", "\n", - "The default settings for the `HybridTopologyProtocol` are designed to be a good starting point for most alchemical transformations. However, depending on the specific system and transformation being studied, you may want to adjust these settings to improve convergence or precision of the estimation.\n", + "The default settings for the `HybridTopologyProtocol` are designed to be a good starting point for most alchemical transformations with the goal of obtaining reliable estimates with sufficient precision for decision-making at a reasonable computational cost. However, depending on the specific system and transformation being studied, you may want to adjust these settings to improve convergence or precision of the estimation.\n", "\n", "The default settings can be inspected by:" ], From 2987975358090c27f32cff3ef87feecc25feaf57 Mon Sep 17 00:00:00 2001 From: Josh Horton Date: Thu, 22 Oct 2026 14:21:25 +0100 Subject: [PATCH 5/5] more clean up --- cookbook/exploring_rbfe_settings.ipynb | 42 ++++++++++++++++---------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/cookbook/exploring_rbfe_settings.ipynb b/cookbook/exploring_rbfe_settings.ipynb index 8abaee5..767d5b4 100644 --- a/cookbook/exploring_rbfe_settings.ipynb +++ b/cookbook/exploring_rbfe_settings.ipynb @@ -7,11 +7,11 @@ "# Exploring HybridTopologyProtocol settings\n", "\n", "\n", - "The `HybridTopologyProtocol` exposes a number of simulation settings that can effect the convergence properties, accuracy and precision of an alchemical transformation. In this notebook, we will explore changes to common settings, explaining when you might want to consider changing them, the expected effect of changing them, and how to change them in practice.\n", + "The `RelativeHybridTopologyProtocol` exposes a number of simulation settings that can affect the convergence properties, accuracy and precision of an alchemical transformation. In this notebook, we will explore changes to common settings, advising when you might want to consider changing them and how to change them in practice. For a detailed explanation of the protocol and its limitations see the [protocol documentation](https://docs.openfree.energy/en/latest/guide/protocols/relativehybridtopology.html#relative-hybrid-topology-protocol) and references therein.\n", "\n", "## Inspecting the default settings\n", "\n", - "The default settings for the `HybridTopologyProtocol` are designed to be a good starting point for most alchemical transformations with the goal of obtaining reliable estimates with sufficient precision for decision-making at a reasonable computational cost. However, depending on the specific system and transformation being studied, you may want to adjust these settings to improve convergence or precision of the estimation.\n", + "The default settings for the `RelativeHybridTopologyProtocol` are designed to be a good starting point for most alchemical transformations with the goal of obtaining reliable estimates with sufficient precision for decision-making at a reasonable computational cost. However, depending on the specific system and transformation being studied, you may want to adjust these settings to improve convergence or precision of the estimation.\n", "\n", "The default settings can be inspected by:" ], @@ -47,15 +47,15 @@ "- **Equilibration length**: the length of the equilibration simulation performed at each lambda window.\n", "- **Protocol repeats**: the number of independent executions of the protocol.\n", "\n", - "The appropriate changes to these settings are transformation dependent with no single setting guarantying sufficient convergence or accuracy in general. These settings are good starting point to investigate the effect of additional sampling on the transformation under study however, but will also increase the computational cost of the simulation. The following example retrieves them from the default settings:" + "The appropriate changes to these settings are transformation dependent with no single setting guaranteeing sufficient convergence or accuracy in general. These settings provide a good starting point to investigate the affect of additional sampling on the transformation under study however, but will also increase the computational cost of the simulation. The following example retrieves them from the default settings:" ], "id": "94c914fc75cd8fcb" }, { "metadata": { "ExecuteTime": { - "end_time": "2026-10-22T11:21:12.003187Z", - "start_time": "2026-10-22T11:21:11.965473Z" + "end_time": "2026-10-22T13:12:34.530752Z", + "start_time": "2026-10-22T13:12:34.485473Z" } }, "cell_type": "code", @@ -83,7 +83,7 @@ ] } ], - "execution_count": 32 + "execution_count": 35 }, { "metadata": {}, @@ -127,7 +127,7 @@ "metadata": {}, "cell_type": "markdown", "source": [ - "The HybridTopologyProtocol simulates the complex and solvent legs of a transformation independently, so if both use the same settings the total cost of the protocol is double the above estimate. It is useful to consider this estimate when deciding how to adjust the settings for a given transformation.\n", + "The `RelativeHybridTopologyProtocol` simulates the complex and solvent legs of a transformation independently, so if both use the same settings the total cost of the protocol is double the above estimate. It is useful to consider this estimate when deciding how to adjust the settings for a given transformation.\n", "\n", "# Increasing simulation length\n", "\n", @@ -142,11 +142,11 @@ "Consider increasing the simulation length **after** running the simulation when:\n", "\n", "- Free-energy estimates differ substantially between independent repeats of the protocol.\n", - "- Forward and reverse free-energy estimates disagree by more than 1kbT at 50% of the simulation length and their uncertainties do not overlap.\n", + "- Forward and reverse free-energy estimates disagree by more than 1kbT at over 50% of the simulation length and their uncertainties do not overlap.\n", "- A large number of samples are discarded during analysis due to the automated equilibration and decorrelation methods.\n", "- Replica exchange or MBAR analysis indicates that alchemical overlap or replica mixing is poor between lambda windows, you may also need to consider increasing the number of lambda windows see the next section for more information.\n", "\n", - "This information is available through the automated analysis performed by the `HybridTopologyProtocol` see the list of available [analysis metrics](https://docs.openfree.energy/en/latest/guide/protocols/relativehybridtopology.html#analysis) for more information, it is recommended to review the analysis metrics before deciding to increase the simulation length.\n", + "This information is available through the automated analysis performed by the `RelativeHybridTopologyProtocol` see the list of available [analysis metrics](https://docs.openfree.energy/en/latest/guide/protocols/relativehybridtopology.html#analysis) for more information, it is recommended to review the analysis metrics before deciding to increase the simulation length.\n", "\n", "## When not to increase simulation length\n", "\n", @@ -154,7 +154,7 @@ "\n", "## Changing the production length\n", "\n", - "The following example shows how to change the production length for a `HybridTopologyProtocol` object. In this example, we will double the production length from `5 ns` to `10 ns` per lambda window. Note the use of units from the `openff.units` package to specify the value is in nanoseconds. We will then calculate the new total simulation time and compare it to the default settings.\n" + "The following example shows how to change the production length for a `RelativeHybridTopologyProtocol` object. In this example, we will double the production length from `5 ns` to `10 ns` per lambda window. Note the use of units from the `openff.units` package to specify the value is in nanoseconds. We will then calculate the new total simulation time and compare it to the default settings.\n" ], "id": "3ab10c2ecebbd3df" }, @@ -225,15 +225,15 @@ "\n", "## Changing the number of lambda windows\n", "\n", - "The following example shows how to change the number of lambda windows for a `HybridTopologyProtocol` object. In this example, we will double the number of lambda windows from `11` to `22`. We will then calculate the new total simulation time and compare it to the default settings. Note the `lambda_windows` setting only accepts integer values and generates a uniform spacing of lambda values between `0` and `1`.\n" + "The following example shows how to change the number of lambda windows for a `RelativeHybridTopologyProtocol` object. In this example, we will double the number of lambda windows from `11` to `22`. We will then calculate the new total simulation time and compare it to the default settings. Note the `lambda_windows` setting only accepts integer values and generates a uniform spacing of lambda values between `0` and `1`.\n" ], "id": "3d6bb208a91ce6d0" }, { "metadata": { "ExecuteTime": { - "end_time": "2026-10-22T10:46:24.818876Z", - "start_time": "2026-10-22T10:46:24.776710Z" + "end_time": "2026-10-22T13:14:05.953017Z", + "start_time": "2026-10-22T13:14:05.920141Z" } }, "cell_type": "code", @@ -242,6 +242,8 @@ "\n", "# Increase the number of lambda windows to 22\n", "more_window_settings.lambda_settings.lambda_windows = 22\n", + "# The number of replicas should be increased to match the number of lambda windows\n", + "more_window_settings.simulation_settings.n_replicas = 22\n", "\n", "# Create a new protocol object with the updated settings\n", "protocol = RelativeHybridTopologyProtocol(settings=more_window_settings)\n", @@ -250,7 +252,7 @@ "\n", "# Calculate the new total simulation time\n", "new_total_sim_time = n_repeats * protocol.settings.lambda_settings.lambda_windows * (protocol.settings.simulation_settings.production_length + protocol.settings.simulation_settings.equilibration_length)\n", - "print(f\"New total simulation time: {new_total_sim_time} ns\")\n", + "print(f\"New total simulation time: {new_total_sim_time.m} ns\")\n", "\n", "# Print the percentage increase in total simulation time\n", "percentage_increase = ((new_total_sim_time - total_sim_time) / total_sim_time) * 100\n", @@ -263,12 +265,20 @@ "output_type": "stream", "text": [ "Updated number of lambda windows: 22\n", - "New total simulation time: 396.0 nanosecond ns\n", + "New total simulation time: 396.0 ns\n", "Percentage increase in total simulation time: 100.00%\n" ] } ], - "execution_count": 28 + "execution_count": 37 + }, + { + "metadata": {}, + "cell_type": "code", + "outputs": [], + "execution_count": null, + "source": "", + "id": "2be1cfe17af0153" } ], "metadata": {