Module tmath

Overview

The module tmath provides data types and algorithms for basic linear algebra. It was attempted to provide a natural access to the mathematical grammar, thus, merging the programming idioms of Lua, C++ and arithmetic languages like MATLAB (TM).

The package is, however, embedded into the language Lua and is, thus, dependent on its logic and syntax. Therefore, sometimes the syntax appears uncommon. For example, any object has a certain datatype. Functions can only be applied to objects of specific datatypes. The same is true for operators and methods which are tied to their lefthand argument. For example, the "*" operator is attached to its left hand neighbour. In programming languages, the terms "A*B" and "A:operator*(B)" are equivalent. Since we can define operators for our own datatypes, but not for Lua's internal "number" type, we can provide the operator "matrix*number", but not "number*matrix".

Dense linear algebra

Creating matrices

There are several ways to create matrices. The simpliest way is to call its constructor

A = tmath.Matrix(3,4) -- create 3x4 matrix
B = tmath.Matrix(3) -- create 3x1 vector (of type Matrix)
C = tmath.Vector(3) -- create 3x1 vector (of type Matrix)

Calling the constructor will only create and return an object of type "Matrix" of the specified size, but without initializing the values. Although the uninitialized values are around zero on most computers, initial values must be assigned by a separate command, e.g.

A = tmath.Matrix (3 ,4)
value = 2.1; value1 = 1
value2 = 2
A:SetZero() -- zero matrix
A:SetOnes() -- all elements are ”1”
A:SetConstant(value) -- all elements are =”value”
A:SetIdentity() -- (rectangular) identity matrix
A:SetLinearCols(value1, value2) -- linear columns from value1 to value2
A:SetLinearRows(value1, value2) -- linear rows
A:SetRandom() -- random numbers ( -1 .. 1 )

To simplify creation and initialization convenience functions are defined such as

A = tmath.Identity(3) -- 3x3 identity matrix
A = tmath.ZeroMatrix(3, 4)
B = tmath.ZeroVector(4)

It is also possible to read the contents of matrices from input

A = tmath.Matrix(2, 3)
tmath.Read(A, 1, 2, 3, 4, 5, 6)
-- even better ( using 2−dimensional Lua tables as input )
B = tmath.Matrix( {{1 ,2 ,3}, {4 ,5 ,6}} );

When defining a matrix by Lua tables, it is possible to combine existing matrix objects. These objects will be interpreted as row vectors:

A = tmath.ZeroVector (4)
B = tmath.Identity (2)
C = tmath.Matrix ({ A, -- 0 0 0 0
{5,6,7,8}, -- 5 6 7 8
B }) -- 1 0 0 1

Assigning values

Assigning values to objects may differ in various programming languages. In C++ and MATLAB the contents of an object is copied into the other. In Lua, however, only a new identifier is created for the right hand object, i.e. Lua's assign command

A = tmath.ZeroVector(3) -- create a new Matrix object and assign it to ident "A"
B = A -- assign the object behind "A" to the ident "B"

will create the identifier "B" which refers to the same matrix object as "A" (The first command will create a Matrix object on the right hand side and assign it to the identifier "A" on its left side).

As long as new objects will be created on the right side, the assign operator is equal to what is known from C++ , i.e.

A = tmath.Identity(3)>
B = A*(-3) + tmath.Identity(3)

Herein, the arithmetic operators always create and return new temporary objects of type Matrix. The last created object will then be assigned to the identifier "B".

If the value should be assigned (and not the object itself) then tmath provides copy constructors for many data types, i.e.

A = tmath.ZeroVector(3) -- create a new Matrix object and assign it to ident "A"
B = tmath.Matrix(A) -- create a new Matrix object which has equal content with "A" and assign it to ident "B"

There are some case, where the "=" operator is not applicable. Then the only way to copy data is to use the "Assign" method. This may happen if you want to assign a value to a matrix which is part of another userdata object. For example, there is a finite element object which stores a force vector and gives access to it via a referencing method:

force = fem_object:RestoringForce() -- call the method to return a reference to a Matrix object stored in "fem_object"
force = tmath.Matrix(fem_object:RestoringForce()) -- create a copy of the internal force vector
B = tmath.Vector(force:Rows())>
fem_object:RestoringForce() = B -- will produce an error because the left side is a userdata
fem_object:RestoringForce():Assign( B ) -- will copy the contents from "B" to "fem_object:RestoringForce()"

For such cases, the Matrix class is equipped with the method "Assign" which directly assigns the given value to itself.

A very fast way to transfer data is the "Swap" method which swaps the pointer to the data buffer of two Matrix objects:

A = tmath.Identity(3)
B = tmath.ZeroVector(4)
B:Swap(A); -- "A" will now be a zero vector, "B" is an identity matrix