| 1 |
# `f16` and `bf16` floating point types for Rust |
| 2 |
[](https://crates.io/crates/half/) [](https://docs.rs/half/)  [](https://github.com/starkat99/half-rs/actions/workflows/rust.yml) [](https://dl.circleci.com/status-badge/redirect/gh/starkat99/half-rs/tree/main) |
| 3 |
|
| 4 |
This crate implements a half-precision floating point `f16` type for Rust implementing the IEEE |
| 5 |
754-2008 standard [`binary16`](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) |
| 6 |
a.k.a "half" format, as well as a `bf16` type implementing the |
| 7 |
[`bfloat16`](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format) format. |
| 8 |
|
| 9 |
## Usage |
| 10 |
|
| 11 |
The `f16` and `bf16` types attempt to match existing Rust floating point type functionality where possible, and provides both conversion operations (such as to/from `f32` and `f64`) and basic |
| 12 |
arithmetic operations. Hardware support for these operations will be used whenever hardware support |
| 13 |
is available—either through instrinsics or targeted assembly—although a nightly Rust toolchain may |
| 14 |
be required for some hardware. |
| 15 |
|
| 16 |
This crate provides [`no_std`](https://rust-embedded.github.io/book/intro/no-std.html) support so can easily be used in embedded code where a smaller float format is most useful. |
| 17 |
|
| 18 |
*Requires Rust 1.70 or greater.* If you need support for older versions of Rust, use 1.x versions of |
| 19 |
this crate. |
| 20 |
|
| 21 |
See the [crate documentation](https://docs.rs/half/) for more details. |
| 22 |
|
| 23 |
### Optional Features |
| 24 |
|
| 25 |
- **`alloc`** — Enable use of the [`alloc`](https://doc.rust-lang.org/alloc/) crate when not using |
| 26 |
the `std` library. |
| 27 |
|
| 28 |
This enables the `vec` module, which contains zero-copy conversions for the `Vec` type. This |
| 29 |
allows fast conversion between raw `Vec<u16>` bits and `Vec<f16>` or `Vec<bf16>` arrays, and vice |
| 30 |
versa. |
| 31 |
|
| 32 |
- **`std`** — Enable features that depend on the Rust `std` library, including everything in the |
| 33 |
`alloc` feature. |
| 34 |
|
| 35 |
Enabling the `std` feature enables runtime CPU feature detection of hardware support. |
| 36 |
Without this feature detection, harware is only used when compiler target supports them. |
| 37 |
|
| 38 |
- **`serde`** - Implement `Serialize` and `Deserialize` traits for `f16` and `bf16`. This adds a |
| 39 |
dependency on the [`serde`](https://crates.io/crates/serde) crate. |
| 40 |
|
| 41 |
- **`num-traits`** — Enable `ToPrimitive`, `FromPrimitive`, `Num`, `Float`, `FloatCore` and |
| 42 |
`Bounded` trait implementations from the [`num-traits`](https://crates.io/crates/num-traits) crate. |
| 43 |
|
| 44 |
- **`bytemuck`** — Enable `Zeroable` and `Pod` trait implementations from the |
| 45 |
[`bytemuck`](https://crates.io/crates/bytemuck) crate. |
| 46 |
|
| 47 |
- **`zerocopy`** — Enable `AsBytes` and `FromBytes` trait implementations from the |
| 48 |
[`zerocopy`](https://crates.io/crates/zerocopy) crate. |
| 49 |
|
| 50 |
- **`rand_distr`** — Enable sampling from distributions like `Uniform` and `Normal` from the |
| 51 |
[`rand_distr`](https://crates.io/crates/rand_distr) crate. |
| 52 |
|
| 53 |
- **`rkyv`** -- Enable zero-copy deserializtion with [`rkyv`](https://crates.io/crates/rkyv) crate. |
| 54 |
|
| 55 |
### Hardware support |
| 56 |
|
| 57 |
The following list details hardware support for floating point types in this crate. When using `std` |
| 58 |
library, runtime CPU target detection will be used. To get the most performance benefits, compile |
| 59 |
for specific CPU features which avoids the runtime overhead and works in a `no_std` environment. |
| 60 |
|
| 61 |
| Architecture | CPU Target Feature | Notes | |
| 62 |
| ------------ | ------------------ | ----- | |
| 63 |
| `x86`/`x86_64` | `f16c` | This supports conversion to/from `f16` only (including vector SIMD) and does not support any `bf16` or arithmetic operations. | |
| 64 |
| `aarch64` | `fp16` | This supports all operations on `f16` only. | |
| 65 |
|
| 66 |
### More Documentation |
| 67 |
|
| 68 |
- [Crate API Reference](https://docs.rs/half/) |
| 69 |
- [Latest Changes](CHANGELOG.md) |
| 70 |
|
| 71 |
## License |
| 72 |
|
| 73 |
This library is distributed under the terms of either of: |
| 74 |
|
| 75 |
* [MIT License](LICENSES/MIT.txt) |
| 76 |
([http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT)) |
| 77 |
* [Apache License, Version 2.0](LICENSES/Apache-2.0.txt) |
| 78 |
([http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)) |
| 79 |
|
| 80 |
at your option. |
| 81 |
|
| 82 |
This project is [REUSE-compliant](https://reuse.software/spec/). Copyrights are retained by their |
| 83 |
contributors. Some files may include explicit copyright notices and/or license |
| 84 |
[SPDX identifiers](https://spdx.dev/ids/). For full authorship information, see the version control |
| 85 |
history. |
| 86 |
|
| 87 |
### Contributing |
| 88 |
|
| 89 |
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the |
| 90 |
work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any |
| 91 |
additional terms or conditions. |