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
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.
Version 1.9 adds an interface to call BLAS and LAPACK routines on MArrays of dimension 2 and 1, as well as LU and Singular Value Decompositions on fixed-size FMatrix and FVector classes.
Version 1.8 adds support for multithreaded environments, for example use of OpenMP, and a much more user-friendly interface to non-linear least-squares fitting of functions.
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:
where()
merge( A!=0, 1/A, 0 )
apply(f, Expr)
The author's email addresses are:
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.
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.
If you are planning on using LTL in a multithreaded environment (e.g. using OpenMP), supply the flag --enable-multithread
to configure. This will ensure that reference counting memory allocations/deallocations are guarded by locks.
The configure
script will try to auto-detect BLAS and LAPACK libraries on your system. If this fails or you wish to force the use of a specific implementation, use the options --with-blas
[=LIB] and --with-lapack
[=LIB].
A typical session might look as follows:
tar -zxf ltl-1.9.tar.gz cd ltl-1.8/ CXXFLAGS='-g -O3 -Wall -march=... -fstrict-aliasing' ./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.
libltl
.
To keep compile times as low as possible, the LTL
headers are split into parts providing distinct functionality.
#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, ...
To call BLAS and LAPACK routines on MArrays
include
#include <marray/blas.h> // BLAS Level 1, 2, and 3 routines
#include <marray/lapack.h> // Selected LAPACK routines (easily extensible).
#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
For some linear algebra with FMatrix and FVector use
#include <ltl/fmatrix/gaussj.h> // Gauss-Jordan #include <ltl/fmatrix/lusolve.h> // LU decomposition #include <ltl/fmatrix/svdsolve.h> // SVD #include <ltl/fmatrix/lmfit.h> // non-linear least-squares fitting
Note that including <ltl/fmatrix.h>
automatically includes <ltl/fvector.h>
, since these represent column and row vectors of matrices.
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.)<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.Also, make sure you include the ltl headers before any standard library headers to make sure that configuration options get honored by the standard library as well.
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_THREADSAFE_MEMBLOCK:
Define this if you are using multiple threads or if you are compiling using OpenMP. This will guard memory block reference counting by locks. This option can also be set at configure time using the option --enable-openmp
. Locks are implemented as machine intrinsics if available (GCC) or as posix mutexes if not (much slower). You have to make sure that you supply the necessary -march
flag to GCC to ensure that the machine intrinsics are defined (and exist for the CPU you are compiling for). 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). Currently, many array operations and reductions have vectorized implementations for double
(on x86), float
, and int
element data. Shorter int
types may or may not be supported. LTL_UNROLL_EXPRESSIONS
(default) or LTL_DONT_UNROLL_EXPRESSIONS:
Controls whether loops are unrolled 4 times or not. Sometimes unrolling can yield worse performance on register-poor architectures such as x86/ia32. LTL_UNROLL_EXPRESSIONS_SIMD
(default) or LTL_DONT_UNROLL_EXPRESSIONS_SIMD:
Controls whether vectorized loops are unrolled 4 times. Sometimes unrolling can yield worse performance on register-poor architectures such as x86/ia32. LTL_DEBUG_EXPRESSIONS:
Print information about the evaluation method chosen for expressions. This will indicate among others if the multidimensional loops were collapsed and if the expression was vectorized.