A protein-ligand simulation portfolio project connecting coarse-grained MD, graph learning, neural backmapping, and atomistic validation.
T4 lysozyme L99A / benzene · PDB 181L · GROMACS · Martini 3 · PyTorch · HEroBM
This repository demonstrates a complete, inspectable workflow on one molecular system. It includes 60 ns of recorded CG sampling and 12 atomistic trajectories of 2 ns each, with English source code, curated measurements, reproducible figures, and an explicit record of reconstruction failures and repairs.
flowchart LR
A[Martini CG trajectories] --> B[Geometric graph classifier]
A --> C[Six documented conformations]
C --> D[Pretrained HEroBM protein backmapping]
D --> E[Local geometry repair and validation]
E --> F[Two velocity replicas per conformation]
F --> G[Atomistic trajectory analysis]
There are two distinct GNN components:
- A small, project-trained distance-filter message-passing network classifies a geometric pocket-proximity label. It is compared with a logistic contact baseline.
- The pretrained HEroBM equivariant network reconstructs protein heavy atoms. It was used, not developed or trained in this project. Benzene uses rigid geometric placement and GAFF2/AM1-BCC parameters, not neural backmapping.
Atomistic candidates were selected by documented geometry and preparation quality, not by a validated GNN selection policy.
| Initial category | Trajectories | Fraction of saved frames inside the 0.6 nm pocket threshold |
|---|---|---|
| Pocket interior | 4 | 100% in each trajectory |
| Solvent | 4 | 0% in each trajectory |
| Pocket edge | 4 | 99.0%, 0%, 0%, 0% |
All 2,412 saved production frames passed the implemented stereochemistry and heavy-bond checks; none of the 12 production logs contained a LINCS warning. These checks do not constitute a complete structural validation suite.
The edge case is useful: the two velocity replicas from one starting conformation have markedly different pocket-proximity outcomes. Protein C-alpha RMSD and residue-contact retention are reported separately. Pocket proximity is a geometric measurement, not binding affinity or equilibrium occupancy.
The CG classifier and logistic contact baseline both achieved 1.000 held-out-replica AUROC on the geometric proxy task. This is an easy coordinate-derived target and provides no evidence of GNN superiority. Edge atomistic candidates overlap the classifier's training data and were adaptively replaced after preparation failures; the atomistic batch is not an independent ML benchmark.
Read the results and metric definitions, methods and limitations, the repair history, and release validation.
Python 3.11 or later:
python -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python make_figures.py
python -m unittest discover -s tests -v
python validate_package.pyThe figures use the committed measurements. This path does not download models, simulate molecules, or require a GPU. Geometry tests additionally require MDAnalysis; they are skipped explicitly when it is unavailable.
See REPRODUCIBILITY.md for the separate CG, classifier, backmapping, and atomistic stages. Linux or WSL Ubuntu, CUDA-enabled GROMACS, and separately installed model/parameterization dependencies are required for the tested GPU workflow.
The tested configuration was GROMACS 2025.4 and an RTX 4090. GMX can point to another compatible GROMACS executable. Recorded environment versions and upstream model revisions are included; this repository does not install system drivers or silently start background jobs.
Reproducibility boundary: the measurements and plots are reproducible from this repository. The original full trajectories, solvated input systems, and third-party runtime environments are not committed. Fresh simulations are a workflow reproduction, not a bitwise replay; original solvation was not deterministically seeded and GPU dynamics can diverge. Fixed frame times may not reproduce the same categories in a new run.
workflow/ Simulation, graph-learning, repair, and analysis commands
config/ Selected frames and recorded environment inventory
results/cg/ Graph dataset, small trained checkpoints, proxy metrics
results/atomistic/ Twelve observable series, summaries, candidate scores
results/quality/ Repair, stereochemistry, and mapping audit records
figures/ PNG and PDF outputs regenerated by make_figures.py
docs/ Methods, results, provenance, and reproduction instructions
tests/ Result reconciliation and PBC stereochemistry regressions
Original project work covers orchestration, the small geometric graph classifier, trajectory analysis, local postprocessing, validation, and reporting. The implementation was developed with AI coding assistance; dependency methods and pretrained models remain attributable to their authors.
HEroBM, Martini, GROMACS, Martinize2, MDAnalysis, ACPYPE/AmberTools, and the PDB structure are third-party resources. See THIRD_PARTY.md for references, provenance, and licensing boundaries. Original project code is licensed under Apache-2.0. No claim of a new force field, new backmapping architecture, binding-affinity prediction, or full paper reproduction is made.
