simply-simd 0.2.0

No-boilerplate portable SIMD library for raw registers with runtime feature detection
Documentation

Crates.io Documentation License Build Status MSRV

No-boilerplate portable SIMD Rust library for raw registers with runtime feature detection.

Usage

Static Dispatch

StaticSimd gives you easy access to simd using the feature set provided by your compiler flags. Using the flag target-cpu=native will ensure you always use the best simd architecutre.

use simply_simd::StaticSimd;

let a = StaticSimd::splat(1.0f32);
let b = StaticSimd::splat(1.5f32);

let c = a + b;

println!("Result: {:?}", c);

Dynamic Dispatch

For dynamic runtime feature detection, dispatch_simd will automatically compile your function for each of the supported targets.

use simply_simd::{Simd, dispatch_simd};

fn main() {
    // Call like normal.
    simd_work();
}

#[dispatch_simd(A)]
fn simd_work() {
    let a = Simd::<f32, A>::splat(1.5);
    let b = Simd::<f32, A>::iota(1.0);

    let c = b.mul_add(b, a);
}

Since the dispatch requires branching at runtime, it is best to do this outside of hot loops.

Rust will not emit SIMD instructions inline if it does not have the associated feature flags. Functions with generic type A: Arch must either inline or use the enable_targets macro. If neither of these are done, Rust may not inline the SIMD instructions and performance will significantly degrade, up to 10x+ times slower.

use simply_simd::{Arch, dispatch_simd, enable_targets};

// Dispatch simd here to avoid repeated dispatching
// in every iteration.
#[dispatch_simd(A)]
pub fn simd_entry() {
    for _ in 0..1024 {
        simd_work_1::<A>();
        simd_work_2::<A>();
        broken_simd_work::<A>();
    }
}

// Avoid using #[dispatch_simd(A)] again here.
// Instead, use #[enable_targets(A)] with <A: Arch>.
#[enable_targets(A)]
pub fn simd_work_1<A: Arch>() {
    // ...
}

// #[inline(always)] can be used as well.
#[inline(always)]
pub fn simd_work_2<A: Arch>() {
    // ...
}

// No inline or enable_targets,
// compiler may not optimize or inline 
// SIMD instructions.
pub fn broken_simd_work<A: Arch>() {
    // ...
}

dispatch_simd and enable_targets can both be used on impl blocks as well. This is necessary when A: Arch is generic across a struct. It will also apply to every function that contains a generic A: Arch (or other identifier you specify). This method must be used for trait implementations:

use simply_simd::{Arch, enable_targets};

trait SimdTask {
    fn simd_work<A: Arch>();
}
struct SimdWorker {}

#[enable_targets(A)]
impl SimdTask for SimdWorker {
    fn simd_work<A: Arch>() {}
}

If #[dispatch_simd(A)] is applied to an associated function using generic parameters from its impl block, the macro will not have enough information to tell it's an associated function and requires an additional flag: #[dispatch_simd(A, associated)]. For the majority of cases, this flag can be omitted.

Unfortunately, these restrictions make it impossible to ensure other functions that you do not own use the dispatched target. This limitation applies to all SIMD libraries.

Variable Lanes

Unlike std::simd, simply-simd does not use a fixed width and instead operates in the largest supported lane count directly.

use simply_simd::StaticSimd;

let array: [f32; 1024] = std::array::from_fn(|i| i as f32);
let mut result = [0.0; 1024];

for i in (0..1024).step_by(StaticSimd::<f32>::LANES) {
    let values = StaticSimd::from_slice(&array[i..]);
    let new_values = values * StaticSimd::splat(100.0);

    new_values.copy_to_slice(result.as_mut_slice());
}

Simd Iters

Iterators are also provided that operate directly on simd registers. They also automatically handle the tail, letting you keep your logic in one place.

use simply_simd::{StaticSimd, SimdSliceIterExt};

let array: [f32; 1024] = std::array::from_fn(|i| i as f32);

let result: [f32; 1024] = array
    .as_slice()
    .simd_iter()
    .map(|x| x * StaticSimd::splat(100.0))
    .collect();

Masks

Masks are also provided using the same structure as Simd.

use simply_simd::{StaticSimd, StaticMask};

let mask = StaticMask::<f32>::first_n_true(3);

let val1 = StaticSimd::iota(1.0);
let val2 = StaticSimd::iota(5.0);

// Blends results of val1 and val2 depending on the mask.
let new_val = mask.select(val1, val2);

Limitations

Simply simd does not offer the full support of a complete SIMD library. It was created primarily for the quick-noise crate and still lacks the polish of a dedicated SIMD library. However, simply-simd can be more than enough for simple simd operations.