What Mesh Formats Does PhaseFieldX Support? A Complete Guide to Gmsh, XDMF, and VTU

PhaseFieldX primarily supports Gmsh .msh files for input, while output and interchange use XDMF, VTU, and VTK formats through its Dolfinx backend.

PhaseFieldX is an open-source finite element framework built on top of Dolfinx (the FEniCSx backend) for simulating phase-field fracture and related phenomena. Because it leverages Dolfinx for mesh handling, PhaseFieldX inherits robust support for industry-standard mesh formats, with specific workflows optimized for Gmsh-generated geometries.

Primary Input Format: Gmsh .msh Files

PhaseFieldX uses Gmsh .msh files as its primary mesh input format. The repository explicitly relies on dolfinx.io.gmsh.read_from_msh to import both ASCII and binary Gmsh meshes into Dolfinx Mesh objects.

In examples/PhaseFieldFracture/plot_1718.py, the canonical import workflow is demonstrated:

import dolfinx.io.gmsh
import mpi4py.MPI as MPI
import os

# Path to the mesh generated by Gmsh

mesh_path = os.path.join("mesh", "my_geometry.msh")

# Read the mesh (Dolfinx expects a communicator, model rank, and geometric dimension)

mesh_data = dolfinx.io.gmsh.read_from_msh(
    mesh_path,
    MPI.COMM_WORLD,   # MPI communicator

    gmsh_model_rank=0,
    gdim=3             # 2 for 2‑D meshes, 3 for 3‑D meshes

)

mesh, cell_markers, facet_markers = mesh_data

This function returns a tuple containing the mesh, cell markers, and facet markers, which PhaseFieldX solvers use to apply boundary conditions and material properties.

Alternative Input: XDMF Format

While Gmsh is the primary input method, PhaseFieldX also supports XDMF (.xdmf + .h5) files through dolfinx.io.XDMFFile. This format is commonly used for exchanging meshes between different simulation tools or for storing pre-tagged geometries.

To load an XDMF mesh:

import dolfinx.io
import mpi4py.MPI as MPI

xdmf_path = "mesh/domain.xdmf"
with dolfinx.io.XDMFFile(MPI.COMM_WORLD, xdmf_path, "r") as xdmf:
    mesh = xdmf.read_mesh()
    cell_tags = xdmf.read_meshtags(mesh, "cell_tags")

Although the repository does not contain a dedicated wrapper for XDMF mesh import, the solvers extensively use XDMFFile for reading and writing solution fields, ensuring full compatibility with XDMF-based meshes.

Output and Visualization Formats

PhaseFieldX generates results in multiple formats optimized for different post-processing workflows.

VTU for Post-Processing

The solvers generate VTU (.vtu) files for visualization in ParaView and PyVista. In src/phasefieldx/Element/Phase_Field_Fracture/solver/solver_ener_variational.py, the solver writes VTU files when save_solution_vtu=True:

import dolfinx.io
import os

# Assume `phi` is a dolfinx.Function defined on the mesh

output_folder = "results/paraview-solutions_vtu"
os.makedirs(output_folder, exist_ok=True)

vtu_path = os.path.join(output_folder, "phasefieldx_p0_000000.vtu")
with dolfinx.io.XDMFFile(mesh.comm, vtu_path, "w") as xdmf:
    xdmf.write_mesh(mesh)
    xdmf.write_function(phi)

Post-processing utilities like src/phasefieldx/PostProcessing/measure_crack_length_2d.py then read these VTU files using PyVista:

import pyvista as pv
import os

vtu_file = os.path.join("results/paraview-solutions_vtu",
                        "phasefieldx_p0_000000.vtu")
mesh = pv.read(vtu_file)

# Simple plot: mesh in black, phase‑field (phi) as red iso‑surface

plotter = pv.Plotter()
plotter.add_mesh(mesh, color="black", opacity=1.0)
phi_iso = mesh.threshold(value=0.95, scalars="phi", invert=False)
plotter.add_mesh(phi_iso, color="red")
plotter.show()

XDMF for Result Storage

Simulation results (displacements, phase-field variables, etc.) are stored in XDMF format for efficient restart capabilities and time-series analysis. The solvers use dolfinx.io.XDMFFile to write these fields at each time step.

VTK for Quick Visualization

Many example scripts in examples/GmshGeoFiles/plot_9105.py write VTK (.vtk) files for rapid visualization without ParaView dependencies, using standard Dolfinx output routines.

Complete Workflow Example

A typical PhaseFieldX simulation follows this mesh handling pipeline:

1. Generate geometry with Gmsh (.geo → gmsh -3 -o mesh.msh)
2. Import the .msh file using dolfinx.io.gmsh.read_from_msh as shown in examples/PhaseFieldFracture/plot_1718.py
3. Run the simulation – the solver writes results as XDMF (for fields) and VTU (for quick inspection)
4. Post-process using PyVista reading the generated VTU files

Summary

• Primary input: Gmsh .msh (ASCII or binary) imported via dolfinx.io.gmsh.read_from_msh
• Alternative input: XDMF files readable through dolfinx.io.XDMFFile
• Output formats: XDMF for result storage, VTU for ParaView/PyVista visualization, VTK for quick dumps
• Key implementation files: examples/PhaseFieldFracture/plot_1718.py (import), src/phasefieldx/Element/Phase_Field_Fracture/solver/solver_ener_variational.py (export), src/phasefieldx/PostProcessing/measure_crack_length_2d.py (post-processing)

Frequently Asked Questions

Can PhaseFieldX read COMSOL or Abaqus meshes?

No, PhaseFieldX does not natively read COMSOL or Abaqus mesh files. You must first convert these to Gmsh .msh format or XDMF using external tools like meshio or Gmsh's import capabilities, then load them via dolfinx.io.gmsh.read_from_msh or dolfinx.io.XDMFFile.

What is the difference between XDMF and VTU output?

XDMF (.xdmf + .h5) stores mesh topology and solution data separately, making it efficient for time-series data and restart capabilities. VTU (.vtu) is a single-file VTK XML format optimized for direct visualization in ParaView and PyVista. PhaseFieldX solvers typically write XDMF for archival storage and VTU for immediate post-processing.

Does PhaseFieldX support binary or ASCII Gmsh files?

Yes, PhaseFieldX supports both ASCII and binary Gmsh .msh formats. The dolfinx.io.gmsh.read_from_msh function automatically detects the format when loading meshes in examples/PhaseFieldFracture/plot_1718.py and other example scripts.

How do I convert my existing mesh to Gmsh format?

Use Gmsh itself or the Python library meshio to convert meshes. For example, with meshio: meshio.convert("input.msh", "output.msh") handles many formats. Alternatively, open your mesh in Gmsh and use File > Save As to export as Version 4.1 ASCII or binary .msh format, which PhaseFieldX can then import via dolfinx.io.gmsh.read_from_msh.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}