PhaseFieldX Post-Processing Tools for Visualization and Quantitative Analysis

PhaseFieldX provides a comprehensive post-processing module under src/phasefieldx/PostProcessing that includes ParaviewResult for VTU file handling, AllResults for simulation data aggregation, and automated crack-length measurement workflows to generate publication-ready visualizations and metrics.

The castillonmiguel/phasefieldx repository ships with a dedicated post-processing package designed to bridge raw simulation outputs and scientific analysis. Located in src/phasefieldx/PostProcessing, these post-processing tools enable researchers to load VTU files, extract quantitative fracture data such as crack lengths, and aggregate energy and reaction force data without writing custom parsing code.

Core Post-Processing Components

The post-processing ecosystem centers on three primary utilities that handle different aspects of simulation analysis.

ParaviewResult Class

The ParaviewResult class in src/phasefieldx/PostProcessing/paraview.py serves as the primary interface for loading and accessing VTU files. It scans a specified simulation folder for the paraview-solutions_vtu sub-directory, loads selected time steps into PyVista datasets, and stores them in a NumPy-compatible array structure.

This class exposes the raw mesh data through its data attribute, allowing direct access to field variables such as displacements, phase-field values, and stresses.

AllResults Container

For comprehensive simulation analysis, the AllResults class in src/phasefieldx/PostProcessing/ReferenceResult.py aggregates all textual output files into organized pandas DataFrames. It automatically detects and loads .conv, .energy, .reaction, .dof, and .input files from the simulation directory.

When a paraview-solutions_vtu folder is present, AllResults can initialize a ParaviewResult instance through its get_paraview() method, creating a unified interface for both numerical data and mesh visualization.

Crack Length Measurement Tools

The fracture-specific post-processing pipeline resides in src/phasefieldx/PostProcessing/measure_crack_length_2d.py. This module provides a complete workflow for extracting quantitative crack metrics from 2D simulations:

1. Image Generation: Converts VTU files to PNG images highlighting crack regions where the phase-field variable ϕ > 0.95 in red
2. Physical Calibration: Detects specimen bounding boxes to calculate pixel-to-meter conversion factors
3. Skeletonization: Applies image processing to measure crack length in physical units
4. Animation: Generates animated GIFs showing crack evolution over time

The primary entry point is the measure_crack() function, which orchestrates the entire pipeline with a single call.

Loading and Visualizing VTU Files

To begin analyzing simulation results, use the ParaviewResult class to load VTU data into PyVista datasets.

from phasefieldx.PostProcessing import ParaviewResult

# Folder that contains the `paraview-solutions_vtu` sub‑directory

sim_folder = "./examples/PhaseFieldFractureEnergyControlled/results_three_point_var"

# Load all solution steps (here we ask for the last step)

result = ParaviewResult(sim_folder, steps=[-1])

# Access the PyVista dataset of the last step

mesh = result.data[0]          # numpy‑array of PyVista datasets

print(mesh.bounds)            # e.g. (0.0, 1.0, 0.0, 0.5, 0.0, 0.0)

For direct plotting with PyVista, access the underlying mesh objects and use standard PyVista visualization commands.

import pyvista as pv
import os

vtus = sorted([f for f in os.listdir("paraview-solutions_vtu") if f.endswith(".vtu")])
first_vtu = pv.read(os.path.join("paraview-solutions_vtu", vtus[0]))

plotter = pv.Plotter()
plotter.add_mesh(first_vtu, show_edges=True)
plotter.camera_position = "xy"
plotter.show()

Aggregating Simulation Data

The AllResults class provides a high-level interface for analyzing numerical outputs alongside mesh data.

from phasefieldx.PostProcessing import AllResults

# Path to the folder that contains the raw output files

results = AllResults("./my_simulation")

# Quick look at available energy data

print(results.energy_files["total.energy"].head())

# If a ParaView folder exists, initialise the visualisation helper

if hasattr(results, "paraview_filenames"):
    results.get_paraview(results.folder_path)   # creates results.paraview

    # Now you can reuse the `ParaviewResult` methods

    mesh = results.paraview.data[0]

Quantitative Fracture Analysis

For 2D fracture simulations, the crack measurement pipeline automates the extraction of physical crack lengths from phase-field results.

from phasefieldx.PostProcessing import measure_crack

# Folder that contains the simulation’s VTU output

simulation_folder = "./examples/PhaseFieldFractureEnergyControlled"

# Physical specimen dimensions (meters, for instance)

width  = 0.01   # horizontal size

height = 0.005  # vertical size

# Run the whole workflow:

#   • generate PNGs

#   • compute pixel‑to‑meter conversion

#   • extract crack length for each frame

#   • build an animated GIF

measure_crack(simulation_folder, physical_horizontal=width,
              physical_vertical=height)

This workflow converts VTU files to PNG images highlighting regions where the phase-field variable ϕ > 0.95, calculates physical pixel dimensions based on the specimen bounding box, applies skeletonization algorithms to measure crack length in physical units, and generates animated GIFs showing crack evolution.

Key Files and API Reference

The post-processing functionality is organized across four primary source files:

File	Purpose
src/phasefieldx/PostProcessing/paraview.py	Core class for loading VTU files and exposing them as NumPy/PyVista arrays.
src/phasefieldx/PostProcessing/measure_crack_length_2d.py	Complete 2-D crack-length post-processing pipeline (VTU → PNG → length → GIF).
src/phasefieldx/PostProcessing/ReferenceResult.py	High-level result aggregation (energies, reactions, DOFs) and optional Paraview integration.
src/phasefieldx/PostProcessing/__init__.py	Public API export for the PostProcessing module.

Summary

PhaseFieldX delivers a complete post-processing ecosystem for phase-field fracture analysis:

• ParaviewResult loads VTU simulation files into PyVista datasets for immediate visualization and custom analysis.
• AllResults aggregates numerical outputs (energies, reactions, DOFs) and optionally integrates mesh data for comprehensive simulation review.
• Crack measurement tools automate the extraction of physical crack lengths from 2D simulations, generating PNG sequences and animated GIFs without manual image processing.
• The public API exposed through __init__.py enables simple imports: from phasefieldx.PostProcessing import ParaviewResult, AllResults, measure_crack.

Frequently Asked Questions

How do I load VTU files in PhaseFieldX for visualization?

Use the ParaviewResult class from phasefieldx.PostProcessing. Pass the simulation folder path to the constructor, optionally specifying which time steps to load via the steps parameter. This returns PyVista datasets accessible through the data attribute, which you can visualize using standard PyVista plotting commands or export to ParaView.

What is the difference between ParaviewResult and AllResults?

ParaviewResult specifically handles VTU file loading and provides direct access to mesh data for visualization. AllResults is a higher-level container that aggregates all simulation text outputs—including energy histories, reaction forces, convergence logs, and DOF data—into pandas DataFrames, while optionally integrating ParaviewResult functionality if VTU files are detected.

How does the crack length measurement tool work in PhaseFieldX?

The measure_crack function in measure_crack_length_2d.py executes a four-step pipeline: it converts VTU files to PNG images highlighting crack regions where the phase-field variable ϕ > 0.95, calculates physical pixel dimensions based on the specimen bounding box, applies skeletonization algorithms to measure crack length in physical units, and generates an animated GIF showing crack evolution over time.

Can I customize the visualization output format?

Yes. Since ParaviewResult exposes raw PyVista datasets through its data attribute, you can leverage PyVista's full API to customize plots—including camera positions, color maps, edge visibility, and export formats like PNG or PDF. For crack visualization outputs, you can modify the phase-field threshold (default ϕ > 0.95) or image processing parameters directly in the measure_crack_length_2d.py source code.

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