Installation guide

MTL4 is a pure template library and only the presence of the sources is required. The only mandatory requirement is the Boost library collection. There are two ways to install MTL4:

• With a package manager or
• By downloading.

We recommend you the first option if you have administrative rights on your computer. It is much easier and you will be provided with automatic updates. Furthermore, boost will be installed as prerequisite.

Install with a Package Manager

We provide the MTL4 sources within 4 packages:

• "mtl" contains the headers of MTL4. This package is the only mandatory one for developing scientific applications.
• "mtl-examples" contains documentation of MTL4.
• "mtl-tests" provides our test suite if you like to check whether the library is properly installed and if your platform is well supported.
• "mtl-all" is a meta-package that install the entire MTL4 sources (i.e. the previous 3 packages).

Installation under Debian, Ubuntu and other .deb-based Linux Distributions

1. Open your package source manager (you find this in the menu System -> Administration -> Software Sources).
2. Go to tab "Other Sources", click on "Add" and insert the line:
   deb http://www.simunova.com/debian main/
   then save and close the package source manager.
3. Open the package manage (you find this in the menu System -> Administration -> Synaptic Package Manager) and "Reload".
4. Click on "Quick search" and type "mtl".
5. Mark the MTL4 packages you want and "Apply" for the installation. Accept all dependent packages.

Your package will warn that you are going to install non-authorized packages. We will provide signatures later. For the time being please accept the installation as it is.

Installation under SuSE, Fedora and other .rpm-based Linux Distribution

1. add the url repository
   http://www.simunova.com/rpm
   to your repository list and update.
   • There will be 2 error messages that come from missing signature. Please ignore this warning for the moment. Later we will add this signatures to avoid these errors.
2. Search the package "mtl" in your package manager
3. Mark the desired packages and accept all dependent packages.

Installation under Windows

This is under development and will be provided soon. For the time being please use an archive.

Install a Downloaded Archive

To compile an MTL4 application you only need to

1. Download and install Boost.
2. Download and install MTL4.
3. Include the libraries in the compile command when not installed in the include path, e.g.
   g++ myapp.cpp -o myapp -I/usr/local/include/boost-1.44 -I/usr/local/include/mtl4

Download and install Boost: One can do this by hand: download it from the Boost web page and unpack it in an appropriate directory. If you have administrator rights on the used computer you can put boost in a directory in the include path, e.g. /usr/local/include. Then you can omit the compiler flag for including from the boost directory. If multiple versions shall be used on your computer you can only put one in the include path or you need extra tools like softenv or module to deal with your paths. More convenient is the installation of boost with a packet manager like synaptic. We use in the development and testing currently versions between 1.38 and 1.44. Some earlier versions might work as well but not 1.33 or earlier (e.g. type traits for std::complex are missing there). The parts of boost used in MTL4 do not need to be compiled but only included (except for the Supercomputing Edition which is documented seperately).

Download MTL4:

Archives are found on the MTL4 download page. They are updated weekly. In principle, MTL4 headers can also be copied in a directory within the standard include path to omit the compiler flag for its inclusion.

For working with the latest version, you can check out the current trunk. As version control we use "subversion" which is contained in any Linux distribution. On Windows we recommend Tortoise. Go to the directory where you like MTL4 to reside and type:
svn checkout https://svn.simunova.com/svn/mtl4/trunk mtl4
The adventage of version control is that you can update it easily with
svn update
when new features are added or a bug is fixed (fortunately not needed very often).

Install MTL4 on Linux: MTL4 does not need an installation. You can simply put the files into any directory you like. In this case you need to pass the directory as flag when you compile your applications, e.g.:
g++ -I/home/joe/mtl4 ...
After extracting, you will have extra prefixes in your file names. For instance, if you extract an MTL4 archive in /home/joe/download then you need to compile with
g++ -I/home/joe/download/<archivename>/usr/include ...
or you copy the content of <archivename>/usr/include into a shorter path

To avoid the -I flag altogether, you can copy the headers into /usr/include. The MTL4 and the boost directory can be mixed in principle since their files are disjoint (but not all directories).

On Windows: If you compile MTL4 with VS2005/08/10 or its free express version you need to install the SDK (some boost files access to it). Please make sure that the compiler is in the path. Then cmake (or scons) will find it.

Additionally, you have to tell the compiler where the header files and the libraries of VC and the Software Developing Kit are located, i.e. declare the environment variables LIB and INCLUDE. For instance:
LIB=c:/Program Files/Microsoft Visual Studio 8/vc/lib;c:/Program Files/MicrosoftVisual Studio 8/vc/platformsdk/lib
INCLUDE=c:/Program Files/Microsoft Visual Studio 8/VC/include;c:/Program Files/Microsoft Visual Studio 8/VC/PlatformSDK/Include

To compile MTL4 programs (including the tests), it is advisable to use CMake. Go into the MTL4 main directory and run:

cmake .

Possibly, CMake will ask you to specify a generator "-G". After you have run CMake, several project files will appear in this directory.

Click on "ALL_BUILD.vcproj" (or "ALL_BUILD.vcprojx") and Visual Studio will open with a project folder containing all test and example programs.

Optional Installations

Using BLAS: Dense matrix multiplication has an acceleration with BLAS (when the types of the matrix elements allow). More BLAS usage is currently under development. To use this acceleration install a well-tuned BLAS (the original Netlib BLAS was even slower than our implementation when benchmarked it), preferably with a packet manager and set the macro MTL_HAS_BLAS. Although one can set the macro somewhere in the program sources it is recommended for better porting to define it in the compiler, e.g.:
g++ -DMTL_HAS_BLAS -lblas ...
or
cl /DMTL_HAS_BLAS ...
Of course, the library must be linked as well.

Using LAPACK: LAPACK is currently not supported but will be soon.

Using UMFPACK: Programs that use UMFPACK must be compiled with MTL_HAS_UMFPACK and linked with the UMFPACK library plus the libraries UMFPACK depends on (AMD and UFConfig).

Using Doxygen: The MTL4 documentation is available online. If you like to create a copy on your computer, e.g. to read it when offline, you can create it yourself. Just run doxygen in the main directory and you will find the documentation in libs/numeric/mtl/doc. The HTML version is found in libs/numeric/mtl/doc/html and a PDF file in libs/numeric/mtl/doc/pdf (not available online). The revision number in the page footer is not automatically set. In the main directory is a script mtl_doxygen that updates the footer. Unfortunately, it does not work under Windows. One can also generate man pages by enabling it in the Doxyfile (in MTL4's root directory). Doxygen can be downloaded here.

Testing

To make sure that MTL4 is completely installed and properly working on your platform, you can run the same tests as we use in our development. The whole test suite can be compiled and executed with few commands. We recommend using cmake, see Testing with CMake. As legacy code there are still scons files that might possibly still work, see Testing with scons. Both build systems support Windows and one can use cmake to generate Visual Studion project folder containing all MTL4 tests and tutorial examples.

In a nutshell

Resuming, for MTL4 you need to:

• Install Boost and include its directory in the compiler flags (unless already in the include path);
• Install MTL4 and include its directory in the compiler flags (unless already in the include path);
• Optionally install cmake or scons (or both);
• Optionally install some or all of the libraries: BLAS, UMFPACK, and LAPACK; and
• Optionally install doxygen.

Supported compilers

The Matrix Template Library is written in compliance with the C++ standard and should be compilable with every compiler compliant with the standard. It is regularly tested - see here for a list of compilers are tested nightly and here for the test results.

More compilers will be tested in the future.

Compilers that are not standard-compliant (e.g. VC 6.0) are not subject to support. Visual Studio is considered standard-compliant from VC 7.1 on but we still had trouble to compile MTL4 and even in VC 8.0 we needed a little work-around.

Proceed to the Debugger Support.