pymol

PyMOL

前提条件

1. uv：阅读 uv 技能，并按照其中的设置说明，确保已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/pymol_LICENSE.txt，则 (1) 显著提醒用户查看许可证：https://www.pymol.org/，然后 (2) 创建该文件，记录通知文本和时间戳。

概览

所有 PyMOL 命令都通过 uv 在主机上运行，并使用 OSMesa 软件渲染——不需要 GPU、显示器或 X server。运行 PyMOL 前，必须先将结构文件下载到主机上。

请勿在以下情况下使用：

• 用户想要运行 AlphaFold 预测。
• 用户想要进行对接或分子动力学模拟。
• 用户只有序列，没有结构文件——请先获取结构。继续操作前，检查是否有其他已安装的技能可以从 PDB 或 AlphaFold Database 获取结构。

设置（Agent 指示）

确保主机系统已安装 uv。PyMOL 脚本使用 PEP 0723 头部声明依赖项，执行脚本时，uv run 会自动处理依赖项的安装（包括 pymol-open-source-whl）。

核心规则

• 输出路径必须是绝对路径，或相对于用户的项目根目录。 始终从用户的项目目录运行 PyMOL 脚本。
• 仅使用软件渲染。 使用 cmd.png() 输出。切勿使用硬件加速调用 cmd.draw() 或 cmd.ray()——OSMesa 不支持硬件加速。设置环境变量 PYOPENGL_PLATFORM=osmesa 以进行无头渲染。
• 始终在任何 PNG 输出旁保存 .pse 会话文件。 这样用户就能在本地 PyMOL 中打开会话，进行进一步检查。
• 始终在每个 PyMOL 脚本末尾调用 cmd.quit()。 省略此调用会导致进程停止响应。
• 初始化样板代码为必需项。 每个 PyMOL 脚本都必须以初始化序列开头。from pymol import cmd 必须放在 finish_launching() 之后，而不是之前。
• 有关选择语法、常用命令和注意事项，请参阅 references/PYMOL_REFERENCE.md。
• 预检文件： 编写 PyMOL 脚本或运行脚本前，必须确认请求的结构文件确实存在于主机上。
• 验证结构加载： 使用 cmd.load() 加载结构后，始终通过检查 cmd.count_atoms("all") 来验证是否成功。如果结果为 0，则向 stdout 打印错误并立即调用 cmd.quit()。
• 自动检测 Alpha-Carbon Trace： 对于 cartoon 表示，PyMOL 脚本应自动检测结构是否为 alpha-carbon trace（cmd.count_atoms("name CA") == cmd.count_atoms("all")），然后必须遵循 Alpha carbon trace cartoon 配方。
• 通知： 如果使用此技能，请确保在输出中提及。

快速入门

• 确保结构文件已下载到用户项目中的某个目录。
• 编写 PyMOL Python 脚本（例如 render.py），其中包含必需的初始化样板代码和 PEP 0723 头部。
• 通过 uv run 运行：bash uv run render.py

最简示例脚本（render.py）

# /// script
# requires-python = ">=3.10, <3.13"
# dependencies = [
#     "pymol-open-source-whl",
# ]
# ///

import os
import sys

# Set environment variable for headless rendering
os.environ["PYOPENGL_PLATFORM"] = "osmesa"

import pymol # pytype: disable=import-error
pymol.pymol_argv = ["pymol", "-cq"]
pymol.finish_launching()

from pymol import cmd # pytype: disable=import-error

cmd.load("AF-P00520-F1-model_v4.cif", "structure")
cmd.show("cartoon")
cmd.color("green", "ss h")
cmd.color("yellow", "ss s")
cmd.color("gray", "ss l+''")
cmd.orient()
cmd.set("ray_opaque_background", 1)
cmd.png("output/render.png", width=1200, height=900, dpi=150)
cmd.save("output/session.pse")
cmd.quit()

常用方案

完整且可直接复制粘贴的方案请参阅 references/RECIPES.md。可用方案：

• 带二级结构着色的卡通表示 — 基本的螺旋／折叠／环区着色
• α 碳轨迹卡通表示 — 为仅含 CA 的结构强制使用卡通表示
• B 因子（pLDDT）着色 — 按 B 因子进行连续光谱着色
• AlphaFold pLDDT 着色 — 使用标准的基于阈值的置信度颜色
• 突出显示特定残基 — 将活性位点或关键残基显示为棒状
• 表面渲染 — 在卡通表示上叠加透明表面
• 静电表面渲染 — 真空静电效果（定性）
• 多链复合物着色 — 自动为每条链着色
• B 因子柔性分析 — 管状宽度与柔性成正比
• 空腔和口袋可视化 — 检测表面空腔并聚焦配体
• 多结构批量渲染 — 渲染结构目录
• 测量残基间距离 — 测量 CA–CA 距离并添加标签
• 放大结合口袋 — 简单的口袋聚焦
• 蛋白质-配体相互作用 — 分离配体、设置渲染样式并显示极性接触
• 两个结构的叠合与 RMSD — 使用 align/cealign 并自动回退
• 计算机辅助诱变 — 使用诱变向导突变残基
• 加载并修改现有会话 — 重新打开 .pse 文件

解读输出

• output/ 目录包含 PNG 图片和一个 .pse 会话文件。
• PyMOL 脚本会将任何测量结果或指标（距离、RMSD、原子数）打印到 stdout。请向用户报告这些值。
• 向用户展示 PNG 图片并描述可视化内容。
• 告知用户，他们可以在本地 PyMOL 中打开 .pse 文件，进一步探索、旋转或修改可视化内容。
• 如果用户需要修改，请在新脚本中加载已保存的 .pse 并重新运行。
• 包含表面的大型会话可能会超出 --max_output_mb 限制（默认值为 500 MB）。如有需要，可使用 --max_output_mb=1000 增大限制。