Add a docstring for VecUnroll

[timholy]

Closes #71

[timholy]

Please feel free to edit at will!

[codecov]

Codecov Report

Merging #72 (9db58d7) into master (bbff9c2) will decrease coverage by 0.03%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master      #72      +/-   ##
==========================================
- Coverage   56.33%   56.30%   -0.04%     
==========================================
  Files          33       33              
  Lines        5742     5742              
==========================================
- Hits         3235     3233       -2     
- Misses       2507     2509       +2     

Impacted Files	Coverage Δ
src/VectorizationBase.jl	67.74% <ø> (ø)
src/llvm_intrin/vector_ops.jl	72.33% <0.00%> (-0.34%)	⬇️
src/vecunroll/memory.jl	48.64% <0.00%> (-0.11%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update bbff9c2...9db58d7. Read the comment docs.

[chriselrod]

The other advantage is that it allows interleaving instructions, which can take better advantage of a CPU's OOO:

julia> using VectorizationBase, SLEEFPirates

julia> vx = Vec(ntuple(_ -> randn(), pick_vector_width(Float64))...)
Vec{8, Float64}<-0.41777997881994483, -0.2778225158869686, 1.0569948436617753, 0.5176464757147176, 0.2323833794303069, -0.7993648787803678, -0.9685718051710357, 0.12727761225970358>

julia> vxu = VecUnroll((vx,vx,vx,vx));

julia> @btime exp2($(Ref(vx))[])
  4.348 ns (0 allocations: 0 bytes)
Vec{8, Float64}<0.7485756477631421, 0.8248350157271293, 2.0805930967801856, 1.431617888324136, 1.174774112297017, 0.5746020803268009, 0.5110116881622035, 1.0922306992794324>

julia> @btime exp2($(Ref(vxu))[])
  9.461 ns (0 allocations: 0 bytes)
4 x Vec{8, Float64}
Vec{8, Float64}<0.7485756477631421, 0.8248350157271293, 2.0805930967801856, 1.431617888324136, 1.174774112297017, 0.5746020803268009, 0.5110116881622035, 1.0922306992794324>
Vec{8, Float64}<0.7485756477631421, 0.8248350157271293, 2.0805930967801856, 1.431617888324136, 1.174774112297017, 0.5746020803268009, 0.5110116881622035, 1.0922306992794324>
Vec{8, Float64}<0.7485756477631421, 0.8248350157271293, 2.0805930967801856, 1.431617888324136, 1.174774112297017, 0.5746020803268009, 0.5110116881622035, 1.0922306992794324>
Vec{8, Float64}<0.7485756477631421, 0.8248350157271293, 2.0805930967801856, 1.431617888324136, 1.174774112297017, 0.5746020803268009, 0.5110116881622035, 1.0922306992794324>

julia> @btime sin($(Ref(vx))[])
  8.536 ns (0 allocations: 0 bytes)
Vec{8, Float64}<-0.40573237311580634, -0.2742623121079716, 0.8708824084181056, 0.49483633008673605, 0.2302974902834125, -0.7169134530311316, -0.8240775144694545, 0.1269342496262836>

julia> @btime sin($(Ref(vxu))[])
  21.154 ns (0 allocations: 0 bytes)
4 x Vec{8, Float64}
Vec{8, Float64}<-0.40573237311580634, -0.2742623121079716, 0.8708824084181056, 0.49483633008673605, 0.2302974902834125, -0.7169134530311316, -0.8240775144694545, 0.1269342496262836>
Vec{8, Float64}<-0.40573237311580634, -0.2742623121079716, 0.8708824084181056, 0.49483633008673605, 0.2302974902834125, -0.7169134530311316, -0.8240775144694545, 0.1269342496262836>
Vec{8, Float64}<-0.40573237311580634, -0.2742623121079716, 0.8708824084181056, 0.49483633008673605, 0.2302974902834125, -0.7169134530311316, -0.8240775144694545, 0.1269342496262836>
Vec{8, Float64}<-0.40573237311580634, -0.2742623121079716, 0.8708824084181056, 0.49483633008673605, 0.2302974902834125, -0.7169134530311316, -0.8240775144694545, 0.1269342496262836>

In these example, 4x the work takes less than 2.5x the time.

[timholy]

Do you want me to change the docstring in some way? I do use the word interleave but don't talk about the performance optimizations (which, as always, are cool). I could basically paste your demo, but I worry about making it quite long. This version emphasizes defining it without going into extensive detail about using it. The balance may not be quite right, though.

[chriselrod]

The test that failed is bwap on random floating point values, which is likely to (correctly) produce NaNs, so I've updated the test on master to use isequal instead of ==.
So I went ahead and merged, thanks!

Do you want me to change the docstring in some way? I do use the word interleave but don't talk about the performance optimizations (which, as always, are cool). I could basically paste your demo, but I worry about making it quite long.

I agree, that'd be long.
It already mentions some optimizations, so users may assume that it can help in other contexts.

This version emphasizes defining it without going into extensive detail about using it. The balance may not be quite right, though.

It should be usable wherever other AbstractSIMDs are, so ideally not much explanation is needed and focusing on construction is the way to go.