Welcome to the L3 Harris Geospatial documentation center. Here you will find reference guides and help documents.
﻿

### IMSL_LUSOL

IMSL_LUSOL

The IMSL_LUSOL function solves a general system of real or complex linear equations Ax = b.

The IMSL_LUSOL function solves a system of linear algebraic equations with a real or complex coefficient matrix A. Any of several related computations can be performed by using keywords. These extra tasks include solving AHx = b or computing the solution of Ax = b given the LU factorization of A. The function first computes the LU factorization of A with partial pivoting such that L–1PA = U.

The matrix U is upper-triangular, while L–1A ≡ Pn – 1 Ln – 2Pn – 2...L0 P0 A ≡ U. The factors Pi and Li are defined by the partial pivoting. Each Pi is an interchange of row i with row j ≥ i. Thus, Pi is defined by that value of j. Every Li = miei T is an elementary elimination matrix. The vector mi is zero in entries 0, ... , i – 1. This vector is stored as column i in the strictly lower-triangular part of the working matrix containing the decomposition information.

The factorization efficiency is based on a technique of “loop unrolling and jamming” by Dr. Leonard J. Harding of the University of Michigan, Ann Arbor, Michigan. The solution of the linear system is then found by solving two simpler systems, y = L–1b and x = U–1y. When the solution to the linear system or the inverse of the matrix is sought, an estimate of the L1 condition number of A is computed using the same algorithm as in Dongarra et al. (1979). If the estimated condition number is greater than 1/ε (where ε is the machine precision), a warning message is issued. This indicates that very small changes in A may produce large changes in the solution x. The IMSL_LUSOL function fails if U, the upper-triangular part of the factorization, has a zero diagonal element.

## Examples

### Example 1

This example solves a system of three linear equations. This is the simplest use of the function. The equations are as follows:

x0 + 3x1 + 3x2 = 1

x0 + 3x1 + 4x2 = 4

x0 + 4x1 + 3x2 = –1

` `
`RM, a, 3, 3`
`; Input a matrix containing the coefficients.`
`row 0: 1 3 3`
`row 1: 1 3 4`
`row 2: 1 4 3`
`RM, b, 3, 1`
` `
`; Input a vector containing the right-hand side.`
`row 0: 1`
`row 1: 4`
`row 2: -1`
`x = IMSL_LUSOL(b, a)`
` `
`; Call IMSL_LUSOL to compute the solution.`
`PM, x, Title = 'Solution'`
` `
`; Print solution and residual.`
`Solution`
`  -2.00000`
`  -2.00000`
`  3.00000`
`PM, a # x - b, Title = 'Residual'`
`Residual`
`  0.00000`
`  0.00000`
`  0.00000`

### Example 2

This example solves the transpose problem AHx = b.

`RM, a, 3, 3`
`; Input the matrix containing the coefficients.`
`row 0: 1 3 3`
`row 1: 1 3 4`
`row 2: 1 4 3`
`RM, b, 3, 1`
`; Input the vector containing the right-hand side.`
`row 0: 1`
`row 1: 4`
`row 2: -1`
`x = IMSL_LUSOL(b, a, /Transpose)`
`; Call IMSL_LUSOL with keyword Transpose set.`
`PM, x, Title = 'Solution'`
`; Print the solution and the residual.`
`Solution`
`  4.00000`
`  -4.00000`
`  1.00000`
`PM, TRANSPOSE(a) # x - b, Title = 'Residual'`
`Residual`
`  0.00000`
`  0.00000`
`  0.00000`

### Example 3

This example computes the solution of two systems. Only the right-hand sides differ. The matrix and first right-hand side are given in the initial example. The second right-hand side is the vector c = [0.5, 0.3, 0.4]T. The factorization information is computed by the IMSL_LUFAC procedure and is used to compute the solutions in calls to IMSL_LUSOL.

`RM, a, 3, 3`
`; Input the coefficient matrix.`
`row 0: 1 3 3`
`row 1: 1 3 4`
`row 2: 1 4 3`
`RM, b, 3, 1`
`; Input the first right-hand side.`
`row 0: 1`
`row 1: 4`
`row 2: -1`
`RM, c, 3, 1`
`; Input the second right-hand side.`
`row 0: .5`
`row 1: .3`
`row 2: .4`
`IMSL_LUFAC, a, pvt, fac`
`; Call IMSL_LUFAC to factor the coefficient matrix.`
`x = IMSL_LUSOL(b, Factor = fac, Pivot = pvt)`
`; Call IMSL_LUSOL with factored form of the coefficient`
`; matrix and the first right-hand side.`
`PM, x, Title = 'Solution'`
`; Print the solution of Ax = b.`
`Solution`
`  -2.00000`
`  -2.00000`
`  3.00000`
`PM, a # x - b, Title = 'Residual'`
`Residual`
`  0.00000`
`  0.00000`
`  0.00000`
`y = IMSL_LUSOL(c, Factor = fac, Pivot = pvt)`
`; Call IMSL_LUSOL with factored form of the coefficient`
`; matrix and the second right-hand side.`
`PM, y, Title = 'Solution'`
`; Print the solution of Ax = b.`
`Solution`
`  1.40000`
`  -0.100000`
`  -0.200000`
`PM, a # y - c, \$`
`Title = 'Residual', Format = '(f8.5)'`
`Residual`
`  0.00000`
`  0.00000`
`  0.00000`

## Syntax

Result = IMSL_LUSOL( B, A, [, CONDITION=variable] [, /DOUBLE] [, FACTOR=variable] [, INVERSE=variable] [, PIVOT=variable] [, TRANSPOSE=value])

## Return Value

A one-dimensional array containing the solution of the linear system Ax = b.

## Arguments

### B

One-dimensional matrix containing the right-hand side.

### A

Two-dimensional matrix containing the coefficient matrix. Element A(i, j) contains the j-th coefficient of the i-th equation.

## Keywords

### CONDITION (optional)

Named variable into which an estimate of the L1 condition number is stored. This keyword cannot be used with keywords PIVOT and FACTOR.

### DOUBLE (optional)

If present and nonzero, double precision is used.

### FACTOR (optional)

Named variable in which the LU factorization of A, computed by the IMSL_LUFAC procedure, is stored. The strictly lower-triangular part of this array contains information necessary to construct L, and the upper-triangular part contains U. The PIVOT and FACTOR keywords must be used together. The FACTOR and CONDITION keywords cannot be used together.

### INVERSE (optional)

Named variable into which the inverse of the matrix A is stored.

### PIVOT (optional)

Named variable into which the pivot sequence for the factorization, computed by the IMSL_LUFAC procedure, is stored. The PIVOT and FACTOR keywords must be used together. The PIVOT and CONDITION keywords cannot be used together.

### TRANSPOSE (optional)

If present and nonzero, AH x = b is solved.

## Errors

### Warning Errors

MATH_ILL_CONDITIONED: Input matrix is too ill-conditioned. An estimate of the reciprocal of its L1 condition number is #. The solution might not be accurate.

### Fatal Errors

MATH_SINGULAR_MATRIX: Input matrix is singular.

## Version History

 6.4 Introduced