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