分子动力学轨迹中π-π堆积数量分析工具。支持智能识别芳香环、基于几何判据的π-π堆积检测，以及时间序列分析。
- 智能环检测：自动解析Gromacs ITP/TOP拓扑文件，基于键连接图识别6元芳香环
- 稠环处理：正确处理稠环结构（如萘、蒽醌），只保留最小独立环
- 几何判据：距离判据（默认5Å）+ 角度判据（默认30°），考虑平行和反平行
- 周期性边界条件：完整支持PBC处理
- 性能优化：Cell list空间加速算法，适用于大体系
- 多分子支持：支持分析多ITP文件体系（如DOX + MM混合物）
- 可视化输出：自动生成时间序列图
# 克隆仓库
git clone https://github.com/tgraphite/gmx_pipistack.git
cd gmx_pipistack
# 安装依赖
pip install -r requirements.txt
# 安装包
pip install -e .- Python >= 3.9
- MDAnalysis >= 2.0.0
- NumPy >= 1.21.0
- Pandas >= 1.3.0
- Matplotlib >= 3.5.0
python scripts/analyze.py \
--topology topol.tpr \
--trajectory traj.xtc \
--itp molecule.itp \
--residue-filter MOL \
--output results/pipi_results.csv \
--plot results/pipi_plot.png \
--distance-cutoff 5.0 \
--angle-cutoff 30.0适用于包含多种分子的体系：
python scripts/analyze_multi_itp.py \
--topology all_md.tpr \
--trajectory allaftermd.xtc \
--itp DOX.itp MM.itp \
--output results/multi_itp_results.csv \
--plot results/multi_itp_plot.png \
--distance-cutoff 8.0 \
--angle-cutoff 45.0| 参数 | 说明 | 默认值 |
|---|---|---|
--topology |
拓扑文件（TPR/GRO/PDB） | 必需 |
--trajectory |
轨迹文件（XTC/TRR/DCD） | 必需 |
--itp |
ITP拓扑文件（可多个） | 必需 |
--residue-filter |
残基名过滤器 | 无 |
--distance-cutoff |
距离判据（Å） | 5.0 |
--angle-cutoff |
角度判据（度） | 30.0 |
--output |
输出CSV文件路径 | pipi_results.csv |
--plot |
输出图表路径 | 无 |
两个芳香环被认为形成π-π堆积，当且仅当满足以下两个条件：
- 距离判据：两环中心距离 < r_cutoff（默认5.0 Å）
- 角度判据：两环法向量夹角 < a_cutoff（默认30°）
法向量夹角计算考虑双向性：
θ_eff = min(θ, 180° - θ)
- ITP解析：解析原子类型和键连接信息
- DFS环检测：深度优先搜索检测5-8元环
- 最小独立环筛选：对于稠环体系，移除外围大环，只保留最小独立环
- 间位原子选择：对每个6元环自动选取间隔的3个原子用于法向量计算
使用Cell list算法将邻居搜索复杂度从O(N²)降至O(N)：
- 将模拟盒子划分为单元格
- 只搜索相邻单元格内的邻居
- 显著加速大体系计算
python scripts/analyze.py \
--topology examples/1_COF/npt.tpr \
--trajectory examples/1_COF/npt.trr \
--itp examples/1_COF/COF-1-singlelayer.itp \
--residue-filter MOL \
--distance-cutoff 5.0 \
--angle-cutoff 30.0结果：检测到64个芳香环，平均49.94对π-π堆积
python scripts/analyze_multi_itp.py \
--topology examples/2_GAO/all_md.tpr \
--trajectory examples/2_GAO/allaftermd.xtc \
--itp examples/2_GAO/DOX.itp examples/2_GAO/MM.itp \
--distance-cutoff 8.0 \
--angle-cutoff 45.0结果：检测到7个芳香环（DOX: 3, MM: 4），平均5.04对π-π堆积
gmx_pipistack/
├── src/ # 核心源代码
│ ├── topology_parser.py # ITP解析与环检测
│ ├── analyzer.py # 主分析引擎
│ ├── geometry.py # 几何计算模块
│ ├── cell_list.py # Cell list空间加速
│ └── io/
│ └── result_writer.py # 结果输出
├── scripts/ # 命令行脚本
│ ├── analyze.py # 单ITP分析
│ └── analyze_multi_itp.py # 多ITP分析
├── tests/ # 单元测试
├── docs/ # 文档
│ ├── DEVELOPMENT_PLAN.md # 开发方案
│ └── GAO_system_report.md # GAO体系报告
├── config/ # 配置示例
├── requirements.txt # 依赖清单
├── setup.py # 安装配置
└── README.md # 本文件
- 环检测算法参考：reax_tools
- DFS环检测实现：
src/topology_parser.py - Cell list实现：
src/cell_list.py
如果您使用了本工具，请引用：
@software{pipi_stack_analyzer,
author = {Hanxiang Chen},
title = {Pi-Pi Stack Analyzer},
url = {https://github.com/tgraphite/gmx_pipistack},
year = {2026}
}GPLv2 License