Molecular Docking

The docking stage writes ligand SDFs and runs molecular docking simulations against a target protein structure. HEDGEHOG supports three docking engines, including SMINA, GNINA, and Matcha. The default config keeps prepare_ligands: false, which uses input molecules directly where possible and preserves a near 1:1 mapping from input rows to docking ligands.

Set auto_run: false to generate docking scripts without executing them.

Docking Engines

SMINA is a fork of AutoDock Vina with enhanced scoring and minimization. GNINA extends SMINA with convolutional neural network (CNN) scoring functions trained on protein-ligand complexes from the PDB. For GNINA, Hedgehog generates multiple modes and uses each molecule’s lowest minimizedAffinity pose for threshold calibration. Matcha is a recent neural docking method based on multi-stage Riemannian flow matching.

Default Matcha path is the official LigandPro/Matcha CLI (modules/matcha_remote): Hedgehog runs uv run --project <checkout> matcha ..., scores poses with GNINA when scorer: gnina, and uses minimizedAffinity for threshold calibration. An optional backend: docking adapter can point at LigandPro/docking screening instead; that path needs checkpoint_root / checkpoint_run and is not the shipped default.

Select the tool in the docking config:

tools: [smina, gnina, matcha]

tools: all also includes Matcha. Prefer a target-specific config when you need a non-default Matcha checkout, device, or the optional docking screening backend.

Data Preparation

Ligand Preparation

Docking requires 3D molecular structures in SDF format. Molecules are automatically converted while previous stages are run, or yuo can manually convert examining molecules into SDF format to run this stage independently.

Default Path: Direct RDKit SDF Generation

With prepare_ligands: false, the docking stage uses built-in RDKit conversion:

1. Parse SMILES with Chem.MolFromSmiles()
2. Add explicit hydrogens with Chem.AddHs()
3. Generate 3D coordinates with AllChem.EmbedMolecule() (ETKDG method)
4. Optimize geometry with AllChem.UFFOptimizeMolecule() (UFF force field)

This produces reasonable starting geometries and keeps row counts predictable.

Protein Preparation

The receptor PDB file is specified in the docking config:

receptor_pdb: examples/7EW9_apo.pdb

For best results, prepare the receptor with a dedicated structure-preparation tool (or PDB2PQR) before docking. Key steps include:

• Removing water molecules and co-crystallized ligands
• Adding hydrogens at physiological pH
• Optimizing hydrogen-bond networks
• Minimizing heavy-atom positions (restrained)

Custom Handler Support

ligand_preparation_tool and protein_preparation_tool can point to any executable (absolute path or command available in PATH).

External handlers are optional:

• If no external tool is configured, HEDGEHOG uses built-in behavior.
• Ligands fall back to RDKit preparation.
• Protein input is used as-is when no protein handler is configured.

For custom handlers, ensure they run non-interactively and produce valid output files expected by the docking stage.

Autobox Configuration

The docking search box defines the 3D region where the docking engine places ligand poses. HEDGEHOG determines the box from a reference ligand:

autobox_ligand: examples/05C_from_7EW9.sdf
autobox_add: 4

Relative receptor, autobox, and checkpoint paths are resolved from the directory containing config_docking.yml; environment variables and ~ are expanded. The shared box applies to every selected engine and can be overridden inside one engine config when necessary.

The search box is computed as the bounding box of the reference ligand’s atoms, expanded by autobox_add Angstroms in each direction.

Important: The reference ligand SDF must be in the same coordinate frame as the receptor PDB. If using an apo (unbound) structure, you may need to superimpose the reference ligand from a holo (bound) structure onto the apo receptor coordinates.

Batch Docking Workflow

The docking stage processes molecules individually:

1. Each molecule is written to a separate SDF file in _workdir/molecules/
2. Per-molecule docking config files are generated in _workdir/configs/
3. Batch shell scripts (run_gnina.sh, run_smina.sh, run_matcha.sh) are generated
4. If auto_run: true, scripts are executed automatically
5. Per-molecule results are collected in _workdir/gnina/, _workdir/smina/, or matcha/<run_name>/best_poses/
6. For each tool, the pose with the lowest affinity is selected per (model_name, mol_idx) pair, so identical molecule IDs from different generator models remain separate
7. Results are aggregated into gnina/gnina_out.sdf, smina/smina_out.sdf, or matcha/matcha_out.sdf
8. Each tool writes a <tool>_best_poses.csv manifest recording the selected affinity, source file, and source pose index

Output Structure

stages/05_docking/
┌── _workdir/
|   ├── configs/               # Per-molecule docking configs
|   ├── gnina/                 # GNINA per-molecule results & logs
|   ├── molecules/             # Per-molecule SDF files
|   ├── smina/                 # SMINA per-molecule results & logs
|   ├── run_gnina.sh
|   ├── run_matcha.sh
|   └── run_smina.sh
├── checkpoints/               # Matcha per stage results 
├── gnina/
|   ├── gnina_best_poses.csv   # Auditable GNINA pose selection
|   └── gnina_out.sdf          # Aggregated GNINA results
├── matcha/
|   ├── matcha_best_poses.csv  # Auditable Matcha pose selection
|   └── matcha_out.sdf         # Aggregated Matcha results
├── smina/
|   ├── smina_best_poses.csv   # Auditable Smina pose selection
|   └── smina_out.sdf          # Aggregated Smina results
├── job_ids.txt                # Docking job ids 
├── job_meta.json              # Job metadata
└── ligands.csv                # Prepared ligands

Usage

# Run docking as part of the full pipeline
uv run hedgehog
 
# Run docking stage only
uv run hedgehog --stage docking
 
# Short alias
uv run hedge --stage docking
 
 
# To run the generated scripts manually:
cd results/stages/05_docking/_workdir
./run_matcha.sh
./run_gnina.sh
./run_smina.sh