

              *** USER MANUAL FOR SIMULATED ENVIRONMENT ***
              ---------------------------------------------

                                                   Toby Tyrrell.  21-3-93.
                                                   (lrtt@cns.ed.ac.uk)


This code should work on a Sun4 computer running unix and SunView or
OpenWindows with either a monochrome or colour monitor.  It has not been
tested on any other machines.  The code has been developed as a research
tool, rather than a commercial program and should be treated as such.  Any
commercial uses of this code must be authorised by myself.  No aspects of
the code are guaranteed.

The acronym SE throughout means simulated environment.


(1) How To Unpack se.Z
----------------------

(i)   "cd" to whichever part of your directory structure you want to put
      these programs.
(ii)  move se.Z to that directory
(iii) "uncompress se"
(iv)  "tar xvf se"

You may have already done this.  when you have unpacked se.Z you should now
have a directory "as", with this file and sub-directories "R_and_P", "asm",
"asm_ng", "drives", "extended_R_and_P", "hds", "lorenz", "maes",
"no_graphics", "sim_env", and "templates".


(2) How To Modify The Programs For Your Machine
-----------------------------------------------

(i)   "cd as/sim_env"
(ii)  "emacs slave.h" and change the value of MASTER_NAME to the name of
      your local machine.

The second step is necessary because there are two types of process: a
"master" process which is in charge of the evaluation process for an action
selection mechanism, and "slave" processes which receive instructions from
the master to perform individual evaluations of the action selection
mechanism in instances of the SE. The master process then receives back the
results of the evaluations and keeps a record of them. The slave processes
can run on any machines which `know about' the machine on which the master
process is running.  There can only be one master process running at a time
but many slave processes can be started on many different machines and the
master process will automatically use them efficiently to evaluate the
action selection mechanism many times in many different random instances of
the SE (this is only useful for calculating the average performance over
many runs).


(3) How To Run The Simulated Environment
----------------------------------------

(i)   start up SunView or OpenWindows
(ii)  "cd as/sim_env"
(iii) "make"
(iv)  "master &"
(v)   "slave"

You should now see the SE display on the screen.  Various buttons can be
clicked to bring up various displays or to pause, step, or change the speed
of the SE.

All being well everything should compile first time, but in case not there
are two main problems you may encounter with the steps above:  (i) errors
during compilation.  If you cannot resolve these problems yourself then talk
to a more experienced C programmer,  (ii) quota restrictions.  The programs
are fairly large and you may run into quota restrictions if they apply on
your machines.  See your system manager.


(4) How To 'Plug In' A Different Action Selection Mechanism
-----------------------------------------------------------

The files in the directory "as/asm" define the action selection mechanism
being used (as opposed to the files in "as/sim_env" which define the SE).
When you first unpack the directories, the files in the directory "as/asm"
are identical to those in "as/drives", which means that a drives-type
mechanism is selecting the animal's actions in the SE.  To change to, for
instance, Maes's spreading activation network, the following steps would be
required:

(i)   "cd as/asm"
(ii)  "rm *"
(iii) "cp ../maes/* ."
(iv)  "cd ../sim_env"
(v)   "make"


(5) How To Design Your Own Action Selection Mechanism
-----------------------------------------------------

You should think twice about doing this since it will probably involve a
large amount of time and effort.

There are two separate sets of files in the "as" directory, those that
specify the workings of the simulated environment (the testbed) and those
that specify the workings of the action selection mechanism (the entity
being tested).  Only the files defining the action selection mechanism have
to be changed.  You will obviously need to be able to program in C to do
this.  The steps required to define a new action selection mechanism are: 

(i)   create your own sub-directory (e.g. "cd as", "mkdir my_asm")
(ii)  copy across some template files ("cp templates/* my_asm/")
(iii) add to those files to produce your own action selection mechanism.  In
      particular, write a function (or functions) to select an action on the
      basis of internal and external stimuli/perception and place a call to
      the function at the indicated place in "asm_functions.c".
(iv)  'plug in' the mechanism by following the steps in (4).

To see some examples of how to build on the template files, look at the
drives, Maes and Rosenblatt & Payton mechanisms as defined in the relevant
directories.

It should be noted that the function "action_selection()" in
"asm_functions.c" gets called by the SE program once every timestep, after
the perception of the animal has been calculated.  The function receives a
large set of descriptors of the internal and external environment and must
return a selected action (an integer in the range 0 to 34 - see
"sim_env/animals_defs.h").  The function "set_up_strategy()" gets called
once when the SE is being set up and can be used to initialise variables,
zero arrays, etc for the use of your action selection mechanism.


(6) How To Run The SE Without Graphics
--------------------------------------

The purpose of doing this is to obtain quicker evaluations, which is useful
if you want to obtain a performance measure averaged over many individual
evaluations (necessary because of all the randomness in the SE).  To do this
the following steps are necessary:

(i)    insert the mechanism you want to test in "as/asm"
(ii)   "cd as/sim_env"
(iii)  "emacs master.h" and change NUM_TESTS to the value you require.
(iv)   "cc d_to_no_graphics.c -o d_to_no_graphics" and
       "cc to_no_graphics.c -o to_no_graphics" to compile two programs.
(v)    "all_to_no_graphics"
(vi)   "cd ../no_graphics"
(vii)  "make"
(viii) "master &"
(ix)   "slave"

Slave processes can then be started on as many machines as you want.  The
greater the number of machines, the faster the evaluations will all be
carried out.

Any questions or comments to lrtt@cns.ed.ac.uk.
