Add doctest examples for floating point operations.

Author: fdxmw

pyrtl/rtllib/float/__init__.py

@@ -11,7 +11,7 @@
 """
 
 from .add_sub import add, sub
-from .mult import mult
+from .multiplication import mult
 from .types import BFloat16, Float16, Float32, Float64, RoundingMode
 from .utils import get_default_rounding_mode, set_default_rounding_mode
 

pyrtl/rtllib/float/add_sub.py

@@ -24,8 +24,59 @@ def add(
     Denormalized numbers are not supported. Denormalized numbers will be flushed to
     zero.
 
-    The return value's ``Float``type will match the operand ``Float`` type. For example,
-    if you ``add`` two :class:`~.Float16`, the result will be a :class:`~.Float16`.
+    The return value's ``Float`` type will match the operand ``Float`` type. For
+    example, if you ``add`` two :class:`~.Float16`, the result will be a
+    :class:`~.Float16`.
+
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    The following example computes ``1.0 + 2.0``. This is a bare-metal example, directly
+    manipulating the raw ``sign``, ``exponent``, and ``mantissa`` in IEEE 754 16-bit
+    floating point representation. See `IEEE 754 Internal Representation
+    <https://en.wikipedia.org/wiki/Floating-point_arithmetic#Internal_representation>`_
+    for more details::
+
+        >>> import pyrtl.rtllib.float as rtlfloat
+
+        >>> a = rtlfloat.Float16(name="a", component_type=pyrtl.Input)
+        >>> b = rtlfloat.Float16(name="b", component_type=pyrtl.Input)
+
+        >>> sum = rtlfloat.Float16(name="sum", Float16=None)
+        >>> sum <<= rtlfloat.add(a, b)
+
+        >>> # IEEE 754 numbers are stored as a sign bit, mantissa, and exponent. The
+        >>> # represented number's absolute value is 1.{mantissa} * 2 ** {exponent}
+        >>> #
+        >>> # All mantissas have this implied `1` before the binary point. {mantissa}
+        >>> # only stores the bits after this implied `1` and binary point.
+        >>> #
+        >>> # IEEE 754 exponents are stored with a bias to simplify comparisons. An
+        >>> # exponent {x} is stored as {x + exponent_bias}.
+        >>> exponent_bias = 2 ** (sum.exponent.bitwidth - 1) - 1
+
+        >>> # Create a=1.0, represented as 1.0 * 2 ** 0.
+        >>> a_one = {"a.sign": 0, "a.exponent": 0 + exponent_bias, "a.mantissa": 0}
+
+        >>> # Create b=2.0, represented as 1.0 * 2 ** 1.
+        >>> b_two = {"b.sign": 0, "b.exponent": 1 + exponent_bias, "b.mantissa": 0}
+
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step(a_one | b_two)
+
+        >>> # The sum should be 3.0, represented as 0b1.1 * 2 ** 1.
+        >>> # Note that this 0b1.1 is in binary! Multiplying by 2 is equivalent to
+        >>> # left-shifting by 1, and 0b1.1 << 1 == 0b11, which is 3 in decimal.
+        >>> sim.inspect("sum.sign")
+        0
+        >>> sim.inspect("sum.exponent") - exponent_bias
+        1
+        >>> bin(sim.inspect("sum.mantissa"))
+        '0b1000000000'
+        >>> bin(1 << (sum.mantissa.bitwidth - 1))
+        '0b1000000000'
 
     :param operand_a:
     :param operand_b:
@@ -100,6 +151,46 @@ def sub(
     example, if you ``sub`` two :class:`~.Float16`, the result will be a
     :class:`~.Float16`.
 
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    The following example computes ``1.0 - 2.0``. This is a bare-metal example, directly
+    manipulating the raw ``sign``, ``exponent``, and ``mantissa`` in IEEE 754 16-bit
+    floating point representation. See the documentation for :func:`add` and `IEEE 754
+    Internal Representation
+    <https://en.wikipedia.org/wiki/Floating-point_arithmetic#Internal_representation>`_
+    for more details::
+
+        >>> import pyrtl.rtllib.float as rtlfloat
+
+        >>> a = rtlfloat.Float16(name="a", component_type=pyrtl.Input)
+        >>> b = rtlfloat.Float16(name="b", component_type=pyrtl.Input)
+
+        >>> difference = rtlfloat.Float16(name="difference", Float16=None)
+        >>> difference <<= rtlfloat.sub(a, b)
+
+        >>> # See the `add` example for IEEE 754 representation background.
+        >>> exponent_bias = 2 ** (difference.exponent.bitwidth - 1) - 1
+
+        >>> # Create a=1.0, represented as 1.0 * 2 ** 0.
+        >>> a_one = {"a.sign": 0, "a.exponent": 0 + exponent_bias, "a.mantissa": 0}
+
+        >>> # Create b=2.0, represented as 1.0 * 2 ** 1.
+        >>> b_two = {"b.sign": 0, "b.exponent": 1 + exponent_bias, "b.mantissa": 0}
+
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step(a_one | b_two)
+
+        >>> # The difference should be -1.0, represented as -1.0 * 2 ** 0.
+        >>> sim.inspect("difference.sign")
+        1
+        >>> sim.inspect("difference.exponent") - exponent_bias
+        0
+        >>> sim.inspect("difference.mantissa")
+        0
+
     :param operand_a:
     :param operand_b:
     :param rounding_mode: Rounding mode, defaults to :attr:`~.RoundingMode.RNE`. The

pyrtl/rtllib/float/mult.py pyrtl/rtllib/float/multiplication.pypyrtl/rtllib/float/mult.py renamed to pyrtl/rtllib/float/multiplication.py

@@ -1,3 +1,11 @@
+# This file should be named `mult.py` for symmetry with `add_sub.py`, but is instead
+# named `multiplication.py` so the module has a name.
+
+# `__init__.py` creates `pyrtl.rtllib.float.mult`, collides with this module's name, if
+# this file were named `mult.py`.
+#
+# This module currently needs to be named to run its `doctest`s.
+
 import pyrtl
 from pyrtl.rtllib.float.types import FloatType, RoundingMode
 from pyrtl.rtllib.float.utils import (
@@ -27,6 +35,46 @@ def mult(
     example, if you ``mult`` two :class:`~.Float16`, the result will be a
     :class:`~.Float16`.
 
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    The following example computes ``2.0 * 4.0``. This is a bare-metal example, directly
+    manipulating the raw ``sign``, ``exponent``, and ``mantissa`` in IEEE 754 16-bit
+    floating point representation. See the documentation for :func:`add` and `IEEE 754
+    Internal Representation
+    <https://en.wikipedia.org/wiki/Floating-point_arithmetic#Internal_representation>`_
+    for more details::
+
+        >>> import pyrtl.rtllib.float as rtlfloat
+
+        >>> a = rtlfloat.Float16(name="a", component_type=pyrtl.Input)
+        >>> b = rtlfloat.Float16(name="b", component_type=pyrtl.Input)
+
+        >>> product = rtlfloat.Float16(name="product", Float16=None)
+        >>> product <<= rtlfloat.mult(a, b)
+
+        >>> # See the `add` example for IEEE 754 representation background.
+        >>> exponent_bias = 2 ** (product.exponent.bitwidth - 1) - 1
+
+        >>> # Create a=2.0, represented as 1.0 * 2 ** 1.
+        >>> a_two = {"a.sign": 0, "a.exponent": 1 + exponent_bias, "a.mantissa": 0}
+
+        >>> # Create b=4.0, represented as 1.0 * 2 ** 2.
+        >>> b_four = {"b.sign": 0, "b.exponent": 2 + exponent_bias, "b.mantissa": 0}
+
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step(a_two | b_four)
+
+        >>> # The product should be 8.0, represented as 1.0 * 2 ** 3.
+        >>> sim.inspect("product.sign")
+        0
+        >>> sim.inspect("product.exponent") - exponent_bias
+        3
+        >>> sim.inspect("product.mantissa")
+        0
+
     :param operand_a:
     :param operand_b:
     :param rounding_mode: Rounding mode, defaults to :attr:`~.RoundingMode.RNE`. The

tests/rtllib/test_float.py

@@ -1,3 +1,4 @@
+import doctest
 import unittest
 
 import pyrtl
@@ -24,6 +25,20 @@
 FLOAT16_DENORMALIZED = 0x0001  # Smallest denormalized number
 
 
+class TestDocTests(unittest.TestCase):
+    """Test documentation examples."""
+
+    def test_add_sub_doctests(self):
+        failures, tests = doctest.testmod(m=rtlfloat.add_sub)
+        self.assertGreater(tests, 0)
+        self.assertEqual(failures, 0)
+
+    def test_mult_doctests(self):
+        failures, tests = doctest.testmod(m=rtlfloat.multiplication)
+        self.assertGreater(tests, 0)
+        self.assertEqual(failures, 0)
+
+
 def float16_parts(sign, exp, mant):
     """Construct Float16 from sign, exponent, and mantissa."""
     assert sign in (0, 1), f"sign must be 0 or 1, got {sign}"