colamd_8c.html

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

<pre>		stats [0]:  number of dense or empty rows ignored.</pre><p>
<pre>		stats [1]:  number of dense or empty columns ignored (and
				ordered last in the output permutation p)
				Note that a row can become "empty" if it
				contains only "dense" and/or "empty" columns,
				and similarly a column can become "empty" if it
				only contains "dense" and/or "empty" rows.</pre><p>
<pre>		stats [2]:  number of garbage collections performed.
				This can be excessively high if Alen is close
				to the minimum required value.</pre><p>
<pre>		stats [3]:  status code.  &lt; 0 is an error code.
			    &gt; 1 is a warning or notice.</pre><p>
<pre>			0	OK.  Each column of the input matrix contained
				row indices in increasing order, with no
				duplicates.</pre><p>
<pre>			1	OK, but columns of input matrix were jumbled
				(unsorted columns or duplicate entries).  Colamd
				had to do some extra work to sort the matrix
				first and remove duplicate entries, but it
				still was able to return a valid permutation
				(return value of colamd was TRUE).</pre><p>
<pre>					stats [4]: highest numbered column that
						is unsorted or has duplicate
						entries.
					stats [5]: last seen duplicate or
						unsorted row index.
					stats [6]: number of duplicate or
						unsorted row indices.</pre><p>
<pre>			-1	A is a null pointer</pre><p>
<pre>			-2	p is a null pointer</pre><p>
<pre>			-3 	n_row is negative</pre><p>
<pre>					stats [4]: n_row</pre><p>
<pre>			-4	n_col is negative</pre><p>
<pre>					stats [4]: n_col</pre><p>
<pre>			-5	number of nonzeros in matrix is negative</pre><p>
<pre>					stats [4]: number of nonzeros, p [n_col]</pre><p>
<pre>			-6	p [0] is nonzero</pre><p>
<pre>					stats [4]: p [0]</pre><p>
<pre>			-7	A is too small</pre><p>
<pre>					stats [4]: required size
					stats [5]: actual size (Alen)</pre><p>
<pre>			-8	a column has a negative number of entries</pre><p>
<pre>					stats [4]: column with &lt; 0 entries
					stats [5]: number of entries in col</pre><p>
<pre>			-9	a row index is out of bounds</pre><p>
<pre>					stats [4]: column with bad row index
					stats [5]: bad row index
					stats [6]: n_row, # of rows of matrx</pre><p>
<pre>			-10	(unused; see symamd.c)</pre><p>
<pre>			-999	(unused; see symamd.c)</pre><p>
<pre>		Future versions may return more statistics in the stats array.</pre><p>
<pre>	Example:</pre><p>
<pre>	    See <a href="http://www.cise.ufl.edu/research/sparse/colamd/example.c">http://www.cise.ufl.edu/research/sparse/colamd/example.c</a>
	    for a complete example.</pre><p>
<pre>	    To order the columns of a 5-by-4 matrix with 11 nonzero entries in
	    the following nonzero pattern</pre><p>
<pre>	    	x 0 x 0
		x 0 x x
		0 x x 0
		0 0 x x
		x x 0 0</pre><p>
<pre>	    with default knobs and no output statistics, do the following:</pre><p>
<pre>		include "colamd.h"
		define ALEN COLAMD_RECOMMENDED (11, 5, 4)
		int A [ALEN] = {1, 2, 5, 3, 5, 1, 2, 3, 4, 2, 4} ;
		int p [ ] = {0, 3, 5, 9, 11} ;
		int stats [COLAMD_STATS] ;
		colamd (5, 4, ALEN, A, p, (double *) NULL, stats) ;</pre><p>
<pre>	    The permutation is returned in the array p, and A is destroyed.</pre><p>
<pre>    ----------------------------------------------------------------------------
    symamd:
    ----------------------------------------------------------------------------</pre><p>
<pre>	C syntax:</pre><p>
<pre>	    include "colamd.h"
	    int symamd (int n, int *A, int *p, int *perm,
	    	double knobs [COLAMD_KNOBS], int stats [COLAMD_STATS],
		void (*allocate) (size_t, size_t), void (*release) (void *)) ;</pre><p>
<pre>	Purpose:</pre><p>
<pre>    	    The symamd routine computes an ordering P of a symmetric sparse
	    matrix A such that the Cholesky factorization PAP' = LL' remains
	    sparse.  It is based on a column ordering of a matrix M constructed
	    so that the nonzero pattern of M'M is the same as A.  The matrix A
	    is assumed to be symmetric; only the strictly lower triangular part
	    is accessed.  You must pass your selected memory allocator (usually
	    calloc/free or mxCalloc/mxFree) to symamd, for it to allocate
	    memory for the temporary matrix M.</pre><p>
<pre>	Returns:</pre><p>
<pre>	    TRUE (1) if successful, FALSE (0) otherwise.</pre><p>
<pre>	Arguments:</pre><p>
<pre>	    int n ;		Input argument.</pre><p>
<pre>	    	Number of rows and columns in the symmetrix matrix A.
		Restriction:  n &gt;= 0.
		Symamd returns FALSE if n is negative.</pre><p>
<pre>	    int A [nnz] ;	Input argument.</pre><p>
<pre>	    	A is an integer array of size nnz, where nnz = p [n].</pre><p>
<pre>		The row indices of the entries in column c of the matrix are
		held in A [(p [c]) ... (p [c+1]-1)].  The row indices in a
		given column c need not be in ascending order, and duplicate
		row indices may be present.  However, symamd will run faster
		if the columns are in sorted order with no duplicate entries.</pre><p>
<pre>		The matrix is 0-based.  That is, rows are in the range 0 to
		n-1, and columns are in the range 0 to n-1.  Symamd
		returns FALSE if any row index is out of range.</pre><p>
<pre>		The contents of A are not modified.</pre><p>
<pre>	    int p [n+1] ;   	Input argument.</pre><p>
<pre>		p is an integer array of size n+1.  On input, it holds the
		"pointers" for the column form of the matrix A.  Column c of
		the matrix A is held in A [(p [c]) ... (p [c+1]-1)].  The first
		entry, p [0], must be zero, and p [c] &lt;= p [c+1] must hold
		for all c in the range 0 to n-1.  The value p [n] is
		thus the total number of entries in the pattern of the matrix A.
		Symamd returns FALSE if these conditions are not met.</pre><p>
<pre>		The contents of p are not modified.</pre><p>
<pre>	    int perm [n+1] ;   	Output argument.</pre><p>
<pre>		On output, if symamd returns TRUE, the array perm holds the
		permutation P, where perm [0] is the first index in the new
		ordering, and perm [n-1] is the last.  That is, perm [k] = j
		means that row and column j of A is the kth column in PAP',
		where k is in the range 0 to n-1 (perm [0] = j means
		that row and column j of A are the first row and column in
		PAP').  The array is used as a workspace during the ordering,
		which is why it must be of length n+1, not just n.</pre><p>
<pre>	    double knobs [COLAMD_KNOBS] ;	Input argument.</pre><p>
<pre>		See colamd_set_defaults for a description.</pre><p>
<pre>	    int stats [COLAMD_STATS] ;		Output argument.</pre><p>
<pre>		Statistics on the ordering, and error status.
		See <a class="el" href="colamd_8h.html">colamd.h</a> for related definitions.
		Symamd returns FALSE if stats is not present.</pre><p>
<pre>		stats [0]:  number of dense or empty row and columns ignored
				(and ordered last in the output permutation 
				perm).  Note that a row/column can become
				"empty" if it contains only "dense" and/or
				"empty" columns/rows.</pre><p>
<pre>		stats [1]:  (same as stats [0])</pre><p>
<pre>		stats [2]:  number of garbage collections performed.</pre><p>
<pre>		stats [3]:  status code.  &lt; 0 is an error code.
			    &gt; 1 is a warning or notice.</pre><p>
<pre>			0	OK.  Each column of the input matrix contained
				row indices in increasing order, with no
				duplicates.</pre><p>
<pre>			1	OK, but columns of input matrix were jumbled
				(unsorted columns or duplicate entries).  Symamd
				had to do some extra work to sort the matrix
				first and remove duplicate entries, but it
				still was able to return a valid permutation
				(return value of symamd was TRUE).</pre><p>
<pre>					stats [4]: highest numbered column that
						is unsorted or has duplicate
						entries.
					stats [5]: last seen duplicate or
						unsorted row index.
					stats [6]: number of duplicate or
						unsorted row indices.</pre><p>
<pre>			-1	A is a null pointer</pre><p>
<pre>			-2	p is a null pointer</pre><p>
<pre>			-3	(unused, see <a class="el" href="colamd_8c.html">colamd.c</a>)</pre><p>
<pre>			-4 	n is negative</pre><p>
<pre>					stats [4]: n</pre><p>
<pre>			-5	number of nonzeros in matrix is negative</pre><p>
<pre>					stats [4]: # of nonzeros (p [n]).</pre><p>
<pre>			-6	p [0] is nonzero</pre><p>
<pre>					stats [4]: p [0]</pre><p>
<pre>			-7	(unused)</pre><p>
<pre>			-8	a column has a negative number of entries</pre><p>
<pre>					stats [4]: column with &lt; 0 entries
					stats [5]: number of entries in col</pre><p>
<pre>			-9	a row index is out of bounds</pre><p>
<pre>					stats [4]: column with bad row index
					stats [5]: bad row index
					stats [6]: n_row, # of rows of matrx</pre><p>
<pre>			-10	out of memory (unable to allocate temporary
				workspace for M or count arrays using the
				"allocate" routine passed into symamd).</pre><p>
<pre>			-999	internal error.  colamd failed to order the
				matrix M, when it should have succeeded.  This
				indicates a bug.  If this (and *only* this)
				error code occurs, please contact the authors.
				Don't contact the authors if you get any other
				error code.</pre><p>
<pre>		Future versions may return more statistics in the stats array.</pre><p>
<pre>	    void * (*allocate) (size_t, size_t)</pre><p>
<pre>	    	A pointer to a function providing memory allocation.  The
		allocated memory must be returned initialized to zero.  For a
		C application, this argument should normally be a pointer to
		calloc.  For a MATLAB mexFunction, the routine mxCalloc is
		passed instead.</pre><p>
<pre>	    void (*release) (size_t, size_t)</pre><p>
<pre>	    	A pointer to a function that frees memory allocated by the
		memory allocation routine above.  For a C application, this
		argument should normally be a pointer to free.  For a MATLAB
		mexFunction, the routine mxFree is passed instead.</pre><p>
<pre>    ----------------------------------------------------------------------------
    colamd_report:
    ----------------------------------------------------------------------------</pre><p>
<pre>	C syntax:</pre><p>
<pre>	    include "colamd.h"
	    colamd_report (int stats [COLAMD_STATS]) ;</pre><p>
<pre>	Purpose:</pre><p>
<pre>	    Prints the error status and statistics recorded in the stats
	    array on the standard error output (for a standard C routine)
	    or on the MATLAB output (for a mexFunction).</pre><p>
<pre>	Arguments:</pre><p>
<pre>	    int stats [COLAMD_STATS] ;	Input only.  Statistics from colamd.</pre><p>
<pre>    ----------------------------------------------------------------------------
    symamd_report:
    ----------------------------------------------------------------------------</pre><p>
<pre>	C syntax:</pre><p>
<pre>	    include "colamd.h"
	    symamd_report (int stats [COLAMD_STATS]) ;</pre><p>
<pre>	Purpose:</pre><p>
<pre>	    Prints the error status and statistics recorded in the stats
	    array on the standard error output (for a standard C routine)
	    or on the MATLAB output (for a mexFunction).</pre><p>
<pre>	Arguments:</pre><p>
<pre>	    int stats [COLAMD_STATS] ;	Input only.  Statistics from symamd.</pre><p>
<pre> </pre> <hr><h2>Define Documentation</h2>
<a class="anchor" name="d8beef706da0344be19d59438fcdab6d"></a><!-- doxytag: member="colamd.c::ALIVE" ref="d8beef706da0344be19d59438fcdab6d" args="" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
  <tr>
    <td class="mdRow">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top">#define ALIVE&nbsp;&nbsp;&nbsp;(0)          </td>
        </tr>
      </table>
    </td>
  </tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
    </td>
  </tr>
</table>
<a class="anchor" name="87e006a00875d2e518652108f6cb5790"></a><!-- doxytag: member="colamd.c::ASSERT" ref="87e006a00875d2e518652108f6cb5790" args="(expression)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
  <tr>
    <td class="mdRow">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top">#define ASSERT          </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top">expression&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>          </td>
          <td class="md" valign="top">&nbsp;)&nbsp;</td>
          <td class="md" nowrap>&nbsp;&nbsp;&nbsp;((void) 0)</td>
        </tr>
      </table>
    </td>
  </tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
    </td>
  </tr>
</table>
<a class="anchor" name="50f9ca65904b13f345862cb46d08d84b"></a><!-- doxytag: member="colamd.c::COL_IS_ALIVE" ref="50f9ca65904b13f345862cb46d08d84b" args="(c)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
  <tr>
    <td class="mdRow">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top">#define COL_IS_ALIVE          </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top">c&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>          </td>
          <td class="md" valign="top">&nbsp;)&nbsp;</td>
          <td class="md" nowrap>&nbsp;&nbsp;&nbsp;(Col [c].start &gt;= ALIVE)</td>
        </tr>
      </table>
    </td>
  </tr>
</table>
<table cellspacing="5" cellpadding="0" border="0">
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
    </td>
  </tr>
</table>
<a class="anchor" name="a08664bd5b8133f28dbeedc9a030fc86"></a><!-- doxytag: member="colamd.c::COL_IS_DEAD" ref="a08664bd5b8133f28dbeedc9a030fc86" args="(c)" --><p>
<table class="mdTable" cellpadding="2" cellspacing="0">
  <tr>