📚 课程目录第2章工具安装

工具安装：QMEAN与Verify3D的获取与安装

好，咱们直接进入正题。我习惯把工具安装当成做菜前的备料，料备不好，后面再好的手艺也白搭。QMEAN 和 Verify3D 的安装路径不太一样，一个偏命令行和库，一个偏独立程序。我这些年在这两个工具上踩过不少坑，把最稳妥的方式给你整理出来。

QMEAN 的安装方式

QMEAN 现在主要通过两个渠道获取：一个是 SWISS-MODEL 团队维护的独立命令行版本（也就是“正宗版”），另一个是通过第三方 Python 封装调用。我个人强烈推荐前者，原因你往下看。

方案一：从 PyPI 安装 QMEAN（最快）

说实话，这是我最常用的方式。SWISS-MODEL 官方已经把 QMEAN 打包成了 Python 包，直接 pip 就行了：

pip install qmean

你可能会问，就这么简单？嗯，是也不是。这个包其实是个“壳”，核心计算引擎是 C++ 写的，pip 安装的时候会自动把二进制文件拉下来。我在项目中遇到过一个问题——如果你的网络在墙内，可能会卡在下载依赖阶段。我当时的解决办法是手动指定镜像源：

pip install qmean -i https://pypi.tuna.tsinghua.edu.cn/simple

技巧：安装完之后跑一下 qmean --help，如果看到参数列表，说明安装成功。我习惯把这个命令加到每天早上的环境检查脚本里。

方案二：从 SWISS-MODEL 网站手动安装（更可控）

这个方案适合需要特定版本、或者想用最新开发版的朋友。步骤如下：

下载最新版源码包（.tar.gz 格式）。
解压后进入目录。
直接使用提供的编译脚本。

wget https://git.scicore.unibas.ch/schwede/QMEAN/releases/latest/download/qmean-1.3.0.tar.gz
tar -xzf qmean-1.3.0.tar.gz
cd qmean-1.3.0
./configure --prefix=/usr/local
make
make install

注意，编译过程需要高版本的 GCC（至少 8.0 以上）。我有个教训：有一次在 CentOS 7 上装，默认 GCC 4.8 编译到一半就报了一堆 C++17 错误。后来我用 devtoolset-8 才解决：

# 安装高版本 GCC（以 CentOS/RHEL 为例）
yum install centos-release-scl
yum install devtoolset-8-gcc devtoolset-8-gcc-c++
scl enable devtoolset-8 bash

这个折腾了我一个下午，你如果也用老系统，最好提前检查一下编译器版本。

Verify3D 的获取

Verify3D 的情况有点特殊。它不像 QMEAN 那样有统一的官方打包。最常用的来源是 UCLA-DOE 实验室的原始版本，还有后续一代代学者优化过的版本。我这里说两种主流方式。

方式一：从 SAVES 下载独立版本

SAVES（Structural Analysis and Verification Server）是 Verify3D 最早的发布渠道之一。你可以从他们的下载页面拿到独立的 C 源码包：

wget https://saves.mbi.ucla.edu/downloads/verify3d_2.0.tar.gz
tar -xzf verify3d_2.0.tar.gz
cd verify3d_2.0/src
make -f Makefile.gfortran

这里有段我自己的血泪史。这个源码用的是早年的 Fortran 77 风格，gfortran 现代版本的某些语法检测更严格。我第一次编译就报了一堆类似 Unterminated comment 的错。原因是源码里有些行尾的感叹号注释写法太随意了。

修复方法也不复杂：把 src/verify3d.f 文件中以下几类行修正：

! 原始（有问题）：
      IF (I .EQ. 1) GOTO 100   ! jump if equal
! 修正后：
      IF (I .EQ. 1) GOTO 100   ! jump if equal

说白了，就是有注释的行，代码前面也要留够空格，或者把注释单独放一行。我整理了 7 处这种问题才编译通过。你如果一次性报几十个错也别慌，绝大多数都是这类格式问题。

方式二：通过 python 封装调用（更符合现代工作流）

我猜多数人读这章是想把它集成到自动化流程里。那直接调 C 程序确实不太方便。所以我在项目里写了个简单的 Python 包装器，把 Verify3D 的本地可执行文件包起来：

import subprocess
import os

def run_verify3d(pdb_path, verify3d_bin):
    """调用本地 Verify3D 程序，返回每个残基的 3D-1D 得分"""
    cmd = [verify3d_bin, pdb_path]
    result = subprocess.run(cmd, capture_output=True, text=True)
    if result.returncode != 0:
        raise RuntimeError(f"Verify3D 运行失败：{result.stderr}")
    # 解析标准输出，提取残基得分
    scores = []
    for line in result.stdout.split('\n'):
        if line.startswith('RES') and len(line.split()) >= 4:
            scores.append(float(line.split()[3]))
    return scores

  注意：这个包装器的前提是先把 Verify3D 编译好，然后指定 verify3d_bin 路径。我一般把它放到 /usr/local/bin/verify3d，或者放到项目目录下，用相对路径调用。

安装验证与常见环境配置

工具装好了，怎么确认真的能跑？我写了个简单的集成测试脚本，每次配新环境时先跑一遍：

#!/bin/bash
# 安装验证脚本 - install_check.sh

echo "=== 检查 QMEAN ==="
qmean --version 2>/dev/null
if [ $? -ne 0 ]; then
    echo "  [FAIL] QMEAN 未正确安装"
else
    echo "  [OK] QMEAN 可用"
fi

echo "=== 检查 Verify3D ==="
verify3d 2>&1 | head -3
if [ $? -ne 0 ]; then
    echo "  [FAIL] Verify3D 未正确安装"
else
    echo "  [OK] Verify3D 可用"
fi

echo "=== 检查 Python 环境 ==="
python3 -c "import qmean; print('qmean 版本:', qmean.__version__)" 2>/dev/null
if [ $? -ne 0 ]; then
    echo "  [FAIL] Python qmean 包不可用"
else
    echo "  [OK] Python qmean 包正常"
fi

跑这个脚本如果全绿，基本上就没什么问题了。如果有任何一个步骤报红，别紧张，按下面的排查表来。

失败项	最常见原因	我的修复建议
qmean --version 报无命令	pip 安装未把可执行文件加入 PATH	检查 `pip show qmean` 的 Location，找到 `bin/qmean`，加软链到 PATH 目录
verify3d 编译报错	Fortran 编译器版本不对或缺失	安装 gfortran（`apt install gfortran` 或 `yum install gcc-gfortran`）
Python qmean 导入失败	系统 Python 与 pip 安装的 Python 版本不匹配	用 `python3 -m pip install qmean` 而不是直接 `pip`
缺少动态库（.so 文件）	QMEAN 编译时需要特定 BLAS/LAPACK 库	安装 OpenBLAS：`apt install libopenblas-dev`

警告：不要试图在 Windows 上直接编译 Verify3D 的 Fortran 源码。它的 Makefile 只兼容 Unix 系统调用。如果你必须在 Windows 下用，我建议启用 WSL 2 或者直接用 Docker 镜像。我曾经在 Cygwin 上强行编译跑通过一次，维护成本高得惊人。

工具安装全流程参考框架

说了这么多，我把整个安装决策过程画了张图，帮你一目了然地做选择：

这张图理清楚了你安装决策的两个分支。QMEAN 我推荐直接 pip；如果真的需要从源码编译，记得用 ./configure --prefix=/usr/local 而不是直接 make。Verify3D 那边，我建议先在 Ubutnu/Debian 环境下编译，兼容性最好。

最后整理一下环境变量

我个人习惯把工具安装完后统一加入 PATH，省得每次调用都要写全路径。在 ~/.bashrc 或 ~/.zshrc 里加几行：

# QMEAN 与 Verify3D 环境配置
export QMEAN_HOME=/path/to/qmean/installation
export VERIFY3D_HOME=/path/to/verify3d/installation
export PATH=$QMEAN_HOME/bin:$VERIFY3D_HOME/bin:$PATH

加完之后记得 source ~/.bashrc，再用前面那个验证脚本跑一遍。嗯，到这里两个工具就基本装好了。先别急着往下跑——确认环境没问题，后面建模验证步骤才不会有莫名其妙的错误。我当年就是没装对验证工具，花了一整天排查一个“模型质量低”的问题，最后发现是 Verify3D 路径指错了。这种坑，咱们绕过去就行。