PhAST: A matrix-free, differentiable PyTorch Solver for Phase-Field Fracture

Phase-field Autograd Solver in Torch
A matrix-free, differentiable PyTorch finite-element solver for two-dimensional phase-field fracture.

Documentation | Getting Started | Quickstart | Examples | Community | Citation | Releases

---

What is PhAST?

PhAST is a research finite-element solver implemented in PyTorch for two-dimensional phase-field fracture. Its principal dynamic pathway evaluates finite-element operators through tensor gather-compute-scatter operations without retaining a global stiffness matrix. Selected operations remain compatible with PyTorch autograd, subject to the documented limitations of nonsmooth history updates, bounds, active sets, and optional sparse backends.

(New to phase-field modeling? Read our Phase-Field Primer to learn the basics).

Models can be authored programmatically through the phast.Problem Python API or executed from YAML configurations. YAML is the reference format for shared examples because it records geometry, materials, boundary conditions, solver controls, and requested outputs in one reviewable file.

Core Strengths

• Matrix-Free Operators: Explicit fracture mechanics and damage updates use operations on PyTorch tensors without persistent global stiffness assembly on the main dynamic path.
• Differentiable Mechanics: Supported tensor operations remain compatible with PyTorch autograd where documented, enabling carefully interpreted sensitivity studies.
• Phase-Field Fracture Focus: Dynamic impact, crack branching, and quasi-static fracture workflows share a consistent mechanics/damage formulation and output schema.
• Documented Examples: Examples provide config.yaml, setup figures, final field plots, response histories, manifests, and compact animations. Numerical fields can be reloaded when the result directory contains a trajectory store.
• YAML Plus Fluent API: Use declarative YAML for reproducible runs and phast.Problem for programmatic model authoring.
• Standardised Post-Processing: phast.load_result reads stored manifests, CSV histories, visualisations, and available trajectory fields.
• Single-File Trajectories: When enabled, trajectory output defaults to HDF5 (training_data.h5). Zarr remains available by explicit selection.

How The Solver Works

YAML / phast.Problem -> Mesh -> Operators -> Solver -> Result bundle

For a phase-field fracture run, PhAST constructs or imports a two-dimensional finite-element mesh, evaluates the mechanical state, updates the tensile history field, solves the regularised damage problem, enforces damage bounds and irreversibility, and writes fields, histories, manifests, and run metadata. Explicit dynamics and quasi-static fracture use different mechanics updates; the solver overview and formulation guide describe both pathways.

For New Users

If you are new to PhAST, follow this sequence:

1. Read the phase-field primer if the formulation is new to you.
2. Follow the standard simulation tutorial for source installation and the common editable YAML layout.
3. Explain and check a fracture input before allocating a full simulation.
4. Run the small linear-elastic example to check solver execution and result loading on the current machine.
5. Consult the capability matrix before selecting a model for research use.

Quickstart

Install Python 3.10 or newer and Git first. These commands install the source checkout you clone; they do not assert that it is the latest release.

On macOS or Linux:

git clone https://github.com/CEMS-Lab/PhAST.git
cd PhAST
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

python -m phast doctor

On Windows PowerShell:

git clone https://github.com/CEMS-Lab/PhAST.git
cd PhAST
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\Activate.ps1
python -m phast doctor

Ensure python3 or py -3 selects Python 3.10 or newer. If activation is blocked on Windows, use .\.venv\Scripts\python.exe instead of python in subsequent commands; do not change system policy.

Editable installation already installs runtime dependencies. To install them separately in the same environment, use:

python -m pip install -r requirements.txt
python -m pip install -e .

The main student route is the small single-material quasi-static SENT, small single-material dynamic SENT, and full layered DCB example in the standard tutorial. The new adapters and schema-2 explanation command require combined checks before those sequences are labelled verified. Existing compatibility examples below provide a separate established first-check route.

Validate a public fracture configuration without launching a full solve:

python -m phast run examples/dynamic/B2_kalthoff_winkler/config.yaml --validate-only

--validate-only checks the schema and semantic consistency of the input. It does not run the solver or establish mesh convergence, benchmark reproduction, or physical validity.

Expected validation output:

OK: examples/dynamic/B2_kalthoff_winkler/config.yaml passes schema validation.

Inspect the parsed problem definition before execution:

python -m phast explain-config examples/quasistatic/notched_holed_plate/config.yaml

Run a compact end-to-end mechanics example and inspect its output:

python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml \
  --output_dir runs/linear_plate

import phast

result = phast.load_result("runs/linear_plate")
print(result.metadata())
print(result.history_names())
print(result.visuals())

PhAST itself does not require a separate CMake build. Optional PETSc/MUMPS, AmgX, cuDSS, and other platform-specific backends are not required for this first workflow.

Reproducible Workflows

The standard simulation workflow uses one schema-2 layout for editable geometry, mesh, materials, and loading. It includes retained DCB PNG/GIF evidence and complete coarse comparison inputs using the same CLI, not new solver drivers. The DCB result is qualitative layered-material interaction, not calibrated inclusion bypass. Its multi-material route is limited to CPU float64, structured-T3, quasi-static Amor AT2, and prescribed-displacement conditions.

Kalthoff-Winkler Impact	Quasi-Static Fracture	Dynamic Crack Branching

Simulation Category	Execution Command	Expected Artifacts
Dynamic Crack Branching	python -m phast run examples/dynamic/B7_dynamic_crack_branching_comsol/config.yaml	Damage fields, kinetic-energy histories, metadata, and visual summaries.
Dynamic Fracture	python -m phast run examples/dynamic/B2_kalthoff_winkler/config.yaml	Crack-propagation states, CSV histories, damage plots, and optional trajectory outputs.
Quasi-Static Fracture	python -m phast run examples/quasistatic/notched_holed_plate/config.yaml	Load-displacement response curves, final phase-field damage, and comparison artifacts.
Solid Mechanics Beta	python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml	Mesh-level FEA fields, nodal displacements, visual manifests, and structured metadata.

Browse the full example gallery for the complete list of runnable examples. Beta examples are provided for inspection, but they have not yet been validated as extensively as the included fracture benchmarks.

Documentation & API

Objective	Interface	Documentation Link
Learn one editable input layout	Schema-2 student workflow	Standard Simulation Workflow
Author a forward model	Fluent phast.Problem API	Python API
Execute public benchmarks	Declarative config.yaml	YAML Workflow
Post-process simulation data	phast.load_result(path)	Public API Reference
Review supported physics	Capability matrix	Capability Matrix
Learn step-by-step setup	Tutorial notebook	Problem Setup Walkthrough
Add an audited learned damage model	Predictor plug-in protocol	Modular FEM and Learned Damage
Learn elementwise E(x) and Gc(x) fields	Script-contract teaching example	Heterogeneous Material Fields
Diagnose failed runs	Troubleshooting guide	Troubleshooting

Programmatic Authoring

import phast

problem = (
    phast.Problem("linear plate")
    .geometry("structured_grid", nx=40, ny=12, length=1.0, height=0.2)
    .region("body", kind="domain")
    .material("steel", model="solid_mechanics", region="body", E=2.1e11, nu=0.3)
    .analysis_step("load", kind="solid_mechanics", controls={"tip_force_y": -1.0e3})
    .solver("solid_mechanics", example="solid_mechanics.linear_plate")
    .outputs(fields=["displacement", "von_mises"], histories=["response"], plots=True)
)

spec = problem.to_spec()

Result Inspection

import phast

result = phast.load_result("runs/linear_plate")
print(result.metadata())
print(result.visuals())
print(result.history_names())

Repository Map

Path	Purpose
src/phast/	Core PyTorch solver packages, mechanics/damage kernels, and CLI entry points.
examples/	Runnable examples, their YAML inputs, and lightweight reference outputs.
reproduction/paper1/	Manuscript and supplement catalogue, retained-data checks and figure reproduction commands.
configs/	Runnable benchmark decks, the YAML reference template and schema, and explicitly labelled reproducibility contracts.
docs/	Sphinx documentation, capability matrices, tutorials, and user guides.
assets/	Lightweight visual assets for repository documentation.
tools/	Maintenance utilities for documentation and release checks.
.github/	Issue templates, Pull Request guidelines, and CI/CD Action workflows.
AGENTS.md, llms.txt, .cursorrules	Agent-facing contribution guidance and repository orientation.

Contributing

Contributions are welcome for solver kernels, example cases, validation scripts, post-processing utilities, documentation, and performance improvements. Start with CONTRIBUTING.md, then use the capability matrix and example contract to keep public claims, examples, and artifacts consistent.

New YAML examples and their READMEs/tutorials must follow CONFIGURATION_STYLE.md alongside DOCUMENTATION_STYLE.md.

Students, researchers, scientific-software developers, and users evaluating PhAST are invited to review the code and documentation, propose reproducible examples, and report unclear instructions. If you become stuck at any point, open an issue. A question about installation or usage is a valid issue and helps improve the documentation for subsequent users.

Agent-assisted contributions are also supported. Guidance lives in AGENTS.md, llms.txt, .cursorrules, and docs/agent-contribution-guide.md. These files are intended to help contributors improve the solver and documentation without inventing benchmark results, capabilities, or paper metadata.

Build The Docs

pip install -r requirements-docs.txt
sphinx-build -b html docs docs/_build/html
open docs/_build/html/index.html

Hosted documentation is published at https://cems-lab.github.io/PhAST/.

Release history and version-specific notes are maintained in GitHub Releases, which is the project changelog referenced by the package metadata.

Citation

If PhAST contributes to your research, please cite the associated arXiv manuscript and the software repository metadata in CITATION.cff.

The Sphinx documentation includes a short how-to-cite page with a repository BibTeX entry and reproducibility notes.

@misc{ani2026phast,
  title={A matrix-free, differentiable PyTorch solver for phase-field fracture: Formulation, benchmarks, and inverse analysis},
  author={Ani, Allamaprabhu and Molinari, Jean-François and Subhash, Ghatu and Ponnusami, Sathiskumar Anusuya},
  year={2026},
  eprint={2606.23458},
  archivePrefix={arXiv},
  primaryClass={cs.CE},
  url={https://arxiv.org/abs/2606.23458}
}

Official code for the manuscript is hosted in this repository: https://github.com/CEMS-Lab/PhAST.

Acknowledgments

The theoretical formulations, phase-field continuum equations, constitutive assumptions, and numerical discretization choices in PhAST are derived from the established computational solid mechanics literature and were selected, interpreted, and validated by the human authors, as described in the associated article and documentation. AI coding assistants, including Codex, Claude, Gemini, and GitHub Copilot, were used as auxiliary software-engineering tools for repository organization, documentation editing, boilerplate generation, and code-review support; they did not define the physics, benchmark claims, validation criteria, or scientific conclusions. The authors reviewed and verified the computational mechanics kernels, benchmark configurations, and validation artifacts, and take full responsibility for the correctness, limitations, and scientific content of the codebase.

PhAST is organised to support reproducible scientific computing. Machine-readable manifests, structured result metadata, command-line and Python interfaces, and repository guidance allow researchers to inspect, reproduce, and extend simulations without relying on undocumented local settings. Scientific claims remain limited to the formulations, tests, and validation cases described in the documentation.