diff --git a/src/c/cgbcon.c b/src/c/cgbcon.c index 1d1b8802..27e74b3d 100644 --- a/src/c/cgbcon.c +++ b/src/c/cgbcon.c @@ -16,33 +16,39 @@ * * An estimate is obtained for norm(inv(A)), and the reciprocal of the * condition number is computed as - * RCOND = 1 / ( norm(A) * norm(inv(A)) ). + * @rst + * .. code-block:: text + * + * rcond = 1 / ( norm(A) * norm(inv(A)) ) + * @endrst * * @param[in] norm Specifies whether the 1-norm condition number or the * infinity-norm condition number is required: - * - '1' or 'O': 1-norm - * - 'I': Infinity-norm - * @param[in] n The order of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The LU factorization of the band matrix A, as computed - * by cgbtrf. U is stored as an upper triangular band matrix - * with kl+ku superdiagonals in rows 0 to kl+ku, and the + * - `'1'` or `'O'`: 1-norm + * - `'I'`: Infinity-norm + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The LU factorization of the band matrix A, as computed + * by CGBTRF. U is stored as an upper triangular band matrix + * with `kl+ku` superdiagonals in rows 0 to `kl+ku`, and the * multipliers used during the factorization are stored in - * rows kl+ku+1 to 2*kl+ku. Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB (ldab >= 2*kl+ku+1). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix - * was interchanged with row ipiv[i]. Array of dimension n. - * @param[in] anorm If norm = '1' or "O", the 1-norm of the original matrix A. - * If norm = "I", the infinity-norm of the original matrix A. + * rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension `n`. + * The pivot indices; for `0<=i= 0). - * @param[in] n The number of columns of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The band matrix A, stored in band format. - * Complex array of dimension (ldab, n). - * The matrix A is stored in rows 0 to kl+ku, so that - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * @param[in] ldab The leading dimension of the array AB (ldab >= kl+ku+1). - * @param[out] R If info = 0 or info > m, R contains the row scale factors - * for A. Array of dimension m. - * @param[out] C If info = 0, C contains the column scale factors for A. - * Array of dimension n. - * @param[out] rowcnd If info = 0 or info > m, rowcnd contains the ratio of the - * smallest R(i) to the largest R(i). If rowcnd >= 0.1 and - * amax is neither too large nor too small, it is not worth - * scaling by R. - * @param[out] colcnd If info = 0, colcnd contains the ratio of the smallest - * C(j) to the largest C(j). If colcnd >= 0.1, it is not - * worth scaling by C. - * @param[out] amax Absolute value of largest matrix element. If amax is very + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The band matrix A, stored in band format. The matrix A is + * stored in rows 0 to `kl+ku`, so that + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[out] R Array of dimension `m`. + * If `info=0` or `info>m`, `R` contains the row scale + * factors for A. + * @param[out] C Array of dimension `n`. + * If `info=0`, `C` contains the column scale factors for A. + * @param[out] rowcnd If `info=0` or `info>m`, `rowcnd` contains the ratio of the + * smallest R(i) to the largest R(i). If `rowcnd>=0.1` and + * `amax` is neither too large nor too small, it is not worth + * scaling by `R`. + * @param[out] colcnd If `info=0`, `colcnd` contains the ratio of the smallest + * C(j) to the largest C(j). If `colcnd>=0.1`, it is not + * worth scaling by `C`. + * @param[out] amax Absolute value of largest matrix element. If `amax` is very * close to overflow or very close to underflow, the matrix * should be scaled. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, and i is - * - <= m: the i-th row of A is exactly zero (1-based) - * - > m: the (i-m)-th column of A is exactly zero (1-based) + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, and i is + * - `i<=m`: the i-th row of A is exactly zero (1-based) + * - `i>m`: the (i-m)-th column of A is exactly zero + * (1-based) */ void cgbequ( const INT m, diff --git a/src/c/cgbequb.c b/src/c/cgbequb.c index 75d33d70..db65fa7d 100644 --- a/src/c/cgbequb.c +++ b/src/c/cgbequb.c @@ -10,13 +10,13 @@ /** * CGBEQUB computes row and column scalings intended to equilibrate an - * M-by-N band matrix A and reduce its condition number. R returns the row - * scale factors and C the column scale factors, chosen to try to make + * `m`-by-`n` band matrix A and reduce its condition number. `R` returns the row + * scale factors and `C` the column scale factors, chosen to try to make * the largest element in each row and column of the matrix B with - * elements B(i,j)=R(i)*A(i,j)*C(j) have an absolute value of at most + * elements `B(i,j)=R(i)*A(i,j)*C(j)` have an absolute value of at most * the radix. * - * R(i) and C(j) are restricted to be a power of the radix between + * `R(i)` and `C(j)` are restricted to be a power of the radix between * SMLNUM = smallest safe number and BIGNUM = largest safe number. Use * of these scaling factors is not guaranteed to reduce the condition * number of A but works well in practice. @@ -25,38 +25,40 @@ * to a power of the radix. Barring over- and underflow, scaling by * these factors introduces no additional rounding errors. However, the * scaled entries' magnitudes are no longer approximately 1 but lie - * between sqrt(radix) and 1/sqrt(radix). + * between `sqrt(radix)` and `1/sqrt(radix)`. * - * @param[in] m The number of rows of the matrix A (m >= 0). - * @param[in] n The number of columns of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The band matrix A, stored in band format. - * Complex array of dimension (ldab, n). - * The matrix A is stored in rows 0 to kl+ku, so that - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * @param[in] ldab The leading dimension of the array AB (ldab >= kl+ku+1). - * @param[out] R If info = 0 or info > m, R contains the row scale factors - * for A. Array of dimension m. - * @param[out] C If info = 0, C contains the column scale factors for A. - * Array of dimension n. - * @param[out] rowcnd If info = 0 or info > m, rowcnd contains the ratio of the - * smallest R(i) to the largest R(i). If rowcnd >= 0.1 and - * amax is neither too large nor too small, it is not worth - * scaling by R. - * @param[out] colcnd If info = 0, colcnd contains the ratio of the smallest - * C(j) to the largest C(j). If colcnd >= 0.1, it is not - * worth scaling by C. - * @param[out] amax Absolute value of largest matrix element. If amax is very + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The band matrix A, stored in band format. The matrix A is + * stored in rows 0 to `kl+ku`, so that + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[out] R Array of dimension `m`. + * If `info=0` or `info>m`, `R` contains the row scale + * factors for A. + * @param[out] C Array of dimension `n`. + * If `info=0`, `C` contains the column scale factors for A. + * @param[out] rowcnd If `info=0` or `info>m`, `rowcnd` contains the ratio of the + * smallest R(i) to the largest R(i). If `rowcnd>=0.1` and + * `amax` is neither too large nor too small, it is not worth + * scaling by `R`. + * @param[out] colcnd If `info=0`, `colcnd` contains the ratio of the smallest + * C(j) to the largest C(j). If `colcnd>=0.1`, it is not + * worth scaling by `C`. + * @param[out] amax Absolute value of largest matrix element. If `amax` is very * close to overflow or very close to underflow, the matrix * should be scaled. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, and i is - * - <= m: the i-th row of A is exactly zero (1-based) - * - > m: the (i-m)-th column of A is exactly zero (1-based) + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, and i is + * - `i<=m`: the i-th row of A is exactly zero (1-based) + * - `i>m`: the (i-m)-th column of A is exactly zero + * (1-based) */ void cgbequb( const INT m, diff --git a/src/c/cgbrfs.c b/src/c/cgbrfs.c index d051c487..e17c17da 100644 --- a/src/c/cgbrfs.c +++ b/src/c/cgbrfs.c @@ -15,40 +15,44 @@ * error bounds and backward error estimates for the solution. * * @param[in] trans Specifies the form of the system of equations: - * - 'N': A * X = B (No transpose) - * - 'T': A**T * X = B (Transpose) - * - 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] nrhs The number of right hand sides (nrhs >= 0). - * @param[in] AB The original band matrix A, stored in rows 0 to kl+ku. - * The j-th column of A is stored in the j-th column of AB: - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku)<=i<=min(n-1,j+kl). - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of AB (ldab >= kl+ku+1). - * @param[in] AFB The LU factorization of A, as computed by cgbtrf. - * U is stored in rows 0 to kl+ku, and the multipliers - * are stored in rows kl+ku+1 to 2*kl+ku. - * Array of dimension (ldafb, n). - * @param[in] ldafb The leading dimension of AFB (ldafb >= 2*kl+ku+1). - * @param[in] ipiv The pivot indices from cgbtrf. Array of dimension n. - * @param[in] B The right hand side matrix B. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B (ldb >= max(1,n)). - * @param[in,out] X On entry, the solution matrix X, as computed by cgbtrs. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The original band matrix A, stored in rows 0 to `kl+ku`. + * The j-th column of A is stored in the j-th column of `AB`: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. + * @param[in] ldab The leading dimension of `AB`. `ldab>=kl+ku+1`. + * @param[in] AFB Array of dimension (`ldafb`, `n`). + * The LU factorization of A, as computed by CGBTRF. + * U is stored in rows 0 to `kl+ku`, and the multipliers + * are stored in rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldafb The leading dimension of `AFB`. `ldafb>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension `n`. + * The pivot indices from CGBTRF. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The right hand side matrix `B`. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[in,out] X Array of dimension (`ldx`, `nrhs`). + * On entry, the solution matrix X, as computed by CGBTRS. * On exit, the improved solution matrix X. - * Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X (ldx >= max(1,n)). - * @param[out] ferr The estimated forward error bound for each solution vector - * X(j). Array of dimension nrhs. - * @param[out] berr The componentwise relative backward error of each solution - * vector X(j). Array of dimension nrhs. - * @param[out] work Complex workspace array of dimension (2*n). - * @param[out] rwork Real workspace array of dimension (n). + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. + * @param[out] ferr Array of dimension `nrhs`. + * The estimated forward error bound for each solution vector + * X(j). + * @param[out] berr Array of dimension `nrhs`. + * The componentwise relative backward error of each solution + * vector X(j). + * @param[out] work Complex workspace array of dimension (`2*n`). + * @param[out] rwork Real workspace array of dimension (`n`). * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void cgbrfs( const char* trans, diff --git a/src/c/cgbsv.c b/src/c/cgbsv.c index 9382c27c..ec7f976f 100644 --- a/src/c/cgbsv.c +++ b/src/c/cgbsv.c @@ -7,47 +7,73 @@ /** * CGBSV computes the solution to a complex system of linear equations - * A * X = B, - * where A is a band matrix of order N with KL subdiagonals and KU - * superdiagonals, and X and B are N-by-NRHS matrices. + * @rst + * .. code-block:: text + * + * A * X = B + * @endrst + * where A is a band matrix of order `n` with `kl` subdiagonals and `ku` + * superdiagonals, and X and `B` are `n`-by-`nrhs` matrices. * * The LU decomposition with partial pivoting and row interchanges is * used to factor A as A = L * U, where L is a product of permutation - * and unit lower triangular matrices with KL subdiagonals, and U is - * upper triangular with KL+KU superdiagonals. The factored form of A + * and unit lower triangular matrices with `kl` subdiagonals, and U is + * upper triangular with `kl+ku` superdiagonals. The factored form of A * is then used to solve the system of equations A * X = B. * * @param[in] n The number of linear equations, i.e., the order of the - * matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). + * matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of - * columns of the matrix B (nrhs >= 0). - * @param[in,out] AB On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * columns of the matrix `B`. `nrhs>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku)<=i<=min(n-1,j+kl). + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB (ldab >= 2*kl+ku+1). - * @param[out] ipiv The pivot indices that define the permutation matrix P; - * row i of the matrix was interchanged with row ipiv[i]. - * Array of dimension n, 0-based. - * @param[in,out] B On entry, the N-by-NRHS right hand side matrix B. - * On exit, if info = 0, the N-by-NRHS solution matrix X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B (ldb >= max(1,n)). + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `n`. + * The pivot indices that define the permutation matrix P; + * row i of the matrix was interchanged with row `ipiv[i]`. + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n`-by-`nrhs` right hand side matrix `B`. + * On exit, if `info=0`, the `n`-by-`nrhs` solution matrix X. + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and the solution has not been computed. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and the solution has not been computed. + * + * @par Further Details: + * @rst + * The band storage scheme is illustrated by the following example, when + * m = n = 6, kl = 2, ku = 1: + * + * .. code-block:: text + * + * On entry: On exit: + * + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * + * + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void cgbsv( const INT n, diff --git a/src/c/cgbsvx.c b/src/c/cgbsvx.c index e910f02f..84ea1496 100644 --- a/src/c/cgbsvx.c +++ b/src/c/cgbsvx.c @@ -13,57 +13,117 @@ /** * CGBSVX uses the LU factorization to compute the solution to a complex - * system of linear equations A * X = B, A**T * X = B, or A**H * X = B, - * where A is a band matrix of order N with KL subdiagonals and KU - * superdiagonals, and X and B are N-by-NRHS matrices. + * system of linear equations + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst + * where A is a band matrix of order `n` with `kl` subdiagonals and `ku` + * superdiagonals, and X and `B` are `n`-by-`nrhs` matrices. * * Error bounds on the solution and a condition estimate are also provided. * - * @param[in] fact 'F': AFB and IPIV contain the factored form of A. - * 'N': The matrix A will be copied to AFB and factored. - * 'E': The matrix A will be equilibrated if necessary, - * then copied to AFB and factored. - * @param[in] trans 'N': A * X = B (No transpose) - * 'T': A**T * X = B (Transpose) - * 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The number of linear equations (order of A). n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in,out] AB On entry, the matrix A in band storage, in rows 0 to kl+ku. - * On exit, if equilibration was done, A is scaled. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of AB. ldab >= kl+ku+1. - * @param[in,out] AFB On entry (if fact='F'), contains the LU factors. + * @rst + * The following steps are performed by this subroutine: + * + * 1. If ``fact='E'``, real scaling factors are computed to equilibrate + * the system:: + * + * trans = 'N': diag(R)*A*diag(C) *inv(diag(C))*X = diag(R)*B + * trans = 'T': (diag(R)*A*diag(C))**T *inv(diag(R))*X = diag(C)*B + * trans = 'C': (diag(R)*A*diag(C))**H *inv(diag(R))*X = diag(C)*B + * + * Whether or not the system will be equilibrated depends on the + * scaling of the matrix A, but if equilibration is used, A is + * overwritten by diag(R)*A*diag(C) and B by diag(R)*B (if ``trans='N'``) + * or diag(C)*B (if ``trans='T'`` or ``'C'``). + * + * 2. If ``fact='N'`` or ``'E'``, the LU decomposition is used to factor + * the matrix A (after equilibration if ``fact='E'``) as:: + * + * A = L * U + * + * where L is a product of permutation and unit lower triangular + * matrices with kl subdiagonals, and U is upper triangular with + * kl+ku superdiagonals. + * + * 3. 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. + * + * 4. The system of equations is solved for X using the factored form of A. + * + * 5. Iterative refinement is applied to improve the computed solution + * matrix and calculate error bounds and backward error estimates for it. + * + * 6. If equilibration was used, the matrix X is premultiplied by + * ``diag(C)`` (if ``trans='N'``) or ``diag(R)`` (if ``trans='T'`` or + * ``'C'``) so that it solves the original system before equilibration. + * @endrst + * + * @param[in] fact + * - `'F'`: `AFB` and `ipiv` contain the factored form of A. + * - `'N'`: The matrix A will be copied to `AFB` and factored. + * - `'E'`: The matrix A will be equilibrated if necessary, + * then copied to `AFB` and factored. + * @param[in] trans + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The number of linear equations (order of A). `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows 0 to + * `kl+ku`. The j-th column of A is stored in the j-th column + * of the array `AB` as follows: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. + * On exit, if `equed != 'N'`, A is scaled. + * @param[in] ldab The leading dimension of `AB`. `ldab>=kl+ku+1`. + * @param[in,out] AFB Array of dimension (`ldafb`, `n`). + * On entry (if `fact='F'`), contains the LU factors. * On exit, contains the factors L and U. - * Array of dimension (ldafb, n). - * @param[in] ldafb The leading dimension of AFB. ldafb >= 2*kl+ku+1. - * @param[in,out] ipiv Pivot indices from factorization. Array of dimension (n). - * @param[in,out] equed On entry (if fact='F'), specifies equilibration done. + * @param[in] ldafb The leading dimension of `AFB`. `ldafb>=2*kl+ku+1`. + * @param[in,out] ipiv Array of dimension (`n`). + * Pivot indices from factorization. + * @param[in,out] equed On entry (if `fact='F'`), specifies equilibration done. * On exit, specifies the form of equilibration: - * 'N': No equilibration - * 'R': Row equilibration (A := diag(R) * A) - * 'C': Column equilibration (A := A * diag(C)) - * 'B': Both (A := diag(R) * A * diag(C)) - * @param[in,out] R Row scale factors. Array of dimension (n). - * @param[in,out] C Column scale factors. Array of dimension (n). - * @param[in,out] B On entry, the N-by-NRHS right hand side matrix B. - * On exit, if equilibration was done, B is scaled. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[out] X The N-by-NRHS solution matrix X. Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). + * - `'N'`: No equilibration + * - `'R'`: Row equilibration (A := diag(R) * A) + * - `'C'`: Column equilibration (A := A * diag(C)) + * - `'B'`: Both (A := diag(R) * A * diag(C)) + * @param[in,out] R Array of dimension (`n`). + * Row scale factors. + * @param[in,out] C Array of dimension (`n`). + * Column scale factors. + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n`-by-`nrhs` right hand side matrix `B`. + * On exit, if equilibration was done, `B` is scaled. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[out] X Array of dimension (`ldx`, `nrhs`). + * The `n`-by-`nrhs` solution matrix X. + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. * @param[out] rcond Reciprocal condition number estimate. - * @param[out] ferr Forward error bound for each solution vector. Array of dimension (nrhs). - * @param[out] berr Backward error for each solution vector. Array of dimension (nrhs). - * @param[out] work Complex workspace array of dimension (2*n). - * @param[out] rwork Real workspace array of dimension (max(1, n)). - * On exit, rwork[0] contains the reciprocal pivot growth factor. + * @param[out] ferr Array of dimension (`nrhs`). + * Forward error bound for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * Backward error for each solution vector. + * @param[out] work Complex workspace array of dimension (`2*n`). + * @param[out] rwork Real workspace array of dimension (`max(1,n)`). + * On exit, `rwork[0]` contains the reciprocal pivot growth + * factor. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i,i) is exactly zero (1-based). - * if info = n+1, U is nonsingular but RCOND < machine precision. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero (1-based). + * If `info=n+1`, U is nonsingular but `rcond` < machine + * precision. */ void cgbsvx( const char* fact, diff --git a/src/c/cgbtf2.c b/src/c/cgbtf2.c index fcdbf17e..de00a6e3 100644 --- a/src/c/cgbtf2.c +++ b/src/c/cgbtf2.c @@ -19,55 +19,54 @@ * trapezoidal if m > n), and U is upper triangular (upper trapezoidal * if m < n). * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB Single complex array, dimension (ldab, n). - * On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[out] ipiv Integer array, dimension (min(m,n)). - * The pivot indices; for 0 <= i < min(m,n), row i of the - * matrix was interchanged with row ipiv[i]. 0-based indexing. + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `min(m,n)`. + * The pivot indices; for `0<=i 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and division by zero will occur if it is used - * to solve a system of equations. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and division by zero will occur if it + * is used to solve a system of equations. + * * @par Further Details: + * @rst * The band storage scheme is illustrated by the following example, when * m = n = 6, kl = 2, ku = 1: * - * On entry (0-based indexing, rows 0 to 5, kl=2, ku=1, kv=kl+ku=3): + * .. code-block:: text * - * Row 0: * * * (fill-in storage) - * Row 1: * * a02 a13 a24 a35 (U superdiagonals) - * Row 2: * a01 a12 a23 a34 a45 (U superdiagonals) - * Row 3: a00 a11 a22 a33 a44 a55 (diagonal) - * Row 4: a10 a21 a32 a43 a54 * (L multipliers after factorization) - * Row 5: a20 a31 a42 a53 * * (L multipliers after factorization) + * On entry: On exit: * - * On exit: - * Row 0: * * * u03 u14 u25 (U fill-in from pivoting) - * Row 1: * * u02 u13 u24 u35 (U superdiagonals) - * Row 2: * u01 u12 u23 u34 u45 (U superdiagonals) - * Row 3: u00 u11 u22 u33 u44 u55 (U diagonal) - * Row 4: m10 m21 m32 m43 m54 * (L multipliers) - * Row 5: m20 m31 m42 m53 * * (L multipliers) + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * * - * Array elements marked * are not used by the routine. + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void cgbtf2( const INT m, diff --git a/src/c/cgbtrf.c b/src/c/cgbtrf.c index f85965ed..8ec1da6c 100644 --- a/src/c/cgbtrf.c +++ b/src/c/cgbtrf.c @@ -24,33 +24,54 @@ * trapezoidal if m > n), and U is upper triangular (upper trapezoidal * if m < n). * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB Single complex array, dimension (ldab, n). - * On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[out] ipiv Integer array, dimension (min(m,n)). - * The pivot indices; for 0 <= i < min(m,n), row i of the - * matrix was interchanged with row ipiv[i]. 0-based indexing. + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `min(m,n)`. + * The pivot indices; for `0<=i 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and division by zero will occur if it is used - * to solve a system of equations. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and division by zero will occur if it + * is used to solve a system of equations. + * + * @par Further Details: + * @rst + * The band storage scheme is illustrated by the following example, when + * m = n = 6, kl = 2, ku = 1: + * + * .. code-block:: text + * + * On entry: On exit: + * + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * + * + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void cgbtrf( const INT m, diff --git a/src/c/cgbtrs.c b/src/c/cgbtrs.c index cd5b3845..b7dc4a49 100644 --- a/src/c/cgbtrs.c +++ b/src/c/cgbtrs.c @@ -10,37 +10,41 @@ /** * CGBTRS solves a system of linear equations - * A * X = B, A**T * X = B, or A**H * X = B + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst * with a general band matrix A using the LU factorization computed * by CGBTRF. * * @param[in] trans Specifies the form of the system of equations: - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of - * columns of the matrix B. nrhs >= 0. - * @param[in] AB Complex*16 array, dimension (ldab, n). + * columns of the matrix `B`. `nrhs>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). * Details of the LU factorization of the band matrix A, * as computed by CGBTRF. U is stored as an upper triangular - * band matrix with kl+ku superdiagonals in rows 0 to kl+ku, + * band matrix with `kl+ku` superdiagonals in rows 0 to `kl+ku`, * and the multipliers used during the factorization are - * stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[in] ipiv Integer array, dimension (n). - * The pivot indices; for 0 <= i < n, row i of the matrix - * was interchanged with row ipiv[i]. 0-based indexing. - * @param[in,out] B Complex*16 array, dimension (ldb, nrhs). - * On entry, the right hand side matrix B. + * stored in rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i= max(1,n). + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void cgbtrs( const char* trans, diff --git a/src/c/cgtcon.c b/src/c/cgtcon.c index 16f7597c..edf38ca6 100644 --- a/src/c/cgtcon.c +++ b/src/c/cgtcon.c @@ -12,33 +12,41 @@ * CGTTRF. * * An estimate is obtained for norm(inv(A)), and the reciprocal of the - * condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))). + * condition number is computed as + * @rst + * .. code-block:: text + * + * rcond = 1 / (anorm * norm(inv(A))) + * @endrst * * @param[in] norm Specifies whether the 1-norm condition number or the * infinity-norm condition number is required: - * = '1' or 'O': 1-norm - * = 'I': Infinity-norm - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the + * - `'1'` or `'O'`: 1-norm + * - `'I'`: Infinity-norm + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the * LU factorization of A as computed by CGTTRF. - * Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U - * from the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first superdiagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second superdiagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. Array of dimension (n). - * @param[in] anorm If norm = '1' or "O", the 1-norm of the original matrix A. - * If norm = "I", the infinity-norm of the original matrix A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U + * from the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first superdiagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second superdiagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in] DL The (n-1) subdiagonal elements of A. Array of dimension (n-1). - * @param[in] D The diagonal elements of A. Array of dimension (n). - * @param[in] DU The (n-1) superdiagonal elements of A. Array of dimension (n-1). - * @param[in] DLF The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] DF The n diagonal elements of U. Array of dimension (n). - * @param[in] DUF The (n-1) elements of the first superdiagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second superdiagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices. Array of dimension (n). - * @param[in] B The right hand side matrix B. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[in,out] X On entry, the solution matrix X, as computed by CGTTRS. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) subdiagonal elements of A. + * @param[in] D Array of dimension (`n`). + * The diagonal elements of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) superdiagonal elements of A. + * @param[in] DLF Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] DF Array of dimension (`n`). + * The n diagonal elements of U. + * @param[in] DUF Array of dimension (`n-1`). + * The (n-1) elements of the first superdiagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second superdiagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The right hand side matrix `B`. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[in,out] X Array of dimension (`ldx`, `nrhs`). + * On entry, the solution matrix X, as computed by CGTTRS. * On exit, the improved solution matrix X. - * Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). - * @param[out] ferr The estimated forward error bound for each solution vector. - * Array of dimension (nrhs). - * @param[out] berr The componentwise relative backward error of each solution. - * Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (2*n). - * @param[out] rwork Real workspace array of dimension (n). + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. + * @param[out] ferr Array of dimension (`nrhs`). + * The estimated forward error bound for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * The componentwise relative backward error of each solution. + * @param[out] work Complex workspace array of dimension (`2*n`). + * @param[out] rwork Real workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void cgtrfs( const char* trans, diff --git a/src/c/cgtsv.c b/src/c/cgtsv.c index 1845e366..f3378eb6 100644 --- a/src/c/cgtsv.c +++ b/src/c/cgtsv.c @@ -10,38 +10,41 @@ /** * CGTSV solves the equation + * @rst + * .. code-block:: text * - * A*X = B, - * - * where A is an n by n tridiagonal matrix, by Gaussian elimination with + * A * X = B + * @endrst + * where A is an `n` by `n` tridiagonal matrix, by Gaussian elimination with * partial pivoting. * * Note that the equation A**T*X = B may be solved by interchanging the - * order of the arguments DU and DL. + * order of the arguments `DU` and `DL`. * - * @param[in] n The order of the matrix A. n >= 0. + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in,out] DL On entry, the (n-1) sub-diagonal elements of A. - * On exit, DL is overwritten by the (n-2) elements of the + * of the matrix `B`. `nrhs>=0`. + * @param[in,out] DL Array of dimension (`n-1`). + * On entry, the (n-1) sub-diagonal elements of A. + * On exit, `DL` is overwritten by the (n-2) elements of the * second super-diagonal of the upper triangular matrix U from - * the LU factorization of A, in DL[0], ..., DL[n-3]. - * Array of dimension (n-1). - * @param[in,out] D On entry, the diagonal elements of A. - * On exit, D is overwritten by the n diagonal elements of U. - * Array of dimension (n). - * @param[in,out] DU On entry, the (n-1) super-diagonal elements of A. - * On exit, DU is overwritten by the (n-1) elements of the first + * the LU factorization of A, in `DL[0]`, ..., `DL[n-3]`. + * @param[in,out] D Array of dimension (`n`). + * On entry, the diagonal elements of A. + * On exit, `D` is overwritten by the n diagonal elements of U. + * @param[in,out] DU Array of dimension (`n-1`). + * On entry, the (n-1) super-diagonal elements of A. + * On exit, `DU` is overwritten by the (n-1) elements of the first * super-diagonal of U. - * Array of dimension (n-1). - * @param[in,out] B On entry, the N by NRHS matrix of right hand side matrix B. - * On exit, if info = 0, the N by NRHS solution matrix X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n` by `nrhs` matrix of right hand side matrix `B`. + * On exit, if `info=0`, the `n` by `nrhs` solution matrix X. + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i-1,i-1) is exactly zero (0-based), and the + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero, and the * solution has not been computed. The factorization has not * been completed unless i = n. */ diff --git a/src/c/cgtsvx.c b/src/c/cgtsvx.c index 881902ca..aa140a2e 100644 --- a/src/c/cgtsvx.c +++ b/src/c/cgtsvx.c @@ -11,48 +11,89 @@ /** * CGTSVX uses the LU factorization to compute the solution to a 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 and X and B are N-by-NRHS + * system of linear equations + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst + * where A is a tridiagonal matrix of order `n` and X and `B` are `n`-by-`nrhs` * matrices. * * Error bounds on the solution and a condition estimate are also provided. * - * @param[in] fact Specifies whether the factored form of A has been supplied. - * = 'F': DLF, DF, DUF, DU2, and IPIV contain the factored form. - * = 'N': The matrix will be copied and factored. + * @rst + * The following steps are performed: + * + * 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 upper triangular with nonzeros in + * only the main diagonal and first two superdiagonals. + * + * 2. 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. + * + * 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. + * @endrst + * + * @param[in] fact + * - `'F'`: `DLF`, `DF`, `DUF`, `DU2`, and `ipiv` contain the + * factored form of A. + * - `'N'`: The matrix will be copied and factored. * @param[in] trans Specifies the form of the system of equations: - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in] DL The (n-1) subdiagonal elements of A. Array of dimension (n-1). - * @param[in] D The diagonal elements of A. Array of dimension (n). - * @param[in] DU The (n-1) superdiagonal elements of A. Array of dimension (n-1). - * @param[in,out] DLF If fact = "F", the (n-1) multipliers from LU factorization. - * If fact = "N", output. Array of dimension (n-1). - * @param[in,out] DF If fact = "F", the n diagonal elements of U. - * If fact = "N", output. Array of dimension (n). - * @param[in,out] DUF If fact = "F", the (n-1) elements of first superdiagonal of U. - * If fact = "N", output. Array of dimension (n-1). - * @param[in,out] DU2 If fact = "F", the (n-2) elements of second superdiagonal of U. - * If fact = "N", output. Array of dimension (n-2). - * @param[in,out] ipiv If fact = "F", the pivot indices from factorization. - * If fact = "N", output. Array of dimension (n). - * @param[in] B The N-by-NRHS right hand side matrix. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[out] X The N-by-NRHS solution matrix. Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) subdiagonal elements of A. + * @param[in] D Array of dimension (`n`). + * The diagonal elements of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) superdiagonal elements of A. + * @param[in,out] DLF Array of dimension (`n-1`). + * If `fact='F'`, the (n-1) multipliers from LU factorization. + * If `fact='N'`, output. + * @param[in,out] DF Array of dimension (`n`). + * If `fact='F'`, the n diagonal elements of U. + * If `fact='N'`, output. + * @param[in,out] DUF Array of dimension (`n-1`). + * If `fact='F'`, the (n-1) elements of first superdiagonal of U. + * If `fact='N'`, output. + * @param[in,out] DU2 Array of dimension (`n-2`). + * If `fact='F'`, the (n-2) elements of second superdiagonal of U. + * If `fact='N'`, output. + * @param[in,out] ipiv Array of dimension (`n`). + * If `fact='F'`, the pivot indices from factorization. + * If `fact='N'`, output. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The `n`-by-`nrhs` right hand side matrix. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[out] X Array of dimension (`ldx`, `nrhs`). + * The `n`-by-`nrhs` solution matrix. + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. * @param[out] rcond The reciprocal condition number estimate. - * @param[out] ferr Forward error bounds for each solution vector. Array of dimension (nrhs). - * @param[out] berr Backward error for each solution vector. Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (2*n). - * @param[out] rwork Real workspace array of dimension (n). + * @param[out] ferr Array of dimension (`nrhs`). + * Forward error bounds for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * Backward error for each solution vector. + * @param[out] work Complex workspace array of dimension (`2*n`). + * @param[out] rwork Real workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i (i <= n), U(i,i) is exactly zero - * - = n+1: U is nonsingular, but rcond < machine precision + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i` (i <= `n`), U(i,i) is exactly zero + * - `info=n+1`: U is nonsingular, but `rcond` < machine + * precision */ void cgtsvx( const char* fact, diff --git a/src/c/cgttrf.c b/src/c/cgttrf.c index 1ee9a8df..bb158f19 100644 --- a/src/c/cgttrf.c +++ b/src/c/cgttrf.c @@ -12,34 +12,39 @@ * using elimination with partial pivoting and row interchanges. * * The factorization has the form - * A = L * U + * @rst + * .. code-block:: text + * + * A = L * U + * @endrst * where L is a product of permutation and unit lower bidiagonal * matrices and U is upper triangular with nonzeros in only the main * diagonal and first two superdiagonals. * - * @param[in] n The order of the matrix A. n >= 0. - * @param[in,out] DL On entry, the (n-1) sub-diagonal elements of A. + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in,out] DL Array of dimension (`n-1`). + * On entry, the (n-1) sub-diagonal elements of A. * On exit, the (n-1) multipliers that define the matrix L * from the LU factorization of A. - * Array of dimension (n-1). - * @param[in,out] D On entry, the diagonal elements of A. + * @param[in,out] D Array of dimension (`n`). + * On entry, the diagonal elements of A. * On exit, the n diagonal elements of the upper triangular * matrix U from the LU factorization of A. - * Array of dimension (n). - * @param[in,out] DU On entry, the (n-1) super-diagonal elements of A. + * @param[in,out] DU Array of dimension (`n-1`). + * On entry, the (n-1) super-diagonal elements of A. * On exit, the (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[out] DU2 On exit, the (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[out] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not + * @param[out] DU2 Array of dimension (`n-2`). + * On exit, the (n-2) elements of the second super-diagonal of U. + * @param[out] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i 0: if info = k, U(k-1,k-1) is exactly zero (0-based). + * - `info=0`: successful exit + * - `info<0`: if `info=-k`, the k-th argument had an illegal + * value + * - `info>0`: if `info=k`, U(k,k) is exactly zero. * The factorization has been completed, but the factor U * is exactly singular, and division by zero will occur * if it is used to solve a system of equations. diff --git a/src/c/cgttrs.c b/src/c/cgttrs.c index 5d3a9a61..89e0faf2 100644 --- a/src/c/cgttrs.c +++ b/src/c/cgttrs.c @@ -8,36 +8,44 @@ /** * CGTTRS solves one of the systems of equations - * A*X = B, A**T*X = B, or A**H*X = B, + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst * with a tridiagonal matrix A using the LU factorization computed * by CGTTRF. * * @param[in] trans Specifies the form of the system of equations. - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A. n >= 0. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U from - * the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not - * required. Array of dimension (n). - * @param[in,out] B On entry, the matrix of right hand side vectors B. - * On exit, B is overwritten by the solution vectors X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * of the matrix `B`. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U from + * the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first super-diagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second super-diagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i=max(1,n)`. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void cgttrs( const char* trans, diff --git a/src/c/cgtts2.c b/src/c/cgtts2.c index d9b49c0a..914c29dc 100644 --- a/src/c/cgtts2.c +++ b/src/c/cgtts2.c @@ -9,33 +9,40 @@ /** * CGTTS2 solves one of the systems of equations - * A * X = B, A**T * X = B, or A**H * X = B, + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst * with a tridiagonal matrix A using the LU factorization computed * by CGTTRF. * * @param[in] itrans Specifies the form of the system of equations. - * = 0: A * X = B (No transpose) - * = 1: A**T * X = B (Transpose) - * = 2: A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A. n >= 0. + * - `0`: A * X = B (No transpose) + * - `1`: A**T * X = B (Transpose) + * - `2`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U from - * the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not - * required. Array of dimension (n). - * @param[in,out] B On entry, the matrix of right hand side vectors B. - * On exit, B is overwritten by the solution vectors X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * of the matrix `B`. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U from + * the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first super-diagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second super-diagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i=max(1,n)`. */ void cgtts2( const INT itrans, diff --git a/src/c/claqgb.c b/src/c/claqgb.c index 6db48bf1..046598ba 100644 --- a/src/c/claqgb.c +++ b/src/c/claqgb.c @@ -9,34 +9,36 @@ #include "semicolon_lapack_complex_single.h" /** - * CLAQGB equilibrates a general M by N band matrix A with KL subdiagonals - * and KU superdiagonals using the row and column scaling factors in the - * vectors R and C. + * CLAQGB equilibrates a general `m` by `n` band matrix A with `kl` subdiagonals + * and `ku` superdiagonals using the row and column scaling factors in the + * vectors `R` and `C`. * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB On entry, the matrix A in band storage, in rows 0 to kl+ku. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows 0 to `kl+ku`. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). + * the array `AB` as follows: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, the equilibrated matrix in the same storage format. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB. ldab >= kl+ku+1. - * @param[in] R The row scale factors for A. Array of dimension (m). - * @param[in] C The column scale factors for A. Array of dimension (n). + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[in] R Array of dimension (`m`). + * The row scale factors for A. + * @param[in] C Array of dimension (`n`). + * The column scale factors for A. * @param[in] rowcnd Ratio of the smallest R(i) to the largest R(i). * @param[in] colcnd Ratio of the smallest C(i) to the largest C(i). * @param[in] amax Absolute value of largest matrix entry. * @param[out] equed Specifies the form of equilibration that was done: - * = 'N': No equilibration - * = 'R': Row equilibration, i.e., A has been premultiplied - * by diag(R). - * = 'C': Column equilibration, i.e., A has been postmultiplied - * by diag(C). - * = 'B': Both row and column equilibration, i.e., A has been - * replaced by diag(R) * A * diag(C). + * - `'N'`: No equilibration + * - `'R'`: Row equilibration, i.e., A has been premultiplied + * by diag(R). + * - `'C'`: Column equilibration, i.e., A has been postmultiplied + * by diag(C). + * - `'B'`: Both row and column equilibration, i.e., A has been + * replaced by diag(R) * A * diag(C). */ void claqgb( const INT m, diff --git a/src/d/dgbcon.c b/src/d/dgbcon.c index 1b37f2d4..20390deb 100644 --- a/src/d/dgbcon.c +++ b/src/d/dgbcon.c @@ -15,33 +15,39 @@ * * An estimate is obtained for norm(inv(A)), and the reciprocal of the * condition number is computed as - * RCOND = 1 / ( norm(A) * norm(inv(A)) ). + * @rst + * .. code-block:: text + * + * rcond = 1 / ( norm(A) * norm(inv(A)) ) + * @endrst * * @param[in] norm Specifies whether the 1-norm condition number or the * infinity-norm condition number is required: - * - '1' or 'O': 1-norm - * - 'I': Infinity-norm - * @param[in] n The order of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The LU factorization of the band matrix A, as computed - * by dgbtrf. U is stored as an upper triangular band matrix - * with kl+ku superdiagonals in rows 0 to kl+ku, and the + * - `'1'` or `'O'`: 1-norm + * - `'I'`: Infinity-norm + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The LU factorization of the band matrix A, as computed + * by DGBTRF. U is stored as an upper triangular band matrix + * with `kl+ku` superdiagonals in rows 0 to `kl+ku`, and the * multipliers used during the factorization are stored in - * rows kl+ku+1 to 2*kl+ku. Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB (ldab >= 2*kl+ku+1). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix - * was interchanged with row ipiv[i]. Array of dimension n. - * @param[in] anorm If norm = '1' or "O", the 1-norm of the original matrix A. - * If norm = "I", the infinity-norm of the original matrix A. + * rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension `n`. + * The pivot indices; for `0<=i= 0). - * @param[in] n The number of columns of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The band matrix A, stored in band format. - * Array of dimension (ldab, n). - * The matrix A is stored in rows 0 to kl+ku, so that - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * @param[in] ldab The leading dimension of the array AB (ldab >= kl+ku+1). - * @param[out] R If info = 0 or info > m, R contains the row scale factors - * for A. Array of dimension m. - * @param[out] C If info = 0, C contains the column scale factors for A. - * Array of dimension n. - * @param[out] rowcnd If info = 0 or info > m, rowcnd contains the ratio of the - * smallest R(i) to the largest R(i). If rowcnd >= 0.1 and - * amax is neither too large nor too small, it is not worth - * scaling by R. - * @param[out] colcnd If info = 0, colcnd contains the ratio of the smallest - * C(j) to the largest C(j). If colcnd >= 0.1, it is not - * worth scaling by C. - * @param[out] amax Absolute value of largest matrix element. If amax is very + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The band matrix A, stored in band format. The matrix A is + * stored in rows 0 to `kl+ku`, so that + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[out] R Array of dimension `m`. + * If `info=0` or `info>m`, `R` contains the row scale + * factors for A. + * @param[out] C Array of dimension `n`. + * If `info=0`, `C` contains the column scale factors for A. + * @param[out] rowcnd If `info=0` or `info>m`, `rowcnd` contains the ratio of the + * smallest R(i) to the largest R(i). If `rowcnd>=0.1` and + * `amax` is neither too large nor too small, it is not worth + * scaling by `R`. + * @param[out] colcnd If `info=0`, `colcnd` contains the ratio of the smallest + * C(j) to the largest C(j). If `colcnd>=0.1`, it is not + * worth scaling by `C`. + * @param[out] amax Absolute value of largest matrix element. If `amax` is very * close to overflow or very close to underflow, the matrix * should be scaled. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, and i is - * - <= m: the i-th row of A is exactly zero (1-based) - * - > m: the (i-m)-th column of A is exactly zero (1-based) + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, and i is + * - `i<=m`: the i-th row of A is exactly zero (1-based) + * - `i>m`: the (i-m)-th column of A is exactly zero + * (1-based) */ void dgbequ( const INT m, diff --git a/src/d/dgbequb.c b/src/d/dgbequb.c index c37969e9..37c682da 100644 --- a/src/d/dgbequb.c +++ b/src/d/dgbequb.c @@ -9,53 +9,55 @@ /** * DGBEQUB computes row and column scalings intended to equilibrate an - * M-by-N band matrix A and reduce its condition number. R returns the row - * scale factors and C the column scale factors, chosen to try to make + * `m`-by-`n` band matrix A and reduce its condition number. `R` returns the row + * scale factors and `C` the column scale factors, chosen to try to make * the largest element in each row and column of the matrix B with - * elements B(i,j)=R(i)*A(i,j)*C(j) have an absolute value of at most + * elements `B(i,j)=R(i)*A(i,j)*C(j)` have an absolute value of at most * the radix. * - * R(i) and C(j) are restricted to be a power of the radix between + * `R(i)` and `C(j)` are restricted to be a power of the radix between * SMLNUM = smallest safe number and BIGNUM = largest safe number. Use * of these scaling factors is not guaranteed to reduce the condition * number of A but works well in practice. * - * This routine differs from DGBEQU by restricting the scaling factors + * This routine differs from DGEEQU by restricting the scaling factors * to a power of the radix. Barring over- and underflow, scaling by * these factors introduces no additional rounding errors. However, the * scaled entries' magnitudes are no longer approximately 1 but lie - * between sqrt(radix) and 1/sqrt(radix). + * between `sqrt(radix)` and `1/sqrt(radix)`. * - * @param[in] m The number of rows of the matrix A (m >= 0). - * @param[in] n The number of columns of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The band matrix A, stored in band format. - * Array of dimension (ldab, n). - * The matrix A is stored in rows 0 to kl+ku, so that - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * @param[in] ldab The leading dimension of the array AB (ldab >= kl+ku+1). - * @param[out] R If info = 0 or info > m, R contains the row scale factors - * for A. Array of dimension m. - * @param[out] C If info = 0, C contains the column scale factors for A. - * Array of dimension n. - * @param[out] rowcnd If info = 0 or info > m, rowcnd contains the ratio of the - * smallest R(i) to the largest R(i). If rowcnd >= 0.1 and - * amax is neither too large nor too small, it is not worth - * scaling by R. - * @param[out] colcnd If info = 0, colcnd contains the ratio of the smallest - * C(j) to the largest C(j). If colcnd >= 0.1, it is not - * worth scaling by C. - * @param[out] amax Absolute value of largest matrix element. If amax is very + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The band matrix A, stored in band format. The matrix A is + * stored in rows 0 to `kl+ku`, so that + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[out] R Array of dimension `m`. + * If `info=0` or `info>m`, `R` contains the row scale + * factors for A. + * @param[out] C Array of dimension `n`. + * If `info=0`, `C` contains the column scale factors for A. + * @param[out] rowcnd If `info=0` or `info>m`, `rowcnd` contains the ratio of the + * smallest R(i) to the largest R(i). If `rowcnd>=0.1` and + * `amax` is neither too large nor too small, it is not worth + * scaling by `R`. + * @param[out] colcnd If `info=0`, `colcnd` contains the ratio of the smallest + * C(j) to the largest C(j). If `colcnd>=0.1`, it is not + * worth scaling by `C`. + * @param[out] amax Absolute value of largest matrix element. If `amax` is very * close to overflow or very close to underflow, the matrix * should be scaled. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, and i is - * - <= m: the i-th row of A is exactly zero (1-based) - * - > m: the (i-m)-th column of A is exactly zero (1-based) + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, and i is + * - `i<=m`: the i-th row of A is exactly zero (1-based) + * - `i>m`: the (i-m)-th column of A is exactly zero + * (1-based) */ void dgbequb( const INT m, diff --git a/src/d/dgbrfs.c b/src/d/dgbrfs.c index cb02fe8f..4df269c7 100644 --- a/src/d/dgbrfs.c +++ b/src/d/dgbrfs.c @@ -14,40 +14,44 @@ * error bounds and backward error estimates for the solution. * * @param[in] trans Specifies the form of the system of equations: - * - 'N': A * X = B (No transpose) - * - 'T': A**T * X = B (Transpose) - * - 'C': A**H * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] nrhs The number of right hand sides (nrhs >= 0). - * @param[in] AB The original band matrix A, stored in rows 0 to kl+ku. - * The j-th column of A is stored in the j-th column of AB: - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku)<=i<=min(n-1,j+kl). - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of AB (ldab >= kl+ku+1). - * @param[in] AFB The LU factorization of A, as computed by dgbtrf. - * U is stored in rows 0 to kl+ku, and the multipliers - * are stored in rows kl+ku+1 to 2*kl+ku. - * Array of dimension (ldafb, n). - * @param[in] ldafb The leading dimension of AFB (ldafb >= 2*kl+ku+1). - * @param[in] ipiv The pivot indices from dgbtrf. Array of dimension n. - * @param[in] B The right hand side matrix B. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B (ldb >= max(1,n)). - * @param[in,out] X On entry, the solution matrix X, as computed by dgbtrs. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The original band matrix A, stored in rows 0 to `kl+ku`. + * The j-th column of A is stored in the j-th column of `AB`: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. + * @param[in] ldab The leading dimension of `AB`. `ldab>=kl+ku+1`. + * @param[in] AFB Array of dimension (`ldafb`, `n`). + * The LU factorization of A, as computed by DGBTRF. + * U is stored in rows 0 to `kl+ku`, and the multipliers + * are stored in rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldafb The leading dimension of `AFB`. `ldafb>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension `n`. + * The pivot indices from DGBTRF. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The right hand side matrix `B`. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[in,out] X Array of dimension (`ldx`, `nrhs`). + * On entry, the solution matrix X, as computed by DGBTRS. * On exit, the improved solution matrix X. - * Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X (ldx >= max(1,n)). - * @param[out] ferr The estimated forward error bound for each solution vector - * X(j). Array of dimension nrhs. - * @param[out] berr The componentwise relative backward error of each solution - * vector X(j). Array of dimension nrhs. - * @param[out] work Workspace array of dimension (3*n). - * @param[out] iwork Integer workspace array of dimension (n). + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. + * @param[out] ferr Array of dimension `nrhs`. + * The estimated forward error bound for each solution vector + * X(j). + * @param[out] berr Array of dimension `nrhs`. + * The componentwise relative backward error of each solution + * vector X(j). + * @param[out] work Workspace array of dimension (`3*n`). + * @param[out] iwork Integer workspace array of dimension (`n`). * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void dgbrfs( const char* trans, diff --git a/src/d/dgbsv.c b/src/d/dgbsv.c index ec93c161..539e99f5 100644 --- a/src/d/dgbsv.c +++ b/src/d/dgbsv.c @@ -6,47 +6,73 @@ /** * DGBSV computes the solution to a real system of linear equations - * A * X = B, - * where A is a band matrix of order N with KL subdiagonals and KU - * superdiagonals, and X and B are N-by-NRHS matrices. + * @rst + * .. code-block:: text + * + * A * X = B + * @endrst + * where A is a band matrix of order `n` with `kl` subdiagonals and `ku` + * superdiagonals, and X and `B` are `n`-by-`nrhs` matrices. * * The LU decomposition with partial pivoting and row interchanges is * used to factor A as A = L * U, where L is a product of permutation - * and unit lower triangular matrices with KL subdiagonals, and U is - * upper triangular with KL+KU superdiagonals. The factored form of A + * and unit lower triangular matrices with `kl` subdiagonals, and U is + * upper triangular with `kl+ku` superdiagonals. The factored form of A * is then used to solve the system of equations A * X = B. * * @param[in] n The number of linear equations, i.e., the order of the - * matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). + * matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of - * columns of the matrix B (nrhs >= 0). - * @param[in,out] AB On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * columns of the matrix `B`. `nrhs>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku)<=i<=min(n-1,j+kl). + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB (ldab >= 2*kl+ku+1). - * @param[out] ipiv The pivot indices that define the permutation matrix P; - * row i of the matrix was interchanged with row ipiv[i]. - * Array of dimension n, 0-based. - * @param[in,out] B On entry, the N-by-NRHS right hand side matrix B. - * On exit, if info = 0, the N-by-NRHS solution matrix X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B (ldb >= max(1,n)). + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `n`. + * The pivot indices that define the permutation matrix P; + * row i of the matrix was interchanged with row `ipiv[i]`. + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n`-by-`nrhs` right hand side matrix `B`. + * On exit, if `info=0`, the `n`-by-`nrhs` solution matrix X. + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and the solution has not been computed. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and the solution has not been computed. + * + * @par Further Details: + * @rst + * The band storage scheme is illustrated by the following example, when + * m = n = 6, kl = 2, ku = 1: + * + * .. code-block:: text + * + * On entry: On exit: + * + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * + * + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void dgbsv( const INT n, diff --git a/src/d/dgbsvx.c b/src/d/dgbsvx.c index cd555e5f..782a1002 100644 --- a/src/d/dgbsvx.c +++ b/src/d/dgbsvx.c @@ -12,57 +12,117 @@ /** * DGBSVX uses the LU factorization to compute the solution to a real - * system of linear equations A * X = B, A**T * X = B, or A**H * X = B, - * where A is a band matrix of order N with KL subdiagonals and KU - * superdiagonals, and X and B are N-by-NRHS matrices. + * system of linear equations + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst + * where A is a band matrix of order `n` with `kl` subdiagonals and `ku` + * superdiagonals, and X and `B` are `n`-by-`nrhs` matrices. * * Error bounds on the solution and a condition estimate are also provided. * - * @param[in] fact 'F': AFB and IPIV contain the factored form of A. - * 'N': The matrix A will be copied to AFB and factored. - * 'E': The matrix A will be equilibrated if necessary, - * then copied to AFB and factored. - * @param[in] trans 'N': A * X = B (No transpose) - * 'T': A**T * X = B (Transpose) - * 'C': A**H * X = B (Conjugate transpose = Transpose) - * @param[in] n The number of linear equations (order of A). n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in,out] AB On entry, the matrix A in band storage, in rows 0 to kl+ku. - * On exit, if equilibration was done, A is scaled. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of AB. ldab >= kl+ku+1. - * @param[in,out] AFB On entry (if fact='F'), contains the LU factors. + * @rst + * The following steps are performed by this subroutine: + * + * 1. If ``fact='E'``, real scaling factors are computed to equilibrate + * the system:: + * + * trans = 'N': diag(R)*A*diag(C) *inv(diag(C))*X = diag(R)*B + * trans = 'T': (diag(R)*A*diag(C))**T *inv(diag(R))*X = diag(C)*B + * trans = 'C': (diag(R)*A*diag(C))**H *inv(diag(R))*X = diag(C)*B + * + * Whether or not the system will be equilibrated depends on the + * scaling of the matrix A, but if equilibration is used, A is + * overwritten by diag(R)*A*diag(C) and B by diag(R)*B (if ``trans='N'``) + * or diag(C)*B (if ``trans='T'`` or ``'C'``). + * + * 2. If ``fact='N'`` or ``'E'``, the LU decomposition is used to factor + * the matrix A (after equilibration if ``fact='E'``) as:: + * + * A = L * U + * + * where L is a product of permutation and unit lower triangular + * matrices with kl subdiagonals, and U is upper triangular with + * kl+ku superdiagonals. + * + * 3. 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. + * + * 4. The system of equations is solved for X using the factored form of A. + * + * 5. Iterative refinement is applied to improve the computed solution + * matrix and calculate error bounds and backward error estimates for it. + * + * 6. If equilibration was used, the matrix X is premultiplied by + * ``diag(C)`` (if ``trans='N'``) or ``diag(R)`` (if ``trans='T'`` or + * ``'C'``) so that it solves the original system before equilibration. + * @endrst + * + * @param[in] fact + * - `'F'`: `AFB` and `ipiv` contain the factored form of A. + * - `'N'`: The matrix A will be copied to `AFB` and factored. + * - `'E'`: The matrix A will be equilibrated if necessary, + * then copied to `AFB` and factored. + * @param[in] trans + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose = Transpose) + * @param[in] n The number of linear equations (order of A). `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows 0 to + * `kl+ku`. The j-th column of A is stored in the j-th column + * of the array `AB` as follows: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. + * On exit, if `equed != 'N'`, A is scaled. + * @param[in] ldab The leading dimension of `AB`. `ldab>=kl+ku+1`. + * @param[in,out] AFB Array of dimension (`ldafb`, `n`). + * On entry (if `fact='F'`), contains the LU factors. * On exit, contains the factors L and U. - * Array of dimension (ldafb, n). - * @param[in] ldafb The leading dimension of AFB. ldafb >= 2*kl+ku+1. - * @param[in,out] ipiv Pivot indices from factorization. Array of dimension (n). - * @param[in,out] equed On entry (if fact='F'), specifies equilibration done. + * @param[in] ldafb The leading dimension of `AFB`. `ldafb>=2*kl+ku+1`. + * @param[in,out] ipiv Array of dimension (`n`). + * Pivot indices from factorization. + * @param[in,out] equed On entry (if `fact='F'`), specifies equilibration done. * On exit, specifies the form of equilibration: - * 'N': No equilibration - * 'R': Row equilibration (A := diag(R) * A) - * 'C': Column equilibration (A := A * diag(C)) - * 'B': Both (A := diag(R) * A * diag(C)) - * @param[in,out] R Row scale factors. Array of dimension (n). - * @param[in,out] C Column scale factors. Array of dimension (n). - * @param[in,out] B On entry, the N-by-NRHS right hand side matrix B. - * On exit, if equilibration was done, B is scaled. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[out] X The N-by-NRHS solution matrix X. Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). + * - `'N'`: No equilibration + * - `'R'`: Row equilibration (A := diag(R) * A) + * - `'C'`: Column equilibration (A := A * diag(C)) + * - `'B'`: Both (A := diag(R) * A * diag(C)) + * @param[in,out] R Array of dimension (`n`). + * Row scale factors. + * @param[in,out] C Array of dimension (`n`). + * Column scale factors. + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n`-by-`nrhs` right hand side matrix `B`. + * On exit, if equilibration was done, `B` is scaled. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[out] X Array of dimension (`ldx`, `nrhs`). + * The `n`-by-`nrhs` solution matrix X. + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. * @param[out] rcond Reciprocal condition number estimate. - * @param[out] ferr Forward error bound for each solution vector. Array of dimension (nrhs). - * @param[out] berr Backward error for each solution vector. Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (3*n). - * On exit, work[0] contains the reciprocal pivot growth factor. - * @param[out] iwork Integer workspace array of dimension (n). + * @param[out] ferr Array of dimension (`nrhs`). + * Forward error bound for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * Backward error for each solution vector. + * @param[out] work Workspace array of dimension (`3*n`). + * On exit, `work[0]` contains the reciprocal pivot growth + * factor. + * @param[out] iwork Integer workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i,i) is exactly zero (1-based). - * if info = n+1, U is nonsingular but RCOND < machine precision. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero (1-based). + * If `info=n+1`, U is nonsingular but `rcond` < machine + * precision. */ void dgbsvx( const char* fact, diff --git a/src/d/dgbtf2.c b/src/d/dgbtf2.c index b9ade04a..0ab56151 100644 --- a/src/d/dgbtf2.c +++ b/src/d/dgbtf2.c @@ -18,55 +18,54 @@ * trapezoidal if m > n), and U is upper triangular (upper trapezoidal * if m < n). * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB Double precision array, dimension (ldab, n). - * On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[out] ipiv Integer array, dimension (min(m,n)). - * The pivot indices; for 0 <= i < min(m,n), row i of the - * matrix was interchanged with row ipiv[i]. 0-based indexing. + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `min(m,n)`. + * The pivot indices; for `0<=i 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and division by zero will occur if it is used - * to solve a system of equations. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and division by zero will occur if it + * is used to solve a system of equations. + * * @par Further Details: + * @rst * The band storage scheme is illustrated by the following example, when * m = n = 6, kl = 2, ku = 1: * - * On entry (0-based indexing, rows 0 to 5, kl=2, ku=1, kv=kl+ku=3): + * .. code-block:: text * - * Row 0: * * * (fill-in storage) - * Row 1: * * a02 a13 a24 a35 (U superdiagonals) - * Row 2: * a01 a12 a23 a34 a45 (U superdiagonals) - * Row 3: a00 a11 a22 a33 a44 a55 (diagonal) - * Row 4: a10 a21 a32 a43 a54 * (L multipliers after factorization) - * Row 5: a20 a31 a42 a53 * * (L multipliers after factorization) + * On entry: On exit: * - * On exit: - * Row 0: * * * u03 u14 u25 (U fill-in from pivoting) - * Row 1: * * u02 u13 u24 u35 (U superdiagonals) - * Row 2: * u01 u12 u23 u34 u45 (U superdiagonals) - * Row 3: u00 u11 u22 u33 u44 u55 (U diagonal) - * Row 4: m10 m21 m32 m43 m54 * (L multipliers) - * Row 5: m20 m31 m42 m53 * * (L multipliers) + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * * - * Array elements marked * are not used by the routine. + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void dgbtf2( const INT m, diff --git a/src/d/dgbtrf.c b/src/d/dgbtrf.c index 9679f067..cc0ddb42 100644 --- a/src/d/dgbtrf.c +++ b/src/d/dgbtrf.c @@ -23,33 +23,54 @@ * trapezoidal if m > n), and U is upper triangular (upper trapezoidal * if m < n). * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB Double precision array, dimension (ldab, n). - * On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[out] ipiv Integer array, dimension (min(m,n)). - * The pivot indices; for 0 <= i < min(m,n), row i of the - * matrix was interchanged with row ipiv[i]. 0-based indexing. + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `min(m,n)`. + * The pivot indices; for `0<=i 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and division by zero will occur if it is used - * to solve a system of equations. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and division by zero will occur if it + * is used to solve a system of equations. + * + * @par Further Details: + * @rst + * The band storage scheme is illustrated by the following example, when + * m = n = 6, kl = 2, ku = 1: + * + * .. code-block:: text + * + * On entry: On exit: + * + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * + * + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void dgbtrf( const INT m, diff --git a/src/d/dgbtrs.c b/src/d/dgbtrs.c index 2bee52d7..d7b69a59 100644 --- a/src/d/dgbtrs.c +++ b/src/d/dgbtrs.c @@ -9,37 +9,41 @@ /** * DGBTRS solves a system of linear equations - * A * X = B or A**T * X = B + * @rst + * .. code-block:: text + * + * A * X = B or A**T * X = B + * @endrst * with a general band matrix A using the LU factorization computed * by DGBTRF. * * @param[in] trans Specifies the form of the system of equations: - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**T * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**T * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of - * columns of the matrix B. nrhs >= 0. - * @param[in] AB Double precision array, dimension (ldab, n). + * columns of the matrix `B`. `nrhs>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). * Details of the LU factorization of the band matrix A, * as computed by DGBTRF. U is stored as an upper triangular - * band matrix with kl+ku superdiagonals in rows 0 to kl+ku, + * band matrix with `kl+ku` superdiagonals in rows 0 to `kl+ku`, * and the multipliers used during the factorization are - * stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[in] ipiv Integer array, dimension (n). - * The pivot indices; for 0 <= i < n, row i of the matrix - * was interchanged with row ipiv[i]. 0-based indexing. - * @param[in,out] B Double precision array, dimension (ldb, nrhs). - * On entry, the right hand side matrix B. + * stored in rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i= max(1,n). + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void dgbtrs( const char* trans, diff --git a/src/d/dgtcon.c b/src/d/dgtcon.c index 458acbbe..b686295d 100644 --- a/src/d/dgtcon.c +++ b/src/d/dgtcon.c @@ -11,34 +11,42 @@ * DGTTRF. * * An estimate is obtained for norm(inv(A)), and the reciprocal of the - * condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))). + * condition number is computed as + * @rst + * .. code-block:: text + * + * rcond = 1 / (anorm * norm(inv(A))) + * @endrst * * @param[in] norm Specifies whether the 1-norm condition number or the * infinity-norm condition number is required: - * = '1' or 'O': 1-norm - * = 'I': Infinity-norm - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the + * - `'1'` or `'O'`: 1-norm + * - `'I'`: Infinity-norm + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the * LU factorization of A as computed by DGTTRF. - * Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U - * from the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first superdiagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second superdiagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. Array of dimension (n). - * @param[in] anorm If norm = '1' or "O", the 1-norm of the original matrix A. - * If norm = "I", the infinity-norm of the original matrix A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U + * from the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first superdiagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second superdiagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in] DL The (n-1) subdiagonal elements of A. Array of dimension (n-1). - * @param[in] D The diagonal elements of A. Array of dimension (n). - * @param[in] DU The (n-1) superdiagonal elements of A. Array of dimension (n-1). - * @param[in] DLF The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] DF The n diagonal elements of U. Array of dimension (n). - * @param[in] DUF The (n-1) elements of the first superdiagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second superdiagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices. Array of dimension (n). - * @param[in] B The right hand side matrix B. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[in,out] X On entry, the solution matrix X, as computed by DGTTRS. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) subdiagonal elements of A. + * @param[in] D Array of dimension (`n`). + * The diagonal elements of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) superdiagonal elements of A. + * @param[in] DLF Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] DF Array of dimension (`n`). + * The n diagonal elements of U. + * @param[in] DUF Array of dimension (`n-1`). + * The (n-1) elements of the first superdiagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second superdiagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The right hand side matrix `B`. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[in,out] X Array of dimension (`ldx`, `nrhs`). + * On entry, the solution matrix X, as computed by DGTTRS. * On exit, the improved solution matrix X. - * Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). - * @param[out] ferr The estimated forward error bound for each solution vector. - * Array of dimension (nrhs). - * @param[out] berr The componentwise relative backward error of each solution. - * Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (3*n). - * @param[out] iwork Integer workspace array of dimension (n). + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. + * @param[out] ferr Array of dimension (`nrhs`). + * The estimated forward error bound for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * The componentwise relative backward error of each solution. + * @param[out] work Workspace array of dimension (`3*n`). + * @param[out] iwork Integer workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void dgtrfs( const char* trans, diff --git a/src/d/dgtsv.c b/src/d/dgtsv.c index b94da805..fdc2ce90 100644 --- a/src/d/dgtsv.c +++ b/src/d/dgtsv.c @@ -9,38 +9,41 @@ /** * DGTSV solves the equation + * @rst + * .. code-block:: text * - * A*X = B, - * - * where A is an n by n tridiagonal matrix, by Gaussian elimination with + * A * X = B + * @endrst + * where A is an `n` by `n` tridiagonal matrix, by Gaussian elimination with * partial pivoting. * * Note that the equation A**T*X = B may be solved by interchanging the - * order of the arguments DU and DL. + * order of the arguments `DU` and `DL`. * - * @param[in] n The order of the matrix A. n >= 0. + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in,out] DL On entry, the (n-1) sub-diagonal elements of A. - * On exit, DL is overwritten by the (n-2) elements of the + * of the matrix `B`. `nrhs>=0`. + * @param[in,out] DL Array of dimension (`n-1`). + * On entry, the (n-1) sub-diagonal elements of A. + * On exit, `DL` is overwritten by the (n-2) elements of the * second super-diagonal of the upper triangular matrix U from - * the LU factorization of A, in DL[0], ..., DL[n-3]. - * Array of dimension (n-1). - * @param[in,out] D On entry, the diagonal elements of A. - * On exit, D is overwritten by the n diagonal elements of U. - * Array of dimension (n). - * @param[in,out] DU On entry, the (n-1) super-diagonal elements of A. - * On exit, DU is overwritten by the (n-1) elements of the first + * the LU factorization of A, in `DL[0]`, ..., `DL[n-3]`. + * @param[in,out] D Array of dimension (`n`). + * On entry, the diagonal elements of A. + * On exit, `D` is overwritten by the n diagonal elements of U. + * @param[in,out] DU Array of dimension (`n-1`). + * On entry, the (n-1) super-diagonal elements of A. + * On exit, `DU` is overwritten by the (n-1) elements of the first * super-diagonal of U. - * Array of dimension (n-1). - * @param[in,out] B On entry, the N by NRHS matrix of right hand side matrix B. - * On exit, if info = 0, the N by NRHS solution matrix X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n` by `nrhs` matrix of right hand side matrix `B`. + * On exit, if `info=0`, the `n` by `nrhs` solution matrix X. + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i-1,i-1) is exactly zero (0-based), and the + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero, and the * solution has not been computed. The factorization has not * been completed unless i = n. */ diff --git a/src/d/dgtsvx.c b/src/d/dgtsvx.c index 96f17f9b..5df8ce7d 100644 --- a/src/d/dgtsvx.c +++ b/src/d/dgtsvx.c @@ -10,48 +10,89 @@ /** * DGTSVX uses the LU factorization to compute the solution to a real - * system of linear equations A * X = B or A**T * X = B, - * where A is a tridiagonal matrix of order N and X and B are N-by-NRHS + * system of linear equations + * @rst + * .. code-block:: text + * + * A * X = B or A**T * X = B + * @endrst + * where A is a tridiagonal matrix of order `n` and X and `B` are `n`-by-`nrhs` * matrices. * * Error bounds on the solution and a condition estimate are also provided. * - * @param[in] fact Specifies whether the factored form of A has been supplied. - * = 'F': DLF, DF, DUF, DU2, and IPIV contain the factored form. - * = 'N': The matrix will be copied and factored. + * @rst + * The following steps are performed: + * + * 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 upper triangular with nonzeros in + * only the main diagonal and first two superdiagonals. + * + * 2. 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. + * + * 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. + * @endrst + * + * @param[in] fact + * - `'F'`: `DLF`, `DF`, `DUF`, `DU2`, and `ipiv` contain the + * factored form of A. + * - `'N'`: The matrix will be copied and factored. * @param[in] trans Specifies the form of the system of equations: - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**H * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in] DL The (n-1) subdiagonal elements of A. Array of dimension (n-1). - * @param[in] D The diagonal elements of A. Array of dimension (n). - * @param[in] DU The (n-1) superdiagonal elements of A. Array of dimension (n-1). - * @param[in,out] DLF If fact = "F", the (n-1) multipliers from LU factorization. - * If fact = "N", output. Array of dimension (n-1). - * @param[in,out] DF If fact = "F", the n diagonal elements of U. - * If fact = "N", output. Array of dimension (n). - * @param[in,out] DUF If fact = "F", the (n-1) elements of first superdiagonal of U. - * If fact = "N", output. Array of dimension (n-1). - * @param[in,out] DU2 If fact = "F", the (n-2) elements of second superdiagonal of U. - * If fact = "N", output. Array of dimension (n-2). - * @param[in,out] ipiv If fact = "F", the pivot indices from factorization. - * If fact = "N", output. Array of dimension (n). - * @param[in] B The N-by-NRHS right hand side matrix. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[out] X The N-by-NRHS solution matrix. Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) subdiagonal elements of A. + * @param[in] D Array of dimension (`n`). + * The diagonal elements of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) superdiagonal elements of A. + * @param[in,out] DLF Array of dimension (`n-1`). + * If `fact='F'`, the (n-1) multipliers from LU factorization. + * If `fact='N'`, output. + * @param[in,out] DF Array of dimension (`n`). + * If `fact='F'`, the n diagonal elements of U. + * If `fact='N'`, output. + * @param[in,out] DUF Array of dimension (`n-1`). + * If `fact='F'`, the (n-1) elements of first superdiagonal of U. + * If `fact='N'`, output. + * @param[in,out] DU2 Array of dimension (`n-2`). + * If `fact='F'`, the (n-2) elements of second superdiagonal of U. + * If `fact='N'`, output. + * @param[in,out] ipiv Array of dimension (`n`). + * If `fact='F'`, the pivot indices from factorization. + * If `fact='N'`, output. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The `n`-by-`nrhs` right hand side matrix. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[out] X Array of dimension (`ldx`, `nrhs`). + * The `n`-by-`nrhs` solution matrix. + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. * @param[out] rcond The reciprocal condition number estimate. - * @param[out] ferr Forward error bounds for each solution vector. Array of dimension (nrhs). - * @param[out] berr Backward error for each solution vector. Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (3*n). - * @param[out] iwork Integer workspace array of dimension (n). + * @param[out] ferr Array of dimension (`nrhs`). + * Forward error bounds for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * Backward error for each solution vector. + * @param[out] work Workspace array of dimension (`3*n`). + * @param[out] iwork Integer workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i (i <= n), U(i,i) is exactly zero - * - = n+1: U is nonsingular, but rcond < machine precision + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i` (i <= `n`), U(i,i) is exactly zero + * - `info=n+1`: U is nonsingular, but `rcond` < machine + * precision */ void dgtsvx( const char* fact, diff --git a/src/d/dgttrf.c b/src/d/dgttrf.c index c962d01a..7beab19d 100644 --- a/src/d/dgttrf.c +++ b/src/d/dgttrf.c @@ -11,34 +11,39 @@ * using elimination with partial pivoting and row interchanges. * * The factorization has the form - * A = L * U + * @rst + * .. code-block:: text + * + * A = L * U + * @endrst * where L is a product of permutation and unit lower bidiagonal * matrices and U is upper triangular with nonzeros in only the main * diagonal and first two superdiagonals. * - * @param[in] n The order of the matrix A. n >= 0. - * @param[in,out] DL On entry, the (n-1) sub-diagonal elements of A. + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in,out] DL Array of dimension (`n-1`). + * On entry, the (n-1) sub-diagonal elements of A. * On exit, the (n-1) multipliers that define the matrix L * from the LU factorization of A. - * Array of dimension (n-1). - * @param[in,out] D On entry, the diagonal elements of A. + * @param[in,out] D Array of dimension (`n`). + * On entry, the diagonal elements of A. * On exit, the n diagonal elements of the upper triangular * matrix U from the LU factorization of A. - * Array of dimension (n). - * @param[in,out] DU On entry, the (n-1) super-diagonal elements of A. + * @param[in,out] DU Array of dimension (`n-1`). + * On entry, the (n-1) super-diagonal elements of A. * On exit, the (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[out] DU2 On exit, the (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[out] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not + * @param[out] DU2 Array of dimension (`n-2`). + * On exit, the (n-2) elements of the second super-diagonal of U. + * @param[out] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i 0: if info = k, U(k-1,k-1) is exactly zero (0-based). + * - `info=0`: successful exit + * - `info<0`: if `info=-k`, the k-th argument had an illegal + * value + * - `info>0`: if `info=k`, U(k,k) is exactly zero. * The factorization has been completed, but the factor U * is exactly singular, and division by zero will occur * if it is used to solve a system of equations. diff --git a/src/d/dgttrs.c b/src/d/dgttrs.c index 17512bd0..fccf0ced 100644 --- a/src/d/dgttrs.c +++ b/src/d/dgttrs.c @@ -7,36 +7,44 @@ /** * DGTTRS solves one of the systems of equations - * A*X = B or A**T*X = B, + * @rst + * .. code-block:: text + * + * A * X = B or A**T * X = B + * @endrst * with a tridiagonal matrix A using the LU factorization computed * by DGTTRF. * * @param[in] trans Specifies the form of the system of equations. - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**T * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A. n >= 0. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**T * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U from - * the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not - * required. Array of dimension (n). - * @param[in,out] B On entry, the matrix of right hand side vectors B. - * On exit, B is overwritten by the solution vectors X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * of the matrix `B`. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U from + * the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first super-diagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second super-diagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i=max(1,n)`. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void dgttrs( const char* trans, diff --git a/src/d/dgtts2.c b/src/d/dgtts2.c index eb6e05bd..df6477e9 100644 --- a/src/d/dgtts2.c +++ b/src/d/dgtts2.c @@ -8,33 +8,40 @@ /** * DGTTS2 solves one of the systems of equations - * A*X = B or A**T*X = B, + * @rst + * .. code-block:: text + * + * A * X = B or A**T * X = B + * @endrst * with a tridiagonal matrix A using the LU factorization computed * by DGTTRF. * * @param[in] itrans Specifies the form of the system of equations. - * = 0: A * X = B (No transpose) - * = 1: A**T * X = B (Transpose) - * = 2: A**T * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A. n >= 0. + * - `0`: A * X = B (No transpose) + * - `1`: A**T * X = B (Transpose) + * - `2`: A**T * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U from - * the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not - * required. Array of dimension (n). - * @param[in,out] B On entry, the matrix of right hand side vectors B. - * On exit, B is overwritten by the solution vectors X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * of the matrix `B`. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U from + * the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first super-diagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second super-diagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i=max(1,n)`. */ void dgtts2( const INT itrans, diff --git a/src/d/dlaqgb.c b/src/d/dlaqgb.c index 284c075b..8b0099db 100644 --- a/src/d/dlaqgb.c +++ b/src/d/dlaqgb.c @@ -8,34 +8,36 @@ #include "semicolon_lapack_double.h" /** - * DLAQGB equilibrates a general M by N band matrix A with KL subdiagonals - * and KU superdiagonals using the row and column scaling factors in the - * vectors R and C. + * DLAQGB equilibrates a general `m` by `n` band matrix A with `kl` subdiagonals + * and `ku` superdiagonals using the row and column scaling factors in the + * vectors `R` and `C`. * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB On entry, the matrix A in band storage, in rows 0 to kl+ku. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows 0 to `kl+ku`. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). + * the array `AB` as follows: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, the equilibrated matrix in the same storage format. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB. ldab >= kl+ku+1. - * @param[in] R The row scale factors for A. Array of dimension (m). - * @param[in] C The column scale factors for A. Array of dimension (n). + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[in] R Array of dimension (`m`). + * The row scale factors for A. + * @param[in] C Array of dimension (`n`). + * The column scale factors for A. * @param[in] rowcnd Ratio of the smallest R(i) to the largest R(i). * @param[in] colcnd Ratio of the smallest C(i) to the largest C(i). * @param[in] amax Absolute value of largest matrix entry. * @param[out] equed Specifies the form of equilibration that was done: - * = 'N': No equilibration - * = 'R': Row equilibration, i.e., A has been premultiplied - * by diag(R). - * = 'C': Column equilibration, i.e., A has been postmultiplied - * by diag(C). - * = 'B': Both row and column equilibration, i.e., A has been - * replaced by diag(R) * A * diag(C). + * - `'N'`: No equilibration + * - `'R'`: Row equilibration, i.e., A has been premultiplied + * by diag(R). + * - `'C'`: Column equilibration, i.e., A has been postmultiplied + * by diag(C). + * - `'B'`: Both row and column equilibration, i.e., A has been + * replaced by diag(R) * A * diag(C). */ void dlaqgb( const INT m, diff --git a/src/s/sgbcon.c b/src/s/sgbcon.c index 3366cb63..c553c923 100644 --- a/src/s/sgbcon.c +++ b/src/s/sgbcon.c @@ -15,33 +15,39 @@ * * An estimate is obtained for norm(inv(A)), and the reciprocal of the * condition number is computed as - * RCOND = 1 / ( norm(A) * norm(inv(A)) ). + * @rst + * .. code-block:: text + * + * rcond = 1 / ( norm(A) * norm(inv(A)) ) + * @endrst * * @param[in] norm Specifies whether the 1-norm condition number or the * infinity-norm condition number is required: - * - '1' or 'O': 1-norm - * - 'I': Infinity-norm - * @param[in] n The order of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The LU factorization of the band matrix A, as computed - * by sgbtrf. U is stored as an upper triangular band matrix - * with kl+ku superdiagonals in rows 0 to kl+ku, and the + * - `'1'` or `'O'`: 1-norm + * - `'I'`: Infinity-norm + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The LU factorization of the band matrix A, as computed + * by SGBTRF. U is stored as an upper triangular band matrix + * with `kl+ku` superdiagonals in rows 0 to `kl+ku`, and the * multipliers used during the factorization are stored in - * rows kl+ku+1 to 2*kl+ku. Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB (ldab >= 2*kl+ku+1). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix - * was interchanged with row ipiv[i]. Array of dimension n. - * @param[in] anorm If norm = '1' or "O", the 1-norm of the original matrix A. - * If norm = "I", the infinity-norm of the original matrix A. + * rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension `n`. + * The pivot indices; for `0<=i= 0). - * @param[in] n The number of columns of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The band matrix A, stored in band format. - * Array of dimension (ldab, n). - * The matrix A is stored in rows 0 to kl+ku, so that - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * @param[in] ldab The leading dimension of the array AB (ldab >= kl+ku+1). - * @param[out] R If info = 0 or info > m, R contains the row scale factors - * for A. Array of dimension m. - * @param[out] C If info = 0, C contains the column scale factors for A. - * Array of dimension n. - * @param[out] rowcnd If info = 0 or info > m, rowcnd contains the ratio of the - * smallest R(i) to the largest R(i). If rowcnd >= 0.1 and - * amax is neither too large nor too small, it is not worth - * scaling by R. - * @param[out] colcnd If info = 0, colcnd contains the ratio of the smallest - * C(j) to the largest C(j). If colcnd >= 0.1, it is not - * worth scaling by C. - * @param[out] amax Absolute value of largest matrix element. If amax is very + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The band matrix A, stored in band format. The matrix A is + * stored in rows 0 to `kl+ku`, so that + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[out] R Array of dimension `m`. + * If `info=0` or `info>m`, `R` contains the row scale + * factors for A. + * @param[out] C Array of dimension `n`. + * If `info=0`, `C` contains the column scale factors for A. + * @param[out] rowcnd If `info=0` or `info>m`, `rowcnd` contains the ratio of the + * smallest R(i) to the largest R(i). If `rowcnd>=0.1` and + * `amax` is neither too large nor too small, it is not worth + * scaling by `R`. + * @param[out] colcnd If `info=0`, `colcnd` contains the ratio of the smallest + * C(j) to the largest C(j). If `colcnd>=0.1`, it is not + * worth scaling by `C`. + * @param[out] amax Absolute value of largest matrix element. If `amax` is very * close to overflow or very close to underflow, the matrix * should be scaled. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, and i is - * - <= m: the i-th row of A is exactly zero (1-based) - * - > m: the (i-m)-th column of A is exactly zero (1-based) + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, and i is + * - `i<=m`: the i-th row of A is exactly zero (1-based) + * - `i>m`: the (i-m)-th column of A is exactly zero + * (1-based) */ void sgbequ( const INT m, diff --git a/src/s/sgbequb.c b/src/s/sgbequb.c index 38951c04..cf12991a 100644 --- a/src/s/sgbequb.c +++ b/src/s/sgbequb.c @@ -9,53 +9,55 @@ /** * SGBEQUB computes row and column scalings intended to equilibrate an - * M-by-N band matrix A and reduce its condition number. R returns the row - * scale factors and C the column scale factors, chosen to try to make + * `m`-by-`n` band matrix A and reduce its condition number. `R` returns the row + * scale factors and `C` the column scale factors, chosen to try to make * the largest element in each row and column of the matrix B with - * elements B(i,j)=R(i)*A(i,j)*C(j) have an absolute value of at most + * elements `B(i,j)=R(i)*A(i,j)*C(j)` have an absolute value of at most * the radix. * - * R(i) and C(j) are restricted to be a power of the radix between + * `R(i)` and `C(j)` are restricted to be a power of the radix between * SMLNUM = smallest safe number and BIGNUM = largest safe number. Use * of these scaling factors is not guaranteed to reduce the condition * number of A but works well in practice. * - * This routine differs from SGBEQU by restricting the scaling factors + * This routine differs from SGEEQU by restricting the scaling factors * to a power of the radix. Barring over- and underflow, scaling by * these factors introduces no additional rounding errors. However, the * scaled entries' magnitudes are no longer approximately 1 but lie - * between sqrt(radix) and 1/sqrt(radix). + * between `sqrt(radix)` and `1/sqrt(radix)`. * - * @param[in] m The number of rows of the matrix A (m >= 0). - * @param[in] n The number of columns of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The band matrix A, stored in band format. - * Array of dimension (ldab, n). - * The matrix A is stored in rows 0 to kl+ku, so that - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * @param[in] ldab The leading dimension of the array AB (ldab >= kl+ku+1). - * @param[out] R If info = 0 or info > m, R contains the row scale factors - * for A. Array of dimension m. - * @param[out] C If info = 0, C contains the column scale factors for A. - * Array of dimension n. - * @param[out] rowcnd If info = 0 or info > m, rowcnd contains the ratio of the - * smallest R(i) to the largest R(i). If rowcnd >= 0.1 and - * amax is neither too large nor too small, it is not worth - * scaling by R. - * @param[out] colcnd If info = 0, colcnd contains the ratio of the smallest - * C(j) to the largest C(j). If colcnd >= 0.1, it is not - * worth scaling by C. - * @param[out] amax Absolute value of largest matrix element. If amax is very + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The band matrix A, stored in band format. The matrix A is + * stored in rows 0 to `kl+ku`, so that + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[out] R Array of dimension `m`. + * If `info=0` or `info>m`, `R` contains the row scale + * factors for A. + * @param[out] C Array of dimension `n`. + * If `info=0`, `C` contains the column scale factors for A. + * @param[out] rowcnd If `info=0` or `info>m`, `rowcnd` contains the ratio of the + * smallest R(i) to the largest R(i). If `rowcnd>=0.1` and + * `amax` is neither too large nor too small, it is not worth + * scaling by `R`. + * @param[out] colcnd If `info=0`, `colcnd` contains the ratio of the smallest + * C(j) to the largest C(j). If `colcnd>=0.1`, it is not + * worth scaling by `C`. + * @param[out] amax Absolute value of largest matrix element. If `amax` is very * close to overflow or very close to underflow, the matrix * should be scaled. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, and i is - * - <= m: the i-th row of A is exactly zero (1-based) - * - > m: the (i-m)-th column of A is exactly zero (1-based) + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, and i is + * - `i<=m`: the i-th row of A is exactly zero (1-based) + * - `i>m`: the (i-m)-th column of A is exactly zero + * (1-based) */ void sgbequb( const INT m, diff --git a/src/s/sgbrfs.c b/src/s/sgbrfs.c index 6534db20..60cd1cb4 100644 --- a/src/s/sgbrfs.c +++ b/src/s/sgbrfs.c @@ -14,40 +14,44 @@ * error bounds and backward error estimates for the solution. * * @param[in] trans Specifies the form of the system of equations: - * - 'N': A * X = B (No transpose) - * - 'T': A**T * X = B (Transpose) - * - 'C': A**H * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] nrhs The number of right hand sides (nrhs >= 0). - * @param[in] AB The original band matrix A, stored in rows 0 to kl+ku. - * The j-th column of A is stored in the j-th column of AB: - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku)<=i<=min(n-1,j+kl). - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of AB (ldab >= kl+ku+1). - * @param[in] AFB The LU factorization of A, as computed by sgbtrf. - * U is stored in rows 0 to kl+ku, and the multipliers - * are stored in rows kl+ku+1 to 2*kl+ku. - * Array of dimension (ldafb, n). - * @param[in] ldafb The leading dimension of AFB (ldafb >= 2*kl+ku+1). - * @param[in] ipiv The pivot indices from sgbtrf. Array of dimension n. - * @param[in] B The right hand side matrix B. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B (ldb >= max(1,n)). - * @param[in,out] X On entry, the solution matrix X, as computed by sgbtrs. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The original band matrix A, stored in rows 0 to `kl+ku`. + * The j-th column of A is stored in the j-th column of `AB`: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. + * @param[in] ldab The leading dimension of `AB`. `ldab>=kl+ku+1`. + * @param[in] AFB Array of dimension (`ldafb`, `n`). + * The LU factorization of A, as computed by SGBTRF. + * U is stored in rows 0 to `kl+ku`, and the multipliers + * are stored in rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldafb The leading dimension of `AFB`. `ldafb>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension `n`. + * The pivot indices from SGBTRF. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The right hand side matrix `B`. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[in,out] X Array of dimension (`ldx`, `nrhs`). + * On entry, the solution matrix X, as computed by SGBTRS. * On exit, the improved solution matrix X. - * Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X (ldx >= max(1,n)). - * @param[out] ferr The estimated forward error bound for each solution vector - * X(j). Array of dimension nrhs. - * @param[out] berr The componentwise relative backward error of each solution - * vector X(j). Array of dimension nrhs. - * @param[out] work Workspace array of dimension (3*n). - * @param[out] iwork Integer workspace array of dimension (n). + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. + * @param[out] ferr Array of dimension `nrhs`. + * The estimated forward error bound for each solution vector + * X(j). + * @param[out] berr Array of dimension `nrhs`. + * The componentwise relative backward error of each solution + * vector X(j). + * @param[out] work Workspace array of dimension (`3*n`). + * @param[out] iwork Integer workspace array of dimension (`n`). * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void sgbrfs( const char* trans, diff --git a/src/s/sgbsv.c b/src/s/sgbsv.c index a77f0a1f..6454194b 100644 --- a/src/s/sgbsv.c +++ b/src/s/sgbsv.c @@ -6,47 +6,73 @@ /** * SGBSV computes the solution to a real system of linear equations - * A * X = B, - * where A is a band matrix of order N with KL subdiagonals and KU - * superdiagonals, and X and B are N-by-NRHS matrices. + * @rst + * .. code-block:: text + * + * A * X = B + * @endrst + * where A is a band matrix of order `n` with `kl` subdiagonals and `ku` + * superdiagonals, and X and `B` are `n`-by-`nrhs` matrices. * * The LU decomposition with partial pivoting and row interchanges is * used to factor A as A = L * U, where L is a product of permutation - * and unit lower triangular matrices with KL subdiagonals, and U is - * upper triangular with KL+KU superdiagonals. The factored form of A + * and unit lower triangular matrices with `kl` subdiagonals, and U is + * upper triangular with `kl+ku` superdiagonals. The factored form of A * is then used to solve the system of equations A * X = B. * * @param[in] n The number of linear equations, i.e., the order of the - * matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). + * matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of - * columns of the matrix B (nrhs >= 0). - * @param[in,out] AB On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * columns of the matrix `B`. `nrhs>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku)<=i<=min(n-1,j+kl). + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB (ldab >= 2*kl+ku+1). - * @param[out] ipiv The pivot indices that define the permutation matrix P; - * row i of the matrix was interchanged with row ipiv[i]. - * Array of dimension n, 0-based. - * @param[in,out] B On entry, the N-by-NRHS right hand side matrix B. - * On exit, if info = 0, the N-by-NRHS solution matrix X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B (ldb >= max(1,n)). + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `n`. + * The pivot indices that define the permutation matrix P; + * row i of the matrix was interchanged with row `ipiv[i]`. + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n`-by-`nrhs` right hand side matrix `B`. + * On exit, if `info=0`, the `n`-by-`nrhs` solution matrix X. + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and the solution has not been computed. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and the solution has not been computed. + * + * @par Further Details: + * @rst + * The band storage scheme is illustrated by the following example, when + * m = n = 6, kl = 2, ku = 1: + * + * .. code-block:: text + * + * On entry: On exit: + * + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * + * + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void sgbsv( const INT n, diff --git a/src/s/sgbsvx.c b/src/s/sgbsvx.c index c91e97ed..05068d3b 100644 --- a/src/s/sgbsvx.c +++ b/src/s/sgbsvx.c @@ -12,57 +12,117 @@ /** * SGBSVX uses the LU factorization to compute the solution to a real - * system of linear equations A * X = B, A**T * X = B, or A**H * X = B, - * where A is a band matrix of order N with KL subdiagonals and KU - * superdiagonals, and X and B are N-by-NRHS matrices. + * system of linear equations + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst + * where A is a band matrix of order `n` with `kl` subdiagonals and `ku` + * superdiagonals, and X and `B` are `n`-by-`nrhs` matrices. * * Error bounds on the solution and a condition estimate are also provided. * - * @param[in] fact 'F': AFB and IPIV contain the factored form of A. - * 'N': The matrix A will be copied to AFB and factored. - * 'E': The matrix A will be equilibrated if necessary, - * then copied to AFB and factored. - * @param[in] trans 'N': A * X = B (No transpose) - * 'T': A**T * X = B (Transpose) - * 'C': A**H * X = B (Conjugate transpose = Transpose) - * @param[in] n The number of linear equations (order of A). n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in,out] AB On entry, the matrix A in band storage, in rows 0 to kl+ku. - * On exit, if equilibration was done, A is scaled. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of AB. ldab >= kl+ku+1. - * @param[in,out] AFB On entry (if fact='F'), contains the LU factors. + * @rst + * The following steps are performed by this subroutine: + * + * 1. If ``fact='E'``, real scaling factors are computed to equilibrate + * the system:: + * + * trans = 'N': diag(R)*A*diag(C) *inv(diag(C))*X = diag(R)*B + * trans = 'T': (diag(R)*A*diag(C))**T *inv(diag(R))*X = diag(C)*B + * trans = 'C': (diag(R)*A*diag(C))**H *inv(diag(R))*X = diag(C)*B + * + * Whether or not the system will be equilibrated depends on the + * scaling of the matrix A, but if equilibration is used, A is + * overwritten by diag(R)*A*diag(C) and B by diag(R)*B (if ``trans='N'``) + * or diag(C)*B (if ``trans='T'`` or ``'C'``). + * + * 2. If ``fact='N'`` or ``'E'``, the LU decomposition is used to factor + * the matrix A (after equilibration if ``fact='E'``) as:: + * + * A = L * U + * + * where L is a product of permutation and unit lower triangular + * matrices with kl subdiagonals, and U is upper triangular with + * kl+ku superdiagonals. + * + * 3. 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. + * + * 4. The system of equations is solved for X using the factored form of A. + * + * 5. Iterative refinement is applied to improve the computed solution + * matrix and calculate error bounds and backward error estimates for it. + * + * 6. If equilibration was used, the matrix X is premultiplied by + * ``diag(C)`` (if ``trans='N'``) or ``diag(R)`` (if ``trans='T'`` or + * ``'C'``) so that it solves the original system before equilibration. + * @endrst + * + * @param[in] fact + * - `'F'`: `AFB` and `ipiv` contain the factored form of A. + * - `'N'`: The matrix A will be copied to `AFB` and factored. + * - `'E'`: The matrix A will be equilibrated if necessary, + * then copied to `AFB` and factored. + * @param[in] trans + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose = Transpose) + * @param[in] n The number of linear equations (order of A). `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows 0 to + * `kl+ku`. The j-th column of A is stored in the j-th column + * of the array `AB` as follows: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. + * On exit, if `equed != 'N'`, A is scaled. + * @param[in] ldab The leading dimension of `AB`. `ldab>=kl+ku+1`. + * @param[in,out] AFB Array of dimension (`ldafb`, `n`). + * On entry (if `fact='F'`), contains the LU factors. * On exit, contains the factors L and U. - * Array of dimension (ldafb, n). - * @param[in] ldafb The leading dimension of AFB. ldafb >= 2*kl+ku+1. - * @param[in,out] ipiv Pivot indices from factorization. Array of dimension (n). - * @param[in,out] equed On entry (if fact='F'), specifies equilibration done. + * @param[in] ldafb The leading dimension of `AFB`. `ldafb>=2*kl+ku+1`. + * @param[in,out] ipiv Array of dimension (`n`). + * Pivot indices from factorization. + * @param[in,out] equed On entry (if `fact='F'`), specifies equilibration done. * On exit, specifies the form of equilibration: - * 'N': No equilibration - * 'R': Row equilibration (A := diag(R) * A) - * 'C': Column equilibration (A := A * diag(C)) - * 'B': Both (A := diag(R) * A * diag(C)) - * @param[in,out] R Row scale factors. Array of dimension (n). - * @param[in,out] C Column scale factors. Array of dimension (n). - * @param[in,out] B On entry, the N-by-NRHS right hand side matrix B. - * On exit, if equilibration was done, B is scaled. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[out] X The N-by-NRHS solution matrix X. Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). + * - `'N'`: No equilibration + * - `'R'`: Row equilibration (A := diag(R) * A) + * - `'C'`: Column equilibration (A := A * diag(C)) + * - `'B'`: Both (A := diag(R) * A * diag(C)) + * @param[in,out] R Array of dimension (`n`). + * Row scale factors. + * @param[in,out] C Array of dimension (`n`). + * Column scale factors. + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n`-by-`nrhs` right hand side matrix `B`. + * On exit, if equilibration was done, `B` is scaled. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[out] X Array of dimension (`ldx`, `nrhs`). + * The `n`-by-`nrhs` solution matrix X. + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. * @param[out] rcond Reciprocal condition number estimate. - * @param[out] ferr Forward error bound for each solution vector. Array of dimension (nrhs). - * @param[out] berr Backward error for each solution vector. Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (3*n). - * On exit, work[0] contains the reciprocal pivot growth factor. - * @param[out] iwork Integer workspace array of dimension (n). + * @param[out] ferr Array of dimension (`nrhs`). + * Forward error bound for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * Backward error for each solution vector. + * @param[out] work Workspace array of dimension (`3*n`). + * On exit, `work[0]` contains the reciprocal pivot growth + * factor. + * @param[out] iwork Integer workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i,i) is exactly zero (1-based). - * if info = n+1, U is nonsingular but RCOND < machine precision. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero (1-based). + * If `info=n+1`, U is nonsingular but `rcond` < machine + * precision. */ void sgbsvx( const char* fact, diff --git a/src/s/sgbtf2.c b/src/s/sgbtf2.c index bef31933..bb6326e9 100644 --- a/src/s/sgbtf2.c +++ b/src/s/sgbtf2.c @@ -18,55 +18,54 @@ * trapezoidal if m > n), and U is upper triangular (upper trapezoidal * if m < n). * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB Double precision array, dimension (ldab, n). - * On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[out] ipiv Integer array, dimension (min(m,n)). - * The pivot indices; for 0 <= i < min(m,n), row i of the - * matrix was interchanged with row ipiv[i]. 0-based indexing. + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `min(m,n)`. + * The pivot indices; for `0<=i 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and division by zero will occur if it is used - * to solve a system of equations. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and division by zero will occur if it + * is used to solve a system of equations. + * * @par Further Details: + * @rst * The band storage scheme is illustrated by the following example, when * m = n = 6, kl = 2, ku = 1: * - * On entry (0-based indexing, rows 0 to 5, kl=2, ku=1, kv=kl+ku=3): + * .. code-block:: text * - * Row 0: * * * (fill-in storage) - * Row 1: * * a02 a13 a24 a35 (U superdiagonals) - * Row 2: * a01 a12 a23 a34 a45 (U superdiagonals) - * Row 3: a00 a11 a22 a33 a44 a55 (diagonal) - * Row 4: a10 a21 a32 a43 a54 * (L multipliers after factorization) - * Row 5: a20 a31 a42 a53 * * (L multipliers after factorization) + * On entry: On exit: * - * On exit: - * Row 0: * * * u03 u14 u25 (U fill-in from pivoting) - * Row 1: * * u02 u13 u24 u35 (U superdiagonals) - * Row 2: * u01 u12 u23 u34 u45 (U superdiagonals) - * Row 3: u00 u11 u22 u33 u44 u55 (U diagonal) - * Row 4: m10 m21 m32 m43 m54 * (L multipliers) - * Row 5: m20 m31 m42 m53 * * (L multipliers) + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * * - * Array elements marked * are not used by the routine. + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void sgbtf2( const INT m, diff --git a/src/s/sgbtrf.c b/src/s/sgbtrf.c index b25cc4be..26b52d84 100644 --- a/src/s/sgbtrf.c +++ b/src/s/sgbtrf.c @@ -23,33 +23,54 @@ * trapezoidal if m > n), and U is upper triangular (upper trapezoidal * if m < n). * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB Double precision array, dimension (ldab, n). - * On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[out] ipiv Integer array, dimension (min(m,n)). - * The pivot indices; for 0 <= i < min(m,n), row i of the - * matrix was interchanged with row ipiv[i]. 0-based indexing. + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `min(m,n)`. + * The pivot indices; for `0<=i 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and division by zero will occur if it is used - * to solve a system of equations. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and division by zero will occur if it + * is used to solve a system of equations. + * + * @par Further Details: + * @rst + * The band storage scheme is illustrated by the following example, when + * m = n = 6, kl = 2, ku = 1: + * + * .. code-block:: text + * + * On entry: On exit: + * + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * + * + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void sgbtrf( const INT m, diff --git a/src/s/sgbtrs.c b/src/s/sgbtrs.c index 32a29321..88cef624 100644 --- a/src/s/sgbtrs.c +++ b/src/s/sgbtrs.c @@ -9,37 +9,41 @@ /** * SGBTRS solves a system of linear equations - * A * X = B or A**T * X = B + * @rst + * .. code-block:: text + * + * A * X = B or A**T * X = B + * @endrst * with a general band matrix A using the LU factorization computed * by SGBTRF. * * @param[in] trans Specifies the form of the system of equations: - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**T * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**T * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of - * columns of the matrix B. nrhs >= 0. - * @param[in] AB Double precision array, dimension (ldab, n). + * columns of the matrix `B`. `nrhs>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). * Details of the LU factorization of the band matrix A, * as computed by SGBTRF. U is stored as an upper triangular - * band matrix with kl+ku superdiagonals in rows 0 to kl+ku, + * band matrix with `kl+ku` superdiagonals in rows 0 to `kl+ku`, * and the multipliers used during the factorization are - * stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[in] ipiv Integer array, dimension (n). - * The pivot indices; for 0 <= i < n, row i of the matrix - * was interchanged with row ipiv[i]. 0-based indexing. - * @param[in,out] B Double precision array, dimension (ldb, nrhs). - * On entry, the right hand side matrix B. + * stored in rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i= max(1,n). + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void sgbtrs( const char* trans, diff --git a/src/s/sgtcon.c b/src/s/sgtcon.c index ae0f9986..3a5e9c3f 100644 --- a/src/s/sgtcon.c +++ b/src/s/sgtcon.c @@ -11,34 +11,42 @@ * SGTTRF. * * An estimate is obtained for norm(inv(A)), and the reciprocal of the - * condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))). + * condition number is computed as + * @rst + * .. code-block:: text + * + * rcond = 1 / (anorm * norm(inv(A))) + * @endrst * * @param[in] norm Specifies whether the 1-norm condition number or the * infinity-norm condition number is required: - * = '1' or 'O': 1-norm - * = 'I': Infinity-norm - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the + * - `'1'` or `'O'`: 1-norm + * - `'I'`: Infinity-norm + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the * LU factorization of A as computed by SGTTRF. - * Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U - * from the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first superdiagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second superdiagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. Array of dimension (n). - * @param[in] anorm If norm = '1' or "O", the 1-norm of the original matrix A. - * If norm = "I", the infinity-norm of the original matrix A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U + * from the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first superdiagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second superdiagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in] DL The (n-1) subdiagonal elements of A. Array of dimension (n-1). - * @param[in] D The diagonal elements of A. Array of dimension (n). - * @param[in] DU The (n-1) superdiagonal elements of A. Array of dimension (n-1). - * @param[in] DLF The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] DF The n diagonal elements of U. Array of dimension (n). - * @param[in] DUF The (n-1) elements of the first superdiagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second superdiagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices. Array of dimension (n). - * @param[in] B The right hand side matrix B. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[in,out] X On entry, the solution matrix X, as computed by SGTTRS. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) subdiagonal elements of A. + * @param[in] D Array of dimension (`n`). + * The diagonal elements of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) superdiagonal elements of A. + * @param[in] DLF Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] DF Array of dimension (`n`). + * The n diagonal elements of U. + * @param[in] DUF Array of dimension (`n-1`). + * The (n-1) elements of the first superdiagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second superdiagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The right hand side matrix `B`. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[in,out] X Array of dimension (`ldx`, `nrhs`). + * On entry, the solution matrix X, as computed by SGTTRS. * On exit, the improved solution matrix X. - * Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). - * @param[out] ferr The estimated forward error bound for each solution vector. - * Array of dimension (nrhs). - * @param[out] berr The componentwise relative backward error of each solution. - * Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (3*n). - * @param[out] iwork Integer workspace array of dimension (n). + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. + * @param[out] ferr Array of dimension (`nrhs`). + * The estimated forward error bound for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * The componentwise relative backward error of each solution. + * @param[out] work Workspace array of dimension (`3*n`). + * @param[out] iwork Integer workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void sgtrfs( const char* trans, diff --git a/src/s/sgtsv.c b/src/s/sgtsv.c index dd958448..20197d62 100644 --- a/src/s/sgtsv.c +++ b/src/s/sgtsv.c @@ -9,38 +9,41 @@ /** * SGTSV solves the equation + * @rst + * .. code-block:: text * - * A*X = B, - * - * where A is an n by n tridiagonal matrix, by Gaussian elimination with + * A * X = B + * @endrst + * where A is an `n` by `n` tridiagonal matrix, by Gaussian elimination with * partial pivoting. * * Note that the equation A**T*X = B may be solved by interchanging the - * order of the arguments DU and DL. + * order of the arguments `DU` and `DL`. * - * @param[in] n The order of the matrix A. n >= 0. + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in,out] DL On entry, the (n-1) sub-diagonal elements of A. - * On exit, DL is overwritten by the (n-2) elements of the + * of the matrix `B`. `nrhs>=0`. + * @param[in,out] DL Array of dimension (`n-1`). + * On entry, the (n-1) sub-diagonal elements of A. + * On exit, `DL` is overwritten by the (n-2) elements of the * second super-diagonal of the upper triangular matrix U from - * the LU factorization of A, in DL[0], ..., DL[n-3]. - * Array of dimension (n-1). - * @param[in,out] D On entry, the diagonal elements of A. - * On exit, D is overwritten by the n diagonal elements of U. - * Array of dimension (n). - * @param[in,out] DU On entry, the (n-1) super-diagonal elements of A. - * On exit, DU is overwritten by the (n-1) elements of the first + * the LU factorization of A, in `DL[0]`, ..., `DL[n-3]`. + * @param[in,out] D Array of dimension (`n`). + * On entry, the diagonal elements of A. + * On exit, `D` is overwritten by the n diagonal elements of U. + * @param[in,out] DU Array of dimension (`n-1`). + * On entry, the (n-1) super-diagonal elements of A. + * On exit, `DU` is overwritten by the (n-1) elements of the first * super-diagonal of U. - * Array of dimension (n-1). - * @param[in,out] B On entry, the N by NRHS matrix of right hand side matrix B. - * On exit, if info = 0, the N by NRHS solution matrix X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n` by `nrhs` matrix of right hand side matrix `B`. + * On exit, if `info=0`, the `n` by `nrhs` solution matrix X. + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i-1,i-1) is exactly zero (0-based), and the + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero, and the * solution has not been computed. The factorization has not * been completed unless i = n. */ diff --git a/src/s/sgtsvx.c b/src/s/sgtsvx.c index 44f4b9ff..bcd6fbe0 100644 --- a/src/s/sgtsvx.c +++ b/src/s/sgtsvx.c @@ -10,48 +10,89 @@ /** * SGTSVX uses the LU factorization to compute the solution to a real - * system of linear equations A * X = B or A**T * X = B, - * where A is a tridiagonal matrix of order N and X and B are N-by-NRHS + * system of linear equations + * @rst + * .. code-block:: text + * + * A * X = B or A**T * X = B + * @endrst + * where A is a tridiagonal matrix of order `n` and X and `B` are `n`-by-`nrhs` * matrices. * * Error bounds on the solution and a condition estimate are also provided. * - * @param[in] fact Specifies whether the factored form of A has been supplied. - * = 'F': DLF, DF, DUF, DU2, and IPIV contain the factored form. - * = 'N': The matrix will be copied and factored. + * @rst + * The following steps are performed: + * + * 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 upper triangular with nonzeros in + * only the main diagonal and first two superdiagonals. + * + * 2. 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. + * + * 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. + * @endrst + * + * @param[in] fact + * - `'F'`: `DLF`, `DF`, `DUF`, `DU2`, and `ipiv` contain the + * factored form of A. + * - `'N'`: The matrix will be copied and factored. * @param[in] trans Specifies the form of the system of equations: - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**H * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in] DL The (n-1) subdiagonal elements of A. Array of dimension (n-1). - * @param[in] D The diagonal elements of A. Array of dimension (n). - * @param[in] DU The (n-1) superdiagonal elements of A. Array of dimension (n-1). - * @param[in,out] DLF If fact = "F", the (n-1) multipliers from LU factorization. - * If fact = "N", output. Array of dimension (n-1). - * @param[in,out] DF If fact = "F", the n diagonal elements of U. - * If fact = "N", output. Array of dimension (n). - * @param[in,out] DUF If fact = "F", the (n-1) elements of first superdiagonal of U. - * If fact = "N", output. Array of dimension (n-1). - * @param[in,out] DU2 If fact = "F", the (n-2) elements of second superdiagonal of U. - * If fact = "N", output. Array of dimension (n-2). - * @param[in,out] ipiv If fact = "F", the pivot indices from factorization. - * If fact = "N", output. Array of dimension (n). - * @param[in] B The N-by-NRHS right hand side matrix. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[out] X The N-by-NRHS solution matrix. Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) subdiagonal elements of A. + * @param[in] D Array of dimension (`n`). + * The diagonal elements of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) superdiagonal elements of A. + * @param[in,out] DLF Array of dimension (`n-1`). + * If `fact='F'`, the (n-1) multipliers from LU factorization. + * If `fact='N'`, output. + * @param[in,out] DF Array of dimension (`n`). + * If `fact='F'`, the n diagonal elements of U. + * If `fact='N'`, output. + * @param[in,out] DUF Array of dimension (`n-1`). + * If `fact='F'`, the (n-1) elements of first superdiagonal of U. + * If `fact='N'`, output. + * @param[in,out] DU2 Array of dimension (`n-2`). + * If `fact='F'`, the (n-2) elements of second superdiagonal of U. + * If `fact='N'`, output. + * @param[in,out] ipiv Array of dimension (`n`). + * If `fact='F'`, the pivot indices from factorization. + * If `fact='N'`, output. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The `n`-by-`nrhs` right hand side matrix. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[out] X Array of dimension (`ldx`, `nrhs`). + * The `n`-by-`nrhs` solution matrix. + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. * @param[out] rcond The reciprocal condition number estimate. - * @param[out] ferr Forward error bounds for each solution vector. Array of dimension (nrhs). - * @param[out] berr Backward error for each solution vector. Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (3*n). - * @param[out] iwork Integer workspace array of dimension (n). + * @param[out] ferr Array of dimension (`nrhs`). + * Forward error bounds for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * Backward error for each solution vector. + * @param[out] work Workspace array of dimension (`3*n`). + * @param[out] iwork Integer workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i (i <= n), U(i,i) is exactly zero - * - = n+1: U is nonsingular, but rcond < machine precision + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i` (i <= `n`), U(i,i) is exactly zero + * - `info=n+1`: U is nonsingular, but `rcond` < machine + * precision */ void sgtsvx( const char* fact, diff --git a/src/s/sgttrf.c b/src/s/sgttrf.c index b3cf2b21..48676161 100644 --- a/src/s/sgttrf.c +++ b/src/s/sgttrf.c @@ -11,34 +11,39 @@ * using elimination with partial pivoting and row interchanges. * * The factorization has the form - * A = L * U + * @rst + * .. code-block:: text + * + * A = L * U + * @endrst * where L is a product of permutation and unit lower bidiagonal * matrices and U is upper triangular with nonzeros in only the main * diagonal and first two superdiagonals. * - * @param[in] n The order of the matrix A. n >= 0. - * @param[in,out] DL On entry, the (n-1) sub-diagonal elements of A. + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in,out] DL Array of dimension (`n-1`). + * On entry, the (n-1) sub-diagonal elements of A. * On exit, the (n-1) multipliers that define the matrix L * from the LU factorization of A. - * Array of dimension (n-1). - * @param[in,out] D On entry, the diagonal elements of A. + * @param[in,out] D Array of dimension (`n`). + * On entry, the diagonal elements of A. * On exit, the n diagonal elements of the upper triangular * matrix U from the LU factorization of A. - * Array of dimension (n). - * @param[in,out] DU On entry, the (n-1) super-diagonal elements of A. + * @param[in,out] DU Array of dimension (`n-1`). + * On entry, the (n-1) super-diagonal elements of A. * On exit, the (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[out] DU2 On exit, the (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[out] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not + * @param[out] DU2 Array of dimension (`n-2`). + * On exit, the (n-2) elements of the second super-diagonal of U. + * @param[out] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i 0: if info = k, U(k-1,k-1) is exactly zero (0-based). + * - `info=0`: successful exit + * - `info<0`: if `info=-k`, the k-th argument had an illegal + * value + * - `info>0`: if `info=k`, U(k,k) is exactly zero. * The factorization has been completed, but the factor U * is exactly singular, and division by zero will occur * if it is used to solve a system of equations. diff --git a/src/s/sgttrs.c b/src/s/sgttrs.c index 1839cd0d..70ad0116 100644 --- a/src/s/sgttrs.c +++ b/src/s/sgttrs.c @@ -7,36 +7,44 @@ /** * SGTTRS solves one of the systems of equations - * A*X = B or A**T*X = B, + * @rst + * .. code-block:: text + * + * A * X = B or A**T * X = B + * @endrst * with a tridiagonal matrix A using the LU factorization computed * by SGTTRF. * * @param[in] trans Specifies the form of the system of equations. - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**T * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A. n >= 0. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**T * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U from - * the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not - * required. Array of dimension (n). - * @param[in,out] B On entry, the matrix of right hand side vectors B. - * On exit, B is overwritten by the solution vectors X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * of the matrix `B`. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U from + * the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first super-diagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second super-diagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i=max(1,n)`. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void sgttrs( const char* trans, diff --git a/src/s/sgtts2.c b/src/s/sgtts2.c index 25a86158..c0e49f77 100644 --- a/src/s/sgtts2.c +++ b/src/s/sgtts2.c @@ -8,33 +8,40 @@ /** * SGTTS2 solves one of the systems of equations - * A*X = B or A**T*X = B, + * @rst + * .. code-block:: text + * + * A * X = B or A**T * X = B + * @endrst * with a tridiagonal matrix A using the LU factorization computed * by SGTTRF. * * @param[in] itrans Specifies the form of the system of equations. - * = 0: A * X = B (No transpose) - * = 1: A**T * X = B (Transpose) - * = 2: A**T * X = B (Conjugate transpose = Transpose) - * @param[in] n The order of the matrix A. n >= 0. + * - `0`: A * X = B (No transpose) + * - `1`: A**T * X = B (Transpose) + * - `2`: A**T * X = B (Conjugate transpose = Transpose) + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U from - * the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not - * required. Array of dimension (n). - * @param[in,out] B On entry, the matrix of right hand side vectors B. - * On exit, B is overwritten by the solution vectors X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * of the matrix `B`. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U from + * the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first super-diagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second super-diagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i=max(1,n)`. */ void sgtts2( const INT itrans, diff --git a/src/s/slaqgb.c b/src/s/slaqgb.c index 54d168fd..1e888bb2 100644 --- a/src/s/slaqgb.c +++ b/src/s/slaqgb.c @@ -8,34 +8,36 @@ #include "semicolon_lapack_single.h" /** - * SLAQGB equilibrates a general M by N band matrix A with KL subdiagonals - * and KU superdiagonals using the row and column scaling factors in the - * vectors R and C. + * SLAQGB equilibrates a general `m` by `n` band matrix A with `kl` subdiagonals + * and `ku` superdiagonals using the row and column scaling factors in the + * vectors `R` and `C`. * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB On entry, the matrix A in band storage, in rows 0 to kl+ku. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows 0 to `kl+ku`. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). + * the array `AB` as follows: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, the equilibrated matrix in the same storage format. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB. ldab >= kl+ku+1. - * @param[in] R The row scale factors for A. Array of dimension (m). - * @param[in] C The column scale factors for A. Array of dimension (n). + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[in] R Array of dimension (`m`). + * The row scale factors for A. + * @param[in] C Array of dimension (`n`). + * The column scale factors for A. * @param[in] rowcnd Ratio of the smallest R(i) to the largest R(i). * @param[in] colcnd Ratio of the smallest C(i) to the largest C(i). * @param[in] amax Absolute value of largest matrix entry. * @param[out] equed Specifies the form of equilibration that was done: - * = 'N': No equilibration - * = 'R': Row equilibration, i.e., A has been premultiplied - * by diag(R). - * = 'C': Column equilibration, i.e., A has been postmultiplied - * by diag(C). - * = 'B': Both row and column equilibration, i.e., A has been - * replaced by diag(R) * A * diag(C). + * - `'N'`: No equilibration + * - `'R'`: Row equilibration, i.e., A has been premultiplied + * by diag(R). + * - `'C'`: Column equilibration, i.e., A has been postmultiplied + * by diag(C). + * - `'B'`: Both row and column equilibration, i.e., A has been + * replaced by diag(R) * A * diag(C). */ void slaqgb( const INT m, diff --git a/src/z/zgbcon.c b/src/z/zgbcon.c index 7d0c17b4..2da3d9e0 100644 --- a/src/z/zgbcon.c +++ b/src/z/zgbcon.c @@ -16,33 +16,39 @@ * * An estimate is obtained for norm(inv(A)), and the reciprocal of the * condition number is computed as - * RCOND = 1 / ( norm(A) * norm(inv(A)) ). + * @rst + * .. code-block:: text + * + * rcond = 1 / ( norm(A) * norm(inv(A)) ) + * @endrst * * @param[in] norm Specifies whether the 1-norm condition number or the * infinity-norm condition number is required: - * - '1' or 'O': 1-norm - * - 'I': Infinity-norm - * @param[in] n The order of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The LU factorization of the band matrix A, as computed - * by zgbtrf. U is stored as an upper triangular band matrix - * with kl+ku superdiagonals in rows 0 to kl+ku, and the + * - `'1'` or `'O'`: 1-norm + * - `'I'`: Infinity-norm + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The LU factorization of the band matrix A, as computed + * by ZGBTRF. U is stored as an upper triangular band matrix + * with `kl+ku` superdiagonals in rows 0 to `kl+ku`, and the * multipliers used during the factorization are stored in - * rows kl+ku+1 to 2*kl+ku. Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB (ldab >= 2*kl+ku+1). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix - * was interchanged with row ipiv[i]. Array of dimension n. - * @param[in] anorm If norm = '1' or "O", the 1-norm of the original matrix A. - * If norm = "I", the infinity-norm of the original matrix A. + * rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension `n`. + * The pivot indices; for `0<=i= 0). - * @param[in] n The number of columns of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The band matrix A, stored in band format. - * Complex array of dimension (ldab, n). - * The matrix A is stored in rows 0 to kl+ku, so that - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * @param[in] ldab The leading dimension of the array AB (ldab >= kl+ku+1). - * @param[out] R If info = 0 or info > m, R contains the row scale factors - * for A. Array of dimension m. - * @param[out] C If info = 0, C contains the column scale factors for A. - * Array of dimension n. - * @param[out] rowcnd If info = 0 or info > m, rowcnd contains the ratio of the - * smallest R(i) to the largest R(i). If rowcnd >= 0.1 and - * amax is neither too large nor too small, it is not worth - * scaling by R. - * @param[out] colcnd If info = 0, colcnd contains the ratio of the smallest - * C(j) to the largest C(j). If colcnd >= 0.1, it is not - * worth scaling by C. - * @param[out] amax Absolute value of largest matrix element. If amax is very + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The band matrix A, stored in band format. The matrix A is + * stored in rows 0 to `kl+ku`, so that + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[out] R Array of dimension `m`. + * If `info=0` or `info>m`, `R` contains the row scale + * factors for A. + * @param[out] C Array of dimension `n`. + * If `info=0`, `C` contains the column scale factors for A. + * @param[out] rowcnd If `info=0` or `info>m`, `rowcnd` contains the ratio of the + * smallest R(i) to the largest R(i). If `rowcnd>=0.1` and + * `amax` is neither too large nor too small, it is not worth + * scaling by `R`. + * @param[out] colcnd If `info=0`, `colcnd` contains the ratio of the smallest + * C(j) to the largest C(j). If `colcnd>=0.1`, it is not + * worth scaling by `C`. + * @param[out] amax Absolute value of largest matrix element. If `amax` is very * close to overflow or very close to underflow, the matrix * should be scaled. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, and i is - * - <= m: the i-th row of A is exactly zero (1-based) - * - > m: the (i-m)-th column of A is exactly zero (1-based) + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, and i is + * - `i<=m`: the i-th row of A is exactly zero (1-based) + * - `i>m`: the (i-m)-th column of A is exactly zero + * (1-based) */ void zgbequ( const INT m, diff --git a/src/z/zgbequb.c b/src/z/zgbequb.c index bb04a03f..5ac19a97 100644 --- a/src/z/zgbequb.c +++ b/src/z/zgbequb.c @@ -10,13 +10,13 @@ /** * ZGBEQUB computes row and column scalings intended to equilibrate an - * M-by-N band matrix A and reduce its condition number. R returns the row - * scale factors and C the column scale factors, chosen to try to make + * `m`-by-`n` band matrix A and reduce its condition number. `R` returns the row + * scale factors and `C` the column scale factors, chosen to try to make * the largest element in each row and column of the matrix B with - * elements B(i,j)=R(i)*A(i,j)*C(j) have an absolute value of at most + * elements `B(i,j)=R(i)*A(i,j)*C(j)` have an absolute value of at most * the radix. * - * R(i) and C(j) are restricted to be a power of the radix between + * `R(i)` and `C(j)` are restricted to be a power of the radix between * SMLNUM = smallest safe number and BIGNUM = largest safe number. Use * of these scaling factors is not guaranteed to reduce the condition * number of A but works well in practice. @@ -25,38 +25,40 @@ * to a power of the radix. Barring over- and underflow, scaling by * these factors introduces no additional rounding errors. However, the * scaled entries' magnitudes are no longer approximately 1 but lie - * between sqrt(radix) and 1/sqrt(radix). + * between `sqrt(radix)` and `1/sqrt(radix)`. * - * @param[in] m The number of rows of the matrix A (m >= 0). - * @param[in] n The number of columns of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] AB The band matrix A, stored in band format. - * Complex array of dimension (ldab, n). - * The matrix A is stored in rows 0 to kl+ku, so that - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * @param[in] ldab The leading dimension of the array AB (ldab >= kl+ku+1). - * @param[out] R If info = 0 or info > m, R contains the row scale factors - * for A. Array of dimension m. - * @param[out] C If info = 0, C contains the column scale factors for A. - * Array of dimension n. - * @param[out] rowcnd If info = 0 or info > m, rowcnd contains the ratio of the - * smallest R(i) to the largest R(i). If rowcnd >= 0.1 and - * amax is neither too large nor too small, it is not worth - * scaling by R. - * @param[out] colcnd If info = 0, colcnd contains the ratio of the smallest - * C(j) to the largest C(j). If colcnd >= 0.1, it is not - * worth scaling by C. - * @param[out] amax Absolute value of largest matrix element. If amax is very + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The band matrix A, stored in band format. The matrix A is + * stored in rows 0 to `kl+ku`, so that + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[out] R Array of dimension `m`. + * If `info=0` or `info>m`, `R` contains the row scale + * factors for A. + * @param[out] C Array of dimension `n`. + * If `info=0`, `C` contains the column scale factors for A. + * @param[out] rowcnd If `info=0` or `info>m`, `rowcnd` contains the ratio of the + * smallest R(i) to the largest R(i). If `rowcnd>=0.1` and + * `amax` is neither too large nor too small, it is not worth + * scaling by `R`. + * @param[out] colcnd If `info=0`, `colcnd` contains the ratio of the smallest + * C(j) to the largest C(j). If `colcnd>=0.1`, it is not + * worth scaling by `C`. + * @param[out] amax Absolute value of largest matrix element. If `amax` is very * close to overflow or very close to underflow, the matrix * should be scaled. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, and i is - * - <= m: the i-th row of A is exactly zero (1-based) - * - > m: the (i-m)-th column of A is exactly zero (1-based) + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, and i is + * - `i<=m`: the i-th row of A is exactly zero (1-based) + * - `i>m`: the (i-m)-th column of A is exactly zero + * (1-based) */ void zgbequb( const INT m, diff --git a/src/z/zgbrfs.c b/src/z/zgbrfs.c index 9abca1a9..24435640 100644 --- a/src/z/zgbrfs.c +++ b/src/z/zgbrfs.c @@ -15,40 +15,44 @@ * error bounds and backward error estimates for the solution. * * @param[in] trans Specifies the form of the system of equations: - * - 'N': A * X = B (No transpose) - * - 'T': A**T * X = B (Transpose) - * - 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). - * @param[in] nrhs The number of right hand sides (nrhs >= 0). - * @param[in] AB The original band matrix A, stored in rows 0 to kl+ku. - * The j-th column of A is stored in the j-th column of AB: - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku)<=i<=min(n-1,j+kl). - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of AB (ldab >= kl+ku+1). - * @param[in] AFB The LU factorization of A, as computed by zgbtrf. - * U is stored in rows 0 to kl+ku, and the multipliers - * are stored in rows kl+ku+1 to 2*kl+ku. - * Array of dimension (ldafb, n). - * @param[in] ldafb The leading dimension of AFB (ldafb >= 2*kl+ku+1). - * @param[in] ipiv The pivot indices from zgbtrf. Array of dimension n. - * @param[in] B The right hand side matrix B. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B (ldb >= max(1,n)). - * @param[in,out] X On entry, the solution matrix X, as computed by zgbtrs. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). + * The original band matrix A, stored in rows 0 to `kl+ku`. + * The j-th column of A is stored in the j-th column of `AB`: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. + * @param[in] ldab The leading dimension of `AB`. `ldab>=kl+ku+1`. + * @param[in] AFB Array of dimension (`ldafb`, `n`). + * The LU factorization of A, as computed by ZGBTRF. + * U is stored in rows 0 to `kl+ku`, and the multipliers + * are stored in rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldafb The leading dimension of `AFB`. `ldafb>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension `n`. + * The pivot indices from ZGBTRF. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The right hand side matrix `B`. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[in,out] X Array of dimension (`ldx`, `nrhs`). + * On entry, the solution matrix X, as computed by ZGBTRS. * On exit, the improved solution matrix X. - * Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X (ldx >= max(1,n)). - * @param[out] ferr The estimated forward error bound for each solution vector - * X(j). Array of dimension nrhs. - * @param[out] berr The componentwise relative backward error of each solution - * vector X(j). Array of dimension nrhs. - * @param[out] work Complex workspace array of dimension (2*n). - * @param[out] rwork Real workspace array of dimension (n). + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. + * @param[out] ferr Array of dimension `nrhs`. + * The estimated forward error bound for each solution vector + * X(j). + * @param[out] berr Array of dimension `nrhs`. + * The componentwise relative backward error of each solution + * vector X(j). + * @param[out] work Complex workspace array of dimension (`2*n`). + * @param[out] rwork Real workspace array of dimension (`n`). * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void zgbrfs( const char* trans, diff --git a/src/z/zgbsv.c b/src/z/zgbsv.c index 9ea113c6..6899ae45 100644 --- a/src/z/zgbsv.c +++ b/src/z/zgbsv.c @@ -7,47 +7,73 @@ /** * ZGBSV computes the solution to a complex system of linear equations - * A * X = B, - * where A is a band matrix of order N with KL subdiagonals and KU - * superdiagonals, and X and B are N-by-NRHS matrices. + * @rst + * .. code-block:: text + * + * A * X = B + * @endrst + * where A is a band matrix of order `n` with `kl` subdiagonals and `ku` + * superdiagonals, and X and `B` are `n`-by-`nrhs` matrices. * * The LU decomposition with partial pivoting and row interchanges is * used to factor A as A = L * U, where L is a product of permutation - * and unit lower triangular matrices with KL subdiagonals, and U is - * upper triangular with KL+KU superdiagonals. The factored form of A + * and unit lower triangular matrices with `kl` subdiagonals, and U is + * upper triangular with `kl+ku` superdiagonals. The factored form of A * is then used to solve the system of equations A * X = B. * * @param[in] n The number of linear equations, i.e., the order of the - * matrix A (n >= 0). - * @param[in] kl The number of subdiagonals within the band of A (kl >= 0). - * @param[in] ku The number of superdiagonals within the band of A (ku >= 0). + * matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of - * columns of the matrix B (nrhs >= 0). - * @param[in,out] AB On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * columns of the matrix `B`. `nrhs>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku)<=i<=min(n-1,j+kl). + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB (ldab >= 2*kl+ku+1). - * @param[out] ipiv The pivot indices that define the permutation matrix P; - * row i of the matrix was interchanged with row ipiv[i]. - * Array of dimension n, 0-based. - * @param[in,out] B On entry, the N-by-NRHS right hand side matrix B. - * On exit, if info = 0, the N-by-NRHS solution matrix X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B (ldb >= max(1,n)). + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `n`. + * The pivot indices that define the permutation matrix P; + * row i of the matrix was interchanged with row `ipiv[i]`. + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n`-by-`nrhs` right hand side matrix `B`. + * On exit, if `info=0`, the `n`-by-`nrhs` solution matrix X. + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and the solution has not been computed. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and the solution has not been computed. + * + * @par Further Details: + * @rst + * The band storage scheme is illustrated by the following example, when + * m = n = 6, kl = 2, ku = 1: + * + * .. code-block:: text + * + * On entry: On exit: + * + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * + * + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void zgbsv( const INT n, diff --git a/src/z/zgbsvx.c b/src/z/zgbsvx.c index 58292561..e52f3dba 100644 --- a/src/z/zgbsvx.c +++ b/src/z/zgbsvx.c @@ -13,57 +13,117 @@ /** * ZGBSVX uses the LU factorization to compute the solution to a complex - * system of linear equations A * X = B, A**T * X = B, or A**H * X = B, - * where A is a band matrix of order N with KL subdiagonals and KU - * superdiagonals, and X and B are N-by-NRHS matrices. + * system of linear equations + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst + * where A is a band matrix of order `n` with `kl` subdiagonals and `ku` + * superdiagonals, and X and `B` are `n`-by-`nrhs` matrices. * * Error bounds on the solution and a condition estimate are also provided. * - * @param[in] fact 'F': AFB and IPIV contain the factored form of A. - * 'N': The matrix A will be copied to AFB and factored. - * 'E': The matrix A will be equilibrated if necessary, - * then copied to AFB and factored. - * @param[in] trans 'N': A * X = B (No transpose) - * 'T': A**T * X = B (Transpose) - * 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The number of linear equations (order of A). n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in,out] AB On entry, the matrix A in band storage, in rows 0 to kl+ku. - * On exit, if equilibration was done, A is scaled. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of AB. ldab >= kl+ku+1. - * @param[in,out] AFB On entry (if fact='F'), contains the LU factors. + * @rst + * The following steps are performed by this subroutine: + * + * 1. If ``fact='E'``, real scaling factors are computed to equilibrate + * the system:: + * + * trans = 'N': diag(R)*A*diag(C) *inv(diag(C))*X = diag(R)*B + * trans = 'T': (diag(R)*A*diag(C))**T *inv(diag(R))*X = diag(C)*B + * trans = 'C': (diag(R)*A*diag(C))**H *inv(diag(R))*X = diag(C)*B + * + * Whether or not the system will be equilibrated depends on the + * scaling of the matrix A, but if equilibration is used, A is + * overwritten by diag(R)*A*diag(C) and B by diag(R)*B (if ``trans='N'``) + * or diag(C)*B (if ``trans='T'`` or ``'C'``). + * + * 2. If ``fact='N'`` or ``'E'``, the LU decomposition is used to factor + * the matrix A (after equilibration if ``fact='E'``) as:: + * + * A = L * U + * + * where L is a product of permutation and unit lower triangular + * matrices with kl subdiagonals, and U is upper triangular with + * kl+ku superdiagonals. + * + * 3. 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. + * + * 4. The system of equations is solved for X using the factored form of A. + * + * 5. Iterative refinement is applied to improve the computed solution + * matrix and calculate error bounds and backward error estimates for it. + * + * 6. If equilibration was used, the matrix X is premultiplied by + * ``diag(C)`` (if ``trans='N'``) or ``diag(R)`` (if ``trans='T'`` or + * ``'C'``) so that it solves the original system before equilibration. + * @endrst + * + * @param[in] fact + * - `'F'`: `AFB` and `ipiv` contain the factored form of A. + * - `'N'`: The matrix A will be copied to `AFB` and factored. + * - `'E'`: The matrix A will be equilibrated if necessary, + * then copied to `AFB` and factored. + * @param[in] trans + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The number of linear equations (order of A). `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows 0 to + * `kl+ku`. The j-th column of A is stored in the j-th column + * of the array `AB` as follows: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(n-1,j+kl)`. + * On exit, if `equed != 'N'`, A is scaled. + * @param[in] ldab The leading dimension of `AB`. `ldab>=kl+ku+1`. + * @param[in,out] AFB Array of dimension (`ldafb`, `n`). + * On entry (if `fact='F'`), contains the LU factors. * On exit, contains the factors L and U. - * Array of dimension (ldafb, n). - * @param[in] ldafb The leading dimension of AFB. ldafb >= 2*kl+ku+1. - * @param[in,out] ipiv Pivot indices from factorization. Array of dimension (n). - * @param[in,out] equed On entry (if fact='F'), specifies equilibration done. + * @param[in] ldafb The leading dimension of `AFB`. `ldafb>=2*kl+ku+1`. + * @param[in,out] ipiv Array of dimension (`n`). + * Pivot indices from factorization. + * @param[in,out] equed On entry (if `fact='F'`), specifies equilibration done. * On exit, specifies the form of equilibration: - * 'N': No equilibration - * 'R': Row equilibration (A := diag(R) * A) - * 'C': Column equilibration (A := A * diag(C)) - * 'B': Both (A := diag(R) * A * diag(C)) - * @param[in,out] R Row scale factors. Array of dimension (n). - * @param[in,out] C Column scale factors. Array of dimension (n). - * @param[in,out] B On entry, the N-by-NRHS right hand side matrix B. - * On exit, if equilibration was done, B is scaled. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[out] X The N-by-NRHS solution matrix X. Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). + * - `'N'`: No equilibration + * - `'R'`: Row equilibration (A := diag(R) * A) + * - `'C'`: Column equilibration (A := A * diag(C)) + * - `'B'`: Both (A := diag(R) * A * diag(C)) + * @param[in,out] R Array of dimension (`n`). + * Row scale factors. + * @param[in,out] C Array of dimension (`n`). + * Column scale factors. + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n`-by-`nrhs` right hand side matrix `B`. + * On exit, if equilibration was done, `B` is scaled. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[out] X Array of dimension (`ldx`, `nrhs`). + * The `n`-by-`nrhs` solution matrix X. + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. * @param[out] rcond Reciprocal condition number estimate. - * @param[out] ferr Forward error bound for each solution vector. Array of dimension (nrhs). - * @param[out] berr Backward error for each solution vector. Array of dimension (nrhs). - * @param[out] work Complex workspace array of dimension (2*n). - * @param[out] rwork Real workspace array of dimension (max(1, n)). - * On exit, rwork[0] contains the reciprocal pivot growth factor. + * @param[out] ferr Array of dimension (`nrhs`). + * Forward error bound for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * Backward error for each solution vector. + * @param[out] work Complex workspace array of dimension (`2*n`). + * @param[out] rwork Real workspace array of dimension (`max(1,n)`). + * On exit, `rwork[0]` contains the reciprocal pivot growth + * factor. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i,i) is exactly zero (1-based). - * if info = n+1, U is nonsingular but RCOND < machine precision. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero (1-based). + * If `info=n+1`, U is nonsingular but `rcond` < machine + * precision. */ void zgbsvx( const char* fact, diff --git a/src/z/zgbtf2.c b/src/z/zgbtf2.c index 636a6167..8db8cf41 100644 --- a/src/z/zgbtf2.c +++ b/src/z/zgbtf2.c @@ -19,55 +19,54 @@ * trapezoidal if m > n), and U is upper triangular (upper trapezoidal * if m < n). * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB Double complex array, dimension (ldab, n). - * On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[out] ipiv Integer array, dimension (min(m,n)). - * The pivot indices; for 0 <= i < min(m,n), row i of the - * matrix was interchanged with row ipiv[i]. 0-based indexing. + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `min(m,n)`. + * The pivot indices; for `0<=i 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and division by zero will occur if it is used - * to solve a system of equations. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and division by zero will occur if it + * is used to solve a system of equations. + * * @par Further Details: + * @rst * The band storage scheme is illustrated by the following example, when * m = n = 6, kl = 2, ku = 1: * - * On entry (0-based indexing, rows 0 to 5, kl=2, ku=1, kv=kl+ku=3): + * .. code-block:: text * - * Row 0: * * * (fill-in storage) - * Row 1: * * a02 a13 a24 a35 (U superdiagonals) - * Row 2: * a01 a12 a23 a34 a45 (U superdiagonals) - * Row 3: a00 a11 a22 a33 a44 a55 (diagonal) - * Row 4: a10 a21 a32 a43 a54 * (L multipliers after factorization) - * Row 5: a20 a31 a42 a53 * * (L multipliers after factorization) + * On entry: On exit: * - * On exit: - * Row 0: * * * u03 u14 u25 (U fill-in from pivoting) - * Row 1: * * u02 u13 u24 u35 (U superdiagonals) - * Row 2: * u01 u12 u23 u34 u45 (U superdiagonals) - * Row 3: u00 u11 u22 u33 u44 u55 (U diagonal) - * Row 4: m10 m21 m32 m43 m54 * (L multipliers) - * Row 5: m20 m31 m42 m53 * * (L multipliers) + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * * - * Array elements marked * are not used by the routine. + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void zgbtf2( const INT m, diff --git a/src/z/zgbtrf.c b/src/z/zgbtrf.c index 30f8f093..883a5a32 100644 --- a/src/z/zgbtrf.c +++ b/src/z/zgbtrf.c @@ -24,33 +24,54 @@ * trapezoidal if m > n), and U is upper triangular (upper trapezoidal * if m < n). * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB Double complex array, dimension (ldab, n). - * On entry, the matrix A in band storage, in rows kl to - * 2*kl+ku; rows 0 to kl-1 of the array need not be set. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows `kl` to + * `2*kl+ku`; rows 0 to `kl-1` of the array need not be set. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[kl+ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). - * + * the array `AB` as follows: + * `AB[kl+ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, details of the factorization: U is stored as an - * upper triangular band matrix with kl+ku superdiagonals in - * rows 0 to kl+ku, and the multipliers used during the - * factorization are stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[out] ipiv Integer array, dimension (min(m,n)). - * The pivot indices; for 0 <= i < min(m,n), row i of the - * matrix was interchanged with row ipiv[i]. 0-based indexing. + * upper triangular band matrix with `kl+ku` superdiagonals in + * rows 0 to `kl+ku`, and the multipliers used during the + * factorization are stored in rows `kl+ku+1` to `2*kl+ku`. + * See below for further details. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[out] ipiv Array of dimension `min(m,n)`. + * The pivot indices; for `0<=i 0: if info = i, U(i-1,i-1) is exactly zero. The factorization - * has been completed, but the factor U is exactly - * singular, and division by zero will occur if it is used - * to solve a system of equations. + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero. The + * factorization has been completed, but the factor U is + * exactly singular, and division by zero will occur if it + * is used to solve a system of equations. + * + * @par Further Details: + * @rst + * The band storage scheme is illustrated by the following example, when + * m = n = 6, kl = 2, ku = 1: + * + * .. code-block:: text + * + * On entry: On exit: + * + * * * * + + + * * * u03 u14 u25 + * * * + + + + * * u02 u13 u24 u35 + * * a01 a12 a23 a34 a45 * u01 u12 u23 u34 u45 + * a00 a11 a22 a33 a44 a55 u00 u11 u22 u33 u44 u55 + * a10 a21 a32 a43 a54 * m10 m21 m32 m43 m54 * + * a20 a31 a42 a53 * * m20 m31 m42 m53 * * + * + * Array elements marked * are not used by the routine; elements marked + * + need not be set on entry, but are required by the routine to store + * elements of U because of fill-in resulting from the row interchanges. + * @endrst */ void zgbtrf( const INT m, diff --git a/src/z/zgbtrs.c b/src/z/zgbtrs.c index f459d390..2b5d09aa 100644 --- a/src/z/zgbtrs.c +++ b/src/z/zgbtrs.c @@ -10,37 +10,41 @@ /** * ZGBTRS solves a system of linear equations - * A * X = B, A**T * X = B, or A**H * X = B + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst * with a general band matrix A using the LU factorization computed * by ZGBTRF. * * @param[in] trans Specifies the form of the system of equations: - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of - * columns of the matrix B. nrhs >= 0. - * @param[in] AB Complex*16 array, dimension (ldab, n). + * columns of the matrix `B`. `nrhs>=0`. + * @param[in] AB Array of dimension (`ldab`, `n`). * Details of the LU factorization of the band matrix A, * as computed by ZGBTRF. U is stored as an upper triangular - * band matrix with kl+ku superdiagonals in rows 0 to kl+ku, + * band matrix with `kl+ku` superdiagonals in rows 0 to `kl+ku`, * and the multipliers used during the factorization are - * stored in rows kl+ku+1 to 2*kl+ku. - * @param[in] ldab The leading dimension of the array AB. ldab >= 2*kl+ku+1. - * @param[in] ipiv Integer array, dimension (n). - * The pivot indices; for 0 <= i < n, row i of the matrix - * was interchanged with row ipiv[i]. 0-based indexing. - * @param[in,out] B Complex*16 array, dimension (ldb, nrhs). - * On entry, the right hand side matrix B. + * stored in rows `kl+ku+1` to `2*kl+ku`. + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=2*kl+ku+1`. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i= max(1,n). + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * Exit status: - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void zgbtrs( const char* trans, diff --git a/src/z/zgtcon.c b/src/z/zgtcon.c index b795d67f..7610b551 100644 --- a/src/z/zgtcon.c +++ b/src/z/zgtcon.c @@ -12,33 +12,41 @@ * ZGTTRF. * * An estimate is obtained for norm(inv(A)), and the reciprocal of the - * condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))). + * condition number is computed as + * @rst + * .. code-block:: text + * + * rcond = 1 / (anorm * norm(inv(A))) + * @endrst * * @param[in] norm Specifies whether the 1-norm condition number or the * infinity-norm condition number is required: - * = '1' or 'O': 1-norm - * = 'I': Infinity-norm - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the + * - `'1'` or `'O'`: 1-norm + * - `'I'`: Infinity-norm + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the * LU factorization of A as computed by ZGTTRF. - * Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U - * from the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first superdiagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second superdiagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. Array of dimension (n). - * @param[in] anorm If norm = '1' or "O", the 1-norm of the original matrix A. - * If norm = "I", the infinity-norm of the original matrix A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U + * from the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first superdiagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second superdiagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in] DL The (n-1) subdiagonal elements of A. Array of dimension (n-1). - * @param[in] D The diagonal elements of A. Array of dimension (n). - * @param[in] DU The (n-1) superdiagonal elements of A. Array of dimension (n-1). - * @param[in] DLF The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] DF The n diagonal elements of U. Array of dimension (n). - * @param[in] DUF The (n-1) elements of the first superdiagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second superdiagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices. Array of dimension (n). - * @param[in] B The right hand side matrix B. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[in,out] X On entry, the solution matrix X, as computed by ZGTTRS. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) subdiagonal elements of A. + * @param[in] D Array of dimension (`n`). + * The diagonal elements of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) superdiagonal elements of A. + * @param[in] DLF Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] DF Array of dimension (`n`). + * The n diagonal elements of U. + * @param[in] DUF Array of dimension (`n-1`). + * The (n-1) elements of the first superdiagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second superdiagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The right hand side matrix `B`. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[in,out] X Array of dimension (`ldx`, `nrhs`). + * On entry, the solution matrix X, as computed by ZGTTRS. * On exit, the improved solution matrix X. - * Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). - * @param[out] ferr The estimated forward error bound for each solution vector. - * Array of dimension (nrhs). - * @param[out] berr The componentwise relative backward error of each solution. - * Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (2*n). - * @param[out] rwork Real workspace array of dimension (n). + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. + * @param[out] ferr Array of dimension (`nrhs`). + * The estimated forward error bound for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * The componentwise relative backward error of each solution. + * @param[out] work Complex workspace array of dimension (`2*n`). + * @param[out] rwork Real workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void zgtrfs( const char* trans, diff --git a/src/z/zgtsv.c b/src/z/zgtsv.c index 806a29dc..4e77ed48 100644 --- a/src/z/zgtsv.c +++ b/src/z/zgtsv.c @@ -10,38 +10,41 @@ /** * ZGTSV solves the equation + * @rst + * .. code-block:: text * - * A*X = B, - * - * where A is an n by n tridiagonal matrix, by Gaussian elimination with + * A * X = B + * @endrst + * where A is an `n` by `n` tridiagonal matrix, by Gaussian elimination with * partial pivoting. * * Note that the equation A**T*X = B may be solved by interchanging the - * order of the arguments DU and DL. + * order of the arguments `DU` and `DL`. * - * @param[in] n The order of the matrix A. n >= 0. + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in,out] DL On entry, the (n-1) sub-diagonal elements of A. - * On exit, DL is overwritten by the (n-2) elements of the + * of the matrix `B`. `nrhs>=0`. + * @param[in,out] DL Array of dimension (`n-1`). + * On entry, the (n-1) sub-diagonal elements of A. + * On exit, `DL` is overwritten by the (n-2) elements of the * second super-diagonal of the upper triangular matrix U from - * the LU factorization of A, in DL[0], ..., DL[n-3]. - * Array of dimension (n-1). - * @param[in,out] D On entry, the diagonal elements of A. - * On exit, D is overwritten by the n diagonal elements of U. - * Array of dimension (n). - * @param[in,out] DU On entry, the (n-1) super-diagonal elements of A. - * On exit, DU is overwritten by the (n-1) elements of the first + * the LU factorization of A, in `DL[0]`, ..., `DL[n-3]`. + * @param[in,out] D Array of dimension (`n`). + * On entry, the diagonal elements of A. + * On exit, `D` is overwritten by the n diagonal elements of U. + * @param[in,out] DU Array of dimension (`n-1`). + * On entry, the (n-1) super-diagonal elements of A. + * On exit, `DU` is overwritten by the (n-1) elements of the first * super-diagonal of U. - * Array of dimension (n-1). - * @param[in,out] B On entry, the N by NRHS matrix of right hand side matrix B. - * On exit, if info = 0, the N by NRHS solution matrix X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * @param[in,out] B Array of dimension (`ldb`, `nrhs`). + * On entry, the `n` by `nrhs` matrix of right hand side matrix `B`. + * On exit, if `info=0`, the `n` by `nrhs` solution matrix X. + * @param[in] ldb The leading dimension of the array `B`. `ldb>=max(1,n)`. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i, U(i-1,i-1) is exactly zero (0-based), and the + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i`, U(i,i) is exactly zero, and the * solution has not been computed. The factorization has not * been completed unless i = n. */ diff --git a/src/z/zgtsvx.c b/src/z/zgtsvx.c index 941b83cb..03912f0e 100644 --- a/src/z/zgtsvx.c +++ b/src/z/zgtsvx.c @@ -11,48 +11,89 @@ /** * ZGTSVX uses the LU factorization to compute the solution to a 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 and X and B are N-by-NRHS + * system of linear equations + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst + * where A is a tridiagonal matrix of order `n` and X and `B` are `n`-by-`nrhs` * matrices. * * Error bounds on the solution and a condition estimate are also provided. * - * @param[in] fact Specifies whether the factored form of A has been supplied. - * = 'F': DLF, DF, DUF, DU2, and IPIV contain the factored form. - * = 'N': The matrix will be copied and factored. + * @rst + * The following steps are performed: + * + * 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 upper triangular with nonzeros in + * only the main diagonal and first two superdiagonals. + * + * 2. 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. + * + * 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. + * @endrst + * + * @param[in] fact + * - `'F'`: `DLF`, `DF`, `DUF`, `DU2`, and `ipiv` contain the + * factored form of A. + * - `'N'`: The matrix will be copied and factored. * @param[in] trans Specifies the form of the system of equations: - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A. n >= 0. - * @param[in] nrhs The number of right hand sides. nrhs >= 0. - * @param[in] DL The (n-1) subdiagonal elements of A. Array of dimension (n-1). - * @param[in] D The diagonal elements of A. Array of dimension (n). - * @param[in] DU The (n-1) superdiagonal elements of A. Array of dimension (n-1). - * @param[in,out] DLF If fact = "F", the (n-1) multipliers from LU factorization. - * If fact = "N", output. Array of dimension (n-1). - * @param[in,out] DF If fact = "F", the n diagonal elements of U. - * If fact = "N", output. Array of dimension (n). - * @param[in,out] DUF If fact = "F", the (n-1) elements of first superdiagonal of U. - * If fact = "N", output. Array of dimension (n-1). - * @param[in,out] DU2 If fact = "F", the (n-2) elements of second superdiagonal of U. - * If fact = "N", output. Array of dimension (n-2). - * @param[in,out] ipiv If fact = "F", the pivot indices from factorization. - * If fact = "N", output. Array of dimension (n). - * @param[in] B The N-by-NRHS right hand side matrix. Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of B. ldb >= max(1, n). - * @param[out] X The N-by-NRHS solution matrix. Array of dimension (ldx, nrhs). - * @param[in] ldx The leading dimension of X. ldx >= max(1, n). + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in] nrhs The number of right hand sides. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) subdiagonal elements of A. + * @param[in] D Array of dimension (`n`). + * The diagonal elements of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) superdiagonal elements of A. + * @param[in,out] DLF Array of dimension (`n-1`). + * If `fact='F'`, the (n-1) multipliers from LU factorization. + * If `fact='N'`, output. + * @param[in,out] DF Array of dimension (`n`). + * If `fact='F'`, the n diagonal elements of U. + * If `fact='N'`, output. + * @param[in,out] DUF Array of dimension (`n-1`). + * If `fact='F'`, the (n-1) elements of first superdiagonal of U. + * If `fact='N'`, output. + * @param[in,out] DU2 Array of dimension (`n-2`). + * If `fact='F'`, the (n-2) elements of second superdiagonal of U. + * If `fact='N'`, output. + * @param[in,out] ipiv Array of dimension (`n`). + * If `fact='F'`, the pivot indices from factorization. + * If `fact='N'`, output. + * @param[in] B Array of dimension (`ldb`, `nrhs`). + * The `n`-by-`nrhs` right hand side matrix. + * @param[in] ldb The leading dimension of `B`. `ldb>=max(1,n)`. + * @param[out] X Array of dimension (`ldx`, `nrhs`). + * The `n`-by-`nrhs` solution matrix. + * @param[in] ldx The leading dimension of `X`. `ldx>=max(1,n)`. * @param[out] rcond The reciprocal condition number estimate. - * @param[out] ferr Forward error bounds for each solution vector. Array of dimension (nrhs). - * @param[out] berr Backward error for each solution vector. Array of dimension (nrhs). - * @param[out] work Workspace array of dimension (2*n). - * @param[out] rwork Real workspace array of dimension (n). + * @param[out] ferr Array of dimension (`nrhs`). + * Forward error bounds for each solution vector. + * @param[out] berr Array of dimension (`nrhs`). + * Backward error for each solution vector. + * @param[out] work Complex workspace array of dimension (`2*n`). + * @param[out] rwork Real workspace array of dimension (`n`). * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value - * - > 0: if info = i (i <= n), U(i,i) is exactly zero - * - = n+1: U is nonsingular, but rcond < machine precision + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value + * - `info>0`: if `info=i` (i <= `n`), U(i,i) is exactly zero + * - `info=n+1`: U is nonsingular, but `rcond` < machine + * precision */ void zgtsvx( const char* fact, diff --git a/src/z/zgttrf.c b/src/z/zgttrf.c index c7f43f2e..71feb04f 100644 --- a/src/z/zgttrf.c +++ b/src/z/zgttrf.c @@ -12,34 +12,39 @@ * using elimination with partial pivoting and row interchanges. * * The factorization has the form - * A = L * U + * @rst + * .. code-block:: text + * + * A = L * U + * @endrst * where L is a product of permutation and unit lower bidiagonal * matrices and U is upper triangular with nonzeros in only the main * diagonal and first two superdiagonals. * - * @param[in] n The order of the matrix A. n >= 0. - * @param[in,out] DL On entry, the (n-1) sub-diagonal elements of A. + * @param[in] n The order of the matrix A. `n>=0`. + * @param[in,out] DL Array of dimension (`n-1`). + * On entry, the (n-1) sub-diagonal elements of A. * On exit, the (n-1) multipliers that define the matrix L * from the LU factorization of A. - * Array of dimension (n-1). - * @param[in,out] D On entry, the diagonal elements of A. + * @param[in,out] D Array of dimension (`n`). + * On entry, the diagonal elements of A. * On exit, the n diagonal elements of the upper triangular * matrix U from the LU factorization of A. - * Array of dimension (n). - * @param[in,out] DU On entry, the (n-1) super-diagonal elements of A. + * @param[in,out] DU Array of dimension (`n-1`). + * On entry, the (n-1) super-diagonal elements of A. * On exit, the (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[out] DU2 On exit, the (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[out] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not + * @param[out] DU2 Array of dimension (`n-2`). + * On exit, the (n-2) elements of the second super-diagonal of U. + * @param[out] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i 0: if info = k, U(k-1,k-1) is exactly zero (0-based). + * - `info=0`: successful exit + * - `info<0`: if `info=-k`, the k-th argument had an illegal + * value + * - `info>0`: if `info=k`, U(k,k) is exactly zero. * The factorization has been completed, but the factor U * is exactly singular, and division by zero will occur * if it is used to solve a system of equations. diff --git a/src/z/zgttrs.c b/src/z/zgttrs.c index af04b094..5af0b422 100644 --- a/src/z/zgttrs.c +++ b/src/z/zgttrs.c @@ -8,36 +8,44 @@ /** * ZGTTRS solves one of the systems of equations - * A*X = B, A**T*X = B, or A**H*X = B, + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst * with a tridiagonal matrix A using the LU factorization computed * by ZGTTRF. * * @param[in] trans Specifies the form of the system of equations. - * = 'N': A * X = B (No transpose) - * = 'T': A**T * X = B (Transpose) - * = 'C': A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A. n >= 0. + * - `'N'`: A * X = B (No transpose) + * - `'T'`: A**T * X = B (Transpose) + * - `'C'`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U from - * the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not - * required. Array of dimension (n). - * @param[in,out] B On entry, the matrix of right hand side vectors B. - * On exit, B is overwritten by the solution vectors X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * of the matrix `B`. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U from + * the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first super-diagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second super-diagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i=max(1,n)`. * @param[out] info - * - = 0: successful exit - * - < 0: if info = -i, the i-th argument had an illegal value + * - `info=0`: successful exit + * - `info<0`: if `info=-i`, the i-th argument had an illegal + * value */ void zgttrs( const char* trans, diff --git a/src/z/zgtts2.c b/src/z/zgtts2.c index c52f1497..1cd8d70e 100644 --- a/src/z/zgtts2.c +++ b/src/z/zgtts2.c @@ -9,33 +9,40 @@ /** * ZGTTS2 solves one of the systems of equations - * A * X = B, A**T * X = B, or A**H * X = B, + * @rst + * .. code-block:: text + * + * A * X = B, A**T * X = B, or A**H * X = B + * @endrst * with a tridiagonal matrix A using the LU factorization computed * by ZGTTRF. * * @param[in] itrans Specifies the form of the system of equations. - * = 0: A * X = B (No transpose) - * = 1: A**T * X = B (Transpose) - * = 2: A**H * X = B (Conjugate transpose) - * @param[in] n The order of the matrix A. n >= 0. + * - `0`: A * X = B (No transpose) + * - `1`: A**T * X = B (Transpose) + * - `2`: A**H * X = B (Conjugate transpose) + * @param[in] n The order of the matrix A. `n>=0`. * @param[in] nrhs The number of right hand sides, i.e., the number of columns - * of the matrix B. nrhs >= 0. - * @param[in] DL The (n-1) multipliers that define the matrix L from the - * LU factorization of A. Array of dimension (n-1). - * @param[in] D The n diagonal elements of the upper triangular matrix U from - * the LU factorization of A. Array of dimension (n). - * @param[in] DU The (n-1) elements of the first super-diagonal of U. - * Array of dimension (n-1). - * @param[in] DU2 The (n-2) elements of the second super-diagonal of U. - * Array of dimension (n-2). - * @param[in] ipiv The pivot indices; for 0 <= i < n, row i of the matrix was - * interchanged with row ipiv[i]. ipiv[i] will always be either - * i or i+1; ipiv[i] = i indicates a row interchange was not - * required. Array of dimension (n). - * @param[in,out] B On entry, the matrix of right hand side vectors B. - * On exit, B is overwritten by the solution vectors X. - * Array of dimension (ldb, nrhs). - * @param[in] ldb The leading dimension of the array B. ldb >= max(1, n). + * of the matrix `B`. `nrhs>=0`. + * @param[in] DL Array of dimension (`n-1`). + * The (n-1) multipliers that define the matrix L from the + * LU factorization of A. + * @param[in] D Array of dimension (`n`). + * The n diagonal elements of the upper triangular matrix U from + * the LU factorization of A. + * @param[in] DU Array of dimension (`n-1`). + * The (n-1) elements of the first super-diagonal of U. + * @param[in] DU2 Array of dimension (`n-2`). + * The (n-2) elements of the second super-diagonal of U. + * @param[in] ipiv Array of dimension (`n`). + * The pivot indices; for `0<=i=max(1,n)`. */ void zgtts2( const INT itrans, diff --git a/src/z/zlaqgb.c b/src/z/zlaqgb.c index 24de3c68..087b6419 100644 --- a/src/z/zlaqgb.c +++ b/src/z/zlaqgb.c @@ -9,34 +9,36 @@ #include "semicolon_lapack_complex_double.h" /** - * ZLAQGB equilibrates a general M by N band matrix A with KL subdiagonals - * and KU superdiagonals using the row and column scaling factors in the - * vectors R and C. + * ZLAQGB equilibrates a general `m` by `n` band matrix A with `kl` subdiagonals + * and `ku` superdiagonals using the row and column scaling factors in the + * vectors `R` and `C`. * - * @param[in] m The number of rows of the matrix A. m >= 0. - * @param[in] n The number of columns of the matrix A. n >= 0. - * @param[in] kl The number of subdiagonals within the band of A. kl >= 0. - * @param[in] ku The number of superdiagonals within the band of A. ku >= 0. - * @param[in,out] AB On entry, the matrix A in band storage, in rows 0 to kl+ku. + * @param[in] m The number of rows of the matrix A. `m>=0`. + * @param[in] n The number of columns of the matrix A. `n>=0`. + * @param[in] kl The number of subdiagonals within the band of A. `kl>=0`. + * @param[in] ku The number of superdiagonals within the band of A. `ku>=0`. + * @param[in,out] AB Array of dimension (`ldab`, `n`). + * On entry, the matrix A in band storage, in rows 0 to `kl+ku`. * The j-th column of A is stored in the j-th column of - * the array AB as follows: - * AB[ku+i-j + j*ldab] = A(i,j) for max(0,j-ku) <= i <= min(m-1,j+kl). + * the array `AB` as follows: + * `AB[ku+i-j + j*ldab] = A(i,j)` for `max(0,j-ku)<=i<=min(m-1,j+kl)`. * On exit, the equilibrated matrix in the same storage format. - * Array of dimension (ldab, n). - * @param[in] ldab The leading dimension of the array AB. ldab >= kl+ku+1. - * @param[in] R The row scale factors for A. Array of dimension (m). - * @param[in] C The column scale factors for A. Array of dimension (n). + * @param[in] ldab The leading dimension of the array `AB`. `ldab>=kl+ku+1`. + * @param[in] R Array of dimension (`m`). + * The row scale factors for A. + * @param[in] C Array of dimension (`n`). + * The column scale factors for A. * @param[in] rowcnd Ratio of the smallest R(i) to the largest R(i). * @param[in] colcnd Ratio of the smallest C(i) to the largest C(i). * @param[in] amax Absolute value of largest matrix entry. * @param[out] equed Specifies the form of equilibration that was done: - * = 'N': No equilibration - * = 'R': Row equilibration, i.e., A has been premultiplied - * by diag(R). - * = 'C': Column equilibration, i.e., A has been postmultiplied - * by diag(C). - * = 'B': Both row and column equilibration, i.e., A has been - * replaced by diag(R) * A * diag(C). + * - `'N'`: No equilibration + * - `'R'`: Row equilibration, i.e., A has been premultiplied + * by diag(R). + * - `'C'`: Column equilibration, i.e., A has been postmultiplied + * by diag(C). + * - `'B'`: Both row and column equilibration, i.e., A has been + * replaced by diag(R) * A * diag(C). */ void zlaqgb( const INT m,