DuIvyInteraction

基于 MD 拓扑力场参数的分子间相互作用判定工具。

解决什么问题

现有工具（PLIP / ProLIF）分析 MD 轨迹时，通过 OpenBabel / RDKit 从坐标重建化学信息（键序、芳香性、加氢），丢弃了 MD 力场拓扑中原有的化学语义。这导致：

• 对 trjconv 导出的 PDB（无 CONECT / 键序）芳香性判定失败
• 每帧重复推断，效率低
• 推断结果与力场参数不自洽

核心思路

直接从 GROMACS tpr 拓扑中读取力场原子类型，确定性识别化学基团，与模拟力场完全自洽。

力场原子类型（如 GAFF 的 ca = 芳香碳、na = 吡咯氮）是参数化时由 antechamber / sobtop 做出的化学判决的留存记录。直接读取 = 零损失、零歧义，不需要从坐标反推。

工具优势

• 确定性：基团鉴定基于力场原子类型，不依赖几何推断
• 与力场自洽：结果与模拟使用的力场参数同源
• 全原子显式 H：H 键供体（D–H 键）、水桥（SOL 残基）、金属（元素+电荷）全部零推断
• Amber 全家族兼容：已验证 amber03/94/96/99/99sb/99sb-ildn/GS/14sb + GAFF，类型映射零冲突
• 支持 8 种相互作用类型：氢键、π-π 堆积、盐桥、π-阳离子、卤键、疏水、金属配位、水桥

依赖

• Python >= 3.9
• NumPy >= 1.20
• SciPy >= 1.7
• MDAnalysis >= 2.0
• h5py >= 3.0
• DuIvyTools >= 0.6.0
• GROMACS（gmx dump，用于文本格式 tpr 解析）

安装

pip install duivyinteractions

项目状态

基团鉴定、相互作用检测、HDF5 结果存储、xvg/xpm/CSV 导出、Pipeline 编排和 DII 命令行工具均已完成。详见 doc/ 目录下的设计文档。

使用

# 运行相互作用检测并保存 h5（--ff 必选，当前支持 amber）
dii run -t md.tpr -f md.xtc -o out/ --ff amber
# 可选参数：
#   --interactions hydrogen_bond,pi_stacking   只检测部分类型（默认 all=8类）
#   --strategy two_pass|per_frame|per_tuple    检测策略（默认 two_pass）

# 导出 h5 结果为 xvg/xpm/csv 并打印概览（支持多 Interaction h5）
dii export -i out/salt_bridge.h5 -o out_export/

支持的 8 种相互作用类型：氢键、π-π 堆积、盐桥、π-阳离子、卤键、疏水、金属配位、水桥。

在 Python 中调用：

from DuIvyInteractions.pipeline import Pipeline

# 配置：力场 + 策略
pipeline = Pipeline(ff="amber", strategy="two_pass")
pipeline.run("md.tpr", "md.xtc", "out/", interactions=None)  # None=全部8类

---

DuIvyInteraction (English)

Molecular interaction detection tool based on MD topology force-field parameters.

Problem Statement

Existing tools (PLIP / ProLIF) analyze MD trajectories by reconstructing chemistry (bond orders, aromaticity, protonation) from coordinates via OpenBabel / RDKit, discarding the chemical semantics already present in the MD force-field topology. This leads to:

• Failed aromaticity detection on PDB files exported by trjconv (no CONECT / bond orders)
• Repeated per-frame inference, inefficient
• Results inconsistent with the force-field parameters

Core Idea

Read force-field atom types directly from the GROMACS tpr topology to identify chemical groups deterministically, fully consistent with the simulation force field.

Force-field atom types (e.g., GAFF ca = aromatic carbon, na = pyrrole nitrogen) are the retained record of chemical decisions made during parameterization by antechamber / sobtop. Reading them directly means zero loss, zero ambiguity, and no need to reverse-engineer chemistry from coordinates.

Advantages

• Deterministic: group identification relies on force-field atom types, not geometric inference
• Consistent with the force field: results share the same origin as the parameters used in the simulation
• All-atom explicit H: H-bond donors (D–H bonds), water bridges (SOL residues), and metals (element + charge) all require zero inference
• Full Amber family support: validated against amber03/94/96/99/99sb/99sb-ildn/GS/14sb + GAFF, zero type-mapping conflicts
• 8 interaction types: hydrogen bond, π-π stacking, salt bridge, π-cation, halogen bond, hydrophobic, metal coordination, water bridge

Dependencies

• Python >= 3.9
• NumPy >= 1.20
• SciPy >= 1.7
• MDAnalysis >= 2.0
• h5py >= 3.0
• DuIvyTools >= 0.6.0
• GROMACS (gmx dump, for text-format tpr parsing)

Installation

pip install duivyinteractions

Project Status

Group identification, interaction detection, HDF5 result storage, xvg/xpm/CSV export, Pipeline orchestration, and the DII command-line tool are all complete. See the doc/ directory for design documents.

Usage

# run interaction detection and save h5 (--ff required, currently supports amber)
dii run -t md.tpr -f md.xtc -o out/ --ff amber
# optional arguments:
#   --interactions hydrogen_bond,pi_stacking    detect only selected types (default all=8)
#   --strategy two_pass|per_frame|per_tuple     detection strategy (default two_pass)

# export h5 results to xvg/xpm/csv and print overview (supports multi-Interaction h5)
dii export -i out/salt_bridge.h5 -o out_export/

The 8 supported interaction types: hydrogen bond, π-π stacking, salt bridge, π-cation, halogen bond, hydrophobic, metal coordination, water bridge.

Usage in Python:

from DuIvyInteractions.pipeline import Pipeline

# configuration: force field + strategy
pipeline = Pipeline(ff="amber", strategy="two_pass")
pipeline.run("md.tpr", "md.xtc", "out/", interactions=None)  # None = all 8 types