LightMat - USER MANUAL

By Vadim Engelson and Tommy Persson. Some material is adapted from Anders Gertz' master thesis.

• What is LightMat
• Installation notes and examples
• The Different Classes
• Constructors and access to arrays
• Indexing
• LightMat arithmetic operations and functions

What is LightMat

LightMat is a collection of C++ classes that provide storage in memory, access and mathematical operations on arrays or tensors. LightMat currently supports arrays of rank 1,2,3 and 4 and can be extended to higher dimensions if needed. Each array is stored as a C++ object, which can be defined and manipulated by corresponding C++ methods. To use LightMat you need just to write the following lines:

#define LM_ALL
#include "lightmat.h"

at the start of your code and add some object files when linking the application.

• This guide (which is a single HTML document) should help you to choose appropriate array classes for your application.
• First you install the library on your computer. Read Installation notes and examplesbelow.
• Read the chapter The Different Classes which presents the classes of the library.
• Then you have to declare your variables. Read the chapter Constructors and Access to Arrays
• If you want to do some mathematics, read the chapter LightMat arithmetic operations and functions.
• If You want to call BLAS or LAPACK, read the chapter ???

If you are interested in more details, read the Implementation notes and Optimization (in a separate page).

Some options are not implemented yet, but will be available in the next versions.

Installation notes and examples

• Available platforms and compilers
• Download and compilation
• How to use the library
  • Using inlined functions, example
  • Using non-inlined functions, example
  • Reducing compilation time for non-inlined functions, example
  • Compiling several files into one executable
• Preprocessor options

Available platforms and compilers

If you use one of these compilers there should be no problems in compilation. Otherwise there is a chance that some small modifications should be introduced in the code. Please, let us know about your modifications.

Download and compilation

You download the library from the LightMat home page at http://www.ida.liu.se/~pelab/lightmat.

• for UNIX - gzipped tar-ed file, like this: lightmat077.tar.gz
• for Windows - zipped like this: lightmat077.zip

After un-zipping you can go to the "src" subdirectory. Compilation can take some 4-5 minutes on a 133MHz Pentium processor. You must have 70MB free on the Windows disk where your swap file is located (usually in C:\WINDOWS).

• On UNIX you compile by make -f make.unx
• On Windows with VisualC++ you compile by nmake -f make.win

The code will not work on 8.3 file systems like Windows 3.1 (long file names are used). As result of compilation all necessary object files in the LightMat library are created.

Testing

It is important to test the library before using it on your platform. A number of predefined test cases are included with the library.

• On UNIX you compile by make -f make.unx all
• On DOS with VisualC++ you compile by nmake -f make.win all

Several executable files are created. It can take 4-5 minutes on a 133MHz Pentium laptop. The make utility automatically runs the test. If there were no assertion violations and no core dumps, then, presumably you can use the code further, e.g. writing new applications from scratch or modifying the supplied test cases.

How to use the library

The test cases in subdirectory tst of the distribution show two different ways of using the library: using inlined functions or non-inlined functions.
The execution is identical, but compilation in different.

Using inlined functions

This variant gives the fastest code, but slow compilation. In your files you specify:

#define LM_ALL
#include "lightmat.h"

You compile your files with the usual compilation flags. Compilation usually takes one or more minutes. You link your object files with cstring.o and extwin.o. For example the file foo.cpp (the default extension .cpp is used for MicroSoft Visual C++ files) contains:

#define LM_ALL
#include <lightmat.h>
int main(){
  doubleNNN f(5,6,7,3.11);
  cout << f;
  return 0;
}

Compile with GNU C++ (assuming that LightMat is installed in the directory ???)

g++ foo.cpp -I../include ../obj/cstring.o ../obj/extwin.o -lm

or Visual C++:

foo.cpp -I..\include ..\obj\cstring.o ..\obj\extwin.o 

Note: Both forward slash and backslash can be used as directory separators with cl.

Using non-inlined functions

This variant gives slower code (although still reasonably fast), but significantly faster compilation. In your files you specify:

#define LM_ALL
#include <lightmat.h>


You compile your files with the usual flags and -DNOT_INLINED. You link your files with cstring.o, extwin.o and not_inlined.o.

All the library functions are non inlined. This gives reasonable, but not the highest performance. Each time you compile your file, it will take less than 1 minute. For example the file foo.cpp contains:

#define LM_ALL
#include <lightmat.h>
int main(){
  doubleNNN f(5,6,7,3.11);
   cout <<f;
  return 0;
}

Compile with

g++ foo.cpp -I../include  -DNOT_INLINED ../obj/cstring.o ../obj/extwin.o ../obj/not_inlined.o -lm

or

cl foo.cpp -I..\include  -DNOT_INLINED ..\obj\cstring.o ..\obj\extwin.o ..\obj\not_inlined.o -lm

Reducing compilation time for non-inlined functions.

If you use only a subset of the LightMat classes you can reduce compilation time for your code. Use a preprocessor definition #define LM_name for each class you use. Names of these definitions are given in the table of classes. Important: This option can be used only with the flag -DNOT_INLINED. #define LM_ALL means that you use all available classes. For example the file foo1.cpp contains:

#define LM_N
#include <lightmat.h>
int main(){
  doubleN x(5,2.0);
  cout << x; 
  //doubleNN y(3,4);- Forbidden
  // This is not allowed because this class requires LM_NN.
  // Compiler reports an error.
  return 0;
}

Compile with

g++ foo1.cpp -I../include  -DNOT_INLINED ../obj/cstring.o ../obj/extwin.o ../obj/not_inlined.o -lm

or

cl foo1.cpp -I..\include -DNOT_INLINED ..\obj\cstring.o ..\obj\extwin.o ..\obj\not_inlined.o

Compiling several files into one executable.

If you compile several files into a single executable, the following holds:

• Either all files must be compiled with -DNOT_INLINED flag
• Or all files must be compiled without -DNOT_INLINED flag

Complex type

The library includes implementation of complex numbers. The class for a stand-alone complex number used is called lm_complex. This should not be mixed with <complex> template from Standard C++ library.  

String type

The library includes implementation of strings. The class for a stand-alone string used is called string. This is the same as std::string from standard C++ library.

Boolean type

 There is no need in a special boolean type - they are implemented via integer types. However all boolean operations (not, and, or) should be defined  for all intege-based lightmat types. The value 1 stands for true, 0 for false in boolean operation results.

Preprocessor definitions

In the file lightmat.h (or lightmat_id.h) there are a number of preprocessor definitions that can be changed. Those definitions are:

If preprocessor definitions change, all application files referring to LightMat should be recompiled.

The Different Classes

• Definitions
• Class table
• Class names
• Specially optimized classes for certain sizes
• Constructors and access to arrays
  • Constructors
  • Destructors
  • Assignment
  • Set() and Get()
  • dimension()
  • Equality and inequality
  • Promoting to higher dimensions
  • Constructing arrays in a function call
• Indexing
  • Index argument
  • Indexing of individual elements
  • Array extraction using operator()
  • Set()
• Setting shape - SetShape()
• Internal data - data()
• Output functions

Definitions

We will need some definitions first:

• Scalar - an elementary data type like double or int
• Array - a data structure with many scalar elements; array elements can be accessed by indexing.
• Vector - a one-dimensional array, array of rank 1, implemented by class lightN.
• Matrix - a two-dimensional array, array of rank 2, implemented by class lightNN.
• Tensor3 (tensor of rank 3) a three-dimensional array, e.g. lightNNN.
• Tensor4 (tensor of rank 4) a four-dimensional array, e.g. lightNNNN.

There exist 8 different classes for vectors, matrices, tensors of rank 3 and tensors of rank 4. There are 4 universal classes and 4 specially optimized classes. The specially optimized classes can be used in particular application areas: for instance matrix of dimension 3x3 is used in geometry and 4x4 in computer graphics. If you are not sure which classes to use then use universal classes.

CLASS TABLE

Note on higher ranks: There are no classes for tensors of higher ranks larger than 4. It is possible to add support for that in the future though. Having different classes for vectors, matrices etc is quite natural, and that's what most other packages also have chosen. Other packages sometimes have one class for tensors of high ranks, but that does not exist in LightMat. Having different classes for the different ranks also avoids run-time choices of what algorithm, for the different ranks, that should be used.

Note on internal class names: The class names in the ...???

Class names

Array classes for elements of type int and double are implemented. The user declares a variable as follows:

double4 foo

This means that foo is a vector with 4 elements of type double. All available class names are given in the class table above. The properties of classes with elements of type int and double are very similar. For instance, by classes with suffix 3 is usually meant both classes int3 and double3.

Specially optimized classes for certain sizes

Extra optimized classes (suffixes 3, 4, 33, 44) have been implemented for some specific sizes of vectors and matrices for double and int. Those are vectors of length 3 and 4, and matrices of size 3x3 and 4x4. They have, of course, a stack allocated memory area for the elements. That means that the compiler can generate code which need fewer references through pointers. Code for calculations is written especially suited to those sizes. Calculation loops are completely unrolled. This makes these classes extra fast computationally.

These classes, though, can also interface with the other existing classes in lightmat.

Since the sizes of objects of these classes are partially or totally fixed they cannot dynamically change their sizes as freely as the universal LightMat classes.

Constructors and access to arrays

All LightMat classes have some basic member functions like constructors, destructors, assignment operators and a few more.

Constructors

There exist a number of constructors, with different arguments, with which a new object can be created. The reasons for having several different constructors are efficiency and ease of use.

• No arguments. These default constructors create an object with a default size (given in the class table above). For example:

  intNN a;
doubleNN b;
stringNNN c;
lm_complexNNNN p;  

• An object of the same class as the only argument. This is the normal copy constructor. I.e. the new object is a copy of the argument. The two objects will not share the same data area. For example suppose that a is of type doubleNN and d is of type intNNN:

  doubleNN b = a;
intNNN c = d;

• Integer arguments. The integers arguments specify the size of the created object, e.g. 3 and 5 should be provided as arguments to the constructor in order to construct a 3x5 matrix. A 4-dimensional array 3x5x2x4 can be constructed in a similar way. For example:

  doubleNN a(3,5);
intNNNN c(3,5,2,4);

• Objects of another class as the only argument. This creates an object with the same size and values in its elements as the argument. A vector can, of course, not be created from, for example, a matrix though. Both data types should have the same rank. The values are copied from the object given as an argument since all objects have their own data areas.

  double33 a;
doubleNN c = a;

  Such constructors are also called converters. There are converters for the following cases:

  • conversion of arrays with integer elements to arrays with double elements (intN to doubleN)
  • conversion of arrays with integer elements to arrays with complex elements (intN to complexN)
  • conversion of arrays with double elements to arrays with complex elements (doubleN to complexN)
  • conversion of arrays with special size to universal arrays. There are no special size arrays for lm_complex and string .  The following conversion constructors are used:

    From	to
    int3	intN
    int4	intN
    int33	intNN
    int44	intNN
    double3	doubleN
    double4	doubleN
    double33	doubleNN
    double44	doubleNN

• Integer arguments and a pointer to a memory area. The integers specify the size of the created object and the elements are initialized from the values in the memory area. The values in the memory area should be stored in row major order (C++ style), since this is how C++ lays out constant arrays. For example:

  double arr[] = { 1.3, 2.6, 3, 4, 5.7, 6 };
doubleNN  a(2,3,arr);

  The same result can be achieved by writing a loop:

  doubleNN a(2,3);
idx=0;
for(inti=1;i<=2;i++)< br>  for(intj=1;j<=3;j++)
     a(i,j)=arr[idx++];

• Integer arguments and a value. The integers specify the size of the created object and all elements in the object are initialized to the supplied value. Only one value can be given. For example:

  doubleNN a(3, 4, 17.7);
lm_complexNN b(3, 5, lm_complex(7.0,6.0));

• Arguments with the values for all elements. These constructors exist only for the classes which have a fixed number of elements (light3, light4, light33 and light44). The values for the elements should be given in row major order.

  double33 a(1.1, 2, 3.5, 4, 5, 6.9, 7, 8.3, 9);

Element initialization

If values for the elements are not supplied in the constructor, the initialization behaviour depends on preprocessor definition LIGHTMAT_INIT_ZERO (see preprocessor definition table above.) If it is defined, the elements are initialized to zero. Otherwise, the elements are not initialized. This saves some time. It can be a good idea not todefine LIGHTMAT_INIT_ZERO if the user knows that objects are never used without explicit initialization. Functions within the classes that do calculations and need a local object use a special internal protected constructor that never initializes the elements.

Memory allocation

The LightMat constructors automatically allocate dynamic memory on the heap if the pre-allocated memory area (area allocated by default on the stack) is not sufficiently large. The class table above describes the size of memory allocated by default on the stack.

Destructors

The destructors free any memory which might have been allocated on the heap.

Assignment

The assignment operators copy values from the elements in one array object to another. The array objects can be of different size, but the rank must be the same. The right-hand operand can however be scalar. The size of the left-hand operand is changed to the size of the right-hand operand if needed. More memory is also allocated if needed.

Note: Memory is not deallocated even if the objects need of memory decreases. The reason is that deallocation and the sometimes following allocation of a smaller memory area takes time. There may also, later in the calculations, once again be a need of a larger memory area in which case another reallocation would be needed once again.

doubleNN a(2,3), b(3,2);
a = b;      // a becomes 3x2
a = 5.7;    // all elements of a become 5.7

Assignment from a scalar will set all the elements in the object to that value. Read the section about indexing on how to assign a value to an element of array.

``Memory'' Set() and Get()

All classes have member functions Get and Set which takes a pointer to a memory area as argument. Set will set the elements in the object from the values which are stored in the memory area. Get does the opposite. The elements are stored in row major order (C++ style) in the memory area. No bounds check is performed. For example:

doubleNN a(5,6,17.7), b(5,6);
double arr[30];
a.Get(arr);    // a --> arr
b.Set(arr);    // arr --> b


dimension()

The size of a dimension of an array object can be found with the function dimension(). It takes an integer argument which should specify the dimension. The argument should, for example, be 1 for the number of rows in a matrix, and 2 for the number of columns. Thus, a a.dimensions(1) returns the size of the list dimension of a, a.dimensions(2) returns the size of the second dimension, etc.

Equality and inequality

The usual operators for equality and inequality exist for all classes. Two objects are considered equal if they have the same size and if the values of all corresponding elements are equal. Only arrays of the same rank can be compared. For example:

if(a == b ?? c != d) { /* something */ }

Promoting to higher dimensions

A function named reshape is used to promote an object of rank n to another object of rank n+1. E.g. a vector can be promoted to a matrix and all the columns in the matrix will then be given the values of the vector. For example:

doubleN v(3);
doubleNN a;
a.reshape(3,5,v);  // a becomes 3x5


Constructing arrays in a function call

The function make_lightN() is not a method of a class, but a friend function. You can use it for construction of an array from its components. Given several arrays of rank n it constructs an array of rank n+1. The number of components should be specified as the first argument. Obviously, the dimensions and element types of all arrays should be the same. Not more than 10 parameters can be given in the argument list.

lightNN a;
a=make_lightN(2, make_lightN( 3, 11,12,13), make_lightN( 3, 14,15,16));

This code creates array 2x3 of integers from 11 to 16. Specification is always given in row-major order. Note: This function is very time and space consuming. Therefore use Set() if you are interested in higher performance.

Indexing

The indexes in LightMat arrays starts at 1, like in Fortran, Matlab and Mathematica, not at 0 like in C. For matrices the first coordinate is usually named "row" and the second "column". Bound check in indexing operations can be turned on or off by preprocessor definitions. There is indexing for individual elements, indexing for array extraction and special indexing for Set().

Index arguments

The index argument to operator () and Set can be of the following types:

• An integer.
• A range, that is an object of the type R.

The class R contains a start index and an end index. Both are integers. This specifies a range (which includes the indexes). There is a constructor taking two arguments, that is start index and end index. For example:

lightNN a(7, 9);
lightN b(3);
b = c(3, R(4, 6));
// Equivalent to b = make_lightN (c(3,4), c(3,5), c(3,6))

Suppose that the range operator is used to index a range in an object where the dimension of the indexed position is size. Then the following trasformations are done:

• All -> R(1, -1)
• R(imin, imax) -> R(imin+size+1, imax) if imin<0
• R(imin, imax) -> R(imax+size+1, imax) if imax<0

After these transformations a limit check is done (if required). If imax == 0 or imin == size+1 then the range is assumed to contain zero elements and the limit check does not fail. Otherwise it is required that imax-imin+1 > size.

If the size of the range is zero then the Set method does not do anything and the operator() method return an object with size zero.

Suppose that a is intNNNN and mat is intNN and we have the following method call: Set (2, range1, 3, range2, mat). Then if limit checks are done it is checked that the size of range1 is less than mat.dimension (1) and that the size of range2 is less than mat.dimension (2).

Indexing of individual elements

Individual elements can be indexed with the parentheses operator. The indexed element can be either an l-value or an r-value. The number of indexes should be equal to the rank of the array.

doubleNN a(5,3);
a(1,1) = a(2,3);

Array extraction using operator()

Arrays can be extracted from arrays of higher dimensions using the range class as index argument for operator(). The result can only be used as an r-value, and the indexed elements are copied in the process. The elements need to be copied since the concept of different views of the same data does not exist in this design. Note that this is relatively expensive operation. If the result is used as a l-value, the assignment result is simply discarded.

doubleN v;
doubleNN a(5, 5);
doubleNNN c(7, 8, 9);
v = a(4, All);
v = c(4, 5, All);
a = c(All, 3, All);
a(1, All) = v; // The result is discarded, and matrix a does not change.
double3 w;
m(3) = w + m(2); // This class is exception, m changes.

Set()

The method Set() is used to set a slice of an object to the value of another object. For example:

doubleN v(3);
doubleNN a(5, 5);
doubleNNN c(7, 8, 9);
a.Set(1, All, v); // Error because a is of size 5x5 and5>3
a.Set(1, R(1, 2), v); // OK, because the range size is 2

Setting shape - SetShape()

This function changes the shape of an array. (Available for universal classes (doubleN, ..., doubleNNNN,) only). If necessary, new memory is allocated. The elements are not initialized. They can be accessed by the usual indexing operation.

doubleNN a;      // Allocates 10x10, has shape 0x0
doubleNN b(5,6); // Allocates 10x10, has shape 5x6
a.SetShape(20,40); // Allocates 20x40, has shape 20x40
b(70,30)=1;        // Causes error
b.SetShape(70,30); // Allocates 70x30, has shape 70x43
b(70,30)=1;        // OK

Internal data - data()

This function returns the address of internal presentation of the array. (Available for universal classes only) Internally the arrays are stored in column major order. This order is used for interfacing with Fortran routines.

Output functions

All arrays can be printed out to an output stream by the usual << operator: If the NOPAR preprocessor definition is defined, no parentheses are used in printouts.

doubleNN a;
cout << a;

May produce:

( 5.0   7.0
  2.6   7.2 )

 

Complex numbers are written as 5+7 I, 5-7 I

Strings are written without quotes.

LightMat arithmetic operations and functions

• Unary operators -,+
• Elementwise binary operators +, -, pow, Mod
• Inner product *
• Combined arithmetic operation and assignment +=, -=, *=, /=
• Division /
• Division and multiplication: ElemProduct, ElemQuotient
• Other operations: Cross, OuterProduct, Apply
• Other mathematical operations: sign, abs, LightMax, LightMin, ifloor, iceil, irint, IntegerPart, FractionalPart, sqrt, exp, log, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh

A collection of operators and functions is defined for every class in the LightMat library. The operators and function names are overloaded and perform relevant operations on various arguments. All the operators and functions are available as friend functions. Therefore the notation is similar for scalar arguments and for arrays of different ranks.

Operators available for all classes are:

Unary operators:

• -x, unary minus
• +x, unary plus

Elementwise binary operators.

One of the arguments can be scalar. If both are arrays they must be of the same size and shape. This applies to int, double and complex.

• x+y, Elementwise addition.
• x-y, Elementwise subtraction.
• pow(x,y), Elementwise power. Extended for complex numbers.
• Mod(x,y), Elementwise modulo. The definition is extended for real and complex numbers. If x and y are integers of different sign (x%y+y) will be the result.

Inner product and multiplication with scalar.

• This applies for int, double and lm_complex.
• xarr*yscalar or xscalar*yarr: If one of the arguments is scalar, all elements of other argument are multiplied by the scalar. The result has the same rank and shpe as the array.
• xarr*yarr: If both arguments are arrays, the inner products is computed. (For vector also called dot product.). If the arguments have rank m and n, the result will be of rank m+n-2. The last dimension of the first argument should be equal to the first dimension of the second argument. This is checked at runtime.

All the possible variants are given in the table (s is a scalar; other symbols are suffixes of class names):

Combined arithmetic operations and assignments.

If y is an array, it must have the same dimensions as x. Result has the same dimension as array x. This applies to int, double and complex.

• x+=y, add array or scalar y to x.
• x-=y, subtract array or scalar y from x.
• x*=y, multiply elements of x by scalar y
• x/=y, divide elements of x by scalar y

Division.

The result array has the same dimension as the array argument. This applies to int, double and complex.

• x/y, divide elements of array x by scalar y
• x/y, divide scalar x by array y. For each element a of y, form an array of elements x/a.

Division and multiplication as operations performed only element-wise

The x and y are arrays. Result has the same dimension. This applies to int, double and complex.

• ElemProduct(x,y) - element-wise multiplication
• ElemQuotient(x,y) - element-wise division

Other operations with arrays

• Cross(x,y) - defined for int3 and double3 and lm_complexN  of length 3  only. Returns the same type. More ???.
• OuterProduct(x,y) - defined for classes with suffixes 3, 4, N. Returns value of corresponding class with suffix NN. For example double3, doubleN gives a result value of doubleNN.
• Apply(arr,f) - applies function f to every element of the array. This applies to int, double, string and complex. Example:

  double add(double x) { return x+1; }
double3 a(1.5,1.6,1.7);
double3 b=Apply(a,add);
cout << b; //  prints 2.5, 2.6, 2.7

• Apply(arr1,arr2,f) - applies function f(x,y) to every element of array arr1 and arr2 element-wise. This applies to int, double, string and complex.  The arrays arr1 and arr2 have the same dimension sizes. Example:

  int sum(int x1, int x2){ return x1+x2;}
int4 s(5,6,7,8);
int4 t(10,11,12,13);
int4 u=Apply(s,t,sum); // 15, 17, 19, 21

Mathematical functions, applied element-wise:

• sign (returns integer, -1, 0 or 1; defined for integer and double). Returns complex for complex as z/abs(z) .
• abs (returns the same type as argument). For complex returns a double value |z|.
• LightMax returns the maximal element of an array (for integer and double).
• LightMin returns the minimal element of an array (for integer and double).
• ifloor, iceil, irint, IntegerPart (returns integer).
• FractionalPart, sqrt, exp, log, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, atan2
• these functions can be applied to integers or double arguments and they returns double.
• these functions can be applied to complex arguments and they then return complex.
• asinh, acosh, atanh (returns double, not defined for Win32 implementation)
• im, re, arg - can be applied to int, double, complex; return int or double.  
• conjugate -- can be applied to int, double, complex; return int or double or complex.  

Note: (Version 0.76) FractionalPart, IntegerPart, Mod, LightMax, LightMin - implemented for universal types (N,NN,...) only.

All complex operations are needed foe universal types (N,NN,...) only.

List operations

These operations can be applied to universal array types (N,NN,...)  of int, double, lm_complex, string

Join

Joins two arrays of the same rank. All dimensions except the first must be identical.

Append

Joins two arrays of the rank n and n-1. All dimensions except the first dimension of the first array must be identical.

Prepend

Joins two arrays of the rank n-1 and n. All dimensions except the first dimension of the first array must be identical.

Drop

Accepts an array and a range (object of class R). Removes all elements whose first index is in the range.