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. Matcha is a recent neural docking method based on multi-stage Riemannian flow matching.

Select the tool in the docking config:

tools: gnina    # Options: all, gnina, smina, matcha, or a comma-separated list

Use tools: all to run SMINA, GNINA, and Matcha together. For subsets, provide a comma-separated YAML value such as gnina,matcha or smina,gnina.

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: src/hedgehog/configs/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:

gnina_config:
  autobox_ligand: src/hedgehog/configs/examples/05C_from_7EW9.sdf   # Reference ligand SDF
  autobox_add: 4                                  # Padding in Angstroms

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. Results are aggregated into gnina/gnina_out.sdf, smina/smina_out.sdf, or matcha/matcha_out.sdf

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_out.sdf          # Aggregated GNINA results
├── matcha/
|   └── matcha_out.sdf         # Aggregated Matcha results
├── smina/
|   └── 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