Cholesky and LU factorizations, their solves and inverses.
Lower-level functions (algorithm-specific variants, workspace queries, validation and helpers): Factorizations: lower-level API.
Batched solve of \( A X = B \) by LU with partial pivoting.
Semantically getrf() followed by getrs() with Transpose::NoTrans: on return A holds L and U as getrf() leaves them, pivots the same packed 1-based interchange list getrf() writes (so the factors can be reused with getrs() or getri()), B holds X and info carries getrf's per-item status. No vendor library call sits behind this op; it is served by a native fused tier or by the routed getrf + getrs composition.
Asynchronous: A, B, pivots and info are readable after the returned event is waited on.
- Template Parameters
-
| Back | backend; the backend-deducing overload takes it from ctx.backend() |
| T | scalar type (float, double, std::complex<float>, std::complex<double>) |
- Parameters
-
| ctx | queue the kernels are enqueued on |
| A | batch of n x n matrices; overwritten with L and U |
| B | batch of n x nrhs right-hand sides; overwritten with X |
| pivots | pivot output, n * batch entries in getrf()'s format |
| work_space | device-accessible scratch of at least gesv_buffer_size() bytes |
| info | per-item status as for getrf(): 0 on success, i > 0 if U(i,i) is exactly zero (that item's X is meaningless). Empty span = not requested. |
- Returns
- event of the last enqueued kernel
- Exceptions
-
Batched LU factorization with partial pivoting.
For every batch item computes \( A = P L U \) with L unit lower triangular and U upper triangular, and overwrites A with L (below the diagonal, unit diagonal implied) and U (on and above it), as LAPACK ?getrf.
Pivot format. pivots is typed int64_t, but on the GPU backends and every native kernel it holds packed 1-based int32 indices: item b's row interchange i (row i was swapped with row ipiv[i]) is the int32 at index b * n + i of the span's bytes reinterpreted as int32_t. The NETLIB backend writes genuine 1-based int64 instead. Pass the span unchanged to getrs() / getri() on the same backend; do not read or compare the entries across backends. Complex pivots are chosen on |Re| + |Im| natively and on the modulus by cuBLAS, so pivot sequences can differ between kernels while both factorizations are valid.
Asynchronous: A, pivots and info are readable after the returned event is waited on.
- Template Parameters
-
| B | backend; the backend-deducing overload takes it from ctx.backend() |
| T | scalar type (float, double, std::complex<float>, std::complex<double>) |
- Parameters
-
| ctx | queue the kernels are enqueued on |
| A | batch of n x n matrices; overwritten with L and U. An m x n batch is factored whole by the NETLIB and ROCm vendors (min(m, n) pivots per item, packed); CUDA has no route for it |
| pivots | pivot output, at least n * batch int64_t elements |
| work_space | device-accessible scratch of at least getrf_buffer_size() bytes |
| info | per-item LAPACK status, one int32 per batch item: 0 on success, i > 0 if U(i,i) is exactly zero (1-based; the factorization completed but U is singular). Empty span = not requested. |
- Returns
- event of the last enqueued kernel
- Precondition
- A.rows() == A.cols() (checked by the option overloads only)
-
pivots.size() >= A.rows() * A.batch_size() (checked by the option overloads only)
-
a non-empty
info holds at least A.batch_size() elements; a shorter one is silently ignored by this overload
- Exceptions
-
- Note
- The workspace size does not depend on whether
info is requested.
Batched solve of \( \mathrm{op}(A) X = B \) using the LU factors from getrf().
A and pivots must be exactly what getrf() produced on the same backend (see getrf() for the packed 1-based int32 pivot format). \( \mathrm{op}(A) \) is A, \( A^T \) or \( A^H \) for NoTrans, Trans, ConjTrans. B is overwritten with X. No singularity check is made: a zero U(i,i) (reported by getrf's info) produces infinities or NaNs in that item.
Asynchronous: B is readable after the returned event is waited on.
- Template Parameters
-
| Back | backend; the backend-deducing overload takes it from ctx.backend() |
| T | scalar type (float, double, std::complex<float>, std::complex<double>) |
- Parameters
-
| ctx | queue the kernels are enqueued on |
| A | batch of n x n LU factors from getrf(); not modified |
| B | batch of n x nrhs right-hand sides; overwritten with X |
| transA | which of A, A^T, A^H to solve with |
| pivots | pivots from getrf(), n * batch entries |
| work_space | device-accessible scratch of at least getrs_buffer_size() bytes |
- Returns
- event of the last enqueued kernel
- Precondition
- A.rows() == A.cols() == B.rows(), equal batch sizes, and pivots.size() >= n * batch (checked by the option overloads only)
- Exceptions
-
- See also
- GetrsOptions
Batched solve of \( A X = B \) for Hermitian positive-definite A.
Semantically potrf(A, uplo) followed by the two triangular solves with the factor: on return A holds the Cholesky factor in the uplo triangle (the other triangle is not read, and, as for potrf(), a vendor potrf leg may overwrite it), B holds X, and info carries potrf's status. There is no vendor library call behind this op on any backend; it is served by native fused tiers or by the routed potrf + trsm composition.
Asynchronous: A, B and info are readable after the returned event is waited on.
- Template Parameters
-
| Back | backend; the backend-deducing overload takes it from ctx.backend() |
| T | scalar type (float, double, std::complex<float>, std::complex<double>) |
- Parameters
-
| ctx | queue the kernels are enqueued on |
| A | batch of n x n matrices; overwritten with the Cholesky factor |
| B | batch of n x nrhs right-hand sides; overwritten with X |
| uplo | triangle of A that is read and receives the factor |
| work_space | device-accessible scratch of at least posv_buffer_size() bytes |
| info | per-item status as for potrf(): 0 on success, i > 0 if the leading minor of order i is not positive definite (that item's X is meaningless). Empty span = not requested. |
- Returns
- event of the last enqueued kernel
- Exceptions
-
1.18.0