记录：在Ubuntu22.04上安装UppASD和Spirit的完整配置流程

1. Ubuntu 22.04 编译 UppASD 与 Spirit 前，先把依赖和坑位理清楚

自旋动力学模拟在磁学、自旋电子学方向用得越来越多，UppASD 和 Spirit 是两款绕不开的开源工具：前者主打原子尺度自旋动力学与蒙特卡洛，后者偏向有限差分/原子模型的微磁与自旋结构计算。它们都能在 Ubuntu 22.04 上从源码编译，但依赖链条长、编译器要求挑剔，新手很容易卡在 Intel oneAPI 环境、Qt 版本冲突、CMake 找不到 OpenGL 这几步。

这篇记录面向的是需要在本地工作站或实验室服务器上一次性部署这两款软件的人。我会把 apt 依赖清单、CMake 编译命令、测试算例验证步骤都写成可直接复制的形式，同时把 401、local proxy failed、reading choices 这类在配置 API 或远程调用时常见的报错也一并对照排查。如果你只是想在 Ubuntu 22.04 上把 UppASD 和 Spirit 跑起来，跟着下面的步骤走基本能一次过。

需要说明的是，UppASD 官方推荐 Intel 编译器（ifort/icx），而 Spirit 对 GCC 和 CMake 版本有明确下限。Ubuntu 22.04 自带的 GCC 11 和 CMake 3.22 对 Spirit 够用，但 UppASD 的 MakefileIfort 需要 oneAPI 的 Fortran 环境。所以整体思路是：先装系统级依赖，再装 oneAPI，然后分别编译两个软件，最后用官方算例验证。

我试过在一台 32 核、64G 内存的服务器上从零部署，整个过程大约 40 分钟，其中 oneAPI 下载和 Qt 安装占了大头。下面按顺序展开。

2. TaoToken 前置：把模型调用和编译排障的入口先备好

在编译过程中遇到报错时，除了查官方 issue，很多时候需要快速问一下模型来定位问题。TaoToken 在这里的作用是提供一个统一的模型调用入口，方便你在终端里直接对编译日志做语义分析。它的官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。

如果你打算在编译脚本里集成一个「报错自动解读」的小工具，可以先去 API Keys 页面生成一个 key：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。拿到 key 之后，在终端里用 curl 就能测试模型对话是否通：

export TAOTOKEN_API_KEY="你的key" curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role":"user","content":"make ifort 报错 undefined reference to `for_open‘ 怎么排查"}] }'

如果返回里出现choices字段且内容正常，说明 key 和网络都没问题。这一步不是编译的必需项，但后面排障会省很多时间。模型对话入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

对于长期做自旋动力学模拟、需要反复编译和跑算例的场景，可以考虑 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它更适合把模型调用嵌到日常脚本里，而不是每次手动贴日志。

需要提醒的是，TaoToken 只是模型调用入口，不替代编译器，也不参与 UppASD/Spirit 的实际计算。编译和运行仍然完全在本地完成。

3. 可复制配置：apt 依赖、oneAPI 环境与 CMake 编译命令

3.1 系统级 apt 依赖清单

先在 Ubuntu 22.04 上把基础工具链装齐。下面这条命令可以直接复制：

sudo apt update sudo apt install -y build-essential gcc g++ gfortran cmake git wget curl \ libopenmpi-dev openmpi-bin libomp-dev \ libblas-dev liblapack-dev libfftw3-dev \ libqt5charts5-dev qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools \ libvtk9-dev libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev \ python3-pip python3-venv python3-dev

这里有几个点要注意：libqt5charts5-dev是 Spirit 可视化需要的，libvtk9-dev是 UppASD 的 ASD_GUI 需要的，libopenmpi-dev用于并行编译。Ubuntu 22.04 的 Qt5 默认版本是 5.15，Spirit 对 Qt5 兼容性比 Qt6 好，所以这里优先装 Qt5。

3.2 安装 Intel oneAPI（UppASD 需要）

UppASD 的MakefileIfort依赖 Intel Fortran 编译器。去 Intel 官网下载 oneAPI Base Toolkit 和 HPC Toolkit 的离线安装包，放到/opt下：

cd /opt sudo sh ./intel-oneapi-base-toolkit-*.sh -a -s --eula accept sudo sh ./intel-oneapi-hpc-toolkit-*.sh -a -s --eula accept

安装完成后加载环境：

source /opt/intel/oneapi/setvars.sh

把这行加到~/.bashrc末尾，避免每次手动 source：

echo 'source /opt/intel/oneapi/setvars.sh' >> ~/.bashrc source ~/.bashrc

验证 ifort 是否可用：

ifort --version

如果输出里有ifort version 2024.x之类的信息，说明环境正常。

3.3 编译 UppASD

下载源码并编译：

cd ~ wget https://github.com/UppASD/UppASD/archive/refs/tags/v6.0.1.tar.gz tar xvzf v6.0.1.tar.gz cd UppASD-6.0.1 make -f MakefileIfort deps make -f MakefileIfort probe make -f MakefileIfort ifort make -f MakefileIfort asd-tests

如果make deps报错找不到libxc，可以手动装：

sudo apt install libxc-dev

编译完成后，source/sd就是主程序。运行算例前先source ~/.bashrc，然后进入某个例子目录：

cd examples/bccFe ../../../../source/sd

3.4 编译 Spirit

Spirit 用 CMake 构建，先克隆源码：

cd ~ git clone https://github.com/spirit-code/spirit.git cd spirit mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release -DSPIRIT_USE_QT=ON make -j$(nproc)

如果 CMake 报找不到 Qt5，检查CMAKE_PREFIX_PATH：

export CMAKE_PREFIX_PATH=/usr/lib/x86_64-linux-gnu/cmake/Qt5:$CMAKE_PREFIX_PATH

编译成功后，build/spirit就是可执行文件。可视化界面需要额外装spirit的 Python 包：

pip3 install spirit

3.5 一个可复用的 settings 片段

如果你用 Cline 或类似工具做远程编译，可以在settings.json里加一段：

{ "terminal.integrated.env.linux": { "TAOTOKEN_API_KEY": "你的key", "CMAKE_PREFIX_PATH": "/usr/lib/x86_64-linux-gnu/cmake/Qt5", "OMP_NUM_THREADS": "8" } }

这段配置的作用是让终端自动带上 oneAPI 和 Qt5 的路径，避免每次手动 export。

4. 验证请求与成功结果：跑通官方算例并确认输出

4.1 UppASD 算例验证

进入examples/bccFe，运行：

source ~/.bashrc ../../../../source/sd

正常输出会包含Initializing spin system、Running Monte Carlo之类的日志，最后生成output目录，里面有moment.dat、energy.dat等文件。用gnuplot或 Python 画一下磁矩随温度的变化：

python3 -c " import numpy as np import matplotlib.pyplot as plt data = np.loadtxt('output/moment.dat') plt.plot(data[:,0], data[:,1]) plt.xlabel('Temperature (K)') plt.ylabel('Moment (mu_B)') plt.savefig('moment.png') "

如果moment.png里能看到居里温度附近的下降趋势，说明 UppASD 编译和运行都正常。

4.2 Spirit 算例验证

Spirit 自带input示例，进入build目录后运行：

./spirit ../input/input.cfg

正常会输出能量收敛日志，并在当前目录生成output文件夹。用 Python 包做可视化：

python3 -c " from spirit import state, configuration with state.State('input/input.cfg') as p: configuration.print_info(p) "

如果能看到Number of spins和Energy信息，说明 Spirit 也通了。

4.3 用 TaoToken 做一次模型调用验证

在终端里跑一次模型对话，确认 API 可用：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role":"user","content":"UppASD 的 sd 程序输出 moment.dat 格式是什么"}] }' | python3 -m json.tool

返回里choices[0].message.content有内容，就说明模型调用链路正常。这一步和编译验证是独立的，但能帮你确认排障通道可用。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

5.1 401 Unauthorized

如果你在调用 TaoToken API 时看到：

{"error":{"message":"401 Unauthorized","type":"invalid_request_error"}}

先检查TAOTOKEN_API_KEY是否 export 成功：

echo $TAOTOKEN_API_KEY

如果为空，说明~/.bashrc没 source 或者变量名写错。重新 export 一次：

export TAOTOKEN_API_KEY="你的key"

然后重试 curl。如果还是 401，去 API Keys 页面确认 key 是否被禁用或过期。

5.2 local proxy failed

这个报错通常出现在终端里设置了http_proxy或https_proxy，但代理不可用：

env | grep -i proxy

如果有输出，先 unset：

unset http_proxy https_proxy all_proxy

然后重新跑 curl。注意，这里只是清理本地环境变量，不涉及任何网络工具配置。

5.3 reading choices 报错

如果你在解析 API 返回时看到：

KeyError: 'choices'

说明返回体不是标准的 chat completion 格式。先用python3 -m json.tool看原始返回：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"test"}]}' \ | python3 -m json.tool

如果返回里有error字段，按错误信息处理；如果有choices，说明是解析代码的问题，检查字段名是否拼错。

5.4 OAuth 相关报错

如果你用 Claude Code 或类似工具接入，看到：

OAuth token expired

需要重新走一遍授权流程。Claude Code 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有完整的 Base URL、Key、Model ID 三件套配置说明。Base URL 填https://taotoken.net/api，Key 填你的 API Key，Model ID 填claude-sonnet-4-20250514或你实际使用的模型。

5.5 编译类报错对照

make ifort报undefined reference to for_open：检查 oneAPI 环境是否 source，ifort --version是否有输出。

CMake 报Could NOT find Qt5：确认libqt5charts5-dev已装，并设置CMAKE_PREFIX_PATH。

Spirit 运行时报libQt5Charts.so.5: cannot open shared object file：执行sudo ldconfig刷新动态库缓存。

6. 语义一致 CTA：编译完成后继续用模型辅助排障

UppASD 和 Spirit 编译通过只是第一步，后面跑复杂算例、调参数、分析输出时还会遇到各种问题。这时候可以把报错日志直接贴给模型，让它帮你定位。模型对话入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，API Keys 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

如果你打算把自旋动力学模拟做成长期项目，Coding Plan 会更合适：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它适合把模型调用嵌到日常脚本和 CI 流程里，而不是每次手动复制粘贴。

最后提醒一句：编译 UppASD 时如果make asd-tests卡住，先检查OMP_NUM_THREADS是否设得太大，设成 4 或 8 再试。Spirit 的make -j$(nproc)在内存小于 16G 的机器上可能 OOM，改成make -j4更稳。