1. 为什么要在 Linux 上从源码编译 Quantum EspressoQuantum Espresso简称 QE是一套基于密度泛函理论、采用平面波基组和赝势方法的第一性原理计算程序。它和 VASP 一样使用平面波基组赝势库覆盖超软赝势和 PAW 赝势精度能满足大多数材料计算需求。更关键的是它开源世界各地的课题组持续往主仓库提交源码和后处理工具所以功能迭代很快。对于想做高精度量子化学或固体物理计算、又不想被商业授权卡住的研究者来说QE 是很实际的选择。那为什么不用 conda 或 apt 直接装非要自己编译我自己的体会是三点。第一Linux 发行版仓库里的 QE 版本往往偏旧很多新赝势和新功能对不上第二集群上的 MPI、MKL、编译器版本各不相同预编译包不一定匹配你的运行环境第三做计算的人迟早要改源码里的参数或加打印源码编译是绕不开的基本功。这篇就按“依赖安装 → configure 配置 → 编译安装 → 并行验证”的顺序把 QE 6.7 在 Linux 上的完整部署流程走一遍命令都可以直接复制。适合的读者是材料计算、凝聚态物理、量子化学方向的研究生和科研人员需要你对 Linux 命令行有基本操作能力知道cd、tar、export这些命令在干什么。如果你之前装过 oneAPI 或 GCC那这篇会更顺。整个流程大概需要 30 到 60 分钟主要时间花在编译上取决于机器核数。在开始之前先确认你的机器满足几个前提有 64 位 Linux 系统内存建议 8GB 以上编译阶段吃内存磁盘预留 20GB 以上空间因为 QE 源码解压后加上编译中间文件体积不小。编译器方面Intel oneAPI 的ifort/icc配合 MKL 数学库是官方推荐组合性能也最好如果没有 Intel 编译器用 GCC 的gfortran加 OpenBLAS 也能跑只是数学库性能会有差异。下面以 Intel oneAPI 为主线GCC 方案在配置章节给出对照。另外提一句工具链管理的事。做第一性原理计算的人电脑上往往不止 QE 一个工具可能还有 VASP 后处理脚本、Python 分析环境、各种 API 调用脚本。这些工具如果各自维护一套 Key 和接口配置时间久了很容易乱。我现在的做法是用 TaoToken 这类统一通道来管理模型调用和 API Key把配置集中在一处换机器或换项目时不用到处翻。这个和 QE 编译本身是两件事但属于同一个“科研环境可复现”的思路后面配置章节会顺带说怎么把相关调用统一起来。2. 编译前的依赖准备与 oneAPI 环境加载QE 编译依赖几个东西Fortran 编译器、C 编译器、MPI 实现、数学库BLAS/LAPACK/ScaLAPACK/FFT。用 Intel oneAPI 的话这些基本都打包在里面了。如果你还没装 oneAPI先去官网下载intel-oneapi-toolkit的离线安装包或在线安装器安装时至少勾选这几个组件intel-oneapi-compiler-fortran、intel-oneapi-compiler-dpcpp-cpp、intel-oneapi-mkl、intel-oneapi-mpi。装完之后每次编译前要先加载环境source /opt/intel/oneapi/setvars.sh如果你把 oneAPI 装在别的路径把/opt/intel/oneapi换成你的实际路径。加载成功后which ifort应该能输出编译器路径which mpiifort也应该有结果。这一步很关键很多人编译报错就是因为忘了 source导致 configure 找不到编译器。除了 oneAPI还需要一些系统级工具用包管理器装一下。以 Ubuntu/Debian 为例sudo apt update sudo apt install -y build-essential wget tar gzip gfortran libopenblas-dev liblapack-dev libfftw3-devCentOS/RHEL 系用sudo yum groupinstall -y Development Tools sudo yum install -y wget tar gzip gcc-gfortran openblas-devel lapack-devel fftw-devel这里装的gfortran和 OpenBLAS 是备用方案如果你确定全程用 Intel 编译器这些不是必须的但装上没坏处万一 Intel 环境出问题可以切换。wget和tar用来下载解压源码。接下来下载 QE 源码。官方仓库在 GitHub 的 QEF/q-e本教程用 6.7 版本其他版本流程基本一致。下载和解压wget https://github.com/QEF/q-e/archive/refs/tags/qe-6.7.tar.gz tar -xvf qe-6.7.tar.gz cd q-e-qe-6.7注意 GitHub 的 tag 压缩包解压后目录名是q-e-qe-6.7如果你从别的地方下载的qe-6.7.tgz解压后可能是qe-6.7以实际为准。进目录后先看一眼有没有configure文件有就说明源码完整。在编译之前建议先规划好安装路径。我习惯把 QE 装到/opt/QE/6.7这种带版本号的目录方便以后多版本共存。先建好目录sudo mkdir -p /opt/QE/6.7 sudo chown -R $USER:$USER /opt/QE把/opt/QE的属主改成你自己避免后面make install时权限不够。如果你没有 sudo 权限就装到自己的家目录比如$HOME/software/QE/6.7后面所有路径相应替换。依赖这块还有一个容易忽略的点devicexlib。QE 6.7 在编译时可能会去找external/devxlib目录下的 device 相关库如果源码包里没带全会报找不到devicexlib相关文件的错误。这个后面排障章节会专门讲怎么补。3. configure 编译参数配置与 make.inc 关键项依赖齐了就可以 configure。QE 的 configure 脚本会探测编译器、MPI 和数学库然后生成make.inc文件这个文件决定了后面 make 用什么编译器、链接什么库。先给出一条完整的 configure 命令用 Intel 编译器加 MKL./configure --prefix/opt/QE/6.7 \ --with-scalapackintel \ --enable-parallel \ --enable-openmp \ CCicc FCifort F77ifort \ MPICCmpiicc MPIF90mpiifort逐项解释一下。--prefix是安装路径编译完make install会把可执行文件放到$prefix/bin。--with-scalapackintel让 configure 自动去 MKL 里找 ScaLAPACK不用手动指定库路径这是最省事的做法。--enable-parallel开启 MPI 并行做集群计算必须开。--enable-openmp开启 OpenMP 线程并行配合 MPI 可以做混合并行。CC、FC、F77指定 C 和 Fortran 编译器MPICC、MPIF90指定 MPI 包装编译器。如果你用 GCC 而不是 Intelconfigure 改成这样./configure --prefix$HOME/software/QE/6.7 \ --enable-parallel \ --enable-openmp \ CCgcc FCgfortran F77gfortran \ MPICCmpicc MPIF90mpif90 \ BLAS_LIBS-lopenblas \ LAPACK_LIBS-lopenblas \ SCALAPACK_LIBS-lscalapack-openmpiGCC 方案下 ScaLAPACK 需要单独装Ubuntu 上是libscalapack-openmpi-devCentOS 上是scalapack-openmpi-devel。如果找不到可以先用--without-scalapack跳过但那样并行性能会打折。configure 跑完会生成make.inc这个文件值得打开看一眼确认几个关键项对不对。用编辑器打开vi make.inc重点检查这几行。MPIF90应该是mpiifortIntel或mpif90GCC。BLAS_LIBS和SCALAPACK_LIBS要指向正确的数学库。Intel 方案下通常长这样BLAS_LIBS -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core SCALAPACK_LIBS -lmkl_scalapack_lp64 -lmkl_blacs_intelmpi_lp64PREFIX要和你 configure 时的--prefix一致。IFLAGS里应该包含 MKL 的 include 路径比如-I/opt/intel/oneapi/mkl/latest/include。如果这些项不对手动改过来再 make比重新 configure 快。这里插一个和工具链管理相关的配置。做计算的人经常要在脚本里调用各种 API比如用 Python 脚本批量提交任务、调用模型接口做数据分析。如果每个脚本都硬编码 Key换环境时很麻烦。我现在的做法是把这类调用统一走 TaoToken 的 API 通道Base URL 固定Key 集中管理。在 shell 里可以这样设环境变量export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEY你的Key然后在 Python 脚本里读这两个变量去请求。这样 QE 的计算流程和外围的 API 调用就解耦了配置只维护一份。具体 Key 在 TaoToken 控制台的 API Keys 页面生成接入文档里有各语言的调用示例需要的话可以对照着配。configure 和 make.inc 确认无误后就可以开始编译了。4. 编译安装与 pw.x 并行算例验证编译分两步先make all再make install。如果你的机器核多可以加-j参数并行编译比如 8 核make -j8 all编译过程会持续十几分钟到半小时取决于机器性能。中途如果报错先看错误信息里是哪个文件、哪个编译器报的大部分是库路径问题。编译完成后安装make install安装完检查$prefix/bin目录应该能看到一堆可执行文件核心的有pw.x、cp.x、pp.x、dos.x、bands.x等。用ls /opt/QE/6.7/bin确认一下pw.x在就说明主程序编译成功了。接下来把 QE 的可执行文件路径加到环境变量方便直接调用。编辑~/.bashrcecho export PATH/opt/QE/6.7/bin:$PATH ~/.bashrc source ~/.bashrc然后which pw.x应该能输出路径。如果输出为空检查路径拼写和source是否执行。现在做并行验证。QE 自带test-suite和examples但最直接的验证是跑一个小的 pw.x 算例。我准备一个最简单的硅晶体 SCF 计算输入文件保存为si.scf.inCONTROL calculation scf prefix si outdir ./tmp pseudo_dir ./pseudo / SYSTEM ibrav 2 celldm(1) 10.2 nat 2 ntyp 1 ecutwfc 20.0 / ELECTRONS conv_thr 1.0d-6 / ATOMIC_SPECIES Si 28.086 Si.pbe-n-rrkjus_psl.1.0.0.UPF ATOMIC_POSITIONS alat Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 K_POINTS automatic 4 4 4 0 0 0这个算例需要硅的赝势文件Si.pbe-n-rrkjus_psl.1.0.0.UPF从赝势库下载后放到./pseudo目录。赝势库在 QE 官网和各大计算社区都有选 PBE 泛函的超软赝势即可。建好目录mkdir -p tmp pseudo把赝势文件放进pseudo然后运行。先用单核验证程序能跑通pw.x -in si.scf.in si.scf.out跑完看输出文件末尾如果出现JOB DONE和总能量说明单核没问题。然后测并行用 4 个 MPI 进程mpirun -np 4 pw.x -in si.scf.in si.scf.4.out如果机器有超线程或你想测混合并行可以加 OpenMP 线程export OMP_NUM_THREADS2 mpirun -np 4 pw.x -in si.scf.in si.scf.omp.out跑完对比几个输出文件的总能量应该基本一致数值误差在小数点后几位内。同时看运行时间并行版本应该比单核快。如果mpirun报错说找不到pw.x用绝对路径/opt/QE/6.7/bin/pw.x试试或者检查 MPI 环境是否加载。验证通过后你的 QE 就部署完成了。可以把这个算例的输入输出留作以后环境迁移时的回归测试换机器后跑一遍确认编译没问题。5. 编译与运行常见报错排查这一节列几个我实际踩过的坑对照报错信息找解决方案。第一个常见报错是 configure 阶段找不到编译器提示configure: error: Fortran compiler cannot create executables。原因基本是没 source oneAPI 环境或者FC指定的编译器不在 PATH 里。解决方法是先source /opt/intel/oneapi/setvars.sh再which ifort确认能找到然后重新 configure。如果用的是 GCC确认gfortran装了gfortran --version有输出。第二个是编译时报devicexlib相关文件找不到类似Cannot find file devicexlib.f90或No rule to make target .../devxlib/...。这是 QE 6.7 的一个已知问题源码包里external/devxlib可能不完整。解决方法是手动下载 devicexlib 补进去wget https://gitlab.com/max-centre/components/devicexlib/-/archive/0.1.0/devicexlib-0.1.0.tar.gz tar -zxvf devicexlib-0.1.0.tar.gz mv devicexlib-0.1.0/* q-e-qe-6.7/external/devxlib/注意目标目录是external/devxlib把解压出来的文件拷进去然后重新make all。第三个是链接阶段报undefined reference to mkl_...或cannot find -lmkl_scalapack_lp64。这是make.inc里数学库路径不对。打开make.inc确认BLAS_LIBS、SCALAPACK_LIBS指向的库在系统里存在。用find /opt/intel -name libmkl_scalapack_lp64*找一下实际路径把make.inc里的路径改对。如果 MKL 版本和 oneAPI 版本不匹配也可能出这个问题确认source的是同一个 oneAPI 环境。第四个是运行阶段mpirun报local proxy failed或OAuth相关错误。这类错误通常和 MPI 的进程启动机制有关不是 QE 本身的问题。先检查mpirun --version是否正常再确认mpiifort和mpirun来自同一个 MPI 实现都是 Intel MPI 或都是 OpenMPI。混用不同 MPI 实现会导致进程间通信失败。如果报reading choices之类的输入解析错误检查输入文件里CONTROL、SYSTEM这些 namelist 的拼写和斜杠结尾QE 对输入格式比较敏感。第五个是运行时报401或权限错误。QE 本身不涉及网络认证如果你在脚本里调用了外部 API 做数据处理那 401 是 API Key 的问题。检查环境变量TAOTOKEN_API_KEY是否设置正确Key 有没有过期。在 TaoToken 控制台重新生成一个 Key 替换即可。这类外围调用和 QE 主程序是分开的排障时先确认 QE 本身能跑通再查 API 部分。第六个是内存不足导致编译中断报virtual memory exhausted或Killed。QE 编译某些大文件时吃内存如果机器内存小减少make -j的并行数比如从-j8降到-j2或者单线程make all。运行阶段如果内存不够减小ecutwfc或K_POINTS密度。排查的基本思路是先看报错发生在哪个阶段configure、make、运行再看报错信息里的文件名和库名然后确认对应的环境变量和路径。大部分问题都是环境没加载对或路径写错。6. 统一 Key 与 API 通道管理计算工具调用QE 部署完之后实际科研流程里往往还要接一堆外围工具用 Python 脚本批量生成输入文件、调用模型接口做结果分析、把计算数据整理成报告。这些调用如果各自维护 Key 和接口地址时间一长就容易乱换机器或换项目时更是要重新配一遍。我现在的做法是把这类调用统一走一个 API 通道Base URL 和 Key 集中管理脚本里只读环境变量。具体配置上在~/.bashrc里加两行export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEY你的KeyKey 在 TaoToken 控制台的 API Keys 页面生成接入文档里有 Python、curl 等调用示例。这样你的 QE 计算脚本里如果需要调用模型做数据分析直接读这两个变量就行不用在代码里硬编码。比如一个简单的 Python 调用import os import requests base_url os.environ[TAOTOKEN_BASE_URL] api_key os.environ[TAOTOKEN_API_KEY] headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { model: claude-3-5-sonnet, messages: [{role: user, content: 帮我分析这个QE输出文件的总能量趋势}] } resp requests.post(f{base_url}/v1/messages, headersheaders, jsonpayload) print(resp.json())这样配置的好处是QE 的计算环境和外围的 API 调用解耦了。你换一台机器只要把环境变量设好脚本不用改。如果团队里多人协作Key 集中管理也方便控制权限和用量。对于长期做编码和 Agent 类任务的场景TaoToken 有 Coding Plan 可以看适合需要持续调用模型做代码生成或自动化流程的情况。如果只是偶尔验证模型效果用模型对话页面直接测就行。接入文档里有各语言的完整示例配置时对照着看能少走弯路。回到 QE 本身部署完成后建议把编译参数、make.inc关键项、验证算例的输入输出都存档下次换机器或升级版本时可以直接复用。科研环境可复现靠的就是这些细节记录。