XRD ML Phase Classification Pipeline

这是一个基于传统机器学习（PCA 降维 + XGBoost / Random Forest 分类）的 XRD 光谱物相分类项目。以下文档描述了位于 Novel-Space-CST 目录下的 6 个核心脚本的功能和主要流程。

快速开始

在运行任何脚本之前，请务必先进入对应的工作目录：

cd /root/xrd/wrh-ML/Novel-Space-CST

---

脚本功能及运行指南

1. download_mp.py —— 下载结构数据

功能：这是准备阶段脚本。它会连接到 Materials Project (MP) 数据库，根据用户输入的材料 ID（如 mp-1700），利用你的 API Key 自动下载对应材料的晶胞结构文件（CIF），并保存在 All_CIFs/ 下。

运行方法：

python download_mp.py
# 运行后会提示“输入ID：”，只需输入数字后缀（如材料是mp-1234，则输入1234，视代码实际前缀而定）。

2. construct_xrd_model.py —— 训练分类模型

功能：扫描 References/ 目录中的已知 CIF 原型文件，利用布拉格定律衍生生成包含仪器偏移、晶粒细化变宽、各向异性等物理扰动的 增广仿真光谱。接着对 4501 长度的特征向量进行 PCA (主成分分析) 平整降维，送入决策树框架进行自动机器学习，最后将模型持久化并导出为 Model_ML.pkl。

运行方法：

python construct_xrd_model.py

# 进阶参数：
# --num_spectra=50   控制每种晶相合成谱图的基础倍数
# --n_components=50  PCA主成分维数，默认50

3. generate_theoretical_spectra.py —— 生成理想对比波形（可选）

功能：对 References/ 中标准的 CIF 结构，计算其理论极限衍射离散峰位（火柴棍图），随即进行了一次极小限度的物理连续高斯展宽（FWHM=0.1°），并将其自动归一化存放至 Spectra/ 目录中。它的意义是作为推理过程中的 最完美基准对比集 (Control Group) 喂给模型，以评估模型的特征抓取能力（理论谱跑出来的置信度通常应该是极高的）。

运行方法：

python generate_theoretical_spectra.py

4. run_xrd_model.py —— 真实光谱推理

功能：使用上面训练好的 Model_ML.pkl 打包文件，去读取并推断 Spectra/ 目录中未经处理的真实扫描仪器原始光谱（.txt 或 .xy 等）。脚本会自动执行角度统一对齐网格线性插值，送入预训参数，推断具体的所属相和对应置信概率（%）。

运行方法：

# 默认推理，打印所有分类概率到终端
python run_xrd_model.py

# 附加存储功能：
# 1. 保存所有分类详情、分属于各个相别的独立概率分布到 CSV 文档
python run_xrd_model.py --save_csv=results.csv

# 2. 画出预测结果对比图并保存至 predictions/ 文件夹
python run_xrd_model.py --plot

5. plot_real_spectra.py —— 真实测量谱插值可视化

功能：数据测试验证脚本。逻辑等同于预测前的“预处理”部分，将 Spectra/ 中格式参差不齐的曲线强行经过 4501 点的等间距插值和幅度归一化，剥离并画出所有的验证波形，统一存放至 figure/real_data/ 进行审核。

运行方法：

python plot_real_spectra.py

6. plot_xrd_samples.py —— 理论及仿真生成谱评估

功能：专门用于对比和汇报出图。利用 pymatgen 内置的公式运算，画出当前模型中支持预测的各个材料由于数学性质决定的 理论最纯正棒状 XRD 图；同理，从引擎随机抽取各 3 条我们交由模型训练并学会的带噪图、包含漂移增宽的 仿真学习特征图。图表均落位到 figure/ 供取用。

运行方法：

python plot_xrd_samples.py