S3l_lu_invert

Description

S3L_lu_invert uses the LU factorization generated by S3L_lu_factor to compute the inverse of each square (M x M) matrix instance A of the parallel array a. This is done by inverting U and then solving the system A^-1L = U^-1 for A^-1, where A^-1 and U^-1 denote the inverse of A and U, respectively.

In general, S3L_lu_invert performs most efficiently when the array  is distributed using the same block size along each axis.

For arrays with rank > 2, the nodal inversion is applied on each of the 2D slices of a across the instance axis and is performed concurrently on all participating processes.

The internal variable setup_id is required for communicating information between the factorization routine and the other LU routines. The application must not modify the contents of this variable.

Syntax

The C and Fortran syntax for S3L_lu_invert are shown below.

C/C++ Syntax

Example 8-25

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_lu_invert(a, setup_id)
    S3L_array_t               a
    int                       setup_id

F77/F90 Syntax

Example 8-26

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_lu_invert(a, setup_id, ier)
    integer*8               a
    integer*4               setup_id
    integer*4               ier

Input

• a - Parallel array that was factored by S3L_lu_factor, where each matrix instance A is a dense M x M square matrix. Supply the same value a that was used in S3L_lu_factor.

• setup_id - Scalar integer variable. Use the value returned by the corresponding S3L_lu_factor call for this argument.

Output

This function uses the following arguments for output:

• a - Upon successful completion, each matrix instance A is overwritten with data giving the corresponding LU factors.

• setup_id - Scalar integer variable returned by S3L_lu_factor. It can be used when calling other LU routines to reference the LU-factored array.

• ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_lu_invert returns S3L_SUCCESS.

S3L_lu_invert performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and returns an error code indicating which value was invalid. See Appendix A of this manual for a detailed list of these error codes.

The following conditions will cause the function to terminate and return the associated error code:

• S3L_ERR_ARG_NULL - Invalid array; must be the same value returned by S3L_lu_factor.

• S3L_ERR_ARG_SETUP - Invalid setup_id.

• S3L_ERR_FACTOR_SING - a contains singular factors; its inverse could not be computed.

Examples

../examples/s3l/lu/lu.c
../examples/s3l/lu/ex_lu1.c
../examples/s3l/lu/ex_lu2.c
../examples/s3l/lu-f/lu.f
../examples/s3l/lu-f/ex_lu1.f

Related Functions

S3L_lu_factor(3)
S3L_lu_invert(3)
S3L_lu_solve(3)