83 lines
4.1 KiB
Markdown
83 lines
4.1 KiB
Markdown
|
# `f16` and `bf16` floating point types for Rust
|
||
|
|
[](https://crates.io/crates/half/) [](https://docs.rs/half/)  [](https://github.com/starkat99/half-rs/actions/workflows/rust.yml)
|
||
|
|
|
||
|
|
This crate implements a half-precision floating point `f16` type for Rust implementing the IEEE
|
||
|
|
754-2008 standard [`binary16`](https://en.wikipedia.org/wiki/Half-precision_floating-point_format)
|
||
|
|
a.k.a `half` format, as well as a `bf16` type implementing the
|
||
|
|
[`bfloat16`](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format) format.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
The `f16` and `bf16` types provides conversion operations as a normal Rust floating point type, but
|
||
|
|
since they are primarily leveraged for minimal floating point storage and most major hardware does
|
||
|
|
not implement them, all math operations are done as an `f32` type under the hood. Complex arithmetic
|
||
|
|
should manually convert to and from `f32` for better performance.
|
||
|
|
|
||
|
|
This crate provides [`no_std`](https://rust-embedded.github.io/book/intro/no-std.html) support by
|
||
|
|
default so can easily be used in embedded code where a smaller float format is most useful.
|
||
|
|
|
||
|
|
*Requires Rust 1.58 or greater.* If you need support for older versions of Rust, use 1.x versions of
|
||
|
|
this crate.
|
||
|
|
|
||
|
|
See the [crate documentation](https://docs.rs/half/) for more details.
|
||
|
|
|
||
|
|
### Optional Features
|
||
|
|
|
||
|
|
- **`serde`** - Implement `Serialize` and `Deserialize` traits for `f16` and `bf16`. This adds a
|
||
|
|
dependency on the [`serde`](https://crates.io/crates/serde) crate.
|
||
|
|
|
||
|
|
- **`use-intrinsics`** - Use hardware intrinsics for `f16` and `bf16` conversions if available on
|
||
|
|
the compiler host target. By default, without this feature, conversions are done only in software,
|
||
|
|
which will be the fallback if the host target does not have hardware support. **Available only on
|
||
|
|
Rust nightly channel.**
|
||
|
|
|
||
|
|
- **`alloc`** - Enable use of the [`alloc`](https://doc.rust-lang.org/alloc/) crate when not using
|
||
|
|
the `std` library.
|
||
|
|
|
||
|
|
This enables the `vec` module, which contains zero-copy conversions for the `Vec` type. This
|
||
|
|
allows fast conversion between raw `Vec<u16>` bits and `Vec<f16>` or `Vec<bf16>` arrays, and vice
|
||
|
|
versa.
|
||
|
|
|
||
|
|
- **`std`** - Enable features that depend on the Rust `std` library, including everything in the
|
||
|
|
`alloc` feature.
|
||
|
|
|
||
|
|
Enabling the `std` feature enables runtime CPU feature detection when the `use-intrsincis` feature
|
||
|
|
is also enabled.
|
||
|
|
Without this feature detection, intrinsics are only used when compiler host target supports them.
|
||
|
|
|
||
|
|
- **`num-traits`** - Enable `ToPrimitive`, `FromPrimitive`, `Num`, `Float`, `FloatCore` and
|
||
|
|
`Bounded` trait implementations from the [`num-traits`](https://crates.io/crates/num-traits) crate.
|
||
|
|
|
||
|
|
- **`bytemuck`** - Enable `Zeroable` and `Pod` trait implementations from the
|
||
|
|
[`bytemuck`](https://crates.io/crates/bytemuck) crate.
|
||
|
|
|
||
|
|
- **`zerocopy`** - Enable `AsBytes` and `FromBytes` trait implementations from the
|
||
|
|
[`zerocopy`](https://crates.io/crates/zerocopy) crate.
|
||
|
|
|
||
|
|
### More Documentation
|
||
|
|
|
||
|
|
- [Crate API Reference](https://docs.rs/half/)
|
||
|
|
- [Latest Changes](CHANGELOG.md)
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
This library is distributed under the terms of either of:
|
||
|
|
|
||
|
|
* [MIT License](LICENSES/MIT.txt)
|
||
|
|
([http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))
|
||
|
|
* [Apache License, Version 2.0](LICENSES/Apache-2.0.txt)
|
||
|
|
([http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))
|
||
|
|
|
||
|
|
at your option.
|
||
|
|
|
||
|
|
This project is [REUSE-compliant](https://reuse.software/spec/). Copyrights are retained by their
|
||
|
|
contributors. Some files may include explicit copyright notices and/or license
|
||
|
|
[SPDX identifiers](https://spdx.dev/ids/). For full authorship information, see the version control
|
||
|
|
history.
|
||
|
|
|
||
|
|
### Contributing
|
||
|
|
|
||
|
|
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the
|
||
|
|
work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
|
||
|
|
additional terms or conditions.
|