Table des Matières
Notations
In the description below, I will use these notations for specifiing types of variable</p>
| X, Y, Z | can be vectors or matrices |
| A | must be or is a matrix (at least 2 columns) |
| V, W | must be or is a vector (just 1 column) |
| m, n | indexes (unsigned integers) |
| i | an integer |
| r | a real |
| b | a boolean |
File matrix.cpp : basic functions
Constructor, destructor, reset, clear and copy operator
| matrix : constructor | |
| Syntax | matrix X; matrix X(10); matrix X(12, 41); matrix X(Z); |
| Description | Construct a matrix object. It is empty with no specified size, or just a column if one argument, or a matrix if the number of rows and columns are specified. The last constructor syntax creates an object that refers to the indicated matrix. It is not a reallocation but a reference (a modification of the referer changes the referenced). |
| ~matrix : destructor | |
| Syntax | not applicable |
| Description | The destructor releases the memory allocated only if it isn’t a reference matrix. In this case, only the referencing counter is decreased. |
| reset | |
| Syntax | X.reset(10); Y.reset(5, 5); |
| Description | Allow the user to change the size of the matrix. The datas are lost. |
| clear | |
| Syntax | X.clear(); |
| Description | Reset and set the default size to unspecified. |
| operator= | |
| Syntax | X = 1.2; X = Y; |
| Description | Copy operator. It set all the elements to a scalar value or copy a matrix to another. It is a real copy, not a referencing copy. The function does nothing if you write X = X. |
Retrieve information from the matrix
| isNull | |
| Syntax | b = X.isNull(); |
| Description | Return TRUE if size isn’t specified, so datas aren’t allocated. |
| nRefs | |
| Syntax | i = X.nRefs(); |
| Description | Return the number of references to this matrix. |
| nCols | |
| Syntax | i = X.nCols(); |
| Description | Return the number of columns for the matrix. |
| nRows | |
| Syntax | i = X.nRows(); |
| Description | Return the number of rows for the matrix. |
| size | |
| Syntax | i = X.size(); |
| Description | Return the number of elements in the matrix. |
| incRow | |
| Syntax | i = X.incRow(); |
| Description | Return the size of allocated rows. Can be different from the number of rows because the matrix can be in a submatrix mode (it refers only to some of his elements). So the result can be different, but it is always greater or equal to the number of rows. |
| isTrans | |
| Syntax | b = X.isTrans(); |
| Description | Return TRUE if the transposed flag is set. See discussion for the !operator. |
addessing elements of the matrix
| xmat : checks bounds | |
| Syntax | X.xmat(5, 4) = 5; r = X.xmat(123); |
| Description | It is the safe way to access the matrix elements. It always checks the bound limits. Return a reference to the REAL so can be used as left or right operand. |
| mat | |
| Syntax | X.mat(5, 4) = 5; r = X.mat(123); |
| Description | This access is checked in the DEBUG version but free in the RELEASE. Return a reference to the REAL so can be used as left or right operand. |
| rmat | |
| Syntax | X.rmat(5.0, 4.0) = 5; r = X.rmat(123.0); |
| Description | Same as mat, but allows REAL arguments. This access is checked in the DEBUG version but free in the RELEASE. Return a reference to the REAL so can be used as left or right operand. |
| operator() | |
| Syntax | X(5, 4) = 5; r = X(123); |
| Description | This access is checked in the DEBUG version but free in the RELEASE. Return a reference to the REAL so can be used as left or right operand. |
| tran | |
| Syntax | X.tran(5, 4) = 5; r = X.tran(123); |
| Description | Is the same as mat, but the access goes to the transposed matrix. This access is checked in the DEBUG version but free in the RELEASE. Return a reference to the REAL so can be used as left or right operand. |
vector addressing and assignment
| vec | |
| Syntax | X.vec(54) = 5; r = X.vec(123); |
| Description | Address the matrix elements as viewed as a vector. The matrix elements are viewed as if the columns of the matrix had been stacked upon on top of each other. Can be used with the size functions to fill a matrix. Example : matrix x(100, 20); for (i=1; i<x.size(); i++) x.vec(i) = i; |
| assign | |
| Syntax | X.assign(3, 2, 1.3, 2.5, 4.2, 7.0, 1.5, 0.0); |
| Description | Allows to assign values to the elements of the matrix. Rather good for small matrix. First two arguments are the numbers of rows and columns given as arguments. The values are listed behind. |
transposition
| trans | |
| Syntax | X = Y.trans(); |
| Description | Return a new matrix which is the transposed matrix. |
| operator! | |
| Syntax | X = Z * !y; |
| Description | Change the transpose flag. Warning : only a few operations are !-aware. In fact only the multiplication will use it, as this function doesn’t reallocate the datas, but only change the status. So it must only be used with the functions which take care about the flag : only operator* for the moment. When you want to interact with the transposed matrix, create a new matrix with the function trans(). This function is only useful for writing such things : C=!A*B; a transposed multiply b C=!A*!B; a transposed multiply b transposed |
type casting, dimension check
| real | |
| Syntax | R = real(V); |
| Description | Allows you to cast a matrix to a double when the matrix is 1 by 1. This is a function and not a operator because it must be implicity called. If it was an operator, the compiler could call it for resolving some bad assignation and program would crash. |
| checkDims | |
| Syntax | B = X.checkDims(Y); |
| Description | Check that X and Y are the same size. |
File matcomp.cpp : comparison
The relational operators are <, <=, >, >=, ==, and !=. Relational operators perform element-by-element comparisons between two arrays. They return an array of the same size, with elements set to logical true (1) where the relation is true, and elements set to logical false (0) where it is not. If one of the operators is a scalar and the other a matrix, the scalar is considered as a matrix with same size as the other argument and filled with this scalar.
comparison operators and functions
| greater, less, equal, greatEqual, lessEqual, notEqual | |
| Syntax | Z.greater(X, r); Z.greater(X, Y); Z.less(X, r); Z.less(X, Y); Z.equal(X, r); Z.equal(X, Y); Z.greatEqual(X, r); Z.greatEqual(X, Y); Z.lessEqual(X, r); Z.lessEqual(X, Y); Z.notEqual(X, r); Z.notEqual(X, Y); |
| Description | Perform the element by element comparison and return the corresponding Z matrix for. |
| operators ==, >, >=, <, <=, != | |
| Syntax | Z = X == Y; Z = X > r; Z = X > Y; Z = X >= r; Z = X >= Y; Z = X < r; Z = X < y; Z = X <= r; Z = X <= Y; Z = X != r; Z = X != Y; |
| Description | Theses operators performs the comparison and return matrices. It is up to you to check this matrix for a boolean result. |
test on logical matrices
| any | |
| Syntax | b = any(Y); |
| Description | Return TRUE is any element of matrix is TRUE (!=0.0). |
| all | |
| Syntax | b = all(Y); |
| Description | Return TRUE is all elements of matrix are TRUE (!=0.0). |
| countTrue | |
| Syntax | i = Y.countTrue(); |
| Description | Return the number of TRUE in the matrix. |
logical operations
| and | |
| Syntax | Z = X.and(Y); |
| Description | Perform the logical AND between elements of X and Y and return it in Z. |
| or | |
| Syntax | Z = X.or(Y); |
| Description | Perform the logical OR between elements of X and Y and return it in Z. |
| not | |
| Syntax | Z = Y.not(); |
| Description | Perform the element logical NOT of X and return it in Z. |
find relationship
| compare | |
| Syntax | c = X.compare®; c = X.compare(Y); |
| Description | Return an indicator which tells if the relationship between the matrices or the matrix and the real is equal, greater or less. The result can be mixed, because some elements by elements comparisons can be less, other equal or greater. |
File matLAB.cpp : matLAB alike functions
These functions are the same as MATLAB’s one. The spelling and arguments are the same. In some case, the behaviors could a slightly change.
special matrix creation
| eye | |
| Syntax | Y = eye(n); Y = eye(m, n); Y = eye(Z); |
| Description | Y = eye(n) returns the n-by-n identity matrix. Y = eye(m, n) returns an m-by-n matrix with 1 on the diagonal and 0 elsewhere. Y = eye(Z) returns an identity matrix the same size as Z. |
| zeros | |
| Syntax | Y = zeros(n); Y = zeros(m, n); Y = zeros(Z); |
| Description | Y = zeros(n) returns an n-by-n matrix of zeros. Y = zeros(m, n) returns an m-by-n matrix of zeros. Y = zeros(Z) returns a Z same size array consisting of all zeros. |
| ones | |
| Syntax | Y = ones(n); Y = ones(m, n); Y = ones(Z); |
| Description | Y = ones(n) returns an n-by-n matrix of ones. Y = ones(m, n) returns an m-by-n matrix of ones. Y = ones(Z) returns an array of ones that is the same size as Z. |
sum, max and min
| sum | |
| Syntax | Y.sum(); r = sum(V); V = sum(A); |
| Description | If the argument is a vector, r = sum(V) returns the sum of the elements in a real because of the double type casting which allow translation of 1 by 1 matrix to double. If the argument is a matrix, V = sum(A) treats the columns of A as vectors, returning a row vector of the sums of each column. Y.sum() apply the preceding transformations to himself. |
| max | |
| Syntax | X.max(); r = max(V); V = max(A); |
| Description | If the argument is a vector, r = max(V) returns the largest element in V as a real because of the double type casting which allow translation of 1 by 1 matrix to double. If the argument is a matrix, V = max(A) treats the columns of A as vectors, returning a row vector containing the maximum element from each column. Y.max() apply the preceding transformations to himself. |
| min | |
| Syntax | Y.min(); r = min(V); V = min(A); |
| Description | If the argument is a vector, r = min(V) returns the smallest element in V as a real because of the double type casting which allow translation of 1 by 1 matrix to double. If the argument is a matrix, V = min(A) treats the columns of A as vectors, returning a row vector containing the minimum element from each column. Y.min() apply the preceding transformations to himself. |
norm, trace, dot and diff
| norm | ||
| Syntax | n = Y.norm(p = NORM_EUCLIDEAN); n = norm(Y, p = NORM_EUCLIDEAN); |
|
| Description | If Y is a matrix, n = Y.norm(p) returns a different kind of norm, depending on the value of p : p = NORM_MAXCOLSUM, 1 The 1-norm, or largest column sum of A, n = max(sum(abs(Y))). p = NORM_EUCLIDEAN, 2 The 2-norm, is the square root of sum of squared elements of A. p = NORM_INFINI, 0xFFFF The Inf-norm, or largest row sum of A, n = max(sum(abs(A.trans()))). If Y is a vector, slightly different rules apply, depending on the value of p : p any integer greater or equal to 1 Returns sum(abs(Y) power p) power (1/p) Particulars cases : p = NORM_SUMOFABS or 1 : It’s the 1-norm p = NORM_EUCLIDEAN or 2 : It’s the Euclidean norm. p = NORM_INFINI, 0xFFFF : Returns max(abs(A)). |
|
| trace | ||
| Syntax | r = Y.trace(); r = trace(Y); |
|
| Description | Return the sum of the diagonal elements of the matrix Y. | |
| dot | ||
| Syntax | r = V.dot(W); r = W.dot(V); it’s the same |
|
| Description | Return the value of the dot (scalar) product of the vectors V and W. | |
| diff | ||
| Syntax | Y = diff(X); Y = diff(X, n); |
|
| Description | Y = diff(X) calculates differences between adjacent elements of X. If X is a vector, then diff(X) returns a vector, one element shorter than X, of differences between adjacent elements : [X(2)-X(1) X(3)-X(2) … X(n)-X(n-1)] If X is a matrix, then diff(X) returns a matrix of column differences. Y = diff(X, n) applies diff recursively n times, resulting in the nth difference. If at any time, there are only one column left when apply recursively to a matrix, diff starts differentiating the next level, i.e. rows. |
|
abs, floor and ceil
| abs | |
| Syntax | Y.abs(); Y = abs(X); |
| Description | Y.abs() changes each element to his absolute value. Y = abs(X) returns an array of the absolute value of each element of X. |
| floor | |
| Syntax | Y.floor(); Y = floor(Z); |
| Description | Y = floor(Z) rounds the elements of Z to the nearest integers less than or equal to Z. |
| ceil | |
| Syntax | Y.ceil(); Y = ceil(Z); |
| Description | Y = ceil(Z) rounds the elements of Z to the nearest integers greater than or equal to Z. |
File matGEN.cpp : general operations
Here are all the functions for additions, substractions, multiplication’s and divisions. Some operators can directly store the result, others can’t. Look at matopt.txt for the discussion about direct access.
operators +=, -=, *= and /=
| operator += | |
| Syntax | Y += r; Y += X; |
| Description | Directly add a scalar or a vector in the matrix X. If it is a scalar, then it is added to every element. |
| operator -= | |
| Syntax | Y -= r; Y -= X; |
| Description | Directly subtract a scalar or a vector in the matrix X. If it is a scalar, then it is subtracted to every element. |
| operator *= | |
| Syntax | Y *= r; |
| Description | Multiply every elements with the scalar. There is no operator that takes a matrix as argument (see discussion in matopt.txt). |
| operator /= | |
| Syntax | Y /= r; |
| Description | Divide every elements with the scalar. |
operator +, -, * and /
| operator + | |
| Syntax | Z = X + Y; Z = X + r; Z = r + X; |
| Description | Create a new matrix with the sum of the arguments. If one of them is a scalar, it is added to every elements of the matrix. |
| operator - | |
| Syntax | Z = X - Y; Z = X - r; Z = r - X; |
| Description | Create a new matrix with the subtraction of the arguments. If one of them is a scalar, the operation is applied to every elements of the matrix. |
| operator * | |
| Syntax | Z = X * Y; Z = r * X; Z = X * r; |
| Description | Create a new matrix with the product of the arguments. If one of them is a scalar, every elements are scaled with this scalar. |
| operator / | |
| Syntax | X = Y / A; X = r / Y; X = Y / r; |
| Description | First case : X = Y / A; Solve the system A.X = Y. It use for this a LU decomposition of the matrix. Assume that the solution exists. Second case : X = r / Y; Return a matrix with for every elements, the scalar divided by the element of the matrix. Third case : X = Y / r; Return a matrix with for every elements, the elements divided by the scalar. |
multiplications
| Mult | |
| Syntax | Z = X.Mult(Y); Z.Mult(X, Y); |
| Description | Multiply two matrices. First case return a temporary matrix, the second directly store the result in Z. |
| MultT | |
| Syntax | Z = X.MultT(Y); Z.MultT(X, Y); |
| Description | Multiply X with the transposed matrix Y. First case return a temporary matrix, the second directly store the result in Z. |
| TMult | |
| Syntax | Z = X.TMult(Y); Z.TMult(X, Y); |
| Description | Multiply X transposed with matrix Y. First case return a temporary matrix, the second directly store the result in Z. |
| TMultT | |
| Syntax | Z = X.TMultT(Y); Z.TMultT(X, Y); |
| Description | Multiply X transposed with matrix Y transposed. First case return a temporary matrix, the second directly store the result in Z. |
row and column multiplication
| rowMult | |
| Syntax | Z.rowMult(V); Z = rowMult(X, V); |
| Description | V is a vector and will be used for rows scaling of Z. First case directly modify the Z matrix, the second case return a temporary matrix with the result. |
| colMult | |
| Syntax | Z.colMult(V); Z = colMult(X, V); |
| Description | V is a vector and will be used for columns scaling of Z. First case directly modify the Z matrix, the second case return a temporary matrix with the result. |
File matSUB.cpp : submatrix operations
You can refer to submatrices very easily. The matrix class allows you to make any operations with these submatrices. For example, you can write :
A.col(1) = 1.0; // tells that the first column of A is set to 1.0 B = A.sub(2, 3, 4, 5); // copy the 2x2 submatrix of A in B
Submatrices are not a new matrix but just a reference to a part of one matrix. So take care about the modification you can do on a submatrix which are also done on the big one, because of the reference. Here are listed the submatrix functions you can directly use in the matrix class. There is a specialized class, called refmatrix whose aim is just to manage references matrices. Look at matref.txt for explanations.
refer and capture
| refer | |
| Syntax | Y.refer(X); |
| Description | After this operation, Y shares the same datas as X. Every modification is done for both. We say that Y refers to X. |
| capture | |
| Syntax | Y.capture(X); |
| Description | Same as refer but the datas are cleared. |
change referencing
| refRowOf | |
| Syntax | X.refRowOf(Y, 5); X.refRowOf(Y, 2, 5); |
| Description | X is referencing a row submatrix of Y. First case, X is the 5th row, second case, X is the matrix from row 2 to row 5. |
| refColOf | |
| Syntax | X.refColOf(Y, 5); X.refColOf(Y, 2, 5); |
| Description | X is referencing a col submatrix of Y. First case, X is the 5th column, second case, X is the matrix from column 2 to column 5. |
| refSubOf | |
| Syntax | X.refSubOf(Y, 2, 4, 3, 5); |
| Description | X is referencing a sub submatrix of Y. In this case, X pointed to the bloc from rows 2 to 4 and from the columns 3 to 5. It’s a 3×3 matrix. |
temporary referencing
| row | |
| Syntax | X = Y.row(5); X = Y.row(2, 8); |
| Description | Allows you to use temporary reference to rows. In the first case, the 5th row only, in the second case, the bloc between row 2 and row 8. Example : X.row(2) = 1.0; set second row to 1 |
| col | |
| Syntax | X = Y.col(5); X = Y.col(2, 8); |
| Description | Allows you to use temporary reference to cols. In the first case, the 5th column only, in the second case, the bloc between column 2 and column 8. Example : Y.col(2, 8) = 5; set column 2 to 8 to value 5 |
| sub | |
| Syntax | X = Y.sub(1, 2, 3, 4); |
| Description | Return a temporary reference to the pointed submatrix. In this case, return a temporary matrix to bloc row 1 to 2 and column 3 to 4, it’s a 2×2 matrix. |
| diag | |
| Syntax | X = Y.diag(); X = Y.diag(-2); |
| Description | Return a temporary reference to the nth diagonal. In the first case, Y.diag() is a temporary reference to the diagonal and Y.diag(-2) to the second lower diagonal. |
submatrix copy
| rowOf | |
| Syntax | X.rowOf(Y, 7); X.rowOf(Y, 1, 5); |
| Description | Copy in X the submatrix of Y, the 7th row for the first case and the bloc between the 1st and 5th row in the second case. |
| colOf | |
| Syntax | X.colOf(Y, 7); X.colOf(Y, 1, 5); |
| Description | Copy in X the submatrix of Y, the 7th column for the first case and the bloc between the 1st and 5th column in the second case. |
| subOf | |
| Syntax | X.subOf(Y, 1, 5, 4, 7); |
| Description | Copy in X the submatrix of Y. In the example, it’s a 5 rows x 4 columns matrix, starting at row 1 and column 4. |
| diagOf | |
| Syntax | X.diagOf(Y); X.diagOf(Y, 2); |
| Description | Copy in X the nth diagonal. In the first case, just the diagonal, in the second the upper 2nd diagonal. |
| triuOf | |
| Syntax | X.triuOf(Y); X.triuOf(Y, 2); |
| Description | Copy in X the nth upper triangular matrix. |
| trilOf | |
| Syntax | X.trilOf(Y); X.trilOf(Y, 2); |
| Description | Copy in X the nth lower triangular matrix. |
submatrix set
| setRow | |
| Syntax | X.setRow(1, Y); |
| Description | Set the nth row of X with Y. Y must have the right size. |
| setCol | |
| Syntax | X.setCol(5, Y); |
| Description | Set the nth col of X with Y. Y must have the right size. |
| setSub | |
| Syntax | X.setSub(1, 5, 3, 5, Y); |
| Description | Set the submatrix of X with Y. Y must have the right size. |
| setDiag | |
| Syntax | X.setDiag(2.5); X.setDiag(2.5, -8); X.setDiag(Y); X.setDiag(Y, 2); |
| Description | Set the nth diagonal with a single scalar or a matrix. X.setDiag(2.5) the diagonal elements are set to 2.5. X.setDiag(2.5, 8) the 8th lower diagonal elements are set to 2.5. X.setDiag(Y) the diagonal elements are set with the vector Y. X.setDiag(Y, 2) the 2th upper diagonal elements are set with the vector Y. |
File matEXTRA.cpp : highly optimised functions
These functions are really optimized. There are directly calling the BLAS. Whenever you can use them, use them !
linear, AddMult
| linear | |
| Syntax | Z.linear(r1, X, Y); Z.linear(r1, X, r2); |
| Description | Computes in one function Z = alpha*X+Y or Z = alpha*X+beta. Is often used by built-in functions such as *Mult*. You can write this : Z.linear(r1, X, Z) where Z is reused as third argument. It allows you to optimize such things : Z += 1.5*X; don’t use this Z.linear(1.5, X, Z); use this |
| AddMult | |
| Syntax | X.AddMult(1.5, A, Z); |
| Description | Does in one function the multiplication of a matrix A with a vector Z, scaled with the scalar 1.5, and directly stored in the vector X. X += 1.5*A*Z; don’t use this X.AddMult(1,5, A, Z); // use this |
apply
| apply | |
| Syntax | X.apply(*cos); |
| Description | Apply a function that takes a double and return a double to every matrix element. In the example, every element is replaced by the cosines of it. |
maxabs and minabs
| maxabs | |
| Syntax | i = X.maxabs(); i = X.maxabs(15); |
| Description | Give the absolute biggest number in the specified column. When no column number is specified, it is the first. |
| minabs | |
| Syntax | i = X.minabs(); i = X.minabs(15); |
| Description | Give the absolute lowest number in the specified column. When no column number is specified, it is the first. |
