| name | biomolecular-md-workflow |
| description | Plan, run, review, and report defensible biomolecular docking and molecular dynamics workflows. Use for protein-ligand docking, docking-pose review, docking-to-MD validation, protein-only MD, membrane-protein MD, multimer modeling, mutation/redocking/MD comparisons, ligand or lipid parameterization decisions, trajectory analysis, free-energy escalation, and cases where MD should be avoided or caveated because the biological assembly, membrane state, protonation, ligand parameters, or starting pose is not reliable. |
Biomolecular MD Workflow
Core Rule
Treat biomolecular modeling as a question-driven evidence workflow, not as a fixed docking-then-MD recipe. First decide what claim the computation is supposed to support, then choose the least overclaimed method that can test it. Do not start production MD until the biological assembly, chemical states, force-field coverage, environment, and starting pose/model are defensible.
For detailed protocols and edge cases, read the relevant reference file:
- references/methodology.md: overall method routing, docking, MD, membrane systems, mutations, and free-energy escalation.
- references/quality_gates.md: go/no-go checks, evidence levels, controls, and safe conclusion wording.
- references/project_audit_trail.md: project directory layout, metadata schema, reproducibility records, and handoff requirements.
- references/preparation_checklists.md: receptor, ligand, nonstandard chemistry, membrane, multimer, nucleic-acid, and PTM preparation.
- references/tools_and_analysis.md: tool choice matrix and analysis cookbook by question type.
- references/empirical_rules.md: practical docking/MD heuristics, score interpretation rules, sampling rules of thumb, and common red flags.
- references/literature_review.md: method sources that shaped this workflow and gaps to revisit.
Use bundled scripts when starting or auditing a project:
scripts/init_project.py <project_dir> creates the standard project directory layout and a metadata.yaml template.scripts/check_metadata.py <metadata.yaml> checks required metadata fields and flags red quality gates or under-replicated MD; add --strict before final handoff.
Question Router
Pick the branch before choosing tools:
- Binding-site discovery: use structure audit, pocket/site prediction, blind or ensemble docking, and controls; MD is optional follow-up.
- Pose validation: use focused redocking, multi-seed clustering, local minimization, then replicated short MD if parameters are reliable.
- Affinity ranking: docking is only a screen; use matched protocols, controls, and escalate to MM/GBSA only as rough ranking or RBFE/ABFE for quantitative claims.
- Mutation mechanism: separate direct-contact mutations from fold/interface/membrane-disrupting mutations; compare WT and mutant with identical protocols.
- Membrane/channel hypothesis: first establish topology, membrane orientation, oligomer, pore geometry, and lipid environment; do not infer channels from soluble fragments.
- Protein conformational stability: use apo/holo comparative MD, replicate RMSD/RMSF/contact networks, and domain/interface metrics.
- Protein-protein/nucleic-acid complexes: audit biological assembly and interface evidence; docking/MD must preserve stoichiometry, cofactors, ions, and nucleic-acid chemistry.
- IDR/flexible-loop question: static docking is weak; use ensemble modeling, restraints, or enhanced sampling and report uncertainty.
- Covalent ligand/PTM/metalloprotein/glycoprotein: parameterization and chemistry define feasibility; stop if parameters cannot be validated.
Triage First
Before docking or MD, establish:
- Biological question: binding site, pose stability, mechanism, mutation effect, membrane/channel hypothesis, affinity ranking, or conformational stability.
- Structure status: experimental vs predicted, full-length vs fragment, missing loops/domains, oligomeric state, biological assembly, membrane orientation, cofactors, metals, PTMs, disulfides.
- Ligand chemistry: protonation/tautomer, formal charge, stereochemistry, covalent vs noncovalent, lipid-like vs drug-like, metal coordination, available force-field parameters.
- Environment: soluble protein, membrane protein, lipid-binding protein, protein-protein complex, nucleic acid complex, glycoprotein, metalloprotein, intrinsically disordered region, coarse-grained system, or large multimer.
- Evidence threshold: quick plausibility check, publication-grade mechanistic support, or quantitative affinity/free-energy estimate.
If any item changes the physical system, stop and resolve it before interpreting scores.
Quality Gate
Before running expensive work, assign each gate as green, yellow, or red:
- Structure/assembly: correct biological unit, sequence mapping, model confidence, missing regions, and interface/membrane plausibility.
- Chemistry: ligand/protein protonation, stereochemistry, tautomer, cofactors, metals, PTMs, glycans, lipids, and covalent bonds.
- Parameters: force-field coverage for every component, inspected charges/atom types, no missing bonded terms.
- Environment: solvent, membrane, ions, pH/salt, restraints, oligomer, and biological context.
- Controls: apo/holo, positive/negative ligands, decoys, alternative receptor states, charge-state controls, or mutant controls when relevant.
- Reproducibility: commands, versions, seeds, box definitions, input files, parameter files, logs, metadata, and analysis scripts are recorded.
Red gates block the requested claim. Yellow gates allow exploratory work only with downgraded language.
Universal Workflow
- Gather structures and annotations from primary sources when possible: PDB/mmCIF biological assembly, UniProt sequence/features, AlphaFold/ColabFold/AF3 confidence metrics, literature on oligomer/membrane state.
- Inspect the starting structure visually and geometrically. Confirm chain mapping, residue numbering, biological assembly, missing atoms, clashes, and whether predicted domains are usable.
- Define all chemistry: protonation, tautomer, stereochemistry, covalent bonds, metals, cofactors, PTMs, glycans, lipids, waters, ions, and nonstandard residues.
- Choose the environment: solvent, membrane, lipid composition, pH/salt, cofactors, restraints, oligomer stoichiometry, and whether coarse-graining is appropriate.
- Choose the modeling branch: docking, ensemble docking, protein-protein docking, flexible fitting, classical MD, membrane MD, enhanced sampling, or free energy.
- Run the minimum screen first, then repeat with independent seeds, controls, and alternative reasonable starting models before making claims.
- Escalate only when the previous rung is defensible: focused redocking before MD, short replicated MD before long production, production MD before free energy.
- Analyze with predeclared metrics tied to the question, not generic RMSD plots alone.
- Report limitations explicitly: model uncertainty, sampling limits, force-field assumptions, environment mismatch, score uncertainty, and what evidence would change the conclusion.
Method Selection
- Docking: use for generating binding hypotheses and comparing poses within a controlled setup, not as standalone proof of affinity.
- Ensemble docking: use when receptor flexibility, loop motion, apo/holo differences, or predicted-model uncertainty affects the site.
- Classical all-atom MD: use for local stability, contact persistence, conformational relaxation, membrane environment, and mechanistic plausibility.
- Coarse-grained MD: use for large membranes, lipid sorting, oligomerization, long-timescale organization, or exploratory membrane insertion; backmap for atomistic detail.
- Enhanced sampling: use when transitions, unbinding, permeation, loop opening, or rare events are central and ordinary MD is unlikely to sample them.
- Free-energy methods: use RBFE/ABFE for quantitative ligand ranking only when binding modes, chemistry, parameters, and convergence can be controlled.
- Normal-mode/elastic/network analyses: use for fast domain-motion hypotheses, not ligand-specific energetic claims.
- Do-not-run outcome: choose this when the structure, assembly, membrane state, ligand chemistry, or parameters are too uncertain for the requested claim.
Default Starting Parameters
Use these only as starting points for small-molecule docking and atomistic MD; choose other protocols for protein-protein, nucleic acids, coarse-grained, enhanced-sampling, or free-energy tasks. Justify deviations in the report:
- Focused docking box: cover the pocket plus at least 5-8 A padding around the ligand; common starting box is 22-30 A per side for flexible fatty acids or shallow grooves.
- Blind docking box: cover the biological assembly/domain being tested, but avoid interpreting scores from huge boxes without reclustering and focused redocking.
- Vina exhaustiveness: start at 32 for ordinary small ligands, 64 for flexible ligands/lipids, and 128 when the pose is unstable or the pocket is broad.
- Vina seeds: use at least 5 seeds for claims about recurrence; use 10+ seeds for highly flexible ligands, shallow sites, or competing pockets.
- Vina modes: keep 20 modes per run for site discovery and clustering; fewer modes are acceptable only after the site is fixed.
- Local docking/relaxation box: center on the candidate pose and use a tight box that still allows side-to-side ligand movement, typically 10-16 A around the ligand.
- Contact cutoffs: use 3.5-4.0 A for polar/salt-bridge screening and 4.5-5.0 A for hydrophobic neighborhood/contact occupancy, then state the cutoff.
- Pose convergence: report score mean/sd, top-pose site recurrence, contact occupancy, and seed-to-seed heavy-atom or COM RMSD instead of only best score.
- Short MD sanity check: run at least 3 replicas when claiming pose retention; 10-50 ns can reject bad poses but is not proof of high-affinity binding.
- Production MD: use longer replicated runs chosen by system timescale; for qualitative ligand stability, prefer 3 replicas of 50-200 ns over one long unreplicated run.
Decision Rules
- Prefer experimental biological assemblies over asymmetric units or arbitrary predicted multimers.
- For predicted structures, trust local high-confidence domains more than global multimer topology unless the inter-chain confidence supports it.
- For membrane proteins, do not use a soluble AF/AF3 multimer topology as a membrane-channel model unless membrane orientation and topology are independently constrained.
- For ligand ranking by docking, require multi-seed recurrence and chemically comparable sites; small score gaps under about 0.5-1.0 kcal/mol are weak unless supported by contacts and controls.
- For docking-to-MD validation, require at least 3 replicas for qualitative stability claims and stronger sampling/free-energy methods for affinity claims.
- For mutations, separate direct contact tests from structural-disruption tests. Avoid interpreting destabilizing core/disulfide mutations as clean binding-site evidence.
Output Standards
Always produce a concise audit trail:
- Inputs: structure IDs/files, sequence mapping, ligand IDs/states, force fields, membrane/lipid model if any.
- Execution environment: software versions, package/environment file, container image or workflow engine, hardware/GPU when relevant.
- Docking setup: receptor, ligand prep, boxes, seeds/exhaustiveness, scoring function, controls.
- MD setup: software, force fields, solvent/membrane/ions, minimization/equilibration, temperature/pressure coupling, timestep, restraints, length, replicas.
- Analysis: exact metrics, contact cutoffs, alignment selections, frame intervals, convergence checks.
- Conclusion: what is confirmed, what is plausible, what is not supported, and what would be needed to upgrade confidence.
Use evidence-matched wording:
- "Docking suggests" for pose/site hypotheses.
- "Multi-seed docking supports recurrence" when pose/site clusters recur under matched settings.
- "Short MD rejects or supports local pose retention" for replicated short trajectories.
- "Replicated production MD supports stability/mechanism" only when prespecified metrics converge across replicas.
- "Free-energy calculations support ranking" only when protocol, convergence, and uncertainty are reported.
- "Not supported" when the model state, parameters, sampling, or controls do not justify the claim.
