Function colamd::symamd

pub fn symamd(
    n: Int,
    a_i: &[Int],
    p: &[Int],
    perm: &mut [Int],
    knobs: Option<[f64; 20]>,
    stats: &mut [Int; 20]
) -> bool

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.

The row indices of the entries in column c of the matrix are held in a_i[(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.

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.

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_i[(p[c])...(p[c+1]-1)]. The first entry, p[0], must be zero, and p[c] <= 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.

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.

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.
stats[1]: (same as `stats[0]`)
stats[2]: number of garbage collections performed.
stats[3]: status code < 0 is an error code.
     > 1 is a warning or notice.

    0: OK. Each column of the input matrix contained
      row indices in increasing order, with no
      duplicates.

    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).

        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.
    -1: A is a null pointer
    -2: p is a null pointer
    -3: (unused, see colamd.go)
    -4:  n is negative
        stats[4]: n
    -5: Number of nonzeros in matrix is negative
        stats[4]: # of nonzeros (p [n]).
    -6: p[0] is nonzero
        stats[4]: p[0]
    -7: (unused)
    -8: A column has a negative number of entries
        stats[4]: column with < 0 entries
        stats[5]: number of entries in col
    -9: A row index is out of bounds
        stats[4]: column with bad row index
        stats[5]: bad row index
        stats[6]: n_row, # of rows of matrix
    -10: Out of memory (unable to allocate temporary
      workspace for M or count arrays using the
      "allocate" routine passed into symamd).