The GS_ITER function solves an *n* by *n*linear system of equations using Gauss-Seidel iteration with over- and under-relaxation to enhance convergence.

**Note: **The equations must be entered in *diagonally dominant* form to guarantee convergence. A system is diagonally dominant if the diagonal element in a given row is greater than the sum of the absolute values of the non-diagonal elements in that row.

This routine is written in the IDL language. Its source code can be found in the file gs_iter.pro in the lib subdirectory of the IDL distribution.

## Example

; Define an array A:

A = [[ 1.0, 7.0, -4.0], $

[ 4.0, -4.0, 9.0], $

[12.0, -1.0, 3.0]]

; Define the right-hand side vector B:

B = [12.0, 2.0, -9.0]

; Compute the solution to the system:

RESULT = GS_ITER(A, B, /CHECK)

IDL prints:

`Input matrix is not in Diagonally Dominant form.`

`Algorithm may not converge.`

% GS_ITER: Algorithm failed to converge within given parameters.

Since the A represents a system of linear equations, we can reorder it into diagonally dominant form by rearranging the rows:

A = [[12.0, -1.0, 3.0], $

[ 1.0, 7.0, -4.0], $

[ 4.0, -4.0, 9.0]]

; Make corresponding changes in the ordering of B:

B = [-9.0, 12.0, 2.0]

; Compute the solution to the system:

RESULT = GS_ITER(A, B, /CHECK)

print, RESULT

IDL prints:

-0.999982 2.99988 1.99994

## Syntax

*Result* = GS_ITER( *A*, *B *[, /CHECK] [, /DOUBLE] [, LAMBDA=*value*{0.0 to 2.0}] [, MAX_ITER=*value*] [, TOL=*value*] [, X_0=*vector*] )

## Return Value

Returns the solution to the linear system of equations of the specified dimensions.

## Arguments

### A

An *n* by *n* integer, single-, or double-precision floating-point array. On output, *A* is divided by its diagonal elements. Integer input values are converted to single-precision floating-point values.

### B

A vector containing the right-hand side of the linear system **Ax=b**. On output, *B* is divided by the diagonal elements of *A*.

## Keywords

### CHECK

Set this keyword to check the array *A* for diagonal dominance. If *A* is not in diagonally dominant form, GS_ITER reports the fact but continues processing on the chance that the algorithm may converge.

### DOUBLE

Set this keyword to force the computation to be done in double-precision arithmetic.

### LAMBDA

A scalar value in the range: [0.0, 2.0]. This value determines the amount of *relaxation*. Relaxation is a weighting technique used to enhance convergence.

- If LAMBDA = 1.0, no weighting is used. This is the default.
- If 0.0 ≤ LAMBDA < 1.0, convergence improves in oscillatory and non-convergent systems.
- If 1.0 < LAMBDA ≤ 2.0, convergence improves in systems already known to converge.

### MAX_ITER

The maximum allowed number of iterations. The default value is 30.

### TOL

The relative error tolerance between current and past iterates calculated as: |( (current-past)/current )|. The default is 1.0 ∞ 10^{-4}.

### X_0

An *n*-element vector that provides the algorithm’s starting point. The default is [1.0, 1.0, ... , 1.0].

## Version History

Pre 4.0 |
Introduced |

## See Also

CRAMER, LU_COMPLEX, CHOLSOL, LUSOL, SVSOL, TRISOL