S3L_gen_band_solve

Description

S3L_gen_band_solve solves a banded system whose factorization has been computed by a prior call to S3L_gen_band_factor.

The factored banded matrix is stored in array a, whose dimensions are 2*bu + 2*bl + 1 x n. The right-hand-side is stored in array b, whose dimensions are n x nrhs.

If a and b have more than two dimensions, axis_r and axis_d refer to those axes of a whose extents are 2*bu + 2*bl + 1 and n, respectively. Likewise, axis_row and axis_col refer to the axes of b with extents n and nrhs.

Array Layout Guidelines

Two-Dimensional Arrays: If a and b are two-dimensional, S3L_gen_band_solve is more efficient when axis_r = 0, axis_d = 1, array a is block distributed along axis 1, axis_row = 0, axis_col = 1 and array b is block distributed along axis 0.

Note that the values cited in the previous paragraph apply to programs using the C/C++ interface--that is, they assume zero-based array indexing. When S3L_gen_band_solve is called from F77 or F90 applications, these values must be increased by one. Therefore, when a and b are two-dimensional and S3L_gen_band_solve is called by a Fortran program, the solver is more efficient when axis_r = 1, axis_d = 2, array a is block distributed along axis 2, axis_row = 1, axis_col = 2 and array b is block distributed along axis 1.

When a and b are two-dimensional and nrhs is greater than 1, the size of a must be such that n is divisible by the number of processors.

Arrays With More Than Two Dimensions: If a and b have more than two dimensions, S3L_gen_band_solve is more efficient when axes axis_r and axis_d of a and axes axis_row and axis_col are local (not distributed).

Syntax

The C and Fortran syntax for S3L_gen_band_solve are shown below.

C/C++ Syntax

Example 8-57

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_gen_band_solve(a, bl, bu, factors, axis_r, axis_d, b, axis_row,
axix_col)
    S3L_array_t       a
    int               bl
    int               bu
    int               *factors
    int               axis_r
    int               axis_d
    S3L_array_t       b
    int               axis_row
    int               axis_col

F77/F90 Syntax

Example 8-58

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

Input

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

• bl - Lower bandwidth of a.

• bu - Upper bandwidth of a.

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

• axis_r - Specifies the axis of array a whose extent is 1+2*bl+2*bu+1

• axis_d - Specifies the axis of array a whose extent is n.

• b - S3L array handle containing the right-hand side of the matrix equation ax=b.

Output

This function uses the following argument for output:

• b - On output, b is overwritten by the solution to the matrix equation ax=b.

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

Error Handling

On success, S3L_gen_band_solve returns S3L_SUCCESS.

S3L_gen_band_solve 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:

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

  • It is 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:

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

  • Greater than the rank of the referenced array

  • axis_d is equal to axis_r.

• S3L_ERR_MATCH_RANK - The rank of a is not the same as that of b.

• S3L_ERR_ARG_SETUP - The factors value does not correspond to a valid setup.

• S3L_ERR_MATCH_EXTENTS - The extents of a along axis_d do not equal the extents of b along axis_row or some of the other extents of a and b do not match.

Examples

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

Related Functions

S3L_gen_band_factor(3)
S3L_gen_band_free_factors(3)