Matrix object methods

Matrix objects are responsible for providing algebraic operations over matrices and vectors. Common operations like addition, subtraction, multiplication by a scalar and multiplication by other matrices are defined with the usual semantics. Matrix objects also define some basic common operations like the transpose and the determinant. Vector objects are simply a column matrix.

Matrix and vector objects are returned by accessors when querying values for non scalar attributes and also by several other object methods, like shape function evaluation or returning cell node coordinates. New vectors and matrices can also be created by calling the Matrix() and Vector() functions.

Example:

local m1 = Matrix(3, 2)      -- New 3 x 2 matrix, initialized with zeros
local m2 = Matrix{{1, 0, 0}, -- New 3 x 3 identity matrix 
                  {0, 1, 0}, 
                  {0, 0, 1}} 

local v1 = Vector(3)       -- A (column) vector with 3 lines, initialized with zeros
local v2 = Vector{1, 2, 3} -- A (column) vector with 3 lines, initialized with values 1, 2 and 3
local v3 = Matrix{1, 2, 3} -- A vector equal to v2

local m3 = cell:nodeMatrix(coordAccessor)             -- Get the element node coordinate matrix
local v4 = cell:shape():shapeValues(Vector{0.0, 0.0}) -- N vector evaluated at natural coordinates (0, 0)

Index:

• Creating matrices and vectors
  • Matrix()
  • Vector()
• Size related methods
  • matrix:nlin()
  • matrix:ncol()
  • matrix:size()
• Querying and updating value methods
  • matrix:at()
  • matrix:set()
  • matrix:col()
  • matrix:line()
  • matrix:setCol()
  • matrix:setLine()
• Algebraic operations
  • Unary - operator
  • Binary +, -, / and % operators
  • Binary * operator
• Comparisson operations
  • == and ~= operators
  • matrix:equal()
• Other methods
  • matrix:t()
  • matrix:det()
  • vector:dot()
  • vector:cross()
  • vector:norm()
  • matrix:toTable()
  • matrix:solve()
  • matrix:inv()
  • matrix:eigSym()
  • matrix:print()
  • matrix:toString()

Creating matrices and vectors

Matrix(nlin, ncol) Matrix(values)
Description:	Creates a new matrix, with size either explicitly given by its number of lines and columns or implicitly given by the initialization data.
Parameters:	nlin, ncol	The number of lines and columns of the matrix. When this set of parameters is given, the matrix will be initialized with zeros.
	values	An initialization table. Can be a table of tables or a single table. In the second case, a matrix with a single column will be created. When this parameter is given, the matrix size will be inferred by the initialization table layout.
Returns:	Returns the new matrix object.

Example:

local m1 = Matrix(3, 2)                            -- New 3 x 2 matrix, initialized with zeros
local m2 = Matrix{{1, 0, 0}, {0, 1, 0}, {0, 0, 1}} -- New 3 x 3 identity matrix 
local m3 = Matrix{1, 2, 3}                         -- A vector (column matrix) with 3 lines 

Vector(nlin) Vector(values)
Description:	Creates a new vector (column matrix), with size either explicitly given by its number of lines or implicitly given by the initialization data.
Parameters:	nlin	The number of vector lines. When this parameter is given, the vector will be initialized with zeros.
	values	An initialization table. When this parameter is given, the vector size will be inferred by the initialization table layout.
Returns:	Returns the new vector (column matrix) object.

Example:

local v1 = Vector(3)       -- A (column) vector with 3 lines, initialized with zeros
local v2 = Vector{1, 2, 3} -- A (column) vector with 3 lines, initialized with values 1, 2 and 3

Size related methods

mat:nlin()
Description:	Returns the number of lines in the matrix or vector.
Parameters:	None.
Returns:	Returns the number of lines in the matrix.

Example:

local m = Matrix(3, 2)
local v = Vector(5)

assert(m:nlin() == 3)
assert(v:nlin() == 5)

mat:ncol()
Description:	Returns the number of columns in the matrix or vector.
Parameters:	None.
Returns:	Returns the number of columns in the matrix.

Example:

local m = Matrix(3, 2)
local v = Vector(5)

assert(m:ncol() == 2)
assert(v:ncol() == 1)

mat:size()
Description:	Returns the number of values (lines * columns) in the matrix or vector.
Parameters:	None.
Returns:	Returns the number of values (lines * columns) in the matrix.

Example:

local m = Matrix(3, 2)
local v = Vector(5)

assert(m:size() == 6)
assert(v:size() == 5)

Querying and updating value methods

mat:at(lin, col) vec:at(lin) mat(lin, col) vec(lin)
Description:	Returns the value of one matrix / vector entry.
Parameters:	lin, col - The line and column defining the matrix position to be returned. Vectors (column matrices) can be indexed with a line only. As a convenience, the syntax mat(line, column) is a shorthand for mat:at(line, column), and vec(line) a shorthand for vec:at(line). IMPORTANT: like any Lua table, line and column indices are indexed from 1 (and not zero).
Returns:	Returns the requested matrix value.

Example:

local m = Matrix{{11, 12}, {21, 22}}
local v = Vector{11, 12, 13}

assert(m:at(1, 2) == 12)
assert(m(1, 2) == 12)
assert(v:at(3) == 13)
assert(v(3) == 13)

local m2 = Matrix{100, 200, 300}  -- A column matrix, i.e., a vector.
assert(m2(2)    == 200)
assert(m2(2, 1) == 200)

mat:set(lin, col, val) vec:set(lin, val) mat:set(scalarVal) mat:set(valuesTable)
Description:	Updates the value of one matrix / vector entry for versions taking an index (line and column for matrices, just line for vectors) and a value. Updates the whole matrix contents for versions taking a single value parameter.
Parameters:	lin, col	The line and column defining the matrix position to be updated. Vectors (column matrices) can be indexed with a line only. IMPORTANT: like any Lua table, line and column indices are indexed from 1 (and not zero).
	val	The value to be set for versions taking a line, column index.
	scalarVal	A single value that will be set over the whole matrix / vector, if this is the single set() parameter.
	valuesTable	A table with new matrix / vector values for all its entries, either given as a table of tables (each sub-table storing one line's values) or as a flat table linearized in column major order (FORTRAN style). The given table must have exactly the same number of values and layout as the matrix object. No matrix resizing is allowed.
Returns:	Nothing.

Example:

local m = Matrix{{11, 12}, {21, 22}}
local v = Vector{11, 12, 13}

m:set(2, 1, 999)          -- New matrix contents = {{ 11,  12}, {999,  22}}
m:set(0)                  -- New matrix contents = {{  0,   0}, {  0,   0}}
m:set{{11, 12}, {21, 22}} -- New matrix contents = {{ 11,  12}, { 21,  22}}
m:set{100, 200, 300, 400} -- New matrix contents = {{100, 300}, {200, 400}}

v:set(2, 999)             -- New vector contents = { 11, 999,  13}
v:set(0)                  -- New vector contents = {  0,   0,   0}
v:set{100, 200, 300}      -- New vector contents = {100, 200, 300}

mat:col(col)
Description:	Returns the matrix data in the given column as a column vector.
Parameters:	col - The column number.
Returns:	Returns the requested matrix column as a new vector.

Example:

local m = Matrix{{11, 12, 13}, 
                 {21, 22, 23},
                 {31, 32, 33}}

local col2 = m:col(2)
assert(col2:nlin() == 3)
assert(col2:ncol() == 1)

assert(col2(1) == 12)
assert(col2(2) == 22)
assert(col2(3) == 32)

mat:line(lin)
Description:	Returns the matrix data in the given line as a row vector (a matrix with one line).
Parameters:	row - The line number.
Returns:	Returns the requested matrix line as a new matrix.

Example:

local m = Matrix{{11, 12, 13}, 
                 {21, 22, 23},
                 {31, 32, 33}}

local row2 = m:line(2)
assert(row2:nlin() == 1)
assert(row2:ncol() == 3)

assert(row2(1, 1) == 21)
assert(row2(1, 2) == 22)
assert(row2(1, 3) == 23)

mat:setCol(col, val)
Description:	Updates the contents of a matrix column with the values in the given column vector or Lua table.
Parameters:	col	The column to be updated. IMPORTANT: like any Lua table, column indices are indexed from 1 (and not zero).
	val	Either a vector object or a Lua table with the new column contents, with size equal to the number of matrix lines. When val is a Lua table, it is usually a flat table, but can also be table of tables representing a column matrix.
Returns:	Nothing.

Example:

local m = Matrix{{11, 12}, {21, 22}}
local v = Vector{50, 70}

m:setCol(1, v)              -- New matrix contents = {{50, 12}, {70, 22}}
m:setCol(2, {60, 80})       -- New matrix contents = {{50, 60}, {70, 80}}
m:setCol(2, {{62}, {82}})   -- Unusual but valid. New matrix contents = {{50, 62}, {70, 82}}

local m2 = Matrix{{1, 2}, {3, 4}}
m:setCol(2, m2:col(2))      -- New matrix contents = {{50, 2}, {70, 4}}
m:setCol(1, m2:line(1):t()) -- New matrix contents = {{ 1, 2}, { 2, 4}}

mat:setLine(lin, val)
Description:	Updates the contents of a matrix line with the values in the given row matrix or Lua table.
Parameters:	lin	The line to be updated. IMPORTANT: like any Lua table, line indices are indexed from 1 (and not zero).
	val	Either a row matrix object or a Lua table with the new line contents, with size equal to the number of matrix columns. When val is a Lua table, it is usually a flat table, but can also be table of tables representing a row matrix.
Returns:	Nothing.

Example:

local m = Matrix{{11, 12}, {21, 22}}
local v = Vector{50, 70} -- A column matrix (vector), NOT a row matrix

m:setLine(1, v:t())         -- New matrix contents = {{50, 70}, {21, 22}}
m:setLine(2, {60, 80})      -- New matrix contents = {{50, 70}, {60, 80}}
m:setLine(2, {{62, 82}})    -- Unusual but valid. New matrix contents = {{50, 70}, {62, 82}}

local m2 = Matrix{{1, 2}, {3, 4}}
m:setLine(2, m2:line(2))    -- New matrix contents = {{50, 70}, { 3, 4}}
m:setLine(1, m2:col(1):t()) -- New matrix contents = {{ 1,  3}, { 3, 4}}

Algebraic operations

"Unary -" operator

Unary - operator
Description:	The unary minus (-) operator is applied to each matrix / vector element and returns a new matrix with the signal exchanged for each of its elements.
Parameters:	A matrix object.
Returns:	Returns a new matrix object.

Example:

local m = Matrix{{1, 2, 3}, 
                 {4, 5, 6}}

assert(-m == Matrix{{-1,-2,-3},{-4,-5,-6}})
assert(-(-m) == m)

Binary +, -, / and % operators
Description:	The standard binary +, - and / operations for matrix / vector objects. They are applied between each corresponding element of the two matrices or between a matrix element and a scalar. The % operator does an element wise multiplication for two matrices (not the standrad matrix multiplication).
Parameters:	Two parameters, that can be numbers or matrices, with at least one of them being a matrix. If two matrices are given, they must have the same size.
Returns:	Returns a new matrix object.

Example:

local m1 = Matrix{{1, 2, 3}, 
                  {4, 5, 6}}

local m2 = 2 + m1        -- m2 == {{3, 4, 5}, {6,  7,  8}}
local m2 = m2 + 3        -- m2 == {{6, 7, 8}, {9, 10, 11}}

local m3 = m1 + m2 + 10  -- m3 == {{17, 19, 21}, {23, 25, 27}} 

local m4 = (m2 - m1) / 5 -- m4 == {{1, 1, 1}, {1, 1, 1}}

loval v1 = Vector{10, 15} / Vector{2, 5}         -- v1 == {5, 3}
local m5 = Matrix{{1, 2, 3}} % Matrix{{2, 3, 4}} -- m5 == {{2, 6, 12}}

Binary * operator
Description:	The standard * operator for matrix and vector objects. When applied between a scalar and a matrix, every matrix element is multipled by the scalar value. When applied between two matrices, the usuall matrix multiplication rules apply.
Parameters:	Two parameters, that can be numbers or matrices, with at least one of them being a matrix. If two matrices are given, they must have sizes compatible with matrix multiplication rules.
Returns:	Returns a new matrix object.

Example:

local m = Matrix{{2, 3,  4}, 
                 {5, 6,  7}, 
                 {8, 9, 10}}
local v = Vector{1, 2, 3}

assert(2 * m == Matrix{{4, 6, 8}, {10, 12, 14}, {16, 18, 20}})
assert(m * 2 == Matrix{{4, 6, 8}, {10, 12, 14}, {16, 18, 20}})

assert(3 * v == Vector{3, 6, 9})
assert(v * 3 == Vector{3, 6, 9})

assert(m * v == Vector{2+6+12, 5+12+21, 8+18+30})

local B = {{1, 2},
           {3, 4}, 
           {5, 6}}

local K = {{10, 20},
           {30, 40}}

local r = B * K * B:t() -- A 3 x 3 matrix with the result of multiplying B by K and then by B transposed.

Comparisson operations

== and ~= operators
Description:	The standard == and ~= operators for matrix and vector objects. Two matrices will be considered equal if they have the same size and each individual element in the first matrix is equal to the corresponding element on the second one. IMPORTANT: This operations are meaningfull mostly for matrices with integer values since floating point values are compared without any tolerance. See the mat:equal() method for an alternative approach.
Parameters:	Two matrix objects.
Returns:	Returns true or false depending on the matrices being equal or not.

Example:

assert(Matrix{{1, 2}, {3, 4}} == Matrix{{1, 2}, {3, 4}})
assert(Matrix{{1, 2}, {3, 4}} ~= Matrix{{1, 2}})
assert(Matrix{{1, 2}, {3, 4}} ~= Matrix{{1, 2}, {3, 5}})

mat:equal(otherMat, relTol, absTol)
Description:	Compares the object matrix with the other given matrix using the equal() function for comparing each matrix number. Two matrices will be considered equal if they have the same size and each individual element in the first matrix compares equal to the corresponding element on the second one.
Parameters:	otherMat	The other matrix with which the object matrix will be compared.
	relTol	The relative tolerance used for comparisson. Two numbers a and b are considered equal if their absolute difference is smaller or equal to relTol * max(a, b). Default = 1e-8 (0.000001%).
	absTol	Absolute tolerance used for comparisson between values close to zero. Default = 1e-12.
Returns:	Returns true if the matrices are equal, false if not.

Example:

local m = Matrix{{1.0, 2.0}, {3.0, 4.0}} 
  
assert(m:equal(Matrix{{0.999999999, 2.0}, {3.0, 4.0}}) == true)

assert(m:equal(Matrix{{ 1.0001, 2.0}, {3.0, 4.0}}) == false)
assert(m:equal(Matrix{{ 1.0001, 2.0}, {3.0, 4.0}}, 1e-3) == true)

Other methods

mat:t()
Description:	Returns a new matrix with the transpose of the current matrix.
Parameters:	None.
Returns:	Returns the transposed matrix.

Example:

local m = Matrix{{1, 2, 3, 4}, 
                 {5, 6, 7, 8}}

local v = Vector{1, 2, 3}

assert(m:t() == Matrix{{1, 5}, {2, 6}, {3, 7}, {4, 8}})
assert(v:t() == Matrix{{1, 2, 3}}) 

mat:det()
Description:	Returns the determinant of a square matrix
Parameters:	None.
Returns:	Returns the matrix determinant.

Example:

assert(Matrix{{1, 2}, {3, 4}}:det() == 1 * 4 - 3 * 2)

vec:dot(otherVec)
Description:	Returns the dot product between the vector and the given other vector. Vectors must be of the same size.
Parameters:	The second vector for the dot product.
Returns:	Returns the dot product value (a scalar number).

Example:

local v1 = {1, 2, 3}
local v2 = {4, 5, 6}

assert(v1:dot(v2) == 1*4 + 2*5 + 3*6)

vec:cross(otherVec)
Description:	Returns the cross product between the vector and the given other vector. Vectors must have 3 components each.
Parameters:	The second vector for the cross product.
Returns:	Returns the cross product value (another column vector with 3 lines).

Example:

local v1 = {1, 2, 3}
local v2 = {4, 5, 6}

local c = v1:cross(v2)
assert(c:equal(Vector{-3, 6, -3}))

mat:norm()
Description:	Returns the Euclidian norm of the vector. Not valid for matrix objects.
Parameters:	None.
Returns:	Returns the vector norm.

Example:

assert(Vector{3, 4, 5}:norm() == math.sqrt(3*3 + 4*4 + 5*5)

mat:toTable()
Description:	Returns a Lua table serializing the matrix contents using a column major format (FORTRAN style).
Parameters:	None.
Returns:	Returns the matrix equivalent Lua table.

Example:

local t = Matrix{{1, 2}, {3, 4}}:toTable()     -- t == {1, 3, 2, 4}

mat:solve(b)
Description:	Solves a linear system of equations Ax = b, where A is the current matrix, b is the given vector (or matrix) and x is the returned result. Solved using Armadillo's solve() method. Accepts non square matrices where the number of rows in A is equal to the number of rows in b.
Parameters:	The b matrix.
Returns:	Returns the result matrix (vector) or nil if the system could not be solved.

Example:

-- Solve system  [[ 3, 2]   * [[x]   = [[11]
--                [-1, 1]]     [y]]     [ 3]]

local A = Matrix{{ 3, 2}, 
                  {-1, 1}}
local b = Vector{11, 3}

local x = A:solve(b)  -- x == Vector{1, 4} 

mat:inv()
Description:	Returns the inverse of the current square matrix or nil if the matrix is not invertible. Solved using Armadillo's inv() method.
Parameters:	None
Returns:	Returns the inverse matrix or nil if the matrix is not invertible.

Example:

local A = Matrix{{ 3, 2}, 
                 {-1, 1}}

local Ai = A:inv()   -- Ai = {{1/5, -2/5}, {1/5, 3/5}}

local I = Matrix{{1, 0}, {0, 1}}
assert(I:equal(A * Ai)) 

mat:eigSym()
Description:	Calculates the eigen values and eigen vectors of a symmetric matrix. Solved using Armadillo's eig_sym() method.
Parameters:	None.
Returns:	Returns the eigen values as a column vector and the eigen vectors as a matrix with vectors in columns.

Example:

local A = Matrix{{1, 2, 3},
                 {2, 2, 4},
                 {3, 4, 3}}
local val, vec = A:eigSym()

val:print()   -- print the calculated eigen values
vec:print()   -- print the calculated eigen vectors, stored as columns in the matrix

local v1 = vec:col(1)  -- The first eigen vector

local x = A*v1
local y = val(1)*v1
assert(x:equal(y))

mat:print(format)
Description:	Prints the object matrix.
Parameters:	Optional string using printf like format (ex: '10.4f'), used to format the printed numbers.
Returns:	Nothing.

Example:

local m = Matrix{{1, 2, 3, 4}, 
                 {5, 6, 7, 8}}

m:print()
m:print('5.2f')

mat:toString(format)
Description:	Serializes the object matrix to a formatted string.
Parameters:	Optional string using printf like format (ex: '10.4f'), used to format the printed numbers.
Returns:	The serialized matrix as a string.

Example:

local m = Matrix{{1, 2, 3, 4}, 
                 {5, 6, 7, 8}}

print(m:toString())  -- Will print: "[1, 2, 3, 4], [5, 6, 7, 8]"
print(m:toString('5.2f'))