Skip to content

DOC: Documentation update overhaul Part 2/n #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ilayn merged 17 commits into from
Jul 31, 2026
Merged

DOC: Documentation update overhaul Part 2/n #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
63b83ed
DOC: Overhaul gbcon family
ilayn Jul 31, 2026
0fb573d
DOC: Overhaul gbequ family
ilayn Jul 31, 2026
77ad71f
DOC: Overhaul gbequb family
ilayn Jul 31, 2026
752b83c
DOC: Overhaul gbrfs family
ilayn Jul 31, 2026
49f544f
DOC: Overhaul gbsv family
ilayn Jul 31, 2026
17ba300
DOC: Overhaul gbsvx family
ilayn Jul 31, 2026
210dcad
DOC: Overhaul gbtf2 family
ilayn Jul 31, 2026
73bfaff
DOC: Overhaul gbtrf family
ilayn Jul 31, 2026
4939522
DOC: Overhaul gbtrs family
ilayn Jul 31, 2026
b072c45
DOC: Overhaul gtcon family
ilayn Jul 31, 2026
50febe5
DOC: Overhaul gtrfs family
ilayn Jul 31, 2026
5af4732
DOC: Overhaul gtsv family
ilayn Jul 31, 2026
79a63b2
DOC: Overhaul gtsvx family
ilayn Jul 31, 2026
f6712a2
DOC: Overhaul gttrf family
ilayn Jul 31, 2026
101e0f0
DOC: Overhaul gttrs family
ilayn Jul 31, 2026
5bddd41
DOC: Overhaul gtts2 family
ilayn Jul 31, 2026
64bbd45
DOC: Overhaul laqgb family
ilayn Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 27 additions & 21 deletions src/c/cgbcon.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<n`, row i of the matrix
* was interchanged with row `ipiv[i]`.
* @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[out] rcond The reciprocal of the condition number of the matrix A,
* computed as RCOND = 1/(norm(A) * norm(inv(A))).
* @param[out] work Complex workspace array of dimension (2*n).
* @param[out] rwork Real workspace array of dimension (n).
* computed as `rcond = 1/(norm(A) * norm(inv(A)))`.
* @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 cgbcon(
const char* norm,
Expand Down
64 changes: 33 additions & 31 deletions src/c/cgbequ.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,46 +10,48 @@

/**
* CGBEQU 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
* `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 absolute value 1.
* elements `B(i,j)=R(i)*A(i,j)*C(j)` have absolute value 1.
*
* R(i) and C(j) are restricted to be between SMLNUM = smallest safe
* `R(i)` and `C(j)` are restricted to be 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.
*
* @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 cgbequ(
const INT m,
Expand Down
66 changes: 34 additions & 32 deletions src/c/cgbequb.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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,
Expand Down
68 changes: 36 additions & 32 deletions src/c/cgbrfs.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading
Loading