Update Memory and Simulation documentation. Lots of improvements:

Memory:
* Add `MemBlock` and `RomBlock` doctest examples.
* Rename `MemBlock` and `RomBlock`'s `__getitem__`` and ``__setitem__`` args to
  improve readability and documentation.
* Convert `EnabledWrite` from `namedtuple` to `NamedTuple` so we can document
  the fields and their types.
* Move some `MemBlock` documentation from constructor to class.

Simulation:
* Replace `FastSimulation` and `CompiledSimulation`'s copy-and-pasted
  docstrings with references to `Simulation`'s docstrings.
* Add a note on how `FastSimulation` can sometimes be a better choice than
  `CompiledSimulation`.
* Add documentation for `Simulation.tracer` and `SimulationTrace.trace`.
* Enable doctests for `simulation.py`.
* Do not display documentation for `CompiledSimulation.run`,
  `SimulationTrace.add_step`, or `SimulationTrace.add_fast_step`, which are
  implementation details.
* Move `enum_name` documentation to the `SimulationTrace` section.

Also:
* Add some documentation on `doctest` to `docs/README.md`.
* Add links to `conditional_assignment`, `working_block`
* In example blocks, the copy button no longer copies the sample output.

Author: fdxmw

docs/README.md

@@ -15,21 +15,42 @@ The main Sphinx configuration file is
 
 Most of PyRTL's documentation is automatically extracted from Python
 docstrings, see [docstring
-formating](https://www.sphinx-doc.org/en/master/usage/domains/python.html)
-for supported directives and fields. Sphinx parses [Python type
+formating](https://www.sphinx-doc.org/en/master/usage/domains/python.html) for
+supported directives and fields. Sphinx parses [Python type
 annotations](https://docs.python.org/3/library/typing.html), so put type
-information into annotations instead of docstrings.
+information in annotations instead of docstrings.
 
 Follow the instructions on this page to build a local copy of PyRTL's
 documentation. This is useful for verifying that PyRTL's documentation still
 renders correctly after making a local change.
 
-There is additional PyRTL documentation in the
-[`gh-pages` branch](https://github.com/UCSBarchlab/PyRTL/tree/gh-pages).
-This additional documentation is pushed to https://ucsbarchlab.github.io/PyRTL/
-by the `pages-build-deployment` GitHub Action. The additional documentation is
-written in [GitHub MarkDown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax),
-and is not described further in this README.
+There is additional PyRTL documentation in the [`gh-pages`
+branch](https://github.com/UCSBarchlab/PyRTL/tree/gh-pages). This additional
+documentation is pushed to https://ucsbarchlab.github.io/PyRTL/ by the
+`pages-build-deployment` GitHub Action. This additional documentation is
+written HTML and is not described further in this README.
+
+## Testing Documentation Examples
+
+PyRTL's documentation contains many examples that are tested with
+[`doctest`](https://docs.python.org/3/library/doctest.html). It is important to
+test these examples so we can be sure that they keep working as we change the
+code. These tests run via test fixtures called `TestDocTest`, see the example
+in
+[`test_core.py`](https://github.com/UCSBarchlab/PyRTL/blob/development/tests/test_core.py).
+
+When adding a new `doctest`, you'll need to to add a preceding comment block
+that imports PyRTL and resets the working block before running your new
+`doctest`. This comment block contains additional code necessary for `doctest`
+to successfully run the test, but the lines are commented out because they are
+not worth showing in every example. These blocks look like:
+
+```
+..
+    # For ``doctest``.
+    >>> import pyrtl
+    >>> pyrtl.reset_working_block()
+```
 
 ## Installing Sphinx
 

docs/basic.rst

@@ -56,8 +56,10 @@ Constants
     :show-inheritance:
     :special-members: __init__
 
-Conditionals
-------------
+.. _conditional_assignment:
+
+Conditional Assignment
+----------------------
 
 .. automodule:: pyrtl.conditional
    :members:

docs/blocks.rst

@@ -8,6 +8,7 @@ Blocks
     :members:
     :exclude-members: sanity_check_memblock, sanity_check_memory_sync, sanity_check_net, sanity_check_wirevector
 
+.. _working_block:
 
 ``working_block``
 ^^^^^^^^^^^^^^^^^

docs/conf.py

@@ -71,3 +71,6 @@
 inheritance_graph_attrs = {
     'bgcolor': 'aliceblue',
 }
+
+# The copy button excludes line numbers, prompts, and outputs.
+copybutton_exclude = '.linenos, .gp, .go'

docs/requirements.txt

@@ -28,7 +28,7 @@ markupsafe==3.0.2
     # via jinja2
 packaging==25.0
     # via sphinx
-pygments==2.19.1
+pygments==2.19.2
     # via
     #   furo
     #   sphinx

docs/simtest.rst

@@ -21,13 +21,17 @@ Compiled (JIT to C) Simulation
 .. autoclass:: pyrtl.compilesim.CompiledSimulation
     :members:
     :special-members: __init__
+    :exclude-members: run
 
 Simulation Trace
 ----------------
 
 .. autoclass:: pyrtl.simulation.SimulationTrace
     :members:
     :special-members: __init__
+    :exclude-members: add_fast_step, add_step
+
+.. autofunction:: pyrtl.simulation.enum_name
 
 Wave Renderer
 -------------
@@ -36,7 +40,7 @@ Wave Renderer
     :members:
     :special-members: __init__
     :exclude-members: render_ruler_segment, render_val, val_to_str
-.. autofunction:: pyrtl.simulation.enum_name
+.. autoclass:: pyrtl.simulation.RendererConstants
 .. autoclass:: pyrtl.simulation.PowerlineRendererConstants
     :show-inheritance:
 .. autoclass:: pyrtl.simulation.Utf8RendererConstants

pyrtl/analysis.py

@@ -147,7 +147,8 @@ class TimingAnalysis:
     def __init__(self, block=None, gate_delay_funcs=None):
         """ Calculates timing delays in the block.
 
-        :param Block block: PyRTL block to analyze
+        :param Block block: PyRTL block to analyze. Defaults to the
+            :ref:`working_block`.
         :param gate_delay_funcs: a map with keys corresponding to the gate op and
             a function returning the delay as the value.
             It takes the gate as an argument.
@@ -449,7 +450,7 @@ def paths(src=None, dst=None, dst_nets=None, block=None):
     :param dict[WireVector, LogicNet] dst_nets: map from wire to set of nets where the
         wire is an argument; will compute it internally if not given via a
         call to pyrtl.net_connections()
-    :param Block block: block to use (defaults to working block)
+    :param Block block: block to use (defaults to :ref:`working_block`)
     :return: a map of the form `{src_wire: {dst_wire: [path]}}` for each `src_wire` in `src`
         (or all inputs if `src` is None), `dst_wire` in `dst` (or all outputs if `dst` is None),
         where `path` is a list of nets. This map is also an instance of :py:class:`.PathsResult`,
@@ -552,7 +553,7 @@ def distance(src, dst, f, block=None):
     :param Callable[[LogicNet], int] f: function from a net to number,
         representing the 'value' of a net that you want to sum
         across all nets in the path
-    :param Block block: block to use (defaults to working block)
+    :param Block block: block to use (defaults to :ref:`working_block`)
     :return: a map from each path (a tuple) to its calculated distance
 
     This calls the given function `f` on each net in a path, summing the result.

pyrtl/compilesim.py

@@ -14,7 +14,7 @@
 from pyrtl.wire import Input, Output, Const, WireVector, Register
 from pyrtl.memory import MemBlock, RomBlock
 from pyrtl.pyrtlexceptions import PyrtlError, PyrtlInternalError
-from pyrtl.simulation import SimulationTrace, _trace_sort_key
+from pyrtl.simulation import Simulation, SimulationTrace, _trace_sort_key
 from pyrtl.helperfuncs import infer_val_and_bitwidth
 
 
@@ -53,48 +53,45 @@ def __eq__(self, other):
 
 
 class CompiledSimulation:
-    """Simulate a block, compiling to C for efficiency.
-
-    This module provides significant speed improvements over
-    :class:`.FastSimulation`, at the cost of somewhat longer setup time.
-    Generally this will do better than :class:`.FastSimulation` for simulations
-    requiring over 1000 steps.  It is not built to be a debugging tool, though
-    it may help with debugging.  Note that only :class:`.Input` and
-    :class:`.Output` wires can be traced using CompiledSimulation.  This code
-    is still experimental, but has been used on designs of significant scale to
-    good effect.
-
-    In order to use this, you need:
-        - A 64-bit processor
-        - GCC (tested on version 4.8.4)
-        - A 64-bit build of Python
+    """Simulate a block by generating, compiling, and running C code.
+
+    ``CompiledSimulation`` provides significant execution speed improvements over
+    :class:`.FastSimulation`, at the cost of even longer start-up time. Generally this
+    will do better than :class:`.FastSimulation` for simulations requiring over 1000
+    steps.
+
+    ``CompiledSimulation`` is not built to be a debugging tool, though it may help with
+    debugging. Note that only :class:`.Input` and :class:`.Output` wires can be traced
+    with ``CompiledSimulation``.
+
+    .. note::
+        For very large circuits, :class:`.FastSimulation` can sometimes be a better
+        choice than ``CompiledSimulation`` because ``CompiledSimulation`` will generate
+        an extremely large ``.c`` file, which can take prohibitively long to compile and
+        optimize. :class:`.FastSimulation` will generate an extremely large ``.py``
+        file, but Python will interpret that generated code as needed, instead of trying
+        to process all the generated code at once.
+
+    .. WARNING::
+        This code is still experimental, but has been used on designs of significant
+        scale to good effect.
+
+    To use ``CompiledSimulation``, you'll need:
+
+    - A 64-bit processor
+    - GCC (tested on version 4.8.4)
+    - A 64-bit build of Python
 
     If using the multiplication operand, only some architectures are supported:
-        - x86-64 / amd64
-        - arm64 / aarch64
-        - mips64 (untested)
-
-    ``default_value`` is currently only implemented for registers, not memories.
-
-    A Simulation step works as follows:
-
-    1. Registers are updated:
-        1. (If this is the first step) With the default values passed in
-           to the Simulation during instantiation and/or any reset values
-           specified in the individual registers.
-        2. (Otherwise) With their next values calculated in the previous step
-           (``r`` logic nets).
-    2. The new values of these registers as well as the values of block inputs
-       are propagated through the combinational logic.
-    3. Memory writes are performed (``@`` logic nets).
-    4. The current values of all wires are recorded in the trace.
-    5. The next values for the registers are saved, ready to be applied at the
-       beginning of the next step.
-
-    Note that the register values saved in the trace after each simulation step
-    are from *before* the register has latched in its newly calculated values,
-    since that latching in occurs at the beginning of the *next* step.
 
+    - x86-64 / amd64
+    - arm64 / aarch64
+    - mips64 (untested)
+
+    ``default_value`` is currently only implemented for :class:`Registers<.Register>`,
+    not :class:`MemBlocks<.MemBlock>`.
+
+    See :class:`.Simulation` for an overview of PyRTL simulations.
     """
 
     def __init__(
@@ -131,12 +128,17 @@ def __init__(
         self._create_dll()
         self._initialize_mems()
 
+    # Use Simulation.__init__'s docstring as CompiledSimulation.__init__'s docstring.
+    __init__.__doc__ = Simulation.__init__.__doc__
+
     def inspect_mem(self, mem: MemBlock) -> dict[int, int]:
-        """Get a view into the contents of a MemBlock."""
         return DllMemInspector(self, mem)
 
+    # Use Simulation.inspect_mem's docstring as CompiledSimulation.inspect_mem's
+    # docstring.
+    inspect_mem.__doc__ = Simulation.inspect_mem.__doc__
+
     def inspect(self, w: str) -> int:
-        """Get the latest value of the wire given, if possible."""
         if isinstance(w, WireVector):
             w = w.name
         try:
@@ -149,23 +151,10 @@ def inspect(self, w: str) -> int:
             return vals[-1]
         raise PyrtlError('CompiledSimulation does not support inspecting internal WireVectors')
 
-    def step(self, provided_inputs: dict[str, int] = {}, inputs=None):
-        """Run one step of the simulation.
-
-        :param provided_inputs: A mapping from input names to the values for
-            the step.
-
-        A step causes the block to be updated as follows, in order:
-
-        1. Registers are updated with their :attr:`~.Register.next` values
-           computed in the previous cycle
-        2. Block inputs and these new register values propagate through the
-           combinational logic
-        3. Memories are updated
-        4. The :attr:`~.Register.next` values of the registers are saved for
-           use in step 1 of the next cycle.
+    # Use Simulation.inspect's docstring as CompiledSimulation.inspect's docstring.
+    inspect.__doc__ = Simulation.inspect.__doc__
 
-        """
+    def step(self, provided_inputs: dict[str, int] = {}, inputs=None):
         if inputs is not None:
             import warnings
             warnings.warn(
@@ -174,65 +163,13 @@ def step(self, provided_inputs: dict[str, int] = {}, inputs=None):
             provided_inputs = inputs
         self.run([provided_inputs])
 
+    # Use Simulation.step's docstring as CompiledSimulation.step's docstring.
+    step.__doc__ = Simulation.step.__doc__
+
     def step_multiple(self, provided_inputs: dict[str, list[int]] = {},
                       expected_outputs: dict[str, int] = {},
                       nsteps: int = None, file=sys.stdout,
                       stop_after_first_error: bool = False):
-        """Take the simulation forward N cycles, where N is the number of values
-         for each provided input.
-
-        :param provided_inputs: a dictionary mapping wirevectors to their values for N steps
-        :param expected_outputs: a dictionary mapping wirevectors to their expected values
-            for N steps; use ``?`` to indicate you don't care what the value at that step is
-        :param nsteps: number of steps to take (defaults to None, meaning step for each
-            supplied input value)
-        :param file: where to write the output (if there are unexpected outputs detected)
-        :param stop_after_first_error: a boolean flag indicating whether to stop the simulation
-            after the step where the first errors are encountered (defaults to False)
-
-        All input wires must be in the `provided_inputs` in order for the simulation
-        to accept these values. Additionally, the length of the array of provided values for each
-        input must be the same.
-
-        When `nsteps` is specified, then it must be *less than or equal* to the number of values
-        supplied for each input when `provided_inputs` is non-empty. When `provided_inputs` is
-        empty (which may be a legitimate case for a design that takes no inputs), then `nsteps`
-        will be used.  When `nsteps` is not specified, then the simulation will take the number
-        of steps equal to the number of values supplied for each input.
-
-        Example: if we have inputs named ``a`` and ``b`` and output ``o``, we can call::
-
-            sim.step_multiple({'a': [0,1], 'b': [23,32]}, {'o': [42, 43]})
-
-        to simulate 2 cycles, where in the first cycle ``a`` and ``b`` take on
-        0 and 23, respectively, and ``o`` is expected to have the value 42, and
-        in the second cycle ``a`` and ``b`` take on 1 and 32, respectively, and
-        ``o`` is expected to have the value 43.
-
-        If your values are all single digit, you can also specify them in a single string, e.g.::
-
-            sim.step_multiple({'a': '01', 'b': '01'})
-
-        will simulate 2 cycles, with ``a`` and ``b`` taking on
-        0 and 0, respectively, on the first cycle and 1 and 1, respectively, on the second
-        cycle.
-
-        Example: if the design had no inputs, like so::
-
-            a = pyrtl.Register(8)
-            b = pyrtl.Output(8, 'b')
-
-            a.next <<= a + 1
-            b <<= a
-
-            sim = pyrtl.Simulation()
-            sim.step_multiple(nsteps=3)
-
-        Using ``sim.step_multiple(nsteps=3)`` simulates 3 cycles, after which
-        we would expect the value of ``b`` to be 2.
-
-        """
-
         if not nsteps and len(provided_inputs) == 0:
             raise PyrtlError('need to supply either input values or a number of steps to simulate')
 
@@ -297,11 +234,18 @@ def _sort_tuple(t):
                 file.write("{0:>5} {1:>10} {2:>8} {3:>8}\n".format(step, name, expected, actual))
             file.flush()
 
+    # Use Simulation.step_multiple's docstring as CompiledSimulation.step_multiple's
+    # docstring.
+    step_multiple.__doc__ = Simulation.step_multiple.__doc__
+
     def run(self, inputs: list[dict[str, int]]):
-        """ Run many steps of the simulation.
+        """Run many steps of the ``CompiledSimulation``.
+
+        :meth:`CompiledSimulation.step` and :meth:`CompiledSimulation.step_multiple` are
+        wrappers around this lower-level method.
 
-        :param inputs: A list of input mappings for each step;
-            its length is the number of steps to be executed.
+        :param inputs: A list of input mappings for each step; its length is the number
+            of steps to be executed.
         """
         steps = len(inputs)
         # create i/o arrays of the appropriate length