?gtsvx

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 3/22/2024

Version

Public

Visible to Intel only — GUID: GUID-D4CAE7DE-83FF-476D-A3E0-0B647FBE853C

View Details

?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, A^T*X = B, or A^H*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:

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.
If some U_i,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.
The system of equations is solved for X using the factored form of A.
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 `AX = B` (No transpose). If `trans = 'T'`, the system has the form `A`^T`X` = `B` (Transpose). If `trans = 'C'`, the system has the form `A`^H`*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(ldbnrhs) for column major layout and max(ldbn) 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 `ldb`≥nrhs for row major layout.
ldx	The leading dimension of `x`; ldx≥ max(1, n) for column major layout and `ldx`≥nrhs 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, ldxnrhs) for column major layout and max(1, ldxn) 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 `x`_j (the `j`-th column of the solution matrix `X`). If `xtrue` is the true solution corresponding to `x`_j, `ferr[j-1]` is an estimated upper bound for the magnitude of the largest element in `x`_j - `xtrue` divided by the magnitude of the largest element in `x`_j. 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 `x`_j, that is, the smallest relative change in any element of `A` or `B` that makes `x`_j 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 i≤n, then U_{i, 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.

Parent topic: LAPACK Linear Equation Driver Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

?gtsvx

Syntax

Include Files

Description

Input Parameters

Output Parameters

Return Values

See Also