README.md 2.62 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 9 10

## Testing

## Using the library
Lucas Serrano's avatar
Lucas Serrano committed
11 12
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
13 14 15 16 17 18 19 20

### 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
21 22
In order to create a matrix you need to create a object from the `BaseMatrix<Type, NRows, NCols, MatSize, MaxVecSize>` class
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
23 24

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

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
33
BaseMatrix<double, 4, 4, 4> my_matrix(data);
Lucas Serrano's avatar
Lucas Serrano committed
34 35 36
```

### Getting the data back
Lucas Serrano's avatar
Lucas Serrano committed
37 38
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
39
```c++
Lucas Serrano's avatar
Lucas Serrano committed
40
std::array<double, 4*4> data = my_matrix.dump_array();
Lucas Serrano's avatar
Lucas Serrano committed
41 42 43 44 45 46 47 48
```

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

```c++
std::cout << my_matrix << std::endl;
```
Lucas Serrano's avatar
Lucas Serrano committed
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 94 95

### 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
```