Armadillo: C++ library for linear algebra & scientific computing

Jump to:

Bug Reports
Citation
Distribution License
Linking
Speed
Development
Features
Related Software
Miscellaneous

Bug Reports

I found a possible bug in the code and/or documentation. How do I report it ?
Please make a small and self-contained program which exposes the bug, and then open an issue at the GitLab repo, or inform the developers via email. The small program should have a main() function and use only functions/classes from Armadillo and the standard C++ library (no other libraries). We appreciate your time to make a bug report.

Citation

How do I cite Armadillo in my work ?
Please cite the following papers if you use Armadillo in your research and/or software.
Citations are useful for the continued development and maintenance of the library.
Conrad Sanderson and Ryan Curtin.
Armadillo: An Efficient Framework for Numerical Linear Algebra.
arXiv:2502.03000, 2025.

Conrad Sanderson and Ryan Curtin.
Practical Sparse Matrices in C++ with Hybrid Storage and Template-Based Expression Optimisation.
Mathematical and Computational Applications, Vol. 24, No. 3, 2019.

Distribution License

What is the distribution license for Armadillo ?
Armadillo versions 7.800 and onwards are licensed under the Apache License 2.0.
The Apache license is a permissive license; its main conditions simply require preservation of copyright and license notices. See also a Quick Summary of the license.

Can I use Armadillo in commercial products without releasing the source code ?
Yes. Armadillo can be used in proprietary software, without releasing the source code. However, any software that incorporates or distributes Armadillo in source or binary form must include a readable copy of the attributions in the NOTICE.txt file that comes with Armadillo. The attributions can be placed in the documentation and/or other materials provided with the software.

How is the Apache License related to the GPL ?
The Apache license and the GPL are completely separate and distinct licenses. Unlike the GPL, the Apache license does not "infect" your source code. See also the comparison of open-source software licenses on Wikipedia.

How is the Apache license related to the MIT and BSD licenses ?
The Apache license is a permissive license similar to the MIT and BSD licenses, but also provides a grant of patent rights from contributors to users. As such, the Apache license can be thought of as an improved version of the MIT and BSD licenses.

Is Armadillo a product from the Apache Software Foundation ?
No. We just use the Apache license.

Linking

I'm getting lots of unresolved symbols during compilation
Use the CMake installer to install Armadillo as described in the README file.
Then link your programs with the armadillo run-time library:
```
g++ prog.cpp -o prog -std=c++11 -O2 -larmadillo
```
What does the Armadillo run-time library do ?
The Armadillo run-time library is generated by the CMake installer and is a wrapper for all the relevant libraries present on your system, such as OpenBLAS, LAPACK, BLAS, ARPACK, SuperLU, ATLAS. On Linux and macOS, the run-time library also provides a C++11 thread-safe random number generator.

How can I link directly with BLAS and LAPACK without using the Armadillo run-time library ?
Define ARMA_DONT_USE_WRAPPER before including the armadillo header. For example:
or, if you're using gcc or clang, you can declare the define directly on the command line:
- If you don't have OpenBLAS installed, on Linux change -lopenblas to -lblas -llapack and on macOS change -lopenblas to -framework Accelerate
Can I use Armadillo as a pure template library ?
Yes. See the answer to the previous question.
Can I use Armadillo 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) may not be as fast.

Where do I get LAPACK, BLAS, etc ?
- For Linux-based systems (eg. Fedora and Ubuntu) pre-built OpenBLAS, LAPACK, BLAS and ATLAS packages are available. You need to explicitly install them before installing Armadillo. Make sure you also install the related development packages (which contain header files).
- macOS comes with the Accelerate framework, which is an optimised implementation of BLAS and LAPACK. The CMake installer can make use of the Accelerate framework by default.
- For Windows systems, Armadillo comes with pre-compiled 64 bit versions of standard LAPACK and BLAS. See the download page for more info.

Can I use high-speed LAPACK and BLAS replacements (eg. OpenBLAS, MKL) ?
Yes. The CMake installer should figure out they are available on your system. Otherwise, you can directly link with such libraries -- see the answers to preceding questions.

How can I use Armadillo with OpenBLAS installed in a non-standard location?
Unpack the Armadillo tar.xz archive and DO NOT install it using the CMake installer.
Compile your programs using:
- Replace /home/xyz with whatever your home directory is called
- Replace /home/xyz/OpenBLAS-0.3.20 with the directory name containing the OpenBLAS library
- You may also need to tell the system linker where to find the OpenBLAS library (eg. by modifying the LD_LIBRARY_PATH environment variable in Linux)

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.8+ with -O3 optimisation. Same applies to recent versions of the clang compiler. For example, compile your code using:
```
g++ prog.cpp -o prog -O3 -larmadillo 
```
To get further speedups (ie. to use AVX instructions), or to enable SSE2 on 32 bit machines, add the -march=native option. For example:
```
g++ prog.cpp -o prog -O3 -march=native -larmadillo
```

Is automatic parallelisation (speed up) via OpenMP supported ?
Yes. As of version 7.900, computationally expensive element-wise functions (such as exp(), log(), cos(), etc) can be executed in parallel via OpenMP. This is automatically enabled when using a C++11/C++14 compiler which has OpenMP 3.1+ active. For example, compile your code using:
```
g++ prog.cpp -o prog -O3 -larmadillo -std=c++11 -fopenmp
```

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 MKL. Under macOS, 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 MKL. Under macOS, the Accelerate framework can be used. See also how to use LAPACK replacements.

Can I use Armadillo with a GPU to speed up large matrix multiplications?
You can link with NVBLAS which is a GPU-accelerated implementation of BLAS. We are also working on the Bandicoot GPU accelerator add-on, which will provide a set of functions (such as matrix decompositions) that process Armadillo matrices on GPUs.

Development

Who are the developers ?
Lead development is done by Conrad Sanderson and Ryan Curtin.

Can you implement features on request ?
Sorry, no.

Can I contribute new functionality ?
Contributions are welcome, provided they are cleanly written, tested, and have accompanying documentation.

Is there a source code repository ?
Yes. See gitlab.com/conradsnicta/armadillo-code. Note that the repository may contain work-in-progress code that has not been tested thoroughly.

What happened to the source code repository at GitHub ?
We moved the repository to GitLab, as Microsoft has acquired GitHub.
Microsoft is a nefarious entity with a long and consistent history of unconscionable & unethical behaviour.

Features / Functions

Is the API stable ?
Yes, within each major version. See the documentation for more details.

I need a specific function, but can't find in the documentation.
If it's not in the documentation, it doesn't exist yet. You can contribute the functionality -- see the answers to development questions.

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.

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. Armadillo has a template meta-programming framework which creates lots of short lived temporaries that are not handled by auto.

Is Armadillo a C++11 only library ?
Armadillo 10.x and later versions require C++11. Armadillo 9.x and earlier versions can work with compilers supporting only the old C++98/C++03 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. The minimum recommended version is 9.600, which has considerably improved support for sparse matrices than earlier versions. 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 ?
- Python:
  - CARMA provides bidirectional conversion of Armadillo matrices and NumPy arrays
  - PyArmadillo provides a user-friendly linear algebra library in Python, based on Armadillo and pybind11;
    see also the paper PyArmadillo: a streamlined linear algebra library for Python
- R language:
  - RcppArmadillo provides a bidirectional interface between R and Armadillo; used by 1000+ R packages;
    see also the paper RcppArmadillo: Accelerating R with high-performance C++ linear algebra
- Go / Julia:
  - mlpack provides bidirectional interfaces between Go / Julia and Armadillo matrices

Related Software & Libraries

Are there open source projects using Armadillo ?
Yes. Examples:


ensmallen		fast non-linear numerical optimisation library
mlpack		extensive library of machine learning algorithms
SigPack		C++ signal processing library
PyArmadillo		linear algebra library for Python with Matlab-like syntax

Rehuel		C++ library for solving ordinary differential equations
SOT		surrogate based optimization algorithms
numerics		various numerical algorithms (interpolation, integration, differential equations, finite difference methods, etc)
GDB Armadillo helpers		pretty printers for debugging Armadillo-based code with GDB

CARMA		bidirectional interface between Python (Numpy) and Armadillo
PyJet		speed up Python / NumPy code via automatic conversion to C++
matlab2cpp		tool for converting Matlab code to C++
RcppArmadillo		bridge between R and Armadillo, used by 800+ R packages

nmflibrary		distributed non-negative matrix factorisation
SmartGridToolbox		Smart Grid simulation library
libpca		principal component analysis library
gplib		C++ Gaussian process library

foreground		robust foreground estimation / background subtraction algorithm
GRASTA		low rank subspace object tracking
background_est		clean background estimation from cluttered scenes

ERKALE		quantum chemistry
SMART+		analysis of mechanics of materials
QIClib		Quantum Information and Computation library

NeuralNet		GPU / CPU implementation of a feed forward neural network
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)

Vespucci		tool for spectroscopic data analysis and imaging
GNSS-SDR		global navigation satellite system receiver
ECOC PAK		error correcting output codes
Flow123d		simulator of underground water flow

L0Learn		efficient algorithms for L0 regularised learning
suanPan		parallel and heterogeneous finite element analysis framework

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

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 file that comes with the Armadillo archive.

Is it possible to plot Armadillo data directly from C++ ?
Yes. Try matplotlib-cpp, gnuplot-cpp, gnuplot-iostream, scopemm.

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.