LTL Documentation

1.7

Author:

Niv Drory, Claus A. Gössl, Jan Snigula

Copying

The Little Template Library is available under the GNU General Public License. See the file `COPYING' for details.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

Introduction

LTL provides dynamic arrays of up to 7 dimensions, subarrays and slicing, support for fixed size vectors and matrices including basic linear algebra operations, expression templates based evaluation, and I/O facilities for columnar ASCII and FITS format files.

Although the library is developed with application to astronomical image and data processing in mind (therefore FITS format I/O), it is by no means restricted to these fields of application. In fact, it qualifies as a fully general array processing package.

Focus is laid on a high abstraction level regarding the handling of expressions involving arrays or parts thereof and linear algebra related operations without the usually involved negative impact on performance. Hence the use of expression templates throughout the library. The price to pay is dependence on a compiler implementing enough of the current ANSI C++ specification, as well as significantly higher demand on resources at compile time.

A new feature as of LTL 1.7 is the automatic use of the vector execution unit present in some modern processors in the evaluation of array expressions. This is basically a compiler independent auto-vectorizer. Currently PowerPC processors (Altivec) and x86 processors (MMX/SSE/SSE2/SSE3) are supported.

As of version 1.6, LTL supports GCC versions 2.95.2 to 3.3.x (Linux/IA32, Mac OS X/PPC, Solaris/SPARC), Intel ICC version 7.1 (Linux/IA32), Sun C++ version 5.5 (Solaris/SPARC), and IBM VisualAge xlC version 6 (AIX/PPC, Mac OS X/PPC). DEC/Compaq/HP (whatever) compiler support is on the way. Other sufficiently ANSI complient C++ compilers should also do, but might require small modifications. Patches welcome.

The multidimensional array class ltl::MArray has the following features:

• creating and referencing subarrays (rank preserving)
• slicing (rank reducing), e.g. a column of an image
• mixing subarrays and slices in the same indexing expression e.g. a submatrix of a slice of a cube
• referencing the data of other arrays ('views')
• reference counting for the memory chunks holding the actual data
• STL-compatible iterators
• arbitrary complex arithmetic expressions without creation of temporary objects: 'expression templates'
• support for all standard library math functions
• user supplied functions can be added easily
• auto-vectorization of expressions (Altivec, SSE2)
• indexing arbitrary sets of elements: where()
• conditional expression evaluation: merge( A!=0, 1/A, 0 )
• stream I/O
• ASCII-file I/O for columnar data
• FITS file I/O
• transparent memory-mapped arrays

The fixed vector and matrix classes ltl::FVector and ltl::FMatrix provide:

• compile time fixed size (allows strong optimization)
• expression template based evaluation of arithmetic and linear algebra expressions
• referencing column and row vectors of a matrix
• vector dot product
• matrix-vector and matrix-matrix dot-product
• all operations on small enough objects are automatically unrolled by template metaprograms
• STL-compatible iterators
• Gauss-Jordan-Elimination
• Linear Least Squares Fitting method(s)
• Nonlinear Least Squares Fitting methods(s)

Additionally, there are some utility classes providing:

• command line and config file parsing
• output formatting utilities
• date format handling

The official homepage is at http://www.usm.uni-muenchen.de/people/drory/ltl/index.html .

The author's email is:

• Niv Drory <drory@mpe.mpg.de>
• Claus A. Goessl <cag@usm.uni-muenchen.de>
• Jan Snigula <snigula@usm.uni-muenchen.de>

Comments, suggestions, and code contributions are welcome anytime.

Documentation

The documentation is divided into 2 parts. The first part gives an overview of the library and its usage and contains many examples. It is a good starting point for getting to know the LTL:

• Multidimensional Dynamic Arrays
• MArray I/O
• The Utility Library
• Fixed Size Vectors and Matrices

The Doxygen-generated documnetation for the classes and functions serves as a reference, for example ltl::MArray, ltl::FVector, ltl::FMatrix. You can access all of this through the modules section of the documentation.

Compiling and Installing LTL

Compiling LTL

Make sure your compiler is supported. Currently GCC versions 2.95.2 and newer are known to work. GCC version 3.1 or later is recommended, since it is much faster, uses less memory and produces more optimized code when compiling heavily templated source. See http://gcc.gnu.org .

LTL's build system is based on GNU autoconf. After unpacking the source archive, go to the directory containing the source and type ./configure, then make, optionally make check to run a testsuite, and finally make install.

The configure script will check for the presence of some standard headers and POSIX functions and verify that the compiler used has all necessary features needed to compile LTL.

The configure script accepts a number of standardized options, run ./configure --help for a complete list. The most important options and environment variables are discussed in what follows.

The configure system honors the setting of the CXX, CXXFLAGS, and CPPFLAGS environment variables. The directory-prefix for installing header files and the library defaults to /usr/local. Headers are installed in /usr/local/include, the library, libltl.a, in /usr/local/lib. Info documentation goes to /usr/local/info.

Note that the LTL header files will actually be installed in a subdirectory ltl/ within the include directory to prevent conflicts with existing header files.

The prefix can be changed by the --prefix= option to configure. --libdir=, --includedir=, and --infodir= can be used to change the target directories individually.

A typical session might look as follows:

tar -zxf ltl-1.6.tar.gz
cd ltl-1.4/
CXXFLAGS='-g -O3 -Wall -Wno-deprecated' ./configure --prefix=$HOME/
...
make
make check
make install

Note that the above invocation of the configure script assumes a Bourne-compatible shell. In a csh shell, you have to use the setenv command for setting each of the environment variables.

Using LTL

Using LTL involves including one or more header files, depending on the features of LTL that are needed in your source file and linking against libltl.

To keep compile times as low as possible, the LTL headers are split into parts providing distinct functionality.

Using Multidimensional Arrays

To use the multidimensional array class, its expression template facilities and standard math operations, use

#include <ltl/marray.h>      // class MArray

To use the I/O facilities for the MArray class, include one or more of the following after including ltl/marray.h:

#include <ltl/marray_io.h>   // stream IO, operator<< and operator>>
#include <ltl/ascio.h>       // columnar ASCII file IO
#include <ltl/fitsio.h>      // FITS format IO

To use statistical functions on MArrays and their expressions, include

#include<statistics.h>       // sum, average, median, ...

Using Fixed Vectors and Matrices

To use the fixed vector class, its expression template facilities and standard math operations, use

#include <ltl/fvector.h>     // class FVector

To use the fixed matrix class, its expression template facilities and standard math operations, use

#include <ltl/fmatrix.h>     // class FMatrix

Note that including <ltl/fmatrix.h> automatically includes <ltl/fvector.h>, since these represent column and row vectors of matrices.

Namespaces

All LTL objects reside in the namespace ltl. If you do not want this behavior, undefine the preprocessor symbol LTL_USING_NAMESPACE in the global configuration file <ltl/config.h>. (See below for further details on options in the global configuration file.)

Global Configuration

Some global options can be set in the file <ltl/config.h> by defining or undefining preprocessor symbols. These options can also be controlled on a case by case basis by defining or undefining the appropriate symbol before including the first LTL header.

For example, if you want range checking (for debugging) turned on in a particular source file of your project, write

// MUST occur BEFORE including any ltl stuff!
#define LTL_RANGE_CHECKING
#include <ltl/marray.h>
...

In particular these are:

• LTL_USING_NAMESPACE: use namespaces if compiler supports them. Put everything in namespace ltl. This is the default behavior.
• LTL_RANGE_CHECKING: perform range checking when indexing. Off by default.
• LTL_ABORT_ON_RANGE_ERROR: abort and coredump if a range error occurs. This is the default if range checking is on.
• LTL_THROW_ON_RANGE_ERROR: throw an exception if a range error occurs.
• LTL_TEMPLATE_LOOP_LIMIT: maximum length of loops which are fully unrolled by expression template engine for ltl::FVector and ltl::FMatrix expressions. Defaults to 25.
• LTL_USE_SIMD: use vector execution unit when evaluating array expressions (auto-vectorize loops on supported hardware and if all operands in the expression have vectorized implementations)

---