GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


archive:programming:matrix

Table of Contents

/* *—————————————————————————– * 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


/data/webs/external/dokuwiki/data/pages/archive/programming/matrix.txt · Last modified: 1999/08/01 17:20 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki