Metadata-Version: 2.4
Name: MDemon
Version: 0.1.0
Summary: Molecular Dynamics Analysis Tool with Cython Extensions
Author-email: Amphilagus <amphilagusjunior@gmail.com>
Maintainer-email: Amphilagus <amphilagusjunior@gmail.com>
License-Expression: GPL-2.0-or-later
Project-URL: Homepage, https://github.com/IMPNanoLabMDTeam/MDemon
Project-URL: Repository, https://github.com/IMPNanoLabMDTeam/MDemon
Project-URL: Issues, https://github.com/IMPNanoLabMDTeam/MDemon/issues
Project-URL: Documentation, https://github.com/IMPNanoLabMDTeam/MDemon/tree/main/docs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: matplotlib>=3.6.0
Requires-Dist: periodictable>=1.5.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: networkx>=3.2.1
Requires-Dist: jupyter>=1.1.1
Requires-Dist: dask[complete]>=2023.0.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: Cython>=3.0.0; extra == "dev"
Requires-Dist: ipykernel>=6.0.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Provides-Extra: build
Requires-Dist: Cython>=3.0.0; extra == "build"
Requires-Dist: numpy>=1.24.0; extra == "build"
Dynamic: license-file

# MDemon

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

## 项目简介

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

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

## 快速开始

### 环境配置

推荐使用 [uv](https://docs.astral.sh/uv/) 管理 Python 环境：

```bash
# 安装 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]"
```

### 基本使用

```python
import MDemon as md
from MDemon.constants import PHYSICS, CHEMISTRY
from MDemon.utils import WaligorskiZhangCalculator
import numpy as np

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

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

# 辐照计算示例
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 格式
│   └── base.py        # 基础读取器
├── selection/         # 原子选择工具
│   └── cylindrical.py # 圆柱形选择
└── utils/             # 实用工具
    ├── irradiation.py # 辐照分析工具
    ├── parallel.py    # 并行计算
    └── spatial.py     # 空间分析
```

### 主要模块说明

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

## 功能特性

### 物理常数与单位转换

```python
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 单位
```

### 材料属性查询

```python
from MDemon.constants.utils import get_material_property

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

### 辐照效应分析

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

## 文档和示例

- [常数使用指南](docs/constants_guide.md)
- [辐照分析指南](IRRADIATION_USAGE.md)
- [Jupyter 使用指南](JUPYTER_GUIDE.md)
- [使用示例](examples/)

## 开发和贡献

### 开发环境设置

```bash
# 克隆仓库
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 扩展以提升性能，安装时会自动编译：

```bash
# 手动重新编译 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](LICENSE) 文件。

## 致谢

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

---

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