diff --git a/cookbook/customise_system_model.ipynb b/cookbook/customise_system_model.ipynb new file mode 100644 index 00000000..122bd5bc --- /dev/null +++ b/cookbook/customise_system_model.ipynb @@ -0,0 +1,214 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "a1000001", + "metadata": {}, + "source": [ + "# Customise the system model" + ] + }, + { + "cell_type": "markdown", + "id": "a1000002", + "metadata": {}, + "source": [ + "OpenMM-based `Protocol`s allow you to customise a number of settings which control how the system is modelled. This includes the water model, solvent box shape and padding. Because the protocols share a consistent design, the guide bellow applies to:\n", + "\n", + "\n", + "- `AbsoluteBindingProtocol`\n", + "- `AbsoluteSolvationProtocol`\n", + "- `RelativeHybridTopologyProtocol`\n", + "- `SepTopProtocol`\n", + "\n", + "\n", + "This guide covers:\n", + "\n", + "1. [Water model](#Change-the-water-model)\n", + "2. [Solvent box shape and padding](#Change-the-solvent-box-shape-and-padding)\n", + "\n", + "The examples here use the `RelativeHybridTopologyProtocol`. The same settings exist for the other protocols, but the names of the groups differ when a protocol has more than one leg (e.g. `solvent_solvation_settings` and `complex_solvation_settings` for `AbsoluteBindingProtocol` and `SepTopProtocol`; `AbsoluteSolvationProtocol` uses a single `solvation_settings`). Check the settings of your protocol with `default_settings()`, and apply each change to every relevant leg.\n", + "\n", + "For more information on these settings see the [User Guide](https://docs.openfree.energy/en/stable/guide/index.html)." + ] + }, + { + "cell_type": "code", + "id": "a1000003", + "metadata": { + "ExecuteTime": { + "end_time": "2026-11-06T14:51:03.445154Z", + "start_time": "2026-11-06T14:50:48.691027Z" + } + }, + "source": [ + "from openff.units import unit\n", + "from openfe.protocols.openmm_rfe import RelativeHybridTopologyProtocol\n", + "\n", + "settings = RelativeHybridTopologyProtocol.default_settings()" + ], + "outputs": [], + "execution_count": 2 + }, + { + "cell_type": "markdown", + "id": "a1000004", + "metadata": {}, + "source": "## Changing the water model" + }, + { + "cell_type": "markdown", + "id": "a1000005", + "metadata": {}, + "source": [ + "Changing the water model for a system with a `SolventComponent` (a system to be solvated at run time) involves changing two coupled settings:\n", + "\n", + "- `solvation_settings.solvent_model`: the model OpenMM uses to solvate the system and generate the initial configuration.\n", + "- `forcefield_settings.forcefields`: the force fields used to parameterise the system. The water model should have a compatible structure to the selected force field. For example a 3-point water model should be used with a 3-point water force field, and a 4-point water model should be used with a 4-point water force field etc.\n", + "\n", + "For systems with an `ExplicitSolventComponent` (a system that is already solvated) or for crystal waters in a `ProteinComponent`, the force field determines the water model. It also adds any missing particles from the system, such as hydrogen or virtual sites, to match the force field description.\n", + "\n", + "The default water model is `tip3p`. The supported options are `tip3p`, `spce`, `tip4pew` and `tip5p`, so 4-point (`tip4pew`) and 5-point (`tip5p`) models are available. See the [OpenMM documentation](https://docs.openmm.org/latest/userguide/application/03_model_building_editing.html#adding-solvent) for details on solvation.\n", + "\n", + "Four- and five-point models add virtual site particles, which are handled when the system is solvated." + ] + }, + { + "cell_type": "code", + "id": "a1000006", + "metadata": { + "ExecuteTime": { + "end_time": "2026-11-06T15:14:14.418886Z", + "start_time": "2026-11-06T15:14:13.864227Z" + } + }, + "source": [ + "# Update the water model to a 4-point model\n", + "settings.solvation_settings.solvent_model = \"tip4pew\"\n", + "# Update the force field files to match the water model - note the protein force field is also set here and must be kept\n", + "settings.forcefield_settings.forcefields = [\n", + " \"amber/ff14SB.xml\",\n", + " \"amber/phosaa10.xml\",\n", + " \"amber/lipid17_merged.xml\",\n", + " \"amber/tip4pew_standard.xml\",\n", + "]" + ], + "outputs": [], + "execution_count": 4 + }, + { + "cell_type": "markdown", + "id": "a1000007", + "metadata": {}, + "source": [ + "**Things to consider**\n", + "\n", + "* Make sure the water model is compatible with the chosen protein and small-molecule force fields.\n", + "* Changing `solvent_model` only changes the water used to solvate. Check that the water and ion parameter files in `forcefield_settings.forcefields` match the chosen model.\n", + "* Models with virtual sites may take longer to simulate." + ] + }, + { + "cell_type": "markdown", + "id": "a1000008", + "metadata": {}, + "source": "## Changing the solvent box shape and padding" + }, + { + "cell_type": "markdown", + "id": "a1000009", + "metadata": {}, + "source": [ + "The size and shape of the simulation cell is controlled by `solvation_settings`. The default is a `dodecahedron` with `solvent_padding` of `1.5 nanometers` (the relative hybrid topology protocol reduces this to `1 nanometer` when the system contains a protein). The box shape can be `cube`, `dodecahedron` or `octahedron`.\n", + "\n", + "
\n", + "\n", + "**Note:** The simulation cell shape and solvent padding only apply when the system is solvated at run time. If the system is already solvated, these settings are ignored.\n", + "\n", + "
" + ] + }, + { + "cell_type": "code", + "id": "a1000010", + "metadata": { + "ExecuteTime": { + "end_time": "2026-11-06T15:42:34.475507Z", + "start_time": "2026-11-06T15:42:34.203786Z" + } + }, + "source": [ + "# Change the box shape and padding\n", + "settings.solvation_settings.box_shape = \"cube\"\n", + "# Use units from openff.units to specify the padding\n", + "settings.solvation_settings.solvent_padding = 1.2 * unit.nanometer" + ], + "outputs": [], + "execution_count": 5 + }, + { + "cell_type": "markdown", + "id": "a1000011", + "metadata": {}, + "source": [ + "**Things to consider**\n", + "\n", + "* `solvent_padding` is the minimum distance from the solute to the cell edge. For the same padding, a cube contains more water, and so is **slower to simulate**, than a dodecahedron or octahedron.\n", + "* Keep the padding large enough to stop the solute interact with its own periodic image, and larger than the nonbonded cutoff. If the padding is too small OpenMM will throw an error during the simulation.\n", + "* The box can alternatively be defined with `number_of_solvent_molecules` (with `box_shape`), `box_size` or `box_vectors`. These cannot be combined with `solvent_padding`, so set `solvent_padding = None` first." + ] + }, + { + "cell_type": "code", + "id": "a1000012", + "metadata": { + "ExecuteTime": { + "end_time": "2026-11-06T15:45:16.861364Z", + "start_time": "2026-11-06T15:45:16.820913Z" + } + }, + "source": [ + "# Alternative: define the box by the number of solvent molecules\n", + "settings.solvation_settings.solvent_padding = None\n", + "settings.solvation_settings.number_of_solvent_molecules = 3000" + ], + "outputs": [], + "execution_count": 6 + }, + { + "cell_type": "markdown", + "id": "a1000021", + "metadata": {}, + "source": [ + "## Create the Protocol" + ] + }, + { + "cell_type": "code", + "id": "a1000022", + "metadata": { + "ExecuteTime": { + "end_time": "2026-11-06T09:45:38.056604Z", + "start_time": "2026-11-06T09:45:38.044032Z" + } + }, + "source": [ + "protocol = RelativeHybridTopologyProtocol(settings=settings)" + ], + "outputs": [], + "execution_count": 8 + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}