Oracle & Scoring

class mockdock.oracle.MDOracle(benchmark_name, budget=1000, docking_backend='auto', clip_reward_upper_bound=None, scratch_dir=None, run_dir=None, n_cpus=None, n_gpus=None, adgpu_executable=None)

Bases: object

mockdock Oracle — Fragment-Constrained Generative Model Benchmark.

Provides a standardized interface for benchmarking generative models against specific protein-ligand systems using fragment-constrained docking.

Parameters:

• benchmark_name (str)

• budget (int)

• docking_backend (str)

• clip_reward_upper_bound (bool | None)

• scratch_dir (str | Path | None)

• run_dir (str | Path | None)

• n_cpus (int | None)

• n_gpus (int | None)

• adgpu_executable (str | None)

property run_dir: Path

Timestamped run directory for this oracle session.

property generation_round: int

Number of score() batch calls made so far (i.e., generation rounds).

property fragment_smiles: str

Fragment SMILES that every submitted molecule must contain.

property fragment_smiles_with_dummies: str | None

Fragment SMILES with (*) dummy attachment point(s) for PromptSMILES scaffold decoration. Returns None if not yet set in the benchmark config TOML.

property libinvent_scaffold_with_dummies: str | None

LibInvent-specific scaffold with two attachment points when needed.

property config: dict

Key benchmark configuration parameters.

property status: str

property budget_remaining: int

property rmsd_threshold: float

RMSD threshold for pose validity.

property ligand_resname: str | None

Residue name of the reference ligand.

property pdb_id: str

PDB ID of the benchmark system.

set_backend_config(**kwargs)

Override default backend settings (e.g. vina_exhaustiveness, n_poses).

classmethod list_benchmarks()

Return all canonical benchmark names bundled with the mockdock package.

Return type:

list[str]

get_initial_compounds()

Retrieve the initial compound set (lowest-quartile bioactivity). These are provided to the generative model as starting points.

Return type:

DataFrame

get_validation_compounds()

Retrieve the validation compound set (above-lowest-quartile bioactivity). These are used to evaluate oracle performance.

Return type:

DataFrame

score(smiles_list)

Dock a list of SMILES and return normalised scores.

Parameters:

smiles_list (list[str])

Return type:

dict[str, float]

export_top_poses(n=10, output_path=None)

Export the top-N docked poses as a single SDF file. Uses DockingAnalyzer (meeko) to extract real docked coordinates from DLG/PDBQT.

Parameters:

• n (int) – Number of top molecules to export.

• output_path (str | Path | None) – Path for the SDF. Defaults to run_dir/top_{n}_poses.sdf.

Returns:

Path to the written SDF file.

Return type:

Path

fetch_poses(smiles=None, top_n=10)

Return RDKit molecules with actual docked 3D coordinates.

Parameters:

• smiles (str | None) – If given, fetch poses only for this SMILES.

• top_n (int) – Otherwise, return poses for the top-N scoring molecules.

Returns:

List of RDKit Mol objects with docked coordinates.

Return type:

list

save_metrics(extra=None)

Save timing and performance metrics to metrics.json in the run directory.

Parameters:

extra (dict | None) – Additional key/value pairs to include (e.g. model name, seed).

Returns:

Path to the written metrics file.

Return type:

Path