gstrf(3P) Sun Performance Library gstrf(3P)NAME
gstrf: cgstrf, dgstrf, sgstrf, zgstrf - computes an LU factorization of
a general sparse m-by-n matrix A using partial pivoting with row inter‐
changes.
SYNOPSIS
#include <sunperf.h>
void sgstrf(superlu_options_t *options, SuperMatrix *A, float drop_tol,
int relax, int panel_size, int *etree, void *work, int lwork,
int *perm_c, int *perm_r, SuperMatrix *L, SuperMatrix *U, Super‐
LUStat_t *stat, int *info)
void dgstrf(superlu_options_t *options, SuperMatrix *A, double
drop_tol, int relax, int panel_size, int *etree, void *work, int
lwork, int *perm_c, int *perm_r, SuperMatrix *L, SuperMatrix *U,
SuperLUStat_t *stat, int *info)
void cgstrf(superlu_options_t *options, SuperMatrix *A, double
drop_tol, int relax, int panel_size, int *etree, void *work, int
lwork, int *perm_c, int *perm_r, SuperMatrix *L, SuperMatrix *U,
SuperLUStat_t *stat, int *info)
void zgstrf(superlu_options_t *options, SuperMatrix *A, double
drop_tol, int relax, int panel_size, int *etree, void *work, int
lwork, int *perm_c, int *perm_r, SuperMatrix *L, SuperMatrix *U,
SuperLUStat_t *stat, int *info)
void sgstrf_64(superlu_options_t_64 *options, SuperMatrix_64 *A, float
drop_tol, long relax, long panel_size, long *etree, void *work,
long lwork, long *perm_c, long *perm_r, SuperMatrix_64 *L,
SuperMatrix_64 *U, SuperLUStat_t_64 *stat, long *info)
void dgstrf_64(superlu_options_t_64 *options, SuperMatrix_64 *A, double
drop_tol, long relax, long panel_size, long *etree, void *work,
long lwork, long *perm_c, long *perm_r, SuperMatrix_64 *L,
SuperMatrix_64 *U, SuperLUStat_t_64 *stat, long *info)
void cgstrf_64(superlu_options_t_64 *options, SuperMatrix_64 *A, float
drop_tol, long relax, long panel_size, long *etree, void *work,
long lwork, long *perm_c, long *perm_r, SuperMatrix_64 *L,
SuperMatrix_64 *U, SuperLUStat_t_64 *stat, long *info)
void zgstrf_64(superlu_options_t_64 *options, SuperMatrix_64 *A, double
drop_tol, long relax, long panel_size, long *etree, void *work,
long lwork, long *perm_c, long *perm_r, SuperMatrix_64 *L,
SuperMatrix_64 *U, SuperLUStat_t_64 *stat, long *info)
PURPOSE
gstrf computes an LU factorization of a general sparse m-by-n matrix A
using partial pivoting with row interchanges. The factorization has
the form
Pr * A = L * U
where Pr is a row permutation matrix, L is lower triangular with unit
diagonal elements (lower trapezoidal if A->nrow > A->ncol), and U is
upper triangular (upper trapezoidal if A->nrow < A->ncol).
ARGUMENTS
superlu_options_t *options (input)
The structure that defines the input parameters to control how
the LU decomposition will be performed.
SuperMatrix *A (input)
Original matrix A, permuted by columns, of dimension (A->nrow,
A->ncol). The type of A can be:
Stype = SLU_NC; Dtype = SLU_S; Mtype = SLU_GE.
float drop_tol (input; not used)
int relax (input)
To control degree of relaxing supernodes. If the number of nodes
(columns) in a subtree of the elimination tree is less than
relax, this subtree is considered as one supernode, regardless
of the row structures of those columns.
int panel_size (input)
A panel consists of at most panel_size consecutive columns.
int *etree (input) An array of size (A->ncol) that contains the elimi‐
nation tree of transpose(A)*A.
Note: etree is a vector of parent pointers for a forest whose
vertices are the integers 0 to A->ncol-1; etree[root]==A->ncol.
On input, the columns of A should be permuted so that the etree
is in a certain postorder.
void *work (input/output)
User-supplied work space and space for the output data struc‐
tures. of size lwork (in bytes). Not referenced if lwork = 0.
int lwork (input)
Specifies the size of work array in bytes.
= 0: allocate space internally by system malloc
> 0: use user-supplied work array of length lwork in bytes,
returns error if space runs out.
= -1: the routine guesses the amount of space needed without per‐
forming the factorization, and returns it in info; no other
side effects.
int *perm_c (input)
Column permutation vector of size (A->ncol) which defines the
permutation matrix Pc. perm_c[i] = j means column i of A is in
position j in A*Pc. When searching for diagonal, perm_c[*] is
applied to the row subscripts of A, so that diagonal threshold
pivoting can find the diagonal of A, rather than that of A*Pc.
int *perm_r (input/output)
Row permutation vector of size (A->nrow) which defines the per‐
mutation matrix Pr. perm_r[i] = j means row i of A is in posi‐
tion j in Pr*A. If options->Fact = SamePattern_SameRowPerm, the
pivoting routine will try to use the input perm_r, unless a cer‐
tain threshold criterion is violated. In that case, perm_r is
overwritten by a new permutation determined by partial pivoting
or diagonal threshold pivoting.
Otherwise, perm_r is output argument.
SuperMatrix *L (output)
The factor L from the factorization Pr*A=L*U. It uses com‐
pressed row subscripts storage for supernodes, i.e., L has
types: Stype = SLU_SC, Dtype = SLU_S, Mtype = SLU_TRLU
SuperMatrix *U (output)
The factor U from the factorization Pr*A*Pc=L*U. It uses col‐
umn-wise storage scheme, i.e., U has types: Stype = SLU_NC,
Dtype = SLU_S, Mtype = SLU_TRU.
SuperLUStat_t *stat (output)
Records the statistics on runtime and floating-point operation
count.
int *info (output)
= 0:
successful exit
< 0: if info = -i, the i-th argument had an illegal value
> 0: if info = i, and i is
<= A->ncol: U(i,i) is exactly zero. The factorization has
been completed, but the factor U is exactly sin‐
gular, and division by zero will occur if it is
used to solve a system of equations.
> A->ncol: number of bytes allocated when memory allocation
failure occurred, plus A->ncol. If lwork = -1, it
is the estimated amount of space needed, plus
A->ncol.
COPYRIGHT
Copyright (c) 2003, The Regents of the University of California,
through Lawrence Berkeley National Laboratory (subject to receipt of
any required approvals from U.S. Dept. of Energy)
SEE ALSO
SuperMatrix
set_default_options
StatInit
StatFree
http://crd.lbl.gov/~xiaoye/SuperLU/
James W. Demmel, Stanley C. Eisenstat, John R. Gilbert, Xiaoye S. Li
and Joseph W. H. Liu, "A supernodal approach to sparse partial pivot‐
ing", SIAM J. Matrix Analysis and Applications, Vol. 20, Num. 3, 1999,
pp. 720-755.
6 Mar 2009 gstrf(3P)
