虚拟器官插件开发教程3SimVascular 环境搭建与 svPythonAPI——BSD 基座、内嵌 Python 与一张真实的文件扩展名地图版本声明块工具/软件SimVascular 主程序BSD 许可现行安装包SimVascular-Ubuntu-24-2025.06.21.deb分发在 SimTK FRsgroup_id188、svMultiPhysicsBSD-3-Clause、svZeroDSolverBSD-3-Clause、svMorphMIT、svFSI“MIT-like”语言/环境SimVascular 内嵌 Python 3脚本模式simvascular --python -- path.py、bash/WSL、外部 Python 3.10本文目标把装哪个包、在哪个解释器里写代码、读写哪些文件三件事一次说死避免在环境上反复掉坑一句话结论SimVascular 是BSD 许可的开源心血管仿真管线引用规范 Updegrove et al.,Ann Biomed Eng45:525, 2017, doi:10.1007/s10439-016-1762-8安装包真正分发在 SimTK FRs现行 Ubuntu 24 的2025.06.21deb约 1333 MB而 GitHub Releases 只到2023-05/2022-07外加 2025-06 的 externals 构建2024.x 主程序无官方发布Python API 是内嵌在可执行文件里的sv包共 9 个子模块dmg/geometry/imaging/meshing/modeling/pathplanning/segmentation/simulation/vmtk经ctypes.PyDLL加载平台相关共享库⚠️ 老教程里的Python Console 已不在新版 GUI 中官方文档仓库 2026-03-31 提交说明 “no longer in the GUI”改走simvascular --python的Python Shell与脚本模式官方示例写法import svimport vtk后调用sv.segmentation.Circle(radius1.0, center[1.0,1.0,1.0], normal[1.0,0.0,0.0])。〇、本篇要解决的认知问题问题 1我该从哪儿下载 SimVascular为什么 GitHub Releases 页面上找不到 2024.x问题 2内嵌 Python 到底是便利还是枷锁我自己的 numpy/pandas 项目怎么和它共存问题 3教程截图里的 “Python Console” 在 GUI 里找不到了现在该从哪个入口写脚本问题 4sv包有哪九个子模块、命名规范是什么、和 GUI 工具怎么一一对应问题 5.vtu/.vtp/.svpre/.in/.xml/.json/.sjb/.dat各是谁的生产物网传的.vsmt/.stm/.stp/.svmg存在吗文档站为什么抓不到正文一、机制解析1.1 版本与分发口径三处入口各有滞后入口你能拿到什么口径说明SimTK FRsgroup_id188现行安装包SimVascular-Ubuntu-24-2025.06.21.deb约 1333 MB、SimVascular-macOS-Ventura-M2-2025.05.02.dmg页面自述 Beta Releaseupdated externals另有Purkinje Plugin跨平台安装包2022-07-20与sv_tests演示工程版本号是日期式YYYY.MM.DD不是语义化版本这是官方主分发渠道GitHub Releases2023-052023-05-31、2022-072022-08-02、2021.09.30、2018.07.04WCB 2018以及 2025-06 的 externals 构建标签主程序发布稀疏2024 年只有求解器svFSIplus-Ubuntu22-x64-2024.09.27.deb主程序无 2024.x 官方发布——找不到 2024 版不是你眼神问题GitHub 源码 / 组织仓库SimVascularGUI、svSolver、svFSI、svMultiPhysics现行默认2024-11-20 官方由 svFSIplus 改名并入、svZeroDSolver、svOneDSolver、svFSI-Tests、svMorph、svVascularize二次开发要跟的是这些子仓库不是主发行页为什么这对你重要企业里版本可追溯是硬要求。请把2025.06.21这类日期式版本写进插件的运行元数据别写最新稳定版——将来复现不了就是审计事故。1.2 启动脚本与两种 Python 入口官方文档给出的启动脚本位置DATE为安装日期目录Linux : /usr/local/sv/simvascular/DATE/simvascular macOS : /usr/local/sv/simvascular/DATE/simvascular Windows: C:\Program Files\SimVascular\SimVascular\DATE\sv.batGUI 模式双击/命令行启动用面板做前处理。Python Shellsimvascular --python终端里进入交互式解释器行为等同标准 Python支持自动缩进退出用 Ctrl-DWindows 用exit()。脚本模式simvascular --python -- my_plugin.py注意脚本名前那个--。为什么这对你重要批量仿真与 CI 只能走脚本模式把插件一个 .py 入口纯 Python 核心设计好GUI 只是可选外壳。1.3 内嵌 Python免装但外部包不可用官方文档documentation/python_interface/intro/python_prog_env/readme.md原话是Python 环境内嵌在 SimVascular 可执行文件中含标准库与若干额外组件“Python does not need to be installed on your computer”内嵌保证解释器与模块版本兼容“However, it prevents using Python packages that may already be installed”无法直接使用你系统里已装的第三方包。这决定了插件的代码形态形态能用什么典型用途代价内嵌 Pythonsv可用sv.*、内嵌vtk影像/分割/中心线/网格/工程节点读写装不了pandas/scikit-learn等自备包外部 Python你的 venv全宇宙 pip 包药理学内核、批量调度、统计与出图看不到sv得靠文件/命令行交换数据工程结论核心逻辑写成外部可跑、不依赖 sv边界适配层写成内嵌可跑、只碰 sv——这正好对应第 2 篇的三层架构L2 在外部L1 在内嵌。另有一个反直觉细节sv/__init__.py里为了兼容嵌入启动时sys.argv缺失显式写了if not hasattr(sys, argv): sys.argv []因为某些第三方包docstring 点名 tensorflow会因此报错——这就是内嵌环境与正常环境的差异样本。1.4sv包解剖9 个子模块与 C 绑定机制Python/site-packages/sv/__init__.py的模块 docstring可直接核对列出 9 个子模块子模块docstring 职责对应 GUI 工具主要文件产物sv.dmg访问 SV Data Manager 节点SV Data Manager工程SVPROJECT/内数据sv.geometry作用在 VTK PolyData 上的几何函数—.vtpsv.imaging影像类与方法Image Menu图像数据、stFile_*.binsv.meshing网格类与方法Meshing Tool后端 TetGen/MeshSim/MMGmesh-complete/、.vtusv.modeling建模类与方法ModelerVessel Segmenter / Modeler.vtp表面sv.pathplanning路径规划PathPath Planning Tool.vtp中心线sv.segmentation分割轮廓Circle/Threshold/LevelSet/Polygon…Segmentations Tool分割节点sv.simulation仿真参数与作业FluidParameters、ROMParametersCFD Simulation Tool / ROM Simulation Tool.sjb、.xml、.json、.insv.vmtk若干 VMTK 功能封装——绑定机制load_module()用ctypes.PyDLL(library_name . ext)取PyInit_*入口ext按平台取so/dylib/dllPyPathplanning、PyMeshing、PySimulation等导出模块来自lib_simvascular_python_apiPyDmg/PyProject来自liborg_sv_pythondatanodes。含义很直白“给 GUI 加一个新模块 加一个PyXxx导出 一个 .py 包装”需要重编译 C普通插件不该走这条路而应挂靠Python/site-packages/里已有的扩展点实存顶层包sv、svZeroDSolver、sv_auto_lv_modeling、sv_ml、sv_rom_extract_results、sv_rom_simulation、sv_vis。GUI 的 Qt 层脚本能力由PythonQt提供ASMEJ Biomech Eng140(2):024501。为什么这对你重要这张GUI 工具 ↔sv子模块 ↔ 文件产物对照表就是插件的接口地图。做批量任务时你需要知道每一步在写哪个文件、由哪个子模块负责否则只能靠 GUI 手点。同时它也划出了你的工作量边界改sv本体要重编 C挂site-packages只要发一个 Python 包。命名规范官方文档明写类名首字母大写、点号分层例如sv.pathplanning.Path、sv.modeling.Modeler、sv.segmentation.Circle函数与方法全小写下划线例如get_center()模块名全小写。两个真实陷阱(a)文档正文里出现过sv.segmention.Circle这种拼写错误的示例以源码为准是sv.segmentation(b)凡返回 VTK 对象的 API脚本必须显式import vtk否则对象造不出来直接报错。1.5 文件扩展名地图逐后缀核实与纠错后缀/文件生产者消费者说明.vtu网格导出、求解器结果Paraview / svPost / 插件VTK XMLUnstructuredGrid体网格与结果如mesh-complete.mesh.vtu、result_002.vtu.vtp中心线、表面模型、svpost 输出svMorph / 建模与网格VTK XMLPolyDatasvMorph 自述the standard output of SimVascular.svpreGUI svSolver 预解配置svpre产出bct.dat、geombc.dat.1、restart.0.1.insvSolver 算例控制文件svsolverFortran 三件套的流解输入.inpsvFSI 算例模板svFSI_master.inpsvFSIlegacy Fortran 多物理/EP 入口.xmlCFD Simulation Tool 输入svmultiphysics现行默认后端Linear_algebra typepetsc指定后端.json0D 集总参数配置svzerodsolver输出.csv.sjbGUI CFD 作业参数GUI/管线路径形如SVPROJECT/Simulations/JOBNAME.sjb.dat/.csv求解器与 0D 边界后处理/插件rcrt.dat、resistance.dat、histor.dat、0D 结果 CSV目录1-procs/、4-procs/并行运行时后处理mpiexec -np 4会新建4-procs纠错只作否定语境网上流传的.vsmt、.stm、.stp当中心线用、.svmg当宏文件用均未在官方仓库与文档中查到判定不是 SimVascular 扩展名中心线现行格式是.vtp。同样不成立的还有./svSolver -i caseDir这种命令行写法真实是三件套svpre吃.svpre、svsolver吃.in、svpost出.vtp/.vtu与pres.xml/velocity.xml两个结果文件名svMultiField这个包名也不存在。为什么这对你重要插件的批量执行器第 14 篇本质上是按扩展名分派读写与重试的状态机。后缀表错了最坏情况不是报错而是静默读到空文件或旧结果——批次跑完才发现几百个条件是脏数据。把这张表做成常量文件进版本库别散落在字符串里。1.6 文档站取源方法写给要抓文档做知识库的你真实入口是https://simvascular.github.io/文档目录页documentation/index.htmlsimvascular.org会跳转、docs.simvascular.org不存在、documentation.html是 404——别把这些当出处。关键机制文档页正文由zero-md元素在浏览器里动态装载 markdown网站仓库 README 明说所有被装载的 markdown 必须命名readme.md导航逻辑在documentation.js。所以curl https://simvascular.github.io/documentation/python_interface.html只能拿到空壳。正确做法是取源文件仓库SimVascular/simvascular.github.io默认分支main里按documentation/章/节/readme.md组织例如documentation/python_interface/intro/python_prog_env/readme.md # 内嵌 Python 与两种入口 documentation/python_interface/intro/python_shell/readme.md # Python Shell 与 --python documentation/python_interface/modules/sv_module/readme.md # sv 包总览 documentation/python_interface/modules/segmentation_module/readme.md documentation/python_interface/modules/path_planning_module/readme.md为什么这对你重要把官方文档纳入插件内部知识库离线检索、版本快照时抓 markdown 源才是可行路径这一步做错你会得到一个全是空页面的知识库。1.7 别忘了它内建电生理但没有药理学svFSI 官方简介写明支持 “blood flow simulation including fluid-structure interaction andcardiac electrophysiology”README 的电生理模型注册表为cepModel_APAliev-Panfilov、cepModel_FN、cepModel_BO、cepModel_TTPten Tusscher-Panfilov 全离子模型源码类CepModTtp/CepModAp/CepModFn带I_Na、I_bNa成员官方算例库svFSI-Tests有08-cep/03-benchmark_tTPNiederer et al. 2011 N-version benchmarkPhil Trans R Soc A369:43313×7×20 mm 立方块。但GUI 没有电生理面板EP 在.inp/XML 输入层配置通道级药物阻滞hERG→I_Kr 缩放无官方模块。第 2 篇说过这一层就是你要写的插件。为什么这对你重要这一段决定你的项目分工——几何、网格、传导、FSI 用现成的药理学自己写并自己验证。反过来若有人告诉你SimVascular 只算血流不算电那是错的若有人告诉你它有药物阻滞模块那同样是错的。二、完整代码与逐行剖析2.1 安装后自检与冒烟测试bash / WSL# 1) 安装目录与启动脚本DATE 是日期式版本目录例如 2025.06.21DATE2025.06.21SVBIN/usr/local/sv/simvascular/$DATE/simvascular# LinuxWindows 下是 C:\Program Files\SimVascular\SimVascular\DATE\sv.bat[-x$SVBIN]echoOK 启动脚本$SVBIN||echoMISS 未找到启动脚本确认从 SimTK FRs(group_id188) 装的 deb/dmg# 2) 交互模式等价于一个带 sv 的 Python REPLCtrl-D 退出$SVBIN--python-cimport sv, sys; print(embedded python:, sys.version.split()[0])2/dev/null||echo改用$SVBIN--python 然后手敲 import sv# 3) 脚本模式注意脚本名前必须有单独的 --官方文档写法catsmoke.pyPY import sv # 内嵌 Python 里才能导入 import vtk # 返回 VTK 对象的 API 必须显式 import vtk否则运行期报错 seg sv.segmentation.Circle(radius1.0, center[1.0, 1.0, 1.0], normal[1.0, 0.0, 0.0]) print(Circle -, type(seg).__module__ . type(seg).__name__) PY$SVBIN--python-- smoke.py|tail-3# tail 一下安装期噪声很大TetGen/OpenCASCADE 版本行# 4) 求解器svMultiPhysics 无原生 WindowsWindows 走 WSLcommand-vsvmultiphysics/dev/nullechoOK svmultiphysics||echoMISS svMultiPhysicsWSL 内安装或用 GUI ROM/0D 先跑通链路2.2 双环境体检sv 子模块清单 文档源抓取外部解释器即可跑第 3 篇环境体检外部解释器也能跑在内嵌 Python 里会自动升级为逐子模块探测。importimportlib.utilasutilimportsysimporturllib.request SV_MODULES{# 名称与职责取自仓库 Python/site-packages/sv/__init__.py 的模块 docstringdmg:SV Data Manager 节点访问工程数据,geometry:作用在 VTK PolyData 上的几何函数,imaging:影像读写与处理,meshing:网格生成TetGen/MeshSim/MMG 后端,modeling:由分割建表面模型Modeler,pathplanning:中心线路径Path落盘 .vtp,segmentation:图像分割轮廓Circle/Threshold/LevelSet/Polygon,simulation:求解参数与作业含 ROMParameters.add_rcr,vmtk:若干 VMTK 功能的封装,}defsv_health():print(f[解释器]{sys.version.split()[0]}{sys.prefix})ifutil.find_spec(sv)isNone:# 外部解释器不报错而是给出正确入口print([结论] 外部解释器sv 不可用它随可执行文件内嵌pip 装不到。)print( 交互simvascular --python 脚本simvascular --python -- my_plugin.py)returnimportsvprint([结论] 已在内嵌 Python 中逐子模块探测)forname,dutyinSV_MODULES.items():okutil.find_spec(sv.name)isnotNoneorhasattr(sv,name)print(f{OK ifokelseMISS}sv.{name:12s}{duty})try:importvtk# 缺 vtk 时所有返回 VTK 对象的 API 都会失败print( OK vtk,vtk.VTK_VERSION)exceptImportError:print( MISS vtk - 检查安装是否完整externals 构建差异)deffetch_doc(md_path,repoSimVascular/simvascular.github.io,refmain,n8):文档站正文由 zero-md 动态装载 markdown - 抓 HTML 无正文直接取 readme.md 源。urlfhttps://api.github.com/repos/{repo}/contents/{md_path}requrllib.request.Request(url,headers{Accept:application/vnd.github.rawjson,User-Agent:sv-doc-probe})# 无 UA 时 GitHub API 会拒withurllib.request.urlopen(req,timeout30)asr:textr.read().decode(utf-8,replace)print(f\n---{md_path}(HTTP{r.status},{len(text)}chars) ---)forlinein[ln.strip()forlnintext.splitlines()ifln.strip()][:n]:print( ,line[:110])if__name____main__:sv_health()fetch_doc(documentation/python_interface/intro/python_prog_env/readme.md)# 内嵌 Python 取舍的官方出处本机外部 Python无 SimVascular实跑[解释器] 3.10.11 C:\Users\...\tools\python [结论] 当前是外部解释器sv 包不可用它随 SimVascular 可执行文件内嵌分发pip 装不到。 请用安装目录的启动脚本进入 Python Shellsimvascular --python 或脚本模式simvascular --python -- my_plugin.py --- documentation/python_interface/intro/python_prog_env/readme.md (HTTP 200, 5203 chars) --- # Python Programming Environment ... The Python programming environment is embedded in the SimVascular executable and includes the standard library剖析sv_health()的价值在于它把失败变成指引——外部解释器不再抛ModuleNotFoundError让人瞎猜而是直接给出该用的入口命令fetch_doc()则演示了取源正确姿势走 GitHub Contents API Accept: application/vnd.github.rawjson绕开zero-md的 JS 装载。2.3 官方示例的两段真实 API在内嵌 Python / 脚本模式里跑importsv# 官方文档原样内嵌环境importvtk# 官方文档原样sv 的 API 大量返回 VTK 对象脚本必须显式 import vtkcircle_segsv.segmentation.Circle(radius1.0,center[1.0,1.0,1.0],normal[1.0,0.0,0.0])# 类名首字母大写、点号分层这是 sv 包的硬规范Path/Modeler/Segmentation 同理importsv.simulationassim# simulation 子模块挂着 ROMParameters/FluidParameterspsim.ROMParameters.BoundaryConditions()p.add_rcr(outlet_0,Rp1.0e8,C1.5e-9,Rd5.0e6)# 3 元件 Windkessel(RCR)外周阻力顺应舒张期阻力p.add_resistance(outlet_1,3.0e8)# 纯电阻出口只做简单下游负载时用p.write_files(./)# 落盘 rcrt.dat / resistance.dat供 0D/3D-0D 耦合读取# 壁材模型常量ROMParameters.WallProperties.OLUFSEN_MATERIAL_MODEL / LINEAR_MATERIAL_MODEL求解器侧的对应命令行都是真实形态供插件的执行器层调用svmultiphysics fluid3d.xml# C 现行 CFD 后端输入 XMLmpiexec-np4svmultiphysics fluid3.xml# 结果写进新建的 4-procs/mpiexec-npNbuild/svFSI-build/bin/svFSI case.inp# legacy Fortran含 EP/FSISimCardio 主力svzerodsolver tests/cases/steadyFlow_RLC_R.json result.csv# 0DJSON - CSV另有 pip 包 pysvzerod三、常见报错与排查ModuleNotFoundError: No module named sv——根因sv内嵌于 SimVascular 可执行文件Python/site-packages/sv/不在系统 Python 的site-packages里。解法simvascular --python或simvascular --python -- script.py插件按 1.3 拆成内嵌适配层外部核心。AttributeError: module sv has no attribute segmention——根因照抄了官方文档里的拼写错误示例。解法以源码为准sv.segmentationdir(sv)是唯一可信清单。调用建模/网格函数时报 VTK 相关错误——根因脚本没import vtk官方文档明确返回 VTK 对象的 API 必须显式导入。解法脚本开头import vtk。在 GUI 里翻找 “Python Console” 找不到——根因官方文档仓库 2026-03-31 的提交把 Getting Started 中的 Python Console 引用移除“no longer in the GUI”但python_interface章节仍留有历史页面读到旧描述会误判。解法用Python Shell若你的脚本要读写 SV Data Manager 的工程节点先在你实装的版本里确认该能力入口以官方文档现行说明为准。Windows 上svmultiphysics不存在 / 装不上——根因svMultiPhysics 不支持原生 Windows。解法WSLUbuntu 24 的 2025.06.21 deb或先用 svSolver/svZeroDSolver 打通链路再迁移。四、动手练习入口验证在 Python Shell 里执行import sv; print(sv.__file__)。判定标准打印出的路径位于 SimVascular 安装目录内的Python/site-packages/sv/__init__.py。子模块清单执行print([n for n in dir(sv) if not n.startswith(_)])与 1.4 表格比对。判定标准9 个子模块全部出现缺vmtk时终端应能看到 “VMTK is not available!” 这类降级提示。扩展名普查解压官方sv_tests演示工程对目录跑find . -type f | sed s/.*\.// | sort | uniq -c | sort -rn。判定标准结果里出现vtu/vtp/svpre/in/xml/json/sjb/dat中至少 5 类且不出现.vsmt/.stm/.stp/.svmg。五、小结与下一篇预告本篇把 SimVascular 的环境问题一次讲透装哪儿SimTK FRs日期式版本2024.x 无主程序发布、在哪儿写代码内嵌 PythonPython Shell/脚本模式Console 已成历史、能用什么9 个子模块必须import vtk外部 pip 包不可用、读写什么真实扩展名地图并对四类假扩展名做否定、文档怎么取抓readme.md源而非 HTML。第 4 篇将离开基座、进入 L2用 Myokit 把离子通道模型跑成器官节拍器并用纯 numpy 复现 I_K 阻滞下 APD90 从 2.34 ms 到 5.35 ms、≥90% 不复极的实跑曲线第 2 篇的三层骨架届时会被真正填上第一块药理学砖而第 5 篇把 CiPA 的 7 电流面板补齐。本篇认知问题回显FAQQ1SimVascular 安装包从哪里下载为什么 GitHub 上没有 2024.x 版本A主分发渠道是 SimTK FRsgroup_id188现行SimVascular-Ubuntu-24-2025.06.21.deb约 1333 MB与SimVascular-macOS-Ventura-M2-2025.05.02.dmg自述 Beta Release版本号是日期式 YYYY.MM.DDGitHub Releases 只有 2023-05、2022-07、2021.09.30、WCB 2018 与 2025-06 的 externals 构建。2024 年只发布过求解器svFSIplus-Ubuntu22-x64-2024.09.27.deb主程序无 2024.x。Q2SimVascular 内嵌 Python 和系统 Python 有什么区别我的第三方包能用吗APython 环境内嵌在可执行文件中含标准库与额外组件因此无需安装 Python 且解释器与模块版本保证兼容但官方明确prevents using Python packages that may already be installed系统里已 pip 装的包用不了。工程做法核心算法放外部 venvsv.*调用放内嵌脚本层两边用 .vtp/.vtu/.json/CSV 交换。Q3新版 GUI 里找不到 Python Console脚本该从哪里跑A用Python Shellsimvascular --pythonLinux/macOS 启动脚本在/usr/local/sv/simvascular/DATE/Windows 是...\SimVascular\DATE\sv.batCtrl-D 或exit()退出跑脚本用simvascular --python -- path.py。官方文档仓库 2026-03-31 提交把 Getting Started 中的 Python Console 引用移除并注明其已不在 GUI 中。Q4sv 包有哪些子模块命名和调用有什么规范A9 个子模块dmg、geometry、imaging、meshing、modeling、pathplanning、segmentation、simulation、vmtk职责见sv/__init__.pydocstring底层用ctypes.PyDLL加载lib_simvascular_python_api.so/.dylib/.dll。规范模块全小写、类首字母大写点号分层sv.pathplanning.Path、sv.segmentation.Circle、函数小写下划线返回 VTK 对象的调用必须显式import vtk。Q5SimVascular 的真实文件扩展名有哪些.vsmt/.stm/.stp/.svmg存在吗文档怎么抓A真实集合是.vtu体网格/结果、.vtp表面/中心线、.svpre与.insvSolver、.inpsvFSI、.xmlsvMultiPhysics、.jsonsvZeroDSolver、.sjbCFD 作业、.dat/.csv.vsmt、.stm、.stp、.svmg官方仓库与文档中均未查到判定为讹传。文档正文由zero-md动态装载须抓仓库SimVascular/simvascular.github.io分支 main的documentation/章/节/readme.md。
复杂度详解)
