Algorithm 8xx: COLAMD, a column
approximate minimum degree ordering
Timothy A. Davis t John R. Gilbert '
Stefan I. Larimore s Esmond G. Ng
October 16, 2000
Technical Report TR-00-006. Department of Computer and Information
Science and Engineering, University of Florida. October, 2000.
Two codes are discussed, colamd and symamd, that compute ap-
proximate minimum degree orderings for sparse matrices in two con-
texts: (1) sparse partial pivoting, which requires a sparsity preserv-
ing column pre-ordering prior to numerical factorization, (2) sparse
C'l. .!-lI: factorization, which requires a symmetric permutation of
both the rows and columns of the matrix being factorized. These
orderings are computed by colamd and symamd, respectively. The or-
dering from colamd is also suitable for sparse QR factorization, and
the factorization of matrices of the form ATA and AAT, such as
*This work was supported in part by the National Science Foundation under grant
number DMS-9803599; in part by the Director, Office of Science, Division of Mathematical,
Information, and Computational Sciences of the U.S. Department of Energy under contract
number DE-AC03-7'.;.I-II I I", and in part by DARPA under contract DABT63-95-C-0087.
tComputer and Info. Sci. and Eng. Dept., University of Florida, Gainesville, FL, USA.
e-mail: firstname.lastname@example.org. http://www.cise.ufl.edu/~davis.
Xerox Palo Alto Research Center, 3333 Coyote Hill Road, Palo Alto, CA 94304-1314.
e-mail: gilbert @parc.xerox.com.
WMicrosoft, Inc. e-mail: email@example.com.
Lawrence Berkeley National Laboratory, One Cyclotron Road, Mail Stop 50F, Berke-
ley, CA -.'Il7 e-mail: EGNg@lbl.gov.
those that arise in least-squares problems and interior point methods
for linear programming problems. The two routines are available both
in Matlab and C-callable forms. They appear as built-in routines in
Matlab Version 6.0.
Categories and Subject Descriptors: G.1.3 [Numerical Analysis]: Numer-
ical Linear Algebra -linear si,;. ii,- (direct methods), sparse and very r'',.
s;,;-l. ,;- G.4 [\I ih.! ii, s of Computing]: Mathematical Software -algo-
rithm Oi.f.il.'-. eff. ";. 1
General terms: Algorithms, Experimentation, Performance
Keywords: sparse unsymmetric matrices, linear equations, ordering meth-
Sparse partial pivoting methods compute the factorization PAQ = LU by
first finding a column ordering Q [3, 4, 5]. The column ordering Q is selected
without regard to the numerical values. The row permutation P is found via
standard partial pivoting, without regard to sparsity. The goal is to find Q
to limit the worst-case fill-in, regardless of how P is subsequently chosen.
Such an ordering Q also limits the fill-in in the Cholesky factorization of
the matrix (AQ)T(AQ) as compared to the unpermuted matrix ATA. The
matrix ATA is not constructed by our ordering methods, however. Sparse
partial pivoting is used extensively in Matlab, by both lu and the matrix
division operators \ and /. The methods used by colamd and symamd are
discussed in a companion paper .
2 colamd: a column ordering algorithm
Colamd computes a column ordering Q, given the nonzero pattern of the
sparse m-by\-, matrix A. It is based on an approximate minimum degree
method . The code can be used in two contexts: as a Matlab mexFunction,
and as a C-callable routine. In Matlab, the usage is
Q = colamd (A)
where A is an m-b\i-, Matlab sparse matrix. The permutation Q is returned
as a size n integer vector. The permuted matrix AQ can be computed
in Matlab as A (:,Q). There is an optional input argument that modifies
how colamd treats rows and columns with iii ,i: nonzero entries, and an
optional output argument that gives statistics on the ordering. The Matlab
colamd function first calls the colamd. c code via the colamdmex.c routine,
and then computes a column elimination tree post-ordering, via Matlab's
built-in coletree function.
3 Symamd: a symmetric ordering algorithm
A symmetric permutation PAPT is typically performed prior to sparse Cholesky
factorization to limit the fill-in in L. This can be computed directly (as in
) or it can be derived from a column ordering method such as colamd. The
symamd algorithm first constructs a matrix M such that the nonzero pattern
of MTM is the same as the pattern of A, and then orders the columns of M
4 Contents of the colamd package
The colamd package consists of the following files and routines:
1. Matlab routines and drivers:
colamd.m: The Matlab-callable colamd routine. This provides
help information (via typing help colamd inside Matlab). It
checks the arguments and calls colamdmex.c.
colamdmex. c: The Matlab mexFunction for interfacing Matlab to
the colamd. c computational kernel.
symamd.m: The Matlab-callable symamd routine. This provides
help information (via help symamd). It calls symamdmex. c.
symamdmex. c: The Matlab interface for the symamd routine.
2. C-callable routines and drivers:
The following user-callable routines are all located in the file colamd. c,
with required definitions in colamd. h. They contain no Matlab-specific
code, so '1:, v can be used in any ANSI C environment. The call-
ing sequence of each user-callable routine is fully documented in the
colamd.c file. These include:
colamd_recommended: Returns the recommended size of the work-
ing array used by colamd. Also available as a macro COLAMD_RECOMMENDED
colamd_set_defaults: Sets default parameters for colamd and
colamd: The primary column ordering kernel. The sparse input
matrix A is in a compressed-column format, such as that used by
symamd: The symmetric ordering routine. This sets up a matrix
M and then calls colamd.
colamd_report: Prints the error status and statistics for colamd.
symamd_report: Prints the error status and statistics for symamd.
3. Testing environment:
Two files, colamd_demo.m and startup.m, provide a simple demon-
stration of colamd and symamd within Matlab. Simply starting Matlab
within the colamd directory will compile the mexFunctions and run a
simple example. A main program in C, colamd_example. c, shows how
to call colamd, and tests its use.
4. Support files:
We provide a Makefile for compiling an example main program (colamd_example. c)
and the Matlab mexFunctions, colamdmex. c and symamdmex.c.
The colamd and symamd routines are written in ANSI/ISO C, with Matlab-
callable interfaces. Version 2.0 of the code is freely available from the follow-
1. University of Florida, http://www.cise.ufl. edu/research/sparse.
2. Netlib, http://www.netlib. org/linalg/colamd/.
3. The MathWorks, Inc., for user-contributed contributions to Matlab,
http://www.mathworks.com. Colamd and symamd are built-in func-
tions in Matlab Version 6.0.
4. The collected algorithms of the AC'\ I, as Algorithm 8xx.
 P. R. Amestoy, T. A. Davis, and I. S. Duff. An approximate minimum
degree ordering algorithm. SIAM J. Matrix Anal. Applic., 17(4):886-905,
 T. A. Davis, J. R. Gilbert, S. I. Larimore, and E. G. Ng. A column
approximate minimum degree ordering algorithm. Technical Report TR-
00-005, Univ. of Florida, CISE Department, Gainesville, FL, October
2000. (submitted to AC'\ Trans. on Mathematical Software).
 J. W. Demmel, S. C. Eisenstat, J. R. Gilbert, X. S. Li, and J. W. H. Liu.
A supernodal approach to sparse partial pivoting. SIAM J. Matrix Anal.
Applic., 20(3):720-755, 1999.
 J. R. Gilbert, C. Moler, and R. Schreiber. Sparse matrices in MATLAB:
design and implementation. SIAM J. Matrix Anal. Applic., 13(1):333
 J. R. Gilbert and T. Peierls. Sparse partial pivoting in time proportional
to arithmetic operations. SIAM J. Sci. Statist. Comput., 9:862-874, 1988.