C++ linear algebra library

API Docs

Bugs · General · Dependencies/External Libraries · Speed · Features/Functions · Development · Licensing · Related · Misc


  • How do I report bugs ?
    If you find a bug, either in the library or the documentation, we are interested in hearing about it. Please make a small self-contained program which exposes the bug, and then send the source code (and the bug description) as an email. We appreciate your time to make a bug report.
  • I'm using an Armadillo package that comes with Ubuntu/Debian/Fedora/SUSE, and a lot of functions appear to be missing.
    Armadillo packages that come with Linux distributions can be outdated. You can manually upgrade to the latest version.
  • Linux/Mac OS X: I'm getting lots of unresolved symbols during compilation
    Two possible solutions:

    Use the cmake-based installer to install Armadillo as described in the README.txt file.
    Then link your programs with the armadillo wrapper library:
    g++ abc.cpp -o abc -O2 -larmadillo


    Use Armadillo without installation, and directly link your programs with BLAS and LAPACK instead of the armadillo wrapper library.
    Assuming the armadillo archive (eg. armadillo-6.200.4.tar.gz) was unpacked in /home/blah, compile your programs using:
    g++ abc.cpp -o abc -O2 -I /home/blah/armadillo-6.200.4/include -lblas -llapack
    • On Mac OS X, -llapack -lblas may need to be replaced with -framework Accelerate
    • You can link with high-speed OpenBLAS instead of standard BLAS by changing  -lblas -llapack  to  -lopenblas -llapack 
      See also how to use BLAS and LAPACK replacements.

  • I'm using the C++11 auto keyword with Armadillo functions and get weird results.
    Use of C++11 auto is not recommended with Armadillo objects and expressions. Armadillo has a template meta-programming framework which creates lots of short lived temporaries that are not handled by auto. Always assign the result of an expression to a scalar, vector or matrix. The expressions can be arbitrarily long (up to a limit imposed by the compiler).


  • 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 gnuplot-cpp, gnuplot-iostream, 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
      SmartGridToolbox Smart Grid simulation library
      SigPack C++ signal processing library
      foreground robust foreground estimation / background subtraction algorithm
      groupsac algorithm for geometric vision problems
      GRASTA low rank subspace object tracking
      background_est clean background estimation from cluttered scenes
      SMART+ analysis of mechanics of materials
      ERKALE quantum chemistry
      libdynamica numerical methods used in physics
      ECOC PAK error correcting output codes
      gplib C++ Gaussian process library
      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)
      OptGpSampler sampling genome-scale metabolic networks
      GStream genetics (SNP and CNV genotyping)
      Mantella analysis and solution to real-world online optimisation problems
      liger integrated optimisation environment
      GNSS-SDR global navigation satellite system receiver
      Flow123d simulator of underground water flow
      matlab2cpp tool for converting Matlab code to Armadillo based C++ code
      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 built-in 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 Linux-based systems (eg. Fedora) pre-built 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 pre-compiled 64 bit versions of LAPACK and BLAS. See the download page for more info.
  • How can I use high-speed 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 Linux-based 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.


  • 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 high-speed BLAS replacements to obtain considerably higher performance, such as the multi-threaded (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 built-in 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 high-speed LAPACK and BLAS replacements to obtain considerably higher performance, such as the multi-threaded 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>
  • Can I use Armadillo with a GPU or OpenCL to speed up large matrix multiplications?
    Yes. You can link with NVIDIA NVBLAS which is a GPU-accelerated implementation of BLAS, or with AMD ACML which will take advantage of GPUs through OpenCL.

Features / Functions

  • I can't find my favourite function in the documentation. Where is it ?
    If it's not in the documentation, it doesn't exist. See also the answers to development questions.
  • Can Armadillo make use of C++11 features ?
    Yes. Armadillo will enable extra features (such as move constructors) when a C++11 compiler is detected. You may need to explicitly enable C++11 mode in your compiler (eg. -std=c++11 in gcc & clang).
  • Can I use the C++11 auto keyword with Armadillo objects and/or expressions?
    Use of C++11 auto is not recommended with Armadillo objects and expressions, due to the extensive use of template meta-programming.
  • Is Armadillo a C++11 only library ?
    No. Armadillo will work with compilers supporting the older C++98 and C++03 standards, as well as the newer C++11 and C++14 standards.
  • 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 STL-style iterators, or by directly obtaining a pointer to matrix memory via the .memptr() function.
  • Is it possible to use Armadillo matrices with user-defined/custom element types ?
    Armadillo supports matrices with the following element types: float, double, std::complex<float>, std::complex<double>, short, int, long, and unsigned versions of short, int, long. Support for other types is beyond the scope of Armadillo.
  • 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.

    This policy is applicable to the APIs described in the documentation; it is not applicable to internal functions (ie. the underlying internal implementation details may change across consecutive minor versions)


  • 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.
  • Can you implement my favourite feature ?
    We only develop the features that we need. However, you're welcome to contribute a patch which implements the functionality you need.
  • Do you accept patches ?
    Contribution of patches is welcome, provided they are cleanly written, tested, and have accompanying documentation. Please first describe what you'd like to contribute by sending an email.
  • Is there a public source code repository ?
    See the SVN repository. Note that the repository contains work-in-progress code that may not compile.


  • 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 ?
  • 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 MPL-licensed 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 machine-dependent 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 sub-matrices. 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 sub-matrices is also relatively slow. Newmat has no provision to use LAPACK or ATLAS, which affects speed.


  • 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 ?

Get Armadillo C++ matrix library at Fast, secure and Free Open Source software downloads