S3L_gen_trid_solve

Description

S3L_gen_trid_solve solves a tridiagonal system that has been previously factored via a call to S3L_gen_trid_factor.

If D, U, and L are of length n, B (the right-hand side of the tridiagonal system) must be of size n x nrhs. If D, U, and L are multidimensional, axis_d is the axis along which the system is solved. The rank of B must be one greater than the rank of D, U, and L.

If the rank of B is greater than 2, row_b and col_b specify the axes whose dimensions are n and nrhs, respectively. The extents of all other axes must be the same as the corresponding axes of D, U, and L.

When computing multiple tridiagonal systems in which only the right-hand-side matrix changes, the factorization routine S3L_gen_trid_factor need only be called once, before the first call to S3l_gen_trid_solve. Then, S3L_gen_trid_solve can be called repeatedly without calling S3L_gen_trid_factor again.

Syntax

The C and Fortran syntax for S3L_gen_trid_solve are shown below.

C/C++ Syntax

Example 8-63

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_gen_trid_solve(D, U, L, factors, B, row_b, col_b)
    S3L_array_t       D
    S3L_array_t       U
    S3L_array_t       L
    int               *factors
    S3L_array_t       B
    int               axis_d
    int               axis_d
    int               row_b

F77/F90 Syntax

Example 8-64

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_gen_trid_solve(D, U, L, factors, B, axis_d, row_b, col_b, ier)
    integer*8         D
    integer*8         U
    integer*8         L
    integer*4         factors
    integer*8         B
    integer*4         axis_d
    integer*4         row_b
    integer*4         col_b
    integer*4          ier

Input

• D - Vector containing the diagonal for the matrix being factored.

• U - Vector containing the first upper subdiagonal for the matrix being factored.

• L - Vector containing the first lower subdiagonal for the matrix being factored.

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

• B - The right-hand side of the tridiagonal system to be solved.

• axis_d - When D, U, and L are one-dimensional, axis_d must be 0 (C/C++ programs) or 1 (F77/F90 programs). For multidimensional arrays, axis_d specifies the axis along which factorization was carried out.

• row_b - Indicates the row axis of the right-hand side array, B. The value of row_b depends on the following:

  • When B is two-dimensional and its sides are n x nrhs, row_b is 0 (C/C++) or 1 (F77/F90).

  • When B is two-dimensional and its sides are nrhs x n, row_b is 1 (C/C++) or 2 (F77/F90).

  • When B has more than two dimensions, row_b identifies the side of B with an extent of n. For C/C++ programs, the row_b value is zero-based and for F77/F90 programs, it is one-based.

  • col_b - Indicates the column axis of the right-hand side array, B that has an extent of nrhs. The value of col_b is determined as follows:

    • When B is two-dimensional and its sides are n x nrhs, col_b is 1 (C/C++) or 2 (F77/F90).

    • When B is two-dimensional and its sides are nrhs x n, col_b is 0 (C/C++) or 1 (F77/F90).

    • When B has more than two dimensions, col_b identifies the side of B with an extent of nhrs. For C/C++ programs, the col_b value is zero-based and for F77/F90 programs, it is one-based.

Output

This function uses the following argument for output:

• B - On output, B is overwritten with the solution to the tridiagonal system.

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

Error Handling

On success, S3L_gen_trid_solve returns S3L_SUCCESS.

S3L_gen_trid_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_MATCH_DTYPE - The arrays are not the same data type.

• S3L_ERR_MATCH_RANK - The arrays do not have compatible rank.

• S3L_ERR_MATCH_EXTENTS - The arrays do not have compatible extents.

• S3L_ERR_ARG_DTYPE - The array type cannot be operated on by the routine (that is, it is integer or long long).

• S3L_ERR_ARRTOOSMALL - The array extent is too small, making the length of the main diagonal less than two times the number of processes.

• 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.

  • row_b is equal to col_b.

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

Examples

../examples/s3l/trid/ex_trid.c
../examples/s3l/trid-f/ex_trid.f

Related Functions

S3L_gen_trid_factor(3)
S3L_gen_trid_free_factors(3)