高通量筛选与扩胞项目 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

快速开始

方式一：使用新版主程序（推荐）

# 激活 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 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 使用示例

使用执行器

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文件")

使用数据库分析器

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++ 执行器

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 文件：

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 示例：

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++ 计算