Use PETSc-native XDMF visualization topology

[gthyagi]

Summary

This PR revives the PETSc-native XDMF topology path from feature/annulus-spherical-benchmark-debug on top of current development, then extends the output API so timestep files can optionally carry PETSc reload metadata as well.

The branch currently contains:

• 22dd9ab2 / 90774778: add petsc_format control to Mesh.write() and make XDMF use PETSc's direct /viz/topology/cells connectivity rather than internal DMPlex /topology/cells.
• 9f41035e / 47719277: keep restart-style topology in write_timestep mesh files while still pointing XDMF to direct visualization topology.
• 5cd8a1f8: remove the manual _write_mesh_viz_groups() path added in PR Fix XDMF output to explicitly write cell-to-vertex topology and ensure strict ParaView compatibility #205 and rely on PETSc-native visualization topology.
• 4bd05789: add unified timestep/reload output support with write_timestep(..., petsc_reload=True) and write_checkpoint(..., create_xdmf=True).

Closes #217.

XDMF / visualization topology change

On current development, PR #205 added a manual Python _write_mesh_viz_groups() path to assemble /viz/geometry and /viz/topology. This PR removes that manual gather/deduplication path and lets PETSc write the visualization topology natively.

The resulting mesh output keeps the restart/topology information needed by UW3 while writing direct visualization connectivity at:

/viz/topology/cells

and geometry at:

/geometry/vertices

The XDMF writer validates and references the PETSc-written /viz/topology/cells dataset rather than raw DMPlex /topology/cells.

Unified timestep / PETSc reload output

This PR also adds an explicit output-payload switch:

mesh.write_timestep(
    "output",
    index=0,
    outputPath=str(output_dir),
    meshVars=[velocity, pressure],
    create_xdmf=True,
    petsc_reload=True,
)

With create_xdmf=True, timestep variable files contain the existing XDMF/remap payloads:

/fields/<variable>
/fields/coordinates
/vertex_fields/... or /cell_fields/...

With petsc_reload=True, the same per-variable HDF5 files also contain PETSc DMPlex reload payloads:

/topologies/uw_mesh/dms/<variable>/section
/topologies/uw_mesh/dms/<variable>/vecs/<variable>

That means a single output.mesh.<variable>.00000.h5 file can be used by both:

var.read_timestep(...)
var.read_checkpoint(...)

write_checkpoint(..., create_xdmf=True) now routes through the same unified writer. The default write_checkpoint() path remains restart-only and backward-compatible.

Why this is needed

The PETSc-native topology path avoids maintaining UW3-side MPI topology assembly, vertex deduplication, and cell reordering code. The unified output option also addresses the earlier architectural concern that visualization/remap output and PETSc-native reload output were locked into separate file families.

Users can now choose explicitly:

# Visualization/remap only
mesh.write_timestep(..., create_xdmf=True, petsc_reload=False)

# PETSc-native reload only
mesh.write_checkpoint(...)

# Unified visualization/remap + PETSc reload output
mesh.write_timestep(..., create_xdmf=True, petsc_reload=True)

Scope note

This PR addresses the PETSc-native /viz/topology/cells replacement requested in #217 for the current linear visualization topology workflow. It does not attempt to implement curved/isoparametric geometry support; that is a larger infrastructure change and should be tracked separately if needed.

Tests

Core UW3 tests run locally in amr-dev:

• ./uw build
• .pixi/envs/amr-dev/bin/python -m pytest -q tests/test_0003_save_load.py tests/test_0005_xdmf_compat.py
  • 16 passed
• .pixi/envs/amr-dev/bin/mpirun -n 2 .pixi/envs/amr-dev/bin/python -m pytest -q --with-mpi tests/test_0003_save_load.py::test_timestep_with_petsc_reload_roundtrip
  • passed on both ranks
• .pixi/envs/amr-dev/bin/mpirun -n 2 .pixi/envs/amr-dev/bin/python -m pytest -q --with-mpi tests/parallel/test_0005_xdmf_viz_topology_mpi.py
  • passed on both ranks in earlier validation for this branch

Benchmark validation:

• Ran the spherical Thieulot benchmark at cellsize=1/8, P2/P1, m=-1, 8 MPI ranks using the unified writer path.
• Confirmed unified files contain both XDMF/remap and PETSc reload payloads.
• Confirmed the checkpoint-only metrics stage completes from the same unified files using read_checkpoint().
• Serial reload comparison from the 8-rank output gave:

velocity max abs diff 0.0
pressure max abs diff 0.0

[gthyagi]

Additional validation after opening the PR:

• Confirmed the checkout is on bugfix/petsc-hdf5-viz-topology.
• Ran ./uw build in the configured amr-dev environment; build completed successfully.
• Re-ran .pixi/envs/amr-dev/bin/python -m pytest -q tests/test_0005_xdmf_compat.py after the build: 10 passed.
• Re-ran .pixi/envs/amr-dev/bin/mpirun -n 2 .pixi/envs/amr-dev/bin/python -m pytest -q --with-mpi tests/parallel/test_0005_xdmf_viz_topology_mpi.py after the build: 1 passed on each rank.

[gthyagi]

Follow-up pushed in 5ab5cb40:

• Mesh.write_checkpoint() now emits a visible FutureWarning and is documented as a compatibility wrapper.
• New code is directed to the unified standard API: write_timestep(..., petsc_reload=True).
• Developer docs now present write_timestep() as the single recommended output method, with create_xdmf and petsc_reload selecting the payloads.
• Tests that intentionally exercise write_checkpoint() now assert the compatibility warning.

Validation after the change:

• ./uw build
• .pixi/envs/amr-dev/bin/python -m pytest -q tests/test_0003_save_load.py tests/test_0005_xdmf_compat.py → 16 passed
• .pixi/envs/amr-dev/bin/mpirun -n 2 .pixi/envs/amr-dev/bin/python -m pytest -q --with-mpi tests/test_0003_save_load.py::test_timestep_with_petsc_reload_roundtrip → passed on both ranks

[lmoresi]

Review — approved ✅ (implements & closes #217)

Reviewed the full write/reload/XDMF path closely since this touches restart data integrity. Restart integrity is preserved, the default-format change is safe, and this satisfies #217's closure criteria.

• Format pairing is consistent on every reload path. _write_petsc_reload_file pushes HDF5_PETSC; MeshVariable.read_checkpoint and mesh _from_plexh5 read HDF5_PETSC. The new default mesh-file layout (petsc_format=None) still carries the full DMPlex restart topology + labels + coordinates, so reload + the FMG-hierarchy round-trip hold. No write/read mismatch.
• Default write() change is additive-safe. write(f) now yields PETSc default (restart + viz) instead of restart-only; write_checkpoint forces petsc_format=True where the old contract matters. Audited callers — none rely on viz-group absence.
• XDMF correctness improved: topology DataItem precision now derives from cells.dtype.itemsize (the old hardcoded Precision="8" mistyped int topology); malformed files now fail loudly with a clear message.
• Fix XDMF output to explicitly write cell-to-vertex topology and ensure strict ParaView compatibility #205 helpers fully removed (_write_mesh_viz_groups, _local_viz_cell_connectivity, _petsc_numbering_to_global_ids) with no dangling callers; the Fix XDMF output to explicitly write cell-to-vertex topology and ensure strict ParaView compatibility #205 viz-topology tests are preserved (updated to the native geometry/vertices path) and a parallel test was added.

Follow-ups (non-blocking — tracked separately, not gating this merge)

1. write_checkpoint FutureWarning fires from UW3's own snapshot subsystem (disk_snapshot.py:314). Harmless today (setup.cfg filterwarnings has no error escalation), but the internal snapshot path should call _write_petsc_reload_file / write_timestep(..., petsc_reload=True) directly rather than the deprecated method.
2. NIT: checkpoint_xdmf reads topo["cells"].attrs["cell_dim"] but never uses it — a needless dependency on a PETSc-internal attr name; delete the read.
3. NIT: the swarmVar XDMF attribute block still uses the old HyperSlab form while meshVar was flattened — unify in a follow-up.

Merging for the release; closing #217.

Underworld development team with AI support from Claude Code