mockdock documentation#

mockdock is a docking-based benchmarking package for chemical language models (CLMs) and generative algorithms performing fragment-constrained molecular generation.

MockDock banner

Overview#

Each benchmark system in mockdock is built around a curated protein–ligand crystal structure from the PDB paired with bioactivity-annotated reference compounds (mainly from ChEMBL). Generative models are evaluated on their ability to grow or decorate a fixed 2D core fragment into high-scoring molecules while maintaining a similar 3D binding pose as the reference ligand.

MOCKDOCK Benchmark Construction and Generative Model Evaluation Workflow

What mockdock provides#

  • Curated Target Benchmarks: Seven protein targets (CHK1, DPP4, ITK, PEPCK, PptT, TTK, VEGFR2) with pre-computed AutoGrid maps and bioactivity baselines.

  • Standardized Oracle Interface: MDOracle handles SMILES sanitization, conformer generation, docking execution, pose RMSD validation, and score normalization.

  • Docking Backends: AutoDock-GPU (GPU) and AutoDock Vina (CPU).

  • Post-hoc Evaluation: MDEvaluator calculates standardized metrics covering generation quality, medicinal chemistry alerts, and oracle call efficiency.

At a glance#

Score molecules using a unified interface:

from mockdock import MDOracle

# Instantiate oracle for a specific benchmark target
oracle = MDOracle("CHK1", budget=1000, run_dir="./my_run")

# Initial seed compounds (lowest-quartile bioactivity)
initial_df = oracle.get_initial_compounds()

# Substructure fragment constraint that generated molecules must contain
fragment_smiles = oracle.fragment_smiles

# Score candidate molecules (returns dict of {smiles: reward_score})
scores = oracle.score(["CCO", "c1ccccc1"])

# Inspect session history
# (Results are automatically written to oracle.run_dir / "results.csv")
print(oracle.results_df)

# Inspect remaining budget
print(oracle.budget_remaining)

# Or export explicitly:
oracle.results_df.write_csv("my_run/results.csv")

Computing benchmarking metrics after a run:

from mockdock import MDEvaluator

evaluator = MDEvaluator("CHK1")
metrics = evaluator.compute_metrics("my_run/results.csv")

print(f"Top 10 Mean Score: {metrics['avg_top_10']:.3f}")
print(f"MedChem Pass Fraction: {metrics['fraction_medchem_pass']:.1%}")

Documentation Sections#

Section

Description

Installation

System requirements, AutoDock-GPU binary setup, CPU Vina fallback, and environment configuration.

Running Benchmarks

How to initialize oracles, query fragment constraints, batch score candidates, inspect session states, and connect with generative models.

Evaluating Results

How to run MDEvaluator, full breakdown of all 22 metrics, and multi-model aggregate analysis.

Benchmark Reference & Guide

Complete reference on the 7 standard targets, scoring equations, creating custom targets, and automation scripts.

API Reference

Python API reference for all public classes, methods, and modules.

User Guide

API Reference