Writing a guide to SIMD

We are going to want to produce a guide on SIMD in Rust that doesn't just cover the API but also covers a standard vocabulary about this, so as to hopefully standardize on a vendor-ambivalent vocabulary. We are also going to want to link to vendors, of course, but we want a way to discuss our own portable types that meshes reasonably well with Rust.

It's important to meet people where they are at here. I believe that people mostly either:

1. know much of what there is to say about SIMD but may mostly have experience with particular vendor intrinsics or even a more abstract model like GPGPU... for them, we want an option to basically read the "front and back pages" because they may be used to certain terms that are not reflected in our API
2. have an idea of what SIMD is but mostly as an awareness of e.g. autovectorization, they may know some basics but don't have experience with things like (GP)GPU or intrinsic function programming
3. have no idea whatsoever, and may not even know why they might care!

• Standard vocabulary will likely include these terms or alternates to them:

  • SIMD
  • vector
  • vector register
  • scalar (by contrast)
  • vectorize / autovectorization
  • "lane"?
  • "field"?
  • "element"?
  • "intrinsics"?

• We will likely need to also cover subtle differences (or the absence thereof)

  • intrinsics vs. instructions
  • instructions vs. operations
  • lane vs. field vs. element
  • scalar vs. vector

• Differences between CPU SIMD and GPU SIMT

• Differences between SIMD vectors and SPMD threads

• Differences between "wide vectors" (x86 SSE/AVX/AVX512, Arm Neon, etc.) and "vector architectures" (Cray, RISCV-V, Arm SVE)

• How to get the most out of Rust SIMD code

  • feature levels, including is_x86_feature_detected!
  • #[target_feature]
  • #[cfg(target_feature)]
  • how to do "multiversioning"
  • multiversioning, why or why not?
  • when do you use std::arch instead?

And we might want to talk briefly about (abstract) tensors vs. (SIMD) vectors due to matrix multiplication being related to this.

No documentation file or entry point is named. Start by reviewing the checklist in the issue, then organize the guide around SIMD vocabulary, CPU/GPU distinctions, Rust feature selection, and multiversioning; done means the listed concepts are covered with vendor links and terminology that fits Rust's portable types.