MDemon 0.2.0

Molecular Dynamics Analysis Tool with Cython Extensions

MDemon

一个强大的分子动力学(MD)仿真数据分析工具，专注于高性能计算和辐照效应分析。

项目简介

MDemon 是一个现代化的分子动力学分析框架，提供全面的分析工具和物理常数库。主要特性包括：

• 🚀 高性能计算: 使用 Cython 扩展优化核心算法
• 📊 全面分析: 支持径向分布函数(RDF)、角分布分析等
• ⚛️ 辐照效应: 集成 Waligorski-Zhang 计算器用于辐照损伤分析
• 🔬 多格式支持: 兼容 LAMMPS、REAXFF、Extended XYZ 等主流 MD 文件格式
• 📚 丰富常数库: 内置物理、化学、材料常数和单位转换
• 🔧 灵活扩展: 模块化设计，易于扩展和定制

快速开始

环境配置

推荐使用 uv 管理 Python 环境：

# 安装 uv (如果尚未安装)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # Linux/macOS
# 或 .venv\Scripts\activate  # Windows

# 安装项目依赖
uv pip install -e .

# 安装开发依赖 (可选)
uv pip install -e ".[dev]"

基本使用

读取分子动力学文件

import MDemon as md

# 读取 LAMMPS DATA 文件
u = md.Universe("system.data")

# 读取 Extended XYZ 文件（如 GPUMD 格式）
u = md.Universe("system.xyz")

# 读取多个文件（DATA + REAXFF）
u = md.Universe("system.data", "bonds.reaxff")

# 访问原子信息
print(f"Total atoms: {len(u.atoms)}")
print(f"First atom coordinate: {u.atoms[0].coordinate}")

使用物理常数

from MDemon.constants import PHYSICS, CHEMISTRY
from MDemon.constants.utils import convert_energy

# 使用物理常数
print(f"玻尔兹曼常数: {md.k_B:.6e} J/K")
print(f"阿伏伽德罗数: {md.N_A:.6e} mol⁻¹")

# 单位转换
energy_ev = 1.0
energy_j = convert_energy(energy_ev, 'eV', 'J')
print(f"1 eV = {energy_j:.6e} J")

辐照效应分析

from MDemon.utils import WaligorskiZhangCalculator
import numpy as np

# 辐照计算示例
calc = WaligorskiZhangCalculator.from_material_preset('Ga2O3')
radius_array = np.logspace(0, 3, 100)  # 1 to 1000 nm
result = calc.calculate_radial_dose(radius_array, ion_Z=8, ion_energy=10.0)

项目结构

MDemon/
├── analysis/           # 分析模块
│   └── single_atom/   # 单原子分析工具
│       ├── angular.py # 角分布分析
│       ├── rdf.py     # 径向分布函数
│       └── ...
├── constants/         # 物理化学常数库
│   ├── chemistry.py   # 化学常数
│   ├── conversion.py  # 单位转换
│   ├── fundamental.py # 基本物理常数
│   ├── irradiation.py # 辐照相关常数
│   ├── material.py    # 材料属性
│   └── utils.py       # 工具函数
├── core/              # 核心数据结构
│   ├── database.py    # 数据库接口
│   ├── structure.py   # 分子结构
│   ├── universe.py    # 模拟体系
│   └── source.pyx     # Cython 优化模块
├── lib/               # 高性能计算库
│   ├── c_distances.pyx # 距离计算 (Cython)
│   ├── distance.py    # 距离分析
│   └── include/       # C/C++ 头文件
├── reader/            # 文件读取器
│   ├── LAMMPS.py      # LAMMPS 格式
│   ├── REAXFF.py      # REAXFF 格式
│   ├── XYZ.py         # Extended XYZ 格式
│   └── base.py        # 基础读取器
├── selection/         # 原子选择工具
│   └── cylindrical.py # 圆柱形选择
└── utils/             # 实用工具
    ├── irradiation.py # 辐照分析工具
    ├── parallel.py    # 并行计算
    └── spatial.py     # 空间分析

主要模块说明

• analysis: 提供各种分析算法，包括径向分布函数、角分布分析等
• constants: 完整的物理、化学常数库和单位转换系统
• core: 核心数据结构，管理分子结构和模拟体系
• lib: 使用 Cython 优化的高性能计算模块
• reader: 支持多种 MD 文件格式的读取器
• utils: 实用工具，包括辐照效应分析和并行计算支持

功能特性

物理常数与单位转换

from MDemon.constants.utils import convert_temperature, boltzmann_energy

# 温度转换
temp_k = convert_temperature(25.0, 'C', 'K')  # 298.15 K

# 热能计算
thermal_energy = boltzmann_energy(298.15, 'eV')  # eV 单位

材料属性查询

from MDemon.constants.utils import get_material_property

# 获取 β-Ga₂O₃ 的密度
density = get_material_property('Ga2O3_beta', 'density')
print(f"β-Ga₂O₃ 密度: {density} kg/m³")

辐照效应分析

from MDemon.utils import WaligorskiZhangCalculator

# 创建辐照计算器
calc = WaligorskiZhangCalculator.from_material_preset('Ga2O3')

# 计算径向剂量分布
dose_profile = calc.calculate_radial_dose(
    radius_nm=np.logspace(0, 3, 100),
    ion_Z=8,           # 氧离子
    ion_energy=10.0    # MeV/amu
)

文档和示例

完整文档

• 文件读取架构指南 - MDemon 核心文件读取逻辑详解
• XYZ Reader 使用指南 - Extended XYZ 格式读取指南
• 常数使用指南 - 物理化学常数库使用说明
• 辐照分析指南 - 辐照效应分析教程
• Jupyter 使用指南 - 在 Jupyter 中使用 MDemon

示例代码

• XYZ Reader 示例 - Extended XYZ 文件读取示例
• RDF 分析示例 - 径向分布函数分析
• 配位数分析示例 - 配位数分析演示
• 常数使用示例 - 物理常数和单位转换

开发和贡献

开发环境设置

# 克隆仓库
git clone <repository-url>
cd MDemon

# 设置开发环境
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# 运行测试
uv run pytest tests/

# 代码格式化
uv run black MDemon/
uv run isort MDemon/

# 代码检查
uv run ruff check MDemon/

构建 Cython 扩展

项目包含 Cython 扩展以提升性能，安装时会自动编译：

# 手动重新编译 Cython 扩展
uv run setup.py build_ext --inplace

系统要求

• Python 3.9+
• NumPy >= 1.24.0
• SciPy >= 1.10.0
• Pandas >= 2.0.0
• Matplotlib >= 3.6.0

许可证

本项目采用 GPL-2.0 许可证。详见 LICENSE 文件。

致谢

感谢所有为 MDemon 项目做出贡献的开发者和科研人员。

---

更多详细信息请参考项目文档和示例代码。如有问题，欢迎提交 Issue 或 Pull Request。