一阶段高筛制作完成

2025-12-16 11:36:49 +08:00
parent 6ea96c81d6
commit f78298e803
22 changed files with 3276 additions and 223 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,4 +1,4 @@
-# 高通量筛选与扩胞项目
+# 高通量筛选与扩胞项目 v2.3

 ## 环境配置需求

@@ -12,9 +12,29 @@
 ### 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`。
@@ -25,6 +45,52 @@
        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)
@@ -51,9 +117,12 @@

 ---

-## 扩胞逻辑 (Step 5 - 待后续执行)
+## 扩胞逻辑 (Step 5)

-目前扩胞逻辑维持原状，基于筛选后的结构进行处理。
+扩胞处理已集成到新版主程序中，支持：
+- 自动计算扩胞因子
+- 可选保存数量（当为1时不加后缀）
+- 自动添加化合价信息

 ### 算法分解
 1.  **读取结构**: 解析 CIF 文件。
@@ -71,4 +140,276 @@

 ### 假设条件
 *   只考虑两个原子在同一位置上的共占位情况。
-*   不考虑 Li 原子的共占位情况，对 Li 原子不做处理。
+*   不考虑 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++ 计算