Chris@49: === Contents ===
Chris@49: 
Chris@49: 1: Introduction
Chris@49: 
Chris@49: 2: Citation Details
Chris@49: 
Chris@49: 3: Installation
Chris@49:    3.0: Preliminaries
Chris@49:    3.1: Installation on Linux and Mac OS X
Chris@49:    3.2: Manual Installation / Installation on Windows
Chris@49: 
Chris@49: 4: Compiling Programs and Linking
Chris@49:    4.0: Examples
Chris@49:    4.1: Compiling & Linking on Linux and Mac OS X
Chris@49:    4.2: Compiling & Linking on Windows
Chris@49: 
Chris@49: 5: Support for high-speed BLAS & LAPACK replacements
Chris@49:    5.0: Support for OpenBLAS, Intel MKL and AMD ACML
Chris@49:    5.1: Support for ATLAS
Chris@49: 
Chris@49: 6: Documentation / API Reference Manual
Chris@49: 
Chris@49: 7: FAQs and Bug Reports
Chris@49: 
Chris@49: 8: Developers and Contributors
Chris@49: 
Chris@49: 9: License
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 1: Introduction ===
Chris@49: 
Chris@49: Armadillo is a C++ linear algebra library (matrix maths)
Chris@49: aiming towards a good balance between speed and ease of use.
Chris@49: The syntax is deliberately similar to Matlab.
Chris@49: 
Chris@49: Integer, floating point and complex numbers are supported,
Chris@49: as well as a subset of trigonometric and statistics functions.
Chris@49: Various matrix decompositions are provided through optional
Chris@49: integration with LAPACK or high-performance LAPACK-compatible
Chris@49: libraries (such as Intel MKL or AMD ACML).
Chris@49: 
Chris@49: A delayed evaluation approach is employed (during compile time)
Chris@49: to combine several operations into one and reduce (or eliminate)
Chris@49: the need for temporaries. This is accomplished through recursive
Chris@49: templates and template meta-programming.
Chris@49: 
Chris@49: This library is useful for conversion of research code into
Chris@49: production environments, or if C++ has been decided as the
Chris@49: language of choice, due to speed and/or integration capabilities.
Chris@49: 
Chris@49: The library is open-source software, and is distributed under a
Chris@49: license that is useful in both open-source and commercial/proprietary
Chris@49: contexts. 
Chris@49: 
Chris@49: Armadillo is primarily developed at NICTA (Australia),
Chris@49: with contributions from around the world.  More information
Chris@49: about NICTA can be obtained from http://nicta.com.au
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 2: Citation Details ===
Chris@49: 
Chris@49: Please cite the following tech report if you use Armadillo in your
Chris@49: research and/or software. Citations are useful for the continued
Chris@49: development and maintenance of the library.
Chris@49: 
Chris@49:   Conrad Sanderson.
Chris@49:   Armadillo: An Open Source C++ Linear Algebra Library for
Chris@49:   Fast Prototyping and Computationally Intensive Experiments.
Chris@49:   Technical Report, NICTA, 2010.
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 3.0: Installation: Preliminaries ===
Chris@49: 
Chris@49: Armadillo makes extensive use of template meta-programming,
Chris@49: recursive templates and template based function overloading.
Chris@49: As such, C++ compilers which do not fully implement the C++
Chris@49: standard may not work correctly.
Chris@49: 
Chris@49: The functionality of Armadillo is partly dependent on other
Chris@49: libraries: mainly LAPACK and BLAS. Armadillo can work without
Chris@49: LAPACK or BLAS, but its functionality will be reduced.
Chris@49: In particular, basic functionality will be available
Chris@49: (eg. matrix addition and multiplication), but things like
Chris@49: eigen decomposition or matrix inversion will not be.
Chris@49: Matrix multiplication (mainly for big matrices) may not be as fast.
Chris@49: 
Chris@49: * For automatic installation on Linux and Mac OS X systems,
Chris@49:   see section 3.1. This installation is also likely to work on
Chris@49:   other Unix-like systems, such as FreeBSD, NetBSD, OpenBSD,
Chris@49:   Solaris, CygWin, etc.
Chris@49:   
Chris@49: * For manual installation and/or installation on Windows,
Chris@49:   see section 3.2.
Chris@49:   
Chris@49: * If you have a previous version of Armadillo already installed,
Chris@49:   we recommend removing it before installing a newer version.
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 3.1: Installation on Linux and Mac OS X ===
Chris@49: 
Chris@49: You can use the manual installation process as described in
Chris@49: section 3.2, or the following CMake based automatic installation.
Chris@49: 
Chris@49: * Step 1:
Chris@49:   If CMake is not already be present on your system, download
Chris@49:   it from http://www.cmake.org
Chris@49:   
Chris@49:   On major Linux systems (such as Fedora, Ubuntu, Debian, etc),
Chris@49:   cmake is available as a pre-built package, though it may need
Chris@49:   to be explicitly installed (using a tool such as PackageKit,
Chris@49:   yum, rpm, apt, aptitude).
Chris@49:   
Chris@49: * Step 2:
Chris@49:   If you have BLAS and/or LAPACK, install them before installing
Chris@49:   Armadillo. Under Mac OS X this is not necessary.
Chris@49:   
Chris@49:   On Linux systems it is recommended that the following libraries
Chris@49:   are present: LAPACK, BLAS, ATLAS and Boost. LAPACK and BLAS are
Chris@49:   the most important. If you have ATLAS and Boost, it's also necessary
Chris@49:   to have the corresponding header files installed.
Chris@49:   
Chris@49:   For best performance, we recommend using the multi-threaded OpenBLAS
Chris@49:   library instead of standard BLAS.  See http://xianyi.github.com/OpenBLAS/
Chris@49:   
Chris@49: * Step 3:
Chris@49:   Open a shell (command line), change into the directory that was
Chris@49:   created by unpacking the armadillo archive, and type the following
Chris@49:   commands:
Chris@49:   
Chris@49:   cmake .
Chris@49:   make 
Chris@49:   
Chris@49:   The full stop separated from "cmake" by a space is important.
Chris@49:   CMake will figure out what other libraries are currently installed
Chris@49:   and will modify Armadillo's configuration correspondingly.
Chris@49:   CMake will also generate a run-time armadillo library, which is a 
Chris@49:   combined alias for all the relevant libraries present on your system
Chris@49:   (eg. BLAS, LAPACK and ATLAS).
Chris@49:   
Chris@49:   If you need to re-run cmake, it's a good idea to first delete the
Chris@49:   "CMakeCache.txt" file (not "CMakeLists.txt").
Chris@49:   
Chris@49: * Step 4:
Chris@49:   If you have access to root/administrator/superuser privileges,
Chris@49:   first enable the privileges (eg. through "su" or "sudo")
Chris@49:   and then type the following command:
Chris@49:   
Chris@49:   make install
Chris@49:   
Chris@49:   If you don't have root/administrator/superuser privileges, 
Chris@49:   type the following command:
Chris@49:   
Chris@49:   make install DESTDIR=my_usr_dir
Chris@49:   
Chris@49:   where "my_usr_dir" is for storing C++ headers and library files.
Chris@49:   Make sure your C++ compiler is configured to use the sub-directories
Chris@49:   present within this directory.
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 3.2: Manual Installation / Installation on Windows ===
Chris@49: 
Chris@49: The manual installation is comprised of 3 steps:
Chris@49: 
Chris@49: * Step 1:
Chris@49:   Copy the entire "include" folder to a convenient location
Chris@49:   and tell your compiler to use that location for header files
Chris@49:   (in addition to the locations it uses already).
Chris@49:   Alternatively, you can use the "include" folder directly.
Chris@49:   
Chris@49: * Step 2:
Chris@49:   Modify "include/armadillo_bits/config.hpp" to indicate 
Chris@49:   which libraries are currently available on your system.
Chris@49:   For example, if you have LAPACK and BLAS (or OpenBLAS) present, 
Chris@49:   uncomment the following lines:
Chris@49:   
Chris@49:   #define ARMA_USE_LAPACK
Chris@49:   #define ARMA_USE_BLAS
Chris@49:   
Chris@49: * Step 3:
Chris@49:   If you have LAPACK and/or BLAS present, configure your 
Chris@49:   compiler to link with these libraries. 
Chris@49:   
Chris@49:   If using Linux, link using -llapack -lblas
Chris@49:   If using Mac OS X, link using -framework Accelerate
Chris@49:   If using Windows, see section 4.2.
Chris@49:   
Chris@49:   You can also link with high-speed replacements for LAPACK and BLAS,
Chris@49:   such as OpenBLAS, or Intel MKL, or AMD ACML. See section 5 for more info.
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 4.0: Compiling Programs and Linking: Examples ===
Chris@49: 
Chris@49: The "examples" directory contains several quick example programs
Chris@49: that use the Armadillo library. If Armadillo was installed manually
Chris@49: (ie. according to section 3.2), you will also need to explicitly
Chris@49: link your programs with the libraries that were specified in
Chris@49: "include/armadillo_bits/config.hpp".
Chris@49: 
Chris@49: "example1.cpp" may require the BLAS library or its equivalent.
Chris@49: "example2.cpp" requires the LAPACK library or its equivalent
Chris@49: (eg. the Accelerate framework on Mac OS X).
Chris@49: 
Chris@49: You may get errors at compile or run time if BLAS and/or LAPACK
Chris@49: functions are not available.
Chris@49: 
Chris@49: NOTE: As Armadillo is a template library, we recommended that
Chris@49:       optimisation is enabled during compilation. For example,
Chris@49:       for the GCC compiler use -O1 or -O2
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 4.1: Compiling & Linking on Linux and Mac OS X ===
Chris@49: 
Chris@49: Please see "examples/Makefile", which may may need to be configured
Chris@49: for your system. If Armadillo header files were installed in a
Chris@49: non-standard location, you will need to modify "examples/Makefile"
Chris@49: to tell the compiler where they are.
Chris@49: 
Chris@49: In general, programs which use Armadillo are compiled along these lines:
Chris@49:   g++ example1.cpp -o example1 -O2 -larmadillo
Chris@49: 
Chris@49: (you may also need to specify the include directory via the -I switch)
Chris@49: 
Chris@49: If you get linking errors, or if Armadillo was installed manually
Chris@49: and you specified that LAPACK and BLAS are available, you will
Chris@49: need to explicitly link with LAPACK and BLAS (or their equivalents),
Chris@49: for example:
Chris@49:   g++ example1.cpp -o example1 -O2 -llapack -lblas
Chris@49: 
Chris@49: (you may also need to specify the library directory via the -L switch)
Chris@49: 
Chris@49: Notes:
Chris@49: 
Chris@49:   * under most Linux systems, using "-llapack -lblas" should be enough;
Chris@49:     however, on Ubuntu and Debian you may need to add "-lgfortran"
Chris@49:     
Chris@49:   * under Mac OS X, try "-framework Accelerate" or "-llapack -lblas"
Chris@49:     (the Accelerate option is usually the fastest)
Chris@49:     
Chris@49:   * under the Sun Studio compiler, try "-library=sunperf"
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 4.2: Compiling & Linking on Windows ===
Chris@49: 
Chris@49: As a courtesy, we've provided pre-compiled 32 bit versions of
Chris@49: standard LAPACK and BLAS for Windows, as well as MSVC project
Chris@49: files to compile example1.cpp and example2.cpp.
Chris@49: The project files are stored in the following folders:
Chris@49:   examples/example1_win32
Chris@49:   examples/example2_win32
Chris@49: 
Chris@49: The standard 32 bit versions of the LAPACK and BLAS libraries
Chris@49: are stored in:
Chris@49:   examples/lib_win32
Chris@49: 
Chris@49: If you're getting messages such as "use of LAPACK needs to be enabled",
Chris@49: you will need to manually modify "include/armadillo_bits/config.hpp"
Chris@49: to enable the use of LAPACK. See section 3.2 for more information.
Chris@49: 
Chris@49: Note that on 64 bit systems (such as Windows 7), dedicated
Chris@49: 64 bit versions of BLAS and LAPACK are considerably faster.
Chris@49: If you don't have a 64 bit BLAS library, it's better to
Chris@49: explicitly disable the use of BLAS by defining ARMA_DONT_USE_BLAS
Chris@49: before including the armadillo header:
Chris@49: 
Chris@49: #define ARMA_DONT_USE_BLAS
Chris@49: #include <armadillo>
Chris@49: 
Chris@49: The MSCV project files were tested on 32 bit Windows XP with
Chris@49: Visual C++ 2008 (Express Edition). You may need to make adaptations
Chris@49: for 64 bit systems, later versions of Windows and/or the compiler.
Chris@49: For example, you may have to enable or disable the ARMA_BLAS_LONG
Chris@49: and ARMA_BLAS_UNDERSCORE macros in "armadillo_bits/config.hpp".
Chris@49: 
Chris@49: The pre-compiled versions of LAPACK and BLAS were downloaded from:
Chris@49:   http://www.fi.muni.cz/~xsvobod2/misc/lapack/
Chris@49: 
Chris@49: If the provided libraries don't work for you, or you want more speed,
Chris@49: try these versions:
Chris@49:   http://software.intel.com/en-us/intel-mkl/
Chris@49:   http://developer.amd.com/tools-and-sdks/cpu-development/amd-core-math-library-acml/
Chris@49:   http://xianyi.github.com/OpenBLAS/
Chris@49:   http://www.stanford.edu/~vkl/code/libs.html
Chris@49:   http://icl.cs.utk.edu/lapack-for-windows/lapack/
Chris@49: 
Chris@49: The OpenBLAS, MKL and ACML libraries are generally the fastest.
Chris@49: See section 5 for more info on making Armadillo use these libraries.
Chris@49: 
Chris@49: 
Chris@49: You can find the original sources for standard BLAS and LAPACK at:
Chris@49:   http://www.netlib.org/blas/
Chris@49:   http://www.netlib.org/lapack/
Chris@49: 
Chris@49: 
Chris@49: We recommend the following high-quality compilers:
Chris@49: 
Chris@49:   * GCC (part MinGW)
Chris@49:     http://www.mingw.org/
Chris@49: 
Chris@49:   * GCC (part of CygWin)
Chris@49:     http://www.cygwin.com/
Chris@49: 
Chris@49:   * Intel C++ compiler
Chris@49:     http://software.intel.com/en-us/intel-compilers/
Chris@49: 
Chris@49: For the GCC compiler, use version 4.0 or later.
Chris@49: For the Intel compiler, use version 10.0 or later.
Chris@49: 
Chris@49: For best results we also recommend using an operating system
Chris@49: that's more reliable and more suitable for heavy duty work,
Chris@49: such as Mac OS X or the various flavours of Linux,
Chris@49: eg. Scientific Linux: http://www.scientificlinux.org/
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 5.0: Support for OpenBLAS, Intel MKL and AMD ACML ===
Chris@49: 
Chris@49: Armadillo can use OpenBLAS, or Intel Math Kernel Library (MKL), or the
Chris@49: AMD Core Math Library (ACML) as high-speed replacements for BLAS and LAPACK.
Chris@49: Generally this just involves linking with the replacement libraries
Chris@49: instead of BLAS and LAPACK.
Chris@49: 
Chris@49: You may need to make minor modifications to "include/armadillo_bits/config.hpp"
Chris@49: in order to make sure Armadillo uses the same style of function names
Chris@49: as used by MKL or ACML. For example, the function names might be in capitals.
Chris@49: 
Chris@49: On Linux systems, MKL and ACML might be installed in a non-standard
Chris@49: location, such as /opt, which can cause problems during linking.
Chris@49: Before installing Armadillo, the system should know where the MKL or ACML
Chris@49: libraries are located. For example, "/opt/intel/mkl/lib/intel64/".
Chris@49: This can be achieved by setting the LD_LIBRARY_PATH environment variable,
Chris@49: or for a more permanent solution, adding the directory locations
Chris@49: to "/etc/ld.so.conf". It may also be possible to store a text file 
Chris@49: with the locations in the "/etc/ld.so.conf.d" directory.
Chris@49: For example, "/etc/ld.so.conf.d/mkl.conf".
Chris@49: If you modify "/etc/ld.so.conf" or create "/etc/ld.so.conf.d/mkl.conf",
Chris@49: you will need to run "/sbin/ldconfig" afterwards.
Chris@49: 
Chris@49: Example of the contents of "/etc/ld.so.conf.d/mkl.conf" on a RHEL 6 system,
Chris@49: where Intel MKL version 11.0.3 is installed in "/opt/intel":
Chris@49: 
Chris@49: /opt/intel/lib/intel64
Chris@49: /opt/intel/mkl/lib/intel64
Chris@49: 
Chris@49: The default installations of ACML 4.4.0 and MKL 10.2.2.025 are known 
Chris@49: to have issues with SELinux, which is turned on by default in Fedora
Chris@49: (and possibly RHEL). The problem may manifest itself during run-time,
Chris@49: where the run-time linker reports permission problems.
Chris@49: It is possible to work around the problem by applying an appropriate
Chris@49: SELinux type to all ACML and MKL libraries.
Chris@49: 
Chris@49: If you have ACML or MKL installed and they are persistently giving
Chris@49: you problems during linking, you can disable the support for them
Chris@49: by editing the "CMakeLists.txt" file, deleting "CMakeCache.txt" and
Chris@49: re-running the CMake based installation. Specifically, comment out
Chris@49: the lines containing:
Chris@49:   INCLUDE(ARMA_FindMKL)
Chris@49:   INCLUDE(ARMA_FindACMLMP)
Chris@49:   INCLUDE(ARMA_FindACML)
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 5.1: Support for ATLAS ===
Chris@49: 
Chris@49: Armadillo can use the ATLAS library for faster versions of
Chris@49: certain LAPACK and BLAS functions. Not all ATLAS functions are
Chris@49: currently used, and as such LAPACK should still be installed.
Chris@49: 
Chris@49: The minimum recommended version of ATLAS is 3.8.
Chris@49: Old versions (eg. 3.6) can produce incorrect results
Chris@49: as well as corrupting memory, leading to random crashes.
Chris@49: 
Chris@49: Users of Ubuntu and Debian based systems should explicitly
Chris@49: check that version 3.6 is not installed.  It's better to
Chris@49: remove the old version and use the standard LAPACK library.
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 6: Documentation / API Reference Manual ===
Chris@49: 
Chris@49: A reference manual (documentation of APIs) is available at
Chris@49: 
Chris@49:   http://arma.sourceforge.net/docs.html
Chris@49: 
Chris@49: and in the "docs.html" file in this archive,
Chris@49: which can be viewed with a web browser.
Chris@49: 
Chris@49: The documentation explains how to use Armadillo's
Chris@49: classes and functions, with snippets of example code.
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 7: FAQs and Bug Reports ===
Chris@49: 
Chris@49: Answers to Frequently Asked Questions (FAQs) can be found at:
Chris@49: 
Chris@49:   http://arma.sourceforge.net/faq.html
Chris@49: 
Chris@49: This library has gone through extensive testing and
Chris@49: has been successfully used in production environments.
Chris@49: However, as with almost all software, it's impossible
Chris@49: to guarantee 100% correct functionality.
Chris@49: 
Chris@49: If you find a bug in the library (or the documentation),
Chris@49: we are interested in hearing about it. Please make a
Chris@49: _small_ _self-contained_ program which exposes the bug
Chris@49: and send the program source (as well as the bug description)
Chris@49: to the developers.  The developers' contact details are at:
Chris@49: 
Chris@49:   http://arma.sourceforge.net/contact.html
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 8: Developers and Contributors ===
Chris@49: 
Chris@49: Main sponsoring organisation:
Chris@49: - NICTA
Chris@49:   http://nicta.com.au
Chris@49: 
Chris@49: Main developers:
Chris@49: - Conrad Sanderson - http://itee.uq.edu.au/~conrad/
Chris@49: - Ryan Curtin
Chris@49: - Ian Cullinan
Chris@49: - Dimitrios Bouzas
Chris@49: - Stanislav Funiak
Chris@49: 
Chris@49: Contributors:
Chris@49: - Matthew Amidon
Chris@49: - Eric R. Anderson
Chris@49: - Benoît Bayol
Chris@49: - Salim Bcoin
Chris@49: - Justin Bedo
Chris@49: - Evan Bollig
Chris@49: - Darius Braziunas
Chris@49: - Filip Bruman
Chris@49: - Ted Campbell
Chris@49: - James Cline
Chris@49: - Chris Cooper
Chris@49: - Clement Creusot
Chris@49: - Chris Davey
Chris@49: - Dirk Eddelbuettel
Chris@49: - Romain Francois
Chris@49: - Michael McNeil Forbes
Chris@49: - Piotr Gawron
Chris@49: - Charles Gretton
Chris@49: - Benjamin Herzog
Chris@49: - Edmund Highcock
Chris@49: - Szabolcs Horvat
Chris@49: - Friedrich Hust
Chris@49: - Kshitij Kulshreshtha
Chris@49: - Oka Kurniawan
Chris@49: - Simen Kvaal
Chris@49: - David Lawrence
Chris@49: - Jussi Lehtola
Chris@49: - Jeremy Mason
Chris@49: - Nikolay Mayorov
Chris@49: - Carlos Mendes
Chris@49: - Sergey Nenakhov
Chris@49: - Artem Novikov
Chris@49: - Martin Orlob
Chris@49: - Ken Panici
Chris@49: - Adam Piątyszek
Chris@49: - Jayden Platell
Chris@49: - Vikas Reddy
Chris@49: - Ola Rinta-Koski
Chris@49: - Boris Sabanin
Chris@49: - James Sanders
Chris@49: - Alexander Scherbatey
Chris@49: - Gerhard Schreiber
Chris@49: - Ruslan Shestopalyuk
Chris@49: - Shane Stainsby
Chris@49: - Petter Strandmark
Chris@49: - Eric Jon Sundstrom
Chris@49: - Paul Torfs
Chris@49: - Martin Uhrin
Chris@49: - Simon Urbanek
Chris@49: - Juergen Wiest
Chris@49: - Arnold Wiliem
Chris@49: - Yong Kang Wong
Chris@49: - Buote Xu
Chris@49: - Sean Young
Chris@49: 
Chris@49: 
Chris@49: 
Chris@49: === 9: License ===
Chris@49: 
Chris@49: Unless specified otherwise, the Mozilla Public License v2.0 is used.
Chris@49: See the "LICENSE.txt" file for license details.
Chris@49: 
Chris@49: The file "include/armadillo_bits/fft_engine.hpp" is licensed under
Chris@49: both the Mozilla Public License v2.0 and a 3-clause BSD license.
Chris@49: See "include/armadillo_bits/fft_engine.hpp" for license details.
Chris@49: 
Chris@49: