README.md 2.94 KB
Newer Older
1 2


3
# Fast5x5
Lucas Serrano's avatar
Lucas Serrano committed
4

5

6
A linear algebra library which focus on 5x5 operations.
7

Lucas Serrano's avatar
Lucas Serrano committed
8

9
---
Lucas Serrano's avatar
Lucas Serrano committed
10
## Using the library
11

12
#### Dependencies
Lucas Serrano's avatar
Lucas Serrano committed
13

14 15 16 17 18
Fast5x5 is a template-based header-only library, relying on Boost (>= 1.62) and
Boost.SIMD (master branch). The only usage requirement is to correctly add Boost.SIMD and
Boost include directory at the list of directories used by your compiler.

#### Importing
19

Lucas Serrano's avatar
Lucas Serrano committed
20 21
There is only one header to import in order to use the library:
```c++
22
#include "../path/to/Fast5x5/fast5x5.hpp"
Lucas Serrano's avatar
Lucas Serrano committed
23 24
```

25
#### Creating a matrix
26

Lucas Serrano's avatar
Lucas Serrano committed
27 28
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
29 30

```c++
Lucas Serrano's avatar
Lucas Serrano committed
31
BaseMatrix<float, 2, 3> my_matrix;
Lucas Serrano's avatar
Lucas Serrano committed
32 33 34 35 36 37 38
```

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
39
BaseMatrix<double, 4, 4> my_matrix(data);
Lucas Serrano's avatar
Lucas Serrano committed
40 41
```

42
#### Getting the data back
43

Lucas Serrano's avatar
Lucas Serrano committed
44 45
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
46
```c++
Lucas Serrano's avatar
Lucas Serrano committed
47
std::array<double, 4*4> data = my_matrix.dump_array();
Lucas Serrano's avatar
Lucas Serrano committed
48 49
```

50
#### Printing values
Lucas Serrano's avatar
Lucas Serrano committed
51 52 53 54 55
`BaseMatrix` objects are printable with the `<<` operator:

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

57
#### Simple example
58

Lucas Serrano's avatar
Lucas Serrano committed
59 60 61 62 63
This is a simple example for matrix multiplication.

```c++
#include <iostream>

64
#include "../Fast-Matrix/fast5x5.hpp"
Lucas Serrano's avatar
Lucas Serrano committed
65 66 67 68 69 70 71 72 73 74 75

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
76 77 78
    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
79 80 81 82 83 84 85 86 87

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

88
---
Lucas Serrano's avatar
Lucas Serrano committed
89
## Testing
90

Lucas Serrano's avatar
Lucas Serrano committed
91 92 93 94
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.

95 96 97 98 99 100 101
#### Additional dependencies

 * cmake (>= 3.4)
 * eigen 3.2.10
 * googletest 1.8.0
 * R

102
#### Build within the Docker image
103

104
or what concerns the external dependencies, if you have Docker installed
105
on your machine, you can move the main Fast5x5 directory and type
106
`docker/run.sh`.
107

108 109 110 111 112 113 114 115 116 117
```bash
cd /path/to/Fast5x5/
docker/run.sh
mkdir build && cd build
cmake -D CMAKE_PREFIX_PATH=/opt/boost.simd/build/ ..
make
```

#### Build without Docker

Lucas Serrano's avatar
Lucas Serrano committed
118
```bash
119
cd /path/to/Fast5x5/
Lucas Serrano's avatar
Lucas Serrano committed
120 121
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
122
cmake -D CMAKE_PREFIX_PATH=path/to/boost.simd_build_dir/ ..
Lucas Serrano's avatar
Lucas Serrano committed
123 124
make
```
125 126 127

#### Run

Lucas Serrano's avatar
Lucas Serrano committed
128
Once the tests are built you can launch them from the test directory.
129

Lucas Serrano's avatar
Lucas Serrano committed
130 131 132
```bash
test/unit_tests
```