XRD Identifier

基于深度学习的 X 射线衍射（XRD）光谱材料识别系统。该系统使用 RegNet-1D 网络架构和 AdaCos 损失函数，能够从 XRD 光谱数据中自动识别晶体材料的类别。

📋 目录

功能特性
项目结构
环境要求
安装依赖
快速开始
详细使用说明
输出文件说明
模型架构
注意事项
许可证

✨ 功能特性

自动化数据准备流程：从 Crystallography Open Database (COD) 批量下载 CIF 文件，自动转换为 XRD 光谱数据
多进程加速：CIF 读取（read_cif.py）与 XRD 光谱转换（convertXRDspectra.py）支持多进程并行，可充分利用多核 CPU
深度学习分类模型：基于 RegNet-1D 架构，使用 AdaCos 自适应余弦相似度损失函数
真实数据预测：支持从实际测量的 XRD txt 文件进行材料识别
批量评估：使用 CIF 文件模拟 XRD 光谱，批量评估模型性能
递归文件搜索：自动递归搜索目录下的所有 CIF 文件

📁 项目结构

XRDidentifier_all/
├── download_script.py            # COD 数据库下载脚本
├── download_script_mp.py         # Materials Project 下载脚本
├── data/                         # 数据目录（软连接，指向外部备份目录）
│   ├── cif/                      # CIF 文件目录
│   │   ├── cod/                  # COD 下载的 CIF（按元素组合分子目录）
│   │   │   └── <元素组合>/
│   │   │       ├── COD-numbers.txt
│   │   │       └── *.cif
│   │   └── mp/                   # Materials Project 下载的 CIF
│   │       └── <元素组合>/
│   │           ├── MP-numbers.txt
│   │           └── *.cif（如 mp-149.cif）
│   ├── checkpoints/              # 训练好的模型权重（自动创建）
│   │   └── regnet1d_adacos_epoch*.pt
│   ├── xrd_pkls/                 # XRD 光谱数据（自动创建）
│   │   └── XRD_epoch*.pkl
│   ├── cif_test/                 # 测试用 CIF 文件目录
│   ├── lithium_datasets.pkl      # CIF 结构数据（read_cif.py 生成）
│   ├── material_labels.csv       # 材料名称 ↔ 类别 ID 映射（自动生成）
│   └── learning_curve.csv       # 训练曲线（自动生成）
├── real_data/                    # 真实测量的 XRD 数据示例
│   ├── AlN/
│   └── CST/
├── auto_download.sh              # 基于 COD 的批量自动下载脚本（调用 download_script.py）
├── auto_download_mp.sh           # 基于 MP 的批量自动下载脚本（调用 download_script_mp.py）
├── read_cif.py                   # CIF 文件读取和验证
├── convertXRDspectra.py         # CIF → XRD 光谱转换
├── train_expert.py              # 模型训练脚本
├── predict_from_txt.py          # 从真实 txt 文件预测
├── evaluate_from_cif.py         # 批量评估脚本
├── net1d.py                     # RegNet-1D 网络定义
└── README.md                    # 本文件

🔧 环境要求

Python 3.7+
PyTorch 1.8+（支持 CUDA 更佳）
pymatgen（用于 CIF 解析和 XRD 模拟）
其他依赖见下方安装说明

📦 安装依赖

# 安装 PyTorch（根据你的 CUDA 版本选择）
# CPU 版本：
pip install torch torchvision

# CUDA 版本（示例，请访问 https://pytorch.org 获取最新命令）：
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# 安装其他依赖
pip install pymatgen numpy pandas scikit-learn matplotlib tqdm

# 若使用 Materials Project 下载脚本，还需：
pip install mp-api

🚀 快速开始

1. 下载 CIF 文件

支持 COD 与 Materials Project (MP) 两个数据源，按元素组合下载 CIF。

从 COD 下载（无需 API Key）：

# 下载只含 Bi 和 Si 的化合物 → 保存到 ./data/cif/cod/BiSi/
python download_script.py --elements "Bi,Si" --output-root ./data/cif

# 下载至少含 Bi 和 Si（可含其他元素）的化合物
python download_script.py --elements "Bi,Si" --allow-extra-elements --output-root ./data/cif

从 Materials Project 下载（需 API Key，见 MP 官网）：

# 设置 API Key 后下载 → 保存到 ./data/cif/mp/BiSi/
export MP_API_KEY="your_api_key"   # 或使用 --api-key 参数
pip install mp-api                 # 首次使用需安装
python download_script_mp.py --elements "Bi,Si" --output-root ./data/cif
python download_script_mp.py --elements "Bi,Si" --allow-extra-elements --output-root ./data/cif

2. 准备训练数据

步骤 2.1：读取和验证 CIF 文件

python read_cif.py --input ./data/cif --output ./data/lithium_datasets.pkl

该脚本会：

递归搜索 ./data/cif 目录下的所有 .cif 文件
使用多进程并行验证每个 CIF 的有效性（跳过损坏或物理上无意义的文件）
提取结构信息、原子类型、空间群和材料化学式
显示进度条并保存为 ./data/lithium_datasets.pkl（pymatgen 的 warning 已屏蔽，便于查看进度）

步骤 2.2：转换为 XRD 光谱数据

python convertXRDspectra.py --input ./data/lithium_datasets.pkl --batch 8 --n_aug 5

该脚本会：

使用 pymatgen 的 XRDCalculator 模拟 XRD 衍射峰，多进程并行转换（默认使用全部 CPU 核）
通过向量化高斯卷积将峰转换为连续光谱（2θ 范围：0-120°，步长 0.02°）
进行数据增强（随机 Debye-Waller 因子）
生成 ./data/xrd_pkls/XRD_epoch*.pkl（包含光谱数组和标签）
自动生成 ./data/material_labels.csv（材料名称 ↔ 类别 ID 映射）

3. 训练模型

python train_expert.py --input ./data/xrd_pkls/XRD_epoch5.pkl --output ./data/learning_curve.csv --batch 16 --n_epoch 100

训练过程会：

自动划分训练集/验证集/测试集（默认 70%/15%/15%）
使用 RegNet-1D + AdaCos 进行训练
保存最佳模型到 ./data/checkpoints/regnet1d_adacos_epoch<epoch>.pt
记录训练曲线到 ./data/learning_curve.csv

4. 使用模型进行预测

从真实测量的 XRD txt 文件预测：

python predict_from_txt.py --input real_data/CST/CrSiTe3_300_10_80_0.01.txt

脚本会自动：

解析 txt 文件中的 2θ-强度数据
插值到标准网格（0-120°，步长 0.02°）
归一化处理
加载最新模型进行预测
输出 Top-3 候选类别和相似度分数

批量评估（使用 CIF 文件模拟）：

python evaluate_from_cif.py --cif_dir ./data/cif_test --batch_size 32

📖 详细使用说明

CIF 下载脚本 - COD (`download_script.py`)

从 Crystallography Open Database (COD) 按元素组合下载 CIF，保存到 <output-root>/cod/<元素组合>/。

python download_script.py --elements "元素1,元素2,..." [选项]

参数说明：

--elements / -e：必需，元素列表，例如 "Bi,Si" 或 "Bi, Si, Te"
--output-root：输出根目录（默认：./data/cif）；COD 数据写入 <output-root>/cod/<元素组合>/
--allow-extra-elements：允许化合物包含除指定元素外的其他元素
--sleep：下载间隔时间（秒），避免对服务器造成压力（默认：0.2）

示例：

python download_script.py --elements "Bi,Si"
python download_script.py --elements "Bi,Si,Te" --allow-extra-elements

# 或使用自动化批量下载脚本（需根据实际环境修改脚本中的 WORK_DIR / VENV_PATH 等配置）
bash auto_download.sh        # 从 COD 批量下载常用体系（CrSiTe3、BiSiTe3、AlInS/Se、ScAlN 及杂质等）

CIF 下载脚本 - Materials Project (`download_script_mp.py`)

从 Materials Project (MP) 按元素组合下载 CIF，保存到 <output-root>/mp/<元素组合>/。需 MP API Key（申请），并安装 pip install mp-api。

export MP_API_KEY="your_api_key"   # 或使用 --api-key
python download_script_mp.py --elements "元素1,元素2,..." [选项]

参数说明：

--elements / -e：必需，元素列表
--output-root：输出根目录（默认：./data/cif）；MP 数据写入 <output-root>/mp/<元素组合>/
--allow-extra-elements：允许除指定元素外还含其他元素（最多 8 种）
--api-key：MP API Key（也可设置环境变量 MP_API_KEY 或 PMG_MAPI_KEY）
--sleep：每写入一个 CIF 后的等待时间（秒），默认 0.2

示例：

python download_script_mp.py --elements "Bi,Si"
python download_script_mp.py --elements "Bi,Si,Te" --allow-extra-elements

# 或使用自动化批量下载脚本（需根据实际环境修改脚本中的 WORK_DIR / VENV_PATH 等配置）
bash auto_download_mp.sh     # 从 Materials Project 批量下载与 auto_download.sh 相同组合

CIF 读取脚本 (`read_cif.py`)

python read_cif.py --input <CIF目录> --output <输出pkl文件>

功能：

递归搜索指定目录下的所有 .cif 文件
多进程并行验证文件有效性并提取结构信息（默认进程数：min(32, CPU核数)）
显示进度条；pymatgen 的 UserWarning/FutureWarning 已屏蔽
输出包含 (structures, atoms, attributes) 的 pickle 文件

示例：

python read_cif.py --input ./data/cif --output ./data/lithium_datasets.pkl

XRD 光谱转换脚本 (`convertXRDspectra.py`)

python convertXRDspectra.py --input <pkl文件> [--batch <batch大小>] [--n_aug <增强次数>] [--num_workers <进程数>] [--resume_from_epoch <epoch数>]

功能：

将 pkl 中的结构数据转换为 XRD 光谱（多进程并行，默认使用全部 CPU 核）
使用随机 Debye-Waller 因子进行数据增强
向量化高斯展宽，生成标准化的 XRD 光谱数组（形状：(N, L)，L=6000）
脚本内已设置每进程 1 线程（OMP/MKL/OpenBLAS），避免与多 worker 争抢 CPU，便于多核跑满

参数说明：

--input：输入的 pickle 文件路径（默认：./data/lithium_datasets.pkl）
--batch：DataLoader 每批返回的样本数（默认：8）；不影响总耗时，仅影响主循环批次数
--n_aug：数据增强次数（默认：5）
--num_workers：并行进程数（默认：os.cpu_count()，即用满所有核）；若内存紧张可适当减小，如 --num_workers 16
--resume_from_epoch：从已有的 XRD_epoch<resume_from_epoch>.pkl 恢复，只生成后续 epoch（例如：--resume_from_epoch 4 表示从 epoch4 开始，生成 epoch5 及之后）。适用场景：如果之前生成到 epoch4 后中断，可用此参数继续生成，避免重复计算

输出：

./data/xrd_pkls/XRD_epoch*.pkl：每个 epoch 的 XRD 光谱数据
./data/material_labels.csv：材料名称 ↔ 类别 ID 映射（自动生成）

示例：

# 标准用法：生成 epoch1-5
python convertXRDspectra.py --input ./data/lithium_datasets.pkl --batch 8 --n_aug 5

# 从 epoch4 恢复，只生成 epoch5（资源受限时可用 num_workers=1）
python convertXRDspectra.py --input ./data/lithium_datasets.pkl --batch 8 --n_aug 5 --resume_from_epoch 4 --num_workers 1

模型训练脚本 (`train_expert.py`)

python train_expert.py --input <XRD数据pkl> --output <学习曲线csv> --batch <batch大小> --n_epoch <训练轮数>

功能：

训练 RegNet-1D + AdaCos 分类模型
自动保存最佳模型权重
记录训练/验证损失和准确率

参数说明：

--input：XRD 光谱数据 pickle 文件（默认：./data/xrd_pkls/XRD_epoch5.pkl）
--output：学习曲线 CSV 文件（默认：./data/learning_curve.csv）
--batch：批处理大小（默认：16）
--n_epoch：训练轮数（默认：100）

输出：

./data/checkpoints/regnet1d_adacos_epoch<epoch>.pt：模型权重文件
./data/learning_curve.csv：训练曲线数据

预测脚本 (`predict_from_txt.py`)

python predict_from_txt.py --input <txt文件路径> [--model <模型路径>] [--labels <标签csv>] [--unknown-threshold <阈值>]

功能：

从真实测量的 XRD txt 文件进行材料识别
自动查找最新模型权重
输出 Top-3 候选类别和相似度分数
支持基于 softmax 概率的“未知类”判定（Open-set / Out-of-distribution 简单处理）

参数说明：

--input：必需，输入的 txt 光谱文件路径
--model：可选，指定模型权重路径（默认：自动查找 ./data/checkpoints/、./checkpoints/ 或当前目录下最新的 .pt）
--labels：标签映射文件（默认：./data/material_labels.csv）
--unknown-threshold：可选，当最高类别的 softmax 概率低于该阈值时，将结果判定为“未知材料 (Unknown)`；默认不启用（None）

txt 文件格式：

支持包含 # 注释行的格式
每行包含两列：2θ 角度和强度值（用空格或制表符分隔）

示例：

# Start theta: 10.0
10.00158    3631.94759
10.01158    3636.76339
...

示例：

python predict_from_txt.py --input real_data/CST/CrSiTe3_300_10_80_0.01.txt

评估脚本 (`evaluate_from_cif.py`)

python evaluate_from_cif.py --cif_dir <CIF目录> [选项]

功能：

从 CIF 文件模拟 XRD 光谱
使用训练好的模型进行批量分类
计算 Top-1 分类准确率

参数说明：

--cif_dir：CIF 文件目录（默认：./data/cif_test）
--labels：标签映射文件（默认：./data/material_labels.csv）
--model：模型权重路径（默认：自动查找）
--batch_size：批处理大小（默认：32）
--max_samples：最多评估样本数（用于调试，默认：全部）

示例：

python evaluate_from_cif.py --cif_dir ./data/cif_test --batch_size 32

📊 输出文件说明

`material_labels.csv`

材料名称与类别 ID 的映射表，格式：

,0
Al2N2,7
Al4F16H16N4,12
...

第一列：材料名称（按元素排序后的化学式）
第二列：类别 ID（整数）

`learning_curve.csv`

训练过程记录，包含列：

loss_train：训练损失
acc_train：训练准确率（Top-5）
loss_val：验证损失
acc_val：验证准确率（Top-5）

`./data/checkpoints/regnet1d_adacos_epoch*.pt`

PyTorch 模型权重文件，包含：

Net1D 主网络参数
AdaCos 分类头参数

`./data/xrd_pkls/XRD_epoch*.pkl`

XRD 光谱数据，包含：

spectra：形状 (N, L) 的光谱数组（L=6000）
labels：形状 (N,) 的标签数组

🏗️ 模型架构

RegNet-1D

基础架构：1D 卷积神经网络，基于 RegNet 设计理念
输入：形状 (batch_size, 1, 6000) 的 XRD 光谱数据
特征提取：多层 1D 卷积 + SE（Squeeze-and-Excitation）模块
输出特征维度：1024

AdaCos（Adaptive Cosine Scaling）

类型：自适应余弦相似度分类头
原理：将特征和权重归一化后计算余弦相似度，并自适应调整缩放因子
优势：相比固定缩放因子（如 ArcFace），能根据训练数据自动调整，提高分类性能

损失函数

AngularPenaltySMLoss：角度惩罚 Softmax 损失（CosFace）
Top-5 准确率：训练和验证时使用 Top-5 准确率评估

⚠️ 注意事项

CIF 文件格式：确保 CIF 文件符合标准格式，损坏的文件会被自动跳过
元素组合下载：使用 download_script.py 时，默认只下载恰好包含指定元素的化合物；使用 --allow-extra-elements 可包含其他元素
模型类别限制：模型只能识别训练时见过的材料类别。如果输入的材料不在 material_labels.csv 中，模型无法正确分类
txt 文件格式：predict_from_txt.py 会自动处理各种格式的 txt 文件，但建议使用标准的 2θ-强度两列格式
GPU 加速：训练和推理过程会自动检测并使用 GPU（如果可用）；convertXRDspectra.py 为多进程并行设计，在 CPU 上运行以充分利用多核
目录结构：所有输出目录（./data/checkpoints/、./data/xrd_pkls/ 等）会在首次使用时自动创建
多进程与内存：read_cif.py、convertXRDspectra.py 的多进程会占用较多内存（每进程约 2–3 GB 量级）。若内存不足可减小 convertXRDspectra.py 的 --num_workers；read_cif.py 的并行数在代码内为 min(32, CPU核数)，可按需修改。
CIF 目录结构：COD 数据保存在 ./data/cif/cod/<元素组合>/，MP 数据保存在 ./data/cif/mp/<元素组合>/。若之前使用过旧版脚本、数据在 cif/<元素组合>/，可整体移动到 ./data/cif/cod/<元素组合>/，再运行 read_cif.py --input ./data/cif。
数据增强中断恢复：如果 convertXRDspectra.py 在生成过程中中断（例如生成到 epoch4 后死机），可使用 --resume_from_epoch 4 从已有文件恢复，只生成后续 epoch，避免重复计算已完成的 epoch。
数据目录管理：项目使用 ./data 软连接指向外部备份目录，便于维护不同版本的数据。所有生成的数据文件（CIF、模型、训练数据等）都保存在 ./data/ 目录下，该目录已加入 .gitignore。

📝 完整工作流程示例

# 1. 下载 CIF 文件（COD 和/或 MP，例如：Bi-Si 化合物）
python download_script.py --elements "Bi,Si" --output-root ./data/cif
# export MP_API_KEY="your_key"; python download_script_mp.py --elements "Bi,Si" --output-root ./data/cif

# 2. 读取和验证 CIF（会递归包含 ./data/cif/cod/ 与 ./data/cif/mp/ 下所有 .cif）
python read_cif.py --input ./data/cif --output ./data/lithium_datasets.pkl

# 3. 转换为 XRD 光谱（默认用满 CPU 核，可选 --num_workers 24 等）
python convertXRDspectra.py --input ./data/lithium_datasets.pkl --batch 8 --n_aug 5

# 4. 训练模型
python train_expert.py --input ./data/xrd_pkls/XRD_epoch5.pkl --output ./data/learning_curve.csv --batch 16 --n_epoch 100

# 5. 使用模型预测（真实数据）
python predict_from_txt.py --input real_data/CST/CrSiTe3_300_10_80_0.01.txt

# 6. 批量评估（使用测试 CIF）
python evaluate_from_cif.py --cif_dir ./data/cif_test --batch_size 32

📄 许可证

本项目遵循相应的开源许可证（请根据实际情况填写）。

🙏 致谢

pymatgen：用于 CIF 解析和 XRD 模拟
PyTorch：深度学习框架
tqdm：进度条显示（read_cif.py）
**Crystallography Open Database (COD)**：提供晶体结构数据
RegNet：网络架构设计参考
AdaCos：自适应余弦相似度损失函数

如有问题或建议，欢迎提交 Issue 或 Pull Request。

XRD Identifier

📋 目录

✨ 功能特性

📁 项目结构

🔧 环境要求

📦 安装依赖

🚀 快速开始

1. 下载 CIF 文件

2. 准备训练数据

3. 训练模型

4. 使用模型进行预测

📖 详细使用说明

CIF 下载脚本 - COD (download_script.py)

CIF 下载脚本 - Materials Project (download_script_mp.py)

CIF 读取脚本 (read_cif.py)

XRD 光谱转换脚本 (convertXRDspectra.py)

模型训练脚本 (train_expert.py)

预测脚本 (predict_from_txt.py)

评估脚本 (evaluate_from_cif.py)

📊 输出文件说明

material_labels.csv

learning_curve.csv

./data/checkpoints/regnet1d_adacos_epoch*.pt

./data/xrd_pkls/XRD_epoch*.pkl

🏗️ 模型架构

RegNet-1D

AdaCos（Adaptive Cosine Scaling）

损失函数

⚠️ 注意事项

📝 完整工作流程示例

📄 许可证

🙏 致谢

CIF 下载脚本 - COD (`download_script.py`)

CIF 下载脚本 - Materials Project (`download_script_mp.py`)

CIF 读取脚本 (`read_cif.py`)

XRD 光谱转换脚本 (`convertXRDspectra.py`)

模型训练脚本 (`train_expert.py`)

预测脚本 (`predict_from_txt.py`)

评估脚本 (`evaluate_from_cif.py`)

`material_labels.csv`

`learning_curve.csv`

`./data/checkpoints/regnet1d_adacos_epoch*.pt`

`./data/xrd_pkls/XRD_epoch*.pkl`