# Linear Solver Accuracy

Linear solver errors are especially troublesome when the condition of
the dynamic matrix is high. This can be caused by various sources.

- Singular mass matrices.

- Lack of a large shift for floating structures.

- Some complex constraint systems.

- Connection of very stiff and very compliant materials.

- Large concentrated masses.

- Poor decomposition, which affect the preconditioner and convergence
  rate.

- Redundant and/or conflicting constraints.

Any of these items can impact the linear solver sufficient to cause
solution failure.

When using the GDSW solver, information on solver accuracy is readily
obtained from `dd_solver.dat`, which is written by default. The output
below provides an example of a portion of this file. The top portion of
the file contains information about the general solution. The operator
diagonal magnitudes provide a lower bound on the condition of the
matrix, in this case 448463. Condition numbers up to 1.e14 are solvable.
Higher condition numbers are rarely solvable. The condition numbers are
determined *after* application of the MPCs.

The default name of this file can be overridden by the
`dd_solver_output_file` option in the GDSW section. Likewise, the
default name of the Krylov solver output file ("krylov_solver.dat") can
be overridden with the `krylov_solver_output_file` option.

Rigid body norms are then reported. Each row is the product, $|A R_j|$,
where $R_j$ is the geometrically determined rigid body vector, and $A$
is the dynamic matrix[^1]. Low values for these norms may indicate
singularity.

The lower portion of the file provides information about each linear
solve. The "recursive relative residual" is computed indirectly as part
of the solution. It is used to control the solution. At the end of the
solution, an "actual relative residual" is computed, $r_a = |Ax-b|/|b|$.
Large differences between relative and actual residuals are a concern
that the solution may lack accuracy.

The solver is designed to reduce the relative residual to a low
tolerance. This residual relates to the error in force in a statics
problem. The error in displacement, $\delta x$, may be more important
for many applications. This error in the displacement depends on
$\kappa$, the condition of $A$, and the relative residual. It is not
directly computed nor reported.

$$
\frac{\delta x}{|x|} \leq \kappa r_a
$$

:::{output}
  --- domain decomposition solver summary ---
  preconditioner                  = GDSW
  Krylov method                   = Right GMRES
  solver option                   = Esmond
  number of processors            = 1
  ...
  solver tolerance                = 1e-09
  maximum number of iterations    = 11
  maximum number of restarts      = 1
  maximum stored directions       = 0
  solving scaled problem          = no
  operator diagonal magnitudes -
  min                             = 31145.6
  max                             = 1.39676e+10
  max/min                         = 448463
  Rigid Body Norm for Mode 1      = 0.0123875
  Rigid Body Norm for Mode 2      = 8.43938e-07
  Rigid Body Norm for Mode 3      = 0.012616
  Rigid Body Norm for Mode 4      = 0.00206949
  Rigid Body Norm for Mode 5      = 0.000878705
  Rigid Body Norm for Mode 6      = 0.00423774
  coarse space type               = large
  number of coarse levels         = 0
  solver initialization time      = 0.0306559 seconds

                             Recursive       Actual
                              Relative     Relative
  Solve  Iter  Total  Avg     Residual     Residual     CPU (s)   Total (s)     Avg (s)
      1     1      1    1  7.22136e-12  1.16949e-11  0.00170898  0.00170898  0.00170898
      2     1      2    1  4.55332e-12   1.7662e-11  0.00142002  0.00312901   0.0015645
      3     1      3    1   8.1699e-13  7.89586e-13  0.00141907  0.00454807  0.00151602
      4     1      4    1  5.69584e-14  5.92117e-14  0.00142908  0.00597715  0.00149429
    ...
     39     1     39    1  2.51249e-14  2.34535e-14  0.00145912   0.0559211  0.00143387
     40     1     40    1  2.08119e-14  2.18612e-14  0.00142503   0.0573461  0.00143365

  total time for overlap preconditioner (seconds) = 0.0491779
:::

[^1]: For eigenvalue problems, $A=K-\sigma M$, where $\sigma$ is the
    shift.
