muSOLVER API Reference

This reference covers the muSOLVER APIs supported in MUSA SDK 5.2. It begins with the muSOLVER library families and problem models, then documents the dense solver APIs for QR factorization, LU factorization and solve, orthogonal and unitary matrix generation, and generalized eigenvalue problems.

1. Introduction

1.1 What Is muSOLVER

muSOLVER provides GPU-accelerated solver routines for linear algebra on MUSA devices. The library follows an umbrella model: different API prefixes identify dense solvers, sparse solvers, sparse refactorization routines, and multi-GPU routines.

This umbrella model helps when reading the headers because the prefix identifies the solver family before the function name identifies the operation. This reference introduces the family model first, then narrows the MUSA SDK 5.2 scope to the supported dense solver APIs.

1.2 muSOLVER Components and Problem Models

The API prefix identifies the solver family and the problem class.

Prefix	Meaning	Typical problem class	MUSA SDK 5.2 API reference coverage
musolverDn	Dense solver APIs	Dense factorizations, dense linear solves, and dense eigenvalue problems	Included in this reference
musolverSp	Sparse solver APIs	Sparse linear systems and sparse least-squares problems	Concept only; no API entries
musolverRf	Sparse refactorization APIs	Repeated sparse solves with a shared sparsity pattern	Concept only; no API entries
musolverMg	Multi-GPU solver APIs	Distributed dense matrix operations	Concept only; no API entries

1.2.1 Dense Solver APIs (musolverDn)

Dn means dense. The musolverDn APIs operate on dense matrices stored in device memory. Dense solver routines commonly target linear systems in which all matrix entries are represented explicitly:

$$A X = B$$

The dense APIs in this reference include QR factorization, LU factorization and solve, generated orthogonal or unitary matrices, and generalized symmetric or Hermitian eigenvalue problems. The corresponding problem models include:

$$A = Q \begin{bmatrix} R \\ 0 \end{bmatrix}, \quad A = P L U, \quad A X = \lambda B X$$

Here, A and B are dense matrices, X is the solution or eigenvector matrix, Q is an orthogonal or unitary matrix, P is a permutation matrix, and L and U are triangular factors.

1.2.2 Sparse Solver APIs (musolverSp)

Sp means sparse. Sparse solver APIs target matrices in which only nonzero entries are stored. These APIs are commonly used for sparse linear systems:

$$A x = b$$

and sparse least-squares problems:

$$\min_x \lVert A x - b \rVert_2$$

Sparse solver declarations may appear in the public headers, but they are not included as supported API entries in this MUSA SDK 5.2 reference.

1.2.3 Sparse Refactorization APIs (musolverRf)

Rf means refactorization. Refactorization APIs target a sequence of sparse linear systems in which the coefficient values change but the sparsity pattern remains the same:

$$A_i x_i = b_i,\quad i = 1,\ldots,k$$

This model avoids repeating the full symbolic analysis when the ordering, pivoting, and sparsity pattern of the triangular factors are unchanged across solves. Refactorization declarations may appear in the public headers, but they are not included as supported API entries in this MUSA SDK 5.2 reference.

1.2.4 Multi-GPU APIs (musolverMg)

Mg means multi-GPU. Multi-GPU APIs describe solver operations over matrices distributed across multiple MUSA devices, typically using a device grid and distributed matrix descriptors. Multi-GPU declarations may appear in the public headers, but they are not included as supported API entries in this MUSA SDK 5.2 reference.

1.3 Document Scope in MUSA SDK 5.2

Use this reference to check the functions, types, parameters, and status values supported for muSOLVER in MUSA SDK 5.2. The API reference body covers only dense solver entries with the musolverDn prefix.

Note: Some muSOLVER declarations may appear in the public headers but are absent from this reference. These declarations are experimental in MUSA SDK 5.2 and are provided for reference only.

1.4 Supported Dense Solver Capabilities

Capability	Representative APIs
Dense solver context management	musolverDnCreate, musolverDnDestroy
QR factorization	musolverDnSgeqrf, musolverDnDgeqrf, musolverDnCgeqrf, musolverDnZgeqrf
LU factorization and solve	musolverDnSgetrf, musolverDnSgetrs
Orthogonal or unitary matrix generation	musolverDnSorgqr, musolverDnCungqr
Generalized symmetric or Hermitian eigenvalue solve	musolverDnSsygvd, musolverDnChegvd

1.5 How to Use This Document

Start with Chapter 1 to understand the muSOLVER family prefixes and the 5.2 reference scope. Use Chapter 2 for the dense solver usage model, matrix layout rules, and workflow overview. Use Chapter 3 to check return values, handle lifecycle, shared helper and context rules, data types, function signatures, parameter lists, and supported API entries.

2. Using the muSOLVER API

2.1 Dense Solver Model

The APIs in Chapter 3 use the musolverDn prefix and operate on dense matrices stored in device memory. Sparse, refactorization, and multi-GPU workflows are outside the scope of this MUSA SDK 5.2 API reference.

The matrix data arguments point to MUSA device memory, and each routine receives a musolverDnHandle_t handle that identifies the dense solver execution context.

The supported routines follow LAPACK-style conventions. Matrix dimensions are passed as integers. Leading dimensions describe the storage stride for column-major dense matrices. Factorization routines overwrite the input matrix with factorized data, and solve or generation routines consume those factors in later calls.

2.2 Handles and Execution Context

Each API entry takes a musolverDnHandle_t argument named handle. The handle must identify a valid dense solver context before the routine is called. The handle type is defined as a muBLAS handle type, so dense solver execution is tied to the library context supplied by the application.

Create the dense solver handle with musolverDnCreate before calling the routines in this reference, and destroy it with musolverDnDestroy when the dense solver context is no longer needed.

Chapter 3.3 documents the handle-lifecycle helper functions. Shared workspace-query and diagnostic conventions are described in Sections 2.4 and 2.8. This release does not include separate reference entries for stream selection or logger control.

2.3 Formats Reference

The MUSA SDK 5.2 musolverDn APIs covered here use dense vectors and dense column-major matrices in device memory. The conventions in this section apply to the QR, LU, solve, orthogonal or unitary generation, and generalized eigenvalue routines in Chapter 3.

2.3.1 Index Base Format

The dense APIs covered here use dimensions, leading dimensions, and memory layouts that follow standard C host-side indexing conventions when describing storage offsets. For example, when a dense matrix is stored in column-major order, the element in row i and column j is addressed with an offset such as A[i + j * lda].

The LU factorization family is a special case for pivot information. The getrf and getrs routines use pivot arrays whose elements are 1-based, as described in the parameter tables for those routines.

2.3.2 Vector (Dense) Format

Dense vectors are stored linearly in device memory. This convention applies to vector arguments in this reference, such as Householder scalar arrays (TAU or tau), eigenvalue output arrays (D), and diagnostic arrays (devInfo or info).

For a length-n vector

$$x = \begin{bmatrix} x_1 \\ x_2 \\ \vdots \\ x_n \end{bmatrix}$$

the device storage is a linear array containing the elements in order:

$$[x_1, x_2, \ldots, x_n]$$

2.3.3 Matrix (Dense) Format

The dense matrix arguments in this reference are stored in column-major order in device memory. This applies to matrices such as the factorization input A, the right-hand side or solution matrix B, and the dense eigenvalue matrices used by sygvd and hegvd.

For an m-by-n matrix

$$A = \begin{bmatrix} a_{11} & a_{12} & \cdots & a_{1n} \\ a_{21} & a_{22} & \cdots & a_{2n} \\ \vdots & \vdots & \ddots & \vdots \\ a_{m1} & a_{m2} & \cdots & a_{mn} \end{bmatrix}$$

the device storage order is

$$[a_{11}, a_{21}, \ldots, a_{m1}, a_{12}, a_{22}, \ldots, a_{m2}, \ldots, a_{1n}, a_{2n}, \ldots, a_{mn}]$$

The leading dimension records the physical stride between successive columns. For an m-by-n matrix A, the routines in this reference typically require lda >= m for factorization and orthogonal or unitary generation routines, and lda >= n for square solve or generalized eigenvalue routines. When a second dense matrix B is present, the same rule applies to ldb, depending on the function family. For symmetric or Hermitian eigenvalue routines, uplo selects whether the upper or lower triangle of A and B is stored and used.

2.4 Workspace Query and Workspace Allocation

Workspace-dependent routines have a matching _bufferSize entry. Call the _bufferSize routine first to query the required lwork or Lwork value, allocate device workspace of the matching data type, and pass that workspace to the compute routine.

Pattern	Purpose
musolverDn<t><op>_bufferSize(...)	Returns the workspace size required by the matching compute routine.
musolverDn<t><op>(..., <type> *work/Workspace, int lwork/Lwork, ...)	Consumes the allocated device workspace during the computation.

The workspace pointer and size must match the requirements of the selected operation. If they do not, the call can fail with a non-success musolverStatus_t value. The supported families that use this pattern in this reference are geqrf, getrf, orgqr, ungqr, sygvd, and hegvd.

2.5 Factorization and Solve Workflow

For a QR workflow, use geqrf_bufferSize to query workspace, call geqrf to factor the input matrix, and use the returned Householder scalar array TAU with orgqr or ungqr when an explicit orthogonal or unitary matrix is required.

For an LU workflow, use getrf_bufferSize to query workspace, call getrf to factor the input matrix with partial pivoting, and call getrs to solve systems using the factorized matrix and pivot array. Pivot indices are 1-based, as described by the getrf parameter tables.

2.6 Orthogonal and Unitary Matrix Generation

The orgqr routines generate real orthogonal matrices from QR factors. The ungqr routines generate complex unitary matrices from QR factors. Both families consume the Householder vectors stored in A and the scalar factors stored in tau from a previous QR factorization.

Use the matching _bufferSize routine to size the workspace before calling the generation routine.

2.7 Generalized Eigenvalue Workflow

The sygvd routines solve real generalized symmetric-definite eigenvalue problems. The hegvd routines solve complex generalized Hermitian-definite eigenvalue problems.

The itype argument selects the generalized problem form. The evect argument selects whether eigenvectors are computed. The uplo argument selects which triangle of the input matrices is stored. Use the matching _bufferSize routine to size the workspace before calling the compute routine.

2.8 Error Handling and Info Arrays

The functions in this section return musolverStatus_t. A return value of MUSOLVER_STATUS_SUCCESS indicates that the API call completed successfully. Any other return value indicates that the call did not complete as requested.

Several routines also take a device-side diagnostic pointer named devInfo or info.

Output	Used by	Meaning
devInfo	geqrf, getrf, getrs	Device-side routine status. 0 indicates success. The meaning of nonzero values depends on the routine family.
info	orgqr, ungqr, sygvd, hegvd	Device-side routine status. 0 indicates success. The meaning of nonzero values depends on the routine family.

For LU factorization, devInfo = 0 indicates success, and devInfo = i > 0 indicates that U(i,i) is the first zero pivot. For generalized eigenvalue routines, info = 0 indicates success; positive values report convergence failures or positive-definiteness diagnostics described in the function entries. The family sections in Chapter 3 define the routine-specific meaning of nonzero diagnostic values.

3. API Reference

This chapter describes muSOLVER status values, data types, helper functions, and dense solver functions. The dense solver families are grouped by API stem, so each subsection combines the typed workspace-query and compute signatures, shared parameter tables, and shared status notes for the supported MUSA SDK 5.2 entries. APIs that may appear in the public headers but do not appear here as supported entries should be treated as experimental and for reference only in this release.

3.1 Return Value musolverStatus_t

The functions in this reference return musolverStatus_t. A return value of MUSOLVER_STATUS_SUCCESS indicates that the call completed successfully. Any other value indicates that the call did not complete as requested.

The public status enum defines the following values. A given function may return only a subset of these values.

Status value	Meaning
MUSOLVER_STATUS_SUCCESS	The operation completed successfully.
MUSOLVER_STATUS_NOT_INITIALIZED	The library context or handle was not initialized.
MUSOLVER_STATUS_ALLOC_FAILED	An internal or requested allocation failed.
MUSOLVER_STATUS_INVALID_VALUE	One or more argument values are invalid.
MUSOLVER_STATUS_ARCH_MISMATCH	The selected device architecture does not support the requested operation.
MUSOLVER_STATUS_MAPPING_ERROR	A memory mapping operation failed.
MUSOLVER_STATUS_EXECUTION_FAILED	Device execution failed.
MUSOLVER_STATUS_INTERNAL_ERROR	The library encountered an internal failure.
MUSOLVER_STATUS_MATRIX_TYPE_NOT_SUPPORTED	The selected matrix type is not supported by the routine.
MUSOLVER_STATUS_NOT_SUPPORTED	The requested operation or configuration is not supported.
MUSOLVER_STATUS_ZERO_PIVOT	A zero pivot was detected.
MUSOLVER_STATUS_INVALID_LICENSE	The required license is not valid.
MUSOLVER_STATUS_IRS_PARAMS_NOT_INITIALIZED	Iterative refinement solver parameters were not initialized.
MUSOLVER_STATUS_IRS_PARAMS_INVALID	Iterative refinement solver parameters are invalid.
MUSOLVER_STATUS_IRS_PARAMS_INVALID_PREC	The iterative refinement solver precision setting is invalid.
MUSOLVER_STATUS_IRS_PARAMS_INVALID_REFINE	The iterative refinement solver refinement setting is invalid.
MUSOLVER_STATUS_IRS_PARAMS_INVALID_MAXITER	The iterative refinement solver maximum-iteration setting is invalid.
MUSOLVER_STATUS_IRS_INTERNAL_ERROR	The iterative refinement solver encountered an internal failure.
MUSOLVER_STATUS_IRS_NOT_SUPPORTED	The iterative refinement solver configuration is not supported.
MUSOLVER_STATUS_IRS_OUT_OF_RANGE	An iterative refinement solver value is out of range.
MUSOLVER_STATUS_IRS_NRHS_NOT_SUPPORTED_FOR_REFINE_GMRES	The number of right-hand sides is not supported for GMRES refinement.
MUSOLVER_STATUS_IRS_INFOS_NOT_INITIALIZED	Iterative refinement solver info storage was not initialized.
MUSOLVER_STATUS_IRS_INFOS_NOT_DESTROYED	Iterative refinement solver info storage was not destroyed.
MUSOLVER_STATUS_IRS_MATRIX_SINGULAR	The iterative refinement solver detected a singular matrix.
MUSOLVER_STATUS_INVALID_WORKSPACE	The workspace pointer or workspace size is invalid for the requested operation.

3.2 muSOLVER Types Reference

This section summarizes the public types that appear in the supported MUSA SDK 5.2 muSOLVER API signatures.

Type	Purpose
musolverDnHandle_t	Dense solver context handle initialized by musolverDnCreate and passed to each API entry.
musolverStatus_t	Return type used by the muSOLVER functions in this reference.
musolverEigType_t	Selects the generalized eigenvalue problem form for sygvd and hegvd routines.
musolverEigMode_t	Selects whether generalized eigenvectors are computed.
mublasFillMode_t	Selects whether the upper or lower triangle of symmetric or Hermitian matrices is stored.
mublasOperation_t	Selects the system form used by getrs, such as non-transposed, transposed, or conjugate-transposed.
muComplex	Single-precision complex scalar type used by complex dense solver routines.
muDoubleComplex	Double-precision complex scalar type used by complex dense solver routines.

3.2.1 musolverDnHandle_t

musolverDnHandle_t identifies the dense solver context used by each supported routine. Initialize the handle with musolverDnCreate before calling the compute families in this reference, and release it with musolverDnDestroy when the context is no longer needed.

3.2.2 musolverEigType_t

musolverEigType_t selects the form of the generalized eigenvalue problem.

Value	Problem form
MUSOLVER_EIG_TYPE_1	Type-1 generalized eigenvalue problem.
MUSOLVER_EIG_TYPE_2	Type-2 generalized eigenvalue problem.
MUSOLVER_EIG_TYPE_3	Type-3 generalized eigenvalue problem.

The corresponding problem forms are:

$$\begin{aligned} \texttt{MUSOLVER\_EIG\_TYPE\_1}:&\quad A X = \lambda B X \\ \texttt{MUSOLVER\_EIG\_TYPE\_2}:&\quad A B X = \lambda X \\ \texttt{MUSOLVER\_EIG\_TYPE\_3}:&\quad B A X = \lambda X \end{aligned}$$

3.2.3 musolverEigMode_t

musolverEigMode_t selects whether the generalized eigenvalue routines compute eigenvectors.

Value	Meaning
MUSOLVER_EIG_MODE_NOVECTOR	Compute eigenvalues only.
MUSOLVER_EIG_MODE_VECTOR	Compute eigenvalues and eigenvectors.

3.3 Dense Solver Helper Functions

This section documents the dense solver helper functions that are in scope for this reference. In MUSA SDK 5.2, that scoped set consists of handle creation and destruction. It does not include separate reference entries for stream selection or logger control.

3.3.1 musolverDnCreate()

musolverStatus_t musolverDnCreate(musolverDnHandle_t *handle)

Initializes a dense solver library context and returns it through handle. Create the handle before calling any musolverDn workspace-query or compute routine in this reference.

Parameter	Description
handle	Output pointer that receives the initialized dense solver handle.

Status Returned

MUSOLVER_STATUS_SUCCESS indicates success. Any other return value indicates that the dense solver context could not be initialized.

3.3.2 musolverDnDestroy()

musolverStatus_t musolverDnDestroy(musolverDnHandle_t handle)

Destroys a dense solver library context and releases the resources associated with it. Call this routine after all operations that use the handle have finished.

Parameter	Description
handle	Dense solver handle to destroy.

Status Returned

MUSOLVER_STATUS_SUCCESS indicates success. Any other return value indicates that the handle could not be destroyed cleanly.

3.4 Dense QR Factorization

The geqrf routines compute a QR factorization of a general m-by-n matrix:

$$A = Q \begin{bmatrix} R \\ 0 \end{bmatrix}$$

R is upper triangular, or upper trapezoidal when m < n. Q is represented as a product of Householder matrices.

3.4.1 musolverDn<t>geqrf()

These APIs first query the workspace size and then compute the QR factorization. The S and D variants use float and double. The C and Z variants use muComplex and muDoubleComplex.

Workspace-query APIs:

musolverStatus_t musolverDnSgeqrf_bufferSize(musolverDnHandle_t handle, int m, int n, float *A, int lda, int *lwork)
musolverStatus_t musolverDnDgeqrf_bufferSize(musolverDnHandle_t handle, int m, int n, double *A, int lda, int *lwork)
musolverStatus_t musolverDnCgeqrf_bufferSize(musolverDnHandle_t handle, int m, int n, muComplex *A, int lda, int *lwork)
musolverStatus_t musolverDnZgeqrf_bufferSize(musolverDnHandle_t handle, int m, int n, muDoubleComplex *A, int lda, int *lwork)

Compute APIs:

musolverStatus_t musolverDnSgeqrf(musolverDnHandle_t handle, int m, int n, float *A, int lda, float *TAU, float *Workspace, int Lwork, int *devInfo)
musolverStatus_t musolverDnDgeqrf(musolverDnHandle_t handle, int m, int n, double *A, int lda, double *TAU, double *Workspace, int Lwork, int *devInfo)
musolverStatus_t musolverDnCgeqrf(musolverDnHandle_t handle, int m, int n, muComplex *A, int lda, muComplex *TAU, muComplex *Workspace, int Lwork, int *devInfo)
musolverStatus_t musolverDnZgeqrf(musolverDnHandle_t handle, int m, int n, muDoubleComplex *A, int lda, muDoubleComplex *TAU, muDoubleComplex *Workspace, int Lwork, int *devInfo)

The compute routines overwrite A. On exit, the diagonal and upper triangle contain R, the elements below the diagonal contain Householder vectors, and TAU stores the corresponding scalar factors.

Parameter	Applies to	Description
handle	all variants	Dense solver handle.
m	all variants	Number of rows in A; m >= 0.
n	all variants	Number of columns in A; n >= 0.
A	all variants	For _bufferSize, device pointer to the input matrix. For compute, on entry contains the m-by-n matrix to factor. On exit, the diagonal and upper triangle contain R, and the elements below the diagonal contain Householder vectors.
lda	all variants	Leading dimension of A; lda >= m.
lwork	_bufferSize variants	Host pointer that receives the required workspace size.
TAU	compute variants	Device array of dimension min(m,n) that receives Householder scalar factors.
Workspace	compute variants	Device workspace for the routine.
Lwork	compute variants	Workspace size returned by the matching _bufferSize routine.
devInfo	compute variants	Device pointer that receives routine status.

Status Returned

MUSOLVER_STATUS_SUCCESS indicates success. Common family-level failures include MUSOLVER_STATUS_NOT_INITIALIZED, MUSOLVER_STATUS_INVALID_VALUE, MUSOLVER_STATUS_INVALID_WORKSPACE, MUSOLVER_STATUS_EXECUTION_FAILED, and MUSOLVER_STATUS_INTERNAL_ERROR. See 3.1 Return Value musolverStatus_t for the complete public enum.

3.5 Dense LU Factorization and Solve

The getrf routines compute an LU factorization of a general m-by-n matrix using partial pivoting:

$$A = P L U$$

P is a permutation matrix, L is lower triangular with unit diagonal elements, and U is upper triangular. The unit diagonal of L is not stored. The getrs routines solve linear systems using the factors and pivot indices returned by getrf.

3.5.1 musolverDn<t>getrf()

These APIs first query the workspace size and then compute the LU factorization. The S and D variants use float and double. The C and Z variants use muComplex and muDoubleComplex.

Workspace-query APIs:

musolverStatus_t musolverDnSgetrf_bufferSize(musolverDnHandle_t handle, int m, int n, float *A, int lda, int *Lwork)
musolverStatus_t musolverDnDgetrf_bufferSize(musolverDnHandle_t handle, int m, int n, double *A, int lda, int *Lwork)
musolverStatus_t musolverDnCgetrf_bufferSize(musolverDnHandle_t handle, int m, int n, muComplex *A, int lda, int *Lwork)
musolverStatus_t musolverDnZgetrf_bufferSize(musolverDnHandle_t handle, int m, int n, muDoubleComplex *A, int lda, int *Lwork)

Compute APIs:

musolverStatus_t musolverDnSgetrf(musolverDnHandle_t handle, int m, int n, float *A, int lda, float *Workspace, int *devIpiv, int *devInfo)
musolverStatus_t musolverDnDgetrf(musolverDnHandle_t handle, int m, int n, double *A, int lda, double *Workspace, int *devIpiv, int *devInfo)
musolverStatus_t musolverDnCgetrf(musolverDnHandle_t handle, int m, int n, muComplex *A, int lda, muComplex *Workspace, int *devIpiv, int *devInfo)
musolverStatus_t musolverDnZgetrf(musolverDnHandle_t handle, int m, int n, muDoubleComplex *A, int lda, muDoubleComplex *Workspace, int *devIpiv, int *devInfo)

The compute routines overwrite A. On exit, A contains the L and U factors, the unit diagonal of L is not stored, and devIpiv contains 1-based pivot indices.

Parameter	Applies to	Description
handle	all variants	Dense solver handle.
m	all variants	Number of rows in A; m >= 0.
n	all variants	Number of columns in A; n >= 0.
A	all variants	For _bufferSize, device pointer to the input matrix. For compute, on entry contains the matrix to factor. On exit, contains the L and U factors.
lda	all variants	Leading dimension of A; lda >= m.
Lwork	_bufferSize variants	Host pointer that receives the required workspace size.
Workspace	compute variants	Device workspace sized by the matching _bufferSize routine.
devIpiv	compute variants	Device array of dimension min(m,n) that receives 1-based pivot indices.
devInfo	compute variants	Device pointer. 0 indicates success. i > 0 indicates that U(i,i) is the first zero pivot.

Status Returned

MUSOLVER_STATUS_SUCCESS indicates success. Common family-level failures include MUSOLVER_STATUS_NOT_INITIALIZED, MUSOLVER_STATUS_INVALID_VALUE, MUSOLVER_STATUS_INVALID_WORKSPACE, MUSOLVER_STATUS_EXECUTION_FAILED, and MUSOLVER_STATUS_INTERNAL_ERROR. See 3.1 Return Value musolverStatus_t for the complete public enum.

3.5.2 musolverDn<t>getrs()

These APIs solve linear systems with one or more right-hand sides using the LU factors and pivot indices returned by getrf.

musolverStatus_t musolverDnSgetrs(musolverDnHandle_t handle, mublasOperation_t trans, int n, int nrhs, const float *A, int lda, const int *devIpiv, float *B, int ldb, int *devInfo)
musolverStatus_t musolverDnDgetrs(musolverDnHandle_t handle, mublasOperation_t trans, int n, int nrhs, const double *A, int lda, const int *devIpiv, double *B, int ldb, int *devInfo)
musolverStatus_t musolverDnCgetrs(musolverDnHandle_t handle, mublasOperation_t trans, int n, int nrhs, const muComplex *A, int lda, const int *devIpiv, muComplex *B, int ldb, int *devInfo)
musolverStatus_t musolverDnZgetrs(musolverDnHandle_t handle, mublasOperation_t trans, int n, int nrhs, const muDoubleComplex *A, int lda, const int *devIpiv, muDoubleComplex *B, int ldb, int *devInfo)

Parameter	Description
handle	Dense solver handle.
trans	Selects whether the routine solves the non-transposed, transposed, or conjugate-transposed system.
n	Order of the square system; n >= 0.
nrhs	Number of right-hand sides; nrhs >= 0.
A	Device pointer to the LU factors returned by getrf; dimension lda * n.
lda	Leading dimension of A; lda >= n.
devIpiv	Device pointer to the pivot indices returned by getrf; dimension n.
B	Device pointer to the right-hand-side matrix on entry and the solution matrix on exit; dimension ldb * nrhs.
ldb	Leading dimension of B; ldb >= n.
devInfo	Device pointer that receives routine status.

Status Returned

MUSOLVER_STATUS_SUCCESS indicates success. Common family-level failures include MUSOLVER_STATUS_NOT_INITIALIZED, MUSOLVER_STATUS_INVALID_VALUE, MUSOLVER_STATUS_EXECUTION_FAILED, and MUSOLVER_STATUS_INTERNAL_ERROR. See 3.1 Return Value musolverStatus_t for the complete public enum.

3.6 Dense Orthogonal and Unitary Matrix Generation

The orgqr routines generate real orthogonal matrices with orthonormal columns. The ungqr routines generate complex unitary matrices with orthonormal columns. The generated matrix is defined as the first n columns of the product of k Householder reflectors returned by QR factorization:

$$Q = H_1 H_2 \cdots H_k$$

3.6.1 musolverDn<t>orgqr()/musolverDn<t>ungqr()

These APIs first query the workspace size and then generate the explicit orthogonal or unitary matrix. The S and D variants use orgqr with float and double. The C and Z variants use ungqr with muComplex and muDoubleComplex.

Workspace-query APIs:

musolverStatus_t musolverDnSorgqr_bufferSize(musolverDnHandle_t handle, int m, int n, int k, const float *A, int lda, const float *tau, int *lwork)
musolverStatus_t musolverDnDorgqr_bufferSize(musolverDnHandle_t handle, int m, int n, int k, const double *A, int lda, const double *tau, int *lwork)
musolverStatus_t musolverDnCungqr_bufferSize(musolverDnHandle_t handle, int m, int n, int k, const muComplex *A, int lda, const muComplex *tau, int *lwork)
musolverStatus_t musolverDnZungqr_bufferSize(musolverDnHandle_t handle, int m, int n, int k, const muDoubleComplex *A, int lda, const muDoubleComplex *tau, int *lwork)

Compute APIs:

musolverStatus_t musolverDnSorgqr(musolverDnHandle_t handle, int m, int n, int k, float *A, int lda, float *tau, float *work, int lwork, int *info)
musolverStatus_t musolverDnDorgqr(musolverDnHandle_t handle, int m, int n, int k, double *A, int lda, double *tau, double *work, int lwork, int *info)
musolverStatus_t musolverDnCungqr(musolverDnHandle_t handle, int m, int n, int k, muComplex *A, int lda, muComplex *tau, muComplex *work, int lwork, int *info)
musolverStatus_t musolverDnZungqr(musolverDnHandle_t handle, int m, int n, int k, muDoubleComplex *A, int lda, muDoubleComplex *tau, muDoubleComplex *work, int lwork, int *info)

The compute routines use the Householder reflectors returned by geqrf. On entry, A contains the reflector data. On exit, A contains the generated matrix Q.

Parameter	Applies to	Description
handle	all variants	Dense solver handle.
m	all variants	Number of rows in Q; m >= 0.
n	all variants	Number of columns in Q; 0 <= n <= m.
k	all variants	Number of Householder reflectors; 0 <= k <= n.
A	all variants	For _bufferSize, device pointer to the QR reflector data. For compute, on entry contains the Householder vectors in the first k columns. On exit, contains the generated matrix Q.
lda	all variants	Leading dimension of A; lda >= m.
tau	all variants	Device pointer to the Householder scalar factors returned by QR factorization.
lwork	_bufferSize variants	Host pointer that receives the required workspace size.
work	compute variants	Device workspace for the routine.
lwork	compute variants	Workspace size returned by the matching _bufferSize routine.
info	compute variants	Device pointer that receives routine status.

Status Returned

MUSOLVER_STATUS_SUCCESS indicates success. Common family-level failures include MUSOLVER_STATUS_NOT_INITIALIZED, MUSOLVER_STATUS_INVALID_VALUE, MUSOLVER_STATUS_INVALID_WORKSPACE, MUSOLVER_STATUS_EXECUTION_FAILED, and MUSOLVER_STATUS_INTERNAL_ERROR. See 3.1 Return Value musolverStatus_t for the complete public enum.

3.7 Generalized Symmetric/Hermitian Eigenvalue Problems

The sygvd routines compute eigenvalues, and optionally eigenvectors, for real generalized symmetric-definite eigenvalue problems. The hegvd routines provide the corresponding complex generalized Hermitian-definite functionality.

The selected itype determines the problem form:

$$\begin{aligned} \texttt{MUSOLVER\_EIG\_TYPE\_1}:&\quad A X = \lambda B X \\ \texttt{MUSOLVER\_EIG\_TYPE\_2}:&\quad A B X = \lambda X \\ \texttt{MUSOLVER\_EIG\_TYPE\_3}:&\quad B A X = \lambda X \end{aligned}$$

When eigenvectors are computed, the normalized eigenvector matrix is returned in A. The eigenvalues are returned in increasing order in D.

3.7.1 musolverDn<t>sygvd()/musolverDn<t>hegvd()

These APIs first query the workspace size and then compute eigenvalues and, optionally, eigenvectors. The S and D variants use sygvd with real symmetric-definite matrices. The C and Z variants use hegvd with complex Hermitian-definite matrices.

Workspace-query APIs:

musolverStatus_t musolverDnSsygvd_bufferSize(musolverDnHandle_t handle, const musolverEigType_t itype, const musolverEigMode_t evect, const mublasFillMode_t uplo, const int n, const float *A, const int lda, const float *B, const int ldb, const float *D, int *lwork)
musolverStatus_t musolverDnDsygvd_bufferSize(musolverDnHandle_t handle, const musolverEigType_t itype, const musolverEigMode_t evect, const mublasFillMode_t uplo, const int n, const double *A, const int lda, const double *B, const int ldb, const double *D, int *lwork)
musolverStatus_t musolverDnChegvd_bufferSize(musolverDnHandle_t handle, const musolverEigType_t itype, const musolverEigMode_t evect, const mublasFillMode_t uplo, const int n, const muComplex *A, const int lda, const muComplex *B, const int ldb, const float *D, int *lwork)
musolverStatus_t musolverDnZhegvd_bufferSize(musolverDnHandle_t handle, const musolverEigType_t itype, const musolverEigMode_t evect, const mublasFillMode_t uplo, const int n, const muDoubleComplex *A, const int lda, const muDoubleComplex *B, const int ldb, const double *D, int *lwork)

Compute APIs:

musolverStatus_t musolverDnSsygvd(musolverDnHandle_t handle, const musolverEigType_t itype, const musolverEigMode_t evect, const mublasFillMode_t uplo, const int n, float *A, const int lda, float *B, const int ldb, float *D, float *work, const int lwork, int *info)
musolverStatus_t musolverDnDsygvd(musolverDnHandle_t handle, const musolverEigType_t itype, const musolverEigMode_t evect, const mublasFillMode_t uplo, const int n, double *A, const int lda, double *B, const int ldb, double *D, double *work, const int lwork, int *info)
musolverStatus_t musolverDnChegvd(musolverDnHandle_t handle, const musolverEigType_t itype, const musolverEigMode_t evect, const mublasFillMode_t uplo, const int n, muComplex *A, const int lda, muComplex *B, const int ldb, float *D, muComplex *work, const int lwork, int *info)
musolverStatus_t musolverDnZhegvd(musolverDnHandle_t handle, const musolverEigType_t itype, const musolverEigMode_t evect, const mublasFillMode_t uplo, const int n, muDoubleComplex *A, const int lda, muDoubleComplex *B, const int ldb, double *D, muDoubleComplex *work, const int lwork, int *info)

For compute routines, info = 0 indicates success. If 0 < info <= n, the routine reports a convergence failure in the intermediate eigenvalue computation. If info = n + i, the leading minor of order i of B is not positive definite.

Parameter	Applies to	Description
handle	all variants	Dense solver handle.
itype	all variants	Generalized eigenvalue problem form.
evect	all variants	Selects whether eigenvectors are computed.
uplo	all variants	Selects whether the upper or lower triangle of A and B is stored.
n	all variants	Matrix order; n >= 0.
A	all variants	For _bufferSize, device pointer to the symmetric or Hermitian matrix A. For compute, on exit contains the normalized eigenvector matrix when eigenvectors are computed; otherwise, the referenced triangle is destroyed.
lda	all variants	Leading dimension of A; lda >= n.
B	all variants	For _bufferSize, device pointer to the symmetric or Hermitian positive definite matrix B. For compute, on exit contains the triangular factor of B.
ldb	all variants	Leading dimension of B; ldb >= n.
D	all variants	For _bufferSize, device pointer to the eigenvalue array used by the compute routine. For compute, device array of dimension n that receives eigenvalues in increasing order.
lwork	_bufferSize variants	Host pointer that receives the required workspace size.
work	compute variants	Device workspace for the routine.
lwork	compute variants	Workspace size returned by the matching _bufferSize routine.
info	compute variants	Device pointer. 0 indicates success. Positive values report convergence or positive-definiteness diagnostics.

Status Returned

MUSOLVER_STATUS_SUCCESS indicates success. Common family-level failures include MUSOLVER_STATUS_NOT_INITIALIZED, MUSOLVER_STATUS_INVALID_VALUE, MUSOLVER_STATUS_INVALID_WORKSPACE, MUSOLVER_STATUS_EXECUTION_FAILED, and MUSOLVER_STATUS_INTERNAL_ERROR. See 3.1 Return Value musolverStatus_t for the complete public enum.