416 lines
12 KiB
Markdown
416 lines
12 KiB
Markdown
# 高通量筛选与扩胞项目 v2.3
|
||
|
||
## 环境配置需求
|
||
|
||
项目需要配置两个 Conda 环境，名称分别为 **screen** 和 **zeo**。
|
||
|
||
### 1. zeo 环境 (用于几何结构分析)
|
||
* **Python**: 2
|
||
* **核心库**: `zeo++` (需编译), `pymatgen==2018.12.12`, `numpy==1.16.6`
|
||
* **其他**: `os`, `argparse`, `PrettyTable`, `monty`, `future`
|
||
|
||
### 2. screen 环境 (用于逻辑筛选与数据处理)
|
||
* **Python**: 3.11.4
|
||
* **核心库**: `pymatgen==2024.11.13`, `pandas` (新增，用于处理CSV)
|
||
* **路径**: `/cluster/home/koko125/anaconda3/envs/screen`
|
||
|
||
## 快速开始
|
||
|
||
### 方式一：使用新版主程序（推荐）
|
||
|
||
```bash
|
||
# 激活 screen 环境
|
||
conda activate /cluster/home/koko125/anaconda3/envs/screen
|
||
|
||
# 运行主程序
|
||
python main.py
|
||
```
|
||
|
||
主程序提供交互式界面，支持：
|
||
- 数据库分析与筛选
|
||
- 本地多进程并行
|
||
- SLURM 直接提交（无需生成脚本文件）
|
||
- 实时进度条显示
|
||
- 扩胞处理与化合价添加
|
||
|
||
### 方式二：传统方式
|
||
|
||
1. **数据准备**:
|
||
* 如果数据来源为 **Materials Project (MP)**，请将 CIF 文件放入 `data/input_pre`。
|
||
* 如果数据来源为 **ICSD**，请直接将 CIF 文件放入 `data/input`。
|
||
2. **运行**:
|
||
* 确保已创建上述两个 Conda 环境。
|
||
* 在根目录下运行自动化脚本：
|
||
```bash
|
||
bash main.sh
|
||
```
|
||
|
||
## 新版功能特性 (v2.1)
|
||
|
||
### 执行模式
|
||
|
||
1. **本地多进程模式** (`local`)
|
||
- 使用 Python multiprocessing 在本地并行执行
|
||
- 适合小规模任务或测试
|
||
|
||
2. **SLURM 直接提交模式** (`slurm`)
|
||
- 直接在 Python 中提交 SLURM 作业
|
||
- 无需生成脚本文件
|
||
- 实时监控作业状态和进度
|
||
- 适合大规模高通量计算
|
||
|
||
### 进度显示
|
||
|
||
```
|
||
分析CIF文件: |████████████████████░░░░░░░░░░░░░░░░░░░░| 500/1000 (50.0%) [0:05:23<0:05:20, 1.6it/s] ✓480 ✗20
|
||
```
|
||
|
||
### 输出格式
|
||
|
||
处理后的文件支持两种输出格式：
|
||
|
||
1. **原始格式**（平铺）
|
||
```
|
||
workspace/processed/
|
||
├── 1514027.cif
|
||
├── 1514072.cif
|
||
└── ...
|
||
```
|
||
|
||
2. **分析格式**（按阴离子分类）
|
||
```
|
||
workspace/data/
|
||
├── O/
|
||
│ ├── 1514027/
|
||
│ │ └── 1514027.cif
|
||
│ └── 1514072/
|
||
│ └── 1514072.cif
|
||
├── S/
|
||
│ └── ...
|
||
└── Cl+O/
|
||
└── ...
|
||
```
|
||
|
||
## 处理流程详解
|
||
|
||
### Stage 1: 预处理与基础筛选 (Step 1)
|
||
* **Pre-process**: 清洗数据，统一放入 `input` 文件夹。
|
||
* **Step 1**:
|
||
* 读取 CIF 文件，利用 `crystal_2` 库检查电荷平衡与化学式。
|
||
* **文件重组**: 将通过筛选的文件按阴离子类型分类。
|
||
* **新结构**: 每个材料拥有独立的文件夹（例如 `after_step1/O/141/141.cif`），便于管理后续的计算日志。
|
||
* **Make SH**: 自动生成用于调用 Zeo++ 的 `analyze.sh` 脚本。
|
||
|
||
### Stage 2: Zeo++ 计算
|
||
* 切换至 `zeo` 环境。
|
||
* 计算材料的孔径 (Percolation diameter)、比表面积等几何参数。
|
||
* 结果输出为每个文件夹下的 **`log.txt`**。
|
||
|
||
### Stage 3: 数据提取与联合筛选 (Step 2-4)
|
||
* **数据提取 (`extract_data.py`)**:
|
||
* 自动遍历所有文件夹中的 `log.txt`。
|
||
* 提取关键参数：`Percolation Diameter` (Step 2), `Minimum of d` (Step 3), `Maximum Node Length` (Step 4)。
|
||
* 结果汇总为 CSV 文件保存在 `output/` 目录下（例如 `output/O/O.csv`）。
|
||
* **联合筛选 (`step2_4_combined.py`)**:
|
||
* 读取 CSV 文件，根据预设的阈值（如 O: Perc>0.5, Min_d<3.0, Node>2.2）进行过滤。
|
||
* **结果**: 将符合所有条件的材料，以**软链接**的形式汇聚到 `data/after_screening` 文件夹中。
|
||
|
||
---
|
||
|
||
## 扩胞逻辑 (Step 5)
|
||
|
||
扩胞处理已集成到新版主程序中，支持：
|
||
- 自动计算扩胞因子
|
||
- 可选保存数量（当为1时不加后缀）
|
||
- 自动添加化合价信息
|
||
|
||
### 算法分解
|
||
1. **读取结构**: 解析 CIF 文件。
|
||
2. **统计 Occupation**:
|
||
* 将具有相同 Occupation 值的原子归为一类。
|
||
* 生成 `Occupation_list` 字典。
|
||
3. **计算扩大倍数**:
|
||
* 根据 Occupation 的分子分母情况（如 0.5 对应 1/2），计算公约数。
|
||
4. **生成结构列表**:
|
||
* 根据分子与分母生成 `structure_list`。
|
||
5. **对称性处理与扩胞**:
|
||
* 根据材料结构的对称性，生成三个方向的扩胞列表 (如 `{"x":1, "y":2, "z":1}`)。
|
||
6. **生成新文件**:
|
||
* 结合 `structure_list` 与扩胞倍数生成最终的超胞 CIF。
|
||
|
||
### 假设条件
|
||
* 只考虑两个原子在同一位置上的共占位情况。
|
||
* 不考虑 Li 原子的共占位情况，对 Li 原子不做处理。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
screen/
|
||
├── main.py # 主入口（新版）
|
||
├── main.sh # 传统脚本入口
|
||
├── readme.md # 本文档
|
||
├── config/ # 配置文件
|
||
│ ├── settings.yaml
|
||
│ └── valence_states.yaml
|
||
├── src/ # 源代码
|
||
│ ├── analysis/ # 分析模块
|
||
│ │ ├── database_analyzer.py
|
||
│ │ ├── report_generator.py
|
||
│ │ ├── structure_inspector.py
|
||
│ │ └── worker.py
|
||
│ ├── core/ # 核心模块
|
||
│ │ ├── executor.py # 任务执行器（新）
|
||
│ │ ├── scheduler.py # 调度器
|
||
│ │ └── progress.py # 进度管理
|
||
│ ├── preprocessing/ # 预处理模块
|
||
│ │ ├── processor.py # 结构处理器
|
||
│ │ └── ...
|
||
│ └── utils/ # 工具函数
|
||
├── py/ # 传统脚本
|
||
├── tool/ # 工具和配置
|
||
│ ├── analyze_voronoi_nodes.py
|
||
│ └── Li/ # 化合价配置
|
||
└── workspace/ # 工作区
|
||
├── data/ # 分析格式输出
|
||
└── processed/ # 原始格式输出
|
||
```
|
||
|
||
## API 使用示例
|
||
|
||
### 使用执行器
|
||
|
||
```python
|
||
from src.core.executor import create_executor, TaskExecutor
|
||
|
||
# 创建执行器
|
||
executor = create_executor(
|
||
mode="slurm", # 或 "local"
|
||
max_workers=32,
|
||
conda_env="/cluster/home/koko125/anaconda3/envs/screen"
|
||
)
|
||
|
||
# 定义任务
|
||
tasks = [
|
||
(file_path, "Li", {"O", "S"})
|
||
for file_path in cif_files
|
||
]
|
||
|
||
# 执行
|
||
from src.analysis.worker import analyze_single_file
|
||
results = executor.run(tasks, analyze_single_file, desc="分析CIF文件")
|
||
```
|
||
|
||
### 使用数据库分析器
|
||
|
||
```python
|
||
from src.analysis.database_analyzer import DatabaseAnalyzer
|
||
|
||
analyzer = DatabaseAnalyzer(
|
||
database_path="/path/to/cif/files",
|
||
target_cation="Li",
|
||
target_anions={"O", "S", "Cl", "Br"},
|
||
anion_mode="all"
|
||
)
|
||
|
||
report = analyzer.analyze(show_progress=True)
|
||
report.save("analysis_report.json")
|
||
```
|
||
|
||
### 使用 Zeo++ 执行器
|
||
|
||
```python
|
||
from src.computation.workspace_manager import WorkspaceManager
|
||
from src.computation.zeo_executor import ZeoExecutor, ZeoConfig
|
||
|
||
# 设置工作区
|
||
ws_manager = WorkspaceManager(
|
||
workspace_path="workspace",
|
||
tool_dir="tool",
|
||
target_cation="Li"
|
||
)
|
||
|
||
# 创建软链接
|
||
workspace_info = ws_manager.setup_workspace()
|
||
|
||
# 获取计算任务
|
||
tasks = ws_manager.get_computation_tasks(workspace_info)
|
||
|
||
# 配置 Zeo++ 执行器
|
||
config = ZeoConfig(
|
||
conda_env="/cluster/home/koko125/anaconda3/envs/zeo",
|
||
partition="cpu",
|
||
max_concurrent=50,
|
||
time_limit="2:00:00"
|
||
)
|
||
|
||
# 执行计算
|
||
executor = ZeoExecutor(config)
|
||
results = executor.run_batch(tasks, output_dir="slurm_logs")
|
||
executor.print_results_summary(results)
|
||
```
|
||
|
||
## 新版功能特性 (v2.2)
|
||
|
||
### Zeo++ Voronoi 分析
|
||
|
||
新增 SLURM 作业数组支持，可高效调度大量 Zeo++ 计算任务：
|
||
|
||
1. **自动工作区管理**
|
||
- 检测现有工作区数据
|
||
- 自动创建配置文件软链接
|
||
- 按阴离子类型组织目录结构
|
||
|
||
2. **SLURM 作业数组**
|
||
- 使用 `--array` 参数批量提交任务
|
||
- 支持最大并发数限制（如 `%50`）
|
||
- 自动分批处理超大任务集
|
||
|
||
3. **实时进度监控**
|
||
- 通过状态文件跟踪任务完成情况
|
||
- 支持 Ctrl+C 中断监控（作业继续运行）
|
||
- 自动收集输出文件
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
Step 1: 数据库分析
|
||
↓
|
||
Step 1.5: 扩胞处理 + 化合价添加
|
||
↓
|
||
Step 2-4: Zeo++ Voronoi 分析
|
||
├── 创建软链接 (yaml 配置 + 计算脚本)
|
||
├── 提交 SLURM 作业数组
|
||
└── 监控进度并收集结果
|
||
↓
|
||
Step 5: 结果处理与筛选
|
||
├── 从 log.txt 提取关键参数
|
||
├── 汇总到 CSV 文件
|
||
├── 应用筛选条件
|
||
└── 复制通过筛选的结构到 passed/ 目录
|
||
```
|
||
|
||
### 筛选条件
|
||
|
||
Step 5 支持以下筛选条件：
|
||
- **最小渗透直径** (Percolation Diameter): 默认 1.0 Å
|
||
- **最小 d 值** (Minimum of d): 默认 2.0
|
||
- **最大节点长度** (Maximum Node Length): 默认不限制
|
||
|
||
### 日志输出
|
||
|
||
Zeo++ 计算的输出会重定向到每个结构目录下的 `log.txt` 文件：
|
||
```bash
|
||
python analyze_voronoi_nodes.py *.cif -i O.yaml > log.txt 2>&1
|
||
```
|
||
|
||
日志中包含的关键信息：
|
||
- `Percolation diameter (A): X.XX` - 渗透直径
|
||
- `the minium of d\nX.XX` - 最小 d 值
|
||
- `Maximum node length detected: X.XX A` - 最大节点长度
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
workspace/
|
||
├── data/ # 分析格式数据
|
||
│ ├── O/ # 氧化物
|
||
│ │ ├── O.yaml -> tool/Li/O.yaml
|
||
│ │ ├── analyze_voronoi_nodes.py -> tool/analyze_voronoi_nodes.py
|
||
│ │ ├── 1514027/
|
||
│ │ │ ├── 1514027.cif
|
||
│ │ │ ├── 1514027_all_accessed_node.cif # Zeo++ 输出
|
||
│ │ │ ├── 1514027_bond_valence_filtered.cif
|
||
│ │ │ └── 1514027_bv_info.csv
|
||
│ │ └── ...
|
||
│ ├── S/ # 硫化物
|
||
│ └── Cl+O/ # 复合阴离子
|
||
├── processed/ # 原始格式数据
|
||
├── slurm_logs/ # SLURM 日志
|
||
│ ├── tasks.json
|
||
│ ├── submit_array.sh
|
||
│ ├── task_0.out
|
||
│ ├── task_0.err
|
||
│ ├── status_0.txt
|
||
│ └── ...
|
||
└── zeo_results.json # 计算结果汇总
|
||
```
|
||
|
||
### 配置文件说明
|
||
|
||
`tool/Li/O.yaml` 示例：
|
||
```yaml
|
||
SPECIE: Li+
|
||
ANION: O
|
||
PERCO_R: 0.5
|
||
NEIGHBOR: 1.8
|
||
LONG: 2.2
|
||
```
|
||
|
||
参数说明：
|
||
- `SPECIE`: 目标扩散离子（带电荷）
|
||
- `ANION`: 阴离子类型
|
||
- `PERCO_R`: 渗透半径阈值
|
||
- `NEIGHBOR`: 邻近距离阈值
|
||
- `LONG`: 长节点判定阈值
|
||
|
||
## 新版功能特性 (v2.3)
|
||
|
||
### 断点续做功能
|
||
|
||
v2.3 新增智能断点续做功能，支持从任意步骤继续执行：
|
||
|
||
1. **自动状态检测**
|
||
- 启动时自动检测工作流程状态
|
||
- 检测 `workspace/data/` 是否存在且有结构 → 判断 Step 1 是否完成
|
||
- 检测结构目录下是否有 `log.txt` → 判断 Zeo++ 计算是否完成
|
||
- 如果 50% 以上结构有 log.txt，认为 Zeo++ 计算已完成
|
||
|
||
2. **智能流程跳转**
|
||
- 如果已完成 Zeo++ 计算 → 可直接进行筛选
|
||
- 如果已完成扩胞处理 → 可直接进行 Zeo++ 计算
|
||
- 从后往前检测，自动跳过已完成的步骤
|
||
|
||
3. **分步执行与中断**
|
||
- 每个大步骤完成后询问是否继续
|
||
- 支持中途退出，下次运行时自动检测进度
|
||
- 三大步骤：扩胞与加化合价 → Zeo++ 计算 → 筛选
|
||
|
||
### 工作流程状态示例
|
||
|
||
```
|
||
工作流程状态检测
|
||
|
||
检测到现有工作区数据:
|
||
- 结构总数: 1234
|
||
- 已完成 Zeo++ 计算: 1200 (97.2%)
|
||
- 未完成 Zeo++ 计算: 34
|
||
|
||
当前状态: Zeo++ 计算已完成
|
||
|
||
可选操作:
|
||
[1] 直接进行结果筛选 (Step 5)
|
||
[2] 重新运行 Zeo++ 计算 (Step 2-4)
|
||
[3] 从头开始 (Step 1)
|
||
[0] 退出
|
||
|
||
请选择 [1]:
|
||
```
|
||
|
||
### 使用场景
|
||
|
||
1. **首次运行**
|
||
- 从 Step 1 开始完整执行
|
||
- 每步完成后可选择继续或退出
|
||
|
||
2. **中断后继续**
|
||
- 自动检测已完成的步骤
|
||
- 提供从当前进度继续的选项
|
||
|
||
3. **重新筛选**
|
||
- 修改筛选条件后
|
||
- 可直接运行 Step 5 而无需重新计算
|
||
|
||
4. **部分重算**
|
||
- 如需重新计算部分结构
|
||
- 可选择重新运行 Zeo++ 计算
|