README.md 2.6 KB
Newer Older
Lucas Serrano's avatar
Lucas Serrano committed
1
# FastMatrix
Lucas Serrano's avatar
Lucas Serrano committed
2 3
FastMatrix: A very efficient linear algebra library for extremely small matrices.

Lucas Serrano's avatar
Lucas Serrano committed
4 5
## Dependencies
 * libboost (>= 1.61)
Lucas Serrano's avatar
Lucas Serrano committed
6
 * Boost.Simd
Lucas Serrano's avatar
Lucas Serrano committed
7 8

## Using the library
Lucas Serrano's avatar
Lucas Serrano committed
9 10
FastMatrix is a template-based header-only library.
That means the only requirement is to correctly add Boost.SIMD and Boost include directory at the list of directories used by your compiler.
Lucas Serrano's avatar
Lucas Serrano committed
11 12 13 14 15 16 17 18

### Importing
There is only one header to import in order to use the library:
```c++
#include "../path/to/Fast-Matrix/fast_matrix.hpp"
```

### Creating a matrix
Lucas Serrano's avatar
Lucas Serrano committed
19
In order to create a matrix you need to create a object from the `BaseMatrix<Type, NRows, NCols, MaxVecSize>` class
Lucas Serrano's avatar
Lucas Serrano committed
20
where `NRows` and `NCols` are the matrix dimensions and `MaxVecSize` the maximum vector size of type `Type` your hardware can support.
Lucas Serrano's avatar
Lucas Serrano committed
21 22

```c++
Lucas Serrano's avatar
Lucas Serrano committed
23
BaseMatrix<float, 2, 3, 8> my_matrix;
Lucas Serrano's avatar
Lucas Serrano committed
24 25 26 27 28 29 30
```

By default your matrix will be initialized to zero.
If you want to initialize it to existing values you can pass an array to the constructor.
Values in the array are considered to be row-major.
```c++
double data[16] {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,160};
Lucas Serrano's avatar
Lucas Serrano committed
31
BaseMatrix<double, 4, 4, 4> my_matrix(data);
Lucas Serrano's avatar
Lucas Serrano committed
32 33 34
```

### Getting the data back
Lucas Serrano's avatar
Lucas Serrano committed
35 36
You can dump the matrix data with the `dump_array()` method.
The returned value is an std::array in row-major order.
Lucas Serrano's avatar
Lucas Serrano committed
37
```c++
Lucas Serrano's avatar
Lucas Serrano committed
38
std::array<double, 4*4> data = my_matrix.dump_array();
Lucas Serrano's avatar
Lucas Serrano committed
39 40 41 42 43 44 45 46
```

### Printing values
`BaseMatrix` objects are printable with the `<<` operator:

```c++
std::cout << my_matrix << std::endl;
```
Lucas Serrano's avatar
Lucas Serrano committed
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93

### Simple example
This is a simple example for matrix multiplication.

```c++
#include <iostream>

#include "../Fast-Matrix/fast_matrix.hpp"

int main (int argc, char **argv) {
    float left_data[6] = {
        1, 2, 3,
        4, 5, 6
    };
    float right_data[6] = {
        7, 8, 9,
        10, 11, 12
    };

    BaseMatrix<float, 2, 3, 8> a(left_data);
    BaseMatrix<float, 3, 2, 8> b(right_data);
    BaseMatrix<float, 2, 2, 8> c;

    matrix_mul_m_m(a, b, c); // The matrix product c = a*b

    std::cout << "A" << std::endl << a << std::endl;
    std::cout << "B" << std::endl << b << std::endl;
    std::cout << "C = A * B" << std::endl << c << std::endl;
}
```

## Testing
Testing functionalities of the library is available through a set of unit tests.
Prior running the tests you must build them with cmake.
Building them require to build Boost.SIMD first.

```bash
cd /path/to/Fast-Matrix/
mkdir build && cd build
export Boost_DIR=/path/to/boost/root # Only if you didn't install boost from your distribution
cmake -D CMAKE_PREFIX_PATH=path/to/boost.simd/build ..
make
```
Once the tests are built you can launch them from the test directory.
```bash
test/unit_tests
```