gdock-py
Minimal Python bindings for gdock, an information-driven protein-protein docking engine using a genetic algorithm.
Installation
pip install gdock
Usage
import gdock
receptor_pdb = open("receptor.pdb").read()
ligand_pdb = open("ligand.pdb").read()
# Score a receptor-ligand complex
scores = gdock.score(receptor_pdb, ligand_pdb)
print(scores) # {"vdw": ..., "elec": ..., "desolv": ..., "total": ...}
# Run the full GA docking pipeline
result = gdock.dock(
receptor_pdb,
ligand_pdb,
restraints=[(10, 20), (15, 25)], # (receptor_resseq, ligand_resseq) pairs
max_generations=250,
seed=42,
)
print(f"Generations run: {result['generationsRun']}")
print(f"Converged early: {result['convergedEarly']}")
print(f"Best fitness: {result['models'][0]['fitness']}")
best_pdb = result["models"][0]["pdb"]
# Pass restraints as a HADDOCK TBL file
result = gdock.dock(receptor_pdb, ligand_pdb, restraints="ambig.tbl")
# Sampling mode — collect a large pool of unique conformations sorted by fitness
result = gdock.dock(
receptor_pdb,
ligand_pdb,
restraints=[(10, 20), (15, 25)],
sampling=500,
)
for model in result["models"]:
print(f"rank={model['rank']} fitness={model['fitness']:.3f}")
Restraints
Restraints tell the GA which receptor and ligand residues should be in contact. They can be provided as:
- A list of integer pairs —
[(rec_resseq, lig_resseq), ...] - A HADDOCK TBL file path —
restraints="ambig.tbl"(string ending in.tbl)
Restraints use OR-group semantics (HADDOCK-style ambiguous AIR): a residue pair is satisfied when any of the specified partners are within the target distance, not all of them simultaneously.
API
score(receptor_pdb, ligand_pdb, w_vdw=0.4, w_elec=0.05, w_desolv=3.4) -> dict
Computes VDW, electrostatic and desolvation energy terms for a receptor-ligand
complex. Returns {"vdw", "elec", "desolv", "total"}.
dock(receptor_pdb, ligand_pdb, restraints=None, max_generations=250, population_size=150, ncores=None, seed=42, sampling=None) -> dict
Runs the genetic algorithm docking pipeline and returns ranked models:
{
"generationsRun": int, # generations actually executed
"convergedEarly": bool, # true if stopped before max_generations
"models": [
{"rank", "fitness", "vdw", "elec", "desolv", "air", "pdb"},
...
]
}
By default, returns up to 5 cluster-representative models selected by FCC
clustering. When sampling=N is set, the Hall-of-Fame capacity is raised to N
and all accumulated unique conformations are returned sorted by fitness — useful
for generating a diverse pool for downstream selection.
Development
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install maturin pytest
maturin develop
pytest tests/
License
0BSD
1 maintainer
Metadata
1 maintainer
Release files for gdock 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gdock-0.5.0.tar.gz | 36.4 kB | Details |
Built distributions (wheels)
Total release size: 13.9 MB
Release files / gdock-0.5.0.tar.gz
| Download URL | gdock-0.5.0.tar.gz |
|---|---|
| Size | 36.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3f61d871252bf0672f7032b6b61810490d3f9529b7fd0dedec099b8ab6a622f8
|
|
BLAKE2b-256 checksum How to use checksums |
5f270834a8a05fa523618b5be009f6d23e4975ed252de2d9003131d87f5d3d09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | gdock-0.5.0-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Linux glibc 2.17+ x86-64 PyPy 3.11 PyPy 3.11 7.3 |
|
SHA-256 checksum How to use checksums |
81e8980a5dbb3ce157def873d9441fd2c8ca548e7aba3490bab6d08277738e57
|
|
BLAKE2b-256 checksum How to use checksums |
efe1c499519ee81ccbdece4415396163c0afb0695fb66035b6c1affcaca8ed51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | gdock-0.5.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.14 CPython 3.14 free-threading Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
3623e3b828e84f137d07cbd2264b72ff421fc9b70a82d6053e6b4463a40a9b30
|
|
BLAKE2b-256 checksum How to use checksums |
3957a5ac274d6e7063b7c05d975a97f7ff325fc5c0cca86e08c2e13901762f98
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | gdock-0.5.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.14 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
846d315cd37ea50f2fa3cf042857094eda1c386e7f25bda8a2ef27c6afc8ae29
|
|
BLAKE2b-256 checksum How to use checksums |
b365514f2cfd78b2c31142466a8199a6776e3301903fe81f3dcf8996c95a149b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | gdock-0.5.0-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.0 MB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e49c33d634c44fc1536631deb3b1611db37e3a516f47c5dcb86f0d9f3d7015b1
|
|
BLAKE2b-256 checksum How to use checksums |
a9e8c6923d136bc3b455fa5437b96b335a3c4335091a5ee6ce9b43612c6d4c1b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | gdock-0.5.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.13 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
741bd5f899a43b42821b27383eb551c48bd7f9bbc5ccb07ab06cda854f7c9f87
|
|
BLAKE2b-256 checksum How to use checksums |
8a5fc8ef0df538b3e89a89f4f5baf628f38255c5f78a68a73a1ee3915d1b8b76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | gdock-0.5.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.0 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
1717eb4a522cc926e0d43156e2c4128400f426a916920836ec6f1deb7a9c91df
|
|
BLAKE2b-256 checksum How to use checksums |
ba40b73d27585afb7f53fa039ec5a193a0ae87db28a76b579039533fbb503f51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | gdock-0.5.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
2f098e741b5f2b5784a29422141fdad0ce47f47ea20e35d180812b94cb73d975
|
|
BLAKE2b-256 checksum How to use checksums |
60e42e98447c232bc2b7c348cd917f74dc362a7490519c115980b3313360b548
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | gdock-0.5.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.0 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
bd41559608edfb967ee5bff37fc2eb903f29d26ba4019d6b6e15c5b45bc444fe
|
|
BLAKE2b-256 checksum How to use checksums |
c970227cef81b67805400257cb88d955a8f4bea9c0e160d9df895b071317fab3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | gdock-0.5.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
018ee1c596fbf56980cf6b245786dc5908f0247e012f3e8698689eee919f5152
|
|
BLAKE2b-256 checksum How to use checksums |
660ad2b1882734e35148984e714703239cf52d6a2384fa56d71a8160454f6712
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | gdock-0.5.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.0 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
5ca36e2794d7ade696928481798f9bc30140a545735dadb719c2ff13996ab140
|
|
BLAKE2b-256 checksum How to use checksums |
f46d30d53c04cffd15fca1123c739057265d8d21aa388fd9f82688a43c906e8d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | gdock-0.5.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
a33e51dea09369ea8f882fd56b42957ec36426106d101dd54a4d5d3d93bd6945
|
|
BLAKE2b-256 checksum How to use checksums |
a4d9a2e90cb483b9672613f8a5d11cc54bb62341cb9ce95cfcdab5a8f6f361b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / gdock-0.5.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | gdock-0.5.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.2 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
82b07a6fb61c0dfbdeb83372aad763eb6609b482f294d3a30aa6d5af9056a382
|
|
BLAKE2b-256 checksum How to use checksums |
faaebb5d532a93b6a207f3ffc5bbb9d944dbcf9f7b3855f011717df5fcb20b39
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency log
