API
QRMumps.qrm_spmat
— TypeThis data type is used to store a sparse matrix in the COO (or coordinate) format through the irn
, jcn
and val
fields containing the row indices, column indices and values, respectively and the m
, n
and nz
containing the number of rows, columns and nonzeros, respectively. qr_mumps uses a Fortran-style 1-based numbering and thus all row indices are expected to be between 1 and m and all the column indices between 1 and n. Duplicate entries are summed during the factorization, out-of-bound entries are ignored. The sym
field is used to specify if the matrix is symmetric and positive definite (true
) or not (false
).
QRMumps.qrm_spfct
— TypeThis type is used to set the parameters that control the behavior of a sparse factorization, to collect information about its execution (number of flops, memory consumpnion etc) and store the result of the factorization, namely, the factors with all the symbolic information needed to use them in the solve phase.
QRMumps.qrm_init
— Functionqrm_init(ncpu, ngpu)
This routine initializes qr_mumps and should be called prior to any other qr_mumps routine. This function is automatically called if you use qr_mumps precompiled with Yggdrasil.
qrm_init()
ncpu
and ngpu
are optional arguments and their default value are, respectively, 1
and 0
.
Input Arguments :
ncpu
: number of working threads on CPU.ngpu
: number of working threads on GPU.
QRMumps.qrm_finalize
— Functionqrm_finalize()
This routine finalizes qr_mumps and no other qr_mumps routine should be called afterwards.
QRMumps.qrm_spmat_init
— Functionspmat = qrm_spmat_init(A; sym=false)
+spmat = qrm_spmat_init(m, n, rows, cols, vals; sym=false)
QRMumps.qrm_spmat_init!
— Functionqrm_spmat_init!(spmat, A; sym=false)
+spmat = qrm_spmat_init!(spmat, m, n, rows, cols, vals; sym=false)
This routine initializes a qrm_spmat type data structure from a sparseMatrixCSC.
Input Arguments :
In the first form,
spmat
: the qrm_spmat sparse matrix to be initialized.A
: a Julia sparse matrix stored in either SparseMatrixCSC or SparseMatrixCOO format (see SparseMatricesCOO.jl for the second case).sym
: a boolean to specify if the matrix is symmetric / hermitian (true) or unsymmetric (false).
In the second form, the matrix A
is specified using
m
: the number of rows.n
: the number of columns.rows
: the array of row indices of nonzero elements.cols
: the array of column indices of nonzero elements.vals
: the array of values of nonzero elements.
QRMumps.qrm_spmat_destroy!
— Functionqrm_spmat_destroy!(spmat)
This routine cleans up a qrm_spmat type data structure.
Input Argument :
spfct
: the sparse matrix to be destroyed.
QRMumps.qrm_spfct_init
— Functionspfct = qrm_spfct_init(spmat)
QRMumps.qrm_spfct_init!
— Functionqrm_spfct_init!(spmat, spfct)
This routine initializes a qrm_spfct type data structure. This amounts to setting all the control parameters to the default values.
Input Arguments :
spmat
: the input matrix of typeqrm_spmat
.spfct
: the sparse factorization object to be initialized.
QRMumps.qrm_spfct_destroy!
— Functionqrm_spfct_destroy!(spfct)
This routine cleans up a qrm_spfct type data structure by deleting the result of a sparse factorization.
Input Argument :
spfct
: the sparse factorization object to be destroyed.
QRMumps.qrm_analyse
— Functionspfct = qrm_analyse(spmat; transp='n')
QRMumps.qrm_analyse!
— Functionqrm_analyse!(spmat, spfct; transp='n')
This routine performs the analysis phase and updates spfct.
Input Arguments :
spmat
: the input matrix of typeqrm_spmat
.spfct
: the sparse factorization object of typeqrm_spfct
.transp
: whether the input matrix should be transposed or not. Can be either't'
,'c'
or'n'
.
QRMumps.qrm_update!
— Functionqrm_update!(spmat, A)
+qrm_update!(spmat, vals)
This routine updates a qrm_spmat type data structure from a sparseMatrixCSC. spmat
and A
must have the same sparsity pattern.
Input Arguments :
In the first form,
spmat
: the qrm_spmat sparse matrix to be updated.A
: a Julia sparse matrix stored in SparseMatrixCSC format.
In the second form,
vals
: the array of values of nonzero elements ofA
.
QRMumps.qrm_factorize!
— Functionqrm_factorize!(spmat, spfct; transp='n')
This routine performs the factorization phase. It can only be executed if the analysis is already done.
Input Arguments :
spmat
: the input matrix of typeqrm_spmat
.spfct
: the sparse factorization object of typeqrm_spfct
.transp
: whether the input matrix should be transposed or not. Can be either't'
,'c'
or'n'
.
QRMumps.qrm_solve
— Functionx = qrm_solve(spfct, b; transp='n')
QRMumps.qrm_solve!
— Functionqrm_solve!(spfct, b, x; transp='n')
This routine solves the triangular system Rx = b
or Rᵀx = b
. It can only be executed once the factorization is done.
Input Arguments :
spfct
: the sparse factorization object resulting from the qrm_factorize! function.b
: the right-hand side(s).x
: the solution vector(s).transp
: whether to solve for R, Rᵀ or Rᴴ. Can be either't'
,'c'
or'n'
.
QRMumps.qrm_apply
— Functionz = qrm_apply(spfct, b; transp='n')
QRMumps.qrm_apply!
— Functionqrm_apply!(spfct, b; transp='n')
This routine computes z = Qb
, z = Qᵀb
or z = Qᴴb
in place and overwrites b. It can only be executed once the factorization is done.
Input Arguments :
spfct
: the sparse factorization object resulting from the qrm_factorize! function.b
: the vector(s) to which Q, Qᵀ or Qᴴ is applied.transp
: whether to apply Q, Qᵀ or Qᴴ. Can be either't'
,'c'
or'n'
.
QRMumps.qrm_spfct_get_cp
— Functioncp = qrm_spfct_get_cp(spfct)
Returns the column permutation.
Input Arguments :
spfct
: a sparse factorization object of typeqrm_spfct
.
QRMumps.qrm_spfct_get_rp
— Functionrp = qrm_spfct_get_rp(spfct)
Returns the row permutation.
Input Arguments :
spfct
: a sparse factorization object of typeqrm_spfct
.
QRMumps.qrm_spfct_get_r
— FunctionR = qrm_spfct_get_r(spfct)
Returns the R factor as a SparseMatrixCSC matrix.
Input Arguments :
spfct
: a sparse factorization object of typeqrm_spfct
.
QRMumps.qrm_spbackslash
— Functionx = qrm_spbackslash(spmat, b; transp='n')
QRMumps.qrm_spbackslash!
— Functionqrm_spbackslash!(spmat, b, x; transp='n')
QRMumps.qrm_spposv
— Functionx = qrm_spposv(spmat, b)
QRMumps.qrm_spposv!
— Functionqrm_spposv!(spmat, b, x)
This function can be used to solve a linear symmetric, positive definite problem. It is a shortcut for the sequence
x = b
+qrm_analyse!(spmat, spfct; transp='n')
+qrm_factorize!(spmat, spfct; transp='n')
+qrm_solve!(spfct, x, x; transp='t')
+qrm_solve!(spfct, x, x; transp='t')
Input Arguments :
spmat
: the input matrix.b
: the right-hand side(s).x
: the solution vector(s).
QRMumps.qrm_least_squares
— Functionx = qrm_least_squares(spmat, b; transp='n')
QRMumps.qrm_least_squares!
— Functionqrm_least_squares!(spmat, b, x; transp='n')
This function can be used to solve a linear least squares problem
\[\min \|Ax − b\|_2\]
in the case where the input matrix is square or overdetermined. It is a shortcut for the sequence
qrm_analyse!(spmat, spfct; transp='n')
+qrm_factorize!(spmat, spfct; transp='n')
+qrm_apply!(spfct, b; transp='t')
+qrm_solve!(spfct, b, x; transp='n')
Input Arguments :
spmat
: the input matrix.b
: the ight-hand side(s).x
: the solution vector(s).transp
: whether to use A, Aᵀ or Aᴴ. Can be either't'
,'c'
or'n'
.
QRMumps.qrm_min_norm
— Functionx = qrm_min_norm(spmat, b; transp='n')
QRMumps.qrm_min_norm!
— Functionqrm_min_norm!(spmat, b, x; transp='n')
This function can be used to solve a linear minimum norm problem
\[\min \|x\|_2 \quad s.t. \quad Ax = b\]
in the case where the input matrix is square or underdetermined. It is a shortcut for the sequence
qrm_analyse!(spmat, spfct; transp='t')
+qrm_factorize!(spmat, spfct; transp='t')
+qrm_solve!(spfct, b, x; transp='t')
+qrm_apply!(spfct, x; transp='n')
Input Arguments :
spmat
: the input matrix.b
: the right-hand side(s).x
: the solution vector(s).transp
: whether to use A, Aᵀ or Aᴴ. Can be either't'
,'c'
or'n'
.
QRMumps.qrm_refine
— Functionx_refined = qrm_refine(spmat, spfct, x, z)
QRMumps.qrm_refine!
— Functionqrm_refine!(spmat, spfct, x, z, Δx, y)
Given an approximate solution x of the linear system RᵀRx ≈ z where R is the R-factor of some QR factorization of size (m, n), compute a refined solution.
Input Arguments :
spmat
: the input matrix.spfct
: a sparse factorization object of typeqrm_spfct
.x
: the approximate solution vector, the size of this vector is n.z
: the RHS vector of the linear system, the size of this vector is n.Δx
: an auxiliary vector used to compute the refinement, the size of this vector is n.y
: an auxiliary vector used to compute the refinement, the size of this vector is m.
QRMumps.qrm_spmat_mv!
— Functionqrm_spmat_mv!(spmat, alpha, x, beta, y; transp='n')
This subroutine performs a matrix-vector product of the type y = αAx + βy
, y = αAᵀx + βy
or y = αAᴴx + βy
.
Input Arguments :
spmat
: the input matrix.alpha
,beta
: the α and β scalarsx
: the x vector(s).y
: the y vector(s).transp
: whether to multiply by A, Aᵀ or Aᴴ. Can be either't'
,'c'
or'n'
.
QRMumps.qrm_spmat_nrm
— Functionqrm_spmat_nrm(spmat; ntype='f')
This routine computes the one-norm $\|A\|_1$, the infinity-norm $\|x\|_{\infty}$ or the two-norm $\|x\|_2$ of a matrix.
Input Arguments :
spmat
: the input matrix.ntype
: the type of norm to be computed. It can be either'i'
,'1'
or'f'
for the infinity, one and Frobenius norms, respectively.
QRMumps.qrm_vecnrm!
— Functionqrm_vecnrm!(x, nrm; ntype='2')
This routine computes the one-norm $\|x\|_1$, the infinity-norm $\|x\|_{\infty}$ or the two-norm $\|x\|_2$ of a vector.
Input Arguments :
x
: the x vector(s).nrm
: the computed norm(s). If x is a matrix this argument has to be a vector and each of its elements will contain the norm of the corresponding column of x.ntype
: the type of norm to be computed. It can be either'i'
,'1'
or'2'
for the infinity, one and two norms, respectively.
QRMumps.qrm_vecnrm
— Functionnrm = qrm_vecnrm(x; ntype='2')
QRMumps.qrm_residual_norm!
— Functionqrm_residual_norm!(spmat, b, x, nrm; transp='n')
This function computes the scaled norm of the residual $\frac{\|b - Ax\|_{\infty}}{\|b\|_{\infty} + \|x\|_{\infty} \|A\|_{\infty}}$, i.e., the normwise backward error.
Input Arguments :
spmat
: the input matrix.b
: the right-hand side(s).x
: the solution vector(s).nrm
: the computed norm(s).transp
: whether to use A, Aᵀ or Aᴴ. Can be either't'
,'c'
or'n'
.
QRMumps.qrm_residual_norm
— Functionnrm = qrm_residual_norm(spmat, b, x; transp='n')
QRMumps.qrm_residual_orth!
— Functionqrm_residual_orth!(spmat, r, nrm; transp='n')
Computes the quantity $\frac{\|A^T r\|_2}{\|r\|_2}$ which can be used to evaluate the quality of the solution of a least squares problem.
Input Arguments :
spmat
: the input matrix.r
: the residual(s).nrm
: the computed norm(s).transp
: whether to use A, Aᵀ or Aᴴ. Can be either't'
,'c'
or'n'
.
QRMumps.qrm_residual_orth
— Functionnrm = qrm_residual_orth(spmat, r; transp='n')
QRMumps.qrm_set
— Functionqrm_set(str, val)
+qrm_set(spfct, str, val)
Set control parameters that define the behavior of qr_mumps
.
Input Arguments :
spfct
: a sparse factorization object of typeqrm_spfct
.str
: a string describing the parameter to set.val
: the parameter value.
QRMumps.qrm_get
— Functionval = qrm_get(str)
+val = qrm_get(spfct, str)
Returns the value of a control parameter or an information parameter.
Input Arguments :
spfct
: a sparse factorization object of typeqrm_spfct
.str
: a string describing the parameter to get.