Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

?gtsvx

Computes the solution to the real or complex system of linear equations with a tridiagonal coefficient matrix A and multiple right-hand sides, and provides error bounds on the solution.

Syntax

lapack_int LAPACKE_sgtsvx( int matrix_layout, char fact, char trans, lapack_int n, lapack_int nrhs, const float* dl, const float* d, const float* du, float* dlf, float* df, float* duf, float* du2, lapack_int* ipiv, const float* b, lapack_int ldb, float* x, lapack_int ldx, float* rcond, float* ferr, float* berr );

lapack_int LAPACKE_dgtsvx( int matrix_layout, char fact, char trans, lapack_int n, lapack_int nrhs, const double* dl, const double* d, const double* du, double* dlf, double* df, double* duf, double* du2, lapack_int* ipiv, const double* b, lapack_int ldb, double* x, lapack_int ldx, double* rcond, double* ferr, double* berr );

lapack_int LAPACKE_cgtsvx( int matrix_layout, char fact, char trans, lapack_int n, lapack_int nrhs, const lapack_complex_float* dl, const lapack_complex_float* d, const lapack_complex_float* du, lapack_complex_float* dlf, lapack_complex_float* df, lapack_complex_float* duf, lapack_complex_float* du2, lapack_int* ipiv, const lapack_complex_float* b, lapack_int ldb, lapack_complex_float* x, lapack_int ldx, float* rcond, float* ferr, float* berr );

lapack_int LAPACKE_zgtsvx( int matrix_layout, char fact, char trans, lapack_int n, lapack_int nrhs, const lapack_complex_double* dl, const lapack_complex_double* d, const lapack_complex_double* du, lapack_complex_double* dlf, lapack_complex_double* df, lapack_complex_double* duf, lapack_complex_double* du2, lapack_int* ipiv, const lapack_complex_double* b, lapack_int ldb, lapack_complex_double* x, lapack_int ldx, double* rcond, double* ferr, double* berr );

Include Files

  • mkl.h

Description

The routine uses the LU factorization to compute the solution to a real or complex system of linear equations A*X = B, AT*X = B, or AH*X = B, where A is a tridiagonal matrix of order n, the columns of matrix B are individual right-hand sides, and the columns of X are the corresponding solutions.

Error bounds on the solution and a condition estimate are also provided.

The routine ?gtsvx performs the following steps:

  1. If fact = 'N', the LU decomposition is used to factor the matrix A as A = L*U, where L is a product of permutation and unit lower bidiagonal matrices and U is an upper triangular matrix with nonzeroes in only the main diagonal and first two superdiagonals.

  2. If some Ui,i= 0, so that U is exactly singular, then the routine returns with info = i. Otherwise, the factored form of A is used to estimate the condition number of the matrix A. If the reciprocal of the condition number is less than machine precision, info = n + 1 is returned as a warning, but the routine still goes on to solve for X and compute error bounds as described below.

  3. The system of equations is solved for X using the factored form of A.

  4. Iterative refinement is applied to improve the computed solution matrix and calculate error bounds and backward error estimates for it.

Input Parameters

matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

fact

Must be 'F' or 'N'.

Specifies whether or not the factored form of the matrix A has been supplied on entry.

If fact = 'F': on entry, dlf, df, duf, du2, and ipiv contain the factored form of A; arrays dl, d, du, dlf, df, duf, du2, and ipiv will not be modified.

If fact = 'N', the matrix A will be copied to dlf, df, and duf and factored.

trans

Must be 'N', 'T', or 'C'.

Specifies the form of the system of equations:

If trans = 'N', the system has the form A*X = B (No transpose).

If trans = 'T', the system has the form AT*X = B (Transpose).

If trans = 'C', the system has the form AH*X = B (Conjugate transpose).

n

The number of linear equations, the order of the matrix A; n 0.

nrhs

The number of right hand sides, the number of columns of the matrices B and X; nrhs 0.

dl,d,du,dlf,df, duf,du2,b

Arrays:

dl, size (n -1), contains the subdiagonal elements of A.

d, size (n), contains the diagonal elements of A.

du, size (n -1), contains the superdiagonal elements of A.

dlf, size (n -1). If fact = 'F', then dlf is an input argument and on entry contains the (n -1) multipliers that define the matrix L from the LU factorization of A as computed by ?gttrf.

df, size (n). If fact = 'F', then df is an input argument and on entry contains the n diagonal elements of the upper triangular matrix U from the LU factorization of A.

duf, size (n -1). If fact = 'F', then duf is an input argument and on entry contains the (n -1) elements of the first superdiagonal of U.

du2, size (n -2). If fact = 'F', then du2 is an input argument and on entry contains the (n-2) elements of the second superdiagonal of U.

b, size max(ldb*nrhs) for column major layout and max(ldb*n) for row major layout, contains the right-hand side matrix B.

ldb

The leading dimension of b; ldb max(1, n) for column major layout and ldbnrhs for row major layout.

ldx

The leading dimension of x; ldx max(1, n) for column major layout and ldxnrhs for row major layout.

ipiv

Array, size at least max(1, n). If fact = 'F', then ipiv is an input argument and on entry contains the pivot indices, as returned by ?gttrf.

Output Parameters

x

Array, size max(1, ldx*nrhs) for column major layout and max(1, ldx*n) for row major layout.

If info = 0 or info = n+1, the array x contains the solution matrix X.

dlf

If fact = 'N', then dlf is an output argument and on exit contains the (n-1) multipliers that define the matrix L from the LU factorization of A.

df

If fact = 'N', then df is an output argument and on exit contains the n diagonal elements of the upper triangular matrix U from the LU factorization of A.

duf

If fact = 'N', then duf is an output argument and on exit contains the (n-1) elements of the first superdiagonal of U.

du2

If fact = 'N', then du2 is an output argument and on exit contains the (n-2) elements of the second superdiagonal of U.

ipiv

The array ipiv is an output argument if fact = 'N'and, on exit, contains the pivot indices from the factorization A = L*U ; row i of the matrix was interchanged with row ipiv[i-1]. The value of ipiv[i-1] will always be i or i+1; ipiv[i-1]=i indicates a row interchange was not required.

rcond

An estimate of the reciprocal condition number of the matrix A. If rcond is less than the machine precision (in particular, if rcond =0), the matrix is singular to working precision. This condition is indicated by a return code of info>0.

ferr

Array, size at least max(1, nrhs). Contains the estimated forward error bound for each solution vector xj (the j-th column of the solution matrix X). If xtrue is the true solution corresponding to xj, ferr[j-1] is an estimated upper bound for the magnitude of the largest element in xj - xtrue divided by the magnitude of the largest element in xj. The estimate is as reliable as the estimate for rcond, and is almost always a slight overestimate of the true error.

berr

Array, size at least max(1, nrhs). Contains the component-wise relative backward error for each solution vector xj, that is, the smallest relative change in any element of A or B that makes xj an exact solution.

Return Values

This function returns a value info.

If info = 0, the execution is successful.

If info = -i, parameter i had an illegal value.

If info = i, and in, then Ui, i is exactly zero. The factorization has not been completed unless i = n, but the factor U is exactly singular, so the solution and error bounds could not be computed; rcond = 0 is returned. If info = i, and i = n + 1, then U is nonsingular, but rcond is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of rcond would suggest.