# 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:

```text
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:

```bash
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:

```text
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:

```text
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:

```text
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:

```text
/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:

```bash
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:

```text
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
#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
#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
#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?