vendor/packed_simd_2/README.md

   1 # The Crates.io Version Can No Longer Be Updated!
   2
   3 The original maintainer is out of contact, and the new maintainers (the Portable SIMD Project Group) do not have the appropriate crates.io permissions to issue updates.
   4
   5 We are aware that the version available on crates.io is currently broken, and will not build.
   6
   7 If you need to continue to use the crate, we have published a "next version" under an alternative name.
   8
   9 Adjust your `[dependencies]` section of `Cargo.toml` to be the following:
  10 ```toml
  11 packed_simd = { version = "0.3.8", package = "packed_simd_2" }
  12 ```
  13
  14 # `Simd<[T; N]>`
  15
  16 ## Implementation of [Rust RFC #2366: `std::simd`][rfc2366]
  17
  18 [![Travis-CI Status]][travis] <!-- [![Appveyor Status]][appveyor] --> [![Latest Version]][crates.io] [![docs]][master_docs]
  19
  20 **WARNING**: this crate only supports the most recent nightly Rust toolchain
  21 and will be superseded by [stdsimd](https://github.com/rust-lang/stdsimd).
  22
  23 ## Documentation
  24
  25 * [API docs (`master` branch)][master_docs]
  26 * [Performance guide][perf_guide]
  27 * [API docs (`docs.rs`)][docs.rs]
  28 * [RFC2366 `std::simd`][rfc2366]: - contains motivation, design rationale,
  29   discussion, etc.
  30
  31 ## Examples
  32
  33 Most of the examples come with both a scalar and a vectorized implementation.
  34
  35 * [`aobench`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/aobench)
  36 * [`fannkuch_redux`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/fannkuch_redux)
  37 * [`matrix inverse`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/matrix_inverse)
  38 * [`mandelbrot`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/mandelbrot)
  39 * [`n-body`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/nbody)
  40 * [`options_pricing`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/options_pricing)
  41 * [`spectral_norm`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/spectral_norm)
  42 * [`triangle transform`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/triangle_xform)
  43 * [`stencil`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/stencil)
  44 * [`vector dot product`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/dot_product)
  45
  46 ## Cargo features
  47
  48 * `into_bits` (default: disabled): enables `FromBits`/`IntoBits` trait
  49   implementations for the vector types. These allow reinterpreting the bits of a
  50   vector type as those of another vector type safely by just using the
  51   `.into_bits()` method.
  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
  79 the library compiles without issues for a given target, while `run` shows
  80 whether the test suite passes for a given target.
  81
  82 | **Linux**                             | **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**                            | **build** | **run** |
 102 | `x86_64-apple-darwin`                 | ✓         | ✓       |
 103 | **Android**                           | **build** | **run** |
 104 | `x86_64-linux-android`                | ✓         | ✓       |
 105 | `arm-linux-androideabi`               | ✓         | ✓       |
 106 | `aarch64-linux-android`               | ✓         | ✓       |
 107 | `thumbv7neon-linux-androideabi`       | ✗         | ✗       |
 108 | **iOS**                               | **build** | **run** |
 109 | `x86_64-apple-ios`                    | ✓         | ✗       |
 110 | `aarch64-apple-ios`                   | ✓         | ✗       |
 111
 112
 113 ## Machine code verification
 114
 115 The
 116 [`verify/`](https://github.com/rust-lang-nursery/packed_simd/tree/master/verify)
 117 crate tests disassembles the portable packed vector APIs at run-time and
 118 compares the generated machine code against the desired one to make sure that
 119 this crate remains efficient.
 120
 121 ## License
 122
 123 This project is licensed under either of
 124
 125 * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
 126   ([LICENSE-APACHE](LICENSE-APACHE))
 127
 128 * [MIT License](http://opensource.org/licenses/MIT)
 129   ([LICENSE-MIT](LICENSE-MIT))
 130
 131 at your option.
 132
 133 ## Contributing
 134
 135 We welcome all people who want to contribute.
 136 Please see the [contributing instructions] for more information.
 137
 138 Contributions in any form (issues, pull requests, etc.) to this project
 139 must adhere to Rust's [Code of Conduct].
 140
 141 Unless you explicitly state otherwise, any contribution intentionally submitted
 142 for inclusion in `packed_simd` by you, as defined in the Apache-2.0 license, shall be
 143 dual licensed as above, without any additional terms or conditions.
 144
 145 [travis]: https://travis-ci.com/rust-lang/packed_simd
 146 [Travis-CI Status]: https://travis-ci.com/rust-lang/packed_simd.svg?branch=master
 147 [appveyor]: https://ci.appveyor.com/project/gnzlbg/packed-simd
 148 [Appveyor Status]: https://ci.appveyor.com/api/projects/status/hd7v9dvr442hgdix?svg=true
 149 [Latest Version]: https://img.shields.io/crates/v/packed_simd_2.svg
 150 [crates.io]: https://crates.io/crates/packed_simd_2
 151 [docs]: https://docs.rs/packed_simd_2/badge.svg
 152 [docs.rs]: https://docs.rs/packed_simd_2
 153 [master_docs]: https://rust-lang-nursery.github.io/packed_simd/packed_simd_2/
 154 [perf_guide]: https://rust-lang-nursery.github.io/packed_simd/perf-guide/
 155 [rfc2366]: https://github.com/rust-lang/rfcs/pull/2366
 156 [ISPC]: https://ispc.github.io/
 157 [rayon]: https://crates.io/crates/rayon
 158 [boost_license]: https://www.boost.org/LICENSE_1_0.txt
 159 [SLEEF]: https://sleef.org/
 160 [sleef_sys]: https://crates.io/crates/sleef-sys
 161 [contributing instructions]: contributing.md
 162 [Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html