DOCSEARCHbyAlgolia
Submit Docs

OpenMMDL

repository·main·Indexed 41 days ago

https://github.com/wolberlab/openmmdl

An interface for the setup, simulation, and analysis of molecular dynamic (MD) simulations of protein-ligand complexes using OpenMM. It provides a Flask-based web interface for preparing simulation files, tools for running simulations, and analysis commands to identify protein-ligand interactions and binding modes.

Tokens
29.4K
Snippets
92
Records
138
Agent score
50%

What's inside OpenMMDL

  1. What is OpenMMDL?

    main

    OpenMMDL is a workflow designed for the setup, simulation, and analysis of OpenMM molecular dynamics (MD) simulations specifically for protein-ligand complexes. It is composed of three primary functional components:

    1. OpenMMDL Setup: A webserver-based tool used to modify protein structures and generate the necessary input files for MD simulations.
    2. OpenMMDL Simulation: A component that executes OpenMM MD simulations using the files prepared in the Setup phase. It also handles post-processing of trajectories using MDTraj and MDAnalysis.
    3. OpenMMDL Analysis: A tool for analyzing protein-ligand interactions within the resulting OpenMM MD simulation trajectories.

  2. Understand OpenMMDL Simulation Output Structure

    main

    The OpenMMDL Simulation script generates a structured set of output folders and files. Understanding this hierarchy is essential for locating input files, restarting simulations from checkpoints, or finding processed trajectories for analysis.

    The output is organized into the following main directories:

    1. Input Files: Contains the original PDB, SDF, and MOL2 files used to start the simulation.
    2. Checkpoints: Contains .chk files used to restart the MD simulation at specific intervals.
    3. MD Files: Contains intermediate files from the simulation process, including:
      • Pre MD: Prepared PDB files (e.g., with solvent or membrane).
      • Minimization Equilibration: Topology files after OpenMM energy minimization and equilibration.
      • MD Output: The raw trajectory (.dcd) and topology (.pdb) files.
    4. MD Postprocessing: Contains centered and unaligned trajectory files in various formats (.dcd, .xtc, .pdb, .gro).
    5. Final Output: The primary folder for analysis, containing processed files organized by atom selection (e.g., All_Atoms or Prot_Lig).

  3. Understand OpenMMDL Analysis output files

    main

    Analysis results are stored in the current working directory. Key outputs include:

    • df_all.csv: Main raw data source containing all interactions found in the trajectory (one row per interaction per frame).
    • Barcodes/: Folder containing .png barcode figures for each interaction type. Includes a Waterbridge_Piecharts/ subfolder with piecharts of water interactions (using waterid).
    • Binding_Modes_Markov_States/: Contains .png images of all found binding modes (arranged by occurrence percentage) and Markov chain plots showing transition probabilities at 1%, 5%, and 10% cutoffs.
    • Visualization files: Files used for point cloud visualization:
      • clouds.json: Point cloud information.
      • interacting_waters.pdb: Topology for visualization.
      • interacting_waters.dcd: Trajectory for visualization.
      • interacting_waters.pkl: Pickle file of interacting water IDs.

  4. Configure Glycoprotein receptors using the Amber path

    main

    The Amber path in OpenMMDL Setup supports a specialized Glycoprotein receptor type for proteins with covalently attached N- or O-linked glycans.

    How it works:

    1. Detection: The system detects sugar residues by PDB residue names (NAG, NDG, BMA, MAN, FUC, FUL) and identifies glycosidic linkages using CONECT records (or a distance scan if CONECT is missing).
    2. Renaming: Residues and atoms are automatically renamed to follow GLYCAM-06j-1 conventions (e.g., NAG $\rightarrow$ 0YB/4YB, MAN $\rightarrow$ 0MA/3MA/6MA).
    3. Bonding: Explicit bond statements for protein-glycan and glycan-glycan covalent links are generated and injected into the tleap.in file.
    4. Forcefields: It automatically sources the chosen protein force field (e.g., leaprc.protein.ff14SB) and the glycan force field (defaults to leaprc.GLYCAM_06j-1).

    Limitations:

    • Only common N-glycan core sugars are currently supported.
    • Unrecognized sugar codes or non-canonical linkage patterns will trigger a descriptive error.

  5. Perform stable water analysis

    main

    To analyze if stable water molecules are present during MD, use the -w True flag during analysis.

    Process:

    1. Collects water molecules that move minimally during MD.
    2. Creates clusters based on the --watereps value (in Angstroms).
    3. Exports clusters as PDBs for different occupancy thresholds (25%, 50%, 75%, 90%, and 99% of the MD).
    4. Generates a PDB of "representative water molecules" (one per cluster) which can be loaded onto a protein.
    5. Outputs a CSV file containing interactions between protein residues and these stable waters.

    This is useful for inhibitor optimization and determining structure-activity relationships (SAR).

  6. Restart an MD Simulation using Checkpoints

    main

    The Checkpoints folder contains saved states that allow you to restart an MD simulation. The script saves checkpoints at regular intervals:

    • checkpoint.chk: Saved every 10,000 steps.
    • 10x_checkpoint.chk: Saved every 100,000 steps.
    • 100x_checkpoint.chk*: Saved every 1,000,000 steps (optional).

  7. Choose between PDBFixer and Amber paths for input file creation

    main

    OpenMMDL Setup provides two distinct workflows for preparing input files for OpenMMDL Simulation:

    1. PDBFixer Path

    Used when you have a .pdb file of the protein. This path handles the preparation and simulation setup directly from the PDB.

    Available Forcefields and Water Models (PDBFixer):

    | Forcefield Group | Water Models | | :--- | : | | AMBER14 / AMBER19 | TIP3P, TIP3P-FB, SPC/E, TIP4P-Ew, OPC3, OPC | | AMBER99SB / AMBER99SB-ILDN / AMBER03 / AMBER10 | TIP3P, TIP3P-FB, SPC/E, TIP4P-Ew, TIP5P, OPC3, OPC | | CHARMM36 | SPC/E, TIP4P-Ew, TIP5P, CHARMM default, TIP3P-PME-B, TIP3P-PME-F, TIP4P-2005, TIP5P-Ew | | CHARMM36 2024 | SPC/E, TIP4P-Ew, TIP5P, CHARMM default, TIP3P-PME-B, TIP3P-PME-F, TIP4P-2005, TIP5P-Ew |

    2. Amber Path

    Used when you have (or want to create) prmtop and inpcrd files. You can either provide existing topology/coordinate files or generate them from PDB files of the receptor and ligand.

    Note: This path allows for custom forcefields from AmberTools 22.0 via a designated textbox.

  8. Understand OpenMMDL versioning with Versioneer

    main

    OpenMMDL uses Versioneer to automatically infer the installed version based on git tags and commit distance.

    • The version format follows PEP 440.
    • If the current commit matches a git tag, the version is exactly the tag (e.g., openmmdl-0.1.2).
    • If the commit is ahead of the last tag, the version is appended with +X (where X is the number of commits ahead) and -YYYYYY (where Y is the git commit hash).

  9. OS Compatibility for OpenMMDL components

    main

    OpenMMDL support varies depending on the operating system:

    • Linux and Mac: Full support for OpenMMDL, OpenMMDL Setup, and OpenMMDL Analysis.
    • Windows: Only OpenMMDL Analysis is compatible. OpenMMDL Setup and OpenMMDL Simulation are currently incompatible with Windows.

  10. Use the tutorial panel in OpenMMDL Setup

    main

    The tutorial panel is located in the lower right corner of the Setup interface and provides guidance throughout the workflow.

    Key Panel Features:

    • Progress Tracking: Shows the current page, current step, and progress on the current page.
    • Visual Guidance: Highlights the specific control required for the current step and labels it with the expected input.
    • Automated Actions: Steps with action buttons (e.g., Set AMBER19 or Add water box) can apply the correct choice automatically when clicked. The panel displays a green Done mark once the page matches the step requirements.
    • Navigation:
      • Back and Next move between steps on the current page.
      • Restart page returns to the first step of the current page.
      • Use the page's own Continue button to move to the next page (standard Setup behavior).
    • Documentation & Files: Open docs links to the relevant documentation section. Download files is available on pages requiring file uploads.
    • Exiting: Click Exit in the panel or Exit Tutorial in the header to end the tutorial. The tutorial state persists across page reloads and Back/Start Over actions until explicitly exited. On the final step, the button changes to Finish tutorial.

  11. Use Interactive Tutorial Mode in OpenMMDL Setup

    main

    OpenMMDL Setup includes a guided tutorial mode to help users learn the workflow.

    How to access:

    • Click the Tutorials button in the Setup header.
    • Or, open the tutorial section on the first page.

    Current Workflow: PDB small molecule The tutorial applies a specific set of configurations to demonstrate the tool:

    • Forcefield: AMBER19 with OPC3 water model.
    • Complex Type: Single complex (includes a second ligand copy as an additional molecule).
    • Small Molecule Parameterization: SMIRNOFF.
    • Environment: pH 7.4, water box with ionic strength 0.15 M.
    • Simulation Length: 10 ns.

    Handling Files: Since the browser cannot access local files automatically, use the Download files button within the Setup interface to get the required example files:

    • 5wyz_tutorial_receptor.pdb (Receptor)
    • 7VF_A.sdf (First ligand copy)
    • 7VF_B.sdf (Second ligand copy/additional molecule)

    When prompted by the tutorial, upload the receptor first, then 7VF_A.sdf, and finally 7VF_B.sdf.

  12. Add custom static files to Sphinx documentation

    main

    To include custom static assets like stylesheets, JavaScript, or logos in the documentation, place them in the _static directory. Files in this directory are relative to the conf.py file's location.

    Note that files in this directory are copied after the built-in static files. This means if you provide a file with the same name as a built-in file (e.g., default.css), your version will overwrite the built-in one.

    templates_path = ['_static']