readme.md
1# `Simd<[T; N]>`
2
3## Implementation of [Rust RFC #2366: `std::simd`][rfc2366]
4
5[![Travis-CI Status]][travis] [![Appveyor Status]][appveyor] [![Latest Version]][crates.io] [![docs]][master_docs]
6
7> This aims to be a 100% conforming implementation of Rust RFC 2366 for stabilization.
8
9**WARNING**: this crate only supports the most recent nightly Rust toolchain.
10
11## Documentation
12
13* [API docs (`master` branch)][master_docs]
14* [Performance guide][perf_guide]
15* [API docs (`docs.rs`)][docs.rs]: **CURRENTLY DOWN** due to
16 https://github.com/rust-lang-nursery/packed_simd/issues/110
17* [RFC2366 `std::simd`][rfc2366]: - contains motivation, design rationale,
18 discussion, etc.
19
20## Examples
21
22Most of the examples come with both a scalar and a vectorized implementation.
23
24* [`aobench`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/aobench)
25* [`fannkuch_redux`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/fannkuch_redux)
26* [`matrix inverse`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/matrix_inverse)
27* [`mandelbrot`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/mandelbrot)
28* [`n-body`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/nbody)
29* [`options_pricing`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/options_pricing)
30* [`spectral_norm`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/spectral_norm)
31* [`triangle transform`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/triangle_xform)
32* [`stencil`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/stencil)
33* [`vector dot product`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/dot_product)
34
35## Cargo features
36
37* `into_bits` (default: disabled): enables `FromBits`/`IntoBits` trait
38 implementations for the vector types. These allow reinterpreting the bits of a
39 vector type as those of another vector type safely by just using the
40 `.into_bits()` method.
41
42* `core_arch` (default: disabled): enable this feature to recompile `core::arch`
43 for the target-features enabled. `packed_simd` includes optimizations for some
44 target feature combinations that are enabled by this feature. Note, however,
45 that this is an unstable dependency, that rustc might break at any time.
46
47* `sleef-sys` (default: disabled - `x86_64` only): internally uses the [SLEEF]
48 short-vector math library when profitable via the [`sleef-sys`][sleef_sys]
49 crate. [SLEEF] is licensed under the [Boost Software License
50 v1.0][boost_license], an extremely permissive license, and can be statically
51 linked without issues.
52
53## Performance
54
55The following [ISPC] examples are also part of `packed_simd`'s
56[`examples/`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/)
57directory, where `packed_simd`+[`rayon`][rayon] are used to emulate [ISPC]'s
58Single-Program-Multiple-Data (SPMD) programming model. The performance results
59on different hardware is shown in the `readme.md` of each example. The following
60table summarizes the performance ranges, where `+` means speed-up and `-`
61slowdown:
62
63* `aobench`: `[-1.02x, +1.53x]`,
64* `stencil`: `[+1.06x, +1.72x]`,
65* `mandelbrot`: `[-1.74x, +1.2x]`,
66* `options_pricing`:
67 * `black_scholes`: `+1.0x`
68 * `binomial_put`: `+1.4x`
69
70 While SPMD is not the intended use case for `packed_simd`, it is possible to
71 combine the library with [`rayon`][rayon] to poorly emulate [ISPC]'s SPMD programming
72 model in Rust. Writing performant code is not as straightforward as with
73 [ISPC], but with some care (e.g. see the [Performance Guide][perf_guide]) one
74 can easily match and often out-perform [ISPC]'s "default performance".
75
76## Platform support
77
78The following table describes the supported platforms: `build` shows whether the
79library compiles without issues for a given target, while `run` shows whether
80the full testsuite passes on the target.
81
82| Linux targets: | build | run |
83|-----------------------------------|-----------|---------|
84| `i586-unknown-linux-gnu` | ✓ | ✓ |
85| `i686-unknown-linux-gnu` | ✓ | ✓ |
86| `x86_64-unknown-linux-gnu` | ✓ | ✓ |
87| `arm-unknown-linux-gnueabi` | ✗ | ✗ |
88| `arm-unknown-linux-gnueabihf` | ✓ | ✓ |
89| `armv7-unknown-linux-gnueabi` | ✓ | ✓ |
90| `aarch64-unknown-linux-gnu` | ✓ | ✓ |
91| `mips-unknown-linux-gnu` | ✓ | ✓ |
92| `mipsel-unknown-linux-musl` | ✓ | ✓ |
93| `mips64-unknown-linux-gnuabi64` | ✓ | ✓ |
94| `mips64el-unknown-linux-gnuabi64` | ✓ | ✓ |
95| `powerpc-unknown-linux-gnu` | ✗ | ✗ |
96| `powerpc64-unknown-linux-gnu` | ✗ | ✗ |
97| `powerpc64le-unknown-linux-gnu` | ✗ | ✗ |
98| `s390x-unknown-linux-gnu` | ✓ | ✓* |
99| `sparc64-unknown-linux-gnu` | ✓ | ✓* |
100| `thumbv7neon-unknown-linux-gnueabihf` | ✓ | ✓ |
101| **MacOSX targets:** | **build** | **run** |
102| `x86_64-apple-darwin` | ✓ | ✓ |
103| `i686-apple-darwin` | ✓ | ✓ |
104| **Windows targets:** | **build** | **run** |
105| `x86_64-pc-windows-msvc` | ✓ | ✓ |
106| `i686-pc-windows-msvc` | ✓ | ✓ |
107| `x86_64-pc-windows-gnu` | ✗ | ✗ |
108| `i686-pc-windows-gnu` | ✗ | ✗ |
109| **WebAssembly targets:** | **build** | **run** |
110| `wasm32-unknown-unknown` | ✓ | ✓ |
111| **Android targets:** | **build** | **run** |
112| `x86_64-linux-android` | ✓ | ✓ |
113| `arm-linux-androideabi` | ✓ | ✓ |
114| `aarch64-linux-android` | ✓ | ✗ |
115| `thumbv7neon-linux-androideabi` | ✓ | ✓ |
116| **iOS targets:** | **build** | **run** |
117| `i386-apple-ios` | ✓ | ✗ |
118| `x86_64-apple-ios` | ✓ | ✗ |
119| `armv7-apple-ios` | ✓ | ✗** |
120| `aarch64-apple-ios` | ✓ | ✗** |
121| **xBSD targets:** | **build** | **run** |
122| `i686-unknown-freebsd` | ✗ | ✗** |
123| `x86_64-unknown-freebsd` | ✗ | ✗** |
124| `x86_64-unknown-netbsd` | ✗ | ✗** |
125| **Solaris targets:** | **build** | **run** |
126| `x86_64-sun-solaris` | ✗ | ✗** |
127
128[*] most of the test suite passes correctly on these platform but
129there are correctness bugs open in the issue tracker.
130
131[**] it is currently not easily possible to run these platforms on CI.
132
133## Machine code verification
134
135The
136[`verify/`](https://github.com/rust-lang-nursery/packed_simd/tree/master/verify)
137crate tests disassembles the portable packed vector APIs at run-time and
138compares the generated machine code against the desired one to make sure that
139this crate remains efficient.
140
141## License
142
143This project is licensed under either of
144
145* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
146 ([LICENSE-APACHE](LICENSE-APACHE))
147
148* [MIT License](http://opensource.org/licenses/MIT)
149 ([LICENSE-MIT](LICENSE-MIT))
150
151at your option.
152
153## Contributing
154
155We welcome all people who want to contribute.
156Please see the [contributing instructions] for more information.
157
158Contributions in any form (issues, pull requests, etc.) to this project
159must adhere to Rust's [Code of Conduct].
160
161Unless you explicitly state otherwise, any contribution intentionally submitted
162for inclusion in `packed_simd` by you, as defined in the Apache-2.0 license, shall be
163dual licensed as above, without any additional terms or conditions.
164
165[travis]: https://travis-ci.org/rust-lang-nursery/packed_simd
166[Travis-CI Status]: https://travis-ci.org/rust-lang-nursery/packed_simd.svg?branch=master
167[appveyor]: https://ci.appveyor.com/project/gnzlbg/packed-simd
168[Appveyor Status]: https://ci.appveyor.com/api/projects/status/hd7v9dvr442hgdix?svg=true
169[Latest Version]: https://img.shields.io/crates/v/packed_simd.svg
170[crates.io]: https://crates.io/crates/packed_simd
171[docs]: https://docs.rs/packed_simd/badge.svg
172[docs.rs]: https://docs.rs/packed_simd/
173[master_docs]: https://rust-lang-nursery.github.io/packed_simd/packed_simd/
174[perf_guide]: https://rust-lang-nursery.github.io/packed_simd/perf-guide/
175[rfc2366]: https://github.com/rust-lang/rfcs/pull/2366
176[ISPC]: https://ispc.github.io/
177[rayon]: https://crates.io/crates/rayon
178[boost_license]: https://www.boost.org/LICENSE_1_0.txt
179[SLEEF]: https://sleef.org/
180[sleef_sys]: https://crates.io/crates/sleef-sys
181[contributing instructions]: contributing.md
182[Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html
183
