S3L_gen_trid_factor

Description

S3L_gen_trid_factor factors a tridiagonal matrix, whose diagonal is stored in vector D. The first upper subdiagonal is stored in U, and the first lower subdiagonal in L.

On return, the integer factors contains a pointer to an internal setup structure that holds the factorization. Subsequent calls to S3L_gen_trid_solve use the value in factors to access the factorization results.

The contents of the vectors D, U, and L may be altered. These altered vectors, along with the factors parameter, have to be passed to a subsequent call to S3L_gen_trid_solve to produce the solution to a tridiagonal system.

D, U, and L must have the same extents and type. If they are one-dimensional, all three must be of length n. The first n-1 entries of U contain the elements of the superdiagonal. The last n-1 entries of L contain the elements of the first subdiagonal. The last element of U and the first element of L are not referenced and can be initialized arbitrarily.

If D, U and L have more than one dimension, axis_d is the axis along which the multidimensional arrays are factored. If they are one-dimensional, axis_d must be 0 in C/C++ programs and 1 in F77/F90 programs.

S3L_gen_trid_factor is based on the ScaLAPACK routines pxdttrf, where x is single, double, complex, or double complex. It does no pivoting; consequently, the matrix has to be positive definite for the factorization to be stable.

For one-dimensional arrays, the routine is more efficient when D, U, and L are block distributed. For multiple dimensions, the routine is more efficient when axis_d is a local axis.

Syntax

The C and Fortran syntax for S3L_gen_trid_factor are shown below.

C/C++ Syntax

Example 8-59

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

F77/F90 Syntax

Example 8-60

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

Input

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

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

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

• 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 the arrays are factored.

Output

This function uses the following arguments for output:

• D - On output, D is overwritten with the partial result of the factorization.

• U - On output, U is overwritten with the partial result of the factorization.

• L - On output, L is overwritten with the partial result of the factorization.

• factors - Upon completion, factors points to the internal data structure containing the factorization results.

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

Error Handling

On success, S3L_gen_trid_factor returns S3L_SUCCESS.

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

• S3L_ERR_MATCH_RANK - The arrays do not have the same rank.

• S3L_ERR_MATCH_EXTENTS - The arrays do not have the same 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.

• S3L_ERR_FACTOR_FAIL - The tridiagonal matrix could not be factored for some reason. For example, it might not be diagonally dominant.

Examples

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

Related Functions

S3L_gen_trid_solve(3)
S3L_gen_trid_free_factors(3)