Function colamd::colamd

pub fn colamd(
    n_row: Int,
    n_col: Int,
    a_len: Int,
    a_i: &mut [Int],
    p: &mut [Int],
    knobs: Option<[f64; 20]>,
    stats: &mut [Int; 20]
) -> bool

Computes a column ordering Q of a sparse matrix A such that the LU factorization P(AQ) = LU remains sparse, where P is selected via partial pivoting. The routine can also be viewed as providing a permutation Q such that the Cholesky factorization (AQ)'(AQ) = LL' remains sparse.

Computes a column ordering (Q) of A such that P(AQ)=LU or (AQ)'AQ=LL' have less fill-in and require fewer floating point operations than factorizing the unpermuted matrix A or A'A, respectively.

colamd returns false if n_row or n_col are negative. a_len >= 2*nnz + 6*(n_col+1) + 4*(n_row+1) + n_col. colamd returns false if these conditions are not met.

Note: this restriction makes an modest assumption regarding the size of the two structures. We do, however, guarantee that

a_len >= recommended(nnz, n_row, n_col)

will be sufficient.

a_i is an integer array of size a_len. a_len must be at least as large as the bare minimum value given above, but this is very low, and can result in excessive run time. For best performance, we recommend that a_len be greater than or equal to recommended(nnz, n_row, n_col), which adds nnz/5 to the bare minimum value given above.

On input, 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 be present. However, colamd will work a little faster if both of these conditions are met (colamd puts the matrix into this format, if it finds that the the conditions are not met).

The matrix is 0-based. That is, rows are in the range 0 to n_row-1, and columns are in the range 0 to n_col-1. Colamd returns false if any row index is out of range.

The contents of a_i are modified during ordering, and are undefined on output.

p is an integer array of size n_col+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_col-1. The value p[n_col] is thus the total number of entries in the pattern of the matrix A. colamd returns false if these conditions are not met.

On output, if colamd returns true, the array p holds the column permutation (Q, for P(AQ)=LU or (AQ)'(AQ)=LL'), where p[0] is the first column index in the new ordering, and p[n_col-1] is the last. That is, p[k] = j means that column j of A is the kth pivot column, in AQ, where k is in the range 0 to n_col-1 (p[0] = j means that column j of A is the first column in AQ).

If colamd returns false, then no permutation is returned, and p is undefined on output.

Statistics on the ordering, and error status:

stats[0]: number of dense or empty rows ignored.
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.
stats[2]: number of garbage collections performed.
    This can be excessively high if a_len is close
    to the minimum required value.
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). 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).
        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: n_row is negative
        stats[4]: n_row
    -4: n_col is negative
        stats[4]: n_col
    -5: number of nonzeros in matrix is negative
        stats[4]: number of nonzeros, p [n_col]
    -6: p[0] is nonzero
        stats[4]: p[0]
    -7: A is too small
        stats[4]: required size
        stats[5]: actual size (a_len)
    -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 matrx
    -10: (unused; see symamd.go)
    -999  (unused; see symamd.go)