Metadata-Version: 2.4
Name: duivyinteractions
Version: 0.0.4
Summary: Molecular interaction detection tool based on MD topology force-field parameters
Author-email: DuIvy Team <1972069239@qq.com>
License: GPL-3.0
Project-URL: Homepage, https://github.com/CharlesHahn/DuIvyInteractions
Project-URL: Documentation, https://duivyinteractions.readthedocs.io/
Project-URL: Source, https://github.com/CharlesHahn/DuIvyInteractions
Keywords: molecular dynamics,interaction analysis,GROMACS,tpr,force field,protein-ligand
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: MDAnalysis>=2.0
Requires-Dist: h5py>=3.0
Requires-Dist: scipy>=1.7
Requires-Dist: DuIvyTools>=0.6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# 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 解析）

## 安装

```bash
pip install duivyinteractions
```

## 项目状态

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

## 使用

```bash
# 运行相互作用检测并保存 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 中调用：

```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

```bash
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

```bash
# 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:

```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
```
