The CHOMPACK routines are available as a standard C library.
The two most basic data-structures in CHOMPACK are a cliqueforest, which represents the sparsity pattern of symmetric matrix, and a chordalmatrix which attaches numerical values to a sparsity pattern defined by a cliqueforest.
A clique-forest is created using the cliqueforest_create function.
Creates a cliqueforest from a ccs matrix.
Parameters: |
|
---|---|
Returns: | a status integer CHOMPACK_OK, or CHOMPACK_NOMEMORY. |
A clique-forest is destroyed using the function:
We can create a chordalmatrix for a particular cliqueforest using the routine:
Creates a chordal matrix by projecting a sparse matrix X onto the sparsity pattern defined by the clique-forest F. Elements in X outside the chordal sparsity pattern in F are ignored.
Parameters: |
|
---|---|
Returns: | a chordal matrix object, or NULL if a memory error occured. |
and a chordalmatrix object is destroyed using the routine:
Internally, CHOMPACK does not distinguish between chordal matrices and factors; the user of the library must make that distinction. In the following we will refer to a symmetric chordalmatrix object as a chordal matrix and a factor stored in a chordalmatrix as a chordal factor.
A chordal matrix is converted to ccs format using the routine:
and a chordal factor is converted using the routine:
Finally, a copy of a chordalmatrix is created using the routine:
The CHOMPACK library provides the following computational routines.
Computes a zero fill-in Cholesky factorization
(1)
of a positive definite chordal matrix X.
Parameters: |
|
---|---|
Returns: | CHOMPACK_OK if the factorization was successful, CHOMPACK_FACTORIZATION_ERR if the factorization failed, or CHOMPACK_NOMEMORY. |
Solves a factored set of equations, or multiplies with Cholesky factors.
L contains the factors of a factorization (1) of a positive definite sparse chordal matrix. X is a dense matrix of doubles with the same number of rows as L, stored as a contigious array on column-major-order. On exit, X is overwritten with one of the four matrices in the table.
action | sys |
---|---|
![]() |
0 |
![]() |
1 |
![]() |
2 |
![]() |
3 |
Parameters: |
|
---|
Returns the Cholesky factor of the inverse of the maximum-determinant positive definite completion of a symmetric chordal matrix X, ie, the Cholesky factor of the inverse of the solution of
The inverse has the same sparsity pattern as
and satisfies the nonlinear equation
completion returns the factor in the factorization
.
Parameters: |
|
---|---|
Returns: | chordal factor with the same sparsity pattern as X |
Evaluates the projection of the inverse of the matrix
on the sparsity pattern of
.
Overwrites L with lower-triangular part of
where is a positive definite chordal matrix specified by
its Cholesky factor
.
Parameters: |
|
---|---|
Returns: | CHOMPACK_OK, CHOMPACK_FACTORIZATION_ERR or CHOMPACK_NOMEMORY |
The mapping
is the Hessian of the log-det barrier at a positive definite chordal
matrix , applied to a symmetric chordal matrix
.
The Hessian operator can be factored as
where the mappings on the right hand side are adjoint mappings that map chordal symmetric matrices to chordal symmetric matrices.
The hessian_factor function evaluates these mappings or their inverses for a list of symmetric chordal matrices **U, and overwrites the matrices with the results. The following table lists the possible actions.
Action | adj | inv |
---|---|---|
![]() |
0 | 0 |
![]() |
0 | 1 |
![]() |
1 | 0 |
![]() |
1 | 1 |
The input argument L is the Cholesky factor of ,
as computed by the cholesky function.
The input argument Y is the partial inverse of the inverse of
, as computed by the partial_inv function.
The input argument U is a list of CHOMPACK matrices with the
same sparsity pattern as L and Y.
The matrices can be computed by two calls
hessian_factor(L, Y, U, 0, 0);
hessian_factor(L, Y, U, 1, 0);
The matrices can be computed as
hessian_factor(L, Y, U, 1, 1);
hessian_factor(L, Y, U, 0, 1);
Parameters: |
|
---|
Evaluates
Parameters: |
|
---|
Evaluates
Parameters: |
|
---|
On entry L contains a Cholesky factor of .
On exit, L is overwritten with X.
Returns: | CHOMPACK_OK or CHOMPACK_NOMEMORY |
---|
Returns the inner product
of two symmetric sparse matrices with the same chordal sparsity pattern.
Parameters: |
|
---|
Returns the logarithm of the determinant of a Cholesky factor L.
Parameters: |
|
---|
Sparse matrices are specified in compressed-column-storage using the (ccs) data-structure. For a general nrows by ncols sparse matrix with nnz nonzero entries this means the following. The sparsity pattern and the nonzero values are stored in three fields:
For example, for the matrix
the elements of values, rowind, and colptr are:
A ccs data-structure can be allocated using the routine:
Allocates a nrows times ncols ccs matrix with nnz non-zero elements.
and a ccs structure can be freed with the routine:
A given ccs can be embedded into a chordal sparsity pattern (i.e., it can be triangulated) using the routine:
Parameters: |
|
---|---|
Returns: | a chordal embedding of X as a ccs matrix. |
Additionally, a number of auxilliary routines for ccs matrices are available.
Returns a symmetric permutation where
P is a permutation and A is a square matrix of dimension n.
Parameters: |
|
---|---|
Returns: | a symmetric permutation of the rows and columns of A. |
typedef struct {
void *values; /* value list */
int_t *colptr; /* column pointer list */
int_t *rowind; /* row index list */
int_t nrows, ncols; /* number of rows and columns */
int id; /* not currently used */
} ccs;
number of rows
number of columns
length colptr[ncols] double array with numerical values.
length ncols+1 array with compressed column-indices.
length colptr[ncols] array with row-indices.
included for compatibility with CVXOPT; not currently used.
typedef struct cliqueforest {
int nRoots, nCliques, n;
struct clique **roots, **list, *location;
int_t *p, *ip;
} cliqueforest;
number of clique-trees in the clique-forest
number of cliques in the clique-forest
number of nodes (dimension of the matrix)
array of pointers to each root element
array of pointers to each clique numbers in reverse topological order
permutation used for creating the clique-forst
inverse permutation
used internally by CHOMPACK
typedef struct {
cliqueforest *F;
double **US;
double **SS;
double **UU;
void *F_py;
} chordalmatrix;
clique-forest representing sparsity pattern of matrix
array of matrices corresponding the blocks of the chordal matrix
array of matrices corresponding the blocks of the chordal matrix
array of matrices corresponding the blocks of the chordal matrix
included for compatibility with CVXOPT
The following example computes the partial inverse of the chordal matrix
#include <stdio.h>
#include "chompack.h"
int main() {
int j, k;
double Aval[] = {10.0, 1.0, 10.0, 1.0, 10.0, 1.0, 10.0, 1.0, 10.0};
int_t Acol[] = {0, 2, 4, 6, 8, 9};
int_t Arow[] = {0, 4, 1, 4, 2, 4, 3, 4, 5};
ccs A = { .values = Aval, .colptr = Acol, .rowind = Arow, .nrows = 5, .ncols = 5, 0 };
printf("creating cliquetree\n");
cliqueforest *F;
cliqueforest_create(&F, &A, NULL);
printf("creating chordal matrix\n");
chordalmatrix *X = ccs_to_chordalmatrix (F, &A);
printf("performing factorization\n");
cholesky(X);
printf("computing partial inverse\n");
partial_inv(X);
ccs *Y = chordalmatrix_to_ccs(X);
printf("partial inverse:\n");
for (j=0; j<Y->ncols; j++)
for (k=Y->colptr[j]; k<Y->colptr[j+1]; k++)
printf("(%i,%i): % 3.2e\n", (int)Y->rowind[k], j, ((double *)Y->values)[k]);
chordalmatrix_destroy(X);
cliqueforest_destroy(F);
free_ccs(Y);
return 0;
}