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 explicit dynamics, preconditioner=None with use_multigrid=True resolves through the auto-selection chain below. For static, quasi_static, quasi_static_legacy, lbfgs, and monolithic, unresolved preconditioners default to jacobi to avoid fragile AMG/GMG behavior in reaction-dominated implicit endgame states. Use preconditioner='auto' or 'amg' only for explicit validation of that path.

CUDA HPC (A100/H100/V100):
  pyamgx installed? → amgx (fastest, GPU-native AMG)
  pyamg installed?  → amg (CPU setup, GPU solve)
  else              → gmg (2-level geometric, always available)

CUDA Workstation (RTX 3090/4090/A6000):
  pyamg installed?  → amg
  else              → gmg

CUDA Consumer (RTX 2080/3060):
  → gmg (low VRAM, AMG setup overhead not worth it)

Apple MPS:
  → gmg (no CUDA, no AMG; float32 with CPU float64 fallback for CG)

CPU:
  pyamg installed?  → amg (fastest CPU option)
  else              → gmg

Anderson Acceleration Guide¶

Anderson acceleration (Type II, Walker & Ni 2011) reduces stagger iterations by 30-50%.

Usage: SolverConfig(anderson_depth=3) or --anderson_depth 3

Energy Split Decision Tree¶

Is the problem pure Mode I tension?
  YES → isotropic (fastest, simplest)
  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

• Version note: If CG reports 5000 iterations every step, update to a release that includes the corresponding convergence fix. Earlier revisions could stall because of an overly strict absolute tolerance, unstable AMG directions in reaction-dominated regimes, and unnecessary hierarchy rebuilds. The corrected path uses a relative tolerance, quality checks with Jacobi fallback, and cached hierarchy data.

[AMG] pyAMG failed (array must not contain infs or NaNs), skipping hierarchy rebuild warnings during crack transition:

Benign — simulation results are unaffected. These warnings fire during the narrow window where damage jumps from max(d) ≈ 0.6 to max(d) = 1.0 at crack nucleation. The reaction coefficient reaction_coeff = (2H + Gc/l0) · area/12 passed into _assemble_sparse_cpu is itself finite (guarded at multigrid.py:875 and would emit a separate [AMG] WARNING: N non-finite reaction_coeff entries, clamping message if it weren’t). The inf/NaN appears inside pyamg.smoothed_aggregation_solver(A_csr) setup, where operations like Jacobi relaxation-weight estimation (1/diag), Lanczos