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

@@ -34,3 +34,17 @@ LogicNets
 .. autoclass:: pyrtl.LogicNet
     :members:
     :undoc-members:
+
+GateGraphs
+----------
+
+.. automodule:: pyrtl.gate_graph
+
+.. autoclass:: pyrtl.Gate
+    :members:
+    :special-members: __init__, __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",