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

> Validate PhaseFieldX simulations effectively by loading output files and comparing them to benchmark CSVs. Learn how to ensure your simulation accuracy with this comprehensive guide.

- Repository: [Miguel Castillón/phasefieldx](https://github.com/castillonmiguel/phasefieldx)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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`](https://github.com/castillonmiguel/phasefieldx/blob/main/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.

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

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

```python

# 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`](https://github.com/castillonmiguel/phasefieldx/blob/main/plot_1713.py) and [`plot_1714.py`](https://github.com/castillonmiguel/phasefieldx/blob/main/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`](https://github.com/castillonmiguel/phasefieldx/blob/main/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`](https://github.com/castillonmiguel/phasefieldx/blob/main/examples/PhaseFieldFracture/plot_1713.py), [`plot_1714.py`](https://github.com/castillonmiguel/phasefieldx/blob/main/plot_1714.py) | Demonstrate loading, comparison, and visualization workflows |
| Energy file writer | [`src/phasefieldx/Element/Phase_Field_Fracture/solver/solver_ener_variational.py`](https://github.com/castillonmiguel/phasefieldx/blob/main/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`](https://github.com/castillonmiguel/phasefieldx/blob/main/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`](https://github.com/castillonmiguel/phasefieldx/blob/main/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).