A comprehensive, progressive learning journey through AVX2 SIMD programming using the Odin programming language on Linux x86_64.

This repository contains 41 hands-on examples (00-40) that teach you AVX2 SIMD programming from the ground up. Each example includes:

• Scalar implementation - Traditional single-element processing
• SIMD implementation - Parallel processing using AVX2 (256-bit vectors)
• Correctness verification - Both implementations produce identical results
• Performance benchmarking - Measured speedup from SIMD
• Extensive comments - Explanations of concepts, instructions, and patterns

• CPU: x86_64 processor with AVX2 support (Intel Haswell or later, AMD Excavator or later)
• OS: Linux
• Compiler: Odin programming language

make check-avx2

Or manually:

grep avx2 /proc/cpuinfo

# Build all examples
make all

# Run a specific example
./bin/00_load_store

# Run all examples
make run-all

# Clean build artifacts
make clean

#simd[8]i32   // 8 × 32-bit integers (256 bits)
#simd[8]f32   // 8 × 32-bit floats (256 bits)
#simd[4]i64   // 4 × 64-bit integers (256 bits)
#simd[4]f64   // 4 × 64-bit doubles (256 bits)
#simd[16]i16  // 16 × 16-bit integers (256 bits)
#simd[32]i8   // 32 × 8-bit integers (256 bits)

import "core:simd"
import "base:intrinsics"

// Loading (unaligned for safety)
vec := intrinsics.unaligned_load(cast(^#simd[8]f32)&array[i])

// Storing
intrinsics.unaligned_store(cast(^#simd[8]f32)&array[i], vec)

// Arithmetic
result := vec_a + vec_b  // Addition
result := vec_a - vec_b  // Subtraction
result := vec_a * vec_b  // Multiplication
result := vec_a / vec_b  // Division (floats)

// Broadcasting a scalar
scale: #simd[8]f32 = 2.5  // All 8 lanes = 2.5

// Fused Multiply-Add (a*b + c in one instruction)
result := simd.fused_mul_add(a, b, c)

// Comparisons (returns mask)
mask := simd.lanes_gt(a, b)  // Greater than
mask := simd.lanes_eq(a, b)  // Equal

// Conditional selection
result := simd.select(mask, true_val, false_val)

// Min/Max/Clamp
result := simd.min(a, b)
result := simd.max(a, b)
result := simd.clamp(val, low, high)

// Convert to/from array
arr := simd.to_array(vec)
vec := simd.from_array(arr)

1. Process in chunks of 8:

i := 0
for ; i + 8 <= n; i += 8 {
    vec := intrinsics.unaligned_load(cast(^#simd[8]f32)&data[i])
    // ... process ...
    intrinsics.unaligned_store(cast(^#simd[8]f32)&result[i], vec)
}
// Handle remainder
for ; i < n; i += 1 {
    result[i] = process_scalar(data[i])
}

2. Reduction (sum all elements):

accum: #simd[8]f32 = 0
for ; i + 8 <= n; i += 8 {
    vec := intrinsics.unaligned_load(cast(^#simd[8]f32)&data[i])
    accum = accum + vec
}
arr := simd.to_array(accum)
total := arr[0] + arr[1] + arr[2] + arr[3] + arr[4] + arr[5] + arr[6] + arr[7]

3. Conditional processing:

mask := simd.lanes_gt(vec, threshold)
result := simd.select(mask, clamped_val, vec)

1. Use FMA - simd.fused_mul_add() is faster AND more accurate than separate multiply+add
2. Minimize horizontal operations - Do vertical (lane-wise) ops in loops, horizontal sum only at end
3. Use multiple accumulators - Hides instruction latency, exploits ILP
4. Prefer multiplication over division - Multiply by reciprocal when possible
5. Avoid branches - Use simd.select() with masks instead
6. Watch alignment - Use intrinsics.unaligned_load/store for safety

All examples tested with -microarch:native -o:speed on x86_64 Linux.

Why ~1.0x for simple operations? The Odin compiler with -o:speed uses LLVM's auto-vectorizer, which is excellent at vectorizing simple loops (add, subtract, multiply, min/max). The explicit SIMD code performs the same operations, resulting in similar performance.

Where SIMD really shines (>2x):

• Reductions (20, 21, 23): Accumulating results with multiple accumulators
• Stencil/convolution (28, 33): Sliding window operations
• Complex conditionals (35): Mandelbrot with per-lane iteration counts
• Data rearrangement (16): Shuffle/permute operations
• Division-heavy (07): Division throughput is limited

Known limitations (<1x):

• Pack/unpack (18): Converting between types has overhead
• Gather (19): AVX2 gather issues multiple memory requests
• u8 image ops (30, 31): u8↔f32 conversion dominates computation
• Histogram (39): Read-modify-write conflicts prevent parallelization

1. Start with 00-09 to understand basic SIMD types and arithmetic
2. Progress to 10-19 for data manipulation and control flow
3. Study 20-29 for algorithm patterns and optimizations
4. Apply knowledge with 30-40 real-world examples

Each example builds on previous concepts, so working through them in order is recommended.

======================================================================
AVX2 SIMD Example 00: Loading and Storing Vectors
======================================================================

Array size: 10007 elements (40028 bytes)

Running scalar version...
Running SIMD version...

Verifying results...
✓ PASSED: Both versions produce identical results!

Benchmarking (1000 iterations each)...

Scalar time: 881.467µs
SIMD time:   625.234µs

Speedup: 1.41x faster with SIMD!

Throughout these examples, you'll encounter these AVX2 instructions:

• Odin Language
• Intel Intrinsics Guide
• Agner Fog's Optimization Manuals

These examples are provided has MIT license and are in here for educational purposes.

Happy SIMD programming!