Configuration guide¶

This guide summarizes the configuration choices that most strongly affect stability, convergence, and reproducibility in PhAST.

mat = create_material('glass_borden', eta_residual=1e-6)

Configuration Guide¶

Preconditioner Selection Logic¶

For implicit solver types, an unspecified preconditioner defaults to jacobi. Other preconditioners are optional paths whose availability and suitability depend on the selected solver, device, mesh, and installed dependencies. Check the capability matrix before treating one as part of a reproducible workflow.

The available vocabulary includes `jacobi`, `gmg`, and optional `amg`/`amgx`
backends. Automatic selection is environment-dependent; no device-specific
performance ranking is implied here.

Anderson Acceleration Guide¶

anderson_depth enables an optional Type-II fixed-point acceleration for the staggered damage update. Its effect is problem-dependent; no iteration-saving percentage or generally preferred depth is asserted here. Leave it at its default unless the selected case has been evaluated with that option.

Energy Split Decision Tree¶

Is the problem pure Mode I tension?
  YES → isotropic (lowest split complexity)
  NO  →
    Is crack path expected to curve?
      YES → spectral (Miehe 2010, eigenvalue decomposition)
      NO  →
        Is compression significant?
          YES → amor (volumetric-deviatoric, robust default)
          NO  → isotropic

    Studying crack nucleation without pre-crack?
      YES → star_convex (Kumar & Lopez-Pamies 2020)

Convergence Criterion Comparison¶

Solver Type Selection¶

Use explicit only when inertia and stress waves are part of the physics question, for example Kalthoff-Winkler impact or dynamic branching. Explicit dynamics is CFL-limited and is not a shortcut for quasi-static loading.

quasi_static is the default for displacement-controlled SENT, SENS, TPB, L-shaped panel, and comparable slow-loading fracture problems. Keep quasi_static_legacy only when reproducing an older accepted run that depends on the frozen-secant CG path.

Explicit-dynamics performance knobs¶

For explicit dynamics, the damage equation can be solved every N-th time step instead of every step. Since damage propagates more slowly than the elastic wave speed used by the CFL condition, damage_every: 2 or 3 can be useful after a sensitivity check.

solver:
  damage_every: 1   # reference validation: solve damage every explicit step
  # damage_every: 2 # throughput sensitivity run
  # damage_every: 3 # aggressive throughput run; document as non-reference

The first explicit steps still solve damage every step to capture crack nucleation. Treat subcycling as a performance setting, not as a change to the benchmark definition.

Smooth load ramps reduce high-frequency oscillations from instantaneous tractions. In YAML, prefer ramp_type: smooth_step with an explicit t_ramp for dynamic traction loads that should approximate a finite rise time.

Residual stiffness eta_residual is the numerical floor in the degradation function. It prevents fully damaged regions from producing zero-stiffness rows; use the benchmark value unless you are deliberately studying sensitivity.

Recommended Settings per Benchmark¶

Benchmark Acceptance Metadata¶

primary public and paper-facing configs should include a top-level acceptance: block. It is structured but extensible metadata for reviewers and post-processing scripts; it does not change the solve. PhAST validates the standard fields while preserving custom benchmark-specific keys. Use it to record the reference figure/table, required artifacts, metric targets, tolerances, units, and caveats:

acceptance:
  status: beta                  # scaffold | beta | production | validated | diagnostic | experimental
  reference_result: "Ambati et al. (2015), L-panel peak load"
  required_outputs: [run_lockfile.json, config.yaml, load_displacement.png]
  metrics:
    peak_reaction_kN:
      target: 16.0
      tolerance: 0.15
      units: kN
    crack_path:
      target: "corner-to-top-edge arc"
      tolerance: visual
  notes: "Reaction convention and extraction script must be cited here."

python -m phast explain-config <config.yaml> prints this block, and YAML runs preserve it in the resolved config and run lockfile. Keep the status below validated until the reference extraction and output artifacts are stored in the repository or linked from the public record.

Material Presets Quick Reference¶

Troubleshooting¶

CG diverges or very slow:

• Check pf_model: AT1 has a nucleation threshold below which CG converges to d=0 trivially

• Keep quasi-static/static jobs on --preconditioner jacobi; use gmg/amg only when validating that preconditioner path explicitly

• Increase --damage_cg_tol from 1e-5 to 1e-4 if convergence is too slow

• For spectral/amor splits, both QuasiStaticSolver (quasi_static, default ) and SecantCGSolver (quasi_static_legacy) are supported; fall back to quasi_static_legacy if the new spectral-split tangent exhibits stalls on a particular configuration

• Optional AMG backends can be unavailable or can reject a problem during setup. Treat such messages as backend-specific diagnostics and compare the resulting route and outputs explicitly; they do not by themselves establish that a simulation result is unaffected.