Solver

*Solver, <solver name>, [<extrapolation>, <iterative solver options>]

This command is used to specify the solver to be used to solve the system of equations of the current step. As default, the Pardiso solver is used. The following solvers can be selected:

<solver name> Use this keyword to specify the strategy for solving the system of equations. numgeo offers direct solvers as well as iterative solvers.

Direct solver

Pardiso: a thread-safe and memory efficient software for solving large sparse symmetric and unsymmetric linear systems of equations on shared-memory and distributed-memory multiprocessors ¹². A cost-free academic licence is available.
Example:
*Solver, Pardiso
MUMPS: Shared-Memory (OpenMP) version of the MUltifrontal Massively Parallel sparse direct Solver ³⁴.
Example:
*Solver, Mumps
simple: A simple implementation of a direct solver using serial forward substitution. Should only be used for very small systems, e.g. single-element tests.
Example:
*Solver, simple
diagnoal: A simple implementation of a direct solver for strictly diagonal matrices such as used in explicit dynamics with mass lumping.
Example:
*Solver, diagnoal

Iterative solver (inhouse):

BiCGStab: The BiConjugate Gradient Stabilized method, often abbreviated as BiCGStab, is an iterative method proposed by H. A. van der Vorst ⁵ for the numerical solution of nonsymmetric linear systems. A (right-)preconditioned as well as a version without preconditioning is implemented in numgeo. In cases where BiCGStab does not work well, it may be advantageous to use the BiCGStab(l) method.
Example:
*Solver, BiCGStab (using default settings)
*Solver, BiCGStab, pc=none, tol=1e-4, check_rel_solution (using costum settings)
BiCGStab(l): The BiConjugate Gradient Stabilized(l) method, often abbreviated as BiCGStab(l), is an iterative method proposed by H. A. van der Vorst and D. Fokkema for the numerical solution of nonsymmetric linear systems. The version implemented in numgeo is based on the proposed implementation by D. Fokkema ⁶⁷⁸, which is based on the power basis variant of BiCGstab(l). This variant is enhanced with a more stable way of determination of the iteration coefficients and with a more reliable update strategy for the residuals. Faster convergence in terms of iteration counts may be expected for increasing values of the parameter l. However, since more work is required to obtain the iterate as l increases, optimal performance in terms of computational work may be realized for quite a small value of l. Starting with the value l=2 is recommended.
Example:
*Solver, BiCGStab(l) (using default settings)
*Solver, BiCGStab(l), l=4, pc=ls-diagonal, tol=1e-4 (using costum settings)
[<iterative solver options>]
Optional. Use this keyword to override the default controls of numgeo for the iterative solver. Multiple keywords can be used, all separated by a comma:
[keyword_1, ..., keyword_n. The available keywords depend on the iterative solver in use:
- tol = real. Define the convergence tolerance of the iterative method, this is, when the approximated solution is said to be converged. In general, given the linear problem: $\(\boldsymbol{A} \boldsymbol{x} = \boldsymbol{b}$\) with $\boldsymbol{A}$ is the global left-hand-side (lhs) of the system of equations and $\boldsymbol{b}$ the corresponding right-hand-side (rhs), $\boldsymbol{x}$ is the desired solution. For a given initial guess $\boldsymbol{x}_0$, the approximate solution $\boldsymbol{x}_k$ is refined until $\boldsymbol{r}_k = \boldsymbol{b}-\boldsymbol{A}\boldsymbol{x}_k$ satisfies a given criterion. Per default numgeo checks:
  
  $\frac{||\boldsymbol{b}-\boldsymbol{A}\boldsymbol{x}_k||_2}{||\boldsymbol{b}||_2} \leq \texttt{tol}$
  
  for the BiCGStab(l) algorithm. In the BiCGStab algorithm, the residuum during the iteration process $\boldsymbol{r}_k$ is updated independent of the solution $\boldsymbol{x}_k$ (see the theory manual!), per default numgeo checks
  
  $\frac{||\boldsymbol{r}_k||_2}{||\boldsymbol{b}||_2} \leq \texttt{tol}$
  which corresponds to the option:
  check_rel_residuum. However, for the BiCGStab algorith, there are different convergence checks available for the iterative methods:
  check_rel_solution,
  check_solution,
  check_rel_residuum,
  check_residuum
  
  By default, this tolerance is tol = 10$^{-3}$ for general nonlinear procedures. The default tolerance may seem loose for general nonlinear procedures, however it is important to note that the linear solver convergence tolerance is independent of the nonlinear convergence process (i.e., Newton-Raphson method) tolerances that are used to determine if analysis increments converge.
- pc = preconditioner. Define the preconditioner to be used:
  - pc = none: no preconditioner is to be used. The iterative method solves $A b = x$. This is the default preconditioner for the BiCGStab(l) algorithm.
  - pc = diagonal: use the inverse diagonal $P_{i,i} = A_{i,i}$ as a preconditioner. The iterative method solves $P^{-1}A b = P^{-1}x$ with $(P_{i,i})^{-1} = 1/A_{i,i}$, but $P_{i,i} = 1$ if $|A_{i,i}| = 0$.
  - pc = ls-diagonal: use the least square diagonal preconditioner $P$. $P$ is derived, such that it scales the columns of $A$ to give each unit L2-norm. The iterative method solves $P^{-1}A b = P^{-1}x$. This is the default preconditioner for the BiCGStab algorithm.
- BiCGSTAB:
  - check_rel_residuum: solution is accepted, when $\frac{||\boldsymbol{r}_k||_2}{||\boldsymbol{b}||_2} \leq \texttt{tol}$ is satisfied.
  - check_residuum: solution is accepted, when $||\boldsymbol{r}_k||_2 \leq \texttt{tol}$ is satisfied. In this case, you want to choose a rather small value for the tolerance tol, e.g. tol=$10^{-9}$.
  - check_rel_solution: solution is accepted, when $\frac{||\boldsymbol{b}-\boldsymbol{A}\boldsymbol{x}_k||_2}{||\boldsymbol{b}||_2} \leq \texttt{tol}$ is satisfied. Compared to the *_residuum controls, this requires two additional AXPY-operations and two add. vector-matrix-products.
  - check_solution: solution is accepted, when $||\boldsymbol{b}-\boldsymbol{A}\boldsymbol{x}_k||_2 \leq \texttt{tol}$ is satisfied. In this case, you want to choose a rather small value for the tolerance tol, e.g. tol=$10^{-9}$. Compared to the *_residuum controls, this requires two additional AXPY-operations and two add. vector-matrix-products.
- BiCGSTAB(l) only:
  - l = integer. Define the polynomial degree of the BiCGStab(l) algorithm. By default, the minimal applicable value l=2 is used. Currently supported are l={2,3,4,5,6,7,8}.

External solver

*Solver, external, exe=$executable name$ [, mpi=<n processors>, <extrapolation>]

Use this option to interface external solvers to numgeo. For the external solver, an additional executable is required. This executable has to be placed in the same directory as the numgeo executable. And takes the following keywords:

executable: tells numgeo to use an external executable to solve the linear system.
exe=$executable name$: specify the name of the external executable.
[mpi=<n processors>]: specify the number of processors to be used. Notice that:
- for mpi=1, the use of mpi is disabled and the external executable is launched using ./executable name. This is the default.
- for mpi=n (with n $>$ 1), the executable is launched using mpirun -n executable name
[omp=<n threads>]: specify the number of (omp) threads to be used. Notice that:
- for [omp=1, the use of omp is disabled. This is the default.
- for [omp=n (with n $>$ 1), the executable is launched using export OMP_NUM_THREADS=n
[<extrapolation>] Optional. Use this keyword to specify an extrapolation strategy of the initial estimate of the solution at the beginning of each increment (except for the first one). You can choose between a linear extrapolation (extrapolation-linear), a quadratic extrapolation extrapolation-quadratic or to forbid any extrapolation (extrapolation-none, not recommended as it significantly slows down the simulation). If no extrapolation scheme is specified, a linear extrapolation is chosen.

Interfaces to some external solvers have already been developed and can be freely downloaded from
https://github.com/j-machacek/numgeo-external-solvers:

numgeo-mumps-mpi: MPI version of the [MU]{.underline}ltifrontal [M]{.underline}assively [P]{.underline}arallel sparse direct Solver, see ³.
numgeo-ilupack
numgeo-pastix

Example:
*Solver, external, exe=$numgeo-mumps-mpi$, mpi=4, omp=2

Arne De Coninck, Bernard De Baets, Drosos Kourounis, Fabio Verbosio, Olaf Schenk, Steven Maenhout, and Jan Fostier. Needles: toward large-scale genomic prediction with marker-by-environment interaction. Genetics, 203(1):543–555, 3 2016. URL: http://dx.doi.org/10.1534/genetics.115.179887, arXiv:http://www.genetics.org/content/203/1/543.full.pdf, doi:10.1534/genetics.115.179887. ↩
Drosos Kourounis, Alexander Fuchs, and Olaf Schenk. Toward the next generation of multiperiod optimal power flow solvers. IEEE Transactions on Power Systems, 33(4):4005–4014, 7 2018. URL: https://doi.org/10.1109/TPWRS.2017.2789187, doi:10.1109/tpwrs.2017.2789187. ↩
Patrick R. Amestoy, Iain S. Duff, Jean-Yves L'Excellent, and Jacko Koster. A fully asynchronous multifrontal solver using distributed dynamic scheduling. SIAM Journal on Matrix Analysis and Applications, 23(1):15–41, 1 2001. doi:10.1137/s0895479899358194. ↩↩
Patrick R. Amestoy, Abdou Guermouche, Jean-Yves L'Excellent, and Stéphane Pralet. Hybrid scheduling for the parallel solution of linear systems. Parallel Computing, 32(2):136–156, 2 2006. doi:10.1016/j.parco.2005.07.004. ↩
H. A. van der Vorst. Bi-CGSTAB: a fast and smoothly converging variant of bi-CG for the solution of nonsymmetric linear systems. SIAM Journal on Scientific and Statistical Computing, 13(2):631–644, 1992-03. Publisher: Society for Industrial & Applied Mathematics (SIAM). doi:10.1137/0913035. ↩
Gerard LG Sleijpen and Diederik R Fokkema. BiCGstab (ell) for linear equations involving unsymmetric matrices with complex spectrum. Electronic Transactions on Numerical Analysis., 1:11–32, 1993. Publisher: Kent State University. ↩
Gerard LG Sleijpen, Henk A Van der Vorst, and Diederik R Fokkema. BiCGstab (l) and other hybrid bi-cg methods. Numerical Algorithms, 7(1):75–109, 1994. Publisher: Springer. ↩
Diederik R. Fokkema. Enhanced implementation of BiCGstab(l) for solving linear systems of equations. Citeseer, 1996. ↩