Scoring Pipeline & Constraints#

mockdock converts raw docking energies into standardized, bounded reward signals designed for reinforcement learning, genetic algorithms, and chemical language models.

The Scoring Pipeline#

When a molecule is submitted to score(), it passes through a 5-step evaluation pipeline:

Candidate SMILES
       │
       ▼
1. 2D Substructure Match? ──[No]──► Reward = 0.0
       │ [Yes]
       ▼
2. 3D Conformer Prep & Docking (AD-GPU or Vina)
       │
       ▼
3. 3D Pose RMSD <= Threshold (2.0 Å)? ──[No]──► Reward = 0.0
       │ [Yes]
       ▼
4. Min-Max Normalization -> norm_score
       │
       ▼
5. Reward Clipping [0.0, 1.0] -> reward_score

1. 2D Substructure Check#

The candidate molecule must contain the target’s core fragment as a substructure (using RDKit’s mol.HasSubstructMatch).

If the fragment is missing, the molecule is assigned a reward score of 0.0 immediately without wasting GPU or CPU cycles on docking.

2. 3D Conformer Prep & Docking#

  • RDKit generates a 3D conformer with energy minimization (ETKDG / UFF).

  • Meeko generates the PDBQT representation with assigned partial charges.

  • The docking engine (AutoDock-GPU or AutoDock Vina) runs against the target’s pre-computed grid maps.

  • The lowest predicted binding energy (kcal/mol) is recorded as docking_score (more negative = stronger binding).

3. 3D Pose RMSD Alignment#

The docked pose of the candidate must maintain the experimental binding mode of the crystal fragment.

  • The coordinates of the matched substructure atoms in the docked pose are compared to the reference crystal ligand fragment atoms.

  • If the heavy-atom RMSD exceeds the threshold (default: 2.0 Å), the pose is considered biologically invalid and given a reward of 0.0.

4. Score Normalization#

Raw docking energies are normalized against target-specific calibration bounds:

\[\text{norm\_score} = \frac{\text{docking\_score} - \text{low\_score}}{\text{high\_score} - \text{low\_score}}\]

Where: * low_score corresponds to the worst average docking score in the baseline ChEMBL dataset (mapped to 0.0). * high_score corresponds to the best average docking score in the baseline ChEMBL dataset (mapped to 1.0).

5. Reward Clipping#

By default (clip_reward_upper_bound = True):

\[\text{reward\_score} = \min(\max(\text{norm\_score}, 0.0), 1.0)\]

This ensures rewards remain strictly within [0.0, 1.0] for reinforcement learning stability. Both norm_score (unclipped) and reward_score (clipped) are preserved in the results DataFrame.

Relaxing Constraints & Ablation Studies#

For unconstrained exploration or ablation studies, you can relax or disable specific filters in Python:

from mockdock import MDOracle

oracle = MDOracle("CHK1")

# Dock all molecules even if they lack the 2D fragment
oracle._loader.require_fragment_match = False

# Accept the best docking energy regardless of pose RMSD
oracle._loader.require_pose_rmsd = False

# Disable reward upper bound clipping
oracle.clip_reward_upper_bound = False