
Armadillo
C++ linear algebra library





Bugs ·
General ·
Dependencies/External Libraries ·
Speed ·
Features/Functions ·
Development ·
Licensing ·
Related ·
Misc
Bugs
General
 Are there code examples ?
See "examples/example1.cpp" which comes with the Armadillo archive.
See also the code snippets within the documentation,
including the short example program.
 How can I do ... ?
Check the documentation
and/or the README.txt file that comes with the Armadillo archive.
 Is it possible to plot Armadillo data directly from C++ ?
Yes. Try
gnuplotcpp,
gnuplotiostream,
scopemm.
 Are there open source projects using Armadillo ?
Yes. Examples:

MLPACK   fast machine learning library (classification, regression, clustering, etc) 
BEM++   boundary element library 
libpca   principal component analysis library 

foreground   robust foreground estimation / background subtraction algorithm 
ERKALE   quantum chemistry 
libdynamica   numerical methods used in physics 

groupsac   computer vision algorithm 
GRASTA   computer vision algorithm 
ECOC PAK   error correcting output codes 

AVRS   acoustic virtual reality system 
bnp   inference in a hierarchical Dirichlet process model 
KL1p   compressed sensing / sparse coding 

Gadgetron   medical image reconstruction 
molotov   motif locator (genetics) 
GStream   genetics (SNP and CNV genotyping) 

liger   integrated optimisation environment 
GNSSSDR   global navigation satellite system receiver 
Flow123d   simulator of underground water flow 

armanpy   Armadillo bindings/interface to Python (NumPy) 
cyarma   alternate Armadillo bindings/interface to Python (NumPy) 
ArmadilloJava   Java based interfaces similar to Armadillo API 
RcppArmadillo   bridge between R and Armadillo, on which 100+ other packages depend 
Dependencies / External Libraries
 What other libraries do I need to make full use of Armadillo ?
Armadillo can work without external libraries,
however it is recommended to install LAPACK in order to get full functionality.
If you have BLAS, Armadillo will use BLAS routines instead of a few builtin ones (eg. matrix multiplication), which might be faster.
On Linux systems, Armadillo can use several ATLAS routines in lieu of LAPACK, if ATLAS is available.
 How well will Armadillo work without LAPACK and BLAS ?
Basic functionality will be available (eg. matrix addition and multiplication),
but things like eigen decomposition will not be.
Matrix multiplication (mainly for big matrices) will not be as fast.
 Where do I get LAPACK / BLAS / ATLAS ?

For Linuxbased systems (eg. Fedora) prebuilt LAPACK, BLAS and ATLAS packages are available,
however you may need to explicitly install them (before installing Armadillo).
Make sure you also install the related development packages (which contain header files).

Mac OS X comes with versions of BLAS and LAPACK via the Accelerate framework.
Armadillo's automatic installer can make use of the Accelerate framework by default.

For Windows systems, Armadillo comes with precompiled 64 bit versions of LAPACK and BLAS.
See the download page for more info.
 How can I use highspeed LAPACK and BLAS replacements
(eg.
OpenBLAS,
Intel MKL,
AMD ACML) ?

Simply link with the replacement library instead of standard LAPACK and BLAS.
You may need to make minor modifications to "include/armadillo_bits/config.hpp"
in order to make sure Armadillo uses the same style of function names as used by MKL or ACML.
For example, the function names might be in capitals.

For Linuxbased systems the automatic installer can figure out that OpenBLAS, MKL, ACML or ATLAS are installed,
and will use them instead of the standard LAPACK and BLAS libraries.
See README.txt within the Armadillo archive for more information.

If you're getting unresolved symbols during linking,
or the automatic installer can't find your installation of OpenBLAS, MKL or ACML, install Armadillo manually (see README.txt).
Then edit include/armadillo_bits/config.hpp and comment out (ie. disable) ARMA_USE_WRAPPER,
and uncomment (ie. enable) ARMA_USE_LAPACK and ARMA_USE_BLAS.
When compiling Armadillo based programs, link with the relevant OpenBLAS, MKL or ACML libraries instead of BLAS and LAPACK.
Speed
 Is automatic SIMD vectorisation supported (eg. SSE2) ?
Yes. As of version 3.900, elementary expressions (eg. matrix addition, multiplication by scalar)
can be vectorised into SSE2 instructions when using GCC 4.7+ with O3 optimisation.
For example, compile your code using:
g++ myprog.cpp o myprog O3 larmadillo
To get further speedups
(ie. to use
SSE3,
SSE4,
or
AVX
instructions),
or to enable SSE2 on 32 bit machines,
add the march=native option.
For example:
g++ myprog.cpp o myprog O3 march=native larmadillo
 How fast is Armadillo's matrix multiplication ?
Armadillo uses BLAS for matrix multiplication, meaning the speed is dependent on the implementation of BLAS.
You can use highspeed BLAS replacements to obtain considerably higher performance,
such as the multithreaded (parallelised)
OpenBLAS,
or Intel MKL,
or AMD ACML.
Under Mac OS X, the Accelerate framework can be used.
If no BLAS library is available, Armadillo will use its builtin matrix multiply,
which is generally fast enough for small and medium sized matrices.
See also how to use BLAS replacements.
 How fast is Armadillo's eigen decomposition, matrix inversion, etc ?
Armadillo uses LAPACK for various matrix decompositions and factorisations,
meaning the speed is dependent on the implementation of LAPACK and/or BLAS.
You can use highspeed LAPACK and BLAS replacements to obtain considerably higher performance,
such as the multithreaded
OpenBLAS,
or Intel MKL,
or AMD ACML.
Under Mac OS X, the Accelerate framework can be used.
See also how to use LAPACK replacements.
 I have a 64 bit operating system, but my BLAS library is 32 bit. What now ?
In this case it's better to disable the use of BLAS and directly use Armadillo's matrix multiplication.
This can be done by defining ARMA_DONT_USE_BLAS
before including the Armadillo header, ie.:
#define ARMA_DONT_USE_BLAS
#include <armadillo>
Features / Functions
 I've searched the documentation for function X but can't find it. Where is it ?
If it's not in the documentation, it doesn't exist.
See also the answers to development questions.
 Is there support for fixed size (static size) matrices ?
Yes. See the documentation for advanced matrix constructors.
Use of fixed size matrices can help the compiler to optimise.
Use of fixed size matrices is in general recommended only for small matrices (eg. ≤ 10x10, or ≤ 100 elements).
 Is there support for sparse matrices ?
Yes. As of version 3.4, there is preliminary support for sparse matrices.
Sparse matrices are stored in compressed sparse column format via the SpMat class.
Furthermore, dense matrix multiplication and inversion involving diagonal matrices
takes into account sparsity (in order to reduce computation).
 Does Armadillo take into account possible aliasing ?
Yes. Armadillo checks for aliasing wherever it's possible to do so.
In normal usage of the library this means aliasing is always checked.
However, if you're evil enough you can always construct an artificial case to defeat any alias checking mechanism;
in particular, if you construct matrices using writeable auxiliary memory (externally managed memory),
your code will be responsible for taking care of possible aliasing.
 Is it possible to interface Armadillo with other libraries ?
Yes. This can be done by creating matrices (or cubes) that use auxiliary memory,
or by accessing elements through STLstyle iterators,
or by directly obtaining a pointer to matrix memory via the .memptr() function.
 Is it possible to use Armadillo from other languages ?
 Is the API stable ?
Yes, within each major version.
Long answer:
Armadillo's version number is A.B.C, where A is a major version, B is a minor version, and C is the patch level (indicating bug fixes).
Within each major version (eg. 4.x), minor versions with an even number (ie. evenly divisible by two) are backwards compatible with earlier even minor versions.
For example, code written for version 4.000 will work with version 4.100, 4.120, 4.200, etc.
However, as each minor version may have more features (ie. API extensions) than earlier versions,
code specifically written for version 4.100 doesn't necessarily work with 4.000.
Experimental versions are denoted by an odd minor version number (ie. not evenly divisible by two), such as 4.199.
Experimental versions are generally faster and/or have more functionality,
but their APIs have not been finalised yet (though the likelihood of APIs changes is quite low).
We don't like changes to existing APIs and strongly prefer not to break any user software.
However, to allow evolution, we reserve the right to alter the APIs in future major versions of Armadillo
while remaining backwards compatible in as many cases as possible
(eg. version 5.x may have slightly different APIs than 4.x).
In a rare instance the user API may need to be tweaked if a bug fix absolutely requires it.
Development
 Who are the developers ?
Lead development is done by Conrad Sanderson,
located at the NICTA Queensland laboratory.
See also the contact page for list of contributors.
 Do you accept patches ?
Contribution of patches is welcome, provided they're cleanly written and have accompanying documentation.
However, please first describe what you'd like to contribute,
by sending an email.
 Can you implement feature X ?
You're welcome to contribute a patch if you'd like to have a particular feature.
Otherwise we only develop the features that we need.
 Is there a public source code repository ?
See the SVN repository.
Note that the repository contains workinprogress code that may not compile.
 Is there internal documentation for the code ?
See the Doxygen generated class documentation.
NOTE: the class documentation is only for library developers;
for user accessible functions, see the API Reference instead.
Licensing
 What is the license for Armadillo ?
Armadillo version 3.800 and later is licensed using the Mozilla Public License 2.0 (MPL).
Older releases of Armadillo (version 3.6 and earlier) are licensed using the Lesser General Public License 3.0 (LGPL).
The LGPL is no longer used for newer versions.
 Can commercial software be statically linked to Armadillo as a single executable ?
Yes.
 Do I need to release the source code of programs/software/executables that use Armadillo ?
No.
You are free to choose the licensing terms for your code (eg. proprietary application), provided that Armadillo files remain licensed using the MPL.
See the license text for exact details.
See also Mozilla's frequently asked questions about the MPL.
 Do I need to provide a copy of Armadillo along with my software / executable ?
If you haven't modified Armadillo, you can just tell the recipient(s) of your software where they can obtain a copy of Armadillo.
 Do I need to provide the source code of a modified version of Armadillo along with my software / executable ?
If you have modified Armadillo files and distribute software outside your organisation which uses the modified Armadillo files,
you need to make the modified Armadillo files available to the entity using your software.
This can be done by providing the modified Armadillo files along with the software.
Alternatively, this can be done by placing the modified Armadillo files on a publicly accessible web page
and stating the address of the web page within the documentation for your software.
See the license text for exact details.
See also Mozilla's frequently asked questions about the MPL.
In general we recommend that you contribute any changes and/or extensions so that they're exposed to wider testing.
If you'd like to contribute, please see the answers to development questions.
 Will my code be "infected" with the GPL if I use Armadillo ?
No. Armadillo files are licensed under the MPL,
which is a different license to the GPL.
The previously used LGPL is also not the same as the GPL.
 How is the MPL different to the GPL and LGPL ?
See Mozilla's frequently asked questions about the MPL.
 Can MPLlicensed code be used with GPL or LGPL licensed code ?
Yes. See also Mozilla's frequently asked questions about the MPL.
 Is Armadillo a product made by Mozilla ?
No. Armadillo just uses the Mozilla Public License.
Related Libraries
 How is Armadillo related to uBLAS (part of Boost) ?
Armadillo and uBLAS use similar template techniques to handle multi matrix expressions.
While uBLAS (currently) has more matrix types, Armadillo has considerably more accessible syntax (ie. easier to use).
Furthermore, Armadillo provides an efficient wrapper to the LAPACK and ATLAS libraries,
thereby providing functionality and machinedependent optimisations not present in uBLAS (eg. matrix inversion).
 How is Armadillo related to IT++ ?
IT++ does not use delayed evaluation, thereby becoming inefficient (slow) for multi matrix expressions or when handling submatrices.
Furthermore, IT++ is licensed under the GPL without any exceptions, meaning that your code becomes "infected" with the GPL
 this is an issue when developing proprietary/commercial applications.
Lastly, Armadillo has a more thorough treatment of vectors.
 How is Armadillo related to Newmat ?
Newmat has (currently) more matrix types, but does not handle delayed evaluation as well.
Newmat's handling of submatrices is also relatively slow.
Newmat has no provision to use LAPACK or ATLAS, which affects speed.
Miscellaneous
 What was the motivation for Armadillo ?
Armadillo was originally developed as part of a NICTA computer vision R&D project,
in order the provide a solid backbone for computationally intensive experimentation,
while at the same time allowing for relatively painless transition of research code into production environments
(ie. translation of Matlab code to C++).
Previous development frameworks and libraries were unsuitable due to limitations
in terms of speed, features, licensing, coherency, or being unnecessarily difficult to use.
 Are there other open source projects associated with NICTA ?
See OpenNICTA.com.au


