README.md 2.65 KB
Newer Older
1 2 3 4

# Fast5x5

A linear algebra library which focus on 5x5 operations.
Lucas Serrano's avatar
Lucas Serrano committed
5

Lucas Serrano's avatar
Lucas Serrano committed
6
## Dependencies
7 8

For the basic usage of the library:
Lucas Serrano's avatar
Lucas Serrano committed
9
 * libboost (>= 1.62) with `program_options`
10 11 12
 * https://github.com/NumScale/boost.simd.git -b master

For the test and benchmarking
Lucas Serrano's avatar
Lucas Serrano committed
13
 * cmake (>= 3.4)
14 15 16
 * eigen 3.2.10
 * googletest 1.8.0
 * R
Lucas Serrano's avatar
Lucas Serrano committed
17 18

## Using the library
19

Lucas Serrano's avatar
Lucas Serrano committed
20 21
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
22 23

### Importing
24

Lucas Serrano's avatar
Lucas Serrano committed
25 26
There is only one header to import in order to use the library:
```c++
27
#include "../path/to/Fast5x5/fast5x5.hpp"
Lucas Serrano's avatar
Lucas Serrano committed
28 29 30
```

### Creating a matrix
31

Lucas Serrano's avatar
Lucas Serrano committed
32 33
In order to create a matrix you need to create a object from the `BaseMatrix<Type, NRows, NCols>` class
where `NRows` and `NCols` are the matrix dimensions.
Lucas Serrano's avatar
Lucas Serrano committed
34 35

```c++
Lucas Serrano's avatar
Lucas Serrano committed
36
BaseMatrix<float, 2, 3> my_matrix;
Lucas Serrano's avatar
Lucas Serrano committed
37 38 39 40 41 42 43
```

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
44
BaseMatrix<double, 4, 4> my_matrix(data);
Lucas Serrano's avatar
Lucas Serrano committed
45 46 47
```

### Getting the data back
48

Lucas Serrano's avatar
Lucas Serrano committed
49 50
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
51
```c++
Lucas Serrano's avatar
Lucas Serrano committed
52
std::array<double, 4*4> data = my_matrix.dump_array();
Lucas Serrano's avatar
Lucas Serrano committed
53 54 55 56 57 58 59 60
```

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

```c++
std::cout << my_matrix << std::endl;
```
Lucas Serrano's avatar
Lucas Serrano committed
61 62

### Simple example
63

Lucas Serrano's avatar
Lucas Serrano committed
64 65 66 67 68
This is a simple example for matrix multiplication.

```c++
#include <iostream>

69
#include "../Fast-Matrix/fast5x5.hpp"
Lucas Serrano's avatar
Lucas Serrano committed
70 71 72 73 74 75 76 77 78 79 80

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
    };

Lucas Serrano's avatar
Lucas Serrano committed
81 82 83
    BaseMatrix<float, 2, 3> a(left_data);
    BaseMatrix<float, 3, 2> b(right_data);
    BaseMatrix<float, 2, 2> c;
Lucas Serrano's avatar
Lucas Serrano committed
84 85 86 87 88 89 90 91 92 93

    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
94

Lucas Serrano's avatar
Lucas Serrano committed
95 96 97 98 99
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
100
cd /path/to/Fast5x5/
Lucas Serrano's avatar
Lucas Serrano committed
101 102
mkdir build && cd build
export Boost_DIR=/path/to/boost/root # Only if you didn't install boost from your distribution
Lucas Serrano's avatar
Lucas Serrano committed
103
cmake -D CMAKE_PREFIX_PATH=path/to/boost.simd_build_dir/ ..
Lucas Serrano's avatar
Lucas Serrano committed
104 105 106 107 108 109
make
```
Once the tests are built you can launch them from the test directory.
```bash
test/unit_tests
```