Define ligand torsion policy across RDKit and Vina reference differences

[dprada]

What

Document and decide DockingMT's ligand torsion-selection policy when RDKit rotatable-bond descriptors and published AutoDock Vina ligand PDBQT branch trees disagree. The current explicit-bond bridge validates a bounded set of structural conditions but does not implement a general automatic classifier.

Reproduction and evidence

• Pinned Vina 1IEP: seven published PDBQT branches; RDKit 2025.09.5 CalcNumRotatableBonds(Strict) counts seven on the hydrogen-suppressed source. This agreement alone does not validate automatic perception because DockingMT currently selects the seven reference bonds explicitly.
• Pinned Vina 1S63: six published PDBQT branches; RDKit Strict counts five. The extra published branch is the aryl–C≡N bond (source indices 26–27). DockingMT currently accepts that bond when explicitly requested. The source SDF has 29 atoms, while the PDBQT has 30, so hydrogen placement must be compared separately.
• Ethyl acetate CC(=O)OCC: RDKit Strict counts one rotatable bond; DockingMT currently accepts both nonterminal single-bond requests, including the ester acyl C–O bond (indices 1–3).
• The official Vina 5X72 P59/P69 stereoisomer pair has two branches each and provides a smaller positive structural control.

Outcome

Build a pinned, minimal differential case matrix with exact bond identity, fragment partition, source atom mapping, hydrogen handling, RDKit version and descriptor mode, and Vina parser acceptance. Define which differences are allowed explicit choices, which require warnings or rejection, and whether any automatic selection policy is scientifically supported. Do not silently identify RDKit Strict with Vina's branch choices.

DockingMT owns the docking protocol choice and user-facing policy. General chemical classification and reusable fragment output belong to uibcdf/molsysmt#224; the temporary PDBQT writer belongs ultimately to uibcdf/molsysmt#214. Related consumer work: #6. No Meeko runtime dependency is proposed.

Record: devguide/pending_proposals/define_ligand_torsion_policy_across_rdkit_and_vina_references.md (partial). Pinned matrix and current evidence: devguide/validation/vina_torsion_matrix.md and commit 2fe344d.

[dprada]

Pause checkpoint (2026-09-26). Published head: 2fe344d, clean main tracking origin/main. Local gates: Ruff lint/format, devguide index, git diff check, and pytest-receptor 103/103 passed. Remote CI run 36259334701 passed 4/4 jobs under gh-run-receptor; MolSysSuite policy run 36259335347 passed. The pinned matrix covers 1IEP, 1S63, and 5X72 P59/P69, reproducing reference-selected branch bonds and rigid fragments while keeping RDKit Strict/NonStrict comparisons separate. Four-character PDBQT atom-name defect #18 is fixed, archived, and closed. Open scientific decision here: specify the DockingMT protocol policy for explicitly requested ester acyl C–O and aryl–C≡N torsions; current acceptance is bounded validation, not automatic perception. Continue from devguide/pending_proposals/define_ligand_torsion_policy_across_rdkit_and_vina_references.md and devguide/validation/vina_torsion_matrix.md. Provider handoffs: MolSysMT #224 for classification/fragment contract, #214 for eventual PDBQT writer, #223 for output atoms absent from source, and #220 for added-H versus protomer-state correspondence. No new DockingMT implementation is needed merely to pause; #5 remains the separate chemistry/typing prerequisite for scientifically credible docking.

[dprada]

Checkpoint addendum: final published main head is e4a643f (the documentation cross-links were rebased cleanly over the synchronized MolSysSuite guide v1.4.12). The final CI run 36262166726 passed 4/4 jobs under gh-run-receptor, and MolSysSuite policy run 36262167451 passed. Local 103/103 pytest-receptor tests and Ruff/devguide checks passed after the documentation links. The 1S63 added-H evidence is now in MolSysMT #223 and #220 and cross-linked from the local validation matrix and pending proposal. Resume from this final head and the earlier pause checkpoint comment; no uncommitted files remain.