Running the Clubs algorithm

HLSIM runs under MIT-Scheme. HLSIM requires the compiler to be loaded, so make sure that you run Scheme with a band that contains the compiler. If you are running Scheme under emacs, use the -compiler command line option when you run scheme (C-u M-x run-scheme). If you are using Edwin, use the command line option -band all.com (on Windows NT) or -band c+e.com (unix).

Code for this tutorial example can be found in the examples.zip   file on the 6.966 web page and in the file /home/gunk/hlsim/examples/Tutorial. One way of running the tutorial example is to insert Tutorial into your Scheme interaction buffer and use M-z to send the expressions to the Scheme REPL.

HLSIM is available as a load option on the Switzerland HP Snakes.

(load-option 'hlsim)

If you are running HLSIM on another machine where load-option is not set up, you can always load HLSIM something like one of these:

;; AI Lab linux machine: (load "/home/gunk/hlsim/stable-linux/loader") ;; Switzerland NT machine: (load "//martigny/gunk/hlsim/stable-linux/loader") ;; From a local copy on an NT machine: (load "d:/gunk/hlsim/stable/loader")

Make your own copy the example files, which contain a Gunk program (club5.scm) and some utilities for keeping a graphical display of the simulation's prograss (club5d.scm).

(copy-file "/gunk/hlsim/examples/club5.scm" "club5.scm") (copy-file "/gunk/hlsim/examples/club5d.scm" "club5d.scm")

  
Figure: Compilation in MIT Scheme

The Scheme code for the gunk processor cannot be executed directly. The resaons for this are explained later. The program first must be compiled into a special continuation passing style (CPS).  This is achieved as follows:

(cps "club5")

The cps procedure reads in the .scm file and outputs a .bin file. In this respect, cps is a replacement for sf. sf processes declarations and macros, so cps first uses sf, and then transforms the result into CPS.

The next two steps are optional. The club files may be compiled for faster execution. Compiled programs are harder to debug. It is strongly recommended that you don't compile the programs until you have got most of the bugs out. Note that we use cbf to compile the .bin file, since cf would do the wrong thing by generating a new .bin file.

(cbf "club5") ; compile gunk file (cf "club5d") ; compile regular scheme file

The relationships between the compilation commands are illustrated in figure .

We can now load some some display utilities and a procedure to help us make a simulation, since they are regular Scheme procedures:

(load "club5d")

The next stage is to construct a simulation object. A simulation object contains all the information required to run the simulation.

The procedure make-sim/1 from club5d (see appendix for listing) is called to construct a simulation where 1000 processors are uniformly distributed in a unit square. The processors have an effective communications radius of 0.05 units:

(define sim (make-sim/1 1000 .05))

This example includes the use of a Scheme Graphics window to display the processors as color-coded dots. If you want to use this feature, then enter:

(simulation.display! sim #T)

An empty Scheme Graphics window will appear.

The penultimate step is to load the gunk program into the simulation. We load two files. init contains a few useful procedures, such as the color-me procedure which calls the %color-me procedure loaded from club5d.

Load the gunk program:

(simulation.load sim 'init "club5")

Finally, we can run the simulation:

(simulation.run sim)

When the simulation has finished (or at any point if you stop it by breaking in C-c C-b) you can gather information from the simulation. For example, you might be interested to know how many collisions each processor detected:

(define cols (simulation.eval sim 'collisions))

The simulation.eval procedure evaluates its second argument in each processor, and returns a vector of results, so

(vector-ref cols 42)

will tell us how many collisions the 43rd processor counted (vector indexes are 0-based).

The expression to evaluate is an arbitrary Scheme expression, for example, we could use

(reduce max 0 (vector->list (simulation.eval sim '(length clubs-i-belong-to))))

to calculate the maximum number of clubs that any processor belongs to, and check it against a theoretical result.