Doc

Author: awf

docs/source/api.rst

@@ -8,9 +8,9 @@ API
 Scalar Functions
 ----------------
 
-.. autofunction:: decode_float
 .. autofunction:: round_float
 .. autofunction:: encode_float
+.. autofunction:: decode_float
 
 Array Functions
 ---------------

docs/source/index.rst

@@ -17,21 +17,32 @@ of:
   * Precision (p)
   * Maximum exponent (emax)
 
-with additional fields defining the encoding of infinities, Not-a-number (NaN) values,
-and negative zero, among others (see :class:`gfloat.FormatInfo`.)
+with additional fields defining the presence/encoding of:
+
+  * Infinities
+  * Not-a-number (NaN) values
+  * Negative zero
+  * Subnormal numbers
+  * Signed/unsigned
+  * Two's complement encoding (of the significand)
 
 This allows an implementation of generic floating point encode/decode logic,
 handling various current and proposed floating point types:
 
  - `IEEE 754 <https://en.wikipedia.org/wiki/IEEE_754>`_: Binary16, Binary32
- - `OCP Float8 <https://www.opencompute.org/documents/ocp-8-bit-floating-point-specification-ofp8-revision-1-0-2023-06-20-pdf>`_: E5M2, E4M3, and MX formats
+ - `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
+
 
-The library favours readability and extensibility over speed - for fast
-implementations of these datatypes see, for example,
+GFloat, being a pure Python library, favours readability and extensibility over speed
+(although the `*_ndarray` functions are reasonably fast for large arrays).
+For fast implementations of these datatypes 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>`_.
+`MX PyTorch Emulation Library <https://github.com/microsoft/microxcaling>`_,
+`APyTypes <https://apytypes.github.io/apytypes>`_.
 
 To get started with the library, we recommend perusing the notebooks,
 otherwise you may wish to jump straight into the API.

src/gfloat/decode_ndarray.py

@@ -9,7 +9,7 @@ def decode_ndarray(
     fi: FormatInfo, codes: np.ndarray, np: ModuleType = np
 ) -> np.ndarray:
     r"""
-    Vectorized version of :function:`decode_float`
+    Vectorized version of :meth:`decode_float`
 
     Args:
       fi (FormatInfo): Floating point format descriptor.

src/gfloat/round_ndarray.py

@@ -18,7 +18,30 @@ def round_ndarray(
     np: ModuleType = np,
 ) -> np.ndarray:
     """
-    Vectorized version of round_float.
+    Vectorized version of :meth:`round_float`.
+
+    Round inputs to the given :py:class:`FormatInfo`, given rounding mode and
+    saturation flag
+
+    Input NaNs will convert to NaNs in the target, not necessarily preserving payload.
+    An input Infinity will convert to the largest float if :paramref:`sat`,
+    otherwise to an Inf, if present, otherwise to a NaN.
+    Negative zero will be returned if the format has negative zero, otherwise zero.
+
+    Args:
+      fi (FormatInfo): Describes the target format
+      v (float): Input value to be rounded
+      rnd (RoundMode): Rounding mode to use
+      sat (bool): Saturation flag: if True, round overflowed values to `fi.max`
+      np (Module): May be `numpy`, `jax.numpy` or another module cloning numpy
+
+    Returns:
+      An array of floats which is a subset of the format's value set.
+
+    Raises:
+       ValueError: The target format cannot represent an input
+             (e.g. converting a `NaN`, or an `Inf` when the target has no
+             `NaN` or `Inf`, and :paramref:`sat` is false)
     """
     p = fi.precision
     bias = fi.expBias
@@ -109,7 +132,22 @@ def round_ndarray(
 
 def encode_ndarray(fi: FormatInfo, v: np.ndarray) -> np.ndarray:
     """
-    Vectorized version of encode_float.
+    Vectorized version of :meth:`encode_float`.
+
+    Encode inputs to the given :py:class:`FormatInfo`.
+
+    Will round toward zero if :paramref:`v` is not in the value set.
+    Will saturate to `Inf`, `NaN`, `fi.max` in order of precedence.
+    Encode -0 to 0 if not `fi.has_nz`
+
+    For other roundings and saturations, call :func:`round_ndarray` first.
+
+    Args:
+      fi (FormatInfo): Describes the target format
+      v (float array): The value to be encoded.
+
+    Returns:
+      The integer code point
     """
     k = fi.bits
     p = fi.precision