LightDock Local Protein Docking

Overview

This skill runs LightDock, a glowworm-swarm-optimization protein-protein docking engine, on the local machine and turns its raw swarm output into a ranked score table and a set of docked complex structures.

LightDock works differently from the HDOCK skill in this same repository. HDOCK is a web service: you submit a job and the server computes. LightDock is a local program: pip install lightdock, and the search runs on your own CPUs. A single job with 50 swarms × 50 steps takes minutes to hours depending on core count and protein size. A batch of 100 pairs takes days. This skill is therefore built around long-running, resumable, interrupt-safe batch execution rather than around request/response handling.

The hard part of driving LightDock from a script is not the subprocess calls — it is the output semantics. The gso_<step>.out files and the lightdock_<i>.pdb conformations have three separate traps that all produce plausible-looking but wrong results, and this skill fixes all three.

When to Use This Skill

• Running protein-protein docking locally with full control over swarm/step counts
• Ranking a batch of receptor-ligand pairs by DFIRE score
• Recovering the best complex model from an existing LightDock run
• Producing docked complex structures for downstream MD, interaction analysis, or figure preparation
• Comparing against the protein-docking-hdock skill when a local (no data leaves the machine) prediction is required

Quick Start

export PYTHONPATH="$PWD/packages"

# 一个受体 vs 一组配体
python scripts/run_docking.py --receptor rec.pdb --ligands ligands/*.pdb \
    --output-dir results/

# 多个受体 vs 多个配体（笛卡尔积）
python scripts/run_docking.py --receptors recs/*.pdb --ligands ligands/*.pdb \
    --output-dir results/

# 快速试跑（先验证流程再上规模）
python scripts/run_docking.py --receptor rec.pdb --ligands a.pdb b.pdb \
    --swarms 5 --glowworms 10 --steps 20 --cores 4 --output-dir test/

# 从已有结果生成最优复合物
python scripts/generate_conformations.py --job-dir results/rec__lig/

# 汇总分数排名
python scripts/extract_scores.py --jobs-root results/ --output-dir scores/

Workflow

1. Locate the executables — resolve_executables() finds lightdock3_setup.py and lightdock3.py by checking, in order: an explicit --setup-exe / --run-exe path, the current interpreter's <prefix>/bin (where conda and venv installs put them — these are not on PATH, which is why the old scripts hard-coded an absolute path), and finally the system PATH.
2. Setup stage — lightdock3_setup.py copies both structures into the job directory, strips waters/oxygens/hydrogens per the flags, computes the minimum-volume ellipsoid of the receptor, places the swarms on its surface, and writes setup.json. Critically, it translates both structures to the origin and saves them as lightdock_receptor.pdb / lightdock_ligand.pdb.
3. Simulation — lightdock3.py setup.json <steps> -c <cores> runs the glowworm swarm optimisation. Each swarm writes gso_<step>.out every 10 steps.
4. Score extraction — collect_swarm_results() picks the highest-step gso_*.out per swarm by numeric step, parses every glowworm line, and finds the minimum-scoring entry. Lower DFIRE score is better.
5. Conformation generation — lgd_generate_conformations.py writes lightdock_<i>.pdb files from the GSO coordinates, using the origin-shifted structures so receptor and ligand stay aligned.
6. Reporting — scores go to docking_scores.csv / .json, incrementally after every job.

Parameters

run_docking.py

generate_conformations.py

extract_scores.py

Outputs

Validation

• Score sign — DFIRE scores are negative and lower is better. A positive "best score" usually means the parser picked the wrong column.
• Score magnitude — a converged small-complex DFIRE score typically lands around -30 to -60. A score near 0 means the search barely moved from the random start.
• glowworm index vs LigID — the glowworm id is the line number in the GSO file. In single-structure docking, RecID and LigID are both 0. If your report says "best glowworm = 0" for every job, the parser is reading the wrong field.
• GSO step selection — the file to use is the one with the largest numeric step (gso_100.out over gso_20.out), not the last one alphabetically.
• Conformation count — lgd_generate_conformations.py clips the requested count to the number of coordinate lines actually found, and says so in its log.
• Complex sanity — open the generated PDB and confirm the two parts touch but do not interpenetrate. A ligand flying off to the origin means the origin-shifted structures were not used.
• RMSD — LightDock does not report RMSD by default; run lgd_rank.py if you need it, or compare against a known holo structure.

References

• references/methodology.md — GSO format semantics, coordinate-frame handling, score extraction, official command reference
• references/troubleshooting.md — common failures and how to diagnose them