Structure, Docking & Dynamics

Tutorials for the omicverse.mol module — the bridge from an omics target protein to its 3D structure, its drug context, and how both behave over time.

A typical omicverse analysis ends with a target: a differential gene from ov.bulk, a marker or driver from ov.single, a variant from ov.genetics. The natural next questions are structural and pharmacological — what does the protein look like in 3D, where are its confident regions, does it have a druggable pocket, are there known drugs against it, and can a candidate molecule bind it? ov.mol answers them, with interactive 3D visualization (py3Dmol) that renders inline in Jupyter and persists in the exported HTML docs.

The notebooks follow the natural arc see the target → assess it → test a drug → watch it move, and each one follows the analysis workflow the field actually uses — with the discipline (model-confidence assessment, redocking validation, minimisation and equilibration before production) a structural biologist or computational chemist would apply. They run real targets — EGFR and ubiquitin — framed as hits handed over by an upstream omics analysis.

Notebook	What you learn
Structure	Fetch / predict and interactively visualize a target’s structure — and assess model confidence (pLDDT, PAE) before trusting it.
Druggability	Detect binding pockets, score druggability, and check what drugs are already known — structure-based target prioritization.
Docking	Validate a docking protocol by redocking, then dock a candidate molecule and inspect the binding pose.
Dynamics	Take a static model or a docked pose and actually run it: solvate, minimise, equilibrate, produce a trajectory on the GPU, then read stability (RMSD/RMSF/DSSP) and rescore binding with MM-GBSA.

• Protein structure of an omics target — fetch, visualize, and assess before you trust
• Is the target druggable? — binding pockets and known drugs
• Molecular docking — validate the protocol, then dock the candidate
• Molecular dynamics — from a static model to motion

Why add dynamics

Structure prediction and docking both hand you a single static snapshot. That snapshot cannot tell you whether a loop is genuinely ordered or whether a docked pose survives more than a picosecond of thermal motion. Molecular dynamics adds the missing axis:

• an AlphaFold model → is the fold stable, and which regions are floppy (rmsf) rather than merely low-pLDDT?

• a docked pose → does the ligand stay in the pocket, and what is its binding free energy averaged over an ensemble rather than one pose?

That last step is what ov.mol uniquely chains end to end:

result = ov.mol.dock(s, 'erlotinib', pocket=1)   # static pose + Vina score
traj   = ov.mol.simulate(result, ns=5)           # relax it with real dynamics
res    = ov.mol.mmgbsa(traj)                     # ensemble-averaged ΔG

dock → MD → MM-GBSA in three calls, with the receptor carried through automatically. Docking alone gives you a point; MD alone gives you a process; only the chain gives you a rescored answer.

Installation

The structural-biology stack is optional. The core layer — structure acquisition, interactive visualization and known-drug lookup:

pip install 'omicverse[mol]'

The docking layer (AutoDock Vina + receptor / ligand preparation):

pip install 'omicverse[mol-dock]'

Binding-pocket detection uses rust-fpocket, a pip-installable Rust port of fpocket:

pip install fpocket-rs

The molecular-dynamics layer (OpenMM engine + MDTraj analysis):

pip install 'omicverse[md]'

On a GPU machine, install OpenMM from conda-forge instead. Its CUDA build is far more likely to match your driver, and the PyPI OpenMM (<8.2) is incompatible with NumPy 2:

conda install -c conda-forge openmm mdtraj

PDBFixer — needed to repair structures before simulation — is not published on PyPI, so omicverse vendors it (omicverse.external.pdbfixer). You never install it separately.

To simulate a protein–ligand complex (ov.mol.simulate(docking_result), ov.mol.mmgbsa) you also need small-molecule parameterisation. Note that AmberTools is required, not optional: both GAFF and OpenFF assign AM1-BCC partial charges, which are computed by AmberTools’ sqm. It is conda-only, so install the ligand stack from conda-forge:

conda install -c conda-forge openmmforcefields openff-toolkit ambertools

Without it, parameterisation fails with “no registered toolkits can provide assign_partial_charges”. (openff-nagl is a lighter alternative that predicts charges with a graph network instead of running semi-empirical QM.)

Two environment gotchas worth knowing, because both surface as that same unhelpful message:

• the OpenFF toolkit locates AmberTools with shutil.which, so an interpreter launched by absolute path (a Jupyter kernel, a cron job, an environment that was never “activated”) will not see it — put the environment’s bin on PATH;

• antechamber needs AMBERHOME set to find its parameter files, and exits non-zero without it: export AMBERHOME=/path/to/env.

ov.mol detects both cases and says exactly which one you are in.

Checking you are actually on the GPU

Every run prints the OpenMM platform it resolved. If you see CPU where you expected CUDA, the CUDA build is not installed or does not match your driver — MD on CPU is 10–100× slower and only viable for toy systems.

traj = ov.mol.simulate(s, ns=1)     # prints "OpenMM platform: CUDA (precision=mixed)"
traj.provenance['platform']          # 'CUDA'

Force a device with platform='CUDA' or the OMICOS_MD_DEVICE environment variable.