zgssvx_8c.html

来自「SuperLU is a general purpose library for」· HTML 代码 · 共 459 行 · 第 1/2 页

               diag(R)*A*diag(C) *inv(diag(C))*X = diag(R)*B
           options->Trans = TRANS:
               (diag(R)*A*diag(C))**T *inv(diag(R))*X = diag(C)*B
           options->Trans = CONJ:
               (diag(R)*A*diag(C))**H *inv(diag(R))*X = diag(C)*B
           Whether or not the system will be equilibrated depends on the
           scaling of the matrix A, but if equilibration is used, A' is
           overwritten by diag(R)*A'*diag(C) and B by diag(R)*B 
           (if trans='N') or diag(C)*B (if trans = 'T' or 'C').</pre><p>
<pre>      2.2. Permute columns of transpose(A) (rows of A), 
           forming transpose(A)*Pc, where Pc is a permutation matrix that 
           usually preserves sparsity.
           For more details of this step, see <a class="el" href="sp__preorder_8c.html">sp_preorder.c</a>.</pre><p>
<pre>      2.3. If options-&gt;Fact != FACTORED, the LU decomposition is used to
           factor the transpose(A) (after equilibration if 
           options-&gt;Fact = YES) as Pr*transpose(A)*Pc = L*U with the
           permutation Pr determined by partial pivoting.</pre><p>
<pre>      2.4. Compute the reciprocal pivot growth factor.</pre><p>
<pre>      2.5. If some U(i,i) = 0, so that U is exactly singular, then the
           routine returns with info = i. Otherwise, the factored form 
           of transpose(A) is used to estimate the condition number of the
           matrix A. If the reciprocal of the condition number
           is less than machine precision, info = A-&gt;nrow+1 is returned as
           a warning, but the routine still goes on to solve for X and
           computes error bounds as described below.</pre><p>
<pre>      2.6. The system of equations is solved for X using the factored form
           of transpose(A).</pre><p>
<pre>      2.7. If options-&gt;IterRefine != NOREFINE, iterative refinement is
           applied to improve the computed solution matrix and calculate
           error bounds and backward error estimates for it.</pre><p>
<pre>      2.8. If equilibration was used, the matrix X is premultiplied by
           diag(C) (if options-&gt;Trans = NOTRANS) or diag(R) 
           (if options-&gt;Trans = TRANS or CONJ) so that it solves the
           original system before equilibration.</pre><p>
<pre>   See <a class="el" href="supermatrix_8h.html">supermatrix.h</a> for the definition of 'SuperMatrix' structure.</pre><p>
<pre> Arguments
 =========</pre><p>
<pre> options (input) superlu_options_t*
         The structure defines the input parameters to control
         how the LU decomposition will be performed and how the
         system will be solved.</pre><p>
<pre> A       (input/output) SuperMatrix*
         Matrix A in A*X=B, of dimension (A-&gt;nrow, A-&gt;ncol). The number
         of the linear equations is A-&gt;nrow. Currently, the type of A can be:
         Stype = SLU_NC or SLU_NR, Dtype = SLU_D, Mtype = SLU_GE.
         In the future, more general A may be handled.</pre><p>
<pre>         On entry, If options-&gt;Fact = FACTORED and equed is not 'N', 
         then A must have been equilibrated by the scaling factors in
         R and/or C.  
         On exit, A is not modified if options-&gt;Equil = NO, or if 
         options-&gt;Equil = YES but equed = 'N' on exit.
         Otherwise, if options-&gt;Equil = YES and equed is not 'N',
         A is scaled as follows:
         If A-&gt;Stype = SLU_NC:
           equed = 'R':  A := diag(R) * A
           equed = 'C':  A := A * diag(C)
           equed = 'B':  A := diag(R) * A * diag(C).
         If A-&gt;Stype = SLU_NR:
           equed = 'R':  transpose(A) := diag(R) * transpose(A)
           equed = 'C':  transpose(A) := transpose(A) * diag(C)
           equed = 'B':  transpose(A) := diag(R) * transpose(A) * diag(C).</pre><p>
<pre> perm_c  (input/output) int*
	   If A-&gt;Stype = SLU_NC, Column permutation vector of size A-&gt;ncol,
         which defines the permutation matrix Pc; perm_c[i] = j means
         column i of A is in position j in A*Pc.
         On exit, perm_c may be overwritten by the product of the input
         perm_c and a permutation that postorders the elimination tree
         of Pc'*A'*A*Pc; perm_c is not changed if the elimination tree
         is already in postorder.</pre><p>
<pre>         If A-&gt;Stype = SLU_NR, column permutation vector of size A-&gt;nrow,
         which describes permutation of columns of transpose(A) 
         (rows of A) as described above.</pre><p>
<pre> perm_r  (input/output) int*
         If A-&gt;Stype = SLU_NC, row permutation vector of size A-&gt;nrow, 
         which defines the permutation matrix Pr, and is determined
         by partial pivoting.  perm_r[i] = j means row i of A is in 
         position j in Pr*A.</pre><p>
<pre>         If A-&gt;Stype = SLU_NR, permutation vector of size A-&gt;ncol, which
         determines permutation of rows of transpose(A)
         (columns of A) as described above.</pre><p>
<pre>         If options-&gt;Fact = SamePattern_SameRowPerm, the pivoting routine
         will try to use the input perm_r, unless a certain 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.</pre><p>
<pre> etree   (input/output) int*,  dimension (A-&gt;ncol)
         Elimination tree of Pc'*A'*A*Pc.
         If options-&gt;Fact != FACTORED and options-&gt;Fact != DOFACT,
         etree is an input argument, otherwise it is an output argument.
         Note: etree is a vector of parent pointers for a forest whose
         vertices are the integers 0 to A-&gt;ncol-1; etree[root]==A-&gt;ncol.</pre><p>
<pre> equed   (input/output) char*
         Specifies the form of equilibration that was done.
         = 'N': No equilibration.
         = 'R': Row equilibration, i.e., A was premultiplied by diag(R).
         = 'C': Column equilibration, i.e., A was postmultiplied by diag(C).
         = 'B': Both row and column equilibration, i.e., A was replaced 
                by diag(R)*A*diag(C).
         If options-&gt;Fact = FACTORED, equed is an input argument,
         otherwise it is an output argument.</pre><p>
<pre> R       (input/output) double*, dimension (A-&gt;nrow)
         The row scale factors for A or transpose(A).
         If equed = 'R' or 'B', A (if A-&gt;Stype = SLU_NC) or transpose(A)
             (if A-&gt;Stype = SLU_NR) is multiplied on the left by diag(R).
         If equed = 'N' or 'C', R is not accessed.
         If options-&gt;Fact = FACTORED, R is an input argument,
             otherwise, R is output.
         If options-&gt;zFact = FACTORED and equed = 'R' or 'B', each element
             of R must be positive.</pre><p>
<pre> C       (input/output) double*, dimension (A-&gt;ncol)
         The column scale factors for A or transpose(A).
         If equed = 'C' or 'B', A (if A-&gt;Stype = SLU_NC) or transpose(A)
             (if A-&gt;Stype = SLU_NR) is multiplied on the right by diag(C).
         If equed = 'N' or 'R', C is not accessed.
         If options-&gt;Fact = FACTORED, C is an input argument,
             otherwise, C is output.
         If options-&gt;Fact = FACTORED and equed = 'C' or 'B', each element
             of C must be positive.</pre><p>
<pre> L       (output) SuperMatrix*
	   The factor L from the factorization
             Pr*A*Pc=L*U              (if A-&gt;Stype SLU_= NC) or
             Pr*transpose(A)*Pc=L*U   (if A-&gt;Stype = SLU_NR).
         Uses compressed row subscripts storage for supernodes, i.e.,
         L has types: Stype = SLU_SC, Dtype = SLU_Z, Mtype = SLU_TRLU.</pre><p>
<pre> U       (output) SuperMatrix*
	   The factor U from the factorization
             Pr*A*Pc=L*U              (if A-&gt;Stype = SLU_NC) or
             Pr*transpose(A)*Pc=L*U   (if A-&gt;Stype = SLU_NR).
         Uses column-wise storage scheme, i.e., U has types:
         Stype = SLU_NC, Dtype = SLU_Z, Mtype = SLU_TRU.</pre><p>
<pre> work    (workspace/output) void*, size (lwork) (in bytes)
         User supplied workspace, should be large enough
         to hold data structures for factors L and U.
         On exit, if fact is not 'F', L and U point to this array.</pre><p>
<pre> lwork   (input) int
         Specifies the size of work array in bytes.
         = 0:  allocate space internally by system malloc;
         &gt; 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
               performing the factorization, and returns it in
               mem_usage-&gt;total_needed; no other side effects.</pre><p>
<pre>         See argument 'mem_usage' for memory usage statistics.</pre><p>
<pre> B       (input/output) SuperMatrix*
         B has types: Stype = SLU_DN, Dtype = SLU_Z, Mtype = SLU_GE.
         On entry, the right hand side matrix.
         If B-&gt;ncol = 0, only LU decomposition is performed, the triangular
                         solve is skipped.
         On exit,
            if equed = 'N', B is not modified; otherwise
            if A-&gt;Stype = SLU_NC:
               if options-&gt;Trans = NOTRANS and equed = 'R' or 'B',
                  B is overwritten by diag(R)*B;
               if options-&gt;Trans = TRANS or CONJ and equed = 'C' of 'B',
                  B is overwritten by diag(C)*B;
            if A-&gt;Stype = SLU_NR:
               if options-&gt;Trans = NOTRANS and equed = 'C' or 'B',
                  B is overwritten by diag(C)*B;
               if options-&gt;Trans = TRANS or CONJ and equed = 'R' of 'B',
                  B is overwritten by diag(R)*B.</pre><p>
<pre> X       (output) SuperMatrix*
         X has types: Stype = SLU_DN, Dtype = SLU_Z, Mtype = SLU_GE. 
         If info = 0 or info = A-&gt;ncol+1, X contains the solution matrix
         to the original system of equations. Note that A and B are modified
         on exit if equed is not 'N', and the solution to the equilibrated
         system is inv(diag(C))*X if options-&gt;Trans = NOTRANS and
         equed = 'C' or 'B', or inv(diag(R))*X if options-&gt;Trans = 'T' or 'C'
         and equed = 'R' or 'B'.</pre><p>
<pre> recip_pivot_growth (output) double*
         The reciprocal pivot growth factor max_j( norm(A_j)/norm(U_j) ).
         The infinity norm is used. If recip_pivot_growth is much less
         than 1, the stability of the LU factorization could be poor.</pre><p>
<pre> rcond   (output) double*
         The estimate of the reciprocal condition number of the matrix A
         after equilibration (if done). If rcond is less than the machine
         precision (in particular, if rcond = 0), the matrix is singular
         to working precision. This condition is indicated by a return
         code of info &gt; 0.</pre><p>
<pre> FERR    (output) double*, dimension (B-&gt;ncol)   
         The estimated forward error bound for each solution vector   
         X(j) (the j-th column of the solution matrix X).   
         If XTRUE is the true solution corresponding to X(j), FERR(j) 
         is an estimated upper bound for the magnitude of the largest 
         element in (X(j) - XTRUE) divided by the magnitude of the   
         largest element in X(j).  The estimate is as reliable as   
         the estimate for RCOND, and is almost always a slight   
         overestimate of the true error.
         If options-&gt;IterRefine = NOREFINE, ferr = 1.0.</pre><p>
<pre> BERR    (output) double*, dimension (B-&gt;ncol)
         The componentwise relative backward error of each solution   
         vector X(j) (i.e., the smallest relative change in   
         any element of A or B that makes X(j) an exact solution).
         If options-&gt;IterRefine = NOREFINE, berr = 1.0.</pre><p>
<pre> mem_usage (output) mem_usage_t*
         Record the memory usage statistics, consisting of following fields:<ul>
<li>for_lu (float)
           The amount of space used in bytes for L data structures.</li><li>total_needed (float)
           The amount of space needed in bytes to perform factorization.</li><li>expansions (int)
           The number of memory expansions during the LU factorization.</li></ul>
</pre><p>
<pre> stat   (output) SuperLUStat_t*
        Record the statistics on runtime and floating-point operation count.
        See util.h for the definition of 'SuperLUStat_t'.</pre><p>
<pre> info    (output) int*
         = 0: successful exit   
         &lt; 0: if info = -i, the i-th argument had an illegal value   
         &gt; 0: if info = i, and i is   
              &lt;= A-&gt;ncol: U(i,i) is exactly zero. The factorization has   
                    been completed, but the factor U is exactly   
                    singular, so the solution and error bounds   
                    could not be computed.   
              = A-&gt;ncol+1: U is nonsingular, but RCOND is less than machine
                    precision, meaning that the matrix is singular to
                    working precision. Nevertheless, the solution and
                    error bounds are computed because there are a number
                    of situations where the computed solution can be more
                    accurate than the value of RCOND would suggest.   
              &gt; A-&gt;ncol+1: number of bytes allocated when memory allocation
                    failure occurred, plus A-&gt;ncol.
 </pre>     </td>
  </tr>
</table>
<hr size="1"><address style="align: right;"><small>Generated on Fri Aug 1 22:40:41 2008 for SuperLU by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.4.6 </small></address>
</body>
</html>