How to Validate PhaseFieldX Simulations Against Reference Solutions: A Complete Guide

You can validate PhaseFieldX simulations by loading output files using the AllResults class and comparing them against benchmark CSV files stored in examples/PhaseFieldFracture/reference_solutions/.

To validate PhaseFieldX simulations against reference solutions, you need to compare your numerical results with established benchmark data. The PhaseFieldX library provides a streamlined validation workflow through its AllResults post-processing class and pre-computed reference datasets for canonical fracture mechanics problems.

Understanding the Validation Workflow in PhaseFieldX

PhaseFieldX stores every simulation output as plain-text files in a dedicated results folder. This design enables direct comparison with reference solutions using standard data science tools.

Where Simulation Data is Stored

When you run a simulation, the solver writes the following file types into your specified output directory:

• .energy files: Contain energy values (E, W, W_phi, W_gradphi) per time step
• .reaction files: Store reaction force components (Rx, Ry, Rz) at boundaries
• .dof files: Record degrees of freedom and displacement values
• .input files: Preserve simulation parameters and metadata

These files are generated by the solver implementations in src/phasefieldx/Element/Phase_Field_Fracture/solver/solver_ener_variational.py, specifically around lines 430-470.

The Role of Reference Solutions

The repository includes validated reference solutions for benchmark problems such as three-point bending, single-edge notched tension, and shear tests. These are stored as CSV files in:

examples/PhaseFieldFracture/reference_solutions/

Available reference files include miehe_solution.csv, miehe_solution_shear.csv, and miehe_three_point.csv, containing columns that match the solver output format (step, E, W, W_phi, W_gradphi, gamma, etc.).

Loading Simulation Results with AllResults

The AllResults class in phasefieldx.PostProcessing.ReferenceResult provides the primary interface for loading and organizing simulation data.

from phasefieldx.PostProcessing.ReferenceResult import AllResults
import pandas as pd

# Load all output files from your simulation folder

sim_folder = "./my_simulation"
sim = AllResults(sim_folder)

# Access specific data types as Pandas DataFrames

energy_df = sim.energy_files["total.energy"]
reaction_df = sim.reaction_files["bottom.reaction"]

The class automatically parses files by their extensions and stores them in dictionaries (energy_files, reaction_files, dof_files, input_files), making it straightforward to access specific quantities by filename.

Comparing Against Reference Data

Once you have loaded both your simulation results and the reference CSV, you can perform quantitative validation.

Aligning Data by Displacement

Reference solutions and simulation data must be aligned on a common physical quantity, typically imposed displacement. You can compute displacement from the reaction forces using the formula implemented in the example scripts:

import numpy as np

# Calculate displacement from energy and reaction force

# Formula: disp = 2 * E / Ry

disp_sim = 2.0 * energy_df["E"] / reaction_df["Ry"]

Alternatively, if your simulation recorded displacement directly in a .dof file, you can extract it from sim.dof_files.

Calculating Quantitative Errors

With both datasets aligned, compute relative errors and norms:

# Load reference data

ref_path = "examples/PhaseFieldFracture/reference_solutions/miehe_solution.csv"
ref_df = pd.read_csv(ref_path)

# Interpolate reference data onto simulation displacement points

W_ref = np.interp(disp_sim, ref_df["disp"], ref_df["W"])

# Relative error at each point

rel_error = np.abs((energy_df["W"] - W_ref) / W_ref)

# Global L2 norm error

l2_error = np.linalg.norm(energy_df["W"] - W_ref) / np.linalg.norm(W_ref)
print(f"Relative L2 error in total energy: {l2_error:.2%}")

Example validation scripts such as plot_1713.py and plot_1714.py in the repository demonstrate complete visualization workflows, plotting simulation curves against reference data on the same axes.

Key Files and Components

Component	Path	Role
AllResults class	src/phasefieldx/PostProcessing/ReferenceResult.py	Loads and organizes simulation output files into Pandas DataFrames
Benchmark CSVs	examples/PhaseFieldFracture/reference_solutions/	Reference energy and reaction data for canonical fracture problems
Example validation scripts	examples/PhaseFieldFracture/plot_1713.py, plot_1714.py	Demonstrate loading, comparison, and visualization workflows
Energy file writer	src/phasefieldx/Element/Phase_Field_Fracture/solver/solver_ener_variational.py (lines 460-470)	Writes .energy files consumed by AllResults
Reaction force writer	src/phasefieldx/Element/Phase_Field_Fracture/solver/solver_ener_variational.py (lines 430-450)	Writes .reaction files for force-displacement analysis

Summary

• PhaseFieldX writes plain-text output files (.energy, .reaction, .dof, .input) that serve as the basis for validation.
• The AllResults class in phasefieldx.PostProcessing.ReferenceResult provides a Python interface to load these files into Pandas DataFrames.
• Reference solutions for benchmark fracture problems are available as CSV files in examples/PhaseFieldFracture/reference_solutions/.
• Validation involves aligning simulation and reference data by displacement, computing relative errors, and visualizing comparisons using the provided example scripts.

Frequently Asked Questions

What file formats does PhaseFieldX use for validation?

PhaseFieldX uses plain-text files with extensions .energy, .reaction, .dof, and .input to store simulation outputs. These files are automatically parsed by the AllResults class into Pandas DataFrames. Reference solutions are provided as CSV files that match the column structure of the solver outputs.

How do I compute displacement from reaction forces when validating PhaseFieldX simulations?

When displacement is not directly recorded, you can calculate it from the energy and reaction force values using the formula disp = 2 * E / Ry, where E is the energy from the .energy file and Ry is the vertical reaction force from the .reaction file. This approach is used in the repository's example validation scripts such as plot_1713.py.

Where can I find benchmark problems for PhaseFieldX validation?

Canonical benchmark problems are located in the examples/PhaseFieldFracture/reference_solutions/ directory of the repository. This folder contains CSV files such as miehe_solution.csv (single-edge notched tension), miehe_solution_shear.csv (shear test), and miehe_three_point.csv (three-point bending), which provide reference energy and reaction data for validation.

Can I automate validation in CI/CD pipelines?

Yes, the validation workflow is fully scriptable and suitable for CI/CD integration. Because AllResults loads plain-text files into Pandas DataFrames, you can write Python test scripts that automatically run simulations, load outputs, compute relative errors against reference CSVs, and assert that errors fall below specified tolerances (typically ≤ 1 % for energy and force quantities).

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