max-soap

一个基于 SOAP + PCA + sequential gamma screening 的结构筛选项目。

输入是：

• 一个参考数据集，例如 train.xyz
• 若干个候选 .xyz/.extxyz 文件，运行时会自动合并成候选池

输出是：

• 输入参考集
• 新选中的候选结构
• 最终参考集
• 未被选中的候选结构
• 对应的 CSV 和 JSON 汇总

当前实现对应的流程伪代码见 ALGORITHM_PSEUDOCODE.md。

核心流程

1. 用输入参考集拟合 PCA 基底。
2. 对所有候选结构计算原子残差，每个结构取残差最高的前 10% 原子。
3. 把这些残差向量堆成矩阵 Z，按 SVD 的 99% 累计能量占比提取新增方向并扩一次基底。
4. 在固定新基底下，用参考集原子初始化 active set。
5. 候选结构按顺序计算 structure_gamma，并按 tau_low / tau_high 分成 selected_candidates、redundant_candidates 和 high_risk_candidates。

只有 selected_candidate 会更新 active set 并并入最终参考集；high_risk_candidate 会单独输出但不会更新 active set。 项目运行要求显式提供 reference_dataset_path，并且参考集至少包含 30 个结构。 input.paths 也必须解析到至少一个候选结构。

环境

• Python 3.12
• 当前项目默认使用仓库内的 .venv
• 项目使用标准 src/ 布局，建议先做 editable install

运行

安装当前项目：

UV_CACHE_DIR=$PWD/.uv-cache uv pip install --python .venv/bin/python -e .

在当前目录生成默认配置：

.venv/bin/max-soap init

如果需要写到自定义位置：

.venv/bin/max-soap init --path runs/my_screen_config.json

最小配置示例：

{
  "input": {
    "reference_dataset_path": "train.xyz",
    "paths": ["candidate_a.xyz", "candidate_b.extxyz"],
    "recursive": false
  }
}

运行：

.venv/bin/max-soap screen --config config.json

示例：

.venv/bin/max-soap screen --config config.example.json

主要输出

默认输出到 output.directory：

• merged.xyz
• reference_input.xyz
• selected_candidates.xyz
• reference_final.xyz
• redundant_candidates.xyz
• high_risk_candidates.xyz
• structure_scores.csv：按结构写出的 structure_residual_score 和 structure_gamma
• atom_scores.csv：按原子写出的 atom_gamma 和 atom_residual_fraction
• summary.json
• used_config.json

selected_candidates.xyz 会按结构编号均匀抽样，默认最多输出 100 个；如果新选中的候选不足 100 个，就全部输出。

summary.json 会记录：

• reference_input_count
• candidate_count
• new_selected_count
• selected_candidates_output_count
• final_reference_count
• redundant_candidate_count
• high_risk_candidate_count
• active_atom_count
• initial_dimensions
• current_dimensions
• added_dimensions
• expansion_triggered
• expansion_input_structure_count
• expansion_input_atom_count

测试

UV_CACHE_DIR=$PWD/.uv-cache uv pip install --python .venv/bin/python -e .
.venv/bin/python -m unittest discover -s tests -v