Troubleshooting and Failure Modes¶

Installation recovery by platform¶

Start with python -m phast doctor and record the first error, rather than installing optional backends pre-emptively.

Windows¶

Use PowerShell in a fresh virtual environment. If python is not found, use the Python launcher (py -3.11) or install Python 3.10 or newer with the launcher enabled. If a package wheel is unavailable, retry with Python 3.11 and update pip; do not mix packages from multiple Python installations. Run commands from the repository root so example paths resolve.

macOS¶

Use a supported Python from python3 or a conda environment. On Apple Silicon, CPU float64 is the conservative verification route; MPS availability is useful information, not a requirement. If Gmsh or a plotting import fails, recreate the environment rather than combining Homebrew and conda binary stacks.

Linux and HPC¶

Create a clean virtualenv or conda environment on the login or development node, then run the doctor and sanitizer before selecting a scheduler or GPU backend. PETSc/MUMPS, cuDSS, AmgX, and CuPy are optional and must match the machine’s MPI, CUDA, and compiler stack. A missing optional backend is not a base-install failure.

Docker¶

Build and run the bounded check from the repository root:

docker build --tag phast:local .
docker run --rm phast:local

The image runs run_sanitizer.py only. It does not run a long simulation.

Phase-field fracture simulations are sensitive to units, mesh resolution, boundary conditions, and time-step choices. This page lists common symptoms and the first checks to perform before changing solver code.

Numerical Mechanics FAQ¶

Is \(h\leq\ell_0/2\) sufficient?¶

No. It is a useful starting resolution criterion near the expected crack path, not a convergence certificate. Assess \(h\)-refinement at fixed \(\ell_0\) using load-displacement response, fracture energy, crack path, and solver convergence. Study \(\ell_0\) separately because changing it changes the regularized model.

Does every route use staggered convergence?¶

No. Supported quasistatic calculations perform inner mechanics-damage iterations and ordinarily monitor displacement and damage changes. Explicit dynamics performs one segregated pass per time step, with damage solved at the configured cadence. The monolithic \((\mathbf{u},d)\) minimizer is experimental.

Is the AT2 damage update explicit because mechanics is explicit?¶

No. For fixed history and the standard quadratic AT2 operator, the damage residual is affine in \(d\), but its finite-element discretization remains a global elliptic linear solve. Explicit dynamics can therefore use an explicit mechanics update while invoking an implicit damage solve at selected steps.

What is the difference between history, bounds, and an active set?¶

The history maximum makes the crack-driving field nondecreasing. Nodal no-healing is imposed separately through \(d_{n+1}\geq d_n\). Projected CG maintains the bound through an active set; post_clamp solves the unconstrained system and clamps afterward, so it is not an active-set solution.

Does adaptive explicit time stepping retry a failed step?¶

The automatic explicit step is bounded by an elastic-wave CFL estimate. The optional damage-increment controller adjusts the subsequent step after the current step is completed; it does not reject and recompute that completed step. In quasistatic runs, the configured increment is a continuation/load increment rather than physical time.

Quick Triage¶

Commands To Run First¶

Validate the environment:

python -m phast doctor

Validate the configuration without launching the full solve:

python -m phast run <config.yaml> --validate-only

Inspect the parsed setup:

python -m phast explain-config <config.yaml>

After a completed run, inspect the result folder:

import phast

result = phast.load_result("runs/<case>")
print(result.metadata())
print(result.manifest())
print(result.visuals())

Mesh and Regularization¶

The phase-field length \(\ell_0\) is not just a material number; it also sets the width of the damage band that the mesh must resolve. Near notches, holes, and expected crack paths, start from

If the crack path changes when the mesh is refined, treat the coarse result as diagnostic rather than validated.

Units¶

The public examples generally use the mm-N-MPa-s convention. Mixing SI values with mm-scale geometry is a common source of immediate failure. Check:

• \(E\) in MPa when length is in mm;

• \(G_c\) in N/mm;

• density and time units for explicit dynamics;

• prescribed displacements and velocities in the same length/time system as the mesh.

When To Open An Issue¶

Open a GitHub issue when the problem persists after the checks above. Include:

• the exact command;

• the configuration file path;

• python -m phast doctor output;

• the first traceback or warning;

• run_manifest.json, run_metadata.json, and run_lockfile.json when a run directory exists;

• a small image or initial_conditions.png if the issue is geometric or visual.

Also open an issue when the documentation does not explain what to do next. Students and first-time users are welcome to submit incomplete diagnostic information; include the command and first observed failure, and the maintainers can help identify the next check.