Merge pull request #35 from graphcore-research/tidy-rounding

Tidy rounding

Author: awf

docs/source/index.rst

@@ -55,6 +55,13 @@ As well as block formats from |ocp_mx_link|.
       IEEE P3109
     </a>
 
+Supported rounding modes include:
+
+  * Directed modes: Toward Zero, Toward Positive, Toward Negative
+  * Round-to-nearest, with Ties to Even or Ties to Away
+  * Stochastic rounding, with specified numbers of random bits
+
+
 Example
 -------
 This table (from example notebook :doc:`value-stats <02-value-stats>`) shows how
@@ -65,8 +72,8 @@ gfloat has been used to tabulate properties of various floating point formats.
  - P: Precision in bits
  - E: Exponent field width in bits
  - smallest: Smallest positive value
- - smallest_normal: Smallest positive normal value, NaN if no finite values are normal
- - max: Largest finite normal value, NaN if all finite values are subnormal
+ - smallest_normal: Smallest positive normal value, n/a if no finite values are normal
+ - max: Largest finite value
  - num_nans: Number of NaN values
  - num_infs: Number of infinities (2 or 0)
 

docs/source/notebooks.rst

@@ -12,3 +12,4 @@ Some notebooks to illustrate uses of the library
    02-value-stats.ipynb
    03-value-tables.ipynb
    04-benchmark.ipynb
+   05-stochastic-rounding.ipynb

src/gfloat/round.py

@@ -88,40 +88,35 @@ def round_float(
         isignificand = math.floor(fsignificand)
         delta = fsignificand - isignificand
 
-        # fmt: off
-        if (
-            (rnd == RoundMode.TowardPositive and not sign and delta > 0)
-            or (rnd == RoundMode.TowardNegative and sign and delta > 0)
-            or (rnd == RoundMode.TiesToAway and delta >= 0.5)
-            or (rnd == RoundMode.TiesToEven and delta > 0.5)
-            or (rnd == RoundMode.TiesToEven and delta == 0.5 and _isodd(isignificand))
-            or (rnd == RoundMode.Stochastic and delta > (0.5 + srbits) * 2.0**-srnumbits)
-        ):
-            isignificand += 1
-
-        ## Special case for Precision=1, all-log format with zero.
-        #  The logic is simply duplicated (and isignificand overwritten) for clarity.
-        if fi.precision == 1:
-            isignificand = math.floor(fsignificand)
-            code_is_odd = isignificand != 0 and _isodd(expval + bias)
-            if (
-                (rnd == RoundMode.TowardPositive and not sign and delta > 0)
-                or (rnd == RoundMode.TowardNegative and sign and delta > 0)
-                or (rnd == RoundMode.TiesToAway and delta >= 0.5)
-                or (rnd == RoundMode.TiesToEven and delta > 0.5)
-                or (rnd == RoundMode.TiesToEven and delta == 0.5 and code_is_odd)
-                or (rnd == RoundMode.Stochastic and delta > (0.5 + srbits) * 2.0**-srnumbits)
-            ):
-                # Go to nextUp.
-                # Increment isignificand if zero,
-                # else increment exponent
+        code_is_odd = (
+            _isodd(isignificand)
+            if fi.precision > 1
+            else (isignificand != 0 and _isodd(expval + bias))
+        )
+
+        if rnd == RoundMode.TowardZero:
+            should_round_away = False
+        if rnd == RoundMode.TowardPositive:
+            should_round_away = not sign and delta > 0
+        if rnd == RoundMode.TowardNegative:
+            should_round_away = sign and delta > 0
+        if rnd == RoundMode.TiesToAway:
+            should_round_away = delta >= 0.5
+        if rnd == RoundMode.TiesToEven:
+            should_round_away = delta > 0.5 or (delta == 0.5 and code_is_odd)
+        if rnd == RoundMode.Stochastic:
+            should_round_away = delta > (0.5 + srbits) * 2.0**-srnumbits
+
+        if should_round_away:
+            if fi.precision > 1:
+                isignificand += 1
+            else:
+                # Increment isignificand if zero, else increment exponent
                 if isignificand == 0:
                     isignificand = 1
                 else:
                     assert isignificand == 1
                     expval += 1
-            ## End special case for Precision=1.
-        # fmt: on
 
         # Reconstruct rounded result to float
         result = isignificand * (2.0**expval)