Merge pull request #13 from MurrellGroup/main

Update v0.1.0 branch

Author: AntonOresten

README.md

@@ -5,7 +5,7 @@
 [![Build Status](https://github.com/MurrellGroup/Microfloats.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/MurrellGroup/Microfloats.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/MurrellGroup/Microfloats.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/MurrellGroup/Microfloats.jl)
 
-Microfloats is a Julia package that implements floating point types and arithmetic for sub-8 bit floating point types, supporting arbitrary combinations of sign, exponent, and mantissa bits.
+Microfloats is a Julia package that implements floating point types and arithmetic (through wider intermediates) for sub-8 bit floating point types, supporting arbitrary combinations of sign, exponent, and mantissa (significand) bits.
 
 Instances of a sub-8 bit floating point type are still 8 bits wide in memory; the goal of `Microfloat` is to serve as a base for arithmetic operations and method dispatch, lending downstream packages a good abstraction for doing bitpacking and hardware acceleration.
 
@@ -30,12 +30,12 @@ const UFloat7_5 = Microfloat{0,5,2,IEEE_754_like}
 
 ### Microscaling (MX)
 
-Microfloats implements the E4M3, E5M2, E2M3, E3M2, E2M1, and E8M0 types from the [Open Compute Project Microscaling Formats (MX) Specification](https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf), with most of these using saturated arithmetic (no infinities), and different bit layouts for NaNs. These are exported as `MX_E4M3`, `MX_E5M2`, `MX_E2M3`, `MX_E3M2`, `MX_E2M1`, and `MX_E8M0`, respectively.
+Microfloats implements the E4M3, E5M2, E2M3, E3M2, E2M1, and E8M0 types from the [Open Compute Project Microscaling Formats (MX) Specification](https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf). These are exported as `MX_E4M3`, `MX_E5M2`, `MX_E2M3`, `MX_E3M2`, `MX_E2M1`, and `MX_E8M0`, respectively, with most of these using saturated arithmetic (no Inf or NaN), and a different encoding for the types that do have NaNs.
 
 For INT8, see `FixedPointNumbers.Q1f6`.
 
-> [!WARNING]
-> MX types may not yet be fully OCP compliant. See issues with the [![MX-compliance](https://img.shields.io/github/labels/MurrellGroup/Microfloats.jl/mx-compliance)](https://github.com/MurrellGroup/Microfloats.jl/labels/mx-compliance) label.
+> [!NOTE]
+> MX types may not be fully MX compliant, but efforts have been and continue to be made to adhere to the specification. See issues with the [![MX-compliance](https://img.shields.io/github/labels/MurrellGroup/Microfloats.jl/mx-compliance)](https://github.com/MurrellGroup/Microfloats.jl/labels/mx-compliance) label.
 
 Since Microfloats.jl only implements the primitive types, microscaling itself may be done with [Microscaling.jl](https://github.com/MurrellGroup/Microscaling.jl), which includes quantization and bitpacking.
 

docs/src/assets/icon.svg

@@ -4,7 +4,7 @@
 ## BFloat16
 
 Conversion to and from `Microfloat` uses `BFloat16` as an intermediate type,
-since BFloat16 has 1 sign bit, 8 exponent bits, and 7 significand bits,
+since BFloat16 has 1 sign bit, 8 exponent bits, and 7 significand (mantissa) bits,
 and is therefore able to represent all `Microfloat` types.
 
 ## Rounding

docs/src/conversion.md

@@ -41,7 +41,7 @@ include("random.jl")
     Microfloat{S,E,M,V}
 
 A `Microfloat` type has `S` sign bits (between 0 and 1),
-`E` exponent bits (between 1 and 8), and `M` significand bits (between 0 and 7).
+`E` exponent bits (between 1 and 8), and `M` mantissa bits (between 0 and 7).
 """
 Microfloat
 
@@ -70,8 +70,8 @@ for T in (
         - Has NaN: `$(hasnan($T))`
         - Max normal: `$(Float64(floatmax($T)))`
         - Min normal: `$(Float64(floatmin($T)))`
-        - Max subnormal: `$(Float64(prevfloat(floatmin($T))))`
-        - Min subnormal: `$(Float64(nextfloat(zero($T))))`
+        - Max subnormal: `$(significand_bits($T) > 0 ? Float64(prevfloat(floatmin($T))) : "N/A")`
+        - Min subnormal: `$(significand_bits($T) > 0 ? Float64(nextfloat(zero($T))) : "N/A")`
         """
         $T
     end

src/Microfloats.jl

@@ -3,11 +3,12 @@ abstract type SAT <: OverflowPolicy end
 abstract type OVF <: OverflowPolicy end
 
 function rshift_round_to_even(x::UInt16, n::Int)
-    n <= 0 && return x << (-n)
-    lower = x & ((UInt16(1) << n) - UInt16(1))
-    half = UInt16(1) << (n - 1)
-    up = (lower > half) | ((lower == half) & (((x >> n) & UInt16(1)) == UInt16(1)))
-    (x >> n) + (up ? UInt16(1) : UInt16(0))
+    n <= 0 && return x >> n
+    x_32 = UInt32(x)
+    lower = x_32 & ((UInt32(1) << n) - UInt32(1))
+    half = UInt32(1) << (n - 1)
+    up = (lower > half) | ((lower == half) & (((x_32 >> n) & UInt32(1)) == UInt32(1)))
+    UInt16((x_32 >> n) + (up ? 1 : 0))
 end
 
 is_outside_floatmax(xb::BFloat16, ::Type{T}) where T<:Microfloat = reinterpret(Unsigned, abs(xb)) > reinterpret(Unsigned, BFloat16(floatmax(T)))