cfavml 0.2.0

CF's Accelerated Vector Math Library providing SIMD optimzied routines for vector operations
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# CFAVML

> _CF's Accelerated Vector Math Library_

Various accelerated vector operations over Rust primitives with SIMD.

This is the core base library, it has no dependencies and only depends on the `core` library,
it does not perform any allocations.

This library is guaranteed to be no-std compatible and can be adjusted by disabling the `std`
feature flag:

##### Default Setup
```toml
cfavml = "0.2.0" 
```

##### No-std Setup
```toml
cfavml = { version = "0.2.0", default-features = false }
```

### Available SIMD Architectures

- AVX2
- AVX2 + FMA
- AVX512
- NEON
- Fallback (Typically optimized to SSE automatically by LLVM on x86)

### Supported Primitives

- `f32`
- `f64`
- `i8`
- `i16`
- `i32`
- `i64`
- `u8`
- `u16`
- `u32`
- `u64`

##### Note on non-`f32/f64` division

Division operations on non-floating point primitives are currently still scalar
operations, as performing integer division is incredibly hard to do anymore efficiently
with SIMD and adds a significant amount of cognitive overhead when reading the code.

Although to be honest I have some serious questions about your application if you're doing 
heavy integer division...

### Supported Operations & Distances


### Spacial distances

These are routines that can be used for things like KNN classification or index building.

- Dot product of two vectors
- Cosine distance of two vectors
- Squared Euclidean distance of two vectors

### Arithmetic 

- Add single value to vector
- Sub single value from vector
- Mul vector by single value
- Div vector by single value
- Add two vectors vertically
- Sub two vectors vertically
- Mul two vectors vertically
- Div two vectors vertically

### Comparison

- Horizontal max element in a vector
- Horizontal min element in a vector
- Vertical max element of two vectors
- Vertical min element of two vectors
- Vertical max element of a vector and broadcast value
- Vertical min element of a vector and broadcast value

### Aggregation

- Horizontal sum of a vector

### Misc

- Squared L2 norm of a vector

### Dangerous routine naming convention

If you've looked at the `danger` folder at all, you'll notice a few things, one SIMD operations
are gated behind the `SimdRegister<T>` trait, this provides us with a generic abstraction
over the various SIMD register types and architectures.

This trait, combined with the `Math<T>` trait form the core of all operations and are
provided as generic functions (with no target features):

- `generic_dot`
- `generic_squared_euclidean`
- `generic_cosine`
- `generic_squared_norm`
- `generic_max_horizontal`
- `generic_max_vector`
- `generic_min_horizontal`
- `generic_min_vector`
- `generic_sum`
- `generic_add_value`
- `generic_sub_value`
- `generic_mul_value`
- `generic_div_value`
- `generic_add_vector`
- `generic_sub_vector`
- `generic_mul_vector`
- `generic_div_vector`

We also export functions with the target_features pre-specified for
each SIMD register type and is found under the `cfavml::danger::export_*` 
modules. Although it is not recommended to use these routines directly
unless you know what you are doing.

### Features

- `nightly` Enables optimizations available only on nightly platforms.
  * This is required for AVX512 support due to it currently being unstable.

### Is this a replacement for BLAS?

No. At least, not unless you're only doing dot product... BLAS and LAPACK are _huge_ and I am certainly
not in the market for implementing all BLAS routines in Rust, but that being said if your application is 
similar to that of ndarray where it is only using BLAS for the dot product, then maybe.