S3l_lu_factor

Description

For each M x N coefficient matrix A of a, S3L_lu_factor computes the LU factorization using partial pivoting with row interchanges.

The factorization has the form A = P x L x U, where P is a permutation matrix, L is lower triangular with unit diagonal elements (lower trapezoidal if M > N), and U is upper triangular (upper trapezoidal if M < N). L and U are stored in A.

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

S3L_lu_factor behaves somewhat differently for 3D arrays, however. In this case, it applies nodal LU factorization on each M x N coefficient matrix across the instance axis. This factorization is performed concurrently on all participating processes.

You must call S3L_lu_factor before calling any of the other LU routines. The S3L_lu_factor routine performs on the preallocated parallel array and returns a setup ID. You must supply this setup ID in subsequent LU calls, as long as you are working with the same set of factors.

Be sure to call S3L_deallocate_lu when you have finished working with a set of LU factors. See "S3l_lu_deallocate " for details.

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_factor are shown below.

C/C++ Syntax

Example 8-23

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_lu_factor(a, row_axis, col_asix, setup_id)
    S3L_array_t               A
    int                       row_axis
    int                       col_axis
    int                       *setup_id
    S3L_data_type             type
    char                      *fname
    char                      *dfmt

F77/F90 Syntax

Example 8-24

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

Input

• a - Parallel array of rank greater than or equal to 2. This array contains one or more instances of a coefficient matrix A to be factored. Each A is assumed to be dense with dimensions M x N with rows counted by axis row_axis and columns counted by axis col_axis.

• row_axis - Scalar integer variable. Identifies the axis of a that counts the rows of each matrix A. For C program calls, row_axis must be >= 0 and less than the rank of a; for Fortran program calls, it must be >= 1 and not exceed the rank of a. In addition, row_axis and col_axis must not be equal.

• col_axis - Scalar integer variable. Identifies the axis of a that counts the columns of each matrix A. For C program calls, col_axis must be >= 0 and less than the rank of a; for Fortran program calls, it must be >= 1 and not exceed the rank of a. In addition, row_axis and col_axis must not be equal.

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_factor returns S3L_SUCCESS.

S3L_lu_factor 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_RANK - Invalid rank; must be >= 2.

• S3L_ERR_ARG_BLKSIZE - Invalid blocksize; must be >= 1.

• S3L_ERR_ARG_DTYPE - Invalid data type. It must be real or complex (single- or double-precision).

• S3L_ERR_ARG_NULL - Invalid array. a must be preallocated.

• S3L_ERR_ARG_AXISNUM - row_axis or col_axis is invalid. This condition can be caused by either an out-of-range axis number (see row_axis and col_axis argument definitions) or row_axis equal to col_axis.

• S3L_ERR_FACTOR_SING - A singular factor U is returned. If it is used by S3L_lu_solve, division by zero will occur.

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_deallocate(3)
S3L_lu_invert(3)
S3L_lu_solve(3)