Add a to_ipynb.py script that converts a PyRTL example script to a Jupyter notebook. This change also updates all Jupyter notebooks in ipynb-examples.

This change also deletes the incomplete `example9-transforms-draft.py`.

The updated Jupyter notebooks were tested in Jupyter Lite.

Author: fdxmw

.gitignore

@@ -53,4 +53,8 @@ ipynb-examples/.ipynb_checkpoints
 .vscode
 
 # Python venv
-pyvenv.cfg
+pyvenv.cfg
+
+# Jupyter
+.jupyterlite.doit.db
+_output

examples/Makefile

@@ -0,0 +1,9 @@
+PYTHON=python
+PY_FILES=$(wildcard *.py)
+IPYNB_FILES=$(addprefix ../ipynb-examples/, $(PY_FILES:.py=.ipynb))
+
+all: $(IPYNB_FILES)
+
+# Convert a PyRTL example Python script to a Jupyter notebook.
+../ipynb-examples/%.ipynb: %.py tools/to_ipynb.py
+	$(PYTHON) tools/to_ipynb.py $< $@

examples/README.md

@@ -0,0 +1,12 @@
+# PyRTL's Examples
+
+PyRTL's examples are Python scripts that demonstrate various PyRTL features.
+These scripts can be run with `python $SCRIPT_FILE_NAME`.
+
+Each script is converted to an equivalent Jupyter notebook in the
+`ipynb-examples` directory. These conversions are done by the `to_ipynb.py`
+script in the `examples/tools` directory.
+
+If you update an example script, be sure to update its corresponding Jupyter
+notebook. These updates are handled by the `Makefile` in this directory, so all
+Jupyter notebooks can be updated by running `make`.

examples/example0-minimum-viable-hardware.py

@@ -1,16 +1,23 @@
+# # A simple combinational logic example.
+#
+# Create an 8-bit adder that adds `a` and `b`. Check if the sum is greater than `5`.
 import pyrtl
 
-# "pin" input/outputs
-a = pyrtl.Input(8, "a")
-b = pyrtl.Input(8, "b")
-q = pyrtl.Output(8, "q")
-gt5 = pyrtl.Output(1, "gt5")
+# Define `Inputs` and `Outputs`.
+a = pyrtl.Input(bitwidth=8, name="a")
+b = pyrtl.Input(bitwidth=8, name="b")
 
-sum = a + b  # makes an 8-bit adder
-q <<= sum  # assigns output of adder to out pin
-gt5 <<= sum > 5  # does a comparison, assigns that to different pin
+q = pyrtl.Output(bitwidth=8, name="q")
+gt5 = pyrtl.Output(bitwidth=1, name="gt5")
 
-# the simulation and waveform output
+# Define the logic that connects the `Inputs` to the `Outputs`.
+sum = a + b  # Makes an 8-bit adder.
+q <<= sum  # Connects the adder's output to the `q` output pin.
+gt5 <<= sum > 5  # Does a comparison and connects the result to the `gt5` output pin.
+
+# Simulate various values for `a` and `b` over 5 cycles.
 sim = pyrtl.Simulation()
 sim.step_multiple({"a": [0, 1, 2, 3, 4], "b": [2, 2, 3, 3, 4]})
+
+# Display simulation traces as waveforms.
 sim.tracer.render_trace()

examples/example1-combologic.py

@@ -1,118 +1,110 @@
-"""
-Example 1: A simple combination logic block example.
-
-This example declares a block of hardware with three one-bit inputs, (a,b,c) and two
-one-bit outputs (sum, cout). The logic declared is a simple one-bit adder and the
-definition uses some of the most common parts of PyRTL. The adder is then simulated on
-random data, the wave form is printed to the screen, and the resulting trace is compared
-to a "correct" addition. If the result is correct then a 0 is returned, else 1.
-"""
-
+# # Example 1: A simple combination logic block example.
+#
+# This example declares a block of hardware with three one-bit inputs, (`a`,`b`,`c`) and
+# two one-bit outputs (`sum`, `cout`). The logic declared is a simple one-bit adder and
+# the definition uses some of the most common parts of PyRTL. The adder is then
+# simulated on random data, the wave form is printed to the screen, and the resulting
+# trace is compared to a "correct" addition.
 import random
 
 import pyrtl
 
-# The basic idea of PyRTL is to specify the component of a some hardware block through
-# the declaration of wires and operations on those wires. The current working block, an
-# instance of a class devilishly named "Block", is implicit in all of the below code --
-# it is easiest to start with the way wires work.
-
-# --- Step 1: Define Logic -------------------------------------------------
-
-# One of the most fundamental types in PyRTL is the "WireVector" which acts very much
+# The basic idea of PyRTL is to specify a hardware block by defining wires and the
+# operations performed on those wires. The current working block, an instance of a class
+# devilishly named `Block`, is implicit in all of the code below -- it is easiest to
+# start with the way wires work.
+#
+# ## Step 1: Define Logic
+#
+# One of the most fundamental types in PyRTL is the `WireVector` which acts very much
 # like a Python list of 1-bit wires. Unlike a normal list, though, the number of bits is
 # explicitly declared.
 temp1 = pyrtl.WireVector(bitwidth=1, name="temp1")
 
-# Both arguments are in fact optional and default to a bitwidth of 1 and a unique name
-# generated by PyRTL starting with 'tmp'
+# Both arguments are optional and default to a `bitwidth` of 1 and a unique `name`
+# generated by PyRTL that starts with `tmp`.
 temp2 = pyrtl.WireVector()
 
-# Two special types of WireVectors are Input and Output, which are used to specify an
+# `Input` and `Output` are two special types of `WireVectors`, which specify the
 # interface to the hardware block.
-a, b, c = pyrtl.Input(1, "a"), pyrtl.Input(1, "b"), pyrtl.Input(1, "c")
-sum, carry_out = pyrtl.Output(1, "sum"), pyrtl.Output(1, "carry_out")
+a = pyrtl.Input(1, "a")
+b = pyrtl.Input(1, "b")
+c = pyrtl.Input(1, "c")
+
+sum = pyrtl.Output(1, "sum")
+carry_out = pyrtl.Output(1, "carry_out")
 
 # Okay, let's build a one-bit adder. To do this we need to use the assignment operator,
-# which is '<<='. This takes an already declared wire and "connects" it to some other
-# already declared wire. Let's start with the sum bit, which is of course just the xor
-# of the three inputs
+# which is `<<=`. This takes an already declared wire and "connects" it to another
+# already declared wire. Let's start with the `sum` bit, which is of course just the xor
+# of the three inputs:
 sum <<= a ^ b ^ c
 
-# The carry_out bit would just be "carry_out <<= a & b | a & c | b & c" but let's break
-# than down a bit to see what is really happening. What if we want to give names to the
-# partial signals in the middle of that computation? When you take "a & b" in PyRTL,
-# what that really means is "make an AND gate, connect one input to 'a' and the other to
-# 'b' and return the result of the gate". The result of that AND gate can then be
-# assigned to temp1 or it can be used like any other Python variable.
-
-temp1 <<= a & b  # connect the result of a & b to the pre-allocated wirevector
+# The `carry_out` bit would just be `carry_out <<= a & b | a & c | b & c` but let's
+# break that down a bit to see what is really happening. What if we want to give names
+# to the intermediate signals in the middle of that computation? When you take `a & b`
+# in PyRTL, what that really means is "make an AND gate, connect one input to `a` and
+# the other to `b` and return the result of the gate". The result of that AND gate can
+# then be assigned to `temp1` or it can be used like any other Python variable.
+temp1 <<= a & b  # connect the result of a & b to the pre-allocated WireVector
 temp2 <<= a & c
 temp3 = b & c  # temp3 IS the result of b & c (this is the first mention of temp3)
 carry_out <<= temp1 | temp2 | temp3
 
-# You can access the working block through pyrtl.working_block(), and for most things
-# one block is all you will need. Example 2 discusses this in more detail, but for now
-# we can just print the block to see that in fact it looks like the hardware we
-# described. The format is a bit weird, but roughly translates to a list of gates (the
-# 'w' gates are just wires). The ins and outs of the gates are printed
-# 'name'/'bitwidth''WireVectorType'
-
+# You can access the working block through `working_block()`, and for most things one
+# block is all you will need. Example 2 discusses this in more detail, but for now we
+# can just print the block to see that in fact it looks like the hardware we described.
+# The format is a bit weird, but roughly translates to a list of gates (the `w` gates
+# are just wires). The ins and outs of the gates are formatted as
+# `{name}/{bitwidth}{WireVectorType}`.
 print("--- One Bit Adder Implementation ---")
 print(pyrtl.working_block())
-print()
-
-# --- Step 2: Simulate Design  -----------------------------------------------
 
+# ## Step 2: Simulate Design
+#
 # Okay, let's simulate our one-bit adder.
-
 sim = pyrtl.Simulation()
 
-# Now all we need to do is call "sim.step" to simulate each clock cycle of our design.
-# We just need to pass in some input each cycle, which is a dictionary mapping inputs
-# (the *names* of the inputs, not the actual Input instances) to their value for that
-# signal each cycle. In this simple example, we can just specify a random value of 0 or
-# 1 with Python's random module. We call step 15 times to simulate 15 cycles.
-
+# Now all we need to do is call `step()` to simulate each clock cycle of our design. We
+# just need to pass in some input each cycle, which is a dictionary mapping inputs (the
+# *names* of the inputs, not the actual instances of `Input`) to their value for that
+# signal in the current cycle. In this simple example, we can just specify a random
+# value of 0 or 1 with Python's random module. We call step 15 times to simulate 15
+# cycles.
 for _cycle in range(15):
     sim.step(
-        {
-            "a": random.choice([0, 1]),
-            "b": random.choice([0, 1]),
-            "c": random.choice([0, 1]),
-        }
+        {"a": random.randrange(2), "b": random.randrange(2), "c": random.randrange(2)}
     )
 
 # Now all we need to do is print the trace results to the screen. Here we use
-# "render_trace" with some size information.
-print("--- One Bit Adder Simulation ---")
+# `render_trace()` with some size information.
+print("\n--- One Bit Adder Simulation ---")
 sim.tracer.render_trace(symbol_len=2)
 
 a_value = sim.inspect(a)
 print("The latest value of 'a' was: ", a_value)
 
-# --- Step 3: Verification of Simulated Design ---------------------------------------
-
-# Now finally, let's check the trace to make sure that sum and carry_out are actually
+# ## Step 3: Verification of Simulated Design
+#
+# Finally, let's check the trace to make sure that `sum` and `carry_out` are actually
 # the right values when compared to Python's addition operation. Note that all the
 # simulation is done at this point and we are just checking the waveform, but there is
 # no reason you could not do this at simulation time if you had a really long-running
 # design.
-
 for cycle in range(15):
-    # Note that we are doing all arithmetic on values, NOT wirevectors, here. We can add
-    # the inputs together to get a value for the result
+    # Note that we are doing all arithmetic on values, NOT `WireVectors` here. We can
+    # add the inputs together to get a value for the result:
     add_result = (
         sim.tracer.trace["a"][cycle]
         + sim.tracer.trace["b"][cycle]
         + sim.tracer.trace["c"][cycle]
     )
-    # We can select off the bits and compare
+    # We can select off the bits and compare:
     python_sum = add_result & 0x1
     python_cout = (add_result >> 1) & 0x1
     if (
         python_sum != sim.tracer.trace["sum"][cycle]
         or python_cout != sim.tracer.trace["carry_out"][cycle]
     ):
-        print("This Example is Broken!!!")
-        exit(1)
+        msg = "This Example is Broken!!!"
+        raise Exception(msg)

examples/example1.1-signed-numbers.py

@@ -1,18 +1,15 @@
-"""Example 1.1: Working with signed integers.
-
-This example demonstrates:
-• Correct addition of signed integers with `signed_add`.
-• Displaying signed integers in traces with `val_to_signed_integer`.
-
-Signed integers are represented in two's complement.
-https://en.wikipedia.org/wiki/Two%27s_complement
-
-"""
-
+# # Example 1.1: Working with signed integers.
+#
+# This example demonstrates:
+# * Correct addition of signed integers with `signed_add()`.
+# * Displaying signed integers in traces with `val_to_signed_integer()`.
+#
+# Signed integers are represented in two's complement.
+# https://en.wikipedia.org/wiki/Two%27s_complement
 import pyrtl
 
-# Let's start with unsigned addition.
-# ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
+# ## Let's start with unsigned addition.
+#
 # Add all combinations of two unsigned 2-bit inputs.
 a = pyrtl.Input(bitwidth=2, name="a")
 b = pyrtl.Input(bitwidth=2, name="b")
@@ -28,43 +25,44 @@
 
 sim = pyrtl.Simulation()
 sim.step_multiple(provided_inputs=unsigned_inputs)
+
 # In this trace, `unsigned_sum` is the sum of all combinations of
 # {0, 1, 2, 3} + {0, 1, 2, 3}. For example:
-# • cycle  0 shows 0 + 0 = 0
-# • cycle  1 shows 0 + 1 = 1
-# • cycle 15 shows 3 + 3 = 6
+# * cycle  0 shows 0 + 0 = 0
+# * cycle  1 shows 0 + 1 = 1
+# * cycle 15 shows 3 + 3 = 6
 print(
-    "Unsigned addition. Each cycle adds a different combination of "
-    "numbers.\nunsigned_sum == a + b"
+    "Unsigned addition. Each cycle adds a different combination of numbers.\n"
+    "unsigned_sum == a + b"
 )
 sim.tracer.render_trace(repr_func=int)
 
-# Re-interpreting `a`, `b`, and `unsigned_sum` as signed is incorrect.
-# ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
-# Use `val_to_signed_integer` to re-interpret the previous simulation results
-# as signed integers. But the results are INCORRECT, because `unsigned_sum`
+# ## Re-interpreting `a`, `b`, and `unsigned_sum` as signed is **incorrect**.
+#
+# Use `val_to_signed_integer()` to re-interpret the previous simulation results
+# as signed integers. But the results are **INCORRECT**, because `unsigned_sum`
 # performed unsigned addition with `+`. For example:
 #
-# • cycle  2 shows 0 + -2 = 2
-# • cycle 13 shows -1 + 1 = -4
+# * cycle  2 shows 0 + -2 = 2
+# * cycle 13 shows -1 + 1 = -4
 #
 # `unsigned_sum` is incorrect because PyRTL must extend `a` and `b` to the
 # sum's bitwidth before adding, but PyRTL zero-extends by default, instead of
 # sign-extending. Zero-extending is correct when `a` and `b` are unsigned, but
-# sign-extending is correct when `a` and `b` are signed. Use `signed_add` to
+# sign-extending is correct when `a` and `b` are signed. Use `signed_add()` to
 # sign-extend `a` and `b`, as demonstrated next.
 print(
-    "\nUse `val_to_signed_integer` to re-interpret the previous simulation "
-    "results as\nsigned integers. But re-interpreting the previous trace as "
-    "signed integers \nproduces INCORRECT RESULTS!"
+    "\nUse `val_to_signed_integer()` to re-interpret the previous simulation results as"
+    "\nsigned integers. But re-interpreting the previous trace as signed integers \n"
+    "produces INCORRECT RESULTS!"
 )
 sim.tracer.render_trace(repr_func=pyrtl.val_to_signed_integer)
 
-# Use `signed_add` to correctly add signed integers.
-# ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
-# `signed_add` works by sign-extending its inputs to the sum's bitwidth before
+# ## Use `signed_add()` to correctly add signed integers.
+#
+# `signed_add()` works by sign-extending its inputs to the sum's bitwidth before
 # adding. There are many `signed_*` functions for signed operations, like
-# `signed_sub`, `signed_mul`, `signed_lt`, and so on.
+# `signed_sub()`, `signed_mult()`, `signed_lt()`, and so on.
 pyrtl.reset_working_block()
 
 a = pyrtl.Input(bitwidth=2, name="a")
@@ -83,30 +81,32 @@
 
 # In this trace, `signed_sum` is the sum of all combinations of
 # {-2, -1, 0, 1} + {-2, -1, 0, 1}. For example:
-# • cycle  0 shows -2 + -2 = -4
-# • cycle  1 shows -2 + -1 = -3
-# • cycle 15 shows 1 + 1 = 2
+# * cycle  0 shows -2 + -2 = -4
+# * cycle  1 shows -2 + -1 = -3
+# * cycle 15 shows 1 + 1 = 2
 print(
-    "\nReset the simulation and use `signed_add` to correctly add signed "
-    "integers.\nsigned_sum == signed_add(a, b)"
+    "\nReset the simulation and use `signed_add()` to correctly add signed integers.\n"
+    "signed_sum == signed_add(a, b)"
 )
 sim.tracer.render_trace(repr_func=pyrtl.val_to_signed_integer)
 
-# Manually sign-extend inputs to correctly add signed integers with `+`.
-# ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
-# Instead of using `signed_add`, we can manually sign-extend the inputs and
-# truncate the output to correctly add signed integers with `+`. Use this trick
-# to implement other signed arithmetic operations.
+# ## Manually sign-extend inputs to correctly add signed integers with `+`.
+#
+# Instead of using `signed_add()`, we can manually sign-extend the inputs with
+# `sign_extended()` and `truncate()` the output to correctly add signed integers with
+# `+`. Use this trick to implement other signed arithmetic operations.
 pyrtl.reset_working_block()
 
 a = pyrtl.Input(bitwidth=2, name="a")
 b = pyrtl.Input(bitwidth=2, name="b")
 
 # Using `+` produces the correct result for signed addition here because we
-# manually extend `a` and `b` to 3 bits. The result of `a.sign_extended(3) +
-# b.sign_extended(3)` is now 4 bits, but we truncate it to 3 bits. This
-# truncation is subtle, but important! The addition's full 4 bit result would
-# not be correct.
+# manually extend `a` and `b` to 3 bits. The result of
+#
+#     a.sign_extended(3) + b.sign_extended(3)
+#
+# is now 4 bits, but we truncate it to 3 bits. This truncation is subtle, but important!
+# The addition's full 4 bit result would not be correct.
 sign_extended_sum = pyrtl.Output(bitwidth=3, name="sign_extended_sum")
 extended_a = a.sign_extended(bitwidth=3)
 extended_b = b.sign_extended(bitwidth=3)
@@ -121,9 +121,8 @@
 sim.step_multiple(provided_inputs=signed_inputs)
 
 print(
-    "\nInstead of using `signed_add`, we can also manually sign extend the "
-    "inputs to\ncorrectly add signed integers with `+`.\n"
-    "sign_extended_sum == (a.sign_extended(3) + b.sign_extended(3))"
-    ".truncate(3)"
+    "\nInstead of using `signed_add()`, we can also manually sign extend the inputs to"
+    "\ncorrectly add signed integers with `+`.\nsign_extended_sum == "
+    "(a.sign_extended(3) + b.sign_extended(3)).truncate(3)"
 )
 sim.tracer.render_trace(repr_func=pyrtl.val_to_signed_integer)