LIGHTMAT  USER  MANUAL

What is LightMat

• This guide (it contains only one single HTML file) should help you to choose appropriate array classes for your application.
• First you install the library on your computer. Read Installation notes.
• Read the  chapter The Different Classes., it  lists the classes of the library.
• Then you have to declare your variables. Read  the chapter Constructors and Access to Arrays.
• Finally if you want to do some mathematics, read the chapter Calculations with LightMat.

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

Installation notes

Available platforms and compilers

Download and compilation

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

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

 Testing

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

 How to use the library

Using inlined functions

Using non-inlined functions

Reducing compilation time for non-inlined functions.

The Different Classes

• 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
• Tensor (tensor of rank 3) a three-dimensional array, e.g. lightNNN
• Quansor (tensor of rank 4) a four-dimensional array, e.g. lightNNNN

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.

The name of class you will use depends on whether you use template notation or non-template notation.

Since some compilers do not support templates in full scale, we suggest to use classes in non-template notation.

Template notation (Not available)

In the template notation classes are implemented as templates, for instance class light4<T>.
The same code can therefore be used for both objects with elements of type double and int.
The user specifies a variable as
     light4<double>  foo
This means that foo is a vector with 4 elements of type double.
Other types of elements  can be used, however, some arithmetical operations with them will not be defined.
 

Non-template notation

 Specially optimized classes for certain sizes

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

 There are also classes for matrices and tensors with partially fixed sizes (lightN3 and lightN33). The usefulness of these classes will be described in  Indexing. One is for matrices with three columns and the other one is for tensors of rank 3 which have the size of the two last indices set to three. Internally the matrix-class consist of a number of vectors of length 3 (light3) and the tensor-class consist of a number of 3x3 matrices (light33).

 Since the sizes of objects of these classes are partially or totally fixed they cannot dynamically change their sizes as freely as the the universal LightMat classes. Only lightN3 and lightN33 can change the first dimension during calculations.

Constructors and access to arrays

Normal constructors

• No arguments.These default constructors create an object with  default size (given in the table).

        lightNNdouble a; doubleNN b;

• An object of the same class as the only argument. This is the a normal copy constructor. I.e. the new object is a copy of the argument. The two objects will not share the same data area.

        lightNNdouble b = a; doubleNN c = d;

 
• Integer arguments. The integers 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.

        lightNNdouble a(3,5); doubleNN c(3,5);

 
• 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 type should have the same rank. The values are copied from the object given as an argument since all objects have their own data areas.

        light33double a;

        lightNNdouble c = a;

Such constructors are also called converters. There are converters for
• conversion of  arrays with integer elements to arrays with double elements (light3int to light3double)
• conversion of arrays with special size to universal arrays (light3 and light4 to lightN; light33, lightN3 and light44 to lightNN; lightN33 to lightNNN)
 
• Integer arguments and a pointer to a memory area. The integers specify the size of the created area 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).

        double arr[] = { 1.3, 2.6, 3, 4, 5.7, 6 };

        lightNN<double> a(2,3,arr);

 
• 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.

        lightNN<double> a(3,4,17.7);

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

        light33<double> a(1.1,2,3.5,4,5,6.9,7,8.3,9);

Element initialization

Memory allocation

Destructors

Assignment

lightNN<double> a(2,3), b(3,2);

a = b;          // a becomes 3x2

a = 5.7;        // all elements of a become 5.7

Set() and Get()

lightNN<double> a(5,5,17.7),  b(5,5);
double arr[25];
a.Get(arr);  // a  -->  arr
b.Set(arr);  // arr  -->  b

No bounds check is performed.

dimension()

Equality and inequality

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

reshape()

lightN<double> v(3);
lightNN<double> a;
a.reshape(3,5,v);  // a becomes 3x5
 

make_lightN()

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

Indexing for individual elements

lightNN<double> a(5,3);
a(1,1) = a(2,3);
 

Indexing for array extraction

lightN<double> v;
lightNN<double> a(5,5);
lightNNN<double> c(7,8,9);
v = a(4);
v=c(4,5);
a= c(3);
a(1) = v; //  The result is discarded, and matrix a does not change.
a.SetRow(1,v) ;// This is the correct way. See access functions.
 
 

light3<double> w;
lightN3<double> m(5);
m(3) = w + m(2); // This class is exception, m changes.
 

Access functions

• class lightN<T>

•  lightN<T> SubVector(int,int)  - returns interval of the vector
•   SetSubVector(int,int,lightN<T>&) - sets interval of the vector

Example:
lightN<int> s(5,30); // Length is 5, all elements initialized to 30
lightN<int> p(2,40); // Length is 2, elements are initialized to 40
s.SetSubVector(3,4,p); // s becomes {30,30,40,40,30}
p=s.SubVector(2,4); // p changes length and becomes {30,40,40}
 

• class lightNN<T>
• SetCol(int n, lightN<T>& x)  - puts x into column n
• SetRow(int n, lightN<T>& x)  - puts x into row n
• SetCols(int n1,int n2, lightNN<T> &x) - puts matrix x into columns n1...n2
• SetRows(int n1,int n2, lightNN<T> &x) - puts matrix x into rows n1...n2
• SetSubMatrix(r1,r2,c1,c2,lightNN<T> &x) - puts matrix x into rows from r1 to r2, columns from c1 to c2
• SetCols(int n1,int n2, T x) - puts scalar x into columns n1...n2
• SetRows(int n1,int n2, T x) - puts scalar x into rows n1...n2
• SetSubMatrix(r1,r2,c1,c2,T x) - puts scalar x into rows from r1 to r2, columns from c1 to c2
• lightN<T> Col(n) - get column n
• lightN<T> Row(n) - get row n
• lightNN<T> SubMatrix(r1,r2,c1,c2) - get submatrix, rows from r1 to r2, columns from c1 to c2
• lightNN<T> Cols(c1,c2) - get submatrix, columns c1 to c2
• lightNN<T> Rows(r1,r2) - get submatrix, rows r1 to r2.

 
• class lightNNN<T>
• SetMatrix1(n, lightNN<T> & x) - sets matrix x to "level" n of the tensor, i. e. elements (n,*,*)
• SetVector12(n, m, lightN<T> & x) - sets vector x to elements (n,m,*) of the tensor.

SetShape()

lightNN<double> a;
lightNN<double> b(5,6);
a.SetShape(2,4);
b.SetShape(7,3);
a(7,3)=1;
 

data()

Calculations in lightmat

Operators available for all classes are:
 

Unary operators:

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

Elementwise binary operators.

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

Inner product and multiplication with scalar.

• If one of arguments is scalar, all elements of other argument are multiplied by the scalar.  The result  has the same rank as the array.
• If both arguments are arrays, 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.

 Operation with assignment.

• x+=y, add array or scalar y
• x-=y, subtract array or scalar y
• x*=y, multiply by scalar y
• x/=y, divide by scalar y

Division.

• x/y, divide array x by scalar y
• x/y, divide scalar x by array y

Division and multiplication as operations performed only element-wise.

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

Other operations with arrays

• Cross(x,y) - defined for light3 vectors only. Returns light3.
• OuterProduct(x,y) - defined for light3, light4, lightN. Returns lightNN.
• Apply(arr,T f(T)) - applies function f to every element of the array with element type T.
• Apply(arr1,arr2,T f(T,T)) - applies function f to every element of array arr1 and arr2 element-wise. The arr1 and arr2 has the same dimension.

Mathematical functions, applied element-wise:

• sign (return integer , -1, 0 or 1; defined for integer and double),
• abs (return the same type as argument),
• LightMax  returns maximal element of array
• LightMin returns minimal element of array
• floor, ceil, rint , IntegerPart (return integer) ,
• FractionalPart, sqrt, exp, log, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh (return double)
• asinh, acosh, atanh (return double, not defined for Win32 implementation)

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

Preprocessor definitions

Implementation notes

Memory usage in classes

One memory area for each object

Static and dynamic memory

Storage for arrays and order of elements

 The interface for the classes expect the elements to be stored in row major order though. That will make it easier to interface to other C++ code.

 Dynamic resizing of objects

The basic internal routines for calculation

 Some classes do not use these basic routines. The classes which are specialized for different sizes have their own optimized routines which do the calculations as quickly as possible. That means that loops are avoided in the classes, the needed statements are instead in a (sometimes) long serie. The functions doesn't get very big anyway since the number of elements in those classes are rather few. Loops can't be avoided in the normal classes since the number of elements aren't known at compile-time.
 
There are different routines for element-wise assignment, addition, subtraction, multiplication and division of two arrays with elements or of an array and a scalar. There are also different variants of those routines which either put the result in some other array or in one of the already supplied arrays. Putting the result in the same array as some of the operands are taken from reduces the code which are needed to index the arrays. All these routines have unrolled loops in order to increase the speed a little more.

 There are also some routines for calculating dot products and inner products. Two routines can calculate dot products. They differ in that one of them allows the step between elements in one of the arrays to be greater than one. That feature is needed by some other routines, one is the routine that calculate matrix-vector products. Both routines for dot product calculation have unrolled loops.

 The routines for calculating inner products use the routines that calculate dot products. All needed routines for calculating inner products between any combinations of vectors, matrices and tensors of rank 3 or 4 exist. No routines which produce a result which is a tensor with a higher rank than 4 exist though (since the result can't be represented in any way). All routines use the routines for dot product directly or via another routine for calculating inner products.
 
 

 All basic routines are listed in the table above. Note that some routines are overloaded and can hence have more than one use, although similar in nature.

 All classes use these routines whenever possible and that makes it easy to change something, e.g. the degree of unrolling, in those routines in order to customize lightmat for speed for a lightmat-user's own computer. compiler and calculations.
 

Using LightMat with BLAS

 The normal lightmat calculation routines can normally be inlined though, and calling a BLAS routine incurs an extra function call. So using BLAS is probably only a good idea if large vectors, matrices or tensors are used in the calculations. Your mileage may vary depending on the computer and compiler that is used.  See  also  preprocessor defintions.
 

 Optimizing calculations and constructors

 Routines for other classes usually do nothing more than call special constructors which do the actual work. E.g. the operator+ functions usually only contain a return statement those argument is a call to a constructor. The reason for doing like that is that the C++ compilers that have been tested produce a faster code if the functions return a in the return statement constructed object. The other way to do it would be to create a, for the function, local and uninitialized object, set the elements to their correct values and then return the object. The object must then be copied (since it's a local variable) when it's returned and that takes time. Having a constructor as the argument to the return-statement can be used to avoid that copying. I.e.

 
classA oper(classA a, classA b){
      // Calculation is done in constructor
    return classA(a, b, oper_enum);
    }

is faster than

classA oper(classA a, classA b)
    {
     classA res;
     // Do calculation here
     return res;
    }
The constructors that do the calculations call the basic routines in  when possible. Constructors that exist are ones that calculate addition, subtraction, multiplication, division, dot product, inner product, transpose, raise to the power and absolute value. There also exist constructors that take a function as an argument and apply it to one or two objects. Those constructors are used by a lot of trigonometric functions.

 A few calculation functions create a local object which is later returned. This is needed by a few functions that do conversions between different element types, e.g. from int to double. It is also used by the indexing functions which does not return a single element but instead, for example, a vector or matrix. The reason for these exceptions is that some special copying is needed for which no constructors exist.
 

  Temporary Variables

 The creation of a temporary variable can be avoided if assignment isn't used when saving the result of the calculation. The result can instead be put directly into a new variable that is constructed at the same time.

  lightNN<double> A,B,C;
A=B+C;                                       // a temporary variable is needed
lightNN<double> D=B+C;      // no temporary variable is  needed

This will avoid the construction and destruction of an extra variable and it will also avoid the call to the assignment operator. A constructor for the new variable need to be called though, but the result-variable has to be constructed somewhere anyway.
 

 Unrolling

Note on assignments

Making Extensions to LightMat

Functions

• The pointer variable elem points at the memory that is used. If it's equal to sarea then the static memory area is being used. In classes with a fixed size elem is the static area.
• The function init() can be used in constructors in order to initialize the size of the object.
• If you need to write a function that must change the size of an already constructed object then have a look at operator=(). There are a examples of size-changes in several of the assignment operators.
• Use the functions described in ``The basic routines for calculation'' whenever possible in calculations since it will then be easier to change unrolling etc. when those functions are used..
• The limiterror() macro shall be used in order to check the sizes, where needed, of arguments to functions. E.g.

        limiterror(s.size == 3);

• When writing a specialized version of a function for a specific type, e.g. double or float, then write it as a template specialization. E.g. matrix multiplication for type double using BLAS is written like that in light_double.icc.

New Classes

 It may also be necessary to add new functions, or friends, to existing classes in order to integrate the new class with old classes. Remember to write conversion functions from specialized sizes of classes to the more general classes when appropriate. I.e. it shall be possible to convert an object of a new light22 class to an object of type lightNN.