armadillo
 
Armadillo
C++ linear algebra library

 
 
      
About
License
Questions
API Docs
Speed
Authors
Download

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




Bugs

  • 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 getting messages such as "use of LAPACK needs to be enabled".
    Edit include/armadillo_bits/config.hpp and uncomment ARMA_USE_LAPACK. See the README.txt file that comes with the Armadillo archive for more information.
  • 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:

    (1)
    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
    

    OR

    (2)
    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-4.450.0.tar.gz) was unpacked in /home/blah, compile your programs using:
    g++ abc.cpp -o abc -O2 -I /home/blah/armadillo-4.450.0/include -DARMA_USE_BLAS -DARMA_USE_LAPACK -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.




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 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
       
      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
      GNSS-SDR global navigation satellite system receiver
       
      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 80+ 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.



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



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 STL-style 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 work-in-progress 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 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.



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


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