483 lines
18 KiB
Plaintext
483 lines
18 KiB
Plaintext
/*
|
|
*-----------------------------------------------------------------------------
|
|
* file: matrix.doc
|
|
* desc: document for matrix toolbox function calls
|
|
* by: KO shu pui, patrick
|
|
* date: 24 may 92 v0.4
|
|
* 23 sep 93 v0.41
|
|
* 16 apr 94 v0.42
|
|
*-----------------------------------------------------------------------------
|
|
*/
|
|
|
|
===============================================================================
|
|
0. INTRODUCTION
|
|
===============================================================================
|
|
This document only provides you the following information:
|
|
|
|
0.1 How to create and free a matrix
|
|
0.2 Description of each matrix function call
|
|
0.3 Some hints to use this toolbox
|
|
|
|
Remember that this document will NOT describe the data structure and
|
|
any technical details of the toolbox - just because this document is
|
|
aimed at to be a sort-of "User's Guide" for programmers.
|
|
|
|
|
|
|
|
|
|
===============================================================================
|
|
1. OUR MATRIX OF REFERENCE
|
|
===============================================================================
|
|
In order to avoid terms confusion, here is our matrix of reference
|
|
(matrix A) which is of size m x n.
|
|
|
|
Column
|
|
Row 0 1 2 n-1
|
|
0 [ a0,0 a0,1 a0,2 ... a0,n-1 ]
|
|
A = 1 [ a1,0 a1,1 a1,2 ... a1,n-1 ]
|
|
2 [ a2,0 a2,1 a2,2 ... a2,n-1 ]
|
|
[ ... ... ... ... ... ]
|
|
m-1 [ am-1,0 am-1,1 am-1,2 ... am-1,n-1 ]
|
|
|
|
|
|
|
|
===============================================================================
|
|
2. BASIC MATRIX OBJECT OPERATION
|
|
===============================================================================
|
|
-------------------------------------------------------------------------------
|
|
Function : MATRIX mat_creat (int m, int n, int type)
|
|
Synopsis : creation of a matrix which can be used by the matrix toolbox
|
|
functions; memory is allocated for this object; and some
|
|
initialization is performed.
|
|
Parameter: m: number of rows
|
|
n: number of columns
|
|
type: matrix initialization type where
|
|
|
|
type=
|
|
|
|
UNDEFINED do not initialize the matrix
|
|
ZERO_MATRIX fill zero to all matrix elements
|
|
UNIT_MATRIX fill a one to all matrix element ai,j
|
|
where i=j
|
|
|
|
Return Value: the matrix object
|
|
Example:
|
|
|
|
MATRIX A;
|
|
|
|
/*
|
|
* create a 15 x 15 matrix;
|
|
* do not initialize the elements
|
|
*/
|
|
A = mat_creat( 15, 15, UNDEFINED);
|
|
|
|
/*
|
|
* put a 4 in element A(0,14) of matrix A,
|
|
* put a 2 in element A(3,5) of matrix A
|
|
*/
|
|
A[0][14] = 4.0;
|
|
A[3][5] = 2.0;
|
|
|
|
See Also: mat_free(), for Accessing a matrix, see this example.
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_fill ( MATRIX A, int type )
|
|
Synopsis: initialize a matrix will a simple type
|
|
Parameter: A: the matrix object for which mat_creat() has been called
|
|
type: matrix initialization type where
|
|
|
|
type=
|
|
|
|
UNDEFINED do not initialize the matrix
|
|
ZERO_MATRIX fill zero to all matrix elements
|
|
UNIT_MATRIX fill a one to all matrix element ai,j
|
|
where i=j
|
|
Return Value: MATRIX A
|
|
Example:
|
|
|
|
MATRIX A;
|
|
|
|
...
|
|
/*
|
|
* fill the matrix A will zeroes
|
|
*/
|
|
mat_fill( A, ZERO_MATRIX );
|
|
|
|
See Also: mat_creat()
|
|
-------------------------------------------------------------------------------
|
|
Function : int mat_free ( MATRIX A )
|
|
Synopsis : free all memory occupied by the matrix object A
|
|
Parameter: A: the matrix object for which mat_creat() was called
|
|
Return Value: None
|
|
Example:
|
|
|
|
MATRIX A;
|
|
|
|
A = mat_creat(...);
|
|
...
|
|
mat_free(A);
|
|
|
|
Note: since memory may be a very scarce resource in a computer,
|
|
as a C programmer you are advised to free up the matrix as
|
|
soon as that matrix will not be used any more in future.
|
|
|
|
See Also: mat_creat()
|
|
-------------------------------------------------------------------------------
|
|
Function: MatCol ( A )
|
|
Synopsis: find out the number of columns of a matrix object A
|
|
Parameter: A: the matrix object for which mat_creat() was called
|
|
Return Value: number of columns
|
|
Example:
|
|
int i;
|
|
|
|
...
|
|
i = MatCol(A);
|
|
|
|
Note: this is a macro
|
|
See Also: MatRow()
|
|
-------------------------------------------------------------------------------
|
|
Function: MatRow ( A )
|
|
Synopsis: find out the number of rows of a matrix object A
|
|
Parameter: A: the matrix object for which mat_creat() was called
|
|
Return Value: number of rows
|
|
Example:
|
|
int i;
|
|
|
|
...
|
|
i = MatRow(A);
|
|
|
|
Note: this is a macro
|
|
See Also: MatCol()
|
|
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_colcopy1 ( MATRIX A, MATRIX B, int j1, int j2 )
|
|
Synopsis: copy a column from a matrix A to a column at matrix B
|
|
Parameter: A, B: the matrix objects for which mat_creat() was called
|
|
column j1 of A is copied to column j2 of B;
|
|
Return Value: MATRIX A
|
|
Example:
|
|
MATRIX A, B;
|
|
|
|
A = mat_creat( 5, 4, ZERO_MATRIX );
|
|
B = mat_creat( 5, 4, UNDEFINED );
|
|
|
|
/*
|
|
* copy column 2 of A to column 0 of B
|
|
*/
|
|
mat_colcopy1( A, 2, B, 0 );
|
|
|
|
Note: the sizes of rows of A, B must be the same
|
|
See Also: mat_copy()
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_copy ( MATRIX A )
|
|
Synopsis: duplicate a matrix
|
|
Parameter: A: the matrix object for which mat_creat() was called
|
|
Return Value: Another allocated matrix object whose contents are same
|
|
as A
|
|
Example:
|
|
MATRIX A, B;
|
|
|
|
A = mat_creat( 5, 4, ZERO_MATRIX );
|
|
|
|
/*
|
|
* B is also a 5 x 4 zero matrix now
|
|
*/
|
|
B = mat_copy( A );
|
|
...
|
|
mat_free( B );
|
|
|
|
See Also: mat_colcopy1()
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
===============================================================================
|
|
3. BASIC MATRIX OBJECT INPUT/OUTPUT OPERATION
|
|
===============================================================================
|
|
-------------------------------------------------------------------------------
|
|
Function: int fgetmat (MATRIX A, FILE * fp)
|
|
Synopsis: read a matrix from stream
|
|
Parameter: A: allocated matrix
|
|
fp: a stream pointer obtained from fopen() or predefined
|
|
pointer in standard library such as stdin
|
|
Return Value: number of matrix elements read
|
|
Example:
|
|
MATRIX A;
|
|
FILE *fp;
|
|
|
|
A = mat_creat(3, 3, UNDEFINED);
|
|
fp = fopen("mymatrix.dat", "r");
|
|
fgetmat( A, fp );
|
|
|
|
See Also: mat_dumpf(), mat_dump(), mat_fdump(), mat_fdumpf()
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_dump (MATRIX A)
|
|
MATRIX mat_dumpf (MATRIX A, char * format)
|
|
MATRIX mat_fdump (MATRIX A, FILE * fp)
|
|
MATRIX mat_fdumpf (MATRIX A, char * format, FILE * fp)
|
|
|
|
Synopsis: mat_dump: dump a matrix to std output with default format
|
|
mat_dumpf: dump a matrix to std output with specified format
|
|
mat_fdump: dump a matrix to a file with default format
|
|
mat_fdumpf:dump a matrix to a file with specified format
|
|
|
|
Parameter: A: allocated matrix
|
|
format: same as printf() 's format parameter, but can only
|
|
be floating point type, such as "%.2f ", etc.
|
|
fp: file pointer obtained via fopen()
|
|
|
|
Return Value: matrix A
|
|
|
|
Example:
|
|
MATRIX A;
|
|
|
|
A = mat_creat( ... );
|
|
...
|
|
/*
|
|
* dump the matrix to standard output and each element
|
|
* is restricted to 2 precision format
|
|
*/
|
|
mat_dumpf( A, "%.2f ");
|
|
|
|
See Also: fgetmat()
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
===============================================================================
|
|
4. BASIC MATRIX OBJECT MATHEMATICAL OPERATION
|
|
===============================================================================
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_add (MATRIX A, MATRIX B);
|
|
MATRIX mat_sub (MATRIX A, MATRIX B);
|
|
Synopsis: mat_add: addition of 2 matrices
|
|
mat_sub: substraction of 2 matrices
|
|
Parameter: A, B: allocated matrices
|
|
Return Value: a newly allocated matrix which is the result of the operation
|
|
Example:
|
|
|
|
MATRIX A, B, C;
|
|
|
|
A = mat_creat( 5, 5, UNIT_MATRIX );
|
|
B = mat_creat( 5, 5, UNIT_MATRIX );
|
|
|
|
C = mat_add( A, B );
|
|
|
|
mat_dump( C );
|
|
|
|
mat_free( A );
|
|
mat_free( B );
|
|
mat_free( C );
|
|
|
|
Note: A, B must be of the same dimensions
|
|
See Also: mat_mul, mat_inv
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_mul (MATRIX A, MATRIX B);
|
|
Synopsis: multiplication of 2 matrices
|
|
Parameter: A, B: allocated matrix
|
|
Return Value: a newly allocated matrix which is the result of the operation
|
|
Example:
|
|
MATRIX A, B, C;
|
|
|
|
A = mat_creat( 5, 3, UNIT_MATRIX );
|
|
B = mat_creat( 3, 6, UNIT_MATRIX );
|
|
|
|
/*
|
|
* C is now a 5 x 6 matrix
|
|
*/
|
|
C = mat_add( A, B );
|
|
|
|
mat_dump( C );
|
|
...
|
|
|
|
Note: the column dimension of A must equal row dimension of B
|
|
See Also: mat_add, mat_sub
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_inv (MATRIX A)
|
|
Synopsis: find the inverse of a matrix
|
|
Parameter: A: allocated square matrix
|
|
Return Value: a newly allocated square matrix which is the inverse of A
|
|
Example:
|
|
MATRIX A, AI;
|
|
|
|
/*
|
|
* A must be a square matrix
|
|
*/
|
|
A = mat_creat( 7, 7, UNIT_MATRIX );
|
|
...
|
|
/*
|
|
* find the inverse of A
|
|
*/
|
|
AI = mat_inv( A );
|
|
...
|
|
|
|
See Also: mat_tran, mat_add, mat_sub
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_tran( MATRIX A )
|
|
Synopsis: find the transpose of a matrix
|
|
Parameter: A: allocated matrix
|
|
Return Value: a newly allocated matrix which is the transpose of A
|
|
Example:
|
|
MATRIX A, T;
|
|
|
|
A = mat_creat( 3, 5, UNDEFINED );
|
|
...
|
|
T = mat_tran( A );
|
|
...
|
|
|
|
See Also: mat_inv
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
===============================================================================
|
|
5. DETERMINANT OPERATIONS
|
|
===============================================================================
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_submat (MATRIX A, int i, int j)
|
|
Synopsis: form a new matrix by deleting a row and a column of A
|
|
Parameter: A: allocated matrix
|
|
i, j: row and column of A which will not appear in the
|
|
resulting matrix
|
|
Return Value: a new matrix whose dimensions are 1 less than A
|
|
Example:
|
|
MATRIX A, B
|
|
|
|
A = mat_creat( 3, 4, UNDEFINED );
|
|
...
|
|
B = mat_submat( A, 2, 2 );
|
|
/*
|
|
* suppose A = [ 1 2 3 4 ]
|
|
* [ 3 3 4 5 ]
|
|
* [ 6 7 9 9 ]
|
|
*
|
|
* then B = [ 1 2 4 ]
|
|
* [ 3 3 5 ]
|
|
*/
|
|
|
|
Note: Do not be misled -- the contents in A will NOT be changed
|
|
See Also: mat_det, mat_cofact, mat_minor
|
|
-------------------------------------------------------------------------------
|
|
Function: double mat_cofact (MATRIX A, int i, int j)
|
|
Synopsis: find out the cofactor of A(i,j)
|
|
Parameter: A: allocated square matrix
|
|
i,j: row, column position of A for the cofactor
|
|
Return Value: the value of cofactor of A(i,j)
|
|
Example:
|
|
MATRIX A;
|
|
|
|
A = mat_creat( 5, 5, UNIT_MATRIX );
|
|
...
|
|
printf( "cofactor of A(0,2) = %f\n", mat_cofact( A, 0, 2 ));
|
|
|
|
See Also: mat_det, mat_minor
|
|
-------------------------------------------------------------------------------
|
|
Function: double mat_minor (MATRIX A, int i, int j)
|
|
Synopsis: find out the minor of A(i,j)
|
|
Parameter: A: allocated square matrix
|
|
i,j: row, column position of A for the minor
|
|
Return Value: the value of minor of A(i,j)
|
|
Example:
|
|
MATRIX A;
|
|
|
|
A = mat_creat( 5, 5, UNIT_MATRIX );
|
|
...
|
|
printf( "minor of A(0,2) = %f\n", mat_minor( A, 0, 2 ));
|
|
|
|
See Also: mat_det, mat_cofact
|
|
-------------------------------------------------------------------------------
|
|
Function: double mat_det (MATRIX A)
|
|
Synopsis: find the determinant of a matrix
|
|
Parameter: A: allocated square matrix
|
|
Return Value: the determinant value of |A|
|
|
Example:
|
|
MATRIX A;
|
|
double det;
|
|
|
|
A = mat_creat( 5, 5, UNIT_MATRIX );
|
|
det = mat_det( A );
|
|
|
|
See Also: mat_cofact, mat_minor, mat_submat
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
===============================================================================
|
|
6. ADVANCED MATRIX OBJECT MATHEMATICAL OPERATION
|
|
===============================================================================
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_lsolve (MATRIX A, MATRIX B)
|
|
Synopsis: solve simultaneous linear equation AX = B given A, B
|
|
Parameter: A, B: allocated matrix
|
|
Return Value: newly allocated matrix X in AX = B
|
|
Example:
|
|
MATRIX A, B, X;
|
|
|
|
A = mat_creat( 5, 5, UNDEFINED );
|
|
fgetmat( A, stdin );
|
|
...
|
|
B = mat_creat( 5, 1, UNDEFINED );
|
|
fgetmat( B, stdin );
|
|
...
|
|
X = mat_lsolve( A, B );
|
|
mat_dump( X );
|
|
|
|
Note: number of rows in A and B must be equal
|
|
See Also: mat_lsolve_durbin
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_lsolve_durbin (MATRIX A, MATRIX B)
|
|
Synopsis: simultaneous linear equations wtih Levinson-Durbin method
|
|
Parameter: A, B: allocated matrix where A is an autocorrelated matrix and
|
|
B is derived from A
|
|
|
|
A, B must be the following forms:
|
|
|
|
| a0 a1 a2 .. an-1 | | x1 | | a1 |
|
|
| a1 a0 a1 .. an-2 | | x2 | | a2 |
|
|
| a2 a1 a0 .. an-3 | | x3 | = | .. |
|
|
| ... | | .. | | .. |
|
|
| an-1 an-2 .. .. a0 | | xn | | an |
|
|
|
|
where A is a symmetric Toeplitz matrix and B
|
|
in the above format (related to A)
|
|
|
|
Return Value: a newly allocated matrix X which is the solution of AX = B
|
|
|
|
Example: this method only applies to certain A, B only.
|
|
e.g.
|
|
|
|
A = [1 3 9] B = [3]
|
|
[3 1 3] [9]
|
|
[9 3 1] [12] <- the last one is unrelated to A
|
|
|
|
See Also: mat_SymToeplz
|
|
-------------------------------------------------------------------------------
|
|
Function: MATRIX mat_SymToeplz (MATRIX R);
|
|
Synopsis: create a symmetric Toeplitz matrix from a
|
|
Autocorrelation vector
|
|
Parameter: R: allocated matrix of dimension n x 1
|
|
Return Value: a newly allocated symmetrical Toeplitz matrix
|
|
Example:
|
|
e.g.
|
|
|
|
MATRIX A, R;
|
|
|
|
R = mat_creat( 3, 1, UNDEFINED );
|
|
...
|
|
A = mat_SymToeplz( R );
|
|
|
|
/*
|
|
* if
|
|
*
|
|
* R = [1 3 9] A = [1 3 9]
|
|
* [3 1 3]
|
|
* [9 3 1]
|
|
*
|
|
*/
|
|
|
|
See Also: mat_lsolve_durbin
|
|
-------------------------------------------------------------------------------
|