Integrazione di flussi di lavoro di simulazione automatizzati con visualizzazione 3D per esperimenti virtuali nel Metaverso

Sommario

Un metodo generalizzato e conforme a FAIR è presentato per ricercatori esperti di dominio che desiderano integrare strumenti di simulazione e elaborazione dati in flussi di lavoro automatizzati per esperimenti virtuali 3D. Un esempio di neutronica dimostra come configurare un'istanza Galaxy locale, incapsulare OpenMC e strumenti di conversione file, avviare flussi di lavoro da Omniverse e visualizzare gli output 3D convertiti.

Abstract

In molti esperimenti virtuali vengono utilizzati più pacchetti software con diversi tipi di simulazione, strumenti di pre- e post-elaborazione e strumenti per visualizzare i risultati degli esperimenti—spesso una combinazione di tutti. Il metodo tipico per integrare questi è manuale, con soluzioni su misura create per ogni area applicativa, il che scala male e ostacola la condivisione e la riproducibilità.

Questo protocollo dimostra la distribuzione e l'utilizzo di un sistema di workflow containerizzato localmente. Successivamente, gli utenti avvieranno un'istanza Galaxy locale usando Docker, creeranno ed eseguiranno un flusso di lavoro di simulazione neutronica OpenMC, trasmetteranno gli output attraverso una catena di strumenti di conversione di formato e caricheranno i risultati sia in ParaView che in NVIDIA Omniverse per la visualizzazione. La distribuzione containerizzata promuove la riproducibilità e la portabilità su qualsiasi macchina che soddisfi i requisiti hardware descritti nella Sezione 1.

Una volta che il sistema è in funzione, i flussi di lavoro possono essere rieseguiti su nuovi input senza riconfigurazione manuale, codici di simulazione aggiuntivi possono essere incapsulati come nuovi strumenti con modesto sforzo, e gli strumenti possono essere utilizzati in più flussi di lavoro e aree applicative. L'approccio supporta i principi di dati FAIR, trovabili, accessibili, interoperabili e riutilizzabili: le storie delle esecuzioni catturano tutti i metadati di provenienza, i flussi di lavoro sono esportabili come file portatili e condivideti direttamente tra istanze Galaxy, e gli strumenti sono confezionati in contenitori controllati dalla versione che possono essere pubblicati in un repository pubblico. La scalabilità verso calcolo ad alte prestazioni (HPC) o risorse cloud tramite il sistema Pulsar di Galaxy è un'estensione naturale dell'architettura descritta qui.

Il metodo è dimostrato attraverso uno studio di caso sulla neutronica a fusione. OpenMC viene utilizzato per simulare il trasporto neutronico in una geometria CAD, progettazione assistita da computer (CAD) per geometria Direct Accelerated Geometry Monte Carlo (DAGMC), che produce un risultato del rapporto di riproduzione al trizio (TBR) e un dataset di tracce neutroniche. I flussi di lavoro di simulazione sono poi collegati a NVIDIA Omniverse come piattaforma metaverso per invocazioni e visualizzazioni.

Introduzione

Il metaverso industriale combina mondi digitali e fisici per supportare la progettazione, la simulazione e la visualizzazione collaborativa 3D di sistemi ingegnerizzati. Tipicamente consisteva in molti gemelli digitali interconnessi di componenti per offrire una visione complessiva del sistema. Grandi organizzazioni come Boeing, BMW, Amazon e molte altre stanno adottando diversi approcci per creare^{metaversi 1}. Sono stati sviluppati e vengono utilizzati sistemi per consentire più catene di strumenti di simulazione e elaborazione. Tuttavia, questi esempi sono tipicamente o su misura per l'area^{applicativa 2} oppure sono opzioni^{commerciali 3,4} con qualche bloccaggio a sistemi proprietari. Alcune alternative open source per costruire gemelli digitali sono state utilizzate per creare alcuni sistemi, come Python Flask, con capacità di simulazione integrate. Tuttavia, questi sono configurati come pezzi di codice su misura per svolgere compiti specifici relativi al particolare modello⁵. Nel contesto di questo protocollo, la piattaforma metaverse (NVIDIA Omniverse) funziona come un front-end di visualizzazione 3D e interazione di workflow: gli output delle simulazioni vengono caricati in una scena condivisa dopo il completamento di una run di workflow, e nuove esecuzioni possono essere attivate dallo stesso ambiente. Questo differisce dai sistemi digitali in tempo reale in cui i sensori in tempo reale aggiornano continuamente il modello; Il metodo qui dimostrato supporta l'esecuzione del flusso di lavoro batch e l'esplorazione post-esecuzione dei risultati. Tuttavia, ciò viene fatto in modo da supportare futuri lavori per integrare più sistemi nella piattaforma metaverso, permettendo la creazione di digital twin con motori di workflow come backend computazionale.

I flussi di lavoro possono essere definiti come catene di strumenti software che specificano esplicitamente il flusso di dati tra di essi. Consentono l'incapsulamento di codici di simulazione esistenti, script di elaborazione e altri passaggi in una pipeline di analisi tipica, senza alterarne la funzione, ma permettendo invece di configurarli e riconfigurarli con input e output standardizzati che non identificano gli strumenti. I flussi di lavoro permettono una facile replica dei risultati tramite la condivisione degli strumenti, fornendo anche metadati e la provenienza delle versioni degli strumenti utilizzate, in quale ordine e con quali input. Gli strumenti stessi possono essere riutilizzati in molte pipeline di simulazione, permettendo ai ricercatori di dedicare meno tempo a impostare simulazioni e più tempo a progettare esperimenti ed esplorare i risultati. I sistemi di workflow sono anch'essi scalabili, con metodi per connettersi a diverse risorse di calcolo locale, cloud e HPC, permettendo di eseguire molti workflow su larga scala su hardware specifico in modo^{automatizzato 6}.

L'approccio manuale tipico è intrinsecamente lento, soggetto a errori e difficile da riprodurre, in cui un ricercatore esegue manualmente ogni strumento di simulazione o post-elaborazione, sposta file intermedi tra ambienti e deve documentare singole run input e output. Al contrario, un workflow manager formalizza il flusso di dati una volta e lo riesegue in modo deterministico. Questo porta molti vantaggi rispetto alle pipeline manuali: lo stesso flusso di lavoro può essere eseguito identico su input diversi, supportando studi di parametri senza scripting su misura; ogni esecuzione cattura automaticamente tutti i metadati di provenienza, colmando eventuali lacune di riproducibilità; E una volta che uno strumento è stato completato, il suo costo di riutilizzo nei flussi di lavoro successivi scende quasi a zero, a parte il tempo di calcolo. Questi benefici sono stati quantificati per la bioinformatica da Wratten et ^al.7 e per la proteomica/metabolomica da Perez-Riverol e^Moreno8 e Verhoeven et ^al.9.

Storicamente, i flussi di lavoro sono stati utilizzati principalmente nel campo della bioinformatica ^8,9 con grande successo con grandi istanze pubbliche come il server europeo^{Galaxy 10,11}, che entro il 2022 ospitava più di 50.000 utenti, 2.500 strumenti, eseguiva oltre 47 milioni di lavori e 260.000 esecuzioni di workflow. Lo stesso stack di motori di workflow supporta la scalabilità su risorse HPC e cloud tramite il sistema distribuito di esecuzione di job^{Pulsar 6,11}, con implementazioni operative che coprono 13 endpoint Pulsar in 10 paesi europei. Tra i numerosi gestori di workflow disponibili, tra cui Snakemake, Nextflow, Toil e motori compatibili con CWL, il Galaxy workflow^{engine 11} è stato selezionato per diversi motivi. Una delle ragioni principali è la sua interfaccia matura basata su browser, che abbassa la barriera d'ingresso per gli esperti di dominio che non lavorano principalmente a riga di comando; espone un'interfaccia completa di programmazione applicativa (API) per trasferimento di stato rappresentativo (REST) (utilizzata nel presente lavoro per collegare il front-end del metaverso); Il suo modello di storia e di lavoro cattura la provenienza in una forma che è facile da far emergere ai collaboratori non specialisti; e supporta un offload HPC trasparente tramite il già citato sistema Pulsar (anche se questo non viene discusso nella sezione protocollo di questo articolo). L'approccio descritto in questo articolo, tuttavia, è in linea di principio indipendente dal motore di workflow: integrazioni equivalenti potrebbero essere costruite sopra motori alternativi. Il contributo di questo lavoro non è il workflow manager in sé, ma la traduzione di un workflow manager generico originariamente sviluppato per la bioinformatica in altri campi (con l'esempio specifico della fusione neurotronica qui), e la sua integrazione con una piattaforma industriale-metaverse (NVIDIA Omniverse), all'interno di uno stack completamente containerizzato e distribuibile localmente, applicato a esperimenti virtuali 3D.

Infine, la containerizzazione consente la condivisione di molti software impacchettando il codice con il sistema operativo e tutte le dipendenze necessarie per essere eseguito. Questi ambienti evitano i problemi di dipendenze mancanti e la snervatura di installare alcuni codici di simulazione. Sono simili nello scopo delle macchine virtuali ma molto più leggere e portatili. Aumentano drasticamente la condivisione e la riproducibilità dei pacchetti software. In questo metodo, il workflow manager e i singoli strumenti girano in container Docker¹² , aumentando la compatibilità con diversi sistemi operativi purché l'utente possa eseguire container.

Questo protocollo è pensato per ricercatori esperti di dominio, ad esempio ingegneri di neutronia della fusione, analisti di fluidodinamica computazionale o operatori di elementi finiti, che sono fluenti negli strumenti di simulazione del loro campo ma non hanno precedentemente utilizzato un workflow manager o una distribuzione basata su container. Si presume familiarità con un singolo codice di simulazione e con l'operazione di base in riga di comando; la familiarità con Galaxy o l'Omniverso non lo è. I lettori nuovi alla containerizzazione dovrebbero consultare la documentazione ufficiale Docker (https://docs.docker.com/) o la formazione introduttiva disponibile a: https://uomresearchit.github.io/docker-introduction/ prima di seguire la Sezione 1; i comandi di base necessari per eseguire il software sono tutti contenuti nel protocollo.

Il resto di questo rapporto coprirà l'installazione e l'uso del sistema localmente distribuibile. Successivamente, seguirà i passaggi per sviluppare nuovi strumenti per il sistema e un metodo per collegare altri pacchetti esterni al motore di workflow, come una piattaforma metaverso. In tutto il rapporto, una simulazione neutrica con OpenMC¹³ funge da caso di studio. OpenMC è stato scelto perché dimostra l'intera pipeline CAD-simulazione-visualizzazione dell'output che motiva l'architettura del workflow. Un file di geometria e un file di configurazione fungono da input strutturati; la simulazione del trasporto neutronico di Monte Carlo produce una metrica scalare (il rapporto di riproduzione del trizio, TBR) che può essere confrontata con un intervallo noto di valori, e un dataset di tracce neutroniche risolto spazialmente che può essere elaborato e presentato in un formato visualizzabile per il rendering 3D nell'applicazione metaverso.

Protocollo

NOTA: Una panoramica della configurazione locale del motore di workflow, della costruzione, del lancio del workflow e dei risultati della visualizzazione è mostrata nella Figura 1, Figura 2, Figura 3, Figura 4, Figura 5, Figura 6, Figura 7 e Figura 8. I file repository necessari per eseguire il protocollo sono forniti nel File Supplementare 1.

1. Configurazione

1. Requisiti
   NOTA: Questo metodo è stato testato sull'ultima versione di Supporto a Lungo Termine (LTS) di Ubuntu, 22.04.1 LTS. Altre versioni di Ubuntu e altre distribuzioni potrebbero funzionare, ma qui non sono state testate. Funziona anche su sistemi Windows, utilizzando Windows Subsystem for Linux (WSL) come backend Docker.
   1. Utenti Windows: Scaricate WSL e configuratelo, poiché è un requisito per Docker.
   2. Scarica Docker e poi verifica eseguendo:
      `Hello-world gestito da Docker'
      che dovrebbe mostrare un messaggio di benvenuto.
   3. Scarica il launcher NVIDIA Omniverse e una delle app Omniverse tramite il launcher.
      NOTA: Il rendering in tempo reale con ray tracing di NVIDIA Omniverse richiede una GPU di classe RTX. Gli utenti senza questo hardware possono comunque eseguire l'intero flusso di lavoro attraverso la Sezione 2 e ispezionare gli output intermedi .vtk / .vtp in ParaView (vedi Discussione). Questi utenti possono saltare la Sezione 3, poiché questa riguarda solo la piattaforma metaverso; I metodi utilizzati per integrare il motore di workflow qui possono essere utili se si connette ad altre piattaforme metaverse.
      Questo protocollo utilizza l'app Omniverse Code, ma le altre app Omniverse dovrebbero essere in linea di massima simili. Sebbene non sia essenziale, ParaView può essere utilizzato per visualizzare alcuni dei file intermedi prodotti dagli strumenti di questo protocollo.
2. Repository
   1. Clona il repository che contiene tutti i file e gli script necessari per l'istanza locale del motore di workflow e gli strumenti descritti in questo articolo con:
      'Fai https://github.com/williamjsmith15/galaxy-omniverse-example.git'
   2. Aggiungi un'email amministrativa all'elenco degli utenti amministratori.
      NOTA: Questo fornirà i privilegi amministrativi necessari per alcune funzionalità del motore di workflow e si può trovare nella sezione admin_users nel file galaxy-config/galaxy.yml (vedi https://github.com/williamjsmith15/galaxy-omniverse-example/blob/master/galaxy-config/galaxy.yml).
   3. Rinomina il file default.json.template in default.json. Questo file si trova su omni_exts/omni.galaxy.example/omni/galaxy/example/default.json.template.
      NOTA: Questo permetterà che venga letto dall'estensione della piattaforma metaverso e che le impostazioni personali vengano aggiunte e persistite tra un caricamento e l'altro—ulteriori modifiche saranno apportate dopo aver configurato l'istanza galattica.
3. Lancio del Local Workflow Engine Server
   1. Avvia l'istanza del motore di workflow eseguendo il file start-galaxy.sh nel livello superiore del repository:
      './start-galaxy.sh'
      Se il file non viene eseguito qui, potrebbe dover essere reso eseguibile se i permessi sono cambiati nel clone del repository. Questo può essere fatto eseguendo:
      'chmod a+x start-galaxy.sh'
      NOTA: Gli utenti Windows devono farlo tramite il loro terminale WSL. Questo scaricherà i file rilevanti e avvierà l'istanza del motore di workflow, che può essere visualizzata http://localhost:8080 in qualsiasi browser che giri sulla stessa macchina. Questa dovrebbe mostrare la pagina mostrata nella Figura 1; Se no, aspetta e aggiorna—l'istanza del motore di workflow potrebbe richiedere un po' di tempo per avviarsi (soprattutto la prima volta).
      1. Generalmente, per vedere le modifiche apportate nel repository sull'istanza del motore di workflow, esegui './restart-galaxy.sh' o './stop-galaxy.sh', poi riavvia lo script.
4. Configurazione della piattaforma metaverso
   1. Apri l'app dopo aver scaricato il launcher e l'app (per questo esempio, Omniverse Code).
   2. In alto a sinistra della finestra, clicca sulla scheda Estensioni (in altre app, questa sarà sotto Finestra | Estensioni).
   3. Nella finestra delle estensioni , clicca sul pulsante grigio delle impostazioni ; Aprirà una finestra con alcune directory già popolate. Aggiungi un altro percorso che punta alla cartella omni_exts cliccando sul pulsante verde plus e aggiungi un percorso che avrà il formato: '/galassia-omniverse-esempio/omni_exts'; vedi la Figura 2 per maggiori dettagli.
   4. Cerca una nuova voce chiamata 'OMNI GALAXY EXAMPLE' nella colonna a sinistra sotto la scheda THIRD PARTY . Imposta il cursore di questa estensione su su acceso e aspetta che appaia la finestra di estensione.
   5. Seleziona la casella di spunta autoload per caricare automaticamente l'estensione ogni volta che l'app viene avviata.
      NOTA: Le modifiche apportate ai file di estensione dovrebbero essere automaticamente mantenute quando il file viene salvato, poiché Omniverse consente il ricaricamento a caldo delle estensioni
5. Creazione di account nel motore di workflow e collegamento al Metaverso
   1. Nell'istanza del motore di workflow, crea un account cliccando sul pulsante Login o Registrati nella barra superiore, poi Registrati qui, e infine compila i dati usando l'indirizzo email aggiunto nel Passo 1.2.2 per creare un account con accesso amministratore.
   2. Genera una chiave API che permetta all'API di comunicare con il motore di workflow. Vai al menu a tendina Utente nella barra in alto | Preferenze | Gestisci la chiave API. Crea una chiave e copiala.
   3. Una volta generata la chiave, aggiungila al file default.json creato nello Step 1.2.3 sotto il campo 'galaxy_api_key' tra virgolette vuote.
      ATTENZIONE: Questo file ora conterrà una chiave API. Questa chiave API può essere utilizzata per eseguire i job e accedere ai dati sull'account associato. Non dovrebbe essere un problema in una distribuzione locale dove non esiste un dominio pubblico o un indirizzo IP; Questo file dovrebbe comunque essere considerato segreto e quindi non condiviso o inviato in un repository pubblico (il file è elencato di default nel .gitignore per contrastare questo problema).
   4. Riavvia l'app della piattaforma metaverso per aggiornare le modifiche apportate nel file predefinito.
      NOTA: La chiave API può anche essere aggiunta direttamente nella finestra di estensione sotto il menu a tendina delle impostazioni del server, anche se questa non persisterà tra una sessione e l'altra.

2. Esecuzione di lavori sul motore di workflow

1. Utensili singoli
   NOTA: Gli strumenti singoli permettono di eseguire e ispezionare singoli passaggi di elaborazione o simulazione in isolamento, il che è utile per verificare che gli input siano correttamente formattati e che uno strumento funzioni come previsto prima di incorporarlo in un workflow. I file di test riferiti di seguito, dagmc.h5m (la geometria CAD DAGMC) e openmc_config.json (la configurazione di simulazione), si trovano nella cartella test_files del repository clonato.
   1. Carica i file di input richiesti cliccando su Carica dati nella colonna a sinistra e seleziona Scegli file locali oppure trascina e rilasci da una esplora file in questa finestra. Carica il dagmc.h5m (file CAD) e openmc_config.json (file di configurazione), poi clicca sul pulsante Start per caricare la cronologia attuale. Entrambi i file appariranno in verde nel pannello Storia a destra quando il caricamento sarà completato.
   2. Seleziona il menu a tendina Strumenti Complessi nella colonna sinistra della landing page e poi lo strumento OpenMC Neutronics Simulation .
   3. Ora, nella pagina specifica dello strumento, seleziona gli input dai file caricati nello Step 2.1.1 e seleziona il file CAD come dataset dagmc.h5m e il file di configurazione come dataset openmc_config.json .
   4. Clicca sul pulsante Esegui. Due nuovi file (TBR e Tracce) appariranno nel pannello Cronologia a destra dello schermo. Diventeranno arancioni quando sono in esecuzione e verdi quando completati e con successo, il rosso indicherebbe un guasto dello strumento. Vedi la Sezione 4 per i passaggi di debug.
   5. Il valore TBR (rapporto di riproduzione del trizio) può essere visualizzato per verificare che il caso di prova sia stato eseguito con successo. Clicca sull'output TBR per espandere, poi sull'icona del grafico e infine sull'editor. Questo porterà il risultato TBR, che dovrebbe essere intorno a 0,76 (questo è un metodo statistico, e la configurazione qui utilizza un campione piccolo per la velocità di simulazione, quindi i risultati varieranno).
      NOTA: Il valore TBR è stocastico; Il valore di 0,76 può variare di ±0,01 e questo riflette un conteggio deliberatamente piccolo di particelle (5 lotti da 1.000 particelle) scelto per flussi di lavoro rapidi di esempio. Per ridurre l'intervallo di valori, aumenta il numero di lotti e particelle nel campo impostazioni nel file openmc_config.json prima di riavviare. Come linea guida per una geometria semplice come il caso presentato qui, 50 lotti da 10.000 particelle dovrebbero ridurre la dispersione dei valori TBR nelle esecuzioni successive a scapito di una durata di esecuzione più lunga.
   6. Altri strumenti possono essere eseguiti sull'output Tracks del workflow per post-elaborare i risultati. Esegui lo strumento Tracks h5 a vtp sull'output Tracks e poi lo strumento CAD h5m a vtk sul file di input dagmc.h5m . Entrambe produrranno un unico output, tracks_0.vtp e dagmc.vtk, che le converte in un formato più facilmente visualizzabile.
   7. Gli output prodotti nel passaggio precedente possono essere scaricati dall'istanza (cliccando sull'output e poi sull'icona di salvataggio) e poi visualizzabili in ParaView¹⁴ per vedere le tracce di neutroni simulate.
   8. Per visualizzare i risultati in ParaView, importa gli output scaricati di tracks_0.vtp e dagmc.vtk . Questi appariranno sul lato sinistro della finestra. Clicca sull'icona Occhio accanto ai file importati, oppure sul pulsante Applica qui sotto nella finestra delle proprietà per visualizzare l'output. Questo dovrebbe essere simile a quello visto nella Figura 7.
2. Flussi di lavoro
   NOTA: Un flusso di lavoro codifica una pipeline di elaborazione completa come un grafo orientato di strumenti con ingressi e uscite dichiarati. Una volta definito, lo stesso flusso di lavoro può essere rieseguito su qualsiasi insieme di file di input senza dover riconfigurare manualmente ogni strumento, e tutti i metadati della cronologia e della provenienza vengono catturati automaticamente.
   1. Clicca su Workflow nella barra di navigazione in alto, poi Crea in alto a destra. Inserisci un nome e una descrizione per il flusso di lavoro (qualsiasi cosa va bene), poi clicca di nuovo su Crea ancora.
   2. Aggiungi tre strumenti al flusso di lavoro, espandi le sezioni rilevanti nel menu Strumenti e aggiungi gli strumenti usati nella sezione 2.1: OpenMC Neutronics Simulation, CAD h5m a vtk e Tracks h5 a vtp.
   3. Definisci il flusso di dati tra gli strumenti. Trascina gli strumenti nell'area di lavoro cliccando e trascinando la barra superiore blu scuro di ciascuno di essi. Collega l'output Tracks (h5) dello strumento di simulazione neutronica all'input tracks.h5 dello strumento h5 a vtp. Fallo cliccando e trascinando dalla freccia in uscita alla freccia in ingresso.
   4. Definisci i dataset di input a livello di workflow. Nella sezione Input degli strumenti, clicca due volte su Input Dataset per creare due nodi di input. Rinomina uno per il file di configurazione e l'altro per l'input CAD cliccando sul passaggio e poi cambiando il campo Etichetta nel menu proprietà a destra.
   5. Collegare il file di configurazione e il file CAD agli input dello strumento di simulazione neutronica, e il file CAD allo strumento h5m a vtk, seguendo il pattern della Figura 3.
   6. Salva il flusso di lavoro usando l'icona di salvataggio in alto a destra.
   7. Per eseguire il flusso di lavoro, clicca sulla scheda Workflow nella barra in alto come prima, poi clicca sull'icona di riproduzione sul flusso di lavoro da eseguire. Poi seleziona gli input come con lo Step 2.1.2, come se eseguissi uno strumento, e clicca su Esegui Workflow.
   8. Aspettare che il flusso di lavoro venga eseguito, e poi gli output possono essere confrontati con i passaggi 2.1.5 e 2.1.8; Questi dovrebbero essere molto simili (ancora una volta, nota la variazione statistica da questi passaggi). Il flusso di lavoro è stato eseguito con successo quando tutti gli output nella Cronologia sono diventati verdi. Dovrebbero esserci (insieme ai dataset di input) quattro dataset presenti qui: TBR, Tracks, dagmc.vtk e tracks_0.vtp.
   9. Poiché il flusso di lavoro è stato eseguito, alcuni utenti potrebbero voler vedere la provenienza e i metadati catturati dall'invocazione (run) del workflow. Questo può essere ottenuto navigando su Utente nella barra in alto | Invocazioni del flusso di lavoro. Questo porta all'elenco di tutti i flussi di lavoro eseguiti dall'utente, cliccando sulla freccia verso il basso sul flusso di lavoro di interesse e poi può scaricare il file JSON dei metadati cliccando sul pulsante Download BioCompute Object . Questo contiene la provenienza degli strumenti/flussi di lavoro eseguiti, degli input utilizzati, ecc.
      NOTA: Il motore di workflow registra anche una cronologia completa di esecuzione per ogni esecuzione del workflow, inclusi checksum dei file di input, versioni degli strumenti e valori dei parametri. Per scaricare il record di provenienza di una run, apri il pannello Storia , clicca sul menu (freccia verso il basso) in alto a destra e seleziona Esporta Cronologia in File. L'archivio esportato contiene tutti i dataset e una registrazione leggibile dalla macchina dei passaggi che li hanno prodotti.
      Il salvataggio della provenienza o delle storie generate dal motore di workflow può essere automatizzato tramite l'API discussa nella Sezione 5.1; tuttavia, non sarà dettagliato in questo protocollo.
3. Flusso di lavoro più complesso
   NOTA: Questo flusso di lavoro estende la Sezione 2.2 aggiungendo passaggi di post-elaborazione che producono file Universal Scene Description (USD) necessari per la visualizzazione nella piattaforma metaverso. Poiché nessun singolo strumento converte direttamente da DAGMC (.h5m) o VTK (vtp) a USD, la pipeline instrada i dati attraverso due catene di conversione a più fasi: la geometria CAD segue una pipeline H5M, STL, OBJ, USD, e le tracce neutroniche seguono H5, VTP, OBJ, USD.
   1. Segui i passaggi per impostare un flusso di lavoro, come mostrato nella sezione 2.2, seguendo il flusso di lavoro mostrato nella Figura 4.
   2. Definire i due input a livello di workflow come nello Step 2.2.4, chiamandoli CAD DAGMC e Config File.
   3. Aggiungi lo strumento OpenMC Neutronics Simulation e collega gli ingressi CAD DAGMC e Config File ai corrispondenti ingressi come nello Step 2.2.3.
   4. Crea la catena di conversione neutrica. Aggiungi gli strumenti Track h5 a vtp, vtp a obj e obj a USD e poi collega le uscite di ciascuno agli input del successivo, seguendo la disposizione nel ramo inferiore della Figura 4.
   5. Crea la catena di conversione CAD. Aggiungi gli strumenti h5m a STL, STL a OBJ e OBJ a USD, e poi collega di nuovo le uscite di ciascuno agli ingressi del successivo, seguendo la disposizione nel ramo superiore della Figura 4.
   6. Salva il flusso di lavoro, che ora è pronto per l'uso nella piattaforma metaverso tramite l'estensione nella Sezione 3.
      NOTA: Questi passaggi aggiuntivi mostrano agli utenti come i flussi di lavoro e gli strumenti possano essere condivisi, consentendo la riproducibilità e l'accessibilità ai dati e ai metodi utilizzati per generare risultati.
   7. Esporta il flusso di lavoro come file portatile navigando su Workflow nella barra superiore, cliccando sul menu (freccia verso il basso) e selezionando Download. Il workflow manager salva un file JSON .ga , che poi può essere condiviso e utilizzato da chiunque abbia gli stessi strumenti sulla propria istanza del motore workflow. Questo può essere importato tramite Workflow nella barra in alto | Importa.
   8. Condividi gli strumenti facendo commit della cartella galaxy-tools/ del repository clonato su un host pubblico di controllo versioni. Chiedi ai collaboratori di clonare questo sistema per accedere a tutti gli strumenti containerizzati, eseguendoli nello stesso modo del dispositivo locale dell'editore.
      NOTA: Le istanze pubbliche di workflow manager possono essere configurate, il che evita la condivisione manuale di workflow e file di strumenti tra deployment locali. In questi casi, gli strumenti sono accessibili a tutti gli utenti e i flussi di lavoro e le storie possono essere resi pubblici a tutti gli altri utenti. Questo è fuori dall'ambito di questo protocollo, ma ulteriori informazioni sono disponibili nella rete ufficiale di Galaxy Training su come ottenere un deployment permanente: https://training.galaxyproject.org/training-material/topics/admin/tutorials/ansible-galaxy/tutorial.html o lo stack docker compose fornito nel repository possono essere distribuiti così com'è su un server e poi instradati tramite un proxy o un mezzo simile per renderlo pubblicamente accessibile.

3. Esecuzione di un flusso di lavoro dalla piattaforma metaverso

1. Lancio del Workflow
   1. Nella finestra dell'estensione della piattaforma metaverso, clicca su Ottieni flussi di lavoro (annotazione 2, Figura 5). Un menu a tendina verrà popolato con tutti i flussi di lavoro disponibili sull'account del motore di workflow associato alla chiave API memorizzata in default.json. Se non è così, verifica che la chiave API sia stata salvata correttamente nel file JSON e riavvia l'app della piattaforma metaverso per assicurarti che la chiave venga rilevata.
   2. Seleziona il Flusso di lavoro complesso per la lista e poi clicca su Prendi input (annotazione 4, Figura 5). I campi di input definiti nel flusso di lavoro (Passaggio 2.3.2) appariranno e dovranno essere chiamati allo stesso modo.
   3. Per ogni input basato su file, clicca su Select File e usa la finestra di esplora file per selezionare il file locale corrispondente: dagmc.h5m per l'input CAD DAGMC e openmc_config.json per l'input Config File .
   4. Clicca su Avvia il flusso di lavoro (annotazione 6, Figura 5). Un messaggio di conferma di lancio sarà visualizzato nella sezione Info (annotazione 7). Dopo il completamento del flusso di lavoro, ulteriori messaggi confermeranno che i file di output sono stati salvati e che l'esecuzione è terminata.
      NOTA: I progressi dei lavori di lavoro possono essere monitorati sull'interfaccia web del motore di workflow a http://localhost:8080 navigando su Admin | Jobs. È necessario l'accesso amministratore (vedi Passaggio 1.2.2).
2. Visualizzazione dei risultati
   NOTA: Al termine di ogni esecuzione del flusso di lavoro, il sistema scarica automaticamente i file di output dal motore di workflow in una directory di output locale. Il percorso di salvataggio è controllato dalla chiave output_dir nel file default.json dell'estensione. Ogni esecuzione è memorizzata in una cartella con timestamp, così che gli output possano essere distinti dall'estensione. Se ci sono problemi nella visualizzazione nella piattaforma metaverso, i file possono essere consultati in queste cartelle e visualizzati manualmente per verificare se il problema riguarda il motore di workflow.
   1. Nella piattaforma metaverso, espandi la sezione File Manager (annotazione 1, Figura 6) e clicca su Aggiorna (annotazione 2). Questo recupera l'elenco delle esecuzioni di workflow completate salvate nella directory locale.
   2. Nel menu a tendina Cartelle (annotazione 3, Figura 6), seleziona la cartella per l'esecuzione del flusso di lavoro corrente (conferma che sia l'unica attualmente presente) e clicca di nuovo su Aggiorna per popolare il menu a tendina File con gli output di quella run.
   3. Seleziona un file dal menu a tendina File (annotazione 4, Figura 6; attualmente sono supportati solo file .usd, .txt, .json e .out ) e poi clicca su Pull File (annotazione 5). I file basati su testo sono visualizzati nel pannello Info , i file USD vengono aggiunti alla scena corrente e dovrebbero essere visualizzati nella finestra principale.
   4. Per allineare la geometria importata con la convenzione di coordinate di Omniverse, apri il pannello Stage sul lato destro, seleziona entrambi gli oggetti di workflow importati e, nel pannello Proprietà appena sotto, imposta Ruota X a −90°. Questo corregge la discrepanza tra la convenzione z-up usata dagli strumenti di esportazione USD e la convenzione y-up di Omniverse. Applica questa rotazione sia al CAD USD che al file USD delle tracce; lo stato atteso del viewport dopo l'allineamento è mostrato nella Figura 8.
   5. Infine, per ottenere più contrasto tra le parti, si possono assegnare i materiali. Questo si ottiene aprendo la scheda Materiali in basso nell'app, selezionando un materiale e trascinando e rilascando la geometria nella vista Stage nella colonna a destra. Fallo per entrambe le geometrie importate per aumentare il contrasto tra di esse.

4. Aggiungere nuovi strumenti

NOTA: Questa sezione descrive il processo di sviluppo per creare e distribuire nuovi strumenti di workflow. Richiede l'accesso al file system del repository e l'accesso amministrativo al motore di workflow per il debug. Gli utenti che devono solo eseguire strumenti e flussi di lavoro esistenti, o creare flussi di lavoro, non devono seguire questa sezione.

1. Processo generale
   1. Sviluppa e testa lo script di simulazione o di elaborazione indipendentemente dal motore di workflow prima di incapsularlo. Il wrapper degli strumenti chiama uno script di lavoro esistente, non è consigliato implementare nuova logica durante lo sviluppo di uno strumento.
   2. Prepara l'ambiente di esecuzione dello script creando un'immagine Docker che includa tutte le dipendenze di runtime (librerie, binari, file dati, ecc.) richieste dallo script.
      NOTA: Tutti gli strumenti di esempio in questo protocollo utilizzano container Docker come ambiente di esecuzione. Gli ambienti Conda sono anch'essi supportati dal motore di workflow, ma qui non sono mostrati. Ulteriori informazioni su Docker sono disponibili nella documentazione ufficiale, oppure un buon corso introduttivo qui: https://uomresearchit.github.io/docker-introduction/ .
   3. Crea un file di definizione di uno strumento XML che dichiari l'ambiente di esecuzione (Docker in questo caso), il comando per invocare lo script e gli input, output e metadati degli strumenti per la visualizzazione nell'interfaccia del motore di workflow.
   4. Una volta creato il wrapper, inserisci l'XML e gli script in una nuova cartella galaxy-tools// nel repository. Aggiungi una nuova voce per lo strumento in galaxy-tools/tool_conf.xml sotto i tag appropriati, puntando al percorso relativo del file XML appena creato.
      NOTA: Assicurati che questo nome di file sia copiato esattamente, poiché questo è un errore comune quando si cerca di distribuire nuovi strumenti. Se la voce tool_conf.xml contiene un percorso errato o il file XML presenta un errore di sintassi, l'istanza del motore di workflow non si avvierà. Per ispezionare i log del contenitore del workflow alla ricerca di messaggi di errore, esegui quanto segue dalla radice del repository:
      'docker compone logs galaxy'
      Gli errori di parse XML appaiono come righe dello strumento di caricamento ERROR
   5. Ridistribuisci il motore di workflow per caricare il nuovo strumento eseguendo lo script di riavvio dalla radice del repository: ./restart-galaxy.sh.
   6. Conferma che lo strumento sia stato registrato correttamente. Naviga fino a http://localhost:8080, trova lo strumento nel pannello Strumenti e clicca sullo strumento per assicurarti che tutti gli input appaiono come previsto. Se lo strumento è assente, segui la nota sopra per il debug, e se ci sono ancora errori, controlla la sintassi stessa dell'XML dello strumento perché questo può causare errori di distribuzione.
   7. Esegui il nuovo strumento come prima, ma con input già testati in precedenza. Le uscite dovrebbero diventare verdi nel pannello Storia
   8. Se gli strumenti falliscono, allora come amministratore, clicca sull'output fallito (rosso) e clicca sull'icona Info . Questa mostra una pagina di output dettagliata e mostra gli stream stdout e stderr. Questi possono essere ampliati per ulteriori informazioni sul debug dello strumento.
2. Strumenti semplici
   NOTA: Gli strumenti 1–5 illustrano motivi di avvolgimento progressivamente più complessi. Il file XML e qualsiasi script per ogni strumento si trovano nella corrispondente sottodirectory galaxy-tools/simple/ / del repository. Distribuire ed eseguire ogni strumento seguendo i Passaggi 4.1.4–4.1.5 e la Sezione 2.1.
   Strumento 1 – Eseguire un comando semplice
   1. Guarda il file galaxy-tools/simple/1/1.xml . L'elemento requisiti specifica un ambiente di esecuzione Linux. L'elemento comando contiene il comando echo per eseguire.
   2. Esegui lo Strumento 1 dall'interfaccia del motore di workflow senza file di input necessari. Poiché non ci sono nemmeno file di output definiti, come amministratore, naviga nella pagina Admin, Jobs e poi clicca sull'icona Informazioni per vedere i flussi stdout e stderr, che corrispondono allo Step 4.1.8. Il flusso stdout dovrebbe contenere solo la stringa 'hello world' dal comando nel file XML.
      Strumento 2 – Utilizzo di input testuale
   3. Guarda il file galaxy-tools/simple/2/2.xml . Ora c'è una voce nel campo di input , con un elemento param type ="text" e la sezione comando ora fa riferimento alla variabile di input tramite il tag nome.
   4. Esegui lo Strumento 2 come prima; Questa volta, dai allo strumento un input di una corda. Può essere qualsiasi cosa l'utente desideri. Visualizza l'output come nel Passo 4.2.2, e l'output stdout dovrebbe essere la stringa fornita dall'utente nell'ingresso dello strumento.
      Strumento 3 – Utilizzo di un input basato su file
   5. Ancora una volta, guarda il file degli strumenti; ora, invece di un input a stringa, il parametro di input utilizza un tag type="data", che consente l'uso di un file. Questo viene citato nella sezione dei comandi come percorso di file, usando ancora il nome del parametro di input.
   6. Crea un file .txt usando un editor di testo locale, se non esegui:
      'echo "hello world da un file" > test_files/input.txt'
      dalla cartella radice del repository per generare l'input di esempio.
   7. Carica il file .txt creato come nel Passo 2.1.1 e poi esegui lo Strumento 3 come prima, selezionando il file di .txt caricato come input. Ancora una volta, visualizza lo stdout allo stesso modo e il contenuto del file .txt dovrebbe essere visualizzato lì. Se si usa il comando sopra, l'output dovrebbe essere "hello world from a file".
      Strumento 4 – Scrivere output in un file
   8. Esamina galaxy-tools/simple/4/4.xml. Una sezione di output ora dichiara un file di output con nome che può essere riferito nella sezione comandi.
   9. Esegui lo strumento come prima con l'input .txt , ma ora invece di visualizzare l'output come amministratore, questo può essere visto dall'utente abituale in questo pannello Cronologia e, in caso di esecuzione riuscita, diventerà verde e potrà essere scaricato / visualizzato nel motore di workflow come dettagliato nelle sezioni precedenti.
      Strumento 5 – Esecuzione di script negli strumenti
   10. Esamina galaxy-tools/simple/5/5.xml e lo script python associato galaxy-tools/simple/5/5.py. In XML, il comando fa riferimento allo script Python della directory degli strumenti, e la sezione dei requisiti ora fa riferimento a un'immagine Python poiché Python è necessario per eseguire lo script.
   11. Distribuisci ed esegui lo strumento allo stesso modo, e dovrebbe comportarsi allo stesso modo dello Strumento 4 (Passo 4.2.9), tranne che questa volta esegue uno script invece che il comando direttamente.
3. Esempio di strumento complesso
   NOTA: Questa sezione documenta lo sviluppo dello strumento di neutronia come esempio pratico del modello descritto nella Sezione 4.1. I file rilevanti si trovano su galaxy-tools/complex/openmc/. Lo stesso schema si generalizza a qualsiasi codice di simulazione o elaborazione.
   1. Sviluppa lo script di esecuzione per la simulazione. Per questo esempio, lo script run galaxy-tools/complex/openmc/openmc_run.py analizza un file di configurazione (openmc_config.json), scrive il file di impostazioni di neutronica ed esegue la simulazione. Testa lo script direttamente dalla riga di comando prima di impacchettarlo in un'immagine Docker.
   2. Costruisci l'ambiente di esecuzione Docker usando il file Dockerfile su galaxy-tools/complex/openmc/Dockerfile. Questo estende l'immagine pubblica con qualche pacchetto extra. Compila e tagga localmente o consulta da un registro container.
   3. Crea il wrapper XML galaxy-tools/complex/openmc/openmc.xml, dichiarando l'immagine Docker dal Passo 4.3.2 nella sezione requisiti . Dovrebbe essere definito anche il comando per eseguire insieme ai file di input e output (come nell'esempio della Sezione 4.2).
   4. Implementa lo strumento come nei Passaggi 4.1.4-4.1.7 e poi usa gli input di test usati nella Sezione 2 per assicurarti che lo strumento funzioni correttamente.
      NOTA: Gli strumenti rimanenti nell'istanza (tracce h5 a vtp, CAD h5m a vtk, h5m a stl, stl a obj, vtp a obj, obj a USD) sono convertitori di formato file che seguono lo stesso schema di sviluppo. I loro file XML sono nella directory galaxy-tools/complex/ e possono servire come ulteriori esempi di riferimento.

5. Collegare i flussi di lavoro al Metaverso

NOTA: Questa sezione fornisce materiale di riferimento per sviluppatori che descrive l'integrazione API del motore di workflow e l'architettura dell'estensione della piattaforma metaverso. Gli utenti che devono eseguire solo flussi di lavoro dalla piattaforma metaverse dovrebbero seguire la Sezione 3 e non devono leggere questa sezione. Gli sviluppatori che desiderano collegare un'applicazione front-end diversa al motore di workflow dovrebbero iniziare dalla Sezione 5.1.

1. API del motore di workflow
   NOTA: Galaxy espone un'API RESTful. La libreria Python Bioblend fornisce un wrapper di livello superiore attorno a questa API ed è la base per tutti gli script helper utilizzati in questo protocollo. Bioblend viene installato automaticamente all'interno degli ambienti di esecuzione Docker rilevanti forniti nel repository.
   1. Importa Bioblend e stabilisci una connessione con il motore di workflow in esecuzione istanziando un oggetto GalaxyInstance con l'indirizzo del server e la chiave API dello Step 1.5.2. In Python in un ambiente con Bioblend installato:
      `da bioblend.galaxy import GalaxyInstance
      gi = GalaxyInstance(url='http://localhost:8080', key=)'
      NOTA: Questo funziona solo per le implementazioni locali; se il motore di workflow è distribuito su una macchina remota, sostituisci il localhost con l'indirizzo e la porta dell'istanza configurata.
   2. Utilizzare le funzioni helper in galaxy-api/helper_functs.py per eseguire operazioni comuni: elencare i flussi di lavoro disponibili (get_workflows), recuperare definizioni di input del workflow (get_inputs) e avviare un workflow con file di input specificati (launch_workflow). Consulta le docstring inline in quel file per le firme di funzione e i tipi di ritorno attesi.
   3. Estendi la helper_functs.py con altre funzioni richieste dall'applicazione. L'API di riferimento completa è disponibile su https://bioblend.readthedocs.io.
2. Collegare i flussi di lavoro al metaverso
   NOTA: Questa sezione descrive solo l'architettura dell'estensione della piattaforma metaverso affinché gli sviluppatori possano adattarla a diversi flussi di lavoro, tipi di file aggiuntivi o piattaforme alternative del metaverso.
   1. Apri il punto di ingresso principale dell'estensione in omni_exts/omni.galaxy.example/. Questa estensione utilizza come punto di partenza l'estensione base¹⁵ di Omniverse. Aggiunge quindi tutte le funzionalità del file API Python delle funzioni helper descritto nel passo 5.1.2 e fornisce una GUI per interagire con i flussi di lavoro.
   2. Quando i flussi di lavoro vengono avviati, i dati che producono vengono scaricati automaticamente dal motore di workflow e memorizzati localmente, permettendo di visualizzarli sulla piattaforma metaverso. Questo consente inoltre di salvare e rendere accessibili i metadati generati durante l'esecuzione del workflow, fornendo così la provenienza dei dati della simulazione.
   3. Questa implementazione utilizza la libreria nativa omni.ui di Omniverse per costruire l'interfaccia. L'estensione principale si trova nella cartella delle estensioni, e l'implementazione principale dell'interfaccia è nel file omni_exts/omni.galaxy.example/omni/galaxy/example/window.py .

Risultati

Se le simulazioni vengono eseguite con gli input forniti nel repository git, dovrebbero essere ottenuti i seguenti risultati:

Al completamento con successo dello Step 2.1.3, sia il dataset di output TBR che quello di Tracce appariranno nel pannello Storia in verde, indicando una run riuscita. Un valore rappresentativo della TBR usando il file di configurazione fornito (5 lotti da 1.000 particelle) è circa 0,76...

Discussione

Ci sono alcuni passaggi critici all'interno del protocollo. La maggior parte riguarda la configurazione iniziale dell'istanza del motore di workflow, come: aggiungere l'email di amministrazione (step 1.2.2 del protocollo), poiché è necessario per l'accesso amministrativo ai pannelli di strumenti e lavori; generare correttamente la chiave API per l'estensione della piattaforma metaverso (step del protocollo 1.5.3) e incollarla correttamente nel file dei valori predefiniti; E quando si agg...

Materiali

Elenco dei materiali utilizzati in questo articolo

Nome	Azienda	Numero di catalogo	Commenti
Bioblend	Galaxy Project	v1.2+	Libreria Python che fornisce un wrapper di alto livello intorno all'API REST di Galaxy. Questo viene utilizzato negli script di aiuto dell'estensione Omniverse per elencare i flussi di lavoro, recuperare le definizioni di input e avviare i lavori. Installato automaticamente all'interno delle immagini Docker pertinenti; non è necessaria l'installazione sull'host.
Docker Containers	Docker	v24.0.5	Runtime di containerizzazione utilizzato per impacchettare ogni simulazione e strumento di post-elaborazione con tutte le sue dipendenze, garantendo portabilità e riproducibilità.
Galaxy	Galaxy Project	v22.05	Motore di workflow open-source utilizzato per orchestrare gli strumenti di simulazione e di elaborazione incatenati e per esporli tramite un'API REST.
Git	Git SCM	v2+	Necessario per clonare il repository per seguire il protocollo
NVIDIA RTX GPU	NVIDIA	-	Necessario per il rendering in tempo reale con ray-trace in Omniverse (Sezione 3). Gli utenti senza hardware RTX possono completare tutti i passaggi fino alla Sezione 2 e utilizzare ParaView per la visualizzazione (vedi Discussione).
Omniverse	NVIDIA	Code 2022.3.3	Piattaforma 3D collaborativa di NVIDIA. Questo viene utilizzato come front-end di visualizzazione e interazione per gli output dei flussi di lavoro tramite un'estensione Kit personalizzata.
ParaView	Kitware	v5.11	Applicazione di visualizzazione scientifica open-source utilizzata come fallback non-RTX per l'ispezione degli output .vtk/.vtp intermedi.
Protocol Repository	Custom	v1.0	Contiene la configurazione di Galaxy insieme a tutti i wrapper XML degli strumenti, gli script di esecuzione, i Dockerfile, i dati di test e l'estensione Omniverse. Clonato nel Passo 1.2.1. I file chiave sono anche forniti come caricamenti supplementari diretti (vedi I.2).
Python	Python	v3.10+	Runtime richiesto per lo script di esecuzione OpenMC e gli script di aiuto dell'estensione Omniverse. Incluso nelle immagini Docker pertinenti o con il download di Omniverse; non è necessaria alcuna installazione separata sull'host.
The OpenMC Monte Carlo Code	OpenMC	v0.13.3	Codice Monte Carlo open-source per il trasporto di particelle utilizzato qui per la simulazione di neutronica di fusione. Questo fornisce il rapporto di produzione di trizio (TBR) e gli output delle tracce dei neutroni.
Windows Subsystem for Linux (WSL)	Microsoft	v2	Necessario per eseguire Docker su host Windows (installa tramite `wsl --install` in powershell). Gli utenti Linux e Mac non hanno bisogno di questo.