Skip to main content

cusolverDnIRSXgels

singe_cusolver_sys

Function cusolverDnIRSXgels 

Source 
pub unsafe extern "C" fn cusolverDnIRSXgels(
    handle: cusolverDnHandle_t,
    gels_irs_params: cusolverDnIRSParams_t,
    gels_irs_infos: cusolverDnIRSInfos_t,
    m: cusolver_int_t,
    n: cusolver_int_t,
    nrhs: cusolver_int_t,
    dA: *mut c_void,
    ldda: cusolver_int_t,
    dB: *mut c_void,
    lddb: cusolver_int_t,
    dX: *mut c_void,
    lddx: cusolver_int_t,
    dWorkspace: *mut c_void,
    lwork_bytes: size_t,
    niters: *mut cusolver_int_t,
    d_info: *mut cusolver_int_t,
) -> cusolverStatus_t
Expand description

This function is designed to perform same functionality as cusolverDn<T1><T2>gels() functions, but wrapped in a more generic and expert interface that gives user more control to parametrize the function as well as it provides more information on output. cusolverDnIRSXgels allows additional control of the solver parameters such as setting:

  • the main precision (Inputs/Outputs precision) of the solver,
  • the lowest precision to be used internally by the solver,
  • the refinement solver type
  • the maximum allowed number of iterations in the refinement phase
  • the tolerance of the refinement solver
  • the fallback to main precision
  • and others

through the configuration parameters structure gels_irs_params and its helper functions. For more details about what configuration can be set and its meaning please refer to all the functions in the cuSolverDN Helper Function Section that start with cusolverDnIRSParamsxxxx(). Moreover, cusolverDnIRSXgels provides additional information on the output such as the convergence history (e.g., the residual norms) at each iteration and the number of iterations needed to converge. For more details about what information can be retrieved and its meaning please refer to all the functions in the cuSolverDN Helper Function Section that start with cusolverDnIRSInfosxxxx().

The function returns value describes the results of the solving process. A cusolverStatus_t::CUSOLVER_STATUS_SUCCESS indicates that the function finished with success otherwise, it indicates if one of the API arguments is incorrect, or if the configurations of params/infos structure is incorrect or if the function did not finish with success. More details about the error can be found by checking the niters and the dinfo API parameters. See their description below for further details. Users should provide the required workspace allocated on device for the cusolverDnIRSXgels function. The amount of bytes required for the function can be queried by calling the respective function cusolverDnIRSXgels_bufferSize. Note that, if the user would like a particular configuration to be set via the params structure, it should be set before the call to cusolverDnIRSXgels_bufferSize to get the size of the required workspace.

The following table provides all possible combinations values for the lowest precision corresponding to the Inputs/Outputs data type. Note that if the lowest precision matches the Inputs/Outputs datatype, then main precision factorization will be used

Tensor Float (TF32), introduced with NVIDIA Ampere Architecture GPUs, is the most robust tensor core accelerated compute mode for the iterative refinement solver. It is able to solve the widest range of problems in HPC arising from different applications and provides up to 4X and 5X speedup for real and complex systems, respectively. On Volta and Turing architecture GPUs, half precision tensor core acceleration is recommended. In cases where the iterative refinement solver fails to converge to the desired accuracy (main precision, INOUT data precision), it is recommended to use main precision as internal lowest precision.

Supported Inputs/Outputs data type and lower precision for the IRS solver

Inputs/Outputs Data Type (e.g., main precision)Supported values for the lowest precision
cusolverPrecType_t::CUSOLVER_C_64FCUSOLVER_C_64F, CUSOLVER_C_32F, CUSOLVER_C_16F, CUSOLVER_C_16BF, CUSOLVER_C_TF32
cusolverPrecType_t::CUSOLVER_C_32FCUSOLVER_C_32F, CUSOLVER_C_16F, CUSOLVER_C_16BF, CUSOLVER_C_TF32
cusolverPrecType_t::CUSOLVER_R_64FCUSOLVER_R_64F, CUSOLVER_R_32F, CUSOLVER_R_16F, CUSOLVER_R_16BF, CUSOLVER_R_TF32
cusolverPrecType_t::CUSOLVER_R_32FCUSOLVER_R_32F, CUSOLVER_R_16F, CUSOLVER_R_16BF, CUSOLVER_R_TF32

The cusolverDnIRSXgels_bufferSize function return the required workspace buffer size in bytes for the corresponding cusolverDnXgels() call with given gels_irs_params configuration.

  • n<0
  • ldda<max(1,m)
  • lddb<max(1,m)
  • lddx<max(1,n).

§Parameters

  • handle: Handle to the cusolverDn library context.
  • gels_irs_params: Configuration parameters structure, can serve one or more calls to any IRS solver.
  • gels_irs_infos: Info structure, where information about a particular solve will be stored. The gels_irs_infos structure correspond to a particular call. Thus different calls requires different gels_irs_infos structure otherwise, it will be overwritten.
  • m: Number of rows of the matrix A. Should be non-negative and n<=m.
  • n: Number of columns of the matrix A. Should be non-negative and n<=m.
  • nrhs: Number of right hand sides to solve. Should be non-negative. Note that, nrhs is limited to 1 if the selected IRS refinement solver is cusolverIRSRefinement_t::CUSOLVER_IRS_REFINE_GMRES, cusolverIRSRefinement_t::CUSOLVER_IRS_REFINE_GMRES_GMRES, cusolverIRSRefinement_t::CUSOLVER_IRS_REFINE_CLASSICAL_GMRES.
  • dA: Matrix A with size m-by-n. Can’t be NULL. On return - unchanged if the lowest precision is not equal to the main precision and the iterative refinement solver converged, - garbage otherwise.
  • ldda: Leading dimension of two-dimensional array used to store matrix A. ldda >= m.
  • dB: Set of right hand sides B of size m-by-nrhs. Can’t be NULL.
  • lddb: Leading dimension of two-dimensional array used to store matrix of right hand sides B. lddb >= max(1,m).
  • dX: Set of solution vectors X of size n-by-nrhs. Can’t be NULL.
  • lddx: Leading dimension of two-dimensional array used to store matrix of solution vectors X. lddx >= max(1,n).
  • dWorkspace: Pointer to an allocated workspace in device memory of size lwork_bytes.
  • lwork_bytes: Size of the allocated device workspace. Should be at least what was returned by cusolverDnIRSXgels_bufferSize function.
  • niters: If iter is * <0 : iterative refinement has failed, main precision (Inputs/Outputs precision) factorization has been performed if fallback is enabled * -1 : taking into account machine parameters, n, nrhs, it is a priori not worth working in lower precision * -2 : overflow of an entry when moving from main to lower precision * -3 : failure during the factorization * -5 : overflow occurred during computation * -maxiter: solver stopped the iterative refinement after reaching maximum allowed iterations * >0 : iter is a number of iterations solver performed to reach convergence criteria.

§Return value

  • n&lt;0
  • ldda&lt;max(1,m)
  • lddb&lt;max(1,m)
  • lddx&lt;max(1,n).