[rustc.git] / vendor / packed_simd / readme.md

# `Simd<[T; N]>`

## Implementation of [Rust RFC #2366: `std::simd`][rfc2366]

[![Travis-CI Status]][travis] [![Appveyor Status]][appveyor] [![Latest Version]][crates.io] [![docs]][master_docs]

> This aims to be a 100% conforming implementation of Rust RFC 2366 for stabilization.

**WARNING**: this crate only supports the most recent nightly Rust toolchain.

## Documentation

* [API docs (`master` branch)][master_docs]
* [Performance guide][perf_guide]
* [API docs (`docs.rs`)][docs.rs]: **CURRENTLY DOWN** due to
  https://github.com/rust-lang-nursery/packed_simd/issues/110
* [RFC2366 `std::simd`][rfc2366]: - contains motivation, design rationale,
  discussion, etc.

## Examples

Most of the examples come with both a scalar and a vectorized implementation.

* [`aobench`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/aobench)
* [`fannkuch_redux`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/fannkuch_redux)
* [`matrix inverse`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/matrix_inverse)
* [`mandelbrot`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/mandelbrot)
* [`n-body`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/nbody)
* [`options_pricing`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/options_pricing)
* [`spectral_norm`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/spectral_norm)
* [`triangle transform`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/triangle_xform)
* [`stencil`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/stencil)
* [`vector dot product`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/dot_product)

## Cargo features

* `into_bits` (default: disabled): enables `FromBits`/`IntoBits` trait
  implementations for the vector types. These allow reinterpreting the bits of a
  vector type as those of another vector type safely by just using the
  `.into_bits()` method.

* `core_arch` (default: disabled): enable this feature to recompile `core::arch`
  for the target-features enabled. `packed_simd` includes optimizations for some
  target feature combinations that are enabled by this feature. Note, however,
  that this is an unstable dependency, that rustc might break at any time.

* `sleef-sys` (default: disabled - `x86_64` only): internally uses the [SLEEF]
  short-vector math library when profitable via the [`sleef-sys`][sleef_sys]
  crate. [SLEEF] is licensed under the [Boost Software License
  v1.0][boost_license], an extremely permissive license, and can be statically
  linked without issues.

## Performance

The following [ISPC] examples are also part of `packed_simd`'s
[`examples/`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/)
directory, where `packed_simd`+[`rayon`][rayon] are used to emulate [ISPC]'s
Single-Program-Multiple-Data (SPMD) programming model. The performance results
on different hardware is shown in the `readme.md` of each example. The following
table summarizes the performance ranges, where `+` means speed-up and `-`
slowdown:

* `aobench`: `[-1.02x, +1.53x]`,
* `stencil`: `[+1.06x, +1.72x]`,
* `mandelbrot`: `[-1.74x, +1.2x]`,
* `options_pricing`:
   * `black_scholes`: `+1.0x`
   * `binomial_put`: `+1.4x`

 While SPMD is not the intended use case for `packed_simd`, it is possible to
 combine the library with [`rayon`][rayon] to poorly emulate [ISPC]'s SPMD programming
 model in Rust. Writing performant code is not as straightforward as with
 [ISPC], but with some care (e.g. see the [Performance Guide][perf_guide]) one
 can easily match and often out-perform [ISPC]'s "default performance".

## Platform support

The following table describes the supported platforms: `build` shows whether the
library compiles without issues for a given target, while `run` shows whether
the full testsuite passes on the target.

| Linux targets:                    | build     | run     |
|-----------------------------------|-----------|---------|
| `i586-unknown-linux-gnu`          | ✓         | ✓       |
| `i686-unknown-linux-gnu`          | ✓         | ✓       |
| `x86_64-unknown-linux-gnu`        | ✓         | ✓       |
| `arm-unknown-linux-gnueabi`       | ✗         | ✗       |
| `arm-unknown-linux-gnueabihf`     | ✓         | ✓       |
| `armv7-unknown-linux-gnueabi`     | ✓         | ✓       |
| `aarch64-unknown-linux-gnu`       | ✓         | ✓       |
| `mips-unknown-linux-gnu`          | ✓         | ✓       |
| `mipsel-unknown-linux-musl`       | ✓         | ✓       |
| `mips64-unknown-linux-gnuabi64`   | ✓         | ✓       |
| `mips64el-unknown-linux-gnuabi64` | ✓         | ✓       |
| `powerpc-unknown-linux-gnu`       | ✗         | ✗       |
| `powerpc64-unknown-linux-gnu`     | ✗         | ✗       |
| `powerpc64le-unknown-linux-gnu`   | ✗         | ✗       |
| `s390x-unknown-linux-gnu`         | ✓         | ✓*      |
| `sparc64-unknown-linux-gnu`       | ✓         | ✓*      |
| **MacOSX targets:**               | **build** | **run** |
| `x86_64-apple-darwin`             | ✓         | ✓       |
| `i686-apple-darwin`               | ✓         | ✓       |
| **Windows targets:**              | **build** | **run** |
| `x86_64-pc-windows-msvc`          | ✓         | ✓       |
| `i686-pc-windows-msvc`            | ✓         | ✓       |
| `x86_64-pc-windows-gnu`           | ✗          | ✗        |
| `i686-pc-windows-gnu`             | ✗          | ✗        |
| **WebAssembly targets:**          | **build** | **run** |
| `wasm32-unknown-unknown`          | ✓         | ✓      |
| **Android targets:**              | **build** | **run** |
| `x86_64-linux-android`            | ✓         | ✓       |
| `arm-linux-androideabi`           | ✓         | ✓       |
| `aarch64-linux-android`           | ✓         | ✗       |
| **iOS targets:**                  | **build** | **run** |
| `i386-apple-ios`                  | ✓         | ✗       |
| `x86_64-apple-ios`                | ✓         | ✗       |
| `armv7-apple-ios`                 | ✓         | ✗**     |
| `aarch64-apple-ios`               | ✓         | ✗**     |
| **xBSD targets:**                 | **build** | **run** |
| `i686-unknown-freebsd`            | ✗         | ✗**     |
| `x86_64-unknown-freebsd`          | ✗         | ✗**     |
| `x86_64-unknown-netbsd`           | ✗         | ✗**     |
| **Solaris targets:**              | **build** | **run** |
| `x86_64-sun-solaris`              | ✗         | ✗**     |

[*] most of the test suite passes correctly on these platform but
there are correctness bugs open in the issue tracker.

[**] it is currently not easily possible to run these platforms on CI.

## Machine code verification

The
[`verify/`](https://github.com/rust-lang-nursery/packed_simd/tree/master/verify)
crate tests disassembles the portable packed vector APIs at run-time and
compares the generated machine code against the desired one to make sure that
this crate remains efficient.

## License

This project is licensed under either of

* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
  ([LICENSE-APACHE](LICENSE-APACHE))

* [MIT License](http://opensource.org/licenses/MIT)
  ([LICENSE-MIT](LICENSE-MIT))

at your option.

## Contributing

We welcome all people who want to contribute.
Please see the [contributing instructions] for more information.

Contributions in any form (issues, pull requests, etc.) to this project
must adhere to Rust's [Code of Conduct].

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in `packed_simd` by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

[travis]: https://travis-ci.org/rust-lang-nursery/packed_simd
[Travis-CI Status]: https://travis-ci.org/rust-lang-nursery/packed_simd.svg?branch=master
[appveyor]: https://ci.appveyor.com/project/gnzlbg/packed-simd
[Appveyor Status]: https://ci.appveyor.com/api/projects/status/hd7v9dvr442hgdix?svg=true
[Latest Version]: https://img.shields.io/crates/v/packed_simd.svg
[crates.io]: https://crates.io/crates/packed_simd
[docs]: https://docs.rs/packed_simd/badge.svg
[docs.rs]: https://docs.rs/packed_simd/
[master_docs]: https://rust-lang-nursery.github.io/packed_simd/packed_simd/
[perf_guide]: https://rust-lang-nursery.github.io/packed_simd/perf-guide/
[rfc2366]: https://github.com/rust-lang/rfcs/pull/2366
[ISPC]: https://ispc.github.io/
[rayon]: https://crates.io/crates/rayon
[boost_license]: https://www.boost.org/LICENSE_1_0.txt
[SLEEF]: https://sleef.org/
[sleef_sys]: https://crates.io/crates/sleef-sys
[contributing instructions]: contributing.md
[Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html
Commit	Line	Data
f20569fa XL	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
	22	Most 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
	55	The following [ISPC] examples are also part of `packed_simd`'s
	56	[`examples/`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/)
	57	directory, where `packed_simd`+[`rayon`][rayon] are used to emulate [ISPC]'s
	58	Single-Program-Multiple-Data (SPMD) programming model. The performance results
	59	on different hardware is shown in the `readme.md` of each example. The following
	60	table summarizes the performance ranges, where `+` means speed-up and `-`
	61	slowdown:
	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
78	The following table describes the supported platforms: `build` shows whether the
79	library compiles without issues for a given target, while `run` shows whether
80	the 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	\| MacOSX targets: \| build \| run \|
101	\| `x86_64-apple-darwin` \| ✓ \| ✓ \|
102	\| `i686-apple-darwin` \| ✓ \| ✓ \|
103	\| Windows targets: \| build \| run \|
104	\| `x86_64-pc-windows-msvc` \| ✓ \| ✓ \|
105	\| `i686-pc-windows-msvc` \| ✓ \| ✓ \|
106	\| `x86_64-pc-windows-gnu` \| ✗ \| ✗ \|
107	\| `i686-pc-windows-gnu` \| ✗ \| ✗ \|
108	\| WebAssembly targets: \| build \| run \|
109	\| `wasm32-unknown-unknown` \| ✓ \| ✓ \|
110	\| Android targets: \| build \| run \|
111	\| `x86_64-linux-android` \| ✓ \| ✓ \|
112	\| `arm-linux-androideabi` \| ✓ \| ✓ \|
113	\| `aarch64-linux-android` \| ✓ \| ✗ \|
114	\| iOS targets: \| build \| run \|
115	\| `i386-apple-ios` \| ✓ \| ✗ \|
116	\| `x86_64-apple-ios` \| ✓ \| ✗ \|
117	\| `armv7-apple-ios` \| ✓ \| ✗** \|
118	\| `aarch64-apple-ios` \| ✓ \| ✗** \|
119	\| xBSD targets: \| build \| run \|
120	\| `i686-unknown-freebsd` \| ✗ \| ✗** \|
121	\| `x86_64-unknown-freebsd` \| ✗ \| ✗** \|
122	\| `x86_64-unknown-netbsd` \| ✗ \| ✗** \|
123	\| Solaris targets: \| build \| run \|
124	\| `x86_64-sun-solaris` \| ✗ \| ✗** \|
125
126	[*] most of the test suite passes correctly on these platform but
127	there are correctness bugs open in the issue tracker.
128
129	[**] it is currently not easily possible to run these platforms on CI.
130
131	## Machine code verification
132
133	The
134	[`verify/`](https://github.com/rust-lang-nursery/packed_simd/tree/master/verify)
135	crate tests disassembles the portable packed vector APIs at run-time and
136	compares the generated machine code against the desired one to make sure that
137	this crate remains efficient.
138
139	## License
140
141	This project is licensed under either of
142
143	* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
144	([LICENSE-APACHE](LICENSE-APACHE))
145
146	* [MIT License](http://opensource.org/licenses/MIT)
147	([LICENSE-MIT](LICENSE-MIT))
148
149	at your option.
150
151	## Contributing
152
153	We welcome all people who want to contribute.
154	Please see the [contributing instructions] for more information.
155
156	Contributions in any form (issues, pull requests, etc.) to this project
157	must adhere to Rust's [Code of Conduct].
158
159	Unless you explicitly state otherwise, any contribution intentionally submitted
160	for inclusion in `packed_simd` by you, as defined in the Apache-2.0 license, shall be
161	dual licensed as above, without any additional terms or conditions.
162
163	[travis]: https://travis-ci.org/rust-lang-nursery/packed_simd
164	[Travis-CI Status]: https://travis-ci.org/rust-lang-nursery/packed_simd.svg?branch=master
165	[appveyor]: https://ci.appveyor.com/project/gnzlbg/packed-simd
166	[Appveyor Status]: https://ci.appveyor.com/api/projects/status/hd7v9dvr442hgdix?svg=true
167	[Latest Version]: https://img.shields.io/crates/v/packed_simd.svg
168	[crates.io]: https://crates.io/crates/packed_simd
169	[docs]: https://docs.rs/packed_simd/badge.svg
170	[docs.rs]: https://docs.rs/packed_simd/
171	[master_docs]: https://rust-lang-nursery.github.io/packed_simd/packed_simd/
172	[perf_guide]: https://rust-lang-nursery.github.io/packed_simd/perf-guide/
173	[rfc2366]: https://github.com/rust-lang/rfcs/pull/2366
174	[ISPC]: https://ispc.github.io/
175	[rayon]: https://crates.io/crates/rayon
176	[boost_license]: https://www.boost.org/LICENSE_1_0.txt
177	[SLEEF]: https://sleef.org/
178	[sleef_sys]: https://crates.io/crates/sleef-sys
179	[contributing instructions]: contributing.md
180	[Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html