A Word about Pygame and Running the Programs

The code has been written using Python 2.7 and Pygame was easily available and downloaded for Windows 7 (download and run a .msi file) and for Ubuntu 12.04 (use apt-get install pygame). It has not been tested on the Macintosh and has not been tested on Python 3. Pygame itself has dependancies for generating the graphics. With the above 2 options these are handled automagically.

In this tutorial the programs are run from the command prompt ('$') supplying arguments after the program name. If you are using IDLE or another enviroment you will probably first input the command line arguments and then run the appropriate program.

Encapulating a Circuit

The test program or.py encapsulates the OR circuit onto layer 2. We can view through layer 1 onto layer 2 by passing the command line argument "2" we see the following:

$ python or.py layer=2

Encapsulated OR circuit animated (return with the browser's Back button)

Notice the labeling on the connectors. The boxed OR gate has inputs "A" and "B". The switches don't have input labels (it's just you and the mouse) but they do each have a "B" output connector.

Something a bit more complex

An XOR gate (exclusive or) outputs high if one and only one input is high. Here's another way to look at it. The output is high if the inputs are different. Below is a circuit using 4 NAND gates to provide this function on connector N4.C.

$ python xor.py layer=3

Animated (return with the browser's Back button)

The program xor.py encapsulates the 4 NAND gates into a circuit component on layer 2. Since we viewed through to layer 3 we peeked into the circuit inside the encapsulation. But if we look just through to layer 2 we see instead:

$ python xor.py layer=2

Animated (return with the browser's Back button)

Just like the AND gate, the OR gate and the XOR gate each has its own standard drawing form and it's NOT a rectangular box. But we won't be using these 3 gates further so I didn't spend any time on how they look. However, the flip-flops that now follow are all traditionally drawn as a box.

The Simple Latch

In the earlier logic projects we built a simple latch from 2 NAND gates. This demonstrated how positive feedback could be used to remember (store) data. Here is a simple latch:

$ python latch.py layer=3

Animated (return with the browser's Back button)

Pulsars P1 and P2 each issue a short single pulse to low when clicked and then return to high. The 2 NAND gates form a one-bit memory unit that basically remembers which pulsar was last clicked. Click them one after another and watch the output change. If this is new for you then spend some time studying the circuit to understand why it works as it does. The crossed wires provide that positive feedback. The circuit is quite symmetrical.

Encapulated the circuit looks like:

$ python latch.py layer=2

Animated (return with the browser's Back button)

The inputs on the left of the encapsulation box are generally labeled A and B and the output on the right is labeled Q (not C) and is fed from the output N1.C

When it is clear (generally from the geometry) I'm going to avoid labeling every input and output.

The Data Latch

The simple latch above is not often used by itself because we usually want to do something else: We'll typically have a data line with a signal coming in and we want the ability to clock the signal value at a given point in time. By adding some front-end logic we can have exactly that: a circuit with two inputs (data and clock) and one output with the remembered value:

$ python dlatch.py layer=3

Animated (return with the browser's Back button)

Let's take a minute to study this. The data coming in from the switch D1 (a simple toggle switch) is delivered to both N1 and N2 but because of the inverter I1 it is delivered at opposite polarity. Switch C1 is a one-shot pulsar delivering a short downward pulse when clicked. I2 makes this an upward pulse to both N1 and N2. One of the outputs (either N1.C or N2.C) then drops setting the simple latch L1. When C1's pulse is over and its output returns to high, The data has been captured in L1.

We can also set the view all the way into layer 4 to see the workings of L1 as well:

$ python dlatch.py layer=4

Animated (return with the browser's Back button)

There's going to be a (not so) small problem, however. While the clock line is active (low), any change on the data line will be immediately be passed through to the output. This may or may not be serious depending on the application. For us it is a catastrophe because we will be using even more feedback from higher level outputs back to higher level inputs.

There is a way around this though. But we have to keep going.

Edge Triggered Data Latch

Our next circuit works something like an airlock. The idea is simple. Don't let the air (or signal) rush through when the door is open. Use two doors. Open the second only after the first is closed.

The simple Data latch is like that single door and when the clock is low that door is opened just letting all that signal out. Our improved E-latch will use 2 D-latches and with a single inverter their 2 clock inputs can be exactly out of step. When one is open the other is closed.

Here are three screen shots viewing through to layers 2, 3, and 4. The view to layer 3 is probably the most informative:

$ python elatch.py layer=2

Animated (return with the browser's Back button)

$ python elatch.py layer=3

Animated (return with the browser's Back button)

$ python elatch.py layer=4

Animated (return with the browser's Back button)

This reminds me a bit of using the zoom feature on map programs.

The Divide by Two Circuit

By adding just one inverter, we can turn an E-latch into a circuit with just one input (the clock) and convert a pulse stream on the input to another on the output with exactly half the frequency.

By feeding the output back to the data input inverted, the output will flip to the opposite polarity each time a pulse come in on the clock. More precisely, the output will flip each time the input clock goes from low to high. This creates a new pulse stream on the output with exactly half the frequency of the input pulse stream. Here is what it looks like at layer 3:

$ python div2.py layer=3

Animated (return with the browser's Back button)

The Four Bit Binary Counter

By simply stringing four div2 circuits together the outputs become bits in a binary counter. Here's what the circuit looks like at layer 3:

$ python counter.py layer=3 scale=1

Animated (return with the browser's Back button)

The circuit consists of a multipulsar C1 and four Divide-by-2 components (DV1, DV2, DV4, DV8).

Notice that there are now 2 arguments on the command line. The first is still the layer to view. The second is a scale factor that determines the size of components drawn to the screen. This defaults to "2". But specifying "1" we get a half scale. Sometimes "3" and "4" are used as well to magnify the circuit.

The screen shot was taken while the counter was in operation. At the bottom the blue lines represent '1' bits, the red lines '0'. We caught the count at '0101' or in decimal 5.

The counter counts up to '1111' and then wraps back to '0000'. And if we take the red lines for '1' instead of blue, we have a counter that counts down to zero and then wraps back to 15 decimal.

Settings

The module settings.py contains constants and also extracts scale and layer variables from the command line. Constants include colors we use as RGB tuples, screen dimensions, animation speed and parameters for the single and repeating pulse switches.

Component Abstract Class

The component class component.py is an abstract class. Basic component classes (Nand2, Inv, Swt) inherit this class as well as the circuit class. Component contains the attributes that all the sub-classes have in common such as name, position, layer and scale. Also common methods such as position alignment, handling mouse clicks, scaling of segments when drawing components. Sub-classes do not define their own __init__ method but must define a setupGraphics method which is called at the end of Component.__init__ and which will complete the initialization of the instance.

Basic Gates and Switches

The module gates.py contains the classes for the 2 input NAND gate (Nand2), the INVERTER gate and the the 3 types of switches. Each has a standard set of methods.

The setupGraphics methods make connectors to attach to the drawing. The self.output connector is mandatory as it's the source of a wire tree (more coming) that will disperse the output signal of the gate to appropriate input connectors on other gates.

The draw methods contain a list of arguments to use with pygame drawing commands. These arguments must be scaled before used to draw polygons, circles, etc.

Every component must have a computeOutput method which calculates the gate's output from its inputs and sometimes its history. Flip-flop circuits and pulse generators contain history.

The switches also have a takeClick method to respond to being clicked by the mouse.

Connectors

Connectors connector.py have several things in common with components but there are enough differences to make subclassing unattractive. Both have a parent, a name, a position, a value and a layer. Components have connectors for their inputs and output. The component is the parent of these connectors and they all reside in the same layer. For circuits that are encapsulated their external connectors reside one layer above the inner connectors.

Connectors connect to each other with wires. Interestingly, wires are not representated in the code. They are simply drawn during animation as a pygame line in either the HOT or COLD color from the source connector to one of its children its feed list.

Connectors may also reside independently within a circuit. In this case the circuit is the parent and both circuit components and these connectors reside in the same layer. These connectors make it easy to "fan out" a signal on a wire are even simply let a wire change direction.

Finally, external connectors in a circuit are used to connect the circuit-component into the rest of the circuit one layer up. These connectors reside in the layer above.

If a connectors parent has to move (scoot over), then the connector must also. The subject of alignment in circuit layout will be discussed below.

During construction of a circuit the method addWire connects components together. This method takes an arbitrary number of connector instances, or (x,y) positions as arguments. Each position argument creates a free standing connector named "Anon" at the x,y position. Method addWire works through the arguments left to right, and populates the feeds list of each connector appropriately. It returns the last connector as its function value, letting us chain these calls or fan a signal out quite easily.

During animation the method drawWires recursively walks the links between connectors and paints wires (lines) along the way. Since they are just wires all connected together, they all carry the same signal and are painted the same color.

Wires are not drawn inside an encapsulated circuit. This is controlled the the layer attribute of both the source and target. If either is hidden (below the visible viewing layer) then the wire is not drawn.

Usually, two "connected" connectors reside on the same layer. The exception is with a circuit's external connectors (at layer n) and its internal wiring (at layer n+1).

Also during animation the method sendOutput works much like drawWires. It transmits the signal from an output connector, through other connectors, on to input connectors on basic components. The difference is that, unlike drawWires, sendOutput doesn't stop at a hidden layer, but goes right to the bottom. The sendOutput method is defined for components as well as connectors.

Text Processing

Text (text.py) is used to label basic components and encapsulated circuits with their names, create banners and to optionally label connectors. Text is tied to a given x,y point and placed in one of four quadrants. When text.py is run stand-alone it creates a image that shows how the four quadrants are used:

$ python text.py

Alignment

Early versions of this project required me to carefully position each component of a circuit working out the x,y position by hand. The origin of a component or circuit is the upper left corner, basically the pygame convention. If a component is inside a circuit its x,y is relative to the origin of the circuit it is in.

When we start to scale, placing items by hand can quickly fall apart. What works much better is to place the first component at a fixed x,y position and then place other components relative to the first or to each other.

This is very effective if a circuit or component can align itself to another by specifying one of its own connectors and another connector from the target, along with an (x,y) offset between the connectors. This creates a very flexible system that adapts to scaling quite nicely. You've already seen this is the above screen shots. We want to use connectors because we run wires between them and this makes it easy to space components easily and also to have wiring that is largely horizontal or vertical.

The methods align and scootOver make this work. If a circuit is aligning itself to another it will scoot over appropriately and all the bits inside (components, connectors, subcircuits) must scoot over too. This is the sort of situation that can make recursion fun. We'll be seeing more of this now as we start to examine some of the code in detail.

A Simple Animation

Let's have another look at our first circuit.

Here is the Python code to build and then animate it:

# basics.py
#  Show off the basic gates in a simple circuit
#
from   gates     import MultPuls, Nand2, Inv, Swt
from   circuit   import Circuit

class TestBasic1 (Circuit) :
    def setupGraphics(self) :
        self.banner = "Basic components. Switch, Multipulsar, Nand, Inverter"

        n1 = Nand2(self,"N1", self.scale1((50, 30))) # Nand Gate
        i1 = Inv  (self,"I1")            # Inverter
        s1 = Swt  (self,"S1")            # Switch feeding input A
        m1 = MultPuls (self,"MP1")       # Pulsar feeding input B

        s1.align(s1.B, n1.A, -50, 0)  # line up the gates
        m1.align(m1.B, n1.B, -30, 0)
        i1.align(i1.B, n1.C,  80, 0)  # inverter follows Nand

        n1.A.labelQuad = 2            # Label all connectors
        n1.B.labelQuad = 2
        n1.C.labelQuad = 1
        i1.A.labelQuad = 2
        i1.B.labelQuad = 1

        self.gates = (m1,s1,n1,i1)
        s1.B.addWire(n1.A)
        m1.B.addWire(n1.B)
        n1.C.addWire(i1.A)
        i1.B.addWire( (i1.B.x(30), i1.B.y()))  # tail to see

if __name__ == "__main__" :
    import gameloop
    from   settings import CmdScale
    circuit = TestBasic1 (None, "TestBasic1",(100,100),scale=CmdScale)
    gameloop.gameloop(circuit)

Let's explain what is going on. The program can run stand-alone with the module name "__main__". The gameloop animation expects to be passed a circuit to animate (at bottom) so we define a class for our circuit and build an instance of it. This is a subclass of Circuit inheriting all of the standard code and we supplement it with the method setupGraphics which is automatically called from __init__ in the abstract Component class. An instance of TestBasic1 is built in the second to last line and then passed to the gameloop.py for animation.

The setupGraphics method defines the 2 gates and 2 switches and sets the banner attribute. Only the Nand gate is given a position of (50,30) scaled and offset relative to its parent, the pygame screen. The Inverter and 2 switches are created with a default position (0,0) and then align themselves to the Nand gate. Switch s1 aligns its output connector 50 units to the left of the Nand's A input (N1.A). The inverter I1 aligns its input 80 units to the right of N1's output connector(N1.C). A unit here is one pixel times the scale factor. The scale factor defaults to two.

The connectors are all assigned a labelQuad attribute to have their labels printed in the appropriate quadrant. The circuit self is assigned a gates attribute. This is a list of its components and used by the abstract Circuit class in the methods computeOutput, checkClicked and draw. (see circuit.py). And finally, wires are created connecting the two switches to the Nand, the Nand to the Inverter and then a piggy tail wire just to show the final output from the Inverter.

Circuits

The Circuit class circuit.py lets us combine components and optionally encapsulate them into a single component with its own connectors to the outside world. Circuits made for encapsulation (put into a box) do not have switches or banners and typically we don't label the interior connectors. On the other hand the outermost (top) circuit is generally never encapsulated and it so makes sense to have switches among its components and to label it more fully.

The Circuit class is quite small and enables the animation of a circuit with the following

• The method computeOutput for a circuit simply calls the same for each component in its gates attribute as well as sendOutput which distributes the signals within the circuit. The order of computation and distribution is set by the order of the components in gates
• The method checkClicked simply passes asks each of its components to do the check for the being clicked and repsond. This is only in the top non-encapsulated circuit.
• The draw method provides 3 possibilities.
  1. The circuit may be hidden and not drawn at all if it resides below the viewing layer.
  2. The circuit may be drawn as a box with just a label and external connectors if it exactly on the viewing layer.
  3. The circuit may be drawn in detail if it is above the viewing layer.

A Fuller Example

Let's return to the OR circuit or.py and look at the code. This will be the only module we'll study in detail. All the later circuits follow exactly the same pattern.

The first part of the setupGraphics method looks like:

class Or (Circuit) :
  def setupGraphics(self) :
      n1 = Nand2(self,"N1", self.scale1((80, 30))) # Nand Gate
      i1 = Inv  (self,"I1") # Inverter for n1.A
      i2 = Inv  (self,"I2") # Inverter for n1.B
      i1.align(i1.B, n1.A, -40, -20)  # inverter precedes Nand
      i2.align(i2.B, n1.B, -40,  20)  # inverter precedes Nand
      # external connectors
      self.A = Connector(self,"A",((i1.A.x(-20),i1.A.y() )))
      self.B = Connector(self,"B",((i2.A.x(-20),i2.B.y() )))
      self.C = Connector(self,"C",((n1.C.x( 20),n1.C.y() )))
      self.output = self.C       # who is output

      # child gates for computeOutput and draw methods
      self.gates = (i1,i2,n1)
      # for convenience let internal gates be seen from outside
      self.i1,self.i2,self.n1 = (i1,i2,n1)

We define the 3 gates with the circuit self as the parent. The first one n1 is set at a scaled position in the circuit. The two inverters i1 and i2 are defined and then aligned to n1. The exteral connectors A, B, and C are built and placed at a (x,y) position relative to the internal gates. These positions are used if the circuit is drawn in detail. The output is identified as connector C. The gates attribute is constructed. The individual gates are also kept as attributes of the circuit. This allows them to be referenced from outside the circuit itself (only sometimes a good idea):

continued ....
      # internal connectors
      i1.B.addWire(n1.A)
      i2.B.addWire(n1.B)
      # connect external connectors to internal components
      self.A.addWire(i1.A)
      self.B.addWire(i2.A)
      n1.C.addWire(self.C)

      if self.encapsulated() :  # if encapsulated re-work externals
          self.A.pos, self.B.pos, self.C.pos = self.scaleM((0,5),(0,35),(20,20))

The rest of setupGraphics method does the wiring between connectors both internally and to the 3 external external connectors self.A, self.B and self.C. So now, if the circuit is displayed in detail these 3 external connectors are in position to be wired into the circuit above. If the circuit is shown encapsulated (as a box) then these connectors need to take new positions that align to the box.

Next we have test circuit whose purpose is simply to instantiate and Or circuit and test it by adding switches, a banner and what not. In this case we labeled all of the connectors both inside (like or2.n1.A) and outside (like s1.B). Here is the code for that:

class TestOr (Circuit) :
  def setupGraphics(self) :
      self.banner = "Encapsulated OR circuit"
      or2 = Or(self,"O2"  , self.scale1((50,30)))
      s1 = Swt  (self,"S1")   # Switch feeding input A
      s2 = Swt  (self,"S2")   # Switch feeding input B

      s1.align(s1.B, or2.A, -30, 0)  # line up the gates
      s2.align(s2.B, or2.B, -30, 0)
      s1.B.addWire(or2.A)
      s2.B.addWire(or2.B)
      s1.B.labelQuad = 1
      s2.B.labelQuad = 1
      self.gates = (s1,s2,or2)

      or2.n1.A.labelQuad = 3            # Label all the connectors
      or2.n1.B.labelQuad = 2
      or2.n1.C.labelQuad = 1
      or2.i1.A.labelQuad = 2            # Inverter
      or2.i1.B.labelQuad = 1
      or2.i2.A.labelQuad = 3            # Inverter
      or2.i2.B.labelQuad = 4
      or2.A.labelQuad = 1
      or2.B.labelQuad = 1
      or2.C.labelQuad = 1
      or2.C.addWire( (or2.C.x(30), or2.C.y()))  # tail to see

Finally, or2.py is meant to be run as main. When it is invoked from the command line the scaling factor and view layer are taken from sys.argv or the defaults in the settings module settings.py. Then a TestOr instance is created, which further creates an Or instance along with the surroundings to test it. The TestOr instance is passed to the gameloop function:

if __name__ == "__main__" :
  import gameloop
  from   settings import CmdScale
  circuit = TestOr (None, "TestOr",(100,100),scale=CmdScale)
  gameloop.gameloop(circuit)

This same pattern is used in the modules that stack like nested russian dolls. Once you understand one, the others are easy.

latch.py, dlatch.py, elatch.py, div2.py, counter.py.

Each one of these can be run stand-alone from the command line as we have seen.

The gameloop

When one of the stand-alone modules is run as main it builds its test circuit and passes it to the gameloop function in gameloop.py. The latter is short and pretty much boiler plate Pygame. It creates a screen and enters an event loop. The constant TICKS_PER_SECOND in the settings module specifys how rapidly the loop is run.

Within the loop a few things happen. A mouse click on the window termination button will shut the program off. A mouse click on a switch (or pulsar) will toggle it. The switch itself is found by a recursive search through layers of circuits (generally not very deep) using the mouse coordinates. Next, the circuit is asked to compute its output, a request that also is sent recursively through the tree of circuits producing signals sent through wires at all layers. The screen is then erased and the circuit is drawn, wires and all. The draw request is also sent recursively through the circuits. Finally, the screen is flipped and the process repeats. At the default setting of 200 times a second.

All of the code files can also be obtained as logicPygame.zip