OpenUSD Case Workflow Strategy

OpenUSD Case Workflow Strategy#

Last updated: 2026-05-25

This document records the current direction for using OpenUSD in MuPRO-related workflows. It is an internal design note for future implementation, not a committed file-format specification.

Decision Summary#

  • MuPRO SDK should remain focused on phase-field simulation kernels, runtime foundations, C ABI, benchmarks, and solver correctness.

  • MuPRO SDK should adopt OpenUSD as the future standardized high-level case input format, but the Fortran solver core should not parse or depend on full OpenUSD directly.

  • MuPRO SDK should provide CLI and TUI tools for authoring, validating, inspecting, compiling, and running OpenUSD-based cases.

  • GUI, visual pre/post-processing, broader multi-scale workflow tooling, and visual case editing should be handled outside the MuPRO core repository, expected under Shenzhen Sijin Information Technology / SimViz-style tooling.

  • OpenUSD should unify case graph, scene-bound simulation metadata, physical semantics, asset references, and provenance. It should not replace HDF5, VTK, LAMMPS, DFT, FEM, or other native heavy data formats.

Scope Boundary#

Area

MuPRO SDK responsibility

External / SimViz-style responsibility

Phase-field solver kernels

Yes

No

Runtime context, status/error, C ABI

Yes

No

Canonical OpenUSD case schema subset needed by MuPRO

Yes

Shared

CLI for case creation, validation, compile, run

Yes

May call it

TUI for terminal-based case editing

Yes, lightweight

May reuse or wrap

Full GUI case editor

No

Yes

Visual pre-processing and post-processing

Minimal CLI hooks only

Yes

Multi-scale workflow orchestration UI

No

Yes

VTK/visualization application development

No

Yes

Scientific data storage for large fields

Define interfaces and metadata

Implement readers/viewers as needed

This boundary intentionally prevents GUI and general visualization work from expanding the MuPRO SDK core. MuPRO should expose stable file, CLI, and ABI surfaces; external tools can build richer experiences on top.

OpenUSD Role#

OpenUSD is suitable as a case description and composition standard because it provides:

  • Layered composition for modular case files.

  • References and asset paths for linking external files.

  • A hierarchical prim model for scene-bound entities such as regions, materials, phases, fields, solvers, couplings, and outputs.

  • Custom properties initially, and custom schemas later when the MuPRO data model stabilizes.

The intended role is:

OpenUSD case package:
  canonical high-level case graph, physical semantics, asset references, provenance

HDF5 / VTK / native solver files:
  large arrays, trajectories, meshes, field outputs, checkpoint data

mupro case CLI:
  author, validate, inspect, flatten, compile

compiled runtime config:
  stable solver-facing input consumed by Fortran/C ABI implementation

OpenUSD should describe where data lives and what it means. It should not carry every large numerical array directly.

Relationship To TOML#

TOML remains reasonable for current simple human-written configuration and examples. The future direction is:

  1. Keep TOML as a transitional and low-level config format while the OpenUSD case layer is prototyped.

  2. Introduce OpenUSD as a high-level case source that can compile into solver-ready configuration.

  3. Avoid direct solver-side dependency on OpenUSD in Fortran.

  4. Eventually treat OpenUSD as the preferred case package format for non-trivial workflows.

Expression evaluation should become explicit, typed, and validated in the case compiler rather than being hidden inside arbitrary string reads.

CLI-First Direction#

AI agents and scripts should interact with MuPRO through a stable CLI. The TUI should be a human-friendly shell over the same operations.

Proposed commands:

mupro case new ferroelectric-thin-film --name bto-film
mupro case new rapid-solidification --name rs-ni-al

mupro case set-grid rs-ni-al 256 256 128 --spacing 5e-9 5e-9 5e-9
mupro case add-component rs-ni-al Ni Al Cr
mupro case add-phase rs-ni-al matrix --eta eta_matrix
mupro case add-phase rs-ni-al precipitate GammaPrime --eta eta_gamma_prime
mupro case set-process rs-ni-al rapid-solidification --cooling-rate 1e6
mupro case attach-field rs-ni-al composition fields/initial_composition.h5 --dataset /c

mupro case inspect rs-ni-al/case.usda
mupro case validate rs-ni-al/case.usda
mupro case flatten rs-ni-al/case.usda -o rs-ni-al/compiled_case.usda
mupro case compile rs-ni-al/case.usda --out rs-ni-al/compiled
mupro run rs-ni-al/compiled

CLI design rules:

  • Every operation should be deterministic and scriptable.

  • Every command should return structured errors that can be consumed by AI agents and CI.

  • Validation should check units, shapes, field layouts, asset existence, unresolved relationships, unknown tokens, and unsupported solver features.

  • The CLI should generate legal OpenUSD rather than asking users or AI agents to hand-edit large USD files.

TUI Direction#

The TUI should help humans inspect and edit cases without building a full GUI.

Proposed layout:

Left:   USD stage tree
        Case / Materials / Phases / Regions / Fields / Solvers / Couplings / Outputs

Middle: selected prim property editor
        name, type, unit, value, relationship, asset path

Right:  validation report
        missing dataset, shape mismatch, unknown unit, unresolved relation

Bottom: command log
        mupro case add-phase ...

Important rule: each TUI edit should map to an equivalent CLI command. This keeps AI, scripts, and humans on the same workflow surface.

Multi-Scale Direction#

OpenUSD can be used to unify multi-scale materials workflows, but only at the case graph and semantic layer.

Recommended:

OpenUSD:
  workflow graph, materials, phases, regions, coupling semantics,
  provenance, file references, units, coordinate/layout metadata

Native / scientific formats:
  LAMMPS input/data/dump/restart
  DFT input/output, charge density, wavefunctions
  FEM mesh/result files
  MuPRO HDF5/VTK/checkpoint outputs

Not recommended:

Use USD as a universal replacement for every raw numerical data format.

Integration Levels#

Level

Goal

Recommendation

Level 1

Unified asset index and provenance

Strongly recommended

Level 2

Unified physical semantics and coupling graph

Recommended after schema stabilizes

Level 3

Convert all raw data into USD

Not recommended

Example multi-scale graph:

/Case/Scales/Electronic/DFT
/Case/Scales/Atomistic/LAMMPS
/Case/Scales/Continuum/FEM
/Case/Scales/Mesoscale/MuPRO

/Case/Couplings/DFT_to_MuPRO_FreeEnergy
/Case/Couplings/LAMMPS_to_MuPRO_Mobility
/Case/Couplings/FEM_to_MuPRO_StressBC
/Case/Couplings/MuPRO_to_FEM_EffectiveProperty

The first implementation should use import/adaptor commands that generate OpenUSD metadata and references:

mupro import lammps --input lammps/in.melt --dump lammps/dump.lammpstrj --into case.usda
mupro import dft --code vasp --path dft/run001 --into case.usda
mupro import fem --mesh fem/model.e --results fem/results.e --into case.usda

These commands should not destroy or rewrite the original simulation files.

Rapid Solidification Multi-Precipitate Example#

For a rapid solidification multi-precipitate simulation, OpenUSD should be split into layers instead of one large hand-written file:

rapid_solidification_case.usda
layers/
  grid.usda
  alloy_system.usda
  phases.usda
  process.usda
  initial_fields.usda
  solvers.usda
  outputs.usda
fields/
  initial_composition.h5
  initial_phase_noise.h5
results/
  results.h5

Root layer example:

#usda 1.0
(
    defaultPrim = "Case"
    subLayers = [
        @layers/grid.usda@,
        @layers/alloy_system.usda@,
        @layers/phases.usda@,
        @layers/process.usda@,
        @layers/initial_fields.usda@,
        @layers/solvers.usda@,
        @layers/outputs.usda@
    ]
)

def Scope "Case"
{
    custom string mupro:schemaVersion = "0.1"
    custom token mupro:caseType = "rapid_solidification"
}

The phase layer should describe phase identities and order-parameter names, not every precipitate particle:

#usda 1.0

over "Case"
{
    def Scope "Phases"
    {
        def Scope "Matrix"
        {
            custom token mupro:phaseKind = "matrix"
            custom token mupro:orderParameter = "eta_matrix"
        }

        def Scope "GammaPrime"
        {
            custom token mupro:phaseKind = "precipitate"
            custom token mupro:orderParameter = "eta_gamma_prime"
            custom double mupro:interfacialEnergy = 0.035
            custom double3 mupro:eigenstrain = (0.002, 0.002, 0.002)
        }
    }
}

Initial random noise, composition fields, and large evolving data should be stored in HDF5 or another scientific data format and referenced from USD:

#usda 1.0

over "Case"
{
    def Scope "Fields"
    {
        def Scope "Composition"
        {
            custom token mupro:fieldQuantity = "composition"
            custom asset mupro:file = @../fields/initial_composition.h5@
            custom string mupro:hdf5Dataset = "/c"
            custom int4 mupro:shape = (256, 256, 128, 4)
            custom token mupro:layout = "fortran_xyz_component"
        }
    }
}

Proposed Implementation Roadmap#

OUSD-001 Define MuPRO OpenUSD case vocabulary#

Deliverable: docs/internal schema vocabulary note and example .usda packages.

Initial entities:

  • Case

  • Simulation grid

  • Materials

  • Phases

  • Regions

  • Boundary conditions

  • Fields

  • Solvers

  • Couplings

  • Outputs

  • Assets and provenance

OUSD-002 Build mupro case validate#

Deliverable: CLI validator that can read a case package and emit structured diagnostics.

First validation set:

  • Required prims and attributes.

  • Units and layout tokens.

  • Asset path existence.

  • HDF5 dataset existence and shape checks where possible.

  • Relationship resolution.

  • Supported solver/model names.

OUSD-003 Build mupro case compile#

Deliverable: converter from composed OpenUSD stage to solver-facing runtime config.

The compiled output may initially include TOML or JSON-like intermediate files, but it must have stable semantics and structured error reporting.

OUSD-004 Build mupro case tui#

Deliverable: terminal UI that edits the same OpenUSD case model through CLI-equivalent operations.

OUSD-005 Add multi-scale asset adapters#

Deliverable: import commands for LAMMPS, DFT, and FEM metadata references. Raw native files remain external.

OUSD-006 Hand off GUI and visualization workflow#

Deliverable: documented interface contract for external SimViz-style tools:

  • OpenUSD case package conventions.

  • CLI commands and machine-readable diagnostics.

  • HDF5/VTK result contracts.

  • Stable asset and provenance metadata.

Risks And Guardrails#

Risk

Guardrail

OpenUSD becomes a huge hand-written config file

Use CLI/TUI authoring and layer templates

Fortran solver becomes coupled to OpenUSD APIs

Compile USD into solver-facing runtime config

USD is misused as raw field database

Store large arrays in HDF5/VTK/native formats and reference them

GUI work expands MuPRO scope

Keep GUI and visual workflow in external SimViz-style tools

Multi-scale semantics become vague

Start with explicit coupling entities and provenance metadata

Unit/layout mismatches create silent errors

Validator must check units, shape, layout, and relationships

Custom schema stabilizes too early

Start with custom mupro:*; introduce formal USD schema after vocabulary stabilizes

External References#

  • OpenUSD layers and composition: https://docs.nvidia.com/learn-openusd/latest/composition-basics/layers.html

  • OpenUSD references: https://docs.nvidia.com/learn-openusd/latest/composition-basics/references.html

  • OpenUSD asset resolution: https://openusd.org/23.05/api/ar_page_front.html

  • OpenUSD schema generation with usdGenSchema: https://openusd.org/release/api/_usd__page__generating_schemas.html

  • OpenUSD file formats and USDZ transport: https://openusd.org/dev/spec_usdz.html

Current Open Questions#

  • Should MuPRO define a formal USD schema plugin, a codeless schema, or stay with custom mupro:* during the first prototype?

  • Which language should implement mupro case first: Python for fast USD/HDF5 iteration, or C++/Rust for longer-term distribution?

  • Which scientific data format should be canonical for large field outputs: HDF5, VTKHDF, or both?

  • What minimum CLI diagnostic format should AI agents consume?

  • Which SimViz-facing interface should be frozen first: case package layout, result data layout, or CLI diagnostics?

Contents