ms-adtools 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. ms_adtools-0.1.0/.github/workflows/publish.yml +31 -0
  2. ms_adtools-0.1.0/.gitignore +220 -0
  3. ms_adtools-0.1.0/LICENSE +25 -0
  4. ms_adtools-0.1.0/PKG-INFO +122 -0
  5. ms_adtools-0.1.0/README.md +95 -0
  6. ms_adtools-0.1.0/benchmarks/REPORT.md +72 -0
  7. ms_adtools-0.1.0/benchmarks/bench.py +128 -0
  8. ms_adtools-0.1.0/pyproject.toml +46 -0
  9. ms_adtools-0.1.0/setup.cfg +4 -0
  10. ms_adtools-0.1.0/src/ms_adtools/__init__.py +15 -0
  11. ms_adtools-0.1.0/src/ms_adtools/ccd.py +221 -0
  12. ms_adtools-0.1.0/src/ms_adtools/cli.py +129 -0
  13. ms_adtools-0.1.0/src/ms_adtools/ligand.py +398 -0
  14. ms_adtools-0.1.0/src/ms_adtools/poses.py +168 -0
  15. ms_adtools-0.1.0/src/ms_adtools/reactive.py +118 -0
  16. ms_adtools-0.1.0/src/ms_adtools/receptor.py +569 -0
  17. ms_adtools-0.1.0/src/ms_adtools/zinc/AD4Zn.dat +121 -0
  18. ms_adtools-0.1.0/src/ms_adtools/zinc/GPL-2.0 +339 -0
  19. ms_adtools-0.1.0/src/ms_adtools/zinc/LICENSE +202 -0
  20. ms_adtools-0.1.0/src/ms_adtools/zinc/NOTICE +15 -0
  21. ms_adtools-0.1.0/src/ms_adtools/zinc/__init__.py +21 -0
  22. ms_adtools-0.1.0/src/ms_adtools/zinc/zinc_pseudo.py +565 -0
  23. ms_adtools-0.1.0/src/ms_adtools.egg-info/PKG-INFO +122 -0
  24. ms_adtools-0.1.0/src/ms_adtools.egg-info/SOURCES.txt +37 -0
  25. ms_adtools-0.1.0/src/ms_adtools.egg-info/dependency_links.txt +1 -0
  26. ms_adtools-0.1.0/src/ms_adtools.egg-info/entry_points.txt +2 -0
  27. ms_adtools-0.1.0/src/ms_adtools.egg-info/requires.txt +6 -0
  28. ms_adtools-0.1.0/src/ms_adtools.egg-info/scm_file_list.json +33 -0
  29. ms_adtools-0.1.0/src/ms_adtools.egg-info/scm_version.json +8 -0
  30. ms_adtools-0.1.0/src/ms_adtools.egg-info/top_level.txt +1 -0
  31. ms_adtools-0.1.0/test/data/1iep.pdbqt +2703 -0
  32. ms_adtools-0.1.0/test/data/1iep_flex_vina_out.pdbqt +348 -0
  33. ms_adtools-0.1.0/test/data/1iep_receptorH.pdb +4414 -0
  34. ms_adtools-0.1.0/test/data/3pg.pdb +12 -0
  35. ms_adtools-0.1.0/test/data/3pg_chem_comp.cif +118 -0
  36. ms_adtools-0.1.0/test/data/altloc.pdb +44 -0
  37. ms_adtools-0.1.0/test/data/ccd/3PG.cif +122 -0
  38. ms_adtools-0.1.0/test/data/zn_site.pdbqt +51 -0
  39. ms_adtools-0.1.0/test/test_prepare.py +282 -0
@@ -0,0 +1,31 @@
1
+ # Publish to PyPI on a GitHub release.
2
+ #
3
+ # No secrets: the job authenticates to PyPI over OIDC (Trusted Publishing).
4
+ # It has to be enabled on the PyPI side *before* the first upload -- for a
5
+ # project that does not exist yet, that is a "pending publisher" under
6
+ # Your projects > Publishing, and it must name this repo, `publish.yml`
7
+ # and the `pypi` environment below.
8
+ name: publish
9
+
10
+ on:
11
+ release:
12
+ types: [published]
13
+
14
+ jobs:
15
+ pypi:
16
+ runs-on: ubuntu-latest
17
+ environment: pypi
18
+ permissions:
19
+ # A permissions block sets every scope it does not name to none, so
20
+ # checkout needs contents spelled out or it cannot read a private repo.
21
+ contents: read
22
+ id-token: write # mint the OIDC token PyPI checks; no secret involved
23
+ steps:
24
+ - uses: actions/checkout@v7
25
+ with:
26
+ fetch-depth: 0 # setuptools-scm reads the version off the tag
27
+ - uses: actions/setup-python@v7
28
+ with:
29
+ python-version: "3.12"
30
+ - run: pipx run build
31
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,220 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ *.lcov
51
+ .hypothesis/
52
+ .pytest_cache/
53
+ cover/
54
+
55
+ # Translations
56
+ *.mo
57
+ *.pot
58
+
59
+ # Django stuff:
60
+ *.log
61
+ local_settings.py
62
+ db.sqlite3
63
+ db.sqlite3-journal
64
+
65
+ # Flask stuff:
66
+ instance/
67
+ .webassets-cache
68
+
69
+ # Scrapy stuff:
70
+ .scrapy
71
+
72
+ # Sphinx documentation
73
+ docs/_build/
74
+
75
+ # PyBuilder
76
+ .pybuilder/
77
+ target/
78
+
79
+ # Jupyter Notebook
80
+ .ipynb_checkpoints
81
+
82
+ # IPython
83
+ profile_default/
84
+ ipython_config.py
85
+
86
+ # pyenv
87
+ # For a library or package, you might want to ignore these files since the code is
88
+ # intended to run in multiple environments; otherwise, check them in:
89
+ # .python-version
90
+
91
+ # pipenv
92
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
93
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
94
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
95
+ # install all needed dependencies.
96
+ # Pipfile.lock
97
+
98
+ # uv
99
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
100
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
101
+ # commonly ignored for libraries.
102
+ # uv.lock
103
+
104
+ # poetry
105
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
106
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
107
+ # commonly ignored for libraries.
108
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
109
+ # poetry.lock
110
+ # poetry.toml
111
+
112
+ # pdm
113
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
114
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
115
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
116
+ # pdm.lock
117
+ # pdm.toml
118
+ .pdm-python
119
+ .pdm-build/
120
+
121
+ # pixi
122
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
123
+ # pixi.lock
124
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
125
+ # in the .venv directory. It is recommended not to include this directory in version control.
126
+ .pixi/*
127
+ !.pixi/config.toml
128
+
129
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
130
+ __pypackages__/
131
+
132
+ # Celery stuff
133
+ celerybeat-schedule*
134
+ celerybeat.pid
135
+
136
+ # Redis
137
+ *.rdb
138
+ *.aof
139
+ *.pid
140
+
141
+ # RabbitMQ
142
+ mnesia/
143
+ rabbitmq/
144
+ rabbitmq-data/
145
+
146
+ # ActiveMQ
147
+ activemq-data/
148
+
149
+ # SageMath parsed files
150
+ *.sage.py
151
+
152
+ # Environments
153
+ .env
154
+ .envrc
155
+ .venv
156
+ env/
157
+ venv/
158
+ ENV/
159
+ env.bak/
160
+ venv.bak/
161
+
162
+ # Spyder project settings
163
+ .spyderproject
164
+ .spyproject
165
+
166
+ # Rope project settings
167
+ .ropeproject
168
+
169
+ # mkdocs/Zensical documentation
170
+ /site
171
+
172
+ # mypy
173
+ .mypy_cache/
174
+ .dmypy.json
175
+ dmypy.json
176
+
177
+ # Pyre type checker
178
+ .pyre/
179
+
180
+ # pytype static type analyzer
181
+ .pytype/
182
+
183
+ # Cython debug symbols
184
+ cython_debug/
185
+
186
+ # PyCharm
187
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
188
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
189
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
190
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
191
+ .idea/
192
+
193
+ # Abstra
194
+ # Abstra is an AI-powered process automation framework.
195
+ # Ignore directories containing user credentials, local state, and settings.
196
+ # Learn more at https://abstra.io/docs
197
+ .abstra/
198
+
199
+ # Visual Studio Code
200
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
201
+ # can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
202
+ # and can be added to the global gitignore or merged into this file. However, if you prefer, you
203
+ # could uncomment the following to ignore the entire vscode folder
204
+ # .vscode/
205
+ # Temporary file for partial code execution
206
+ tempCodeRunnerFile.py
207
+
208
+ # Ruff stuff:
209
+ .ruff_cache/
210
+
211
+ # PyPI configuration file
212
+ .pypirc
213
+
214
+ # Marimo
215
+ marimo/_static/
216
+ marimo/_lsp/
217
+ __marimo__/
218
+
219
+ # Streamlit
220
+ .streamlit/secrets.toml
@@ -0,0 +1,25 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mario S. Valdés-Tresanco and Mario E. Valdés-Tresanco
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ The files in src/ms_adtools/zinc/ keep their own licenses: zinc_pseudo.py is
24
+ Apache-2.0 (see its LICENSE) and AD4Zn.dat is GPL-2.0-or-later data, shipped
25
+ unmodified alongside this package (see its NOTICE and GPL-2.0).
@@ -0,0 +1,122 @@
1
+ Metadata-Version: 2.4
2
+ Name: ms_adtools
3
+ Version: 0.1.0
4
+ Summary: AutoDock receptor, flexible-residue and ligand preparation with RDKit and gemmi.
5
+ Author: Mario S. Valdés-Tresanco, Mario E. Valdés-Tresanco
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/MolSuite/ms_adtools
8
+ Project-URL: Issues, https://github.com/MolSuite/ms_adtools/issues
9
+ Keywords: autodock,vina,pdbqt,docking,molsuite
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: Programming Language :: Python :: 3 :: Only
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Topic :: Scientific/Engineering :: Chemistry
15
+ Requires-Python: >=3.12
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ License-File: src/ms_adtools/zinc/LICENSE
19
+ License-File: src/ms_adtools/zinc/GPL-2.0
20
+ License-File: src/ms_adtools/zinc/NOTICE
21
+ Requires-Dist: numpy>=2.0
22
+ Requires-Dist: gemmi>=0.7
23
+ Requires-Dist: rdkit>=2024.3
24
+ Provides-Extra: dev
25
+ Requires-Dist: pytest>=7.0; extra == "dev"
26
+ Dynamic: license-file
27
+
28
+ # ms_adtools
29
+
30
+ AutoDock preparation on RDKit and gemmi: ligand PDBQT, receptor PDBQT (PDB, mmCIF, PQR, PDBQT,
31
+ mol2), the rigid/flexible pair for flexible-residue docking as AutoDockTools writes it, and
32
+ docked poses (PDBQT, DLG) back to RDKit. Requires only `numpy`, `gemmi` and `rdkit`.
33
+
34
+ ```bash
35
+ pip install ms_adtools
36
+ ```
37
+
38
+ ## Why
39
+
40
+ Performance. A virtual screen prepares molecules in many parallel workers, so what each worker
41
+ loads matters as much as how fast it runs. meeko, the reference preparation tool for AutoDock,
42
+ brings heavy dependencies (scipy, pandas, prody): importing it alone takes about 240 MB, and
43
+ preparing a receptor peaks above 350 MB. ms_adtools follows its ligand conventions (typing,
44
+ torsion tree, `REMARK SMILES` / `IDX` / `H PARENT`), so its ligand PDBQT reads the same, with numpy, gemmi
45
+ and RDKit as the only requirements: a worker that prepares a receptor peaks at about 80 MB.
46
+
47
+ ## Command line
48
+
49
+ ```bash
50
+ ms_adtools ligand lig.sdf -o lig.pdbqt # SDF, MOL, mol2, or .smi (embedded in 3D)
51
+ ms_adtools ligand library.smi -o library/ # several molecules: one PDBQT each
52
+ ms_adtools receptor 1iep.pdb -o 1iep.pdbqt # --repairs hydrogens, --zinc, --ccd, --charges
53
+ ms_adtools flexreceptor 1iep.pdbqt -r "A:239,315" # writes 1iep_rigid.pdbqt + 1iep_flex.pdbqt
54
+ ms_adtools poses docked.pdbqt -o poses.sdf # or a .dlg; one record per pose, with its score
55
+ ```
56
+
57
+ `ms_adtools <command> -h` lists every option. A molecule that fails is reported on stderr and the
58
+ rest of the library goes on (exit code 1 if any failed).
59
+
60
+ ## Selecting residues
61
+
62
+ `-r` / `residues=` takes chains and residue numbers, comma- or space-separated:
63
+
64
+ | selection | means |
65
+ |---|---|
66
+ | `A:2-10,B:20` | residues 2 to 10 of chain A, 20 of chain B |
67
+ | `A:2,4,6` | three residues of chain A (a chain holds until the next one) |
68
+ | `A:ARG239,THR315` | with names, which must then match |
69
+ | `100` / `100A` | any chain; `100` takes its insertion codes, `100A` only that one |
70
+
71
+ Residues with nothing to rotate (Gly, Ala) and Pro stay rigid, with a warning.
72
+
73
+ ## Python API
74
+
75
+ ```python
76
+ from rdkit import Chem
77
+ from rdkit.Chem import AllChem
78
+ from ms_adtools import prepare_ligand, prepare_receptor, prepare_flexreceptor, pdbqt_to_rdkit
79
+
80
+ mol = Chem.AddHs(Chem.MolFromSmiles("CC(=O)Nc1ccc(O)cc1"))
81
+ AllChem.EmbedMolecule(mol)
82
+ pdbqt = prepare_ligand(mol) # str, with REMARK SMILES / IDX / H PARENT
83
+ receptor = prepare_receptor("1iep.pdb") # str
84
+ rigid, flex = prepare_flexreceptor("1iep.pdbqt", "A:239,315")
85
+ poses = pdbqt_to_rdkit(docked_text) # one conformer per MODEL, `score` on each
86
+ ```
87
+
88
+ | function | returns |
89
+ |---|---|
90
+ | `prepare_ligand(mol, open_macrocycles=False, hydrate=False, flexible_amides=False, ...)` | ligand PDBQT text |
91
+ | `prepare_reactive_ligand(mol, smarts, idx=0, ...)` | ligand PDBQT with the reactive atom typed |
92
+ | `prepare_receptor(path, repairs="", charges=None, cleanup=..., zinc=False, ccd=False)` | receptor PDBQT text |
93
+ | `prepare_flexreceptor(path, residues, reactive=())` | `(rigid, flex)` PDBQT texts |
94
+ | `pdbqt_to_rdkit(text)` | RDKit molecule, one conformer per pose |
95
+ | `dlg_to_pdbqt(text, cluster_leads=True)` | PDBQT poses of an AutoDock4/AutoDock-GPU DLG |
96
+ | `flexres_models(text, rigid=None)` | docked flexible residues as a multi-model PDB |
97
+ | `add_zinc_pseudo_atoms(pdbqt)` | receptor PDBQT with AutoDock4Zn TZ atoms |
98
+
99
+ `ms_adtools.reactive.reactive_config` writes the config of reactive docking;
100
+ `ms_adtools.zinc.PARAMETERS` is the `AD4Zn.dat` that autogrid4 needs for AutoDock4Zn maps.
101
+ Each function's docstring has the details.
102
+
103
+ ## Speed and memory
104
+
105
+ One CPU, Python 3.12, RDKit 2026.09; each row is a fresh process.
106
+
107
+ | | wall | peak RSS |
108
+ |---|---|---|
109
+ | import | 0.12 s | 71 MB |
110
+ | 200 ligands (Enamine, 3D) | 0.29 s (1.5 ms each) | 72 MB |
111
+ | receptor (4uwh, 4905 atoms) | 0.16 s | 83 MB |
112
+
113
+ On `1iep_receptorH.pdb` the receptor has AutoDockTools' atoms and types (charges within 0.02 on
114
+ average), and `prepare_flexreceptor` writes its rigid file byte for byte. `benchmarks/` has the
115
+ script and the full measurements.
116
+
117
+ ## License
118
+
119
+ MIT (`LICENSE`). The PDBQT conventions are AutoDockTools' (MGLTools, M. Sanner, TSRI) and the Forli
120
+ lab's; cite them with AutoDock. `src/ms_adtools/zinc/` carries AutoDock Vina's
121
+ `zinc_pseudo.py` (Apache-2.0) and the unmodified `AD4Zn.dat` parameter file (GPL-2.0-or-later
122
+ data), each with its own license (see its `NOTICE`).
@@ -0,0 +1,95 @@
1
+ # ms_adtools
2
+
3
+ AutoDock preparation on RDKit and gemmi: ligand PDBQT, receptor PDBQT (PDB, mmCIF, PQR, PDBQT,
4
+ mol2), the rigid/flexible pair for flexible-residue docking as AutoDockTools writes it, and
5
+ docked poses (PDBQT, DLG) back to RDKit. Requires only `numpy`, `gemmi` and `rdkit`.
6
+
7
+ ```bash
8
+ pip install ms_adtools
9
+ ```
10
+
11
+ ## Why
12
+
13
+ Performance. A virtual screen prepares molecules in many parallel workers, so what each worker
14
+ loads matters as much as how fast it runs. meeko, the reference preparation tool for AutoDock,
15
+ brings heavy dependencies (scipy, pandas, prody): importing it alone takes about 240 MB, and
16
+ preparing a receptor peaks above 350 MB. ms_adtools follows its ligand conventions (typing,
17
+ torsion tree, `REMARK SMILES` / `IDX` / `H PARENT`), so its ligand PDBQT reads the same, with numpy, gemmi
18
+ and RDKit as the only requirements: a worker that prepares a receptor peaks at about 80 MB.
19
+
20
+ ## Command line
21
+
22
+ ```bash
23
+ ms_adtools ligand lig.sdf -o lig.pdbqt # SDF, MOL, mol2, or .smi (embedded in 3D)
24
+ ms_adtools ligand library.smi -o library/ # several molecules: one PDBQT each
25
+ ms_adtools receptor 1iep.pdb -o 1iep.pdbqt # --repairs hydrogens, --zinc, --ccd, --charges
26
+ ms_adtools flexreceptor 1iep.pdbqt -r "A:239,315" # writes 1iep_rigid.pdbqt + 1iep_flex.pdbqt
27
+ ms_adtools poses docked.pdbqt -o poses.sdf # or a .dlg; one record per pose, with its score
28
+ ```
29
+
30
+ `ms_adtools <command> -h` lists every option. A molecule that fails is reported on stderr and the
31
+ rest of the library goes on (exit code 1 if any failed).
32
+
33
+ ## Selecting residues
34
+
35
+ `-r` / `residues=` takes chains and residue numbers, comma- or space-separated:
36
+
37
+ | selection | means |
38
+ |---|---|
39
+ | `A:2-10,B:20` | residues 2 to 10 of chain A, 20 of chain B |
40
+ | `A:2,4,6` | three residues of chain A (a chain holds until the next one) |
41
+ | `A:ARG239,THR315` | with names, which must then match |
42
+ | `100` / `100A` | any chain; `100` takes its insertion codes, `100A` only that one |
43
+
44
+ Residues with nothing to rotate (Gly, Ala) and Pro stay rigid, with a warning.
45
+
46
+ ## Python API
47
+
48
+ ```python
49
+ from rdkit import Chem
50
+ from rdkit.Chem import AllChem
51
+ from ms_adtools import prepare_ligand, prepare_receptor, prepare_flexreceptor, pdbqt_to_rdkit
52
+
53
+ mol = Chem.AddHs(Chem.MolFromSmiles("CC(=O)Nc1ccc(O)cc1"))
54
+ AllChem.EmbedMolecule(mol)
55
+ pdbqt = prepare_ligand(mol) # str, with REMARK SMILES / IDX / H PARENT
56
+ receptor = prepare_receptor("1iep.pdb") # str
57
+ rigid, flex = prepare_flexreceptor("1iep.pdbqt", "A:239,315")
58
+ poses = pdbqt_to_rdkit(docked_text) # one conformer per MODEL, `score` on each
59
+ ```
60
+
61
+ | function | returns |
62
+ |---|---|
63
+ | `prepare_ligand(mol, open_macrocycles=False, hydrate=False, flexible_amides=False, ...)` | ligand PDBQT text |
64
+ | `prepare_reactive_ligand(mol, smarts, idx=0, ...)` | ligand PDBQT with the reactive atom typed |
65
+ | `prepare_receptor(path, repairs="", charges=None, cleanup=..., zinc=False, ccd=False)` | receptor PDBQT text |
66
+ | `prepare_flexreceptor(path, residues, reactive=())` | `(rigid, flex)` PDBQT texts |
67
+ | `pdbqt_to_rdkit(text)` | RDKit molecule, one conformer per pose |
68
+ | `dlg_to_pdbqt(text, cluster_leads=True)` | PDBQT poses of an AutoDock4/AutoDock-GPU DLG |
69
+ | `flexres_models(text, rigid=None)` | docked flexible residues as a multi-model PDB |
70
+ | `add_zinc_pseudo_atoms(pdbqt)` | receptor PDBQT with AutoDock4Zn TZ atoms |
71
+
72
+ `ms_adtools.reactive.reactive_config` writes the config of reactive docking;
73
+ `ms_adtools.zinc.PARAMETERS` is the `AD4Zn.dat` that autogrid4 needs for AutoDock4Zn maps.
74
+ Each function's docstring has the details.
75
+
76
+ ## Speed and memory
77
+
78
+ One CPU, Python 3.12, RDKit 2026.09; each row is a fresh process.
79
+
80
+ | | wall | peak RSS |
81
+ |---|---|---|
82
+ | import | 0.12 s | 71 MB |
83
+ | 200 ligands (Enamine, 3D) | 0.29 s (1.5 ms each) | 72 MB |
84
+ | receptor (4uwh, 4905 atoms) | 0.16 s | 83 MB |
85
+
86
+ On `1iep_receptorH.pdb` the receptor has AutoDockTools' atoms and types (charges within 0.02 on
87
+ average), and `prepare_flexreceptor` writes its rigid file byte for byte. `benchmarks/` has the
88
+ script and the full measurements.
89
+
90
+ ## License
91
+
92
+ MIT (`LICENSE`). The PDBQT conventions are AutoDockTools' (MGLTools, M. Sanner, TSRI) and the Forli
93
+ lab's; cite them with AutoDock. `src/ms_adtools/zinc/` carries AutoDock Vina's
94
+ `zinc_pseudo.py` (Apache-2.0) and the unmodified `AD4Zn.dat` parameter file (GPL-2.0-or-later
95
+ data), each with its own license (see its `NOTICE`).
@@ -0,0 +1,72 @@
1
+ # ms_adtools benchmark
2
+
3
+ Measured 2026-11-08 and 2026-11-10 on one machine: Python 3.12, RDKit 2026.09.1, numpy 2.5.4,
4
+ gemmi 0.7.6. meeko 0.8.0, the reference tool for AutoDock preparation, is measured alongside on
5
+ the same inputs. Reproduce with `python benchmarks/bench.py`; each row runs in a fresh
6
+ subprocess, so RSS is a clean-interpreter number.
7
+
8
+ Ligands: 200 Enamine_D10k molecules, hydrogens added, ETKDG + MMFF.
9
+ Receptor: `4uwh.pdb` (4905 atoms, `BENCH_PDB=.../4uwh.pdb`), read from the PDB file by both
10
+ (meeko with `allow_bad_res=True`, `default_altloc="A"`).
11
+
12
+ ## Time and memory
13
+
14
+ All single-threaded.
15
+
16
+ | measurement | wall s | RSS growth MB | peak RSS MB |
17
+ |---|---|---|---|
18
+ | `from rdkit import Chem` alone | 0.03 | 30 | 42 |
19
+ | import ms_adtools, ligand path | 0.12 | 44 | 56 |
20
+ | import ms_adtools, receptor path | 0.12 | 59 | 71 |
21
+ | import meeko | 1.31 | 231 | 243 |
22
+ | 200 ligands, ms_adtools | 0.29 | 2 | 72 |
23
+ | 200 ligands, meeko | 0.43 | 1 | 268 |
24
+ | receptor, ms_adtools | 0.16 | 12 | 83 |
25
+ | receptor, meeko (`Polymer.from_pdb_file`) | 2.6 | 110 | 354 |
26
+
27
+ Opening macrocycles takes the 200 ligands to 0.31 s and hydration to 0.36 s. The number that
28
+ mattered for us is the per-worker footprint: a worker that only prepares receptors peaks at
29
+ about 80 MB.
30
+
31
+ ## Output
32
+
33
+ `prepare_ligand` follows meeko's ligand conventions; over the same 200 ligands, in each mode,
34
+ its PDBQT matches meeko's:
35
+
36
+ | | rigid rings | open macrocycles | hydrated |
37
+ |---|---|---|---|
38
+ | same atoms written | 200/200 | 200/200 | 200/200 |
39
+ | same atom types | 200/200 | 189/200 | 200/200 |
40
+ | max charge difference | 0.000 | 0.000 | 0.000 |
41
+ | same TORSDOF | 200/200 | 200/200 | 200/200 |
42
+ | same number of BRANCHes | 200/200 | 200/200 | 200/200 |
43
+ | same W / G / CG counts | 200/200 | 200/200 | 200/200 |
44
+ | pose back to the input SMILES | 200/200 | 200/200 | 200/200 |
45
+
46
+ The 11 differences with open macrocycles are the choice of which C–C bond of the ring is cut
47
+ when several cuts give an equally shallow tree: the same number of breaks and the same TORSDOF,
48
+ one bond over.
49
+
50
+ The receptor follows AutoDockTools' conventions: bonds by distance (`DetermineConnectivity`),
51
+ bond orders and formal charges from the hydrogens the structure carries, Gasteiger over the
52
+ whole receptor. Against `prepare_receptor4.py` on `1iep_receptorH.pdb` it writes the same 2702
53
+ atoms with the same types, charges within 0.020 on average (ADT charges residue by residue);
54
+ `prepare_flexreceptor` writes ADT's rigid file byte for byte and the same torsion tree.
55
+
56
+ ## Scope
57
+
58
+ What each covers, for choosing between them:
59
+
60
+ | | ms_adtools | meeko |
61
+ |---|---|---|
62
+ | ligand PDBQT, `REMARK SMILES` / `IDX` / `H PARENT` | yes | yes |
63
+ | pose back to an RDKit molecule | yes | yes |
64
+ | receptor PDBQT | yes, by distances and hydrogens; CCD templates for non-standard residues | yes, by residue templates |
65
+ | flexible residues | yes | yes |
66
+ | macrocycle opening, hydrated docking, flexible amides | yes | yes |
67
+ | reactive docking | yes | yes |
68
+ | covalent docking | no | yes |
69
+ | AutoDock4 DLG poses | yes | yes |
70
+ | AutoDock4Zn TZ pseudo-atoms | yes | no |
71
+ | receptor input | PDB, mmCIF, PQR, PDBQT, mol2 | PDB, PQR, mmCIF, prody selection |
72
+ | required imports | rdkit, numpy, gemmi | rdkit, numpy, scipy, gemmi, pandas, prody |
@@ -0,0 +1,128 @@
1
+ """ms_adtools benchmark, meeko as the reference: import cost, ligand and receptor preparation time and memory.
2
+
3
+ Each measurement runs in its own subprocess, so the reported RSS is that of a fresh
4
+ interpreter that only imported what the measurement needs.
5
+
6
+ python bench.py # all measurements, as a markdown table
7
+ python bench.py import_meeko # one measurement, as JSON
8
+ """
9
+ import json
10
+ import os
11
+ import subprocess
12
+ import sys
13
+ import time
14
+
15
+ HERE = os.path.dirname(os.path.abspath(__file__))
16
+ LIGANDS = os.environ.get("BENCH_SDF", "/tmp/adt/ligs/set200.sdf")
17
+ RECEPTOR = os.environ.get("BENCH_PDB", os.path.join(HERE, "..", "test", "data", "1iep_receptorH.pdb"))
18
+
19
+
20
+ def rss_mb():
21
+ with open("/proc/self/status") as f:
22
+ for line in f:
23
+ if line.startswith("VmRSS:"):
24
+ return int(line.split()[1]) / 1024
25
+ return float("nan")
26
+
27
+
28
+ def _timed(fn):
29
+ """(wall seconds, cpu seconds, RSS growth MB, peak RSS MB) of fn()."""
30
+ base = rss_mb()
31
+ t, c = time.perf_counter(), time.process_time()
32
+ fn()
33
+ wall, cpu = time.perf_counter() - t, time.process_time() - c
34
+ return wall, cpu, rss_mb() - base, rss_mb()
35
+
36
+
37
+ def import_adtools_receptor():
38
+ def go():
39
+ from ms_adtools import prepare_receptor # noqa: F401 (numpy only)
40
+ return _timed(go)
41
+
42
+
43
+ def import_adtools_ligand():
44
+ def go():
45
+ from ms_adtools import prepare_ligand # noqa: F401 (pulls RDKit in)
46
+ return _timed(go)
47
+
48
+
49
+ def import_rdkit():
50
+ def go():
51
+ from rdkit import Chem # noqa: F401 (the floor both ligand paths pay)
52
+ return _timed(go)
53
+
54
+
55
+ def import_meeko():
56
+ def go():
57
+ import meeko # noqa: F401
58
+ return _timed(go)
59
+
60
+
61
+ def _mols():
62
+ from rdkit import Chem
63
+ return [m for m in Chem.SDMolSupplier(LIGANDS, removeHs=False) if m is not None]
64
+
65
+
66
+ def ligands_adtools():
67
+ from ms_adtools import prepare_ligand
68
+ mols = _mols()
69
+ out = []
70
+ return (*_timed(lambda: out.extend(prepare_ligand(m) for m in mols)), len(mols))
71
+
72
+
73
+ def ligands_meeko():
74
+ from rdkit import Chem
75
+ from meeko import MoleculePreparation, PDBQTWriterLegacy
76
+ # meeko refuses a molecule with more than one fragment, so the salts are split here,
77
+ # as ms_adtools does on its own
78
+ mols = [max(Chem.GetMolFrags(m, asMols=True), key=lambda f: f.GetNumHeavyAtoms()) for m in _mols()]
79
+ prep = MoleculePreparation()
80
+ out = []
81
+
82
+ def go():
83
+ for m in mols:
84
+ for setup in prep.prepare(m):
85
+ out.append(PDBQTWriterLegacy.write_string(setup)[0])
86
+ return (*_timed(go), len(mols))
87
+
88
+
89
+ def receptor_adtools():
90
+ from ms_adtools import prepare_receptor
91
+ return _timed(lambda: prepare_receptor(RECEPTOR))
92
+
93
+
94
+ def receptor_meeko():
95
+ from meeko import MoleculePreparation, Polymer, ResidueChemTemplates
96
+
97
+ def go():
98
+ Polymer.from_pdb_file(RECEPTOR, ResidueChemTemplates.create_from_defaults(),
99
+ MoleculePreparation(), blunt_ends=[(0, 0)], allow_bad_res=True,
100
+ default_altloc="A")
101
+ return _timed(go)
102
+
103
+
104
+ MEASUREMENTS = {k: v for k, v in list(globals().items())
105
+ if k.startswith(("import_", "ligands_", "receptor_"))}
106
+
107
+
108
+ def main():
109
+ if len(sys.argv) > 1:
110
+ print(json.dumps(MEASUREMENTS[sys.argv[1]]()))
111
+ return
112
+ rows = {}
113
+ for name in MEASUREMENTS:
114
+ p = subprocess.run([sys.executable, __file__, name], capture_output=True, text=True)
115
+ last = p.stdout.strip().splitlines()[-1:] # the tools print notes of their own
116
+ rows[name] = json.loads(last[0]) if p.returncode == 0 and last else p.stderr.strip().splitlines()[-1:]
117
+ print("| measurement | wall s | cpu s | RSS growth MB | peak RSS MB | n |")
118
+ print("|---|---|---|---|---|---|")
119
+ for name, r in rows.items():
120
+ if isinstance(r, list) and len(r) >= 4:
121
+ n = r[4] if len(r) > 4 else ""
122
+ print(f"| {name} | {r[0]:.2f} | {r[1]:.2f} | {r[2]:.0f} | {r[3]:.0f} | {n} |")
123
+ else:
124
+ print(f"| {name} | failed: {r} | | | | |")
125
+
126
+
127
+ if __name__ == "__main__":
128
+ main()