将自动化仿真工作流与3D可视化集成以实现元宇宙中的虚拟实验

摘要

本文介绍了一种通用的、符合FAIR原则的方法，适用于领域专家研究人员将模拟和数据处理工具集成到三维虚拟实验的自动化工作流中。以中子学为例，展示了如何建立本地Galaxy实例，封装OpenMC和文件转换工具，从Omniverse启动工作流，并对转换后的三维输出结果进行可视化。

摘要

在许多虚拟实验中，通常会结合使用多种软件包，涉及不同类型的模拟、预处理与后处理工具，以及用于可视化实验结果的工具。目前整合这些工具的典型方法是手动操作，针对每个应用领域定制专门的解决方案，这种方法可扩展性差，且阻碍了成果的共享与可重复性。

本方案演示了本地容器化工作流系统的部署与使用。按照本方案操作，用户将使用 Docker 启动一个本地 Galaxy 实例，创建并运行一个 OpenMC 中子学模拟工作流，将输出结果通过一系列格式转换工具进行处理，并将最终结果加载到 ParaView 和 NVIDIA Omniverse 中进行可视化。这种容器化部署方式可在满足第 1 节所述硬件要求的任何设备上实现结果的可重复性和可移植性。

系统运行后，工作流程可针对新的输入数据重新运行，而无需手动重新配置；只需少量工作即可将额外的模拟代码封装为新工具；工具可在多个工作流程和应用领域中重复使用。该方法支持可发现、可访问、可互操作、可重用（FAIR）的数据原则：运行历史记录完整地保存了来源元数据；工作流程可导出为可移植文件，并可在 Galaxy 实例之间直接共享；工具则被打包在版本控制的容器中，可发布至公共仓库。通过 Galaxy 的 Pulsar 系统，将本架构扩展至高性能计算（HPC）或云资源是一种自然的延伸。

本方法通过一个聚变中子学案例研究进行演示。使用 OpenMC 在直接加速几何蒙特卡罗（DAGMC）计算机辅助设计（CAD）几何结构中模拟中子输运过程，得到氚增殖比（TBR）结果和中子轨迹数据集。随后将仿真工作流连接至 NVIDIA Omniverse 作为元宇宙平台，用于调用与可视化。

引言

工业元宇宙融合了数字世界与物理世界，以支持工程系统的设计、仿真以及协作式三维可视化。它通常由众多相互连接的组件数字孪生体构成，从而提供整体系统的视图。波音（Boeing）、宝马（BMW）、亚马逊（Amazon）等许多大型组织正在采用多种方法构建元宇宙¹。目前已有系统被开发并投入使用，用于支持多链条的仿真与处理工具。然而，这些实例通常要么针对特定应用领域定制²，要么属于商业解决方案^3,4，存在对专有系统的依赖性。一些用于构建数字孪生体的开源替代方案已被用于创建部分系统，例如具有内置仿真功能的 Python Flask。但这些方案仍被配置为定制化的代码模块，仅执行与特定模型相关的具体任务⁵。在本实验方案的背景下，元宇宙平台（NVIDIA Omniverse）作为三维可视化和工作流交互的前端：在工作流运行完成后，仿真结果将被加载到共享场景中，并可在同一环境中触发新的运行。这与实时数字孪生系统不同，后者通过实时传感器数据流持续更新模型；本文演示的方法支持批量工作流的执行以及运行后对结果的探索。然而，该方法的设计方式为未来研究奠定了基础，可将更多系统集成至元宇宙平台，从而实现以工作流引擎作为计算后端的数字孪生体构建。

工作流程可以被定义为明确指定软件工具之间数据流的工具链。它们允许将现有的模拟代码、处理脚本以及典型分析流程中的其他步骤进行封装，而无需更改这些组件的功能，而是通过标准化的输入和输出对其进行配置和重新配置，且不依赖于具体工具。通过共享工具，工作流程可轻松实现结果的重复验证，同时提供关于所使用工具版本、执行顺序及输入参数的元数据和来源信息。单个工具本身可在多个模拟流程中重复使用，使研究人员能够减少搭建模拟环境的时间，将更多精力投入到实验设计和结果探索中。工作流程系统还具有良好的可扩展性，可通过方法连接不同的本地计算资源、云平台和高性能计算（HPC）资源，从而以自动化方式在特定硬件上运行大量大规模工作流程⁶。

传统的手动方法本质上速度慢、容易出错且难以重复：研究人员需要手动运行每个模拟或后处理工具，将中间文件在不同环境之间移动，并手动记录每次运行的输入和输出。相比之下，工作流管理工具通过一次性明确数据流，并以确定性方式重复执行，从而带来诸多优势：相同的工作流可以针对不同输入完全一致地执行，无需编写专门脚本即可支持参数化研究；每次运行都会自动记录完整的来源元数据，有效解决可重复性问题；此外，一旦工具被封装，其在后续工作流中的复用成本几乎为零，仅需考虑计算时间。Wratten 等人⁷已对生物信息学领域、Perez-Riverol 和 Moreno⁸以及 Verhoeven 等人⁹已对蛋白质组学/代谢组学领域的工作流优势进行了量化研究。

从历史上看，工作流主要在生物信息学领域得到了广泛应用^8,9，并取得了显著成功，例如欧洲 Galaxy 服务器这一大型公共实例^10,11。截至2022年，该服务器已拥有超过5万名用户，集成了2500种工具，执行了超过4700万项任务和26万次工作流运行。相同的底层工作流引擎可通过 Pulsar 分布式任务执行系统^6,11扩展至高性能计算（HPC）和云资源，目前已在欧洲10个国家部署了13个 Pulsar 节点。在众多可用的工作流管理工具中，包括 Snakemake、Nextflow、Toil 和支持 CWL 的引擎，本文选择了 Galaxy 工作流引擎¹¹，原因如下：其一，它具备成熟的基于浏览器的界面，降低了非命令行用户为主的领域专家的使用门槛；其二，它提供了完整的表征状态转移（REST）应用程序编程接口（API），本文利用该接口连接至元宇宙前端；其三，其历史记录与任务模型能够以直观的方式向非专业合作者展示数据来源信息；此外，它还通过前述的 Pulsar 系统支持透明的高性能计算任务卸载（尽管本文的实验方案部分未对此进行讨论）。然而，本文所描述的方法在原则上与具体工作流引擎无关：类似的集成也可基于其他引擎构建。本研究的贡献并非工作流管理器本身，而是将原本为生物信息学开发的通用型工作流管理器迁移应用于其他领域（本文以聚变中子学为具体示例），并将其与工业元宇宙平台（NVIDIA Omniverse）集成，构建于一个完全容器化、可本地部署的技术栈中，用于开展三维虚拟实验。

最后，容器化通过将代码与其运行所需的操作系统及所有依赖项打包在一起，实现了多种软件的共享。这些环境避免了依赖项缺失的问题，也免去了安装某些仿真代码的繁琐过程。容器化在目的上类似于虚拟机，但更加轻量且更具可移植性。它极大地提高了软件包的可共享性和可重复性。在本方法中，工作流管理器和各个工具均在 Docker¹² 容器中运行，只要用户能够运行容器，即可提升在不同操作系统上的兼容性。

本方案适用于特定领域的专家研究人员，例如聚变中子学工程师、计算流体动力学分析人员或有限元实践人员，这些研究人员精通各自领域的仿真工具，但此前未使用过工作流管理器或基于容器的部署方式。假设读者已熟悉单一仿真代码及基本的命令行操作；不要求了解 Galaxy 或 Omniverse。初次接触容器化技术的读者应在进行第1节前，参考官方 Docker 文档（https://docs.docker.com/）或访问以下网址获取入门培训：https://uomresearchit.github.io/docker-introduction/；运行软件所需的基本命令均已包含在本方案中。

本报告其余部分将介绍本地可部署系统的设置与使用方法，随后阐述为该系统开发新工具的步骤，以及将其他外部软件包（例如元宇宙平台）与工作流引擎相连接的方法。在整个报告中，以使用 OpenMC¹³ 进行中子输运模拟作为案例研究。选择 OpenMC 是因为它展示了从 CAD 建模到仿真计算再到结果可视化的完整流程，这正是本工作流架构的设计动机。几何文件和配置文件作为结构化输入；蒙特卡罗中子输运模拟生成一个标量指标（氚增殖比，TBR），可用于与已知取值范围进行比较，同时生成空间分辨的中子轨迹数据集，该数据集可被处理并转换为可在元宇宙应用中进行三维渲染的可视化格式。

方案

注意：本地工作流引擎的设置、工作流构建、工作流启动以及可视化输出的概览见 图 1、图 2、图 3、图 4、图 5、图 6、图 7 和 图 8。运行本方案所需的仓库文件见补充文件 1。

1. 设置

1. 要求
   注意：本方法已在 Ubuntu 最新的长期支持（LTS）版本 22.04.1 LTS 上测试通过。其他版本的 Ubuntu 或其他发行版可能也可运行，但本文未进行测试。该方法同样适用于 Windows 系统，需使用 Windows Subsystem for Linux（WSL）作为 Docker 的后端。
   1. Windows 用户：请下载并设置 WSL，因为这是运行 Docker 的必要条件。
   2. 下载 Docker，然后通过运行以下命令进行验证：
      `docker run hello-world`
      应显示欢迎信息。
   3. 通过 NVIDIA Omniverse 启动器下载 NVIDIA Omniverse 启动器及其中一个 Omniverse 应用。
      注意：NVIDIA Omniverse 的实时光线追踪渲染需要 RTX 级 GPU。没有此类硬件的用户仍可完整运行第 2 节中的工作流程，并在 ParaView 中查看中间生成的 .vtk / .vtp 输出文件（参见讨论部分）。这些用户可跳过第 3 节，因其内容仅涉及元宇宙平台；但本文中用于集成工作流程引擎的方法，若需连接至其他元宇宙平台时仍可能具有参考价值。
      本方案使用 Omniverse Code 应用，但其他 Omniverse 应用在整体上应类似。虽然 ParaView 并非必需，但可用于可视化本协议中工具生成的部分中间文件。
2. 代码仓库
   1. 使用以下命令克隆包含本地工作流程引擎实例及本文所述工具所需全部文件和脚本的代码仓库：
      `git clone https://github.com/williamjsmith15/galaxy-omniverse-example.git`
   2. 将管理员邮箱添加至管理员用户列表。
      注意：这将赋予某些工作流程引擎功能所需的管理员权限，可在 galaxy-config/galaxy.yml 文件的 admin_users 部分找到（参见 https://github.com/williamjsmith15/galaxy-omniverse-example/blob/master/galaxy-config/galaxy.yml）。
   3. 将 default.json.template 文件重命名为 default.json。该文件位于 omni_exts/omni.galaxy.example/omni/galaxy/example/default.json.template。
      注意：重命名后，元宇宙平台的扩展程序即可读取该文件，并可在每次加载之间保存和保留个人设置——在 Galaxy 实例设置完成后，还将对此文件进行更多修改。
3. 启动本地工作流程引擎服务器
   1. 通过运行仓库根目录下的 start-galaxy.sh 文件来启动工作流程引擎实例：
      `./start-galaxy.sh`
      如果该文件无法运行，可能是由于仓库克隆后权限发生变化，需将其设为可执行。可通过运行以下命令实现：
      `chmod a+x start-galaxy.sh`
      注意：Windows 用户必须通过 WSL 终端执行此操作。该命令将下载相关文件并启动工作流程引擎实例，可在同一台机器上的任意浏览器中访问 http://localhost:8080 查看。应显示如图 1所示的页面；若未显示，请稍等并刷新页面——工作流程引擎实例可能需要一定时间启动（尤其是首次启动时）。
      1. 通常情况下，若要在工作流程引擎实例中查看仓库中的更改，请运行 `./restart-galaxy.sh` 或 `./stop-galaxy.sh`，然后重新运行启动脚本。
4. 元宇宙平台配置
   1. 下载启动器和应用后（本示例中为 Omniverse Code），打开该应用。
   2. 在窗口左上角，点击 扩展 选项卡（在其他应用中，该选项位于 窗口 | 扩展 菜单下）。
   3. 在 扩展 窗口中，点击灰色的 设置 按钮；将弹出一个窗口，其中已预设若干目录。点击绿色的 加号 按钮，添加指向 omni_exts 文件夹的新目录，路径格式为：‘<克隆仓库的根目录>/galaxy-omniverse-example/omni_exts’；详见图 2。
   4. 在左侧列的 第三方 选项卡下查找名为“OMNI GALAXY EXAMPLE”的新条目。将该扩展的滑块打开，并等待扩展窗口出现。
   5. 选中自动加载复选框，以便每次启动应用时自动加载该扩展。
      注意：在 Omniverse 支持扩展热重载的前提下，对扩展文件所做的更改在保存后应会自动保留。
5. 工作流程引擎账户创建及与元宇宙平台的连接
   1. 在工作流程引擎实例中，点击顶部工具栏的 登录或注册 按钮，然后点击 立即注册，并使用第 1.2.2 步中添加的邮箱地址填写信息，以创建具有管理员权限的账户。
   2. 生成一个 API 密钥，以便 API 能与工作流程引擎通信。进入顶部工具栏的 用户 下拉菜单 | 偏好设置 | 管理 API 密钥，创建密钥并复制。
   3. 密钥生成后，将其添加到第 1.2.3 步创建的 default.json 文件中的 ‘galaxy_api_key’ 字段的空引号内。
      警告：该文件现在包含一个 API 密钥。此密钥可用于在关联账户上运行任务和访问数据。在本地部署且无公网暴露的域名或 IP 地址的情况下，通常不会构成安全问题；但该文件仍应视为机密，不得共享或提交至公共代码仓库（该文件默认已在 .gitignore 中列出，以防止误提交）。
   4. 重新启动元宇宙平台应用，以刷新 default 文件中的更改。
      注意：API 密钥也可直接在扩展窗口的服务器设置下拉菜单中输入，但该方式不会在会话间持久保留。

2. 在工作流引擎上运行任务

1. 单一工具
   注意：单个工具允许独立运行和检查单独的处理或模拟步骤，这有助于在将工具集成到工作流之前验证输入格式是否正确以及工具是否按预期工作。下文提到的测试文件 dagmc.h5m（DAGMC CAD 几何文件）和 openmc_config.json（模拟配置文件）位于克隆仓库的 test_files 目录中。
   1. 单击以上传所需的输入文件 上传数据 在左侧栏中并选择 选择本地文件 或从文件浏览器拖放至本窗口。上传该 dagmc.h5m （CAD 文件）和 openmc_config.json （配置文件），然后单击 开始 单击按钮以将文件上传至当前历史记录。上传完成后，这两个文件将显示在右侧历史记录面板中的绿色条目中。
   2. 选择 复杂工具 登录页面左侧栏的下拉菜单，然后 OpenMC 中子学模拟 工具
   3. 现在，在工具特定页面上，从步骤 2.1.1 中上传的文件中选择输入，并选择 CAD 文件作为 dagmc.h5m 数据集和配置文件作为 openmc_config.json 数据集
   4. 点击 执行 按钮。两个新文件（TBR 和 Tracks）将出现在 历史 屏幕右侧的面板。运行时变为橙色，成功完成时变为绿色，红色表示工具失败。调试步骤详见第4节。
   5. 氚增殖比（TBR）值可以可视化，以检查测试案例是否已成功运行。点击 TBR 输出以展开，然后在 图表图标，然后在 编辑这将显示TBR结果，其值应约为0.76（这是一种统计方法，此处配置使用较小的样本量以加快模拟速度，因此结果可能有所差异）。
      注意：TBR 值具有随机性；0.76 这一数值可能在 ±0.01 范围内波动，这反映了为实现快速示例工作流程而故意选择的较小粒子数量（5 批，每批 1,000 个粒子）。为减小数值波动范围，可增加粒子数量 批次 和 颗粒 数字在下方的 设置 在重新运行之前，请修改 openmc_config.json 文件中的 field。作为参考，对于本案例中所示的简单几何结构，使用 50 个批次、每个批次 10,000 个粒子，可在延长运行时间的代价下减少后续运行中 TBR 值的波动。
   6. 其他工具可以在 轨迹 工作流程输出以进行结果的后处理。运行该流程 将 h5 轨迹转换为 vtp 工具在 轨迹 输出，然后 CAD h5m 转 vtk 工具在 dagmc.h5m 输入文件。这两种方法都将生成一个输出， tracks_0.vtp 和 dagmc.vtk，将其转换为更易于可视化的格式。
   7. 上一步生成的输出可从实例中下载（通过点击 输出 然后 保存 图标）随后可在 ParaView 中进行可视化¹⁴ 以查看模拟的中子径迹。
   8. 要在 ParaView 中可视化结果，请导入下载的文件 tracks_0.vtp 和 dagmc.vtk 输出。这些将显示在窗口的左侧。可以单击 眼睛图标 除导入的文件外，或位于 应用 属性窗口中点击下方按钮以查看输出结果。该结果应与所见内容相似 图7.
2. 工作流程
   注意：工作流将完整的处理流程编码为一个有向图，其中包含具有明确定义的输入和输出的工具。一旦定义完成，相同的工作流便可针对任意输入文件集重复运行，而无需手动重新配置每个工具，且所有运行历史和来源元数据将自动记录。
   1. 点击 工作流程 在顶部导航栏中，然后 创建 在右上角。输入工作流的名称和描述（任意内容均可），然后点击 创建 再次。
   2. 向工作流程中添加三个工具，展开工具菜单中的相关部分，并添加第2.1节中使用的工具： OpenMC 中子学模拟, CAD h5m 转 vtk 和 将 h5 轨迹转换为 vtp.
   3. 定义工具之间的数据流。通过点击并拖动每个工具顶部的深蓝色栏，在工作区中移动工具。连接 轨迹（h5） 中子学模拟工具的输出结果 tracks.h5 将 h5 到 vtp 工具的输出端口连接至其输入端口。操作方法为：点击输出端口的箭头，并将其拖动至输入端口的箭头处。
   4. 定义工作流级别的输入数据集。在 输入 工具部分，单击 输入数据集 两次以创建两个输入节点。通过点击步骤并修改名称，将其中一个重命名为配置文件，另一个重命名为CAD输入 标记 右侧属性菜单中的字段。
   5. 将配置文件和CAD文件链接到中子学模拟工具的输入端，并将CAD文件链接到h5m转vtk工具，遵循图中的模式 图3.
   6. 使用以下方法保存工作流程 保存图标 在右上角
   7. 要运行工作流程，请点击 工作流程 顶部工具栏中的标签，然后点击 播放图标 根据要运行的工作流程进行操作。然后选择输入，步骤与2.1.2相同，如同运行工具时一样，点击 运行工作流.
   8. 等待工作流程运行完成，然后将输出结果与步骤 2.1.5 和 2.1.8 进行比较；这些结果应非常相似（同样请注意这些步骤中的统计学变异）。当所有输出在 历史 已变为绿色。此处应显示四个数据集（连同输入数据集一起）： TBR, 轨迹, dagmc.vtk，以及 tracks_0.vtp.
   9. 由于工作流已经运行，部分用户可能希望查看该工作流调用（运行）所捕获的来源信息和元数据。可通过导航至 用户 在顶部工具栏 | 工作流调用. 这将显示该用户运行过的所有工作流，点击 向下箭头 在感兴趣的 workflow 上，然后通过点击下载元数据 JSON 文件 下载 BioCompute 对象 按钮。其中包含有关所运行工具/工作流程的来源信息、所用输入等。
      注意：工作流引擎还会记录每次工作流执行的完整运行历史，包括输入文件的校验和、工具版本及参数值。要下载某次运行的溯源记录，请打开 历史 面板，点击菜单（向下箭头右上角的）并选择 导出历史记录到文件导出的存档包含所有数据集以及生成这些数据集的步骤的机器可读记录。
      通过第5.1节中讨论的API，可自动保存由工作流引擎生成的来源或历史记录；但本方案中将不对此进行详细说明。
3. 更复杂的工作流程
   注意：本工作流程通过添加后处理步骤扩展了第2.2节的内容，以生成在元宇宙平台中进行可视化所需的通用场景描述（USD）文件。由于目前没有单一工具能够直接从DAGMC转换为USD格式，.h5m）或 VTK（vtp) 转换为 USD 时，该流程通过两条多步骤转换链路由数据：CAD 几何结构遵循 H5M、STL、OBJ、USD 流程，中子轨迹则遵循 H5、VTP、OBJ、USD 流程。
   1. 按照 2.2 节中所示的工作流程进行操作，以建立工作流程 图4.
   2. 按照第 2.2.4 步的方法定义两个工作流级别的输入，将其命名为 CAD DAGMC 和 配置文件.
   3. 加入 OpenMC 中子学模拟 工具并连接 CAD DAGMC 和 配置文件 将其输入与步骤 2.2.3 中的相应输入对应。
   4. 创建中子学转换链。添加 Tracks h5 转 vtp、vtp 转 obj 以及 obj 转 USD 工具，然后按照下分支的布局，将每一步的输出连接到下一步的输入 图4.
   5. 创建 CAD 转换链。添加 h5m 到 STL、STL 到 OBJ 以及 OBJ 到 USD 工具，然后再次将每个工具的输出连接到 下一个的输入，遵循上部分支的布局 图4.
   6. 保存工作流程，该流程现已可通过第3节中的扩展程序在元宇宙平台中使用。
      注意：这些附加步骤向用户展示了如何共享工作流程和工具，从而确保生成结果所用数据和方法的可重复性与可访问性。
   7. 通过导航到将工作流导出为便携式文件 工作流程 在顶部工具栏中，点击菜单（向下箭头），并选择 下载工作流程管理器会保存一个 .ga JSON 文件，然后可由任何在工作流引擎实例上使用相同工具的人员共享和使用。可通过以下方式导入 工作流程 在顶部工具栏中 | 导入.
   8. 通过提交共享工具 galaxy-tools/ 将克隆的仓库文件夹上传至公共版本控制托管平台。请合作者克隆该仓库，以获取所有容器化的工具，并以与发布者本地设备相同的方式运行这些工具。
      注意：可以配置公共工作流管理器实例，从而避免在本地部署之间手动共享工作流和工具文件。在这些实例中，所有用户均可访问工具，且工作流和操作历史可对所有其他用户公开。此内容不在本实验方案的范围之内，但有关获得永久性部署的更多信息，可参见官方 Galaxy 培训网络：https://training.galaxyproject.org/training-material/topics/admin/tutorials/ansible-galaxy/tutorial.html 或者，可以将代码仓库中提供的 Docker Compose 堆栈直接部署到服务器上，然后通过代理或其他类似方式路由，以使其公开可访问。

3. 从元宇宙平台运行工作流程

1. 启动工作流
   1. 在元宇宙平台扩展窗口中，点击 获取工作流（标注 2，图 5）。下拉菜单将显示与存储在 default.json 中的 API 密钥关联的工作流引擎账户上所有可用的工作流。如果未出现相应内容，请检查 API 密钥是否已正确保存至 JSON 文件中，并重新启动元宇宙平台应用程序以确保其读取到该密钥。
   2. 从列表中选择 Complex 工作流，然后点击 获取 输入（标注 4，图 5）。工作流中定义的输入字段（步骤 2.3.2）将显示出来，且名称应保持一致。
   3. 对于每个基于文件的输入，点击 选择文件，并通过弹出的文件浏览器选择对应的本地文件：CAD DAGMC 输入选择 dagmc.h5m 文件，配置文件 输入选择 openmc_config.json 文件。
   4. 点击 启动工作流（标注 6，图 5）。启动确认信息将显示在 信息 区域（标注 7）。工作流完成后，系统将显示额外消息，确认输出文件已保存且运行已结束。
      注意：可通过访问工作流引擎的网页界面 http://localhost:8080 并导航至 管理员 | 任务 来监控工作流任务的进度。需要管理员权限（参见步骤 1.2.2）。
2. 可视化结果
   注意：每次工作流运行完成后，系统会自动将输出文件从工作流引擎下载到本地输出目录。保存路径由扩展程序的 default.json 文件中的 output_dir 键控制。每次运行的结果均存储在一个带时间戳的文件夹中，因此可通过扩展程序区分不同输出。若在元宇宙平台中可视化出现问题，可直接访问这些文件夹中的文件进行手动查看，以判断问题是否出在工作流引擎。
   1. 在元宇宙平台中展开 文件管理器 区域（标注 1，图 6），然后点击 刷新（标注 2）。这将获取已保存至本地目录的已完成工作流运行列表。
   2. 在 文件夹 下拉菜单（标注 3，图 6）中选择当前工作流运行的文件夹（确认当前仅存在一个文件夹），然后再次点击 刷新，以在 文件 下拉菜单中加载该次运行的输出文件。
   3. 从 文件 下拉菜单（标注 4，图 6）中选择一个文件（目前仅支持 .usd、.txt、.json 和 .out 文件），然后点击 拉取文件（标注 5）。基于文本的文件将在 信息 面板中显示，USD 文件将被添加到当前场景中，并应在主视口中进行可视化。
   4. 为使导入的几何体与 Omniverse 的坐标约定对齐，请打开右侧的 Stage 面板，选中两个导入的工作流对象，然后在下方的 属性 面板中将 旋转 X 设置为 −90°。此操作可修正 USD 导出工具使用的 z 轴向上约定与 Omniverse 使用的 y 轴向上约定之间的不匹配。请将此旋转应用于 CAD USD 和 tracks USD 文件；对齐后的预期视口状态如 图 8 所示。
   5. 最后，为增强各部件之间的对比度，可分配材质。具体操作为：打开应用程序底部的 材质 选项卡，选择一种材质，然后将其拖拽并释放到右侧列的 Stage 视图中的几何体上。对两个导入的几何体均执行此操作，以增强它们之间的视觉对比度。

4. 添加新工具

注意：本节介绍创建和部署新工作流工具的开发流程。需要访问存储库的文件系统，以及对工作流引擎的管理员权限以进行调试。仅需运行现有工具和工作流或创建工作流的用户，无需遵循本节内容。

1. 通用流程
   1. 在封装之前，独立于工作流引擎开发并测试模拟或处理脚本。工具封装器调用一个已存在的可运行脚本，在开发工具时实现新逻辑并不推荐。
   2. 通过创建包含脚本所需所有运行时依赖项（库、二进制文件、数据文件等）的 Docker 镜像，为脚本准备执行环境。
      注意：本协议中的所有示例工具均使用 Docker 容器作为执行环境。工作流引擎也支持 Conda 环境，但此处未作演示。有关 Docker 的更多信息，请参阅官方文档，或在此处找到一个良好的入门课程：https://uomresearchit.github.io/docker-introduction/ 。
   3. 创建一个 XML 工具定义文件，声明执行环境（本例中为 Docker）、调用脚本的命令，以及工具的输入、输出和元数据，以便在工作流引擎界面中显示。
   4. 封装创建完成后，将 XML 文件及任何脚本放入仓库中的新文件夹 galaxy-tools/<tool_name>/。在 galaxy-tools/tool_conf.xml 中的适当 <section> 标签内为该工具添加新条目，指向新创建的 XML 文件的相对路径。
      注意：请确保文件名完全复制正确，因为这是部署新工具时常见的错误。如果 tool_conf.xml 条目包含错误路径或 XML 文件存在语法错误，工作流引擎实例将无法启动。要检查工作流容器日志中的错误信息，请从仓库根目录运行以下命令：
      `docker compose logs galaxy`
      XML 解析错误会以如下形式显示：ERROR loading tool <path>: <reason>，通常会指出问题文件名和行号。
   5. 通过从仓库根目录运行重启脚本 ./restart-galaxy.sh，重新部署工作流引擎以加载新工具。
   6. 确认工具已正确注册。访问 http://localhost:8080，在 工具 面板中找到该工具并点击，确保所有输入按预期显示。如果工具缺失，请参考上述说明进行调试；若仍有错误，请检查工具 XML 文件本身的语法，因为这也可能导致部署失败。
   7. 像之前一样运行新工具，但使用先前已测试过的输入。输出应在 历史记录 面板中变为绿色。
   8. 如果工具运行失败，作为管理员，请点击失败（红色）输出，并点击 信息 图标。这将显示详细输出页面，并展示 stdout 和 stderr 输出流。可展开这些内容以获取更多调试信息。
2. 简单工具
   注意：工具 1–5 展示了逐步复杂的封装模式。每个工具的 XML 文件及任何脚本均位于仓库对应的 galaxy-tools/simple/<N>/ 子目录中。请按照步骤 4.1.4–4.1.5 和第 2.1 节部署并运行每个工具。
   工具 1 — 运行简单命令
   1. 查看 galaxy-tools/simple/1/1.xml 文件。requirements 元素指定了 Linux 执行环境。command 元素包含要运行的 echo 命令。
   2. 从工作流引擎界面运行工具 1，无需输入文件。由于未定义输出文件，作为管理员，请导航至 管理、作业 页面，然后点击 信息 图标以查看 stdout 和 stderr 输出流，其内容与步骤 4.1.8 相同。stdout 输出流应仅包含 XML 文件中命令生成的“hello world”字符串。
      工具 2 — 使用基于文本的输入
   3. 查看 galaxy-tools/simple/2/2.xml 文件。现在 input 字段中有一个条目，包含一个 type=”text” 的 param 元素，且 command 部分现在通过名称标签引用输入变量。
   4. 像之前一样运行工具 2；这次为工具提供一个字符串输入。用户可输入任意内容。按步骤 4.2.2 查看输出，stdout 输出应为用户在工具输入中提供的字符串。
      工具 3 — 使用基于文件的输入
   5. 再次查看工具文件；现在输入参数使用 type=”data” 标签而非字符串输入，从而允许使用文件。在 command 部分中，该文件通过文件路径引用，仍使用输入参数的名称。
   6. 使用本地文本编辑器创建一个 .txt 文件，或运行以下命令：
      `echo “hello world from a file” > test_files/input.txt`
      从仓库根目录生成示例输入。
   7. 按步骤 2.1.1 上传创建的 .txt 文件，然后像之前一样运行工具 3，选择上传的 .txt 文件作为输入。同样以相同方式查看 stdout，.txt 文件的内容应在此处显示。若使用上述命令，输出应为“hello world from a file”。
      工具 4 — 将输出写入文件
   8. 查看 galaxy-tools/simple/4/4.xml。现在 outputs 部分声明了一个命名输出文件，可在 command 部分中引用。
   9. 像之前一样使用 .txt 输入运行该工具，但现在无需以管理员身份查看输出，普通用户可在 历史记录 面板中看到输出。成功运行后，该输出将变为绿色，并可按之前章节所述在工作流引擎中下载或查看。
      工具 5 — 在工具中运行脚本
   10. 查看 galaxy-tools/simple/5/5.xml 及其配套的 Python 脚本 galaxy-tools/simple/5/5.py。在 XML 文件中，command 引用了工具目录中的 Python 脚本，且 requirements 部分现在引用了一个 Python 镜像，因为运行脚本需要 Python。
   11. 以相同方式部署并运行该工具，其行为应与工具 4（步骤 4.2.9）相同，只是此次运行的是脚本而非直接执行命令。
3. 复杂工具示例
   注意：本节以中子学工具的开发为例，详细说明第 4.1 节所述模式的实际应用。相关文件位于 galaxy-tools/complex/openmc/。该模式可推广至任何模拟或处理代码。
   1. 为模拟开发运行脚本。本示例中，运行脚本 galaxy-tools/complex/openmc/openmc_run.py 解析配置文件（openmc_config.json），生成中子学设置文件，并执行模拟。在将其打包进 Docker 镜像前，请先从命令行直接测试该脚本。
   2. 使用位于 galaxy-tools/complex/openmc/Dockerfile 的 Dockerfile 构建 Docker 执行环境。该文件基于公共镜像并添加了少量额外包。可在本地构建并打标签，或从容器注册表引用。
   3. 创建 XML 封装器 galaxy-tools/complex/openmc/openmc.xml，在 requirements 部分声明步骤 4.3.2 中的 Docker 镜像。同时应定义运行命令以及输入和输出文件（如第 4.2 节示例所示）。
   4. 按照步骤 4.1.4–4.1.7 部署该工具，然后使用第 2 节中的测试输入确保工具正常运行。
      注意：实例中其余工具（Tracks h5 to vtp、CAD h5m to vtk、h5m to stl、stl to obj、vtp to obj、obj to USD）均为遵循相同开发模式的文件格式转换器。其 XML 文件位于 galaxy-tools/complex/ 目录中，可作为进一步的参考示例。

5. 将工作流程连接到元宇宙

注意：本节提供描述工作流引擎 API 集成及元宇宙平台扩展架构的开发者参考材料。仅需从元宇宙平台运行工作流的用户应遵循第 3 节，无需阅读本节。希望将不同前端应用连接至工作流引擎的开发者应从第 5.1 节开始阅读。

1. 工作流引擎 API
   注意：Galaxy 提供了 RESTful API。Bioblend Python 库为此 API 提供了更高层次的封装，是本实验方案中所有辅助脚本的基础。Bioblend 已在仓库提供的相关 Docker 执行环境中自动安装。
   1. 导入 Bioblend 并通过使用第 1.5.2 步中的服务器地址和 API 密钥实例化 GalaxyInstance 对象，建立与正在运行的工作流引擎的连接。在已安装 Bioblend 的 Python 环境中：
      `from bioblend.galaxy import GalaxyInstance
      gi = GalaxyInstance(url=’http://localhost:8080’, key=<api_key>)`
      注意：此操作仅适用于本地部署；如果工作流引擎部署在远程机器上，请将 localhost 替换为已配置实例的地址和端口。
   2. 使用 galaxy-api/helper_functs.py 中的辅助函数执行常见操作：列出可用工作流（get_workflows）、获取工作流输入定义（get_inputs）以及使用指定输入文件启动工作流（launch_workflow）。有关函数签名和预期返回类型，请参考该文件中的内联文档字符串。
   3. 根据应用需求，在 helper_functs.py 中扩展其他函数。完整的 API 参考文档可在 https://bioblend.readthedocs.io 查阅。
2. 将工作流链接至元宇宙
   注意：本节仅描述元宇宙平台扩展的架构，以便开发者可根据不同的工作流输出、新增文件类型或替代元宇宙平台进行适配。
   1. 打开 omni_exts/omni.galaxy.example/ 中的主要扩展入口点。该扩展以 Omniverse 基础扩展¹⁵ 为起点，随后集成了第 5.1.2 步所述的辅助函数 API Python 文件中的全部功能，并提供图形用户界面以与工作流交互。
   2. 当工作流启动后，其生成的数据会自动从工作流引擎下载并存储在本地，从而可在元宇宙平台中进行可视化。此机制还可保存工作流运行期间生成的元数据并使其可访问，从而提供仿真数据的来源信息。
   3. 该实现使用 Omniverse 原生的 omni.ui 库构建界面。主扩展位于扩展文件夹中，界面的主要实现位于 omni_exts/omni.galaxy.example/omni/galaxy/example/window.py 文件中。

结果

如果使用 Git 仓库中提供的输入参数运行模拟，则应获得以下结果：

成功完成步骤 2.1.3 后，TBR 和 Tracks 输出数据集均会以绿色显示在 History 面板中，表示运行成功。使用提供的配置文件（5 批次，每批次 1,000 个粒子）得到的典型 TBR 值约为 0.76，不同运行之间的波动范围约为 ±0.01。因此，若获得的 TBR 值在 0.74–0.78 范围内，均可视为成功。该较宽的范围反映了蒙特卡洛中子学模拟的随机性；当前配置为提高运行速度而有意采用了较少的粒子数量。若增加中子数量（当前为 5 批次，每批次 1,000 个粒子），则不同运行之间的 TBR 值将更加一致。参见步骤 2.1.5 后的说明，以修改中子学工具输入文件中的设置，从而减小结果的离散程度，但计算成本将相应增加。如果在此 History 面板中出现红色数据集，请通过第 4.1 节所述的 Admin, Jobs 步骤（需要管理员...

讨论

在本方案中存在几个关键步骤，主要涉及工作流引擎实例的初始设置，例如：添加管理员邮箱（方案步骤 1.2.2），因为这是访问工具和任务面板管理功能所必需的；正确生成用于元宇宙平台扩展的 API 密钥（方案步骤 1.5.3），并将其正确粘贴到默认值文件中；在添加工具时，需确保这些工具在重启前已添加至工具配置文件（方案步骤 4.1.6），因为这些工具在启动时加载，此处的错误在工作流日志中可能并不明显。由于在方案步骤 1.5.3 之后，default.json 文件中包含 API 密钥，因此该文件应视为机密。请确认其已包含在 .gitignore 文件中（默认已包含），切勿提交至任何公开代码仓库。如果工作流引擎的登录页面在首次访问时未在 http://localhost:8080 显示，可能仅需几分钟时间以拉取并运行容器镜像，后续启动速度将显著加快。若工具未显示，可能是工具未添加至工具配置文件，请检查该文件，并确认工具 XML 文件的格式正确。随后重启服务；工作流日志在报告此类错误时有时信息较少，而重启是最常见的解决方法。与元宇宙平台扩展相关的任何问题，几乎都源于使用了错误的 API 密钥，或本地工作流引擎实例...

材料

本文使用的材料清单

姓名	公司	目录编号	评论
Bioblend	Galaxy 项目	v1.2+	提供围绕 Galaxy REST API 的高级封装的 Python 库。在 Omniverse 扩展辅助脚本中用于列出工作流、获取输入定义并启动任务。该库会自动安装在相关 Docker 镜像中，无需在主机上单独安装。
Docker 容器	Docker	v24.0.5	容器化运行时，用于将每个仿真和后处理工具及其所有依赖项打包，确保可移植性和可重复性。
Galaxy	Galaxy 项目	v22.05	开源工作流引擎，用于编排串联的仿真和处理工具，并通过 REST API 暴露功能。
Git	Git SCM	v2+	需要使用 Git 克隆代码仓库以跟随本实验方案操作
NVIDIA RTX GPU	NVIDIA	-	用于在 Omniverse 中实现实时光线追踪渲染（第 3 节）。无 RTX 硬件的用户可完成至第 2 节的所有步骤，并使用 ParaView 进行可视化（见讨论部分）。
Omniverse	NVIDIA	Code 2022.3.3	NVIDIA 的协作式 3D 平台。通过自定义 Kit 扩展，用作工作流输出的可视化与交互前端。
ParaView	Kitware	v5.11	开源科学可视化应用程序，作为无 RTX 硬件时的备选方案，用于检查中间输出文件（.vtk/.vtp 格式）。
实验方案代码仓库	自定义	v1.0	包含 Galaxy 配置文件、所有工具 XML 封装器、运行脚本、Dockerfile、测试数据以及 Omniverse 扩展。在步骤 1.2.1 中进行克隆。关键文件也作为直接补充材料上传（见 I.2）。
Python	Python	v3.10+	OpenMC 运行脚本和 Omniverse 扩展辅助脚本所需的运行环境。已包含在相关 Docker 镜像中或随 Omniverse 下载包提供，无需在主机上单独安装。
OpenMC 蒙特卡罗程序	OpenMC	v0.13.3	开源的蒙特卡罗粒子输运代码，本研究中用于聚变中子学仿真。提供氚增殖比（TBR）和中子轨迹输出结果。
适用于 Linux 的 Windows 子系统（WSL）	Microsoft	v2	在 Windows 主机上运行 Docker 所必需（通过 PowerShell 执行 `wsl --install` 命令安装）。Linux 和 Mac 用户无需此组件。