PsiLAB Help Manual Page

Section: Basic Matrix functions

Name: cmatrix

Create a new complex matrix. Complex data is represented in PsiLAB with a float tuple. There are several arguments controlling the way the new matrix is defined. This function expects a combination of several arguments, but most are optional.
[ mat:(Complex.t, 'b, 'c) Matrix.t ] = fmatrix
?dim:int list
?const:'a list
?copy:(Complex.t, 'b, 'c) Matrix.t list
?fill:Complex.t list
?sub:(int * int) list
?rand:float list
?row:(Complex.t, 'd, 'e) Matrix.t list
?col:(Complex.t, 'd, 'e) Matrix.t list
()

At least the dimension list argument is necessary:

~dim:[ size i ; size j ; ... ]

The common way to use the cmatrix function is within a let statement: 
let f = cmatrix ~dim:[5;3] () ;;

Don't forget the unit operator for the last argument.
It's possible to create a matrix from a list of constant values. Only vectors (1 dimension) are allowed. The complex values are paired in tuples:
~const:[ (xr 0 ,xi SB 0 ) ;(xr 1 , xi 1 ) ; (xr 2 , xi 2 ) ; ... ]

To copy an already existing matrix to a new one, use:
~copy:[ original matrix ]

The original and the new matrix have the same dimension and sizes.
If only a subarea of the original matrix should be copied, use the subrange argument additional to the copy argument:
~sub:[ (i start,i end);(j start, j end);... ]

To specifiy a full range of a matrix dimension, use the (--) operator. All elements can be filled with a constant value using the fill argument:
~fill:[ (float*float) value ]

The complex element is written in form of a tuple (re,im).
Each element of the new matrix can be filled with random numbers:
~rand:[ maximum value ]

The real and imaginary parts are calculated independently. The minimum value of the random distribution is always 0.
To glue several 2 dimensional matrices or vectors with same row number to one matrix, all matrices appended in a row, there is the row argument:
~row:[ a ; b ; c ; ... ]

a,b,c,... -> | a b c ... |

To glue several 2 dimensional matrices or vectors with same column number to one matrix, all matrices will be appended in a column, there is the col argument:
~col:[ a ; b ; c ; ... ]

a,b,c,... ->
| a |
| b |
| c |
...


Note 1.) All indices start with number 1!
Note 2.) Allocating a new matrix with this function is a little bit
time consuming operation, because the Caml Garbage Collector
is invoked. And because of the lazy variable management in Caml,
the matrix data space will be delayed freed (by the GC).
Use the cmatrix_byname function family for faster and
better user controlled matrix allocation and destruction!

Examples: 
(* Create a new matrix with 200 rows and 100 columns *) 
[] let f = cmatrix ~dim:[200;100] () ;; 
val f : (Complex.t, '_a, '_b) Matrix.t = <abstr> 

(* Fill all elements of new matrix with value (1.0,1.0) *) 
[] let u = cmatrix ~dim:[100] ~fill:[(1.0,1.0)] () ;; 
val u : (Complex.t, '_a, '_b) Matrix.t = <abstr> 

(* Create a new matrix from constant values *) 
[] let g = cmatrix ~const:[(1.0,2.0);(4.0,-1.0);(0.0,0.0)] () ;; 
val g : (Complex.t, '_a, '_b) Matrix.t = <abstr> 

[] print_cmat g ;; 
| 	 1+ 	 2*i | 
| 	 4- 	 1*i | 
| 	 0+ 	 0*i | 

- : unit = () 



(* Copy all elements of g to new matrix h *) 
[] let h = cmatrix ~copy:[g] () ;; 
val h : (Complex.t, '_a, '_b) Matrix.t = <abstr> 

(* Copy sub matrix of g -> g(1:2) to new matrix hs *) 
[] let hs = cmatrix ~copy:[g] ~sub:[(1,2)] () ;; 
val hs : (Complex.t, '_a, '_b) Matrix.t = <abstr> 

[] print_fmat hs ;; 
| 	 1+ 	 2*i | 
| 	 4- 	 1*i | 

- : unit = ()

Printed by PsiLAB