Introduction to Armadillo

Armadillo is an efficient linear algebra library for C++, that balances speed and ease of use. We recommend using this library for numerical linear algebra computations in this course.

We’ll cover some of the very basics of Armadillo here to get you started with the library. A complete overview of the available classes and functions, along with usage examples, can be found in the Armadillo code documentation.

Building code with Armadillo

We must make sure to include the header file for Armadillo, which amounts to adding #include <armadillo> at the top of a header or source file.

Compiling code with Armadillo

For macOS users specifically, you must specificy a version of C++ that is C++11 or later. This is done by adding the compiler flag -std=c++11 during compilation.

For Linux users, nothing special is typically required.

Linking code with Armadillo

To link to Armadillo, we must add the compiler flag -larmadillo during linking.

Vectors

Armadillo provides a useful vector class arma::vec that can be used to replace arrays in numerical computations. Assume n is a positive integer.

Declaring and filling vectors

arma::vec x = arma::vec(n); //Initialize vector but don't fill it.
arma::vec y = arma::vec(n).fill(2.); //Declare and fill a vector with 2's.
arma::vec z = arma::vec(n).randu(); //Declare and fill a vector with random values from a uniform distribution.
arma::vec u = arma::vec("0.0 0.1 0.2"); //Declare and fill a vector with the values 0.1, 0.2 and 0.3.

Accessing and assigning elements in a vector

We can access an element i from a vector x by

double x_i = x(i); //Extract element i of x and assign it to x_i.

We can assign a new value to element i in the vector x using

x(i) = some_new_value;

Matrices

Assume that n and m are positive integers.

Declaring and filling matrices

Creating matrices with Armadillo is easy. Here’s a couple examples:

arma::mat A = arma::mat(n, m); //Initialize matrix but don't fill.
arma::mat B = arma::mat(n, m).fill(0.); //Declare and fill a matrix with zeros.
arma::mat C = arma::mat(n, m).randn(); //Declare and fill a matrix with random values from the normal distribution.
arma::mat D = arma::mat("0.0 0.1 0.2 ; 1.0 1.1 1.2 ; 2.0 2.1 2.2"); //Declare and fill a 3x3 matrix with the listed values. (Note the semicolons.)

Accessing elements in a matrix

Access of elements in an Armadillo matrix is done as follows:

double A_ij = A(i,j); //Assign element (i,j) of the matrix A to A_ij.

Extracting a column of a matrix

Armadillo provides a simple way to extract entire columns of a matrix:

arma::vec col_vec = A.col(j); //Extract column j of A and assign it to col_vec.

Read matrix columns in a given order

A particular task that may be useful in this course is to read the columns of a matrix in a specific order. Below is an example that uses arma::sort_index to find the index ordering that sorts a given vector (from low to high values), and then sorts both the vector and the columns of a matrix according to this ordering.

arma::mat A = arma::mat("0.0 0.1 0.2 ; 1.0 1.1 1.2 ; 2.0 2.1 2.2");
arma::vec x = arma::vec("20. 10. 30.");

arma::uvec x_sort_indices = arma::sort_index(x); // Get index ordering that sorts x.
  
x = x(x_sort_indices); // Sort x according to ordering in x_sort_indices.
A = A.cols(x_sort_indices); // Sort columns of A according to ordering in x_sort_indices.

Saving and loading vectors and matrices

Armadillo provides built-in functionality for saving and loading arma::vec and arma::mat objects to binary files. Not only does this simplify storage of results with a predictable format, but it turns out that they provide a Python module pyarma that can me used to load in these objects directly into a Python program!

If A is an arma::mat object, you can save it using

A.save(filename);

The default storage format is binary. Your filename should end with .bin. Loading the object is as simple as

B = arma::mat() //Initialize an arma::mat variable
B.load(filename) //Load content of arma::mat A stored earlier into arma::mat B.

Reading a data table in text format

The load functionality in Armadillo can also be used to load data from files not generated by Armadillo, as long as the data file has some standard format (see the Armadillo documentation for details). For instance, assume we have a text file mynumbers.dat looking like this:

0.0000e+00  0.0000e+00  0.0000e+00
0.0000e+00  1.9635e-01  3.8553e-02
0.0000e+00  3.9270e-01  1.5421e-01
0.0000e+00  5.8905e-01  3.4698e-01
0.0000e+00  7.8540e-01  6.1685e-01
1.9635e-01  0.0000e+00  1.9635e-01
1.9635e-01  1.9635e-01  2.4247e-01
1.9635e-01  3.9270e-01  3.6569e-01
1.9635e-01  5.8905e-01  5.6599e-01
1.9635e-01  7.8540e-01  8.4336e-01
3.9270e-01  0.0000e+00  3.9270e-01
3.9270e-01  1.9635e-01  4.6150e-01
3.9270e-01  3.9270e-01  6.0723e-01
3.9270e-01  5.8905e-01  8.2971e-01
3.9270e-01  7.8540e-01  1.1288e+00
5.8905e-01  0.0000e+00  5.8905e-01
5.8905e-01  1.9635e-01  6.9558e-01
5.8905e-01  3.9270e-01  8.7831e-01
5.8905e-01  5.8905e-01  1.1363e+00
5.8905e-01  7.8540e-01  1.4688e+00

To read these numbers into an Armadillo matrix, we simply do this:

arma::mat A;
A.load("mynumbers.dat", arma::raw_ascii)

The Python module

You can install the Armadillo Python module pyarma using

pip install pyarma

The recommended way to import the library in Python is

import pyarma as pa

From there, you can easily load the arma::mat (or arma::vec) object you saved in C++ using

A = pa.mat() #Create pa.mat object (just as arma::mat in C++)
A.load(filename) #Load the content of the matrix you saved into your Python program.