---
title: "Armadillo configuration"
output: rmarkdown::html_vignette
bibliography: "references.bib"
vignette: >
  %\VignetteIndexEntry{Armadillo configuration}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

If you vendor `cpp11armadillo`, Armadillo options on C++ side can be configured via editing the file `include/armadillo/config.hpp`.

Specific functionality can be enabled or disabled by uncommenting or commenting out a particular `#define`, listed below.

Some options can also be specified by explicitly defining them before including the armadillo header in `cpp` scripts. For example:


```cpp
#define ARMA_WARN_LEVEL 1

#include <cpp11.hpp>
#include <cpp11armadillo.hpp>

[[cpp11::register]] my_fun() {
  // some linear algebra code
  // ...
}
```

| Option | Description |
|--------|-------------|
| `ARMA_DONT_USE_WRAPPER` | Disable going through the run-time Armadillo wrapper library (`libarmadillo.so`) when calling LAPACK, BLAS, ARPACK, and SuperLU functions. You will need to directly link with BLAS, LAPACK, etc (eg. `-lblas -llapack`) |
| `ARMA_USE_LAPACK` | Enable use of LAPACK, or a high-speed replacement for LAPACK (eg. OpenBLAS, Intel MKL, or the Accelerate framework). Armadillo requires LAPACK for functions such as `svd()`, `inv()`, `eig_sym()`, `solve()`, etc. |
| `ARMA_DONT_USE_LAPACK` | Disable use of LAPACK; overrides `ARMA_USE_LAPACK` |
| `ARMA_USE_BLAS` | Enable use of BLAS, or a high-speed replacement for BLAS (eg. OpenBLAS, Intel MKL, or the Accelerate framework). BLAS is used for matrix multiplication. Without BLAS, Armadillo will use a built-in matrix multiplication routine, which might be slower for large matrices. |
| `ARMA_DONT_USE_BLAS` | Disable use of BLAS; overrides `ARMA_USE_BLAS` |
| `ARMA_USE_NEWARP` | Enable use of NEWARP (built-in alternative to ARPACK). This is used for the eigen decomposition of real (non-complex) sparse matrices, ie. `eigs_gen()`, `eigs_sym()` and `svds()`. Requires `ARMA_USE_LAPACK` to be enabled. If use of both NEWARP and ARPACK is enabled, NEWARP will be preferred. |
| `ARMA_DONT_USE_NEWARP` | Disable use of NEWARP (built-in alternative to ARPACK); overrides `ARMA_USE_NEWARP` |
| `ARMA_USE_ARPACK` | Enable use of ARPACK, or a high-speed replacement for ARPACK. Armadillo requires ARPACK for the eigen decomposition of complex sparse matrices, ie. `eigs_gen()`, `eigs_sym()` and `svds()`. If use of NEWARP is disabled, ARPACK will also be used for the eigen decomposition of real sparse matrices. |
| `ARMA_DONT_USE_ARPACK` | Disable use of ARPACK; overrides `ARMA_USE_ARPACK` |
| `ARMA_USE_SUPERLU` | Enable use of SuperLU, which is used by `spsolve()` for finding the solutions of sparse systems, as well as `eigs_sym()` and `eigs_gen()` in shift-invert mode. You will need to link with the superlu library, for example `-lsuperlu` |
| `ARMA_DONT_USE_SUPERLU` | Disable use of SuperLU; overrides `ARMA_USE_SUPERLU` |
| `ARMA_USE_HDF5` | Enable the ability to save and load matrices stored in the HDF5 format; the `hdf5.h` header file must be available on your system and you will need to link with the hdf5 library (eg. `-lhdf5`) |
| `ARMA_DONT_USE_HDF5` | Disable the use of the HDF5 library; overrides `ARMA_USE_HDF5` |
| `ARMA_USE_FFTW3` | Enable use of the FFTW3 library by `fft()` and `ifft()`; you will need to link with the FFTW3 library (eg. `-lfftw3`) |
| `ARMA_DONT_USE_FFTW3` | Disable the use of the FFTW3 library; overrides `ARMA_USE_FFTW3` |
| `ARMA_DONT_USE_STD_MUTEX` | Disable use of `std::mutex`; applicable if your compiler and/or environment doesn't support `std::mutex` |
| `ARMA_DONT_OPTIMISE_BAND` | Disable automatically optimised handling of band matrices by `solve()` and `chol()` |
| `ARMA_DONT_OPTIMISE_SYMPD` | Disable automatically optimised handling of symmetric/hermitian positive definite matrices by `solve()`, `inv()`, `pinv()`, `expmat()`, `logmat()`, `sqrtmat()`, `powmat()`, `rcond()` |
| `ARMA_USE_OPENMP` | Use OpenMP for parallelisation of computationally expensive element-wise operations (such as `exp()`, `log()`, `cos()`, etc). Automatically enabled when using a compiler which has OpenMP 3.1+ active (eg. the `-fopenmp` option for gcc and clang). |
| `ARMA_DONT_USE_OPENMP` | Disable use of OpenMP for parallelisation of element-wise operations; overrides `ARMA_USE_OPENMP` |
| `ARMA_OPENMP_THRESHOLD` | The minimum number of elements in a matrix to enable OpenMP based parallelisation of computationally expensive element-wise functions; default value is 320 |
| `ARMA_OPENMP_THREADS` | The maximum number of threads for OpenMP based parallelisation of computationally expensive element-wise functions; default value is 8 |
| `ARMA_BLAS_CAPITALS` | Use capitalised (uppercase) BLAS and LAPACK function names (eg. `DGEMM` vs `dgemm`) |
| `ARMA_BLAS_UNDERSCORE` | Append an underscore to BLAS and LAPACK function names (eg. `dgemm_` vs `dgemm`). Enabled by default. |
| `ARMA_BLAS_LONG_LONG` | Use `"long long"` instead of `"int"` when calling BLAS and LAPACK functions; the `"long long"` type is a 64 bit integer type on all platforms |
| `ARMA_USE_FORTRAN_HIDDEN_ARGS` | Use so-called "hidden arguments" when calling BLAS and LAPACK functions. Enabled by default. See Fortran argument passing conventions for more details. |
| `ARMA_DONT_USE_FORTRAN_HIDDEN_ARGS` | Disable use of so-called "hidden arguments" when calling BLAS and LAPACK functions. May be necessary when using Armadillo in conjunction with broken MKL headers (eg. if you have `#include "mkl_lapack.h"` in your code). |
| `ARMA_USE_TBB_ALLOC` | Use Intel TBB `scalable_malloc()` and `scalable_free()` instead of standard `malloc()` and `free()` for managing matrix memory |
| `ARMA_USE_MKL_ALLOC` | Use Intel MKL `mkl_malloc()` and `mkl_free()` instead of standard `malloc()` and `free()` for managing matrix memory |
| `ARMA_USE_MKL_TYPES` | Use Intel MKL types for complex numbers. You will need to include appropriate MKL headers before the Armadillo header. You may also need to enable one or more of the following options: `ARMA_BLAS_LONG_LONG`, `ARMA_DONT_USE_FORTRAN_HIDDEN_ARGS` |
| `ARMA_64BIT_WORD` | Use 64 bit integers for matrix and vector sizes. Automatically enabled when using a 64-bit platform, except when using Armadillo in the R environment (via RcppArmadillo). Useful if matrices/vectors capable of holding more than 4 billion elements are required. This can also be enabled by adding `#define ARMA_64BIT_WORD` before each instance of `#include <armadillo>`. See also the `ARMA_BLAS_LONG_LONG` option. |
| `ARMA_MAT_PREALLOC` | The number of pre-allocated elements used by matrices and vectors. Must be always enabled and set to an integer that is at least 1. By default set to 16. If you mainly use lots of very small vectors (eg. ≤ 4 elements), change the number to the size of your vectors. |
| `ARMA_COUT_STREAM` | The default stream used for printing matrices and cubes by `.print()`. Must be always enabled. By default defined to `std::cout` |
| `ARMA_CERR_STREAM` | The default stream used for printing warnings and errors. Must be always enabled. By default defined to `std::cerr` |
| `ARMA_WARN_LEVEL` | The level of warning messages printed to `ARMA_CERR_STREAM`. Must be an integer ≥ 0. By default defined to 2.<br>0 = no warnings; generally not recommended.<br>1 = only critical warnings about arguments and/or data which are likely to lead to incorrect results.<br>2 = as per level 1, and warnings about poorly conditioned systems (low `rcond`) detected by `solve()`, `spsolve()`, etc.<br>3 = as per level 2, and warnings about failed decompositions, failed saving / loading, etc. |

# References