Solver and Preconditioning¶

FrontISTR's linear solver is configured by selecting either a direct or iterative method; when an iterative method is selected, it is combined with a preconditioner to solve the linear system. The MPC treatment method and contact-DOF elimination are auxiliary choices that determine how linear systems containing multi-point or contact constraints are handled.

Overview¶

Solver and preconditioning consist of the following choices. First select either an iterative or direct method as the linear solver. A preconditioner is combined only with an iterative method.

Category	Main Options	Role
Iterative methods	`CG`, `CR`, `PipeCG`, `GroppCG`, `BiCGSTAB`, `GMRES`, `GPBiCG`, `GMRESR`, `GMRESREN`	Solve large sparse linear systems with efficient memory use.
Preconditioners for iterative methods	SSOR, diagonal scaling, BILU, AMG, SAINV, RIF	Improve convergence of iterative methods. Not used with direct methods.
Direct methods	`MUMPS`, `MKL`	Solve linear systems robustly through factorization.
MPC treatment methods	Penalty method, explicit DOF elimination	Incorporate multi-point constraints into the linear system.
Contact-DOF elimination	Automatic, always enabled	Switches how contact DOFs added by SLAGRANGE contact are handled.
Auxiliary functions	Condition-number estimation, matrix dump, logging	Support debugging, convergence assessment, and performance evaluation.

For parallel execution, MPI parallelism based on domain decomposition can be combined with OpenMP thread parallelism. Iterative methods are the standard choice for large-scale parallel analyses, while direct methods are used when the required libraries are linked and a more robust solution is needed.

Choosing a Solver and Preconditioner¶

First decide whether to use an iterative or direct method. If an iterative method is selected, then choose a preconditioner.

Decision Factor	Recommended Approach
Problem size	Direct methods are stable and easy to use for small to medium problems. Iterative methods are more memory-efficient for large problems.
Matrix symmetry	For symmetric positive-definite problems, consider `CG` and its variants (`PipeCG`, `GroppCG`). For nonsymmetric problems, consider `BiCGSTAB`, `GMRES`, `GPBiCG`, or similar methods.
Parallel environment	Under MPI parallelism, combine an iterative method with domain decomposition. For preconditioning under OpenMP parallelism, consider SSOR, which is threaded using multicolor ordering. For problems with three DOFs per node, BILU is also threaded.
Preconditioner (when using an iterative method)	Try the default SSOR first, then consider AMG. SSOR is computationally lightweight when convergence is good; AMG preconditioning is suitable for complex, large-scale problems. AMG is available as a Trilinos-ML implementation or HEC-MW's built-in SA-AMG; choose according to the build configuration.
Contact and MPC	In analyses containing contact or multi-point constraints, the choice of MPC treatment method and contact-DOF elimination affects convergence and robustness.
External libraries	`MUMPS`, `MKL`, and AMG (Trilinos-ML) are available in builds linked with the corresponding libraries. AMG (SA-AMG) is available in builds with LAPACK enabled.

For standard analyses, the default convergence tolerance, maximum iteration count, preconditioner diagonal correction coefficient, and similar settings generally work adequately. Only when convergence is slow or the solution diverges should you review, in order, the iterative method, preconditioner, MPC treatment method, and contact-DOF elimination. See the !SOLVER keyword reference for parameter values and syntax.

Iterative Methods¶

Iterative methods solve large sparse systems by repeatedly updating the solution through matrix-vector products and preconditioning. FrontISTR provides the following iterative methods.

Iterative Method	Typical Application	Notes
`CG`	Symmetric positive-definite problems	A standard candidate for structural and heat conduction analyses.
`PipeCG`	Symmetric positive-definite problems	A variant of `CG` that combines the global inner-product reductions into one per iteration. A candidate when many MPI processes are used and waiting for collective communication dominates computation time.
`GroppCG`	Symmetric positive-definite problems	A variant of `CG` that combines the inner-product reductions into two per iteration. Its intended use is the same as for `PipeCG`.
`CR`	Symmetric problems	Conjugate residual method.
`BiCGSTAB`	Nonsymmetric problems	A candidate when contact or coupling produces strong nonsymmetry.
`GMRES`	Nonsymmetric problems	Used with a specified Krylov subspace size.
`GPBiCG`	Nonsymmetric problems	Used as an improved method in the `BiCGSTAB` family.
`GMRESR`	Nonsymmetric problems, advanced applications	An option that uses `GMRES` in a nested form.
`GMRESREN`	Nonsymmetric problems, advanced applications	A recursive variant in the `GMRESR` family.

CG, PipeCG, and GroppCG assume that the matrix is symmetric positive definite, while CR assumes that the matrix is symmetric. If frictional contact, nonsymmetric constraint treatment, coupling effects, or similar factors introduce strong nonsymmetry, consider BiCGSTAB, GMRES, GPBiCG, or another nonsymmetric solver. With GMRES, increasing the Krylov subspace size can improve convergence, but also increases memory usage.

When METHOD2 is specified, FrontISTR can switch to an alternative iterative method if CG, PipeCG, or GroppCG diverges or breaks down. This feature is a fallback for cases in which one of these methods is the primary solver; the alternative method uses the same remaining settings and data lines as the primary solver.

CG, BiCGSTAB, GPBiCG, PipeCG, and GroppCG update the residual vector by recurrence, so roundoff error accumulates over repeated iterations and the recursively updated residual can drift from the true residual. To prevent this, the residual vector is periodically recomputed from the right-hand side and the matrix-vector product. For all of these methods except GroppCG, the interval can be specified with RECOMPUTE_RESIDUAL. A longer interval reduces the number of matrix-vector products, but increases the risk that the recursively updated residual will drift from the true residual and a solution that has not converged will be judged converged. Conversely, making the interval too short not only increases the number of matrix-vector products but can also disrupt the relationship between the residual and auxiliary vectors maintained by the recurrence and degrade convergence itself. The default value for each method balances these effects; if you change it, check the convergence history and the final relative residual.

Preconditioning¶

Preconditioning transforms the coefficient matrix to improve convergence of an iterative method and is applied only when an iterative method is selected. Direct methods do not use preconditioning. Even for the same iterative method, the choice of preconditioner can substantially change the number of iterations and computation time required for convergence.

Preconditioner	Characteristics	Typical Application
SSOR	Standard preconditioner; supports multicolor ordering.	First candidate to try; widely used in structural analysis.
Diagonal scaling	Lightweight preconditioner using diagonal entries.	When low computational cost is preferred.
BILU	Block incomplete LU factorization.	A candidate for problems for which SSOR converges poorly.
AMG (Trilinos-ML)	Algebraic multigrid using the external Trilinos-ML library.	A candidate for large-scale problems or problems dominated by hierarchical error components.
AMG (SA-AMG)	Smoothed Aggregation algebraic multigrid built into HEC-MW.	Same as above; a candidate when using AMG without adding an external library.
SAINV	Sparse Approximate Inverse.	A specialized preconditioning option for contact problems or distributed environments.
RIF	Robust Incomplete Factorization.	Another incomplete-factorization option.

SSOR is the standard choice, and a multicolor-ordering version is used under OpenMP parallelism. A relaxation parameter can be specified to tune convergence, but the default value can be used for standard analyses. Diagonal scaling is lightweight, although its convergence improvement depends on the problem. BILU is implemented as a block incomplete LU factorization and also supports matrices with a general DOF count. For matrices with three DOFs per node, BILU also uses a multicolor-ordering version under OpenMP parallelism. For the BILU family, there is a path that automatically increases the diagonal correction coefficient SIGMA_DIAG and retries when an iterative method diverges; see the keyword reference for how to specify the value.

AMG (algebraic multigrid) has two implementations: one using the external Trilinos-ML library and HEC-MW's built-in SA-AMG. These are independent implementations with different required build configurations and available options.

AMG using Trilinos-ML requires ML to be enabled at build time. The smoother, multigrid cycle, coarsening scheme, and other settings can be specified; see the keyword reference for detailed values.

SA-AMG is a Smoothed Aggregation algebraic multigrid preconditioner and does not require Trilinos-ML. It uses LAPACK internally, so a build with LAPACK enabled is required; if it is selected in a build without LAPACK, the program terminates without starting the analysis. For coarse-grid solves, MUMPS can be used in builds with MUMPS enabled; otherwise, the built-in dense direct method is used.

SA-AMG primarily targets symmetric positive-definite systems (CG) but also supports nonsymmetric reduced systems arising from frictional contact (BiCGSTAB, GMRES, and others). It supports 1 (heat conduction), 2 (plane), 3 (solid), and 6 (shell) DOFs per node, but does not support matrices in which the number of DOFs differs by node. The coarse-grid solver, multigrid cycle, smoother degree, and other options can be specified, but the defaults can be used for standard analyses. See the keyword reference for values and syntax. In builds with GPU (OpenACC) enabled, the preconditioner application phase runs on the GPU.

When SAINV is used in a parallel analysis containing contact or MPC constraints, the overlap depth used for domain decomposition can affect convergence.

Direct Methods¶

Direct methods solve linear systems by factorizing the coefficient matrix. Because they do not depend on an iteration count, they are robust and can be a stable choice for analyses containing contact or constraint conditions. Their memory consumption, however, increases with problem size.

Direct Method	Parallel Environment	Application
`MUMPS`	MPI parallel	Solves sparse matrices directly in distributed-memory environments.
`MKL`	Intel MKL / OpenMP	Direct solver based on Intel MKL. Intel PARDISO is used internally. With multiple MPI processes, the Cluster MKL path is used. `DIRECTmkl` is an alias of `MKL`.

Direct methods can be used for both symmetric and nonsymmetric matrices. MUMPS and MKL require the corresponding libraries to be linked at build time. They cannot be used in environments without those libraries, so see the build guide for required dependencies and CMake options.

FrontISTR also contains a built-in direct-solver path that does not use an external library, but for ordinary analyses requiring a direct method, consider MUMPS or MKL.

Preconditioning is not applied to direct methods. Even if a preconditioner is specified in !SOLVER, it is not referenced on the direct-solver path.

MPC Treatment Methods¶

The MPC treatment method determines how degrees of freedom connected by multi-point constraints are incorporated into the linear equations. Even with the same constraint equations in the input data, the treatment method changes the properties and convergence behavior of the coefficient matrix.

MPC Treatment Method	Role	Default Use
Penalty method	Approximately satisfies the constraints by adding large stiffness terms to the constraint equations.	Default for direct methods.
Explicit DOF elimination	Eliminates constrained degrees of freedom and solves the reduced linear system.	Default for iterative methods.

The penalty method is the default for direct methods, while explicit DOF elimination is the default for iterative methods. The formerly available MPC-CG method has been removed; input specifying MPCMETHOD=2 produces a warning and is processed using these defaults.

With explicit elimination of degrees of freedom, the lumped masses used in modal analysis and explicit dynamic analysis are also condensed using the same transformation as the stiffness matrix. Since the condensed mass matrix is generally not diagonal, its row sums are used as lumped masses. For coupling or interpolation constraints whose constraint-equation coefficients sum to 1, the mass of the slave degree of freedom is distributed to the master degrees of freedom in proportion to the coefficients.

The MPC treatment method can be specified explicitly in !SOLVER with MPCMETHOD. See the keyword reference for the meaning and syntax of each value.

Contact-DOF Elimination¶

Contact-DOF elimination condenses the additional contact degrees of freedom introduced by SLAGRANGE contact before passing the system to the linear solver. Eliminating these contact degrees of freedom can improve the properties of the linear system handled by an iterative method.

In the default automatic mode, contact-DOF elimination is enabled for iterative methods and disabled for direct methods. For direct methods, a path is provided that handles the enlarged system containing the contact degrees of freedom without eliminating them.

When CONTACT_ELIM is specified explicitly, contact-DOF elimination can also be performed when a direct method is used. For input-side choices of contact type, contact pair, and contact algorithm, see the Contact and Embedding page.

Auxiliary Functions¶

Condition-number estimation, matrix dumping, and logging can be used to investigate solver convergence and performance. These functions are unnecessary for normal analyses and are enabled for debugging or performance evaluation.

Function	Purpose	Notes
Condition-number estimation	Outputs an indicator of the condition number for `CG` and `GMRES`.	Available in builds with LAPACK enabled.
Matrix dump	Saves the matrix and right-hand side passed to the solver in a file.	Supports Matrix Market, CSR, and BSR formats.
`DUMPEXIT`	Terminates the analysis after dumping the matrix.	Used when only the matrix is required for external verification.
`ITERLOG`	Outputs the convergence history of an iterative method.	Used to inspect residual trends.
`TIMELOG`	Outputs solver computation time.	`VERBOSE` outputs a more detailed breakdown.
`STEPLOG`	Outputs step information.	Used to inspect the analysis procedure.
`LOGLEVEL`	Outputs diagnostic information such as the hierarchy construction of AMG preconditioners.	Specified independently of `ITERLOG` and `TIMELOG`. Higher values increase the amount of output.

Matrix dumping allows the coefficient matrix assembled by the analysis to be inspected with external tools. When DUMPEXIT is enabled, the analysis terminates after the matrix and right-hand side have been saved. Condition-number estimation is an experimental feature available with CG and GMRES, and can be used to diagnose convergence behavior.