Skip to content

Solver & Integrator Selection

solver-selectionApplies to analyze / troubleshoot~660 tokens

The desktop AI reads from the same knowledge base — this page is its English edition. When the AI cites 📖 guide · solver-selection in a conversation, it refers to this entry.

In One Sentence

Users should never pick the solver by hand. Dispatch automatically by DOF count and soil state; a wrong choice is a 100× difference in time.

Decision Tree (Implemented Directly in the Kernel, Not Exposed to Users)

DOFs Solver Integrator Expected time per solve Key constraint
< 50k Sparse direct (PARDISO / SuperLU) HHT-α / Newmark 0.1–0.3 s Runs on a laptop
50k–300k Sparse direct (PARDISO multithreaded / MUMPS) HHT-α + modified Newton 1–8 s DRM domain reduction required, or you hit the memory wall
300k–1M AMG-CG (hypre BoomerAMG) or MUMPS out-of-core HHT-α + a few Newton iterations 3–20 s Direct methods need 16–104 GB
> 1M Explicit (dry soil / high permeability only) or MPI domain decomposition + AMG ExplicitBathe / CDM 0.2–1 s/step Reduce the model first; don’t brute-force

The ordering algorithm is always MMD/METIS, measured at 3.4× difference on 3D models. There is no option for this.

Liquefying Soil Is a Hard Boundary

When u-p elements are present and the permeability coefficient is < 1e-7, only implicit is possible. The reason is not accuracy—explicit’s stable time step gets crushed by the pore pressure diffusion term (Δt collapses to the 1e-8 range; a 40 s time history would take a year to run).

So the decision order must be:

if has u-p elements and permeability < 1e-7:
→ implicit (PARDISO if n < 3e5 else AMG_CG(stabilized=True)) + HHT-α
elif n < 5e4:
→ PARDISO + HHT-α
elif n < 3e5:
→ PARDISO(multithreaded, out-of-core) + HHT-α
elif wave propagation and dry soil:
→ Diagonal + ExplicitBathe # the only case where explicit is correct
else:
→ AMG_CG + HHT-α

The liquefaction check must come first. If dispatch happens by DOF count first, an 80k-DOF liquefaction model will walk into the “sparse direct” branch—it looks fine but will actually deadlock in the pore pressure iterations.

Three Measured Pitfalls

Pitfall 1: system Diagonal runs, but the results are wrong

The diagonal preconditioner works in standard OpenSees—no error, no warning—yet the displacements differ from the direct method by 9.1×. It is only suitable for explicit integration (explicit doesn’t solve linear systems; it only needs a diagonal mass matrix).

Criterion: with any implicit integration, seeing system Diagonal means it’s wrong. Kavvo forbids this combination at the kernel level.

Pitfall 2: system Mumps crashes the standard build outright

Not an error—the process simply exits (0xC0000005). MUMPS is only compiled into OpenSeesMP.exe. Therefore:

  • Single-machine build → PARDISO / SuperLU / AMG
  • MUMPS required → must go through the MPI build

Capability probing must use a separate subprocess per item. Trying system Mumps in the same process means one crash kills the entire probe.

Pitfall 3: Skipping factorization reuse wastes 90% of the time

In implicit dynamic analysis, the stiffness matrix barely changes from step to step (it only changes during nonlinear iterations). Re-factorizing every step is pure waste.

Strategy: factorize every 10 steps when convergence is fast; fall back automatically to every step when convergence slows. This adaptive logic lives in the kernel where users never see it, but it decides whether a time history takes 3 minutes or 30.

The ν = 0.499 Degradation

Undrained and liquefying soils use ν = 0.499 (not 0.5—0.5 makes the bulk modulus infinite). This value has two consequences:

  1. The element stiffness matrix’s condition number worsens, and iterative methods struggle to converge → pressure stabilization is needed (u-p formulation or F-bar)
  2. Direct methods’ memory grows, because fill-in increases

So when you see “ν = 0.499 + iterative method + no convergence”, the first response should not be to loosen the tolerance—it should be to switch to a direct method or add stabilization.

How the UI Should Present This

Show only “Selected: PARDISO (automatic)”. Advanced users may override, but once they do, a warning line must appear in the status bar: “Solver manually specified; automatic dispatch disabled.”

Do not build a “solver” dropdown for users to choose from. A structural engineer shouldn’t have to learn the difference between PARDISO and MUMPS to run a model—that’s our job.

solverperformanceconvergenceliquefactiondegrees-of-freedom