Initial implementation of GateGraph, an alternative PyRTL logic representation (#470)

* Initial implementation of `GateGraph`, an alternative PyRTL logic representation:

`GateGraph` attempts to address several issues with PyRTL's standard
`WireVector` and `LogicNet` representation:

1. A `GateGraph` can be directly traversed, without the help of side data
   structures like the `wire_src_dict` and `wire_sink_dict` returned by
   `net_connections`.

2. `GateGraph` builds a graph where each node is a `Gate`, and the edges are
   all references to other `Gates`. By using only one node type, rather than
   two (`WireVector`, `LogicNet`), it becomes easier to work with the nodes in
   a `GateGraph`, because every node is the same type, with the same interface.

3. `GateGraph` decouples the user interface and the internal representation.
   Users directly instantiate `WireVectors` as they build circuits. A user that
   is only building circuits should never interact with a `GateGraph` or a
   `Gate`. Users should only interact with `GateGraph` when they need
   reflection, which typically happens when writing an analysis or optimization
   pass.

   Another advantage of this decoupling is that `Gate` does not need to support
   `WireVector`'s quality-of-life features for users, like inferring bitwidth
   from assignment.

Author: fdxmw

docs/blocks.rst

@@ -1,9 +1,13 @@
 Block and Logic Nets
 =====================
 
-:class:`.Block` and :class:`.LogicNet` are lower level PyRTL abstractions. Most
-users won't need to understand them, unless they are implementing
-:ref:`analysis_and_optimization` passes or modifying PyRTL itself.
+:class:`.Block` and :class:`.LogicNet` are lower level PyRTL abstractions for
+representing a hardware design. Most users won't need to understand them,
+unless they are implementing :ref:`analysis_and_optimization` passes or
+modifying PyRTL itself.
+
+:ref:`gate_graphs` are an alternative representation that makes it easier to
+write analysis passes.
 
 Blocks
 ------
@@ -34,3 +38,19 @@ LogicNets
 .. autoclass:: pyrtl.LogicNet
     :members:
     :undoc-members:
+
+.. _gate_graphs:
+
+GateGraphs
+----------
+
+.. automodule:: pyrtl.gate_graph
+
+.. autoclass:: pyrtl.Gate
+    :members:
+    :special-members: __str__
+
+.. autoclass:: pyrtl.GateGraph
+    :members:
+    :special-members: __init__, __str__
+

pyrtl/__init__.py

@@ -19,6 +19,8 @@
 # convenience classes for building hardware
 from .wire import WireVector, Input, Output, Const, Register
 
+from .gate_graph import GateGraph, Gate
+
 # helper functions
 from .helperfuncs import (
     input_list,
@@ -160,6 +162,9 @@
     "Output",
     "Const",
     "Register",
+    # gate_graph
+    "GateGraph",
+    "Gate",
     # helperfuncs
     "input_list",
     "output_list",

pyrtl/core.py

@@ -581,6 +581,10 @@ def net_connections(
         This information helps when building a graph representation for the ``Block``.
         See :func:`net_graph` for an example.
 
+        .. note::
+
+            Consider using :ref:`gate_graphs` instead.
+
         :param include_virtual_nodes: If ``True``, external `sources` (such as an
             :class:`Inputs<Input>` and :class:`Consts<Const>`) will be represented as
             wires that set themselves, and external `sinks` (such as