# xyzprocess

**Repository Path**: hao-yiping/xyzprocess

## Basic Information

- **Project Name**: xyzprocess
- **Description**: 处理单点能.xyz格式文件的python3 脚本工具
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xyzprocess

#### 介绍
处理单点能.xyz格式文件的Python 3脚本工具，提供分子结构和能量信息的读取、处理、分析和可视化功能。

#### 软件架构
- **xyz.py**：核心模块，定义了 `xyz` 类用于表示分子的结构和能量信息，提供文件读写、分子比较等功能
- **statis.py**：统计分析模块，提供能量分布统计和可视化功能
- **split.py**：数据集分割模块，提供随机抽样和训练集/测试集分割功能
- **EANNswitch.py**：格式转换模块，提供 xyz 格式到 EANN 格式的转换功能
- **test/**：测试目录，包含各种测试脚本

#### 核心功能

##### xyz.py 模块
1. **xyz 类**：
   - 存储分子的原子数量、能量、坐标和力信息
   - `check` 方法：检查两个分子是否相同
   - `demo` 方法：演示如何使用 xyz 对象
   - `print` 方法：将分子信息输出到文件
   - `Metric` 方法：计算两个分子之间的差异

2. **loadxyz 函数**：
   - 从文件中加载多个xyz分子
   - 支持处理空行等格式问题
   - 返回一个包含所有xyz对象的列表

##### statis.py 模块
1. **statisE 函数**：
   - 统计分子的能量平均值、方差、上界、下界
   - 计算平均值和上界与下界的差值
   - 绘制能量分布散点图
   - 支持将结果保存为图片

2. **命令行工具**：
   - 直接运行脚本处理 xyz 文件
   - 支持 `-s` 或 `--save` 选项保存图片

##### split.py 模块
1. **split_dataset 函数**：
   - 从输入文件读取全部构型
   - 随机抽取指定数量的构型
   - 对抽取的构型进行洗牌
   - 按比例分割为训练集和测试集
   - 如果测试集数量为0，则不输出测试集文件

2. **命令行工具**：
   - 直接运行脚本处理 xyz 文件
   - 支持指定抽样数量、训练集比例和输出文件前缀

##### EANNswitch.py 模块
1. **convert_to_eann 函数**：
   - 从输入文件读取 xyz 格式的构型
   - 将 xyz 格式转换为 EANN 格式
   - 自动添加晶格参数和周期性边界条件
   - 根据元素符号自动推断原子质量
   - 支持包含力信息的构型

2. **get_atomic_mass 函数**：
   - 根据元素符号获取相对原子质量
   - 支持常见元素的质量查询

3. **命令行工具**：
   - 直接运行脚本进行格式转换
   - 支持指定输入文件和输出文件

#### 使用说明

##### 1. 作为模块导入使用

```python
import xyz
import statis

# 加载xyz文件
xyz_list = xyz.loadxyz('sample.xyz')

# 统计能量分布
result = statis.statisE(xyz_list, save_fig=True)

# 比较两个分子
metric = xyz_list[0].Metric(xyz_list[1])
print(f"分子差异: {metric}")

# 输出分子信息
xyz_list[0].demo()

# 将分子信息输出到文件
with open('output.xyz', 'w') as f:
    xyz_list[0].print(f)
```

##### 2. 直接运行脚本

```bash
# 统计能量分布，不保存图片
python statis.py sample.xyz

# 统计能量分布，保存图片
python statis.py -s sample.xyz

# 随机抽样并分割数据集
python split.py sample.xyz 10 0.7 output

# 随机抽样但不输出测试集（测试集数量为0）
python split.py sample.xyz 10 1.0 output

# 将 xyz 格式转换为 EANN 格式
python EANNswitch.py sample.xyz output.eann
```

##### 3. 运行测试

```bash
# 测试 Metric 方法
python test/test_metric.py sample.xyz

# 测试其他功能
python test/test_loadxyz.py
python test/test_precision.py
```

#### xyz 文件格式说明

参考 sample.xyz 文件格式：
1. 每个分子块以原子数量开始
2. 第二行是能量值
3. 接下来的行是每个原子的信息，包括：原子标签、x坐标、y坐标、z坐标、力的三个分量（如果有）

示例：
```
9
-97208.40600498248
C       0.0072  -0.5687 0.0     1.4517297437249999      6.01923561735   5.2067503058e-07
C       -1.2854 0.2499  0.0     17.9533587683   -5.1623821924   3.49002255005e-07
O       1.1304  0.3147  0.0     -4.0883694515   22.5901955842   3.30876819905e-06
H       0.0392  -1.1972 0.89    -1.141572648295 -9.7469181345   7.64734244805
H       0.0392  -1.1972 -0.89   -1.141572648295 -9.7469181345   -7.64734244805
H       -1.3175 0.8784  0.89    -2.48205465155  4.933531279     4.3699824457
H       -1.3175 0.8784  -0.89   -2.48205465155  4.933531279     -4.3699824457
H       -2.1422 -0.4239 0.0     -5.5147904611   -3.0206752465   -8.9092739811e-09
H       1.9857  -0.1365 0.0     -2.4392777023   -10.83820307755 -6.07213606025e-08
```

#### 依赖项
- Python 3
- numpy
- matplotlib

#### 安装依赖

```bash
pip install numpy matplotlib
```

#### 项目结构

```
xyzprocess/
├── xyz.py              # 核心模块
├── statis.py           # 统计分析模块
├── split.py            # 数据集分割模块
├── EANNswitch.py       # 格式转换模块
├── sample.xyz          # 示例文件
├── test/               # 测试目录
│   ├── test_metric.py  # Metric方法测试
│   ├── test_loadxyz.py # 文件加载测试
│   └── test_precision.py # 精度测试
├── README.md           # 项目说明
└── README.en.md        # 英文说明
```