- added backwards calculation of hkl from four circle angles. This
required inclusion of a matrix package. - modified counter error handling to send a Stop when the _BAD_BUSY error is received. - added an environment interface to the general controller stuff in choco.* Also added setting a parameter directly at the controller object. - Added a driver for the ETH High Temperature Furnace to be used at SANS.
This commit is contained in:
cvs
482
matrix/MATRIX.DOC
Normal file
482
matrix/MATRIX.DOC
Normal file
@@ -0,0 +1,482 @@
|
||||
/*
|
||||
*-----------------------------------------------------------------------------
|
||||
* 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
|
||||
-------------------------------------------------------------------------------
|
||||
Reference in New Issue
Block a user