分子模拟异构算力适配开发教程4OpenMM Platform 抽象——一个 Context 如何在五个引擎之间切换版本声明块工具/软件OpenMM 8.2HIP 平台进主线、getPlatform(name)新重载PyPI 8.3.1 / GitHub 8.5.1getDevices()新 API语言/环境Python 3.10–3.13PyPI wheel 覆盖范围本文目标读完你能写出平台自动协商代码——同一份 System/Integrator 在不同硬件上自动选最优平台并正确传属性一句话结论OpenMM 用Platform.registerPlatform()注册平台、Platform.getPlatformByName(CUDA)或 8.2 的getPlatform(CUDA)按名查找、Context(system, integrator, platform, properties)第四参数传平台属性字典如{Precision:mixed,DeviceIndex:0}——五个内置平台Reference/CPU/CUDA/OpenCL/HIP共存于一个二进制这是它与 GROMACS 编译期绑定的根本差异。〇、本篇要解决的认知问题OpenMM 内置哪五个平台各自的能力边界与适用场景是什么Platform 的注册/查找 API 族getNumPlatforms/getPlatform/getPlatformByName/findPlatform怎么用8.2.0 和 8.5.0 各新增了什么平台属性Precision、DeviceIndex、Threads 等从哪查、怎么传、哪些平台认哪些如何写一个自动选平台的协商函数让同一份模拟脚本在 NVIDIA/AMD/CPU 机器上都跑起来一、机制解析1.1 五个平台的能力地图为什么这一节对你重要平台选择是 OpenMM 侧异构适配的第一决策——选错平台轻则慢十倍Reference重则直接跑不了CUDA 平台在没有 CUDA 的机器上找不到。五个平台的准确名称字符串大小写敏感与能力平台精度速度适用Reference双精度确定性参考实现极慢比 CPU 慢约百倍量级数值验证、教学、调试CPUmixed中无 GPU 机器、小体系快速迭代CUDAsingle/mixed/double快NVIDIA GPUOpenCLsingle/mixed/double较快跨厂商含苹果但生态收缩HIP同 CUDA 属性集快官方称较 OpenCL 约两倍AMD GPUROCm8.2.0 进主线三个关键事实① HIP 平台是 8.2.02024-11进入主线的release note 原文称其性能相比 OpenCL 平台roughly double官方用户指南有 “11.3 HIP Platform” 专节② HIP 平台识别与 CUDA 平台完全相同的平台属性官方原文 “The HIP Platform recognizes exactly the same Platform-specific properties as the CUDA platform”——从 CUDA 迁到 AMD 只需换平台名属性照传③ OpenMM 8 论文arXiv:2310.03121记录了 HIP 后端对 AMD GPU 性能的大幅提升。为什么 Reference 平台值得存在它是确定性双精度实现是跨平台数值对账的黄金参照第 19 篇的故障诊断直接用它——性能最差的位置恰恰是正确性最高的锚点。1.2 Platform API 族注册、枚举、按名查找、按内核查找官方 Python APIopenmm.openmm.Platform的 static 方法族Platform.registerPlatform(platform)# 注册新平台插件机制入口第 8 篇Platform.getNumPlatforms()# 已注册平台数Platform.getPlatform(index)# 按索引取Platform.getPlatform(CUDA)# 按名取8.2.0 新增重载Platform.getPlatformByName(CUDA)# 按名取向后兼容别名一直可用Platform.findPlatform(kernelNames)# 按内核名查找能力协商的原生入口Platform.loadPluginsFromDirectory(dir)# 从目录批量加载平台插件版本变化要记牢8.2.0新增getPlatform(name)重载getPlatformByName保留为兼容别名两者行为一致8.5.0新增getDevices(filters{})实例方法——“new API to query what devices are available before starting a simulation”模拟启动前查询设备不再需要先建 Context 才知道有哪些卡。一个容易踩的 API 陷阱Platform.addPlatform不存在——官方 C/Python API 文档7.7.0 与 latest 四份对照均无此方法注册入口只有registerPlatform。网上一些二手资料写 addPlatform照抄必报 AttributeError。findPlatform(kernelNames)是被低估的能力协商原语传入你的模拟所需的内核名列表返回第一个支持全部内核的平台。体系里用了 CustomForce 时前一部曲的主题不是所有平台都有对应内核实现——findPlatform 让你把平台能不能跑这个体系的判断交给 OpenMM 自己。1.3 平台属性每平台的参数面属性properties是平台暴露的参数面通过 Context 构造的第四参数传入Mapping[str, str]值是字符串——传 int 会出类型错误。官方用户指南第 11 章的准确属性名平台属性取值CUDA / HIPPrecisionsingle / mixed / doubleDeviceIndex设备号多卡逗号分隔如 “0,1”TempDirectory临时目录内核编译缓存UseCpuPmetrue/falseDeterministicForces/UseBlockingSyncCUDA 系调试选项OpenCLPrecision/DeviceIndex/OpenCLPlatformIndex/UseCpuPmeDeviceIndex 同样支持逗号分隔CPUThreads线程数默认读环境变量OPENMM_CPU_THREADS未设则用逻辑核数两个实践要点① 属性名是平台自描述的——platform.getPropertyNames()返回该平台认的属性清单比死记硬背可靠第 1 篇探测脚本已经用了它② 传不认识的属性会报错所以按平台筛属性是封装层的必备逻辑见下节代码。反直觉默认值CPU 平台的Threads不传时不是全部核心而是逻辑核数——在超线程机器上这通常不是最优值物理核数才是跑 CPU 平台基准时值得显式设置对照。1.4 环境变量与设备可见性CUDA/OpenCL 平台选卡除了DeviceIndex属性还受进程环境变量CUDA_VISIBLE_DEVICES影响对 CUDA 平台——OpenMM 遵循 CUDA 运行时的可见性机制。这一点在第 16 篇Slurm 会为作业注入 CUDA_VISIBLE_DEVICES和第 18 篇适配层要统一处理设备可见性是核心衔接点调度器改环境变量、OpenMM 读环境变量、DeviceIndex 在可见集合内再选三层关系必须理清。二、完整代码与逐行剖析一个生产级的平台协商器——统一入口create_context()自动选平台、筛属性、优雅降级#!/usr/bin/env python3OpenMM 平台协商器自动选平台 属性过滤 优雅降级。 设计目标同一份脚本在 NVIDIA / AMD / 纯CPU 机器上都直接跑铁律 10封装不改数值 降级只影响速度不影响正确性——Reference 平台兜底保证总能跑出对的结果。 fromopenmmimportContext,Integrator,Platform,System# 协商优先级生产平台在前Reference 兜底。# HIP 与 CUDA 都认同一套属性官方文档可以共用属性构造逻辑。PLATFORM_PRIORITY[CUDA,HIP,OpenCL,CPU,Reference]# 用户偏好属性——注意值全部是字符串Context properties 的类型要求BASE_PROPERTIES{Precision:mixed,# 铁律 7默认 mixeddouble 需论证Threads:str(8),# CPU 平台用超线程机器建议物理核数}defnegotiate_platform(system:System,required_kernels:list[str]|NoneNone)-Platform:按优先级找一个能跑这个体系的平台。 两层判据 1. 内核能力required_kernels 非空时用 findPlatform 语义手动检查 2. 平台存在性按 PLATFORM_PRIORITY 顺序尝试 返回Platform 实例。 fornameinPLATFORM_PRIORITY:try:platformPlatform.getPlatformByName(name)# 不存在则抛异常吃掉继续exceptException:continue# 内核能力检查getPropertyNames 只是参数面真正的内核支持在 Context 创建时才暴露。# 这里先做平台在场级协商内核级失败留给 create_context 的异常处理。returnplatformraiseRuntimeError(没有任何可用平台连 Reference 都没有安装有问题)deffilter_properties(platform:Platform,props:dict[str,str])-dict[str,str]:按平台自描述的属性面过滤用户属性。 为什么必须过滤把 CUDA 的 TempDirectory 传给 CPU 平台会直接报错 getPropertyNames() 是官方提供的自描述接口比硬编码哪个平台认哪些健壮。allowedset(platform.getPropertyNames())return{k:vfork,vinprops.items()ifkinallowed}defcreate_context(system:System,integrator:Integrator,prefer:str|NoneNone,device:str0,**extra_props)-Context:统一 Context 创建入口。 prefer: 强制平台名如 CUDANone 则自动协商。 device: DeviceIndex 值字符串CUDA/HIP/OpenCL 平台生效。 extra_props: 额外平台属性覆盖。 propsdict(BASE_PROPERTIES)props.update(extra_props)ifpreferisnotNone:platformPlatform.getPlatformByName(prefer)# 强制时不再降级找不到直接抛else:platformnegotiate_platform(system)props.setdefault(DeviceIndex,device)# setdefault允许调用方显式覆盖propsfilter_properties(platform,props)try:returnContext(system,integrator,platform,props)exceptExceptionase:# 内核不支持等深层失败降级到 Reference 拿正确性性能牺牲ifplatform.getName()!Reference:print(f[warn]{platform.getName()}创建 Context 失败{e}降级 Reference)returnContext(system,integrator,Platform.getPlatformByName(Reference))raisedefmain()-None:演示同一份体系在三台机器上的行为。# 探测面第 1 篇的脚本可复用先看这台机器有什么names[Platform.getPlatform(i).getName()foriinrange(Platform.getNumPlatforms())]print(已注册平台:,names)# OpenMM 8.5 可以在创建 Context 前查询设备旧版本此 API 不存在注意守卫pPlatform.getPlatformByName(names[0])ifnameselseNoneifhasattr(p,getDevices):print(设备清单:,p.getDevices())# 构造一个最小演示体系并跑协商实际使用时 system/integrator 来自你的建模流程fromopenmmimportappfromopenmmimportunitfromsysimportstdout pdbapp.PDBFile(5dfr_minimized.pdb)# OpenMM 自带示例体系之一examples/benchmarks 目录forcefieldapp.ForceField(amber14-all.xml,amber14/tip3pfb.xml)systemforcefield.createSystem(pdb.topology,nonbondedMethodapp.PME,constraintsapp.HBonds)integratoropenmm.LangevinMiddleIntegrator(300*unit.kelvin,1/unit.picosecond,0.002*unit.picoseconds)contextcreate_context(system,integrator)print(协商结果:,context.getPlatform().getName(),context.getPlatform().getPropertyValue(context,Precision))if__name____main__:main()逐段剖析negotiate_platform的两层判据是刻意的属性面getPropertyNames在平台对象上就能查但内核能力这个平台有没有实现你的 CustomForce 内核只有创建 Context 时才暴露——所以协商器把内核级失败留给create_context的 try/except 降级路径。这是探测成本与信息完整度的权衡。filter_properties用getPropertyNames()做白名单过滤这是官方自描述接口的正确用法——新增平台如国产插件第 8/10 篇带自己的属性集时这段代码不用改。降级链CUDA→HIP→OpenCL→CPU→Reference的终点是 Reference慢但双精度确定性保证脚本总能出对的结果。这是铁律 10调度封装不改变物理在单机层面的体现——性能可以降正确性不许丢。hasattr(p, getDevices)守卫 8.5.0 的新 API——8.3.x 的 PyPI 包没有这个方法直接调用会在 8.3.1 上崩PyPI 落后 GitHub 发布线是 OpenMM 的现状第 1 篇版本基线。三、常见报错与排查问题 1现象——Platform.getPlatformByName(cuda)抛 “There is no registered Platform called cuda”。根因平台名大小写敏感正确写法是CUDA。同类错误还有Cuda、hip应为HIP。解法永远用第 1 篇的探测脚本先枚举平台名从输出里复制或用常量表管理平台名字符串。问题 2现象——Context 创建时报 “Property DeviceIndex is not recognized” 之类属性错误。根因把 A 平台的属性传给了 B 平台最常见CUDA 的 DeviceIndex 传给 CPU 平台或对 OpenCL 平台传了 CUDA 专属的 TempDirectory。解法用本文的filter_properties或对照官方用户指南第 11 章的属性表本篇 1.3 节的表就是从那里来的。问题 3现象——脚本在 PyPI 装的 8.3.1 上调用Platform.getPlatform(CUDA)新重载工作正常但同事在 conda 装的 8.1.0 上报 TypeError。根因getPlatform(name)按名重载是 8.2.0 新增8.1 及以前getPlatform()只接受索引。getPlatformByName才是全版本兼容的写法。解法封装层统一用getPlatformByName它在新版本仍是兼容别名官方文档确认或在使用处做版本守卫。问题 4现象——明明有两块 GPUDeviceIndex 传 “1” 却报设备不存在。根因DeviceIndex是在进程可见设备集合内编号的。如果环境变量CUDA_VISIBLE_DEVICES0已把可见集合限制为单卡那么容器/进程内的 “1” 不存在——可见集合重编号是 CUDA 运行时的语义OpenMM 遵循它。解法排障时先查echo $CUDA_VISIBLE_DEVICES要跨过可见性限制要么改环境变量要么把 DeviceIndex 理解为可见集合内编号。第 16 篇 Slurm自动注入 CUDA_VISIBLE_DEVICES与第 18 篇适配层统一设备可见性会再回到这个三层关系。四、动手练习练习 1基础在你任一台机器上跑通本文协商器 main()需要 OpenMM 示例文件 5dfr_minimized.pdb可从 OpenMM GitHub 仓库 examples/benchmarks/ 目录取记录已注册平台清单、协商结果平台名、Precision 属性值。判定成功标准程序无异常退出协商结果不是 Reference除非机器真无 GPU输出的 Precision 为 mixed。练习 2进阶给协商器加基准驱动的选择——对候选平台如 CUDA 与 CPU各跑 500 步integrator.step(500)计时选 ns/day 高者。注意用time.perf_counter()计时并换算 ns/day步数 × dt / 秒数 × 86400。判定成功标准输出两个平台各自的 ns/day保留 1 位小数与最终选择CPU 平台 ns/day 0 且低于 CUDA如可用选择逻辑可被 prefer 参数覆盖。练习 3思考题无标准答案GROMACS 用编译期绑定换性能、OpenMM 用运行期注册换灵活性混合架构比如编译期选定内核 运行期选调度可行吗思考方向验证要点① 第 5 篇 gpu_utils 的后端文件分派模式是否接近这种混合② 摩尔线程同时做了 GROMACS fork编译期与 openmm-musa 插件运行期两条线的工程量对比③ 内核二进制体积与首次加载延迟的取舍。五、小结与下一篇预告本篇讲透了 OpenMM 的运行期平台抽象五平台各有定位Reference 是正确性锚点API 族里 getPlatformByName 全版本兼容、getPlatform(name) 是 8.2 新货、registerPlatform 是插件入口addPlatform 不存在平台属性按平台自描述getPropertyNames值必须字符串协商器把平台存在性与内核能力分层判断Reference 兜底保证正确性。设备可见性的三层关系环境变量/平台属性/调度器是后续调度篇的伏笔。下一篇回到 GROMACS 源码gpu_utils 模块的 DeviceContext/DeviceStream/DeviceBuffer 三件套如何把 CUDA/HIP/SYCL 的差异藏进一层 C 抽象——理解它是读懂任何国产后端移植第 9 篇的前置课。第 8 篇再把 OpenMM 插件开发补全registerPlatforms/registerKernelFactories 双导出协议。本篇认知问题回显FAQQ1OpenMM 内置哪些平台HIP 平台是什么时候加入的AOpenMM 8.x 内置五个平台Reference、CPU、CUDA、OpenCL、HIP准确字符串大小写敏感。HIP 平台在 8.2.02024-11进入主线基于 AMD HIP 框架官方称性能约为 OpenCL 平台的两倍且识别与 CUDA 平台完全相同的平台属性。Q2OpenMM 按名字获取平台的正确 API 是什么addPlatform 存在吗A全版本兼容写法是Platform.getPlatformByName(CUDA)8.2.0 新增Platform.getPlatform(CUDA)按名重载getPlatformByName 保留为兼容别名。Platform.addPlatform不存在——官方 API 文档无此方法注册新平台的唯一入口是Platform.registerPlatform(platform)。Q3OpenMM 的 CUDA 平台支持哪些平台属性DeviceIndex 怎么传多卡ACUDA与 HIP平台支持 Precisionsingle/mixed/double、DeviceIndex、TempDirectory、UseCpuPme、DeterministicForces、UseBlockingSyncDeviceIndex 多卡用逗号分隔字符串如 “0,1”且编号是进程可见设备集合内的编号受 CUDA_VISIBLE_DEVICES 影响所有属性值必须是字符串。Q4怎么让同一份 OpenMM 脚本在不同硬件上自动选平台A按优先级遍历候选平台名CUDA→HIP→OpenCL→CPU用Platform.getPlatformByName()探测存在性用getPropertyNames()过滤属性后经Context(system, integrator, platform, properties)创建内核级失败时降级到 Reference 平台兜底双精度确定性实现保证结果正确性。