MeatAxe  2.4
Programs for working with modular representations
Matrices over Finite Fields

Detailed Description

In the MeatAxe, a matrix over a finite field is represented by a Matrix_t structure. Matrices can be created in many ways, for example

Matrices that no longer needed must be deleted by calling MatFree(). Matrices can consume large amounts of memory, so it always a good idea to delete a matrix as early as possible.

As with row vectors, row and column indexs are zero-based. For example, in a 3 by 5 matrix the row index runs from 0 to 2 and the column index runs from 0 to 4.

A matrix A with entries (aij) is said to be in echelon form if the following conditions are satisfied:

If a matrix is in echelon form, the column indexes of its pivot elements are called the pivot columns of the matrix. The list of all pivot columns is called the pivot table of the matrix. For a matrix in echelon form the number of rows, Nor, is always less than or equal to the number of columns, Noc. When different from 0, the PivotTable field is a pointer to an array of integers containing first the pivot columns and then the non-pivot columns. This means, the size of the array is always Noc: the first Nor elements contain the pivot columns and the remaining Noc-Nor elements contain the non-pivot columns in arbitrary order.

Data Structures

class  Matrix_t
 A matrix over a finite field. More...
 

Functions

Matrix_tMatAddMul (Matrix_t *dest, const Matrix_t *src, FEL coeff)
 Add a multiple of a matrix. More...
 
Matrix_tMatAdd (Matrix_t *dest, const Matrix_t *src)
 Sum of two matrices. More...
 
int MatClean (Matrix_t *mat, const Matrix_t *sub)
 Clean a matrix. More...
 
int MatCompare (const Matrix_t *a, const Matrix_t *b)
 Compare two matrices If the matrices are equal, the return value is 0. More...
 
int MatCopyRegion (Matrix_t *dest, int destrow, int destcol, const Matrix_t *src, int row1, int col1, int nrows, int ncols)
 Copy a rectangular region of a matrix This function copies a rectangular region of src tp dest. More...
 
int MatIsValid (const Matrix_t *mat)
 Check if the matrix is valid. More...
 
Matrix_tMatAlloc (int field, int nor, int noc)
 Create a new matrix. More...
 
PTR MatGetPtr (const Matrix_t *mat, int row)
 Pointer to a row of a matrix. More...
 
void Mat_DeletePivotTable (Matrix_t *mat)
 Delete the pivot table of a matrix. More...
 
int MatFree (Matrix_t *mat)
 Delete a matrix. More...
 
Matrix_tMatCut (const Matrix_t *src, int row1, int col1, int nrows, int ncols)
 Cut a rectangle out of a matrix. More...
 
Matrix_tMatCutRows (const Matrix_t *src, int row1, int nrows)
 Copy a range of rows of a matrix. More...
 
Matrix_tMatDup (const Matrix_t *src)
 Duplicate a matrix This function creates a copy of an existing matrix. More...
 
int MatEchelonize (Matrix_t *mat)
 Reduce to echelon form This function performs a Gaussian elimination on the matrix |mat|. More...
 
long MatNullity (const Matrix_t *mat)
 Nullity of a matrix. More...
 
long MatNullity__ (Matrix_t *mat)
 Nullity of a matrix. More...
 
Matrix_tMatId (int fl, int nor)
 Identity matrix This function creates an identity matrix with nor nows over GF(fl). More...
 
Matrix_tMatInsert_ (Matrix_t *mat, const Poly_t *pol)
 Insert a matrix into a polynomial Given a square matrix A and a polynomial p over the same field, this functions calculates p(A). More...
 
Matrix_tMatInsert (const Matrix_t *mat, const Poly_t *pol)
 Insert a matrix into a polynomial Given a square matrix A and a polynomial p over the same field, this functions calculates p(A). More...
 
Matrix_tMatInverse (const Matrix_t *mat)
 Inverse of a matrix This function calculates the inverse of a matrix. More...
 
Matrix_tMatMul (Matrix_t *dest, const Matrix_t *src)
 Multiply matrices This function multiplies dest from the right by src. More...
 
Matrix_tMatNullSpace_ (Matrix_t *mat, int flags)
 Null-space of a matrix This function calculates the null-space of a matrix. More...
 
Matrix_tMatNullSpace (const Matrix_t *mat)
 Null-space of a matrix This function calculates the null-space of a matrix. More...
 
Matrix_tMatNullSpace__ (Matrix_t *mat)
 Null-space of a matrix This function calculates the null-space of a matrix and deletes the original matrix. More...
 
int MatOrder (const Matrix_t *mat)
 Order of a matrix. More...
 
int MatPivotize (Matrix_t *mat)
 Reduce to echelon form. More...
 
void MatPrint (const char *name, const Matrix_t *m)
 Print a matrix on stdout. More...
 
Matrix_tMatPower (const Matrix_t *mat, long n)
 Power of a matrix. More...
 
Matrix_tMatRead (FILE *f)
 Read a matrix from a file. More...
 
Matrix_tMatLoad (const char *fn)
 Read a matrix from a file. More...
 
Matrix_tMatTransposed (const Matrix_t *src)
 Transpose a matrix. More...
 
FEL MatTrace (const Matrix_t *mat)
 Trace of a Matrix. More...
 
int MatWrite (const Matrix_t *mat, FILE *f)
 Write a matrix to a file. More...
 
int MatSave (const Matrix_t *mat, const char *fn)
 Write a matrix to a file. More...
 
Matrix_tMatMulScalar (Matrix_t *dest, FEL coeff)
 Multiply a Matrix by a Constant. More...
 
int StablePower_ (Matrix_t *mat, int *pwr, Matrix_t **ker)
 Stable power of a matrix. More...
 
int StablePower (const Matrix_t *mat, int *pwr, Matrix_t **ker)
 Stable power of a matrix. More...
 

Function Documentation

void Mat_DeletePivotTable ( Matrix_t mat)

Delete the pivot table of a matrix.

This function deletes the pivot table associated with a matrix. It is used internally, applications should never call this function directly.

Parameters
matPointer to the matrix.
Matrix_t* MatAdd ( Matrix_t dest,
const Matrix_t src 
)

Sum of two matrices.

This function adds src to dest, overwriteing the previos value in dest. The matrices must be over the same field and have the same dimensions.

Returns
dest on success, 0 on error.
Matrix_t* MatAddMul ( Matrix_t dest,
const Matrix_t src,
FEL  coeff 
)

Add a multiple of a matrix.

This function adds a multiple of a matrix to another matrix. The matrices must be compatible for addition. |MatAddMul()| handles special cases (|coeff| equals 0 or 1) in an intelligent way, so there is no need for the caller to do this.

Parameters
destMatrix to add to.
srcMatrix to add.
coeffCoefficient.
Returns
The function returns |dest|, or |NULL| on error.
Matrix_t* MatAlloc ( int  field,
int  nor,
int  noc 
)

Create a new matrix.

This function creates a new matrix with given dimensions over a given field.

Attention
To destroy a matrix, use MatFree(), not SysFree().
Parameters
fieldField order.
norNumber of rows.
nocNumber of columns.
Returns
Pointer to the new matrix or 0 on error.
int MatClean ( Matrix_t mat,
const Matrix_t sub 
)

Clean a matrix.

This function "cleans" a matrix with a space, i.e., it adds suitable linear combinations of the rows in sub to the rows of mat such that all pivot columns in mat are zero. Both matrices must be over the same field and have the same number of colums. The second matrix, sub, must be in echelon form. The cleaned matrix is reduced to echelon form.

Returns
Rank of the cleaned matrix, or -1 on error.
int MatCompare ( const Matrix_t a,
const Matrix_t b 
)

Compare two matrices If the matrices are equal, the return value is 0.

Otherwise the return value is positive, if a is "greater" than b and negative, if a is "less" than b. The ordering matrices is defined as follows:

  • If the matrices are over different fields, the matrix over the smaller field is smaller.
  • Otherwise, if the matrices have different number of columns, the matrix with the smaller number of columns is smaller.
  • Otherwise, if the matrices have different number of rows, the matrix with the smaller number of rows is smaller.
  • Otherwise, the relation is determined by the return value of FfCmpRow() on the first row that is not equal in both matrices.

In case an error occurs, the return value is -1. But note that a return value of -1 does not necessarily mean that an error has occured.

Parameters
aFirst matrix.
bSecond matrix.
Returns
0 if the matrices are equal, nonzero otherwise (see description).
int MatCopyRegion ( Matrix_t dest,
int  destrow,
int  destcol,
const Matrix_t src,
int  row1,
int  col1,
int  nrows,
int  ncols 
)

Copy a rectangular region of a matrix This function copies a rectangular region of src tp dest.

The source region is defined by its upper left corner and dimensions, the destination region is specified by its upper left corner and has the same dimensions. Both nrows and ncols can be given as -1. In this case the region extends up to the last row or last column, respectively. The two matrices must be over the same field. Both source and destination region must not exceed the matrices' dimensions. In particular, it is not possible to extend the destination matrix by using MatCopyRegion().

Parameters
destPointer to the destination matrix.
destrowDestination row.
destcolDestination column.
srcPointer to the source matrix.
row1First row in region.
col1First column in region.
nrowsNumber of rows to copy. -1 means as many rows as possible.
ncolsNumber of columns to copy. -1 means as many columns as possible.
Returns
0 on success, -1 on error.
Matrix_t* MatCut ( const Matrix_t src,
int  row1,
int  col1,
int  nrows,
int  ncols 
)

Cut a rectangle out of a matrix.

This function creates a new matrix containing a copy of a rectangular region of the source matrix. The region, defined by row1, col1, nrows and ncols, must not exceed the matrix. However, both nrows and ncols may be -1. In this case the region extends up to the last row or last column, respectivly. For example, to extract the first 10 rows from a matrix independently of the number of columns, you could say

1 MatCut(mat,0,0,10,-1)
See also
MatCopyRegion MatCutRows
Parameters
srcPointer to the matrix.
row1First row in region.
col1First column in region.
nrowsNumber of rows to cut. -1 means as many rows as possible.
ncolsNumber of columns to cut. -1 means as many columns as possible.
Returns
Pointer to a new matrix containing the specified region, or 0 on error.
Matrix_t* MatCutRows ( const Matrix_t src,
int  row1,
int  nrows 
)

Copy a range of rows of a matrix.

This function creates a new matrix containing a range of consecutive rows of the source matrix. The range must now exceed the matrix's dimensions. However, nrows may be given as -1, meaning "up to the last row".

See also
MatCopyRegion MatCutRows
Parameters
srcPointer to the matrix.
row1First row in region.
nrowsNumber of rows to cut. -1 means as many rows as possible.
Returns
A new matrix containing the specified rows of src, or 0 on error.
Matrix_t* MatDup ( const Matrix_t src)

Duplicate a matrix This function creates a copy of an existing matrix.

The caller is responsible for destroying the copy with MatFree() when it is no longer needed.

Returns
A copy of the source Matrix, or 0 on error.
int MatEchelonize ( Matrix_t mat)

Reduce to echelon form This function performs a Gaussian elimination on the matrix |mat|.

On return, |mat| is in semi echelon form and a pivot table has been attatched to the matrix. If the rank of |mat| was smaller than the number of rows, some rows are removed during the process. This function can also be used to rebuild the pivot table after the matrix has been modified.

Parameters
matPointer to the matrix.
Returns
Rank of mat, or -1 on error.
int MatFree ( Matrix_t mat)

Delete a matrix.

This function frees a matrix which has beed created by MatAlloc(). Freeing includes the internal data buffers as well as the Matrix_t structure itself.

Parameters
matPointer to the matrix.
Returns
0 on success, -1 on error.
PTR MatGetPtr ( const Matrix_t mat,
int  row 
)

Pointer to a row of a matrix.

This function returns a pointer to the specified row of a matrix. Row numbers start from 0. The current row size is not changed.

Parameters
matPointer to the matrix.
rowRow index.
Returns
Pointer to the selected row or 0 on error.
Matrix_t* MatId ( int  fl,
int  nor 
)

Identity matrix This function creates an identity matrix with nor nows over GF(fl).

Parameters
flField order.
norNumber of rows.
Returns
Pointer to the matrix, or 0 on error.
See also
MatAlloc
Matrix_t* MatInsert ( const Matrix_t mat,
const Poly_t pol 
)

Insert a matrix into a polynomial Given a square matrix A and a polynomial p over the same field, this functions calculates p(A).

Unlike MatInsert_() this function returns a new matrix and does not modify the original matrix.

Parameters
matPointer to the matrix.
polPointer to the polynomial.
Returns
pol(mat), or 0 on error.
Matrix_t* MatInsert_ ( Matrix_t mat,
const Poly_t pol 
)

Insert a matrix into a polynomial Given a square matrix A and a polynomial p over the same field, this functions calculates p(A).

Unlike MatInsert() this function is destructive. The result is stored in the original matrix and the old value is lost.

Parameters
matPointer to the matrix.
polPointer to the polynomial.
Returns
The function returns mat, or 0 on error.
Matrix_t* MatInverse ( const Matrix_t mat)

Inverse of a matrix This function calculates the inverse of a matrix.

mat must be a non-singular square matrix. The inverse matrix is returned in a newly allocated Matrix_t structure, and the original matrix remains unchanged.

Parameters
matPointer to the matrix.
Returns
Inverse matrix or 0 on error.
int MatIsValid ( const Matrix_t mat)

Check if the matrix is valid.

This function checks if the argument is a pointer to a valid matrix. If the matrix is o.k., the function returns 1. Otherwise, an error is signalled and, if the error handler does not terminate the program, the function returns 0.

Parameters
matMatrix to check.
Returns
1 if the matrix is valid, 0 otherwise.
Matrix_t* MatLoad ( const char *  fn)

Read a matrix from a file.

This function opens a file, reads a single matrix, and closes the file. To read more than one matrix from a file, use |MatRead()|.

Parameters
fnFile name.
Returns
Pointer to the matrix, or |NULL| on error.
Matrix_t* MatMul ( Matrix_t dest,
const Matrix_t src 
)

Multiply matrices This function multiplies dest from the right by src.

The matrices must be compatible for multiplication, i.e. they must be over the same field, and the number of columns of dest must be equal to the number of rows of src. The result of the multiplication is stored in dest, overwriting the original contents.

See also
MatPower()
Parameters
destLeft factor and result.
srcRight factor.
Returns
The function returns dest, or 0 on error.
Matrix_t* MatMulScalar ( Matrix_t dest,
FEL  coeff 
)

Multiply a Matrix by a Constant.

Parameters
destPointer to the matrix.
coeffValue to multiply with.
Returns
The function returns dest.
long MatNullity ( const Matrix_t mat)

Nullity of a matrix.

This function calculates the dimension of the null-space of a matrix. Unlike MatNullity__() this function does not modify the matrix.

Parameters
matPointer to the matrix.
Returns
Nullity of the matrix, or -1 on error.
long MatNullity__ ( Matrix_t mat)

Nullity of a matrix.

This function calculates the dimension of the null-space of a matrix and deletes the matrix.

Parameters
matPointer to the matrix.
Returns
Nullity of mat, or -$ on error.
Matrix_t* MatNullSpace ( const Matrix_t mat)

Null-space of a matrix This function calculates the null-space of a matrix.

Unlike MatNullSpace_() and MatNullSpace__(), this function does not change the original matrix, but it allocates a temporary copy of the matrix and thus needs more memory.

Parameters
matPointer to the matrix.
Returns
Pointer to the null-space, or 0 on error.
Matrix_t* MatNullSpace_ ( Matrix_t mat,
int  flags 
)

Null-space of a matrix This function calculates the null-space of a matrix.

Unlike MatNullSpace(), this function modifies the orginal matrix, but uses less memory since no temporary workspace is allocated. The result is in echelon form.

Parameters
matPointer to the matrix.
flagsIf nonzero, the null-space is not reduced to echelon form.
Returns
Pointer to the null-space of |mat|, or |NULL| on error.
Matrix_t* MatNullSpace__ ( Matrix_t mat)

Null-space of a matrix This function calculates the null-space of a matrix and deletes the original matrix.

See also
MatNullSpace_(), MatNullSpace()
Parameters
matPointer to the matrix.
Returns
Pointer to the null-space, or 0 on error.
int MatOrder ( const Matrix_t mat)

Order of a matrix.

This function calculates the order of a matrix. mat must be a non-singular, square matrix. Even if mat is non-singular, the function may fail. This happens if the order is greater than 1000000, or if the order on any cyclic subspace is greater than 1000.

Parameters
matPointer to the matrix.
Returns
The order of mat, or 1 on error.
int MatPivotize ( Matrix_t mat)

Reduce to echelon form.

This function builds the pivot table of a matrix. Unlike MatEchelonize() this function assumes that mat is already in echelon form.

Parameters
matPointer to the matrix.
Returns
0 on success, -1 on error.
Matrix_t* MatPower ( const Matrix_t mat,
long  n 
)

Power of a matrix.

This function calculates the n-th power of a matrix, using the binary method. This method is generally faster than multiplying the matrix $n$ times by itself. On the other hand, a third matrix is temporarily created in addition to the original matrix and the result matrix. The cases n=0 and n=1 are handled separately, avoiding unnecessary memory allocation and calculation.

Negative exponents are not allowed. To calculate a negative power, you must first invert the matrix with MatInverse() and then call MatPower() with the inverted matrix and a positive exponent.

Parameters
matPointer to the matrix.
nExponent.
Returns
n-th power of mat, or NULL on error.
void MatPrint ( const char *  name,
const Matrix_t m 
)

Print a matrix on stdout.

This function prints a matrix on the standard output in readable form. If name is not 0, the name followed by an equal sign is printed before the matrix.

Parameters
nameName to print before the matrix, or 0.
mPointer to the matrix.
Matrix_t* MatRead ( FILE *  f)

Read a matrix from a file.

Parameters
fFile to read from.
Returns
Pointer to the matrix, or 0 on error.
int MatSave ( const Matrix_t mat,
const char *  fn 
)

Write a matrix to a file.

This function opens a file, writes a matrix to the file, and closes the file. If a file with the specified name already exists, the old contents of the file are destroyd. To write more than one matrix to a file, use MatWrite().

Parameters
matPointer to the matrix.
fnFile name.
Returns
0 on success, -1 on error.
FEL MatTrace ( const Matrix_t mat)

Trace of a Matrix.

This function calculates the sum of all diagonal elements of a matrix. Note that the matrix need not be square.

Parameters
matPointer to the matrix.
Returns
Trace of mat, FF_ZERO on error.
Matrix_t* MatTransposed ( const Matrix_t src)

Transpose a matrix.

Parameters
srcPointer to the matrix.
Returns
Pointer to the transposed matrix or 0 on error.
int MatWrite ( const Matrix_t mat,
FILE *  f 
)

Write a matrix to a file.

See also
MatSave
Parameters
matPointer to the matrix.
fPointer to the file.
Returns
0 on success, -1 on error.
int StablePower ( const Matrix_t mat,
int *  pwr,
Matrix_t **  ker 
)

Stable power of a matrix.

This function works like |StablePower_()|, but it does not modify the matrix in |mat|. This means, of course, that a temporary copy of the matrix is created.

Parameters
matThe matrix.
pwrStable power.
kerKernel of the stable power.
Returns
$0$ on success, $-1$ on error.
int StablePower_ ( Matrix_t mat,
int *  pwr,
Matrix_t **  ker 
)

Stable power of a matrix.

This function takes a square matrix M and finds an integer n>0 such that ker(Mn) = ker(Mn+1). ker must be a pointer to a variable of type Matrix_t*, where the stable kernel will be stored. Both pwr and ker may be NULL if the corresponding information is not needed.

Note that the number $n$ found by StablePower_() is not guararanteed to be minimal. In fact, n will always be a power of two since the function only examines matrices of the form M2k.

This function modifies the matrix. To avoid this, use StablePower().

Parameters
matThe matrix.
pwrStable power.
kerKernel of the stable power.
Returns
0 on success, -1 on error.

MeatAxe 2.4 documentation, generated on Wed Jan 7 2015 08:38:36