aprender-compute 0.32.0

High-performance SIMD compute library with GPU support, LLM inference engine, and GGUF model loading (was: trueno)
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

# Vector Math

This chapter demonstrates Trueno's vector math capabilities using the `quickstart` and `performance_demo` examples.

## Quick Start

Run the quickstart example to see all core vector operations:

```bash
cargo run --example quickstart
```

### Basic Operations

```rust
use trueno::Vector;

// Create vectors
let a = Vector::from_slice(&[1.0, 2.0, 3.0, 4.0]);
let b = Vector::from_slice(&[5.0, 6.0, 7.0, 8.0]);

// Element-wise operations
let sum = a.add(&b)?;      // [6.0, 8.0, 10.0, 12.0]
let prod = a.mul(&b)?;     // [5.0, 12.0, 21.0, 32.0]

// Reductions
let dot = a.dot(&b)?;      // 70.0
let norm = a.norm_l2()?;   // 5.477...

// Statistical operations
let mean = a.mean()?;      // 2.5
let variance = a.variance()?;
```

### Backend Selection

Trueno automatically selects the best available backend:

```rust
use trueno::{Vector, Backend};

// Auto backend (recommended)
let v = Vector::from_slice(&data);

// Force specific backend
let scalar = Vector::from_slice_with_backend(&data, Backend::Scalar);
```

## Performance Comparison

Run the performance demo to see SIMD speedups:

```bash
cargo run --release --example performance_demo
```

### Expected Results

| Operation | SIMD Speedup | Notes |
|-----------|-------------|-------|
| Dot Product | 3-4x | Compute-intensive |
| Sum Reduction | 3x | Compute-intensive |
| Max Finding | 3x | Compute-intensive |
| Element-wise Add | 1.5x | Memory-bound |
| Element-wise Mul | 1.5x | Memory-bound |

### Understanding the Results

**Compute-intensive operations** (dot product, sum, max) show significant speedups because SIMD can process 8 f32 values simultaneously.

**Memory-bound operations** (add, mul) show modest speedups because performance is limited by memory bandwidth, not computation.

## ML Similarity Operations

Run the similarity example:

```bash
cargo run --example ml_similarity
```

### Cosine Similarity

```rust
use trueno::Vector;

let query = Vector::from_slice(&[0.5, 0.8, 0.2]);
let document = Vector::from_slice(&[0.6, 0.7, 0.3]);

// Compute cosine similarity
let norm_q = query.norm_l2()?;
let norm_d = document.norm_l2()?;
let dot = query.dot(&document)?;
let similarity = dot / (norm_q * norm_d);
```

### k-NN Classification

```rust
// Compute Euclidean distances
let diff = query.sub(&sample)?;
let dist_sq = diff.dot(&diff)?;
let distance = dist_sq.sqrt();
```

## Layer Normalization

```rust
use trueno::Vector;

let input = Vector::from_slice(&[1.0, 2.0, 3.0, 4.0, 5.0]);

// Compute mean and variance
let mean = input.mean()?;
let centered = input.sub_scalar(mean)?;
let var = centered.dot(&centered)? / input.len() as f32;
let std = (var + 1e-5).sqrt();

// Normalize
let normalized = centered.mul_scalar(1.0 / std)?;
```

## See Also

- [Performance Demo](../performance/benchmarks.md) - Detailed benchmarks
- [ML Similarity](./neural-networks.md) - ML-specific operations
- [Backend Selection](../architecture/backend-selection.md) - How backends are chosen