Armadillo: C++ library for linear algebra & scientific computing (original) (raw)

Jump to:

• Bug Reports
• Citation
• Distribution License
• Linking
• Speed
• Development
• Features
• 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.

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 ARMADONTUSEWRAPPER before including the armadillo header. For example:

#define ARMA_DONT_USE_WRAPPER
#include
or, if you're using gcc or clang, you can declare the define directly on the command line:

g++ prog.cpp -o prog -std=c++11 -O2 -I /home/xyz/armadillo-12.0.1/include -DARMA_DONT_USE_WRAPPER -lopenblas
* If you don't have OpenBLAS installed, on Linux change -lopenblas to -lblas -llapackand 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:

g++ prog.cpp -o prog -O2 -I /home/xyz/armadillo-12.0.1/include -DARMA_DONT_USE_WRAPPER -L /home/xyz/OpenBLAS-0.3.20 -lopenblas

* 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 useAVXinstructions), 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 matricestakes 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, std::complex, 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

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 documentationand/or the README file that comes with the Armadillo archive.
• Is it possible to plot Armadillo data directly from C++ ?
  Yes. Trymatplotlib-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.