Integrating Automated Simulation Workflows with 3D Visualization for Virtual Experiments in the Metaverse

Summary

A generalized, FAIR-compliant method is presented for domain-expert researchers seeking to integrate simulation and data-processing tools into automated workflows for 3D virtual experiments. A neutronics example demonstrates setting up a local Galaxy instance, wrapping OpenMC and file-conversion tools, launching workflows from Omniverse, and visualizing the converted 3D outputs.

Abstract

In many virtual experiments, multiple software packages are used with varied simulation types, pre- and post-processing tools, and tools to visualize the experiments' results—often a combination of all. The typical method of integrating these is a manual one, with bespoke solutions created for each application area, which scales poorly and impedes sharing and reproducibility.

This protocol demonstrates the deployment and use of a locally containerized workflow system. Following it, users will launch a local Galaxy instance using Docker, create and run an OpenMC neutronics simulation workflow, pass the outputs through a chain of format-conversion tools, and load the results into both ParaView and NVIDIA Omniverse for visualization. The containerized deployment promotes reproducibility and portability on any machine meeting the hardware requirements described in Section 1.

Once the system is running, workflows can be re-run against new inputs without manual reconfiguration, additional simulation codes can be wrapped as new tools with modest effort, and tools can be used in multiple workflows and application areas. The approach supports the findable, accessible, interoperable, reusable (FAIR) data principles: run histories capture full provenance metadata, workflows are exportable as portable files and can be shared directly between Galaxy instances, and tools are packaged in version-controlled containers that can be published in a public repository. Scalability to high-performance computing (HPC) or cloud resources via Galaxy's Pulsar system is a natural extension of the architecture described here.

The method is demonstrated through a fusion neutronics case study. OpenMC is used to simulate neutron transport in a Direct Accelerated Geometry Monte Carlo (DAGMC) computer-aided design (CAD) geometry, producing a tritium breeding ratio (TBR) result and a neutron-track dataset. The simulation workflows are then connected to the NVIDIA Omniverse as the metaverse platform for invocation and visualization.

Introduction

The industrial metaverse combines digital and physical worlds to support design, simulation, and collaborative 3D visualization of engineered systems. It would typically consist of many interconnected digital twins of components to give an overall system view. Large organizations such as Boeing, BMW, Amazon, and many more are taking multiple approaches to create metaverses¹. Systems for allowing multiple chains of simulation and processing tools have been developed and are being used. However, these examples are typically either bespoke to the application area² or are commercial options^3,4 with some lock-in to proprietary systems. Some open-source alternatives for building digital twins have been used to create some systems, such as Python Flask, with built-in simulation capabilities. Still, these are configured as bespoke pieces of code to carry out specific tasks relating to the particular model⁵. In the context of this protocol, the metaverse platform (NVIDIA Omniverse) functions as a 3D visualization and workflow interaction front-end: simulation outputs are loaded into a shared scene after a workflow run completes, and new runs can be triggered from within the same environment. This differs from live digital-twin systems in which real-time sensor feeds update the model continuously; the method demonstrated here supports batch workflow execution and post-run exploration of results. However, this is done in such a way that would support future work to integrate more systems into the metaverse platform to enable the creation of digital twins with workflow engines as the computational backend.

Workflows can be defined as chains of software tools explicitly specifying the data flow between them. They allow wrapping of existing simulation codes, processing scripts, and other steps in a typical analysis pipeline, without altering the function of these, but instead allowing them to be configured and reconfigured with standardized inputs and outputs that are tool agnostic. Workflows allow easy replication of results via the sharing of tools, also providing metadata and provenance about what versions of tools were used, in what order, and with which inputs. Tools themselves can be reused in many simulation pipelines, allowing researchers to spend less time setting up simulations and more time designing experiments and exploring the results. Workflow systems are also scalable, with methods to connect to different local compute, cloud and HPC resources, enabling many large-scale workflows to be run on specific hardware in an automated manner⁶.

The typical manual approach is inherently slow, error-prone, and difficult to reproduce, in which a researcher runs each simulation or post-processing tool by hand, moves intermediate files between environments, and has to document individual run inputs and outputs. In contrast to this, a workflow manager formalizes the data flow once and re-runs it deterministically. This brings many benefits relative to manual pipelines: the same workflow can be executed identically on different inputs, supporting parameter studies without bespoke scripting; every run automatically captures full provenance metadata, addressing any reproducibility gap; and once a tool has been wrapped, its reuse cost in subsequent workflows drops to near zero, other than compute time. These benefits have been quantified for bioinformatics by Wratten et al.⁷ and for proteomics/metabolomics by Perez-Riverol and Moreno⁸ and Verhoeven et al.⁹.

Historically, workflows have been used primarily in the bioinformatics field^8,9 to great success with large public instances such as the European Galaxy server^10,11, which by 2022 hosted more than 50,000 users, 2500 tools, executed over 47 million jobs and 260,000 workflow runs. The same workflow engine stack supports scaling onto HPC and cloud resources via the Pulsar distributed job-execution system^6,11, with operational deployments spanning 13 Pulsar endpoints across 10 European countries. Among the many available workflow managers, including Snakemake, Nextflow, Toil, and CWL-compatible engines, the Galaxy workflow engine¹¹ was selected for a few reasons. One of the primary reasons is its mature browser-based interface which lowers the barrier to entry for domain experts who do not work primarily on the command line; it exposes a complete representational state transfer (REST) application programming interface (API) (used in the present work to bridge to the metaverse front-end); its history and jobs model captures provenance in a form that is straightforward to surface to non-specialist collaborators; and it supports transparent HPC offload via the aforementioned Pulsar system (although this is not discussed in the protocol section in this paper). The approach described in this paper, however, is workflow-engine-agnostic in principle: equivalent integrations could be built atop alternative engines. The contribution of this work is not the workflow manager itself but the translation of a general-purpose workflow manager originally developed for bioinformatics to other fields (with the specific example of fusion neutronics here), and its integration with an industrial-metaverse platform (NVIDIA Omniverse), inside a fully containerized, locally deployable stack, applied to 3D virtual experiments.

Finally, containerization enables the sharing of many pieces of software by packaging code with the operating system and all the dependencies it needs to run. These environments avoid the issues of missing dependencies and the hassle of installing some simulation codes. They are similar in purpose to virtual machines but much lighter and more portable. They drastically increase the shareability and reproducibility of software packages. In this method, the workflow manager and the individual tools run in Docker¹² containers, increasing compatibility with different operating systems as long as the user can run containers.

This protocol is intended for domain-expert researchers, for example, fusion neutronics engineers, computational fluid-dynamics analysts, or finite-element practitioners, who are fluent in the simulation tools of their own field but have not previously used a workflow manager or container-based deployment. Familiarity with a single simulation code and basic command-line operation is assumed; familiarity with Galaxy or the Omniverse is not. Readers new to containerization should consult the official Docker documentation (https://docs.docker.com/) or introductory training available at: https://uomresearchit.github.io/docker-introduction/ before following Section 1; the basic commands needed to run the software are all contained within the protocol.

The rest of this report will cover the setup and use of the locally deployable system. Then, it will follow steps for developing new tools for the system and a method for linking other external packages to the workflow engine, such as a metaverse platform. Throughout the report, a neutronics simulation using OpenMC¹³ serves as the case study. OpenMC was selected because it demonstrates the full CAD-to-simulation-to-output-visualization pipeline that motivates the workflow architecture. A geometry file and a configuration file serve as structured inputs; the Monte Carlo neutron transport simulation produces a scalar metric (the tritium breeding ratio, TBR) that can be compared to a known range of values, and a spatially resolved neutron-track dataset that can be processed and presented in a visualizable format for the 3D rendering in the metaverse application.

Protocol

NOTE: An overview of the local workflow engine setup, workflow construction, workflow launch, and visualization outputs is shown in Figure 1, Figure 2, Figure 3, Figure 4, Figure 5, Figure 6, Figure 7, and Figure 8. The repository files required to run the protocol are provided in Supplemental File 1.

1. Setup

1. Requirements
   NOTE: This method has been tested on the latest Long Term Support (LTS) version of Ubuntu, 22.04.1 LTS. Other versions of Ubuntu and other distros may work, but they have not been tested here. It also works on Windows systems, utilizing Windows Subsystem for Linux (WSL) as the Docker backend.
   1. Windows Users: Download WSL and set it up, as it is a requirement for Docker.
   2. Download Docker and then verify by running:
      `docker run hello-world`
      which should display a welcome message.
   3. Download the NVIDIA Omniverse launcher and one of the Omniverse apps via the launcher.
      NOTE: NVIDIA Omniverse’s real-time ray-traced rendering requires an RTX-class GPU. Users without this hardware can still run the full workflow through Section 2 and inspect the intermediate .vtk / .vtp outputs in ParaView (see Discussion). These users can skip Section 3, as this pertains only to the metaverse platform; the methods used to integrate the workflow engine here may be useful if connecting to other metaverse platforms.
      This protocol uses the app Omniverse Code, but the other Omniverse apps should be broadly similar. While not essential, ParaView can be used to visualize some of the intermediate files produced by the tools in this protocol.
2. Repository
   1. Clone the repository housing all the files and scripts needed for the local workflow engine instance and the tools described in this paper with:
      `git clone https://github.com/williamjsmith15/galaxy-omniverse-example.git`
   2. Add an admin email to the admin users list.
      NOTE: This will give admin privileges needed for some workflow engine features and can be found under the admin_users section in the galaxy-config/galaxy.yml file (see https://github.com/williamjsmith15/galaxy-omniverse-example/blob/master/galaxy-config/galaxy.yml).
   3. Rename the default.json.template file to default.json. This file is located at omni_exts/omni.galaxy.example/omni/galaxy/example/default.json.template.
      NOTE: This will allow it to be read by the metaverse platform’s extension and for personal settings to be added and persisted between loads—more changes to this will be made after setting up the galaxy instance.
3. Launching Local Workflow Engine Server
   1. Launch the workflow engine instance by running the start-galaxy.sh file in the top level of the repository:
      `./start-galaxy.sh`
      If the file does not run here, it may need to be made executable if the permissions have changed in the repository clone. This may be done by running:
      `chmod a+x start-galaxy.sh`
      NOTE: Windows users must do this through their WSL terminal. This will download the relevant files and launch the workflow engine instance, which can be viewed at http://localhost:8080 in any browser running on the same machine. This should display the page shown in Figure 1; if not, wait and refresh—the workflow engine instance may take some time to launch (especially the first time).
      1. Generally, to see the changes made in the repository on the workflow engine instance, run `./restart-galaxy.sh` or `./stop-galaxy.sh`, then start the script again.
4. Metaverse platform configuration
   1. Open the app after downloading the launcher and app (for this example, Omniverse Code).
   2. In the top left of the window, click the Extensions tab (in other apps, this will be under Window | Extensions).
   3. In the extensions window, click the grey settings button; it will bring up a window with a few already populated directories. Add another one that points to the omni_exts folder by clicking the green plus button and add a path that will have the format: ‘<root of cloned repo>/galaxy-omniverse-example/omni_exts’; see Figure 2 for more details.
   4. Look for a new entry called ‘OMNI GALAXY EXAMPLE’ in the left-hand column under the THIRD PARTY tab. Switch the slider on this extension to on, and wait for the extension window to appear.
   5. Select the autoload checkbox to load the extension automatically each time the app is launched.
      NOTE: Changes made in the extension files should be automatically persisted when the file is saved as Omniverse allows hot reloading of extensions
5. Workflow engine account creation and link to the Metaverse
   1. On the workflow engine instance, create an account by clicking the Login or Register button on the top bar, then Register Here, and then fill in the details using the email address added in Step 1.2.2 to create an account with admin access.
   2. Generate an API key to allow the API to talk to the workflow engine. Go to the User dropdown in the top bar | Preferences | Manage API Key. Create a key and copy it.
   3. Once the key has been generated, add this to the default.json file created in Step 1.2.3 under the ‘galaxy_api_key’ field in the empty quotation marks.
      CAUTION: This file will now hold an API key. This API key can be used to run jobs and access data on the associated account. It should not be an issue in a local deployment where there is no public-facing domain or IP address; this file should still be treated as secret and therefore not shared or committed to a public repository (the file is listed by default in the .gitignore to combat this).
   4. Relaunch the metaverse platform app to refresh the changes made in the default file.
      NOTE: The API key can also be added directly into the extension window under the server settings dropdown, although this will not persist between sessions.

2. Running jobs on the Workflow Engine

1. Single tools
   NOTE: Single tools allow individual processing or simulation steps to be run and inspected in isolation, which is useful for verifying that inputs are correctly formatted and that a tool is working as expected before incorporating it into a workflow. The test files referenced below, dagmc.h5m (the DAGMC CAD geometry) and openmc_config.json (the simulation configuration), are in the test_files directory of the cloned repository.
   1. Upload the required input files by clicking Upload Data in the left column and either select Choose local files or drag and drop from a file explorer into this window. Upload the dagmc.h5m (CAD file) and openmc_config.json (configuration file), and then click the Start button to upload to the current history. Both files will appear in green in the History panel on the right when the upload is complete.
   2. Select the Complex Tools dropdown on the left column of the landing page and then the OpenMC Neutronics Simulation tool.
   3. Now on the tool specific page, select the inputs from the files that were uploaded in Step 2.1.1 and select the CAD file as the dagmc.h5m dataset and the config file as the openmc_config.json dataset.
   4. Click the Execute button. Two new files (TBR and Tracks) will appear in the History panel on the right of the screen. They will turn orange when running and green when complete and successful, red would indicate a tool failure. See Section 4 for debugging steps.
   5. The TBR (tritium breeding ratio) value can be visualized to check that the test case has been run successfully. Click on the TBR output to expand, then on the graph icon, and then on the editor. This will bring up the TBR result, which should be around 0.76 (this is a statistical method, and the configuration here uses a small sample size for simulation speed, so results will vary).
      NOTE: The TBR value is stochastic; the 0.76 value may vary by ±0.01 and this reflects a deliberately small particle count (5 batches of 1,000 particles) chosen for quick example workflows. To reduce the range in values, increase the batches and particles numbers under the settings field in the openmc_config.json file before re-running. As a guideline for a simple geometry such as the case presented here, 50 batches of 10,000 particles should reduce the scatter of TBR values in subsequent runs at the cost of longer run time.
   6. Other tools can be run on the Tracks output of the workflow to post-process the results. Run the Tracks h5 to vtp tool on the Tracks output and then the CAD h5m to vtk tool on the dagmc.h5m input file. These will both produce one output, tracks_0.vtp and dagmc.vtk, that converts them into a more easily visualizable format.
   7. The outputs produced in the previous step can be downloaded from the instance (by clicking on the output and then the save icon) and then can be visualized in ParaView¹⁴ to see the simulated neutron tracks.
   8. To visualize the results in ParaView, import the downloaded tracks_0.vtp and dagmc.vtk outputs. These will appear on the left-hand side of the window. Either click on the Eye Icon beside the imported files, or on the Apply button below in the properties window to visualize the output. This should be similar to that seen in Figure 7.
2. Workflows
   NOTE: A workflow encodes a complete processing pipeline as a directed graph of tools with declared inputs and outputs. Once defined, the same workflow can be rerun against any set of input files without manually reconfiguring each tool, and all run history and provenance metadata are captured automatically.
   1. Click Workflow in the top navigation bar, then Create in the top right. Enter a name and description for the workflow (anything will do), then click Create again.
   2. Add three tools to the workflow, expand the relevant sections in the Tools menu and add the tools used in section 2.1: OpenMC Neutronics Simulation, CAD h5m to vtk and Tracks h5 to vtp.
   3. Define the data flow between the tools. Drag the tools around the workspace by clicking and dragging the dark blue top bar of each of them. Connect the Tracks (h5) output of the neutronics simulation tool to the tracks.h5 input of the h5 to vtp tool. Do this by clicking and dragging from the arrow on the output to the arrow on the input.
   4. Define the workflow-level input datasets. In the Inputs section of the tools, click on Input Dataset twice to create two input nodes. Rename one for the configuration file and the other for the CAD input by clicking on the step and then changing the Label field on the right-hand properties menu.
   5. Link the configuration file and the CAD file to the inputs on the neutronics simulation tool, and the CAD file to the h5m to vtk tool, following the pattern in Figure 3.
   6. Save the workflow using the save icon in the top right.
   7. To run the workflow, click on the Workflow tab in the top bar as before, then click on the play icon on the workflow to be run. Then select the inputs as with Step 2.1.2, the same as if running a tool, and click Run Workflow.
   8. Wait for the workflow to run, and then the outputs can be compared to steps 2.1.5 and 2.1.8; these should be very similar (again, note the statistical variation from these steps). The workflow has run successfully when all outputs in the History have turned green. There should be (along with the input datasets) four datasets present here: TBR, Tracks, dagmc.vtk, and tracks_0.vtp.
   9. As the workflow has been run, some users may want to be able to see the provenance and metadata captured of the workflow invocation (run). This can be achieved by navigating to User on the top bar | Workflow Invocations. This results in the list of all workflows run by the user, click on the downwards arrow on the workflow of interest and then can download the metadata JSON file by clicking on the Download BioCompute Object button. This contains provenance about the tools/workflows ran, inputs used, etc.
      NOTE: The workflow engine also records a complete run history for every workflow execution, including input file checksums, tool versions, and parameter values. To download the provenance record for a run, open the History panel, click the menu (downwards arrow) at the top right, and select Export History to File. The exported archive contains all datasets and a machine-readable record of the steps that produced them.
      The saving of provenance or histories generated by the workflow engine can be automated via the API discussed in Section 5.1; however, it will not be detailed in this protocol.
3. More complex workflow
   NOTE: This workflow extends Section 2.2 by adding post-processing steps that produce Universal Scene Description (USD) files required for visualization in the metaverse platform. Because no single tool converts directly from DAGMC (.h5m) or VTK (vtp) to USD, the pipeline routes data through two multi-step conversion chains: the CAD geometry follows a H5M, STL, OBJ, USD pipeline, and the neutron tracks follow H5, VTP, OBJ, USD.
   1. Follow the steps to set up a workflow, as shown in section 2.2, following the workflow shown in Figure 4.
   2. Define the two workflow-level inputs as in Step 2.2.4, naming them CAD DAGMC and Config File.
   3. Add the OpenMC Neutronics Simulation tool and connect the CAD DAGMC and Config File inputs to its corresponding inputs as in Step 2.2.3.
   4. Create the neutronics conversion chain. Add the Tracks h5 to vtp, vtp to obj, and obj to USD tools and then connect the outputs of each to inputs of the next, following the layout in the lower branch of Figure 4.
   5. Create the CAD conversion chain. Add the h5m to STL, STL to OBJ, and OBJ to USD tools, and then again connect the outputs of each to the inputs of the next, following the layout in the upper branch of Figure 4.
   6. Save the workflow, which is now ready for use in the metaverse platform via the extension in Section 3.
      NOTE: These additional steps show users how workflows and tools might be shared, enabling reproducibility and accessibility to the data and methods used to generate results.
   7. Export the workflow as a portable file by navigating to Workflow in the top bar, clicking the menu (downwards arrow), and selecting Download. The workflow manager saves a .ga JSON file, which can then be shared and used by anyone with the same tools on their workflow engine instance. This can be imported via Workflow in the top bar | Import.
   8. Share tools by committing the galaxy-tools/ folder of the cloned repository to a public version control host. Ask collaborators to clone this to get access to all the containerized tools, running them in the same manner as on the publisher’s local device.
      NOTE: Public workflow manager instances can be configured, which circumvents the manual sharing of workflow and tool files between local deployments. In these instances, tools are accessible to all users, and workflows and histories can be made public to all other users. This is outside the scope of this protocol, but more information can be found in the official Galaxy Training network on getting a permanent deployment: https://training.galaxyproject.org/training-material/topics/admin/tutorials/ansible-galaxy/tutorial.html or the docker compose stack given in the repository can be deployed as is on a server and then routed via a proxy or similar means to make it publicly accessible.

3. Running a workflow from the metaverse platform

1. Launching the Workflow
   1. In the metaverse platform extension window, click Get Workflows (annotation 2, Figure 5). A dropdown will populate with all workflows available on the workflow engine account associated with the API key stored in default.json. If this is not the case, check that the API key has been saved correctly in the JSON file, and re-launch the metaverse platform app to ensure it picks up the key.
   2. Select the Complex Workflow for the list and then click Get Inputs (annotation 4, Figure 5). The input fields defined in the workflow (Step 2.3.2) will appear and should be named the same.
   3. For each file-based input, click Select File and use the file explorer pop-up to select the corresponding local file: dagmc.h5m for the CAD DAGMC input and openmc_config.json for the Config File input.
   4. Click Launch Workflow (annotation 6, Figure 5). A launch confirmation message will be displayed in the Info section (annotation 7). After the workflow is completed, additional messages will confirm that output files have been saved and that the run has finished.
      NOTE: Workflow job progress can be monitored on the workflow engine’s web interface at http://localhost:8080 by navigating to Admin | Jobs. Administrator access is required (see Step 1.2.2).
2. Visualizing the results
   NOTE: On completion of each workflow run, the system automatically downloads the output files from the workflow engine to a local output directory. The save path is controlled by the output_dir key in the extension’s default.json file. Each run is stored in a timestamped folder, so outputs can be distinguished by the extension. If there are issues in visualization in the metaverse platform, the files can be accessed in these folders and viewed manually to see if the issue lies with the workflow engine.
   1. In the metaverse platform, expand the File Manager section (annotation 1, Figure 6) and click Refresh (annotation 2). This retrieves the list of the completed workflow runs saved to the local directory.
   2. In the Folders dropdown (annotation 3, Figure 6), select the folder for the current workflow run (confirm that this is the only one there currently) and click Refresh again to populate the Files dropdown with outputs from that run.
   3. Select a file from Files dropdown (annotation 4, Figure 6; only .usd, .txt, .json and .out files are supported currently) and then click Pull File (annotation 5). Text-based files are displayed in the Info panel, USD files are added to the current scene, and should be visualized in the main viewport.
   4. To align the imported geometry with Omniverse's coordinate convention, open the Stage panel on the right-hand side, select both imported workflow objects, and in the Property panel just below this, set Rotate X to −90°. This corrects the mismatch between the z-up convention used by the USD export tools and Omniverse's y-up convention. Apply this rotation to both the CAD USD and the tracks USD file; the expected viewport state after alignment is shown in Figure 8.
   5. Finally, to get more contrast between the parts, materials can be assigned. This is achieved by opening the Materials tab at the bottom of the app, selecting a material, and then dragging and dropping onto the geometry in the Stage view in the right-hand column. Do this for both imported geometries to increase the contrast between them.

4. Adding new tools

NOTE: This section describes the developer process for creating and deploying new workflow tools. It requires access to the filesystem of the repository, and admin access to the workflow engine for debugging. Users who only need to run existing tools and workflows, or create workflows, do not need to follow this section.

1. General process
   1. Develop and test the simulation or processing script independently of the workflow engine before wrapping it. The tools wrapper calls an existing working script, implementing new logic while developing a tool is not recommended.
   2. Prepare the execution environment for the script by creating a Docker image that includes all runtime dependencies (libraries, binaries, data files, etc.) required by the script.
      NOTE: All example tools in this protocol use Docker containers as the execution environment. Conda environments are also supported by the workflow engine but are not demonstrated here. Further information on Docker can be found via the official documentation, or a good introductory course can be found here: https://uomresearchit.github.io/docker-introduction/ .
   3. Create an XML tool definition file that declares the execution environment (Docker in this case), the command to invoke the script, and the tools' inputs, outputs, and metadata for display in the workflow engine’s interface.
   4. Once the wrapper has been created, place the XML and any scripts in a new folder galaxy-tools/<tool_name>/ in the repository. Add a new entry for the tool in galaxy-tools/tool_conf.xml under the appropriate <section> tags, pointing to the relative file path of the newly created XML file.
      NOTE: Ensure this file name is copied exactly, as this is a common error when trying to deploy new tools. If the tool_conf.xml entry contains an incorrect path or the XML file has a syntax error, the workflow engine instance will fail to start. To inspect the workflow container logs for error messages, run the following from the repository root:
      `docker compose logs galaxy`
      XML parse errors appear as lines of the form ERROR loading tool <path>: <reason> and typically identify the filename and line number of the problem.
   5. Redeploy the workflow engine to load the new tool by running the restart script from the repo root: ./restart-galaxy.sh.
   6. Confirm the tool has been registered correctly. Navigate to http://localhost:8080, locate the tool in the Tools panel and click the tool to ensure all the inputs appear as expected. If the tool is absent follow the above note for debugging, and if there are still errors, check the syntax of the tool XML itself as this can also cause deployment errors.
   7. Run the new tool as before, but with inputs that have been tested previously. Outputs should turn green in the History panel
   8. If tools fail, then as an admin, click on the failed (red) output and click on the Info icon. This shows a detailed output page and displays the stdout and stderr streams. These can be expanded for further information on debugging the tool.
2. Simple tools
   NOTE: Tools 1–5 illustrate progressively more complex wrapping patterns. The XML file and any scripts for each tool are in the corresponding galaxy-tools/simple/<N>/ subdirectory of the repository. Deploy and run each tool following Steps 4.1.4–4.1.5 and Section 2.1.
   Tool 1 – Running a simple command
   1. Look at the galaxy-tools/simple/1/1.xml file. The requirements element specifies a Linux execution environment. The command element contains the echo command to run.
   2. Run Tool 1 from the workflow engine interface with no input files required. As there are also no output files defined, as an Admin, navigate to the Admin, Jobs page and then click the Information icon to see the stdout and stderr streams, which is the same as in Step 4.1.8. The stdout stream should contain only the ‘hello world’ string from the command in the XML file.
      Tool 2 – Using text-based input
   3. Look at the galaxy-tools/simple/2/2.xml file. There is now an entry in the input field, with a param element of type=”text” and the command section now references the input variable by the name tag.
   4. Run Tool 2 as before; this time, give the tool an input of a string. This can be anything the user wishes. View the output as in Step 4.2.2, and the stdout output should be the string the user provided in the tool input.
      Tool 3 – Using a file-based input
   5. Again, look at the tool file; now, rather than a string input, the input parameter uses a type=”data” tag, which allows the use of a file. This is referenced in the command section as a file path, again using the name of the input parameter.
   6. Create a .txt file using a local text editor, if not run:
      `echo “hello world from a file” > test_files/input.txt`
      from the repository root folder to generate the example input.
   7. Upload the created .txt file as in Step 2.1.1 and then run Tool 3 as before, selecting the uploaded .txt file as the input. Again, view the stdout in the same way, and the content of the .txt file should be displayed there. If using the above command, the output should be “hello world from a file”.
      Tool 4 – Writing output to a file
   8. Examine galaxy-tools/simple/4/4.xml. An outputs section now declares a named output file that can be referenced in the command section.
   9. Run the tool as before with the .txt input, but now rather than viewing the output as admin, this can be seen by the regular user in this History panel, and on a successful run, this will turn green and be able to be downloaded / viewed in the workflow engine as detailed in previous sections.
      Tool 5 – Running scripts in tools
   10. Examine galaxy-tools/simple/5/5.xml and the accompanying python script galaxy-tools/simple/5/5.py. In the XML, the command references the Python script from the tool directory, and the requirements section now references a Python image as Python is needed to run the script.
   11. Deploy and run the tool in the same way, and it should behave in the same way as Tool 4 (Step 4.2.9) except this time it runs a script rather than the command directly.
3. Complex tool example
   NOTE: This section documents the development of the neutronics tool as a worked example of the pattern described in Section 4.1. The relevant files are in galaxy-tools/complex/openmc/. The same pattern generalizes to any simulation or processing code.
   1. Develop the run script for the simulation. For this example, the run script galaxy-tools/complex/openmc/openmc_run.py parses a config file (openmc_config.json), writes the neutronics settings file, and executes the simulation. Test the script directly from the command line before packaging it in a Docker image.
   2. Build the Docker execution environment using the Dockerfile at galaxy-tools/complex/openmc/Dockerfile. This extends the public image with a few extra packages. Build and tag locally or reference it from a container registry.
   3. Create the XML wrapper galaxy-tools/complex/openmc/openmc.xml, declaring the Docker image from Step 4.3.2 in the requirements section. The command to run along with the input and output files (as in the example in Section 4.2) should also be defined.
   4. Deploy the tool as in Steps 4.1.4-4.1.7 and then use the test inputs used in Section 2 to ensure the tool is operating correctly.
      NOTE: The remaining tools in the instance (Tracks h5 to vtp, CAD h5m to vtk, h5m to stl, stl to obj, vtp to obj, obj to USD) are file-format converters following the same development pattern. Their XML files are in the galaxy-tools/complex/ directory and can serve as further reference examples.

5. Connecting workflows to the Metaverse

NOTE: This section provides developer reference material describing the workflow engine’s API integration and the architecture of the metaverse platform extension. Users who only need to run workflows from the metaverse platform should follow Section 3 and do not need to read this section. Developers wishing to connect a different front-end application to the workflow engine should start from Section 5.1.

1. Workflow Engine API
   NOTE: Galaxy exposes a RESTful API. The Bioblend Python library provides a higher-level wrapper around this API and is the basis for all helper scripts used in this protocol. Bioblend is installed automatically within the relevant Docker execution environments provided in the repository.
   1. Import Bioblend and establish a connection to the running workflow engine by instantiating a GalaxyInstance object with the server address and API key from Step 1.5.2. In Python in an environment with Bioblend installed:
      `from bioblend.galaxy import GalaxyInstance
      gi = GalaxyInstance(url=’http://localhost:8080’, key=<api_key>)`
      NOTE: This will only work for local deployments, if the workflow engine is deployed on a remote machine, replace the localhost with the address and port of the configured instance.
   2. Use the helper functions in galaxy-api/helper_functs.py to perform common operations: listing available workflows (get_workflows), retrieving workflow input definitions (get_inputs), and launching a workflow with specified input files (launch_workflow). Refer to the inline docstrings in that file for function signatures and expected return types.
   3. Extend the helper_functs.py with other functions as required by application. The full reference API can be found at https://bioblend.readthedocs.io.
2. Linking workflows to the metaverse
   NOTE: This section only describes the architecture of the metaverse platform extension so developers can adapt it for different workflow outputs, additional file types, or alternative metaverse platforms.
   1. Open the main extension entry point in omni_exts/omni.galaxy.example/. This extension uses the Omniverse base extension¹⁵ as a starting point. It then adds all the functionality from the helper functions API Python file described in step 5.1.2 and gives a GUI to interact with the workflows.
   2. When workflows are launched, the data they produce is automatically downloaded from the workflow engine and stored locally, allowing them to be visualized in the metaverse platform. This also allows the metadata generated during the workflow run to be saved and made accessible, thereby providing the provenance of the simulation data.
   3. This implementation uses the Omniverse native omni.ui library to build the interface. The main extension is in the extension folder, and the primary implementation of the interface is in the omni_exts/omni.galaxy.example/omni/galaxy/example/window.py file.

Results

If the simulations are run with the provided inputs in the git repository, the following results should be obtained:

On successful completion of Step 2.1.3, both the TBR and Tracks output datasets will appear in the History panel in green, indicating a successful run. A representative TBR value using the supplied configuration file (5 batches of 1,000 particles) is approximately 0.76, with variations between runs of approximately ±0.01. Theref...

Discussion

There are a few critical steps within the protocol. Most concern the initial setup of the workflow engine instance such as: adding the admin email (protocol step 1.2.2) as this is required for admin access to the tools and jobs panels; generating the API key correctly for the metaverse platform extension (protocol step 1.5.3) and pasting this correctly into the default values file; and when adding tools, ensuring that these are added to the tool config file (protocol step 4.1.6) before restarting as these are loaded in a...

Materials

List of materials used in this article

Name	Company	Catalog Number	Comments
Bioblend	Galaxy Project	v1.2+	Python library providing a high-level wrapper around the Galaxy REST API. This is used in the Omniverse extension helper scripts to list workflows, retrieve input definitions, and launch jobs. Installed automatically within the relevant Docker images; no host installation required.
Docker Containers	Docker	v24.0.5	Containerization runtime used to package each simulation and post-processing tool with all its dependencies, ensuring portability and reproducibility.
Galaxy	Galaxy Project	v22.05	Open-source workflow engine used to orchestrate the chained simulation and processing tools and to expose them via a REST API.
Git	Git SCM	v2+	Required to clone the repository to follow along with the protocol
NVIDIA RTX GPU	NVIDIA	-	Required for real-time ray-traced rendering in Omniverse (Section 3). Users without RTX hardware can complete all steps through Section 2 and use ParaView for visualisation (see Discussion).
Omniverse	NVIDIA	Code 2022.3.3	NVIDIA's collaborative 3D platform. This is used as the visualization and interaction front-end for workflow outputs via a custom Kit extension.
ParaView	Kitware	v5.11	Open-source scientific visualization application used as a non-RTX fallback for inspecting intermediate .vtk/.vtp outputs.
Protocol Repository	Custom	v1.0	Contains Galaxy configuration along with all tool XML wrappers, run scripts, Dockerfiles, test data, and the Omniverse extension. Cloned in Step 1.2.1. Key files are also provided as direct supplementary uploads (see I.2).
Python	Python	v3.10+	Runtime required for the OpenMC run script and the Omniverse extension helper scripts. Included within the relevant Docker images or with Omniverse download; no separate host installation is required.
The OpenMC Monte Carlo Code	OpenMC	v0.13.3	Open-source Monte Carlo particle-transport code used here for fusion neutronics simulation. This provides the tritium breeding ratio (TBR) and neutron-track outputs.
Windows Subsystem for Linux (WSL)	Microsoft	v2	Required to run Docker on Windows hosts (install via `wsl --install` in powershell). Linux and Mac users do not need this.