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