This project focuses on the extraction and validation of Collective Variables (CVs) for Molecular Dynamics (MD) simulations, specifically targeting T4 Lysozyme systems. It leverages the State Predictive Information Bottleneck (SPIB) framework to learn reaction coordinates and integrates them into OpenMM for enhanced sampling (Metadynamics).
The main objective is to identify the most relevant features (CVs) that distinguish between different conformational states of proteins (e.g., Closed vs. Open states of T4 Lysozyme) and use these features to drive sampling in MD simulations.
Key capabilities include:
- CV Extraction: Extracting and selecting important features (inverse distances, dihedrals, etc.) from MD trajectories.
- Biological Mapping: Mapping learned latent spaces back to biological features to understand the physical drivers of conformational changes.
- SPIB Integration: Training SPIB models to learn non-linear reaction coordinates.
- Transfer Learning: Testing the transferability of learned CVs across different states or systems.
- Enhanced Sampling: Implementing Metadynamics simulations using SPIB-learned CVs in OpenMM.
CVExtractionAndValidation/
├── CVExtractionBiologicalMapping.ipynb # Main analysis notebook for CV extraction and mapping
├── openMMwithSPIBDemo.ipynb # End-to-end demo of OpenMM simulation + SPIB training
├── SamplingSizeAblation.ipynb # Analysis of sampling size effects
├── AcceleratedMDcompletedScript.ipynb # Script for accelerated MD runs
├── scripts/ # Modular pipeline scripts
│ ├── 01_prep_system.py # System preparation (PDB -> OpenMM System)
│ ├── 02_run_unbiased.py # Run unbiased MD simulation
│ ├── 03_train_spib.py # Train SPIB model on trajectory data
│ ├── 04_export_spib_model.py # Export trained model for C++ integration
│ ├── 05_run_metad_spib.py # Run Metadynamics using SPIB CVs
│ ├── spib_lib.py # Shared library for SPIB models and utils
│ └── setup.sh # Environment setup script
├── Efficiency Curve Results/ # Results from efficiency analysis
├── OtherAnalysis(Non Conclusive)/ # Exploratory analysis files
└── Plots/ # Generated plots and figures
-
Prerequisites:
- Python 3.8+
- Conda (recommended)
-
Dependencies: The project relies on the following key libraries:
openmmpytorchmdtrajnumpyscipymatplotlib
-
Environment Setup: You can use the provided
scripts/setup.shto set up the environment (check the script for details) or install dependencies manually:conda install -c conda-forge openmm mdtraj conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia pip install matplotlib scipy
CVExtractionBiologicalMapping.ipynb: Use this notebook to perform deep analysis on existing trajectories. It covers data loading, feature computation (inverse distances), feature selection (variance filtering), model training, and transfer learning experiments.openMMwithSPIBDemo.ipynb: Run this notebook to see a complete workflow from scratch. It loads a PDB file, sets up the system in OpenMM, runs a short simulation, computes features, and trains a simple SPIB model.
The scripts/ directory contains a step-by-step pipeline for production runs:
- Prepare System:
python scripts/01_prep_system.py
- Run Unbiased MD:
python scripts/02_run_unbiased.py
- Train SPIB Model:
python scripts/03_train_spib.py
- Export Model:
python scripts/04_export_spib_model.py
- Run Metadynamics:
python scripts/05_run_metad_spib.py
- SPIB (State Predictive Information Bottleneck): A deep learning framework that learns a low-dimensional reaction coordinate by maximizing the predictive information about future states while compressing the input.
- Inverse Distances: Often used as input features for the model as they are translation/rotation invariant and physically meaningful for contacts.
- Transfer Learning: Evaluating if a model trained on one state (e.g., Closed) can effectively describe or drive sampling in another state (e.g., Open).
- Efficiency Curves: Analysis of how sampling efficiency scales with data size and model parameters can be found in
Efficiency Curve Results/. - Visualizations: Plots of latent spaces, loss curves, and physical observables are saved in
Plots/.
If you use this code or the SPIB framework in your research, please cite the following papers:
-
SPIB: Wang, D., & Tiwary, P. (2021). State predictive information bottleneck. The Journal of Chemical Physics, 154(13), 134111. https://doi.org/10.1063/5.0038198
-
OpenMM: Eastman, P., Galvelis, R., Peláez, R. P., Abreu, C. R. A., Farr, S. E., Gallicchio, E., ... & Markland, T. E. (2023). OpenMM 8: Molecular Dynamics Simulation with Machine Learning Potentials. The Journal of Physical Chemistry B, 128(1), 109-116. https://doi.org/10.1021/acs.jpcb.3c06662