geometry-optimizer（几何优化器）

Geometry Optimizer

geometry-optimizer 是一个用于 分子三维几何结构优化 的化学类 skill。 它基于 GFN-xTB 半经验量子化学方法，对用户提供的分子初始结构进行快速、可落地的本地优化，输出优化后的坐标、能量、收敛状态等结果。

核心功能

• ✅ SMILES → 3D → 优化：自动从 SMILES 生成初始 3D 构象并进行 xTB 优化
• ✅ XYZ 文件输入：直接对已有 3D 坐标文件进行优化
• ✅ GFN2-xTB 方法：默认使用高精度的 GFN2-xTB 半经验方法
• ✅ 完整结果输出：优化后坐标、最终能量、梯度、收敛状态、日志文件
• ✅ 批量处理：支持 JSON 批量输入，多分子连续优化

适用场景

当用户有以下需求时，应调用本 skill：

不适用场景

以下情况不应调用本 skill：

输入格式

1. SMILES（推荐）

python scripts/main_script.py --smiles "CCO" --name "乙醇"

• 自动使用 RDKit 生成初始 3D 构象
• 自动推断电荷和未成对电子数
• 适用于只有二维分子表达式的场景

2. XYZ 文件

python scripts/main_script.py --input-xyz molecule.xyz --output-dir ./results

• 直接使用已有 3D 坐标
• 适合从实验结构或其他软件导出的坐标

3. 批量 JSON 输入

python scripts/main_script.py --input input.json --output output.json --output-dir ./results

input.json 格式：

[
  {"name": "乙醇", "smiles": "CCO"},
  {"name": "水", "smiles": "O"},
  {"name": "自定义", "input_xyz": "path/to/molecule.xyz"}
]

输出格式

JSON 结果

{
  "status": "completed",
  "backend_used": "xtb",
  "total": 1,
  "success": 1,
  "partial_success": 0,
  "error": 0,
  "results": [
    {
      "name": "乙醇",
      "input_type": "smiles",
      "smiles": "CCO",
      "canonical_smiles": "CCO",
      "status": "success",
      "backend_used": "xtb",
      "method": "gfn2",
      "charge": 0,
      "uhf": 0,
      "solvent": null,
      "converged": true,
      "energy_hartree": -11.394338789631,
      "energy_kcal_mol": -7150.050139542559,
      "final_gradient": 0.000195893782,
      "num_atoms": 9,
      "optimized_xyz_path": "./test_output/optimized.xyz",
      "log_path": "./test_output/xtbopt.log",
      "runtime_seconds": 0.26,
      "warnings": [],
      "message": "Geometry optimization completed. Converged."
    }
  ]
}

输出字段说明

XYZ 坐标文件

9
Optimized with xTB gfn2, energy=-11.394338789631 Ha
C -0.915405  0.082880  0.018580
C  0.513691 -0.435657 -0.103334
O  1.452768  0.397316  0.535701
H -1.015673  1.046445 -0.479628
...

命令行参数

python scripts/main_script.py \
  --smiles "CCO" \
  --name "乙醇" \
  --method gfn2 \
  --charge 0 \
  --uhf 0 \
  --solvent water \
  --max-cycles 200 \
  --output-dir ./results \
  --output ./results/result.json

方法选择

收敛标准

xTB 几何优化收敛标准：

• 梯度范数 < 0.001 Eh/a₀ (约 0.5 kcal/mol/Å)
• 达到收敛：status: "success", converged: true
• 未收敛但有结果：status: "partial_success", converged: false

安装指南

系统要求

• Python 3.8+
• xTB 6.3+（半经验量子化学程序）

1. 安装 Python 依赖

cd /home/administratorlulaiao/.openclaw/workspace/skills/geometry-optimizer
pip install -r requirements.txt

或直接安装：

pip install rdkit

2. 安装 xTB

xTB 是该 skill 的核心依赖，必须安装。以下是几种安装方式：

方式 A: Conda（推荐）

conda install -c conda-forge xtb

验证安装：

xtb --version

方式 B: Ubuntu/Debian

检查系统仓库：

apt-cache search xtb

如果仓库中没有，需要从源码编译或使用 Conda。

方式 C: 源码编译

# 安装依赖
sudo apt install cmake gfortran libblas-dev liblapack-dev

# 克隆源码
git clone https://github.com/grimme-lab/xtb.git
cd xtb

# 编译
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/.local
make -j4
make install

# 添加到 PATH
export PATH=$HOME/.local/bin:$PATH

详细编译说明：https://xtb-docs.readthedocs.io/en/latest/installation.html

3. 验证安装

运行测试脚本：

python scripts/test_xtb_backend.py

预期输出：

✓ xTB is available: xtb version X.X.X
✓ Full optimization tests can be run!

4. 可选：安装 CREST（构象搜索）

如需进行构象搜索，可安装 CREST：

# Conda
conda install -c conda-forge crest

# 或从源码：https://github.com/grimme-lab/crest

验证：

crest --version

系统依赖

必须安装

• xTB (6.x 版本)

# Ubuntu/Debian
sudo apt install xtb

# Conda
conda install -c conda-forge xtb

# 验证安装
xtb --version

Python 依赖

pip install rdkit

文件结构

geometry-optimizer/
├── SKILL.md                    # 本文件
├── README.md                   # 使用文档
├── INSTALL.md                  # 安装指南
├── requirements.txt            # Python 依赖
├── input.json                  # 批量输入示例
├── scripts/
│   ├── main_script.py          # 主入口脚本
│   ├── test_xtb_backend.py     # 测试脚本
│   ├── backends/
│   │   └── xtb_backend.py      # xTB 后端实现
│   └── utils/
│       ├── io_utils.py         # XYZ 读写工具
│       ├── smiles_utils.py     # SMILES→3D 生成
│       └── xtb_utils.py        # xTB 调用/解析工具
└── references/
    └── xtb_documentation.md    # xTB 命令参考

使用示例

示例 1: 单分子优化 (SMILES)

python scripts/main_script.py --smiles "CN1C=NC2=C1C(=O)N(C(=O)N2C)C" --name "咖啡因" --output-dir ./results

示例 2: 单分子优化 (XYZ 文件)

python scripts/main_script.py --input-xyz molecule.xyz --output-dir ./results

示例 3: 批量优化

python scripts/main_script.py --input input.json --output output.json --output-dir ./results

示例 4: 指定溶剂模型

python scripts/main_script.py --smiles "CCO" --solvent water --output-dir ./results

示例 5: 使用 GFN-FF 快速优化大分子

python scripts/main_script.py --smiles "大分子 SMILES" --method gfnff --max-cycles 500 --output-dir ./results

常见问题

xTB 未找到

xTB not available: xtb command not found

解决: 安装 xTB，参考上方"系统依赖"。

3D 构象生成失败

Failed to generate 3D structure

解决:

• 检查 SMILES 是否正确
• 尝试提供 XYZ 文件而非 SMILES

优化不收敛

status: "partial_success", converged: false

解决:

• 增加 --max-cycles (如 500)
• 尝试 --method gfnff 预优化，再用 gfn2 精修
• 检查初始结构是否合理

参考资料

• xTB 官方文档: https://xtb-docs.readthedocs.io
• GFN2-xTB 论文: https://doi.org/10.1021/acs.jctc.8b01176
• GFN1-xTB 论文: https://doi.org/10.1021/acs.jctc.7b00118
• GFN-FF 论文: https://doi.org/10.1002/anie.202004239
• RDKit 文档: https://www.rdkit.org/docs/

版本历史

待扩展功能

• CREST 构象搜索后端
• 约束几何优化
• 频率分析
• 溶剂化自由能计算
• 更多输入格式支持 (MOL, SDF, PDB)