💾 Archived View for gemini.spam.works › mirrors › textfiles › programming › matrix.txt captured on 2023-01-29 at 11:28:17.
View Raw
More Information
⬅️ Previous capture (2020-10-31)
-=-=-=-=-=-=-
/*
- -----------------------------------------------------------------------------
- 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
-------------------------------------------------------------------------------