Make all top-level pyrtl names canonical, and stop using submodule names.

This makes the documentation consistently use top-level names like
`pyrtl.WireVector`, instead of submodule-level names like
`pyrtl.wire.WireVector`. This also updates `examples` and `tests` to
consistently use the canonical top-level names.

Users should not be aware of pyrtl's submodule structure. For example, users
should not know or care that `mux` is a `corecircuit` and not a `helperfunc`.

Author: fdxmw

CHANGELOG.md

@@ -11,8 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - An optimization pass to [optimize inverter chains](https://github.com/UCSBarchlab/PyRTL/blob/d5f8dbe53f54e61e1d54722449e4894b885243c7/pyrtl/passes.py#L130)
-- `one_hot_to_binary` encoder ([documentation](https://pyrtl.readthedocs.io/en/latest/helpers.html#pyrtl.helperfuncs.one_hot_to_binary))
-- `binary_to_one_hot` decoder ([documentation](https://pyrtl.readthedocs.io/en/latest/helpers.html#pyrtl.helperfuncs.binary_to_one_hot))
+- `one_hot_to_binary` encoder ([documentation](https://pyrtl.readthedocs.io/en/latest/helpers.html#pyrtl.one_hot_to_binary))
+- `binary_to_one_hot` decoder ([documentation](https://pyrtl.readthedocs.io/en/latest/helpers.html#pyrtl.binary_to_one_hot))
 
 ### Changed
 
@@ -31,7 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Added an `initialize_registers` option to `output_to_verilog`
-  ([documentation](https://pyrtl.readthedocs.io/en/latest/export.html#pyrtl.importexport.output_to_verilog))
+  ([documentation](https://pyrtl.readthedocs.io/en/latest/export.html#pyrtl.output_to_verilog))
 
 ### Changed
 
@@ -46,8 +46,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Named `WireVector` slices with `wire_struct` and `wire_matrix`. See documentation:
-  - [wire_struct](https://pyrtl.readthedocs.io/en/latest/helpers.html#pyrtl.helperfuncs.wire_struct)
-  - [wire_matrix](https://pyrtl.readthedocs.io/en/latest/helpers.html#pyrtl.helperfuncs.wire_matrix)
+  - [wire_struct](https://pyrtl.readthedocs.io/en/latest/helpers.html#pyrtl.wire_struct)
+  - [wire_matrix](https://pyrtl.readthedocs.io/en/latest/helpers.html#pyrtl.wire_matrix)
 
 ### Changed
 

docs/analysis.rst

@@ -16,23 +16,23 @@ Estimation
 Optimization
 ------------
 
-.. autofunction:: pyrtl.passes.optimize
+.. autofunction:: pyrtl.optimize
 
 Synthesis
 ---------
 
-.. autofunction:: pyrtl.passes.synthesize
+.. autofunction:: pyrtl.synthesize
 
-.. autoclass:: pyrtl.core.PostSynthBlock
+.. autoclass:: pyrtl.PostSynthBlock
    :show-inheritance:
    :members:
 
 Individual Passes
 -----------------
 
-.. autofunction:: pyrtl.passes.common_subexp_elimination
-.. autofunction:: pyrtl.passes.constant_propagation
-.. autofunction:: pyrtl.passes.nand_synth
-.. autofunction:: pyrtl.passes.and_inverter_synth
-.. autofunction:: pyrtl.passes.one_bit_selects
-.. autofunction:: pyrtl.passes.two_way_concat
+.. autofunction:: pyrtl.common_subexp_elimination
+.. autofunction:: pyrtl.constant_propagation
+.. autofunction:: pyrtl.nand_synth
+.. autofunction:: pyrtl.and_inverter_synth
+.. autofunction:: pyrtl.one_bit_selects
+.. autofunction:: pyrtl.two_way_concat

docs/basic.rst

@@ -18,17 +18,17 @@ the design. :class:`.Const` is useful for specifying hard-wired values and
 :class:`.Register` is how sequential elements are created (they all have an
 implicit clock).
 
-.. inheritance-diagram:: pyrtl.wire.WireVector
-                         pyrtl.wire.Input
-                         pyrtl.wire.Output
-                         pyrtl.wire.Const
-                         pyrtl.wire.Register
+.. inheritance-diagram:: pyrtl.WireVector
+                         pyrtl.Input
+                         pyrtl.Output
+                         pyrtl.Const
+                         pyrtl.Register
     :parts: 1
 
 WireVector
 ----------
 
-.. autoclass:: pyrtl.wire.WireVector
+.. autoclass:: pyrtl.WireVector
     :members:
     :special-members: __init__, __add__, __sub__, __mul__, __getitem___,
                       __len__, __ilshift__, __and__, __or__, __xor__, __lt__,
@@ -37,21 +37,21 @@ WireVector
 Input Pins
 ----------
 
-.. autoclass:: pyrtl.wire.Input
+.. autoclass:: pyrtl.Input
     :members:
     :show-inheritance:
 
 Output Pins
 -----------
 
-.. autoclass:: pyrtl.wire.Output
+.. autoclass:: pyrtl.Output
     :members:
     :show-inheritance:
 
 Constants
 ---------
 
-.. autoclass:: pyrtl.wire.Const
+.. autoclass:: pyrtl.Const
     :members:
     :show-inheritance:
     :special-members: __init__

docs/blocks.rst

@@ -4,7 +4,7 @@ Block and Logic Nets
 Blocks
 ------
 
-.. autoclass:: pyrtl.core.Block
+.. autoclass:: pyrtl.Block
     :members:
     :exclude-members: sanity_check_memblock, sanity_check_memory_sync, sanity_check_net, sanity_check_wirevector
 
@@ -16,17 +16,17 @@ Blocks
 Most PyRTL operations operate on the global ``working_block`` by default. PyRTL
 provides several functions to inspect and manipulate the ``working_block``:
 
-.. autofunction:: pyrtl.core.working_block
+.. autofunction:: pyrtl.working_block
 
-.. autofunction:: pyrtl.core.reset_working_block
+.. autofunction:: pyrtl.reset_working_block
 
-.. autofunction:: pyrtl.core.set_working_block
+.. autofunction:: pyrtl.set_working_block
 
-.. autofunction:: pyrtl.core.temp_working_block
+.. autofunction:: pyrtl.temp_working_block
 
 LogicNets
 ---------
 
-.. autoclass:: pyrtl.core.LogicNet
+.. autoclass:: pyrtl.LogicNet
     :members:
     :undoc-members:

docs/export.rst

@@ -4,29 +4,29 @@ Exporting and Importing Designs
 Exporting Hardware Designs
 --------------------------
 
-.. autofunction:: pyrtl.importexport.output_to_verilog
+.. autofunction:: pyrtl.output_to_verilog
 
-.. autofunction:: pyrtl.importexport.output_to_firrtl
+.. autofunction:: pyrtl.output_to_firrtl
 
 Exporting Testbenches
 ---------------------
 
-.. autofunction:: pyrtl.importexport.output_verilog_testbench
+.. autofunction:: pyrtl.output_verilog_testbench
 
 Importing Verilog
 -----------------
 
-.. autofunction:: pyrtl.importexport.input_from_blif
-.. autofunction:: pyrtl.importexport.input_from_verilog
+.. autofunction:: pyrtl.input_from_blif
+.. autofunction:: pyrtl.input_from_verilog
 
 Outputting for Visualization
 ----------------------------
 
-.. autofunction:: pyrtl.visualization.output_to_trivialgraph
-.. autofunction:: pyrtl.visualization.output_to_graphviz
-.. autofunction:: pyrtl.visualization.graphviz_detailed_namer
-.. autofunction:: pyrtl.visualization.output_to_svg
-.. autofunction:: pyrtl.visualization.block_to_graphviz_string
-.. autofunction:: pyrtl.visualization.block_to_svg
-.. autofunction:: pyrtl.visualization.trace_to_html
-.. autofunction:: pyrtl.visualization.net_graph
+.. autofunction:: pyrtl.output_to_trivialgraph
+.. autofunction:: pyrtl.output_to_graphviz
+.. autofunction:: pyrtl.graphviz_detailed_namer
+.. autofunction:: pyrtl.output_to_svg
+.. autofunction:: pyrtl.block_to_graphviz_string
+.. autofunction:: pyrtl.block_to_svg
+.. autofunction:: pyrtl.trace_to_html
+.. autofunction:: pyrtl.net_graph

docs/helpers.rst

@@ -6,20 +6,19 @@ Cutting and Extending WireVectors
 
 The functions below provide ways of combining, slicing, and extending
 :class:`WireVectors<.WireVector>` in ways that are often useful in hardware
-design.  The functions below extend those member functions of the
+design. The functions below extend those member functions of the
 :class:`.WireVector` class itself (which provides support for the Python
 builtin :func:`len`, slicing e.g. ``wire[3:6]``,
-:meth:`~pyrtl.wire.WireVector.zero_extended`,
-:meth:`~pyrtl.wire.WireVector.sign_extended`, and many operators such as
-addition and multiplication).
-
-.. autofunction:: pyrtl.corecircuits.concat
-.. autofunction:: pyrtl.corecircuits.concat_list
-.. autofunction:: pyrtl.corecircuits.match_bitwidth
-.. autofunction:: pyrtl.helperfuncs.truncate
-.. autofunction:: pyrtl.helperfuncs.chop
-.. autofunction:: pyrtl.helperfuncs.wire_struct
-.. autofunction:: pyrtl.helperfuncs.wire_matrix
+:meth:`~.WireVector.zero_extended`, :meth:`~.WireVector.sign_extended`, and
+many operators such as addition and multiplication).
+
+.. autofunction:: pyrtl.concat
+.. autofunction:: pyrtl.concat_list
+.. autofunction:: pyrtl.match_bitwidth
+.. autofunction:: pyrtl.truncate
+.. autofunction:: pyrtl.chop
+.. autofunction:: pyrtl.wire_struct
+.. autofunction:: pyrtl.wire_matrix
 
 Coercion to WireVector
 ----------------------
@@ -32,19 +31,19 @@ hardware development.
 
 See :ref:`wirevector_coercion` for examples and more details.
 
-.. autofunction:: pyrtl.corecircuits.as_wires
+.. autofunction:: pyrtl.as_wires
 
 Control Flow Hardware
 ---------------------
 
-.. autofunction:: pyrtl.corecircuits.mux
-.. autofunction:: pyrtl.corecircuits.select
+.. autofunction:: pyrtl.mux
+.. autofunction:: pyrtl.select
 .. autoclass:: pyrtl.helperfuncs.MatchedFields
     :members:
     :undoc-members:
-.. autofunction:: pyrtl.helperfuncs.match_bitpattern
-.. autofunction:: pyrtl.corecircuits.bitfield_update
-.. autofunction:: pyrtl.corecircuits.bitfield_update_set
+.. autofunction:: pyrtl.match_bitpattern
+.. autofunction:: pyrtl.bitfield_update
+.. autofunction:: pyrtl.bitfield_update_set
 
 Interpreting Vectors of Bits
 ----------------------------
@@ -56,30 +55,30 @@ values into their corresponding bit vectors, can both be a bit of a pain.  The
 functions below do not create any hardware but rather help in the process of
 reasoning about bit vector representations of human understandable values.
 
-.. autofunction:: pyrtl.helperfuncs.val_to_signed_integer
+.. autofunction:: pyrtl.val_to_signed_integer
 .. autoclass:: pyrtl.helperfuncs.ValueBitwidthTuple
    :members: value, bitwidth
-.. autofunction:: pyrtl.helperfuncs.infer_val_and_bitwidth
-.. autofunction:: pyrtl.helperfuncs.val_to_formatted_str
-.. autofunction:: pyrtl.helperfuncs.formatted_str_to_val
-.. autofunction:: pyrtl.helperfuncs.log2
+.. autofunction:: pyrtl.infer_val_and_bitwidth
+.. autofunction:: pyrtl.val_to_formatted_str
+.. autofunction:: pyrtl.formatted_str_to_val
+.. autofunction:: pyrtl.log2
 
 Debugging
 ---------
 
-.. autofunction:: pyrtl.core.set_debug_mode
-.. autofunction:: pyrtl.helperfuncs.probe
-.. autofunction:: pyrtl.helperfuncs.rtl_assert
+.. autofunction:: pyrtl.set_debug_mode
+.. autofunction:: pyrtl.probe
+.. autofunction:: pyrtl.rtl_assert
 
 Reductions
 ----------
 
-.. autofunction:: pyrtl.corecircuits.and_all_bits
-.. autofunction:: pyrtl.corecircuits.or_all_bits
-.. autofunction:: pyrtl.corecircuits.xor_all_bits
-.. autofunction:: pyrtl.corecircuits.parity
-.. autofunction:: pyrtl.corecircuits.rtl_any
-.. autofunction:: pyrtl.corecircuits.rtl_all
+.. autofunction:: pyrtl.and_all_bits
+.. autofunction:: pyrtl.or_all_bits
+.. autofunction:: pyrtl.xor_all_bits
+.. autofunction:: pyrtl.parity
+.. autofunction:: pyrtl.rtl_any
+.. autofunction:: pyrtl.rtl_all
 
 .. _extended_logic_and_arithmetic:
 
@@ -92,20 +91,20 @@ design. The functions below extend those member functions of the
 :class:`.WireVector` class itself (which provides support for unsigned
 addition, subtraction, multiplication, comparison, and many others).
 
-.. autofunction:: pyrtl.corecircuits.signed_add
-.. autofunction:: pyrtl.corecircuits.signed_sub
-.. autofunction:: pyrtl.corecircuits.signed_mult
-.. autofunction:: pyrtl.corecircuits.signed_lt
-.. autofunction:: pyrtl.corecircuits.signed_le
-.. autofunction:: pyrtl.corecircuits.signed_gt
-.. autofunction:: pyrtl.corecircuits.signed_ge
-.. autofunction:: pyrtl.corecircuits.shift_left_logical
-.. autofunction:: pyrtl.corecircuits.shift_left_arithmetic
-.. autofunction:: pyrtl.corecircuits.shift_right_logical
-.. autofunction:: pyrtl.corecircuits.shift_right_arithmetic
+.. autofunction:: pyrtl.signed_add
+.. autofunction:: pyrtl.signed_sub
+.. autofunction:: pyrtl.signed_mult
+.. autofunction:: pyrtl.signed_lt
+.. autofunction:: pyrtl.signed_le
+.. autofunction:: pyrtl.signed_gt
+.. autofunction:: pyrtl.signed_ge
+.. autofunction:: pyrtl.shift_left_logical
+.. autofunction:: pyrtl.shift_left_arithmetic
+.. autofunction:: pyrtl.shift_right_logical
+.. autofunction:: pyrtl.shift_right_arithmetic
 
 Encoders and Decoders
 ---------------------
 
-.. autofunction:: pyrtl.helperfuncs.one_hot_to_binary
-.. autofunction:: pyrtl.helperfuncs.binary_to_one_hot
+.. autofunction:: pyrtl.one_hot_to_binary
+.. autofunction:: pyrtl.binary_to_one_hot

docs/index.rst

@@ -86,11 +86,11 @@ overloaded operations such as :meth:`~.WireVector.__add__` or
 derived from :class:`.WireVector`. Coupled with :class:`.MemBlock` (and
 :class:`.RomBlock`), this is all a user needs to create a functional hardware design.
 
-.. inheritance-diagram:: pyrtl.wire.WireVector
-                         pyrtl.wire.Input
-                         pyrtl.wire.Output
-                         pyrtl.wire.Const
-                         pyrtl.wire.Register
+.. inheritance-diagram:: pyrtl.WireVector
+                         pyrtl.Input
+                         pyrtl.Output
+                         pyrtl.Const
+                         pyrtl.Register
     :parts: 1
 
 After specifying a hardware design, there are then options to simulate your
@@ -141,10 +141,10 @@ internal invariants and assertions over the core logic graph which should never
 encountered when constructing designs in the normal ways. If you hit a confusing
 :class:`.PyrtlError` or any :class:`.PyrtlInternalError` feel free to file an issue.
 
-.. autoclass:: pyrtl.pyrtlexceptions.PyrtlError
+.. autoclass:: pyrtl.PyrtlError
     :members:
 
-.. autoclass:: pyrtl.pyrtlexceptions.PyrtlInternalError
+.. autoclass:: pyrtl.PyrtlInternalError
     :members:
 
 Reference Guide

docs/regmem.rst

@@ -4,22 +4,22 @@ Registers and Memories
 Registers
 ---------
 
-.. autoclass:: pyrtl.wire.Register
+.. autoclass:: pyrtl.Register
     :members:
     :show-inheritance:
     :special-members: __init__
 
 Memories
 --------
 
-.. autoclass:: pyrtl.memory.MemBlock
+.. autoclass:: pyrtl.MemBlock
     :members:
     :special-members: __init__, __getitem__, __setitem__
 
 ROMs
 ----
 
-.. autoclass:: pyrtl.memory.RomBlock
+.. autoclass:: pyrtl.RomBlock
     :members:
     :show-inheritance:
     :special-members: __init__, __getitem__