Struct burn::tensor::f16

source ·

pub struct f16(/* private fields */);

Expand description

A 16-bit floating point type implementing the IEEE 754-2008 standard binary16 a.k.a “half” format.

This 16-bit floating point type is intended for efficient storage where the full range and precision of a larger floating point value is not required.

Implementations§

Returns the memory representation of the underlying bit representation as a byte array in native byte order.

As the target platform’s native endianness is used, portable code should use to_be_bytes or to_le_bytes, as appropriate, instead.

§Examples

let bytes = f16::from_f32(12.5).to_ne_bytes();
assert_eq!(bytes, if cfg!(target_endian = "big") {
    [0x4A, 0x40]
} else {
    [0x40, 0x4A]
});

source

pub const fn from_le_bytes(bytes: [u8; 2]) -> f16

Creates a floating point value from its representation as a byte array in little endian.

§Examples

let value = f16::from_le_bytes([0x40, 0x4A]);
assert_eq!(value, f16::from_f32(12.5));

source

pub const fn from_be_bytes(bytes: [u8; 2]) -> f16

Creates a floating point value from its representation as a byte array in big endian.

§Examples

let value = f16::from_be_bytes([0x4A, 0x40]);
assert_eq!(value, f16::from_f32(12.5));

source

pub const fn from_ne_bytes(bytes: [u8; 2]) -> f16

Creates a floating point value from its representation as a byte array in native endian.

As the target platform’s native endianness is used, portable code likely wants to use from_be_bytes or from_le_bytes, as appropriate instead.

§Examples

let value = f16::from_ne_bytes(if cfg!(target_endian = "big") {
    [0x4A, 0x40]
} else {
    [0x40, 0x4A]
});
assert_eq!(value, f16::from_f32(12.5));

source

pub fn to_f32(self) -> f32

Converts a [f16] value into a f32 value.

This conversion is lossless as all 16-bit floating point values can be represented exactly in 32-bit floating point.

source

pub const fn to_f32_const(self) -> f32

Converts a [f16] value into a f32 value.

This function is identical to to_f32 except it never uses hardware intrinsics, which allows it to be const. to_f32 should be preferred in any non-const context.

This conversion is lossless as all 16-bit floating point values can be represented exactly in 32-bit floating point.

source

pub fn to_f64(self) -> f64

Converts a [f16] value into a f64 value.

This conversion is lossless as all 16-bit floating point values can be represented exactly in 64-bit floating point.

source

pub const fn to_f64_const(self) -> f64

Converts a [f16] value into a f64 value.

This function is identical to to_f64 except it never uses hardware intrinsics, which allows it to be const. to_f64 should be preferred in any non-const context.


let min = f16::MIN_POSITIVE;
let max = f16::MAX;
let lower_than_min = f16::from_f32(1.0e-10_f32);
let zero = f16::from_f32(0.0_f32);

assert!(min.is_normal());
assert!(max.is_normal());

assert!(!zero.is_normal());
assert!(!f16::NAN.is_normal());
assert!(!f16::INFINITY.is_normal());
// Values between `0` and `min` are Subnormal.
assert!(!lower_than_min.is_normal());

source

pub const fn classify(self) -> FpCategory

Returns the floating point category of the number.

If only one property is going to be tested, it is generally faster to use the specific predicate instead.

§Examples

use std::num::FpCategory;

let num = f16::from_f32(12.4_f32);
let inf = f16::INFINITY;

assert_eq!(num.classify(), FpCategory::Normal);
assert_eq!(inf.classify(), FpCategory::Infinite);

source

pub const fn signum(self) -> f16

Returns a number that represents the sign of self.

1.0 if the number is positive, +0.0 or INFINITY
-1.0 if the number is negative, -0.0 or NEG_INFINITY
NAN if the number is NaN

§Examples


let f = f16::from_f32(3.5_f32);

assert_eq!(f.signum(), f16::from_f32(1.0));
assert_eq!(f16::NEG_INFINITY.signum(), f16::from_f32(-1.0));

assert!(f16::NAN.signum().is_nan());

source

pub const fn is_sign_positive(self) -> bool

Returns true if and only if self has a positive sign, including +0.0, NaNs with a positive sign bit and +∞.

§Examples


let nan = f16::NAN;
let f = f16::from_f32(7.0_f32);
let g = f16::from_f32(-7.0_f32);

assert!(f.is_sign_positive());
assert!(!g.is_sign_positive());
// `NaN` can be either positive or negative
assert!(nan.is_sign_positive() != nan.is_sign_negative());

source

pub const fn is_sign_negative(self) -> bool

Returns true if and only if self has a negative sign, including -0.0, NaNs with a negative sign bit and −∞.

§Examples


let nan = f16::NAN;
let f = f16::from_f32(7.0f32);
let g = f16::from_f32(-7.0f32);

assert!(!f.is_sign_negative());
assert!(g.is_sign_negative());
// `NaN` can be either positive or negative
assert!(nan.is_sign_positive() != nan.is_sign_negative());

source

pub const fn copysign(self, sign: f16) -> f16

Returns a number composed of the magnitude of self and the sign of sign.

Equal to self if the sign of self and sign are the same, otherwise equal to -self. If self is NaN, then NaN with the sign of sign is returned.

§Examples

let f = f16::from_f32(3.5);

assert_eq!(f.copysign(f16::from_f32(0.42)), f16::from_f32(3.5));
assert_eq!(f.copysign(f16::from_f32(-0.42)), f16::from_f32(-3.5));
assert_eq!((-f).copysign(f16::from_f32(0.42)), f16::from_f32(3.5));
assert_eq!((-f).copysign(f16::from_f32(-0.42)), f16::from_f32(-3.5));

assert!(f16::NAN.copysign(f16::from_f32(1.0)).is_nan());

source

pub fn max(self, other: f16) -> f16

Returns the maximum of the two numbers.

If one of the arguments is NaN, then the other argument is returned.

§Examples

let x = f16::from_f32(1.0);
let y = f16::from_f32(2.0);

assert_eq!(x.max(y), y);

source

pub fn min(self, other: f16) -> f16

Returns the minimum of the two numbers.

If one of the arguments is NaN, then the other argument is returned.

§Examples

let x = f16::from_f32(1.0);
let y = f16::from_f32(2.0);

assert_eq!(x.min(y), x);

source

pub fn clamp(self, min: f16, max: f16) -> f16

Restrict a value to a certain interval unless it is NaN.

Returns max if self is greater than max, and min if self is less than min. Otherwise this returns self.

Note that this function returns NaN if the initial value was NaN as well.

§Panics

Panics if min > max, min is NaN, or max is NaN.

§Examples

assert!(f16::from_f32(-3.0).clamp(f16::from_f32(-2.0), f16::from_f32(1.0)) == f16::from_f32(-2.0));
assert!(f16::from_f32(0.0).clamp(f16::from_f32(-2.0), f16::from_f32(1.0)) == f16::from_f32(0.0));
assert!(f16::from_f32(2.0).clamp(f16::from_f32(-2.0), f16::from_f32(1.0)) == f16::from_f32(1.0));
assert!(f16::NAN.clamp(f16::from_f32(-2.0), f16::from_f32(1.0)).is_nan());

source

pub fn total_cmp(&self, other: &f16) -> Ordering

Returns the ordering between self and other.

Unlike the standard partial comparison between floating point numbers, this comparison always produces an ordering in accordance to the totalOrder predicate as defined in the IEEE 754 (2008 revision) floating point standard. The values are ordered in the following sequence:

negative quiet NaN
negative signaling NaN
negative infinity
negative numbers
negative subnormal numbers
negative zero
positive zero
positive subnormal numbers
positive numbers
positive infinity
positive signaling NaN
positive quiet NaN.

The ordering established by this function does not always agree with the PartialOrd and PartialEq implementations of f16. For example, they consider negative and positive zero equal, while total_cmp doesn’t.

The interpretation of the signaling NaN bit follows the definition in the IEEE 754 standard, which may not match the interpretation by some of the older, non-conformant (e.g. MIPS) hardware implementations.

§Examples

let mut v: Vec<f16> = vec![];
v.push(f16::ONE);
v.push(f16::INFINITY);
v.push(f16::NEG_INFINITY);
v.push(f16::NAN);
v.push(f16::MAX_SUBNORMAL);
v.push(-f16::MAX_SUBNORMAL);
v.push(f16::ZERO);
v.push(f16::NEG_ZERO);
v.push(f16::NEG_ONE);
v.push(f16::MIN_POSITIVE);

v.sort_by(|a, b| a.total_cmp(&b));

assert!(v
    .into_iter()
    .zip(
        [
            f16::NEG_INFINITY,
            f16::NEG_ONE,
            -f16::MAX_SUBNORMAL,
            f16::NEG_ZERO,
            f16::ZERO,
            f16::MAX_SUBNORMAL,
            f16::MIN_POSITIVE,
            f16::ONE,
            f16::INFINITY,
            f16::NAN
        ]
        .iter()
    )
    .all(|(a, b)| a.to_bits() == b.to_bits()));

source

pub fn serialize_as_f32<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>
where S: Serializer,

Alternate serialize adapter for serializing as a float.

By default, [f16] serializes as a newtype of u16. This is an alternate serialize implementation that serializes as an f32 value. It is designed for use with serialize_with serde attributes. Deserialization from f32 values is already supported by the default deserialize implementation.

§Examples

A demonstration on how to use this adapater:

use serde::{Serialize, Deserialize};
use half::f16;

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(serialize_with = "f16::serialize_as_f32")]
    value: f16 // Will be serialized as f32 instead of u16
}

source

pub fn serialize_as_string<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>
where S: Serializer,

Alternate serialize adapter for serializing as a string.

By default, [f16] serializes as a newtype of u16. This is an alternate serialize implementation that serializes as a string value. It is designed for use with serialize_with serde attributes. Deserialization from string values is already supported by the default deserialize implementation.

§Examples

A demonstration on how to use this adapater:

use serde::{Serialize, Deserialize};
use half::f16;

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(serialize_with = "f16::serialize_as_string")]
    value: f16 // Will be serialized as a string instead of u16
}

source

pub const DIGITS: u32 = 3u32

Approximate number of [f16] significant digits in base 10

source

pub const EPSILON: f16 = _

[f16] machine epsilon value

[f16] √2

Trait Implementations§

§

impl Abs for f16

§

fn abs(x: Self) -> Self

§

fn __expand_clamp( context: &mut CubeContext, input: Self::ExpandType, min_value: Self::ExpandType, max_value: Self::ExpandType, ) -> Self::ExpandType

source §

impl Clone for f16

source §

fn clone(&self) -> f16

Returns a copy of the value. Read more

1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

§

fn __expand_cos( context: &mut CubeContext, x: Self::ExpandType, ) -> ExpandElementTyped<Self>

§

Lowest possible value

fn from_expand_elem(elem: ExpandElement) -> Self::ExpandType

§

impl Element for f16

§

const KIND: Kind = Kind::Half

§

const ZERO: f16 = half::f16::ZERO

§

impl ElementComparison for f16

§

fn cmp(&self, other: &f16) -> Ordering

Returns and Ordering between self and other.

§

impl ElementConversion for f16

§

fn from_elem<E>(elem: E) -> f16
where E: ToElement,

Converts an element to another element. Read more

§

fn floor(x: Self) -> Self

§

source §

impl FromStr for f16

source §

type Err = ParseFloatError

The associated error which can be returned from parsing.

source §

fn from_str(src: &str) -> Result<f16, ParseFloatError>

Parses a string s to return a value of this type. Read more

fn vec_dot_unopt( n: usize, xs: &[f16], ys: &[<f16 as GgmlType>::VecDotType], ) -> Result<f32, Error>

Generic implementation of the dot product without simd optimizations.

fn to_f32(&self) -> f32

Convert this sample to an f32, trying to represent the same numerical value.

§

fn to_u32(&self) -> u32

Convert this sample to an u16, trying to represent the same numerical value.

§

Compilation argument.

§

fn expand( _: &<f16 as LaunchArgExpand>::CompilationArg, builder: &mut KernelBuilder, ) -> ExpandElementTyped<f16>

Register an input variable during compilation that fill the [KernelBuilder].

§

fn expand_output( arg: &Self::CompilationArg, builder: &mut KernelBuilder, ) -> Self::ExpandType

Register an output variable during compilation that fill the [KernelBuilder].

Formats the value using the given formatter. Read more

source §

impl LowerHex for f16

source §

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more

fn neg(self) -> <&f16 as Neg>::Output

Performs the unary - operation. Read more

source §

impl Neg for f16

source §

type Output = f16

The resulting type after applying the - operator.

source §

fn neg(self) -> <f16 as Neg>::Output

Performs the unary - operation. Read more

Convert from a string and radix (typically 2..=36). Read more

source §

impl NumCast for f16

source §

fn from<T>(n: T) -> Option<f16>
where T: ToPrimitive,

Creates a number from another value that can be converted into a primitive via the ToPrimitive trait. If the source value cannot be represented by the target type, then None is returned. Read more

§

impl Numeric for f16

§

const MAX: f16 = f16::MAX

§

const MIN: f16 = f16::MIN

§

fn from_int(val: i64) -> Self

Create a new constant numeric. Read more

impl One for f16

source §

fn one() -> f16

Returns the multiplicative identity element of Self, 1. Read more

source §

fn set_one(&mut self)

Sets self to the multiplicative identity element of Self, 1.

source §

fn is_one(&self) -> bool
where Self: PartialEq,

Returns true if self is equal to the multiplicative identity. Read more

source §

impl PartialEq for f16

source §

fn eq(&self, other: &f16) -> bool

Tests for self and other values to be equal, and is used by ==.

1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

source §

impl Product for f16

source §

fn product(iter: I) -> f16
where I: Iterator<Item = f16>,

Takes an iterator and generates Self from the elements by multiplying the items.

§

unsafe fn vec_dot(lhs: const f16, rhs: const f16, res: *mut f16, len: usize)

Dot-product of two vectors. Read more

§

unsafe fn vec_reduce_sum(xs: const Self, res: mut Self, len: usize)

Sum of all elements in a vector. Read more

§

unsafe fn vec_reduce_max(xs: const Self, res: mut Self, len: usize)

Maximum element in a non-empty vector. Read more

§

unsafe fn vec_reduce_min(xs: const Self, res: mut Self, len: usize)

Minimum element in a non-empty vector. Read more

Returns the additive identity element of Self, 0. Read more

source §

fn is_zero(&self) -> bool

Returns true if self is equal to the additive identity.

source §

fn set_zero(&mut self)

Sets self to the additive identity element of Self, 0.

source §

impl Zeroable for f16

§

fn zeroed() -> Self

Calls zeroed. Read more

impl<T> Borrow<T> for T
where T: ?Sized,

source §

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

source §

impl<T> BorrowMut<T> for T
where T: ?Sized,

source §

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

fn is_valid_bit_pattern(_bits: &T) -> bool

If this function returns true, then it must be valid to reinterpret bits as &Self.

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more

§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more

§