Initial implementation of GateGraph, an alternative PyRTL logic representation

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