Cryo-EM Refinement & XModeScore Tutorials
The following tutorials demonstrate density-coupled QM/MM refinement and XModeScore for Cryo-EM using the DivCon Suite—primarily via qmechanic (no Phenix required). Optional examples using qbdivcon are included where helpful.
Note: these same calculations can be performed with X-ray data. Simply substitute X-ray density (in MTZ or sf.cif format) and change the –experiment option from CryoEM to Xray.
- Method Summary
- Prerequisites & Environment
- Tutorial #1: Cryo-EM QM/MM refinement on 7JSY (qmechanic)
- Tutorial #2: Cryo-EM ONIOM refinement on 7EFC (qbdivcon)
- Tutorial #3: Cryo-EM XModeScore on 7JSY (qbdivcon)
- Tutorial #4: Cryo-EM XModeScore on 7JSY (qmechanic)
- Tutorial #5: Protonation/Preparation of 7W9W (qmechanic)
- Tutorial #6: Protonation + Missing Loops on 7EFC (qmechanic)
- Tutorial #7: Multi-Blob Docking on 7JSY (qmechanic)
- Output & Validation Metrics
- Key Resources
(If you’d like to be notified of updates, email support@quantumbioinc.com.)
Method Summary
Goal: Improve protein:ligand model accuracy in Cryo-EM maps by coupling real-space density agreement with semi-empirical QM/MM energy (DivCon). The approach emphasizes chemically consistent protonation/tautomer states, reduced ligand strain, and better local electrostatics (including ions/solvent) at medium/variable resolution.
- Density-coupled objective: real-space map agreement + SE-QM energy in one target (qmechanic/qbdivcon).
- Automated prep: protonation and model completion (gaps/loops) where applicable.
- XModeScore: enumerates and ranks protomers/tautomers/stereoisomers against the map, using strain + difference-density statistics.
- Notes for Cryo-EM: works directly with Cryo-EM maps; Phenix is not required for the qmechanic-based Cryo-EM workflows below.
Prerequisites & Environment
- Install the DivCon Discovery Suite and source the environment:
source /path/to/DivConDiscoverySuite/etc/qbenv.sh
- Ensure the following binaries resolve on your PATH:
$QBHOME/bin/qmechanic(required)$QBHOME/bin/qbdivcon(optional; only for qbdivcon tutorials)
- Download inputs (PDB with H where indicated, Cryo-EM map files) from the links in each tutorial.
Tutorial #1: Cryo-EM QM/MM refinement on PDBid:7JSY (qmechanic)
Objective: Run density-coupled QM/MM refinement with ligand in the QM region using qmechanic. Input is a protonated PDB and the experimental Cryo-EM map.
- Create a clean directory and fetch inputs:
wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/7jsy+H.pdb wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/emd_22463.map
- Execute QM/MM refinement (ligand I3C as QM):
qmechanic 7jsy+H.pdb emd_22463.map \ --resolution 1.8 --experiment cryoEM \ --opt all 35 0.01 \ --qm-region /A/I3C/501// 0.0 0.0 \ -h pm6 amberff14sb -O \ -p 7jsy+H_refined.pdb 7jsy+H_refined.mtz \ -v2 --np 2
| Switch / Arg | Value | Description |
| (positional) | 7jsy+H.pdb | Input model (protonated PDB). |
| (positional) | emd_22463.map | Cryo-EM map file used for the real-space target. |
| –experiment | cryoEM | Select Cryo-EM mode (map-based real-space scoring/gradients). |
| –resolution | 1.8 | Nominal map resolution; informs weighting/filters. |
| –opt | all 35 0.01 | Global optimization control (scope, cycles, tolerance). |
| –qm-region | /A/I3C/501// 0.0 0.0 | Select ligand as QM region; trailing numbers are buffer radii (region/buffer Å). |
| -h | pm6 amberff14sb | Hamiltonians: PM6 for QM; AMBER ff14SB for MM. |
| -O | (flag) | Overwrite/force output where applicable. |
| -p | PDB MTZ | Output refined coordinates and MTZ map coefficients. |
| -v2 | (flag) | Increase console/log verbosity. |
| –np | 2 | CPU threads for parallel parts of the run. |
Notes: This performs a local, chemically aware refinement of the ligand environment in real space. Monitor ligand strain and map-model metrics post-run.
Tutorial #2: Cryo-EM ONIOM refinement on PDBid:7EFC (qbdivcon)
Objective: Demonstrate ONIOM (QM/MM) refinement via the qbdivcon wrapper (optional path; qmechanic alone is sufficient for Cryo-EM).
- Fetch inputs:
wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/7efc+H.pdb wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/emd_31083.map
- Run qbdivcon (skip protonation since input is +H):
qbdivcon \ --pdbfile 7efc+H.pdb \ --sfFile emd_31083.map \ --experiment cryoEM \ --resolution 1.7 \ --protonation skip \ --engine divcon \ --qmMethod pm6 \ --mmMethod amberff14sb \ --resname BTN \ --chains All \ --np 8 -v 2 -O
| Switch / Arg | Value | Description |
| –pdbfile | 7efc+H.pdb | Input model (protonated PDB). |
| –sfFile | emd_31083.map | Cryo-EM map file. |
| –experiment | cryoEM | Enable Cryo-EM real-space target. |
| –resolution | 1.7 | Nominal resolution to inform weights/filters. |
| –protonation | skip | Skip initial protonation (input is already +H). |
| –engine | divcon | Use DivCon’s internal refinement engine. |
| –qmMethod | pm6 | QM Hamiltonian (semiempirical). |
| –mmMethod | amberff14sb | MM force field for non-QM region. |
| –resname | BTN | Filter/selection convenience for ligand(s) of interest. |
| –chains | All | Consider all chains during setup/refinement. |
| –np | 8 | Threads for parallel work. |
| -v | 2 | Verbosity level. |
| -O | (flag) | Overwrite outputs if present. |
Tutorial #3: Cryo-EM XModeScore on PDBid:7JSY (qbdivcon)
Objective: Enumerate/rank protomers/tautomers/flips in Cryo-EM using XModeScore via qbdivcon.
- Fetch inputs:
wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/7jsy+H.pdb wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/emd_22463.map
- Run XModeScore scan:
qbdivcon \ --pdbfile 7jsy+H.pdb \ --sfFile emd_22463.map \ --experiment cryoEM \ --resolution 1.8 \ --XmodeScore \ --protomers "-1..1" \ --exploreFlip \ --protonation skip \ --engine divcon \ --qmMethod pm6 \ --mmMethod amberff14sb \ --np 8 -v 2 -O
| Switch / Arg | Value | Description |
| –pdbfile | 7jsy+H.pdb | Input model (with hydrogens). |
| –sfFile | emd_22463.map | Cryo-EM map. |
| –experiment | cryoEM | Cryo-EM real-space scoring. |
| –resolution | 1.8 | Nominal resolution. |
| –XmodeScore | (flag) | Enable XModeScore pipeline (strain + density stats). |
| –protomers | “-1..1” | Enumerate charge/protomer range to test. |
| –exploreFlip | (flag) | Explore flips/rotamers where applicable. |
| –protonation | skip | Do not reprotonate enumerated states (keep input H). |
| –engine | divcon | Use internal DivCon scoring/refinement engine. |
| –qmMethod | pm6 | QM level for strain/interaction energies. |
| –mmMethod | amberff14sb | MM level for environment. |
| –np | 8 | Parallel threads. |
| -v | 2 | Verbosity level. |
| -O | (flag) | Overwrite outputs. |
Tutorial #4: Cryo-EM XModeScore on PDBid:7JSY (qmechanic)
Objective: Perform the same style of XModeScore exploration directly via qmechanic, including flip/chirality checks and optional density-driven docking.
- Fetch inputs:
wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/7jsy+H.pdb wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/emd_22463.map
- Run XModeScore (enumeration + scoring):
qmechanic 7jsy+H.pdb emd_22463.map \ --resolution 1.8 --experiment cryoEM \ --ligand /A/I3C/501// \ --protomer [-1..1] /A/I3C/501// \ --flip on --chirality on \ --dock LIGAND opt torsion pocket 100 0.01 \ --np 8 -h amberff14sb \ --xmodescore opt all \ -O -v2
| Switch / Arg | Value | Description |
| (positional) | 7jsy+H.pdb | Input PDB with hydrogens. |
| (positional) | emd_22463.map | Cryo-EM map. |
| –experiment | cryoEM | Use real-space Cryo-EM target. |
| –resolution | 1.8 | Nominal resolution for weighting/filters. |
| –ligand | /A/I3C/501// | Primary ligand selection used for enumeration/docking. |
| –protomer | [-1..1] /A/I3C/501// | Enumerate protomer/charge states for the selection. |
| –flip | on | Evaluate flipped orientations where meaningful. |
| –chirality | on | Evaluate chiral alternatives if allowed. |
| –dock | LIGAND opt torsion pocket 100 0.01 | Density-aware docking mode; torsional optimization in pocket (iterations/tol shown). |
| –xmodescore | opt all | Run XModeScore after placement with optimization. |
| -h | amberff14sb | Force field context; QM is implied where needed during scoring. |
| –np | 8 | Parallel threads. |
| -O | (flag) | Overwrite outputs. |
| -v2 | (flag) | Verbose logging. |
Tutorial #5: Protonation/Preparation of PDBid:7W9W (qmechanic)
Objective: Use DivCon’s preparation pipeline to protonate a Cryo-EM structure and write a new +H model.
- Fetch inputs:
wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/7w9w.pdb wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/emd_32377.map
- Prepare/protonate:
qmechanic 7w9w.pdb emd_32377.map \ --resolution 2.0 \ --experiment cryoEM \ --prepare \ -p 7w9w+H.pdb \ -h amberff14sb \ -O -v2 --np 2
| Switch / Arg | Value | Description |
| (positional) | 7w9w.pdb | Input model (unprotonated). |
| (positional) | emd_32377.map | Cryo-EM map. |
| –experiment | cryoEM | Enable Cryo-EM real-space context. |
| –resolution | 2.0 | Nominal map resolution. |
| –prepare | (flag) | Run automated preparation (perception + protonation pipeline). |
| -p | 7w9w+H.pdb | Write protonated output PDB. |
| -h | amberff14sb | Force field context for preparation. |
| –np | 2 | Parallel threads. |
| -O | (flag) | Overwrite outputs. |
| -v2 | (flag) | Verbose logging. |
Tip: Inspect histidine/acid/base states and nearby ions/solvent sites after automated protonation—these influence density-coupled refinement and XModeScore.
Tutorial #6: Protonation + Missing Loops on PDBid:7EFC (qmechanic)
Objective: Extend preparation to include model completion (gaps/truncations) before refinement.
- Fetch inputs:
wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/7efc.pdb wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/emd_31083.map
- Prepare with gap handling:
qmechanic 7efc.pdb emd_31083.map \ --resolution 1.7 \ --experiment cryoEM \ --prepare all \ -p 7efc+H.pdb \ -h amberff14sb \ -O -v2 --np 2
| Switch / Arg | Value | Description |
| (positional) | 7efc.pdb | Input model (may contain gaps/truncations). |
| (positional) | emd_31083.map | Cryo-EM map. |
| –experiment | cryoEM | Real-space Cryo-EM context. |
| –resolution | 1.7 | Nominal resolution. |
| –prepare | all | Full preparation (protonation + gap/loop completion as supported). |
| -p | 7efc+H.pdb | Write completed/protonated output model. |
| -h | amberff14sb | Force field context during prep. |
| –np | 2 | Parallel threads. |
| -O | (flag) | Overwrite outputs. |
| -v2 | (flag) | Verbose logging. |
Note: Completing loops improves local electrostatics and reduces spurious strain during later density-coupled refinements.
Tutorial #7: Multi-Blob Docking (Cryo-EM) on PDBid:7JSY (qmechanic)
Objective: Use density “blobs” to guide docking of a ligand fragment ensemble, then refine/evaluate placements.
- Fetch inputs:
wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/7jsy+HnL5.pdb wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/7jsy+H_lig.pdb wget https://raw.githubusercontent.com/quantumbio/QBSupportScripts/master/Tutorials/data/CryoEM/emd_22463.map
- Run multi-blob docking + refinement:
qmechanic 7jsy+HnL5.pdb emd_22463.map \ --ligand blobs 7jsy+H_lig.pdb \ -h amberff14sb \ --experiment cryoEM \ --resolution 1.8 \ --np 8 -v2 \ --dock opt rigid \ -O
| Switch / Arg | Value | Description |
| (positional) | 7jsy+HnL5.pdb | Input model (host protein; may include multiple blob targets). |
| (positional) | emd_22463.map | Cryo-EM map. |
| –ligand | blobs 7jsy+H_lig.pdb | Use density blobs + candidate ligand PDB for placements. |
| -h | amberff14sb | Force field context for scoring/relaxation. |
| –experiment | cryoEM | Real-space EM target. |
| –resolution | 1.8 | Nominal resolution. |
| –dock | opt rigid | Optimize rigid placement into density (torsionless mode). |
| –np | 8 | Parallel threads. |
| -v2 | (flag) | Verbose logging. |
| -O | (flag) | Overwrite outputs. |
Output & Validation Metrics
Each refinement/XModeScore run will emit logs and (where requested) refined PDB/MTZ files. We recommend tracking:
- Map–model agreement: local RSCC; FSC/local resolution (where available).
- Accuracy via difference-density: ZDD (lower is better).
- Chemical realism: ligand strain (PM6 kcal/mol) and clashes.
- XModeScore: combined strain + density ranker (higher is better within the compared set).
Key Resources
Notes & Best Practices:
- For Cryo-EM workflows on this page, Phenix is not required; all examples run directly with DivCon (
qmechanic/qbdivcon). - Always verify ligand identity, protonation/tautomer state, nearby ions/solvent, and alternate conformers in ambiguous density.
- When enumerating states, keep inputs consistent across candidates to avoid preparation-driven artifacts.