Merge pull request #32 from graphcore-research/docs-cleanup

Various documentation improvements

Author: awf

README.md

@@ -10,7 +10,8 @@ handling various current and proposed floating point types:
  - [IEEE WG P3109](https://github.com/awf/P3109-Public/blob/main/Shared%20Reports/P3109%20WG%20Interim%20report.pdf): P{p} for p in 1..7
  - [OCP MX Formats](https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf): E2M1, M2M3, E3M2, E8M0, INT8, and the MX block formats.
 
-The library favours readability and extensibility over speed - for fast implementations of these datatypes see, for example, [ml_dtypes](https://github.com/jax-ml/ml_dtypes),
+The library favours readability and extensibility over speed (although the *_ndarray functions are reasonably fast for large arrays, see the [benchmarking  notebook](docs/source/04-benchmark.ipynb)).
+For other implementations of these datatypes more focused on speed see, for example, [ml_dtypes](https://github.com/jax-ml/ml_dtypes),
 [bitstring](https://github.com/scott-griffiths/bitstring),
 [MX PyTorch Emulation Library](https://github.com/microsoft/microxcaling).
 

docs/source/01-decode.ipynb

@@ -31,10 +31,96 @@ handling various current and proposed floating point types:
 
  - `IEEE 754 <https://en.wikipedia.org/wiki/IEEE_754>`_: Binary16, Binary32
  - `Brain floating point <https://en.wikipedia.org/wiki/Bfloat16_floating-point_format>`_: BFloat16
- - `OCP Float8 <https://www.opencompute.org/documents/ocp-8-bit-floating-point-specification-ofp8-revision-1-0-2023-06-20-pdf>`_: E5M2, E4M3
- - `IEEE WG P3109 <https://github.com/awf/P3109-Public/blob/main/Shared%20Reports/P3109%20WG%20Interim%20report.pdf>`_: P{p} for p in 1..7
- - Types from the `OCP MX <https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf>`_ spec: E8M0, INT8, and FP4, FP6 types
-
+ - |ocp_link|: E5M2, E4M3
+ - |p3109_link|: P{p} for p in 1..7
+ - Types from the |ocp_mx_link| spec: E8M0, INT8, and FP4, FP6 types
+
+As well as block formats from |ocp_mx_link|.
+
+.. |ocp_mx_link| raw:: html
+
+   <a href="https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf" target="_blank">
+     OCP MX
+   </a>
+
+.. |ocp_link| raw:: html
+
+   <a href="https://www.opencompute.org/documents/ocp-8-bit-floating-point-specification-ofp8-revision-1-0-2023-06-20-pdf" target="_blank">
+     OCP Float8
+   </a>
+
+.. |p3109_link| raw:: html
+
+    <a href="https://raw.githubusercontent.com/P3109/Public/main/Shared%20Reports/P3109%20WG%20Interim%20Report.pdf" target="_blank">
+      IEEE P3109
+    </a>
+
+Example
+-------
+This table (from example notebook :doc:`value-stats <02-value-stats>`) shows how
+gfloat has been used to tabulate properties of various floating point formats.
+
+ - name: Format
+ - B: Bits in the format
+ - 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
+ - num_nans: Number of NaN values
+ - num_infs: Number of infinities (2 or 0)
+
+========  ===  ===  ===  ===========  =================  ============  ===========  ======
+name        B    P    E  smallest     smallest_normal    max           num_nans       infs
+========  ===  ===  ===  ===========  =================  ============  ===========  ======
+ocp_e2m1    4    2    2  0.5          1                  6             0                 0
+ocp_e2m3    6    4    2  0.125        1                  7.5           0                 0
+ocp_e3m2    6    3    3  0.0625       0.25               28            0                 0
+ocp_e4m3    8    4    4  ≈0.0019531   0.015625           448           2                 0
+ocp_e5m2    8    3    5  ≈1.5259e-05  ≈6.1035e-05        57344         6                 2
+p3109_p1    8    1    7  ≈2.1684e-19  ≈2.1684e-19        ≈9.2234e+18   1                 2
+p3109_p2    8    2    6  ≈2.3283e-10  ≈4.6566e-10        ≈2.1475e+09   1                 2
+p3109_p3    8    3    5  ≈7.6294e-06  ≈3.0518e-05        49152         1                 2
+p3109_p4    8    4    4  ≈0.00097656  0.0078125          224           1                 2
+p3109_p5    8    5    3  0.0078125    0.125              15            1                 2
+p3109_p6    8    6    2  0.015625     0.5                3.875         1                 2
+binary16   16   11    5  ≈5.9605e-08  ≈6.1035e-05        65504         2046              2
+bfloat16   16    8    8  ≈9.1835e-41  ≈1.1755e-38        ≈3.3895e+38   254               2
+binary32   32   24    8  ≈1.4013e-45  ≈1.1755e-38        ≈3.4028e+38   ≈1.6777e+07       2
+binary64   64   53   11  4.9407e-324  ≈2.2251e-308       ≈1.7977e+308  ≈9.0072e+15       2
+ocp_e8m0    8    1    8  ≈5.8775e-39  ≈5.8775e-39        ≈1.7014e+38   1                 0
+ocp_int8    8    8    0  0.015625     n/a                ≈  1.9844     0                 0
+========  ===  ===  ===  ===========  =================  ============  ===========  ======
+
+In the above table, values which are not exact are indicated with the "≈" symbol.
+And here's the same table, but with values which don't render exactly as short floats
+printed as rationals times powers of 2:
+
+========  ===  ===  ===  ===========  =================  ========================================  ======================================  ======
+name        B    P    E  smallest     smallest_normal    max                                       num_nans                                  infs
+========  ===  ===  ===  ===========  =================  ========================================  ======================================  ======
+ocp_e2m1    4    2    2  0.5          1                  6                                         0                                            0
+ocp_e2m3    6    4    2  0.125        1                  7.5                                       0                                            0
+ocp_e3m2    6    3    3  0.0625       0.25               28                                        0                                            0
+ocp_e4m3    8    4    4  2^-9         0.015625           448                                       2                                            0
+ocp_e5m2    8    3    5  2^-16        2^-14              57344                                     6                                            2
+p3109_p1    8    1    7  2^-62        2^-62              2^63                                      1                                            2
+p3109_p2    8    2    6  2^-32        2^-31              2^31                                      1                                            2
+p3109_p3    8    3    5  2^-17        2^-15              49152                                     1                                            2
+p3109_p4    8    4    4  2^-10        0.0078125          224                                       1                                            2
+p3109_p5    8    5    3  0.0078125    0.125              15                                        1                                            2
+p3109_p6    8    6    2  0.015625     0.5                3.875                                     1                                            2
+binary16   16   11    5  2^-24        2^-14              65504                                     2046                                         2
+bfloat16   16    8    8  2^-133       2^-126             255/128*2^127                             254                                          2
+binary32   32   24    8  2^-149       2^-126             16777215/8388608*2^127                    8388607/4194304*2^23                         2
+binary64   64   53   11  4.9407e-324  2^-1022            9007199254740991/9007199254740992*2^1024  4503599627370495/4503599627370496*2^53       2
+ocp_e8m0    8    1    8  2^-127       2^-127             2^127                                     1                                            0
+ocp_int8    8    8    0  0.015625     n/a                127/64*2^0                                0                                            0
+========  ===  ===  ===  ===========  =================  ========================================  ======================================  ======
+
+
+See Also
+--------
 
 GFloat, being a pure Python library, favours readability and extensibility over speed
 (although the `*_ndarray` functions are reasonably fast for large arrays).
@@ -47,6 +133,9 @@ For fast implementations of these datatypes see, for example,
 To get started with the library, we recommend perusing the notebooks,
 otherwise you may wish to jump straight into the API.
 
+Contents
+========
+
 .. toctree::
    :hidden:
 

docs/source/02-value-stats.ipynb

@@ -1,12 +1,19 @@
 # Copyright (c) 2024 Graphcore Ltd. All rights reserved.
 
 import pandas
+from typing import Callable
 from IPython.display import HTML
 
 
-def pandas_render(df: pandas.DataFrame) -> HTML:
+def pandas_render(df: pandas.DataFrame, **kwargs) -> HTML:
     """
     Render a dataframe, hiding the index,
     and set ID to minimize diffs for notebook regression tests
     """
-    return HTML(df.style.hide().set_uuid("my_id").to_html())
+    s = df.style.hide().set_uuid("my_id")
+    for f, v in kwargs.items():
+        if isinstance(getattr(s, f, None), Callable):
+            s = getattr(s, f)(v)
+        else:
+            s = s.format(**{f: v})
+    return HTML(s.to_html())

docs/source/index.rst

@@ -6,6 +6,7 @@ jaxlib
 jax
 airium
 pandas
+matplotlib
 
 # Requirements for development
 pre-commit

docs/source/utils.py

@@ -212,13 +212,13 @@ def format_info_p3109(precision: int) -> FormatInfo:
 ]
 
 all_formats = [
-    format_info_ocp_e8m0,
-    format_info_ocp_int8,
     *_tiny_formats,
     *_fp8_formats,
     *_fp16_formats,
     format_info_binary32,
     format_info_binary64,
+    format_info_ocp_e8m0,
+    format_info_ocp_int8,
 ]
 
 # ------

requirements-dev.txt

@@ -21,16 +21,22 @@ def float_pow2str(v: float, min_exponent: float = -np.inf) -> str:
     if not np.isfinite(v):
         return str(v)
 
-    s = np.sign(v)
+    signstr = "-" if np.signbit(v) else ""
+
     x = np.abs(v)
-    e = np.floor(np.log2(x))
-    sig = x * 2.0**-e
+    e = int(np.floor(np.log2(x)))
+    sig = np.ldexp(x, -e)
     if e < min_exponent:
-        sig *= 2.0 ** (e - min_exponent)
-        e = min_exponent
+        sig = np.ldexp(sig, e - min_exponent)
+        e = int(min_exponent)
+
+    pow2str = f"2^{e:d}"
 
     significand = fractions.Fraction(sig)
-    return ("-" if s < 0 else "") + f"{significand}*2^{int(e):d}"
+    if significand == 1:
+        return signstr + pow2str
+    else:
+        return signstr + f"{significand}*{pow2str}"
 
 
 def float_tilde_unless_roundtrip_str(v: float, width: int = 14, d: int = 8) -> str: