README

Copyright 2014 by Andrew L. Blais.
This program is distributed under the terms of the GNU General Public License 
version 3.

Virtual Harry is a python simulation of Harry Porter's relay computer. See his 
website.

web.cecs.pdx.edu/~harry/Relay/

The best way to read this document is to start VirtualHarry. This can be done 
on the command line, with: 

>>> ./VirtualHarry.py

Then, press the red README button, which is in the upper right hand corner, and 
this document will appear in the area labeled "Inside VH's Head". This is where 
system messages are displayed. 

VH is a very simple computer. It is so simple that it only its only inputs and 
outputs are 0s and 1s. Well, this is true of the real, physical, relay Harry.
Virtual Harry is partly a simulation of the relay Harry with a wrapper that 
makes it possible to manipulate the simulation in ways that the relay Harry 
cannot be. For example, the relay Harry must be programmed by flipping many, 
many switches. VirtualHarry can be programmed by selecting a much more easily 
constructed text file. This is curious, because part of the motivation for 
creating harry was to see what programming a computer by flipping switches 
would be like. The answer is, simply put, extremely tedious. 
It was more interesting to figure out how to get a virtual machine to respond 
to 0s and 1s in a way that closely paralleled the way that the relay Harry 
responds. 

VH has two main ways to input 0s and 1s. (1) The Data Bus and (2) the Address 
Bus. These two busses are located on the right. 

Just above the system messages area on the right is an area labeled "8 bit Data 
Bus". It consists of eight buttons that are initially labeled "0" and 
that are used to control the values on the Data Bus. In the relay Harry, the 
data bus consists of wires that carry electric signals. In VH, the Data Bus is
an imitation of these wires. Instead of an electric signal, there are 0s and 
1s. Instead of electric charges on wires, there are 0s and 1s in lists or 
arrays. Instead of being being switched on or off, a list has either a one or a
zero. Instead of current flowing, 0s and 1s are copied from the source to the 
Data Bus and then copied from the Data Bus to the destination. 

To change the values on the Data Bus, click the buttons. If the button is 0 
(or 1), it changes to 1 (or 0). Experiment, enter 00110011 into the data bus. 

Once data is on the Data Bus, where can it go? One place it can go is what 
might be thought of as VH's scratch pad. This is the Register, which is on the 
top right. The Register has three areas. 

First, there is the up time clock. It has nothing to do with VH's computing 
however. There was an empty space and I thought it would be cool to put an up 
time clock there. It seems obvious that there should be a way to implement 
this program in a way that also simulates a clock and the timing required by 
actual physical relays. This might be done with bunches of threads, I suspect. 





Now, the next two key components are the ALU and the Register. The ALU is on 
the right near the bottom just above the area labeled "Encoder"; 



He has a number of documents explaining how he built his relay computer. About 
two years ago, I though that it would be interesting to write a simulation of 
his machine. At first, I tried javascript. The result was a mess. Partly 
because javascript is complicated by having to play nice with a bunch of 
different browsers. Partly because writing a simulation of the physical machine 
is kind of hard. I partly got as far as I have by separating what the relays 
did from how the relays worked together to do what they do. Instead of thinking 
of relays, I thought of a relatively smart winged monkey flying amongst rows of 
boxes filled with 0s and 1s. 

It has occurred to me that VH is a piece of conceptual art. It explores the
platitude that computers are, at bottom, 0s and 1s. If you think about it, 
there is no reason that VH could not have been implemented as a very long 
series of boxes, or as a very long tape, whose contents are manipulated by the 
extremely clever winged monkey. So, if you see how VH works, you see how a 
Turing machine works. I think. 

The organization of the code follows the model-view-controller paradigm. The 
various parts of the view are in files with "face" in their names. They can be 
run as independent programs, although they do not do anything but make an 
appearance. The model is essentially in core.py, which itself makes use of 
alu.py, control.py, memory.py, and register.py. The alu can be run on the 
command line. Oh, yes, I used Eclipse as my code editor; the various eclipse 
files are in this archive. 

The function of the alu can be set with F0, F1 and F2. Doing this determines 
the result. The chosen function is highlighted in red. Pushing "Send Result to 
Data Bus" does exactly that. One of the ways that VH differs from Harry's relay 
computer is that the result of the alu is not automatically "gated" onto the 
data bus. It is necessary to explicitly move the result of the alu to the data
bus. This also makes for a difference in the way that the execute phase works,
that is, in the fetch-increment-execute cycle.   

By pushing the various 8 bit load buttons, their respective reisters are filled 
with the content of the data bus. Similarly for the address bus. 

VirtualHarry can be programmed using the "Relay Computer Instruction Set", 
which can be found at:

web.cecs.pdx.edu/~harry/Relay/Original-Circuit-Diagrams/InstructionSet.jpeg

(Include instruction set in VH?)

Essentially, more or less, use a procedure somewhat like this:

(1) Enter an address where the command is to be stored in memory.
(2) Enter a command into the data bus.
(3) Push write to memory.
(4) If the command wasn't halt, go back to (1), else your'e done. (Well, maybe
    not, since halt may be buried somewhere that the program eventually finds.)

I have made a number of files that store the 0s and 1s that encode a number of 
VH programs. These are the *.pgm files. They are ASCII files that can be edited
in the standard ways. Pressing "Load PGM" brings up a file choosing menu. 
Selecting the file then writes the program to memory. Select a test program 
such as "multiplyPGM" or "testGOTOpgm". Then decided whether you want to step 
through the program's commands or have it just run through all of them without 
pause.

If the later, press the "no step" button. It will turn red. Then press the RUN 
button. You will see a description of each command pass by on the command line. 
You can scroll through the history to see what VH did. 

If the former, leave the "no step" button alone, and simply press RUN. Then, to 
proceed through the series of commands, press STEP.


For example, enter "00001010" (10) into the data bus.
Then press "Load C".
You will see the alu change state.
Enter "00000110" (6) into the data bus.
Then press "Load B".
Again, you will see the alu change state.
Now, press "test subtract".
Press RUN.

The command line will scroll by with various descriptions of the commands. 
Finally, it will stop. I hope. And, the last command should be represented by a 
description of halting. In the A register, you should see "00000100", that 
is, 4.

The "test multiply" function works in essentially the same way. Except that the 
arguments are entered into X and Y. Note that M1 must be empty. 

Feedback is desirable. I'd like to see additional tests.

Human Harry, 
Porter that is, has a very interesting and informative pdf book that describes
the workings of the timings and such.

Check it out at:

http://web.cecs.pdx.edu/~harry/Relay/RelayPaper.pdf

There is also a movie....

The memory module has four buttons: random, clear, read and write. Read and 
write do exactly those things relative to the current value of the address bus
and the data bus. Random fills all pow(2,15) bytes with random 0s and 1s. Push 
"random mem". Then push "NOSTEPS". Then push "RUN", and you'll have the moral 
equivalent of a lava lamp. This raises interesting questions about whether VH
will HALT for any given random filling of the memory. Hmmm...the halting 
problem.... How does that proof go?