🔷 SplitPOSCAR Studio

POSCAR 差分电荷片段拆分器 · T/F 可视化 · 纯离线

把带 Selective dynamics T/F 标记的 POSCAR，一键拆成差分电荷计算所需的 A / AB / B 三个片段，并用 3D 视图预览每个片段。

结构有序，探索自由。

---

📌 它做什么

差分电荷（charge density difference）通常需要三份结构分别做单点计算，再取

Δρ = ρ(AB) − ρ(A) − ρ(B)

SplitPOSCAR Studio 负责其中最容易出错的一步——按 T/F 标记把 POSCAR 拆成三个片段：

<输出目录>/
├── A/POSCAR    全部为 F（F F F）的固定原子
├── B/POSCAR    其余带 T 标记的原子
└── AB/POSCAR   完整结构

拆分规则与 fast-vasp 的 split_poscar.py 完全一致， 界面布局参考 FixAtoms Studio。

✨ 功能亮点

能力	说明
📥 多格式解析	支持 VASP 4（无元素行）/ VASP 5、Direct / Cartesian、正负缩放系数
🎯 T/F 可视化	黑色网格球 = F F F 固定（A 片段）；橙色网格球 = 混合 T/F；无网格 = T 弛豫（B 片段）
🔎 片段预览	AB 全部 / A 固定 / B 弛豫 一键切换，3D 视图所见即导出内容
🖱️ 三种交互	旋转 / 点选切换 F↔T / 框选（Shift 反选），支持 1-8, 12 按编号批量设置
↩️ 撤销重做	T/F 修改最多 100 步可撤销
🔀 一键拆分	选择输出目录，自动生成 A/ B/ AB/ 三个文件夹的 POSCAR
🚫 严格模式	可选：只允许 F F F → A、T T T → B，混合标记直接报错
🧭 六个标准视图	前 / 后 / 左 / 右 / 上 / 下，按真实晶胞向量对齐
🎨 元素外观	内置周期表，可调颜色与球直径，偏好保存到 ball_settings.json
🖥️ 无界面模式	--export 直接命令行拆分，便于脚本批量调用
🚀 离线便携	Windows 便携版开箱即用，本地 3Dmol-min.js，运行无需联网

🖼️ 界面预览

• 左侧栏：当前结构信息、T/F 约束编辑、拆分预览、视图设置。
• 右侧 3D 舞台：旋转 / 点选 / 框选，六个标准视图，投影与深度雾化。
• 右上图例：实时显示 A / B 片段原子数与元素外观。

🚀 快速开始

方式一：便携版 EXE（推荐，无需环境）

前往 Releases 下载 SplitPOSCAR-Windows-x64-portable.zip，完整解压后双击 SplitPOSCAR.exe：

• 无需安装 Python、Conda、PySide6 或 ASE
• 目录内含运行依赖、本地 3Dmol.js、图标、示例文件与使用说明
• 分享 / 迁移请保留同目录的 _internal 文件夹，不能单独取出 EXE
• 外观偏好 ball_settings.json 写入 EXE 同目录
• 适用于 Windows 10 / 11 64 位，需要系统支持 QtWebEngine / WebGL

方式二：从源码运行

# 首次安装依赖（Python 3.11）
python -m pip install -r requirements.txt

# 打开文件
python app.py examples/POSCAR_diff

# 或显示内置 Fe-O 示例
python app.py --demo

也可双击 run.bat（支持把 POSCAR 拖入窗口打开）。

📖 使用流程

1. 打开 POSCAR：点击「打开 POSCAR…」或把文件拖入窗口。
2. 查看 T/F：黑色网格为固定原子，橙色网格为混合标记，无网格为弛豫原子。
3. 调整 T/F：
   • 点选模式点击原子在固定 / 弛豫之间切换；
   • 框选模式拖动固定范围内原子，Shift + 拖动 解除；
   • 或输入 1-8, 12, 16 后点「设为固定 F」/「设为弛豫 T」。
4. 预览片段：在「03 / 拆分预览 → 3D 预览片段」中选择 AB 全部 / A 固定 / B 弛豫，确认每个片段内容。
5. 拆分导出：点击「拆分导出 A / AB / B…」，选择输出根目录，得到三份 POSCAR。
6. 对三个结构分别做单点计算，取 AB − A − B 的电荷密度差即为差分电荷。

⌨️ 快捷键

快捷键	操作
Ctrl+O	打开 POSCAR
Ctrl+S	拆分导出
1 / 2 / 3	旋转 / 点选 / 框选
Esc	回到旋转模式
F11	全屏
Ctrl+Z / Ctrl+Shift+Z	撤销 / 重做

🖥️ 无界面拆分

python app.py --export D:\work\diff examples/POSCAR_diff
python app.py --export D:\work\diff --strict POSCAR

🧬 拆分规则

模式	规则
默认	A = 全部为 F 的固定原子，B = 其余带 T 标记的原子，AB = 全部原子
严格	只允许 F F F → A、T T T → B，混合标记（如 F T F）直接报错

• 三个片段的晶格、缩放系数、坐标系、原子顺序、坐标列保持原样；
• 片段 A / B 只保留实际含有的元素种类；
• 输入没有 Selective dynamics 行时，默认全部视为 T，可在界面标记后再导出。

📁 项目结构

split-POSCAR/
├── app.py                  # PySide6 窗口、拆分导出、片段预览、快捷键
├── poscar_io.py            # POSCAR 解析、T/F 掩码、A/AB/B 写出、3D 数据
├── ball_settings.py        # 周期表外观设置（含未知元素回退）
├── camera_views.py         # 六个标准视图旋转计算
├── viewer.html / viewer.js # 本地 3D 页面与渲染（含片段过滤）
├── 3Dmol-min.js            # 本地 3Dmol.js（离线渲染）
├── SplitPOSCAR.spec        # PyInstaller 打包配置
├── tools/build_icon.py     # SVG → ICO 图标生成
├── tools/build_portable.py # 便携目录 + ZIP 打包
├── assets/                 # 图标 SVG / ICO / PNG
├── examples/POSCAR_diff    # Fe-O 差分电荷示例（4 固定 + 6 弛豫）
├── PORTABLE_README.txt     # 便携版使用说明
└── tests/test_poscar_io.py # I/O 单元测试

📦 自行打包

python tools/build_icon.py          # 生成 assets/splitposcar.ico
python tools/build_portable.py      # 生成便携目录与 ZIP
# 输出：dist/SplitPOSCAR/SplitPOSCAR.exe
#       dist/SplitPOSCAR-Windows-x64-portable.zip

✅ 测试

python -m unittest discover -s tests -v

覆盖：VASP 4 / VASP 5 解析、Direct / Cartesian 与缩放、无 Selective dynamics 默认弛豫、A/B/AB 原子数、A 仅含 F、B 保留混合标记、严格模式报错、空片段写出、 晶格与缩放系数保留、3D 数据生成。

⚠️ 说明

• poscar_io.py 为纯 Python 解析（ASE 仅用于键长与范德华半径估计）， 因此不依赖 ASE 的 VASP 读取器，VASP 4 文件也能处理。
• 导出默认保留 B 片段中的混合 T/F 标记（与 fast-vasp 默认模式一致）； 若需要干净的 F F F / T T T，请使用严格模式或先统一标记。
• 文件读取与显示数据准备在后台线程完成；大规模结构（数万原子）渲染性能不做保证。
• 3Dmol-min.js 为第三方库，使用与再分发需遵守其上游许可。

📄 许可

本项目基于 MIT License 发布。

SplitPOSCAR Studio · 让差分电荷的结构准备变得简单直观

_{Built with Python · PySide6 · ASE · 3Dmol.js}