Skip to content

Add note and warning boxes #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
IAlibay wants to merge 1 commit into
base: membrane_tutorial
Choose a base branch
from
Open

Add note and warning boxes #297

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 45 additions & 15 deletions openmm_rbfe/rbfe_membrane_protein.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,16 @@
"\n",
"This tutorial walks you through the process of setting up a relative binding free energy (RBFE) simulation campaign for a membrane protein system using OpenFE.\n",
"\n",
"RBFE calculations for membrane proteins require additional preparation compared to soluble protein systems. For soluble proteins, solvation and box setup are handled automatically within the OpenFE protocol. In contrast, membrane protein systems must be provided as fully built, solvated, and pre-equilibrated systems, including correctly defined box vectors.\n",
"You can prepare these systems using tools such as `packmol-memgen`, `CHARMM-GUI`, or `Maestro`. The membrane should be aligned with the coordinate axes to ensure that the barostat applies pressure correctly during the simulation.\n",
"\n",
"> **Note:** This tutorial currently emphasizes on importing inputs from `Maestro`, though the overall procedure is applicable to systems prepared with other tools."
"RBFE calculations for membrane proteins require additional preparation compared to soluble protein systems. For soluble proteins, solvation and box setup are handled automatically within the OpenFE protocol. In contrast, **membrane protein systems must be provided as fully built, solvated, and pre-equilibrated systems, including correctly defined box vectors**.\n",
"You can prepare these systems using tools such as `packmol-memgen`, `CHARMM-GUI`, or `Maestro`. The membrane should be aligned with the coordinate axes to ensure that the barostat applies pressure correctly during the simulation."
]
},
{
"cell_type": "markdown",
"id": "34e014d3-fedc-4b14-8d3c-2adc37a05762",
"metadata": {},
"source": [
"<div class=\"alert alert-block alert-info\"> <b>Note:</b> This tutorial currently emphasizes on importing inputs from <b>Maestro</b>, though the overall procedure is applicable to systems prepared with other tools. </div>"
]
},
{
Expand All @@ -32,12 +38,20 @@
"from rdkit import Chem"
]
},
{
"cell_type": "markdown",
"id": "a9cdc1e6-725f-41e8-91d4-55adea5cb5aa",
"metadata": {},
"source": [
"## Loading a PDB file with a pre-solvated protein-membrane system"
]
},
{
"cell_type": "markdown",
"id": "62ad3b9e-ee68-4735-ba77-8cf2aa585bbc",
"metadata": {},
"source": [
"## (Optional) Combining System Components into a Single PDB File\n",
"### (Optional) Combining System Components into a Single PDB File\n",
"\n",
"Maestro exports solvated protein-membrane systems in a non-standard PDB format that OpenMM cannot directly read. To simplify the workflow, it is often easier to save different parts of the system separately—such as the protein, lipids, and water—and then combine them into a single PDB file.\n",
"\n",
Expand Down Expand Up @@ -130,7 +144,7 @@
"id": "44aaba48-9664-4887-a6ec-f2946bda94b9",
"metadata": {},
"source": [
"## Load the system as a `ProteinMembraneComponent` with Periodic Box Vectors\n",
"### Loading the system as a `ProteinMembraneComponent` with Periodic Box Vectors\n",
"\n",
"The **`ProteinMembraneComponent`** requires periodic box vectors to define the simulation box. There are several ways to provide these vectors:\n",
"\n",
Expand All @@ -142,10 +156,15 @@
"\n",
"3. **Inferring from atomic positions** \n",
" Box vectors can be estimated from the atomic coordinates in the PDB file.\n",
" Caveat: This approach can be inaccurate if the PDB comes from a previous simulation and some atoms are positioned in periodic images. \n",
"\n",
"> **Maestro-specific note:** \n",
"> - When merging multiple components exported from Maestro, `CRYST` records are not currently preserved in the combined output PDB file. If one of the original input files contains valid `CRYST` information (for example, `a2a_water.pdb` in this case), you can load that file directly as a `ProteinMembraneComponent` and extract the box vectors from it, as shown below."
" Caveat: This approach can be inaccurate if the PDB comes from a previous simulation and some atoms are positioned in periodic images."
]
},
{
"cell_type": "markdown",
"id": "f40f5666-d8b4-4504-9c36-0f7da4d7ab6b",
"metadata": {},
"source": [
"<div class=\"alert alert-block alert-info\"> <b>Maestro-specific note:</b> When merging multiple components exported from Maestro, <b>CRYST</b> records are not currently preserved in the combined output PDB file. If one of the original input files contains valid <b>CRYST</b> information (for example, <b>a2a_water.pdb</b> in this case), you can load that file directly as a <b>ProteinMembraneComponent</b> and extract the box vectors from it, as shown below.</div>"
]
},
{
Expand Down Expand Up @@ -289,13 +308,17 @@
"\n",
"As a fallback, box vectors can be estimated from the atomic coordinates in the PDB file. An orthorhombic box is constructed by taking the minimum and maximum coordinates along each axis and expanding the resulting bounding box by an optional padding.\n",
"\n",
"> **Caveat:** \n",
"> - The system must be fully wrapped into a single periodic image. If atoms are split across periodic boundaries, the inferred box will be incorrect.\n",
"\n",
"\n",
"This approach is convenient when no box information is available, but should generally be used as a last resort."
]
},
{
"cell_type": "markdown",
"id": "c905621c-7796-47c8-91be-1da00715d9e7",
"metadata": {},
"source": [
"<div class=\"alert alert-block alert-warning\"> <b>Caveat:</b> The system must be fully wrapped into a single periodic image. If atoms are split across periodic boundaries, the inferred box will be incorrect. </div>"
]
},
{
"cell_type": "code",
"execution_count": 11,
Expand Down Expand Up @@ -1057,7 +1080,14 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.13.12"
"version": "3.12.11"
},
"widgets": {
"application/vnd.jupyter.widget-state+json": {
"state": {},
"version_major": 2,
"version_minor": 0
}
}
},
"nbformat": 4,
Expand Down