Python aiida-sssp 完全指南及实战案例

摘要：本文系统介绍 AiiDA 生态中的aiida-sssp插件，涵盖其功能定位、安装配置、命令行与 Python API 语法、核心参数含义，并通过 16 个由浅入深的实际应用案例演示如何用 SSSP 赝势库驱动 AiiDA 计算流程，最后总结常见错误与使用注意事项。

一、aiida-sssp 是什么

aiida-sssp是 AiiDA 官方生态中的插件包，用于把SSSP（Standard Solid-State Pseudopotentials）赝势库接入 AiiDA 的数据管理流程。SSSP 由 Materials Cloud 团队维护，针对不同计算精度（efficiency / precision）为每种元素推荐一套经过收敛性验证的赝势，是当前固态材料高通量计算中最常用的赝势标准之一。

简单来说，aiida-sssp解决的是这样一个问题：在 AiiDA 中做高通量计算时，如何自动、可复现、可追溯地为每个元素选择正确的赝势文件，并把它注册为 AiiDA 的UpfData节点。

1.1 核心功能

• 赝势自动下载与注册：根据元素符号和 SSSP 版本，自动获取对应的 UPF 文件并导入 AiiDA 数据库。
• 版本化管理：支持 SSSP 1.1.0、1.2.0、1.3.0 等多个版本，不同版本对应不同的推荐赝势集合。
• 精度档位选择：支持efficiency与precision两种精度标准，前者追求速度，后者追求精度。
• 与计算插件联动：可直接为aiida-quantumespresso的PwBaseWorkChain提供pseudo_family或伪势字典。
• 可追溯性：每个赝势文件在 AiiDA 中都是一个带 UUID 的节点，计算谱系完整可查。

1.2 与相关包的关系

需要特别说明：在较新的版本中，SSSP 的功能已经部分合并进aiida-pseudo，通过aiida-pseudo install sssp命令即可安装。但独立的aiida-sssp包在旧项目和特定工作流中仍然广泛使用，理解它的用法对维护历史项目很有价值。

二、安装与环境配置

2.1 前置条件

• Python 3.8 及以上版本
• 已安装并初始化aiida-core（verdi status显示正常）
• 已配置好 Quantum ESPRESSO 代码（如需实际运行计算）
• 可访问外网（首次安装需下载赝势文件）

2.2 安装步骤

# 建议在独立虚拟环境中安装 python -m venv aiida-env source aiida-env/bin/activate 安装 aiida-core pip install aiida-core 安装 aiida-sssp pip install aiida-sssp 安装 Quantum ESPRESSO 插件（可选，用于实际计算） pip install aiida-quantumespresso 验证安装 verdi plugin list aiida.data | grep -i sssp

2.3 初始化 AiiDA 配置

# 创建 AiiDA 配置 verdi quicksetup --profile sssp-demo 检查状态 verdi status

如果verdi status输出中 profile、storage、daemon 均为绿色，说明环境就绪。

2.4 安装 SSSP 赝势族

# 安装 efficiency 精度的 SSSP 1.3.0 aiida-pseudo install sssp -v 1.3 -p efficiency 安装 precision 精度 aiida-pseudo install sssp -v 1.3 -p precision 查看已安装的赝势族 aiida-pseudo list

安装完成后会得到一个形如SSSP/1.3/PBE/efficiency的赝势族标签，后续在计算中直接引用该标签即可。

三、语法与核心参数

3.1 命令行语法

aiida-pseudo install sssp [OPTIONS] 选项： -v, --version TEXT SSSP 版本号，如 1.1、1.2、1.3 -p, --functional TEXT 泛函类型，PBE 或 PBEsol -p, --protocol TEXT 精度档位，efficiency 或 precision -d, --download-only 仅下载不安装 --label TEXT 自定义赝势族标签 -h, --help 显示帮助

3.2 Python API 语法

from aiida import orm, load_profile from aiida_pseudo.groups.family import SsspFamily load_profile() 通过标签加载赝势族 family = orm.load_group('SSSP/1.3/PBE/efficiency') 获取某个元素的赝势 pseudo = family.get_pseudo('Si') 获取多个元素的赝势字典 pseudos = family.get_pseudos(elements=['Si', 'O']) 获取族内所有元素 elements = family.elements print(f"共 {len(elements)} 个元素")

3.3 核心参数详解

注意：functional必须与pw.x输入中的input_dft一致，否则计算结果不可信。

四、16 个实际应用案例

案例 1：安装并列出 SSSP 赝势族

aiida-pseudo install sssp -v 1.3 -p efficiency aiida-pseudo list

输出会列出所有已安装的赝势族，确认SSSP/1.3/PBE/efficiency存在即安装成功。

案例 2：查询某元素的赝势信息

from aiida import orm, load_profile load_profile() family = orm.load_group('SSSP/1.3/PBE/efficiency') pseudo = family.get_pseudo('Si') print(pseudo.filename) print(pseudo.pk, pseudo.uuid)

用于确认某个元素在库中对应的具体 UPF 文件名和节点标识。

案例 3：为多元素体系构建赝势字典

from aiida import orm, load_profile load_profile() family = orm.load_group('SSSP/1.3/PBE/efficiency') pseudos = family.get_pseudos(elements=['Ba', 'Ti', 'O']) for symbol, node in pseudos.items(): print(symbol, node.filename)

这是构建PwBaseWorkChain输入时最常用的操作。

案例 4：在 PwBaseWorkChain 中使用 SSSP

from aiida import orm, load_profile from aiida.engine import submit from aiida_quantumespresso.workflows.pw.base import PwBaseWorkChain load_profile() family = orm.load_group('SSSP/1.3/PBE/efficiency') pseudos = family.get_pseudos(elements=['Si']) builder = PwBaseWorkChain.get_builder_from_protocol( code=orm.load_code('qe-7.2@localhost'), structure=orm.load_node(STRUCTURE_PK), protocol='fast', ) builder.pw.pseudos = pseudos workchain = submit(builder) print(workchain.pk)

把 SSSP 赝势直接注入工作流，是最典型的集成方式。

案例 5：对比 efficiency 与 precision 的赝势差异

from aiida import orm, load_profile load_profile() eff = orm.load_group('SSSP/1.3/PBE/efficiency') pre = orm.load_group('SSSP/1.3/PBE/precision') for el in ['Si', 'O']: print(el, eff.get_pseudo(el).filename, pre.get_pseudo(el).filename)

可直观看到两种精度档位下同一元素使用的赝势文件可能不同。

案例 6：批量检查结构所需赝势是否齐全

from aiida import orm, load_profile load_profile() family = orm.load_group('SSSP/1.3/PBE/efficiency') structure = orm.load_node(STRUCTURE_PK) needed = set(structure.get_symbols_set()) available = set(family.elements) missing = needed - available print('缺失元素:', missing if missing else '无')

在提交大批量计算前做一次预检，可避免中途失败。

案例 7：导出赝势族清单为表格

from aiida import orm, load_profile load_profile() family = orm.load_group('SSSP/1.3/PBE/efficiency') for el in sorted(family.elements): p = family.get_pseudo(el) print(f"{el}\t{p.filename}")

输出可直接重定向到文件，作为项目赝势清单存档。

案例 8：自定义标签安装多个版本

aiida-pseudo install sssp -v 1.2 -p efficiency --label SSSP-1.2-eff aiida-pseudo install sssp -v 1.3 -p efficiency --label SSSP-1.3-eff aiida-pseudo list

便于在同一数据库中并存多个版本，做版本对比研究。

案例 9：在 AiiDA 工作图中追溯赝势来源

from aiida import orm, load_profile load_profile() calc = orm.load_node(CALC_PK) for label, pseudo in calc.inputs.pseudos.items(): print(label, pseudo.uuid, pseudo.filename)

通过计算节点的输入反查赝势，保证结果可复现。

案例 10：为高通量筛选批量准备赝势

from aiida import orm, load_profile load_profile() family = orm.load_group('SSSP/1.3/PBE/efficiency') structures = orm.QueryBuilder().append( orm.StructureData, tag='s' ).all(flat=True) for s in structures: try: pseudos = family.get_pseudos(elements=s.get_symbols_set()) except ValueError as e: print(f"结构 {s.pk} 缺赝势: {e}")

批量场景下必须做异常捕获，否则单个结构缺元素会中断整个循环。

案例 11：结合 aiida-quantumespresso 的协议构建器

from aiida import orm, load_profile from aiida_quantumespresso.workflows.pw.base import PwBaseWorkChain load_profile() family = orm.load_group('SSSP/1.3/PBE/efficiency') builder = PwBaseWorkChain.get_builder_from_protocol( code=orm.load_code('qe-7.2@localhost'), structure=orm.load_node(STRUCTURE_PK), protocol='moderate', overrides={'pw': {'parameters': {'SYSTEM': {'ecutwfc': 60}}}}, ) builder.pw.pseudos = family.get_pseudos( elements=builder.pw.structure.get_symbols_set() )

协议构建器 + SSSP 是当前推荐的组合方式。

案例 12：检查赝势族与泛函是否匹配

from aiida import orm, load_profile load_profile() family = orm.load_group('SSSP/1.3/PBE/efficiency') print('族泛函:', family.functional) print('族版本:', family.version) print('族精度:', family.protocol)

提交计算前核对泛函，避免 PBE 赝势配 PBEsol 输入的低级错误。

案例 13：离线环境手动导入赝势

# 在有网机器上下载 aiida-pseudo install sssp -v 1.3 -p efficiency --download-only 拷贝压缩包到离线机器后手动导入 aiida-pseudo install family /path/to/sssp-1.3-efficiency.tar.gz SSSP/1.3/PBE/efficiency

HPC 集群通常无外网，离线导入是必备技能。

案例 14：统计赝势族覆盖的元素数量

from aiida import orm, load_profile load_profile() for label in ['SSSP/1.3/PBE/efficiency', 'SSSP/1.3/PBE/precision']: family = orm.load_group(label) print(label, len(family.elements))

用于评估赝势库是否覆盖研究体系涉及的全部元素。

案例 15：在 Notebook 中可视化赝势使用情况

from aiida import orm, load_profile import collections load_profile() qb = orm.QueryBuilder() qb.append(orm.CalcJobNode, tag='c', project='*') qb.append(orm.UpfData, with_incoming='c', tag='p', project='filename') counter = collections.Counter() for filename, in qb.iterall(): counter[filename] += 1 for name, cnt in counter.most_common(10): print(f"{name}: {cnt}")

可快速了解项目中哪些赝势被高频使用。

案例 16：完整的最小可运行示例

from aiida import orm, load_profile from aiida.engine import run_get_node from aiida_quantumespresso.calculations.pw import PwCalculation load_profile() family = orm.load_group('SSSP/1.3/PBE/efficiency') structure = orm.load_node(STRUCTURE_PK) builder = PwCalculation.get_builder() builder.code = orm.load_code('qe-7.2@localhost') builder.structure = structure builder.pseudos = family.get_pseudos(elements=structure.get_symbols_set()) builder.parameters = orm.Dict({ 'CONTROL': {'calculation': 'scf'}, 'SYSTEM': {'ecutwfc': 60, 'ecutrho': 480}, }) builder.kpoints = orm.KpointsData() builder.kpoints.set_kpoints_mesh([6, 6, 6]) builder.metadata.options.resources = {'num_machines': 1} builder.metadata.options.max_wallclock_seconds = 3600 results, node = run_get_node(builder) print('计算完成:', node.pk, results['output_parameters'].get_dict())

这个例子把安装、加载、注入赝势、提交计算串成完整闭环，适合作为入门模板。

五、常见错误与排查

5.1 赝势族找不到

ValueError: No group found with label 'SSSP/1.3/PBE/efficiency'

原因：未安装该族，或标签拼写不一致。
解决：执行aiida-pseudo list确认实际标签，注意大小写和斜杠。

5.2 元素缺失

ValueError: the pseudo for element 'Xx' is not available

原因：结构中含有 SSSP 未收录的元素（如某些放射性元素）。
解决：检查family.elements，必要时手动补充赝势或更换体系。

5.3 泛函不匹配

使用 PBE 赝势却在input_dft中写了PBEsol，会导致能量偏差。务必保证赝势族泛函与计算输入一致。

5.4 网络下载失败

ConnectionError: HTTPSConnectionPool ... Read timed out

解决：配置代理，或使用--download-only在可联网机器下载后离线导入。

5.5 数据库版本不兼容

旧版aiida-sssp可能不兼容新版aiida-core。建议升级到最新版本，或改用aiida-pseudo内置的 SSSP 安装命令。

5.6 重复安装导致标签冲突

同一标签重复安装会报错。可先aiida-pseudo list检查，或使用--label指定新标签。

六、使用注意事项

• 版本锁定：论文或项目应明确记录使用的 SSSP 版本与精度档位，保证可复现。
• 泛函一致：赝势泛函、input_dft、以及后续对比数据必须统一。
• 精度选择：高通量筛选用 efficiency，最终精确计算建议用 precision 复核关键结果。
• 离线部署：HPC 环境提前准备离线包，避免计算中途因下载失败中断。
• 节点管理：赝势节点会占用数据库空间，定期清理无用节点，但不要删除已被计算引用的节点。
• 迁移兼容：新项目优先使用aiida-pseudo install sssp，旧项目迁移时注意 API 差异。

七、总结

aiida-sssp把 SSSP 赝势库与 AiiDA 的数据溯源能力结合起来，让高通量材料计算中的赝势选择从“手工拷贝文件”变成“可查询、可追溯、可复现”的标准化流程。掌握其安装、语法参数与常见坑位后，可以显著提升计算流程的稳定性与结果可信度。建议从案例 16 的最小示例入手，逐步扩展到批量筛选与工作流集成。

《AI提示工程必知必会》为读者提供了丰富的AI提示工程知识与实战技能，主要包括各类提示词的应用，如问答式、指令式、状态类、建议式、安全类和感谢类提示词，以及如何通过实战演练掌握提示词的使用技巧；使用提示词进行文本摘要、改写重述、语法纠错、机器翻译等语言处理任务，以及在数据挖掘、程序开发等领域的应用；AI在绘画创作上的应用，百度文心一言和阿里通义大模型这两大智能平台的特性与功能，以及市场调研中提示词的实战应用。通过阅读《AI提示工程必知必会》，读者可掌握如何有效利用AI提示工程提升工作效率，创新工作流程，并在职场中脱颖而出。