S3L_gen_band_factor

Description

S3L_gen_band_factor performs the LU factorization of an n x n general banded array with lower bandwidth bl and upper bandwidth bl. The non-zero diagonals of the array should be stored in an S3L array a of size [2*bl+2*bu+1,n].

In the more general case, a can be a multidimensional array, where axis_r and axis_d denote the array axes whose extents are 2*bl+2*bu+1 and n respectively. The format of the array a is described in the following example:

Example:

Consider a 7 x 7 (n=7) banded array with bl = 1, bu = 2. c is the main diagonal, b is the first superdiagonal and a the second. d is the first subdiagonal. The contents of the composite array a used as input to S3L_gen_band_factor should have the following organization:

Example 8-52

 *   *   *   *   *   *   *
 *   *   *   *   *   *   *
 *   *   *   *   *   *   *
 *   *  a0  a1  a2  a3  a4
 *  b0  b1  b2  b3  b4  b5
c0  c1  c2  c3  c4  c5  c6
d0  d1  d2  d3  d4  d5   *

Note that, items denoted by '*' are not referenced.

If a is two-dimensional, S3L_gen_band_factor is more efficient when axis_r is the first axis, axis_d is the second axis, and array a is block-distributed along the second axis. For C programs, the indices of the first and second axes are 0 and 1, respectively. For Fortran programs, the corresponding indices are 1 and 2.

If a has more than two dimensions, S3L_gen_band_factor is most efficient when axes axis_r and axis_d of a are local (that is, are not distributed).

Syntax

The C and Fortran syntax for S3L_gen_band_factor are shown below.

C/C++ Syntax

Example 8-53

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_gen_band_factor(a, bl, bu, factors, axis_r, axis_d)
    S3L_array_t       a
    int               bl
    int               bu
    int               *factors
    int               axis_r
    int               axis_d

F77/F90 Syntax

Example 8-54

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_gen_band_factor(a, bl, bu, factors, axis_r, axis_d, ier)
    integer*4          a
    integer*4         bl
    integer*4         bu
    integer*4         factors
    integer*4         axis_r
    integer*4         axis_d
    integer*4          ier

Input

• a - S3L array handle for a real or complex parallel array of size [1+2*bl+2*bl,N].

• bl - Lower bandwidth of a.

• bu - Upper bandwidth of a.

• axis_r - Specifies the row axis along which factorization will occur.

• axis_d - Specifies the column axis along which factorization will occur.

Output

This function uses the following arguments for output:

• a - Upon successful completion, S3L_gen_band_factor stores the factorization results in a.

• factors - Pointer to an internal structure that holds the factorization.

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

Error Handling

On success, S3L_gen_band_factor returns S3L_SUCCESS.

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

In addition, the following conditions will cause the function to terminate and return the associated error code:

• S3L_ERR_ARG_DTYPE - The type of a is not one of: real, double, complex or double complex.

• S3L_ERR_INDX_INVALID - bl or bu value is invalid for either of the following reasons:

  • Less than 0 (C/C++) or less than 1 (F77/F90).

  • Greater than the extent of a along axis_d.

• S3L_ERR_ARG_EXTENTS - The extent of a along axis axis_r is not equal to 2*bl+2*bu+1.

• S3L_ERR_ARRTOOSMALL - The extents of a along axis axis_d are such that the block size in a block distribution is less than bu + bl + 1.

• S3L_ERR_ARG_AXISNUM - An axis argument is invalid; that is, it is either:

  • It is less than 0 (C/C++) or less than 1 (F77/F90).

  • It is greater than the rank of the referenced array.

  • axis_d is equal to axis_r.

• S3L_ERR_BAND_FFAIL - The factorization could not be completed.

Examples

../examples/s3l/band/ex_band.c
../examples/s3l/band-f/ex_band.f

Related Functions

S3L_gen_band_solve(3)
S3L_gen_band_free_factors(3)