f16 and bf16 floating point types for Rust

This crate implements a half-precision floating point f16 type for Rust implementing the IEEE 754-2008 standard binary16 a.k.a "half" format, as well as a bf16 type implementing the bfloat16 format.

Usage

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 arithmetic operations. Hardware support for these operations will be used whenever hardware support is available—either through instrinsics or targeted assembly—although a nightly Rust toolchain may be required for some hardware.

This crate provides no_std support by default so can easily be used in embedded code where a smaller float format is most useful.

Requires Rust 1.61 or greater. If you need support for older versions of Rust, use 1.x versions of this crate.

See the crate documentation for more details.

Optional Features

• serde - Implement Serialize and Deserialize traits for f16 and bf16. This adds a dependency on the serde crate.

• use-intrinsics — Use unstable hardware intrinsics for f16 and bf16 conversions if available on the compiler target. By default, only hardware support compatible with the Rust stable toolchain will be used, or software emulation otherwise. Available only on Rust nightly channel.

• alloc — Enable use of the 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 of hardware support. Without this feature detection, harware is only used when compiler target supports them.

• num-traits — Enable ToPrimitive, FromPrimitive, Num, Float, FloatCore and Bounded trait implementations from the num-traits crate.

• bytemuck — Enable Zeroable and Pod trait implementations from the bytemuck crate.

• zerocopy — Enable AsBytes and FromBytes trait implementations from the zerocopy crate.

Hardware support

The following list details hardware support for floating point types in this crate. When using std library, runtime CPU target detection will be used. To get the most performance benefits, compile for specific CPU features which avoids the runtime overhead and works in a no_std environment.

Architecture	CPU Target Feature	Notes
x86/x86_64	f16c	Only on nightly Rust toolchain with use-intrinsics cargo feature. This supports conversion to/from f16 only (including vector SIMD) and does not support any bf16 or arithmetic operations.
aarch64	fp16	This supports all operations on f16 only.

More Documentation

• Crate API Reference
• Latest Changes

License

This library is distributed under the terms of either of:

• MIT License (http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)

at your option.

This project is REUSE-compliant. Copyrights are retained by their contributors. Some files may include explicit copyright notices and/or license SPDX identifiers. 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.