Solver & Integrator Selection
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 correctelse: → 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:
- The element stiffness matrix’s condition number worsens, and iterative methods struggle to converge → pressure stabilization is needed (u-p formulation or F-bar)
- 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.