$usepop/pop/packages/brait/README
Aaron Sloman
Revised: 3 Jul 2009
8 Oct 2000


Previously: $poplocal/local/brait/README



See "Changes" list below.
========================


CONTENTS

 -- OVERVIEW
 -- PREREQUISITES FOR THE PACKAGE TO BE USABLE
 -- INSTALLATION OF THE BRAIT PACKAGE
 -- TEACH FILES
 -- CHANGE NOTES

                           The "Brait" package
                           -------------------
-- OVERVIEW

The files in this directory and its subdirectories were produced mainly
by Duncan Fewkes, working under the supervision of Jeremy Wyatt.

The files provide an introduction, using working demonstrations, to the
ideas in this book:

    V. Braitenberg, 1984,
        Vehicles: Experiments in Synthetic Psychology,
        Cambridge, Mass, The MIT Press

The programs are all implemented in Pop-11, augmented by the Rclib and
SimAgent toolkits, available from

    http://www.cs.bham.ac.uk/research/poplog/rclib.tar.gz
    http://www.cs.bham.ac.uk/research/poplog/newkit.tar.gz


The teach files in the Brait package also include an introduction to the
Pop-11 language and its editor Ved, so that the package can be used
for a course intended for complete beginners.

Subsequent to the completion of the main project, Aaron Sloman made a
number of changes to take account of recent additions and modifications
to the Rclib and SimAgent toolkits used by the package, and also some
streamlining and clarification of the Pop-11 code.



=======================================================================

-- PREREQUISITES FOR THE PACKAGE TO BE USABLE

The package should work on any version of Poplog running under Unix or
Linux with the X window system installed for graphics. Motif is not
required.

The Rclib and SimAgent libraries mentioned above must be installed.
They can be fetched from
    http://www.cs.bham.ac.uk/research/poplog/freepoplog.html

and installed in the directory
    $poplocal/local/

with appropriate links set up from these locations:

    $poplocal/local/lib/rclib.p
    $poplocal/local/lib/prblib.p
    $poplocal/local/lib/simlib.p

This will enable the commands

    uses rclib
    uses prblib
    uses simlib

to work.

NB: Because of the RCLIB and SimAgent facilities used, this needs the
version of RCLIB created on 24 December 2000 or later and version of
SimAgent created 27 Nov 2000 or later.

NOTE: this package uses the "compilehere" macro to enable it to be
location independent. This is avaiable from

    http://www.cs.bham.ac.uk/research/poplog/auto/compilehere.p

To be installed in
    $poplocal/local/auto/compilehere.p

The help file is available at
    http://www.cs.bham.ac.uk/research/poplog/help/compilehere

To be installed in
    $poplocal/local/help/compilehere

AS A CONVENIENCE, since these files are both small they have been
included in the Brait library in the auto and help directories, to make
it unnecessary to fetch them separately. However it is possible that the
versions at the web site will be extended to make them more versatile,
in which case the versions here will be out of date. If there are
problems with them, please try the versions at the poplog web site.



-- INSTALLATION OF THE BRAIT PACKAGE

If this directory is installed as:
    $poplocal/local/brait/

and a symbolic link is made from
        $poplocal/local/brait/brait.p
    to the directory
        $poplocal/local/lib/

then the command

    uses brait

will suffice to make the programs available.


-- TEACH FILES

After installation the following teach files will be available
(and others may be added)

    teach brait1

        This gives an introduction to Pop-11, the editor Ved/XVed and
        the "brait" library. It is designed for beginners.
        (Written by Duncan Fewkes and Jeremy Wyatt)

    teach boxdemo
        This reads in a file which can be compiled to produce a
        demonstration of a working vehicle inside a box, along
        with some sound sources. It can be controlled by means
        of the control panel defined in brait/lib/interface.p
        (Written by Aaron Sloman, using examples in the previous
        teach file, slightly modified.)

=======================================================================

-- CHANGE NOTES

Changes are listed in reverse chronological order

Changes by A.Sloman  3 Jan 2001
1. Made a number of changes to TEACH brait1, including removing spelling
   errors and various points that were unclear. A lot more work is still
   needed.

2. Added global variable trace_colours, and ensured that vehicles leave
   different line trace colours when moving. (Previously only worked
   for blob trace). Uses new RCLIB procedure rc_draw_coloured_line

3. Replaced many string constants with words (for efficiency: words can
   be tested for equality with "==",

4. For reasons of accuracy replace string quotes with word quotes in
   documentation referring to words

5. Started to rationalise the vehicle creation code, including new lvars
   and lconstants, with new lblocks.

Changes by A.Sloman  23 Dec 2000

1. Renamed several files, e.g. box.object.p is now box_object.p
   vehicle.agent.p is now vehicle_agent.p

   No file name now includes more than one dot.

Changes by A.Sloman  8 Oct 2000

1.  Corrected file headers for lib files and footers for teach files.

2.  Did some reformatting of procedures, etc., by using ENTER jcp

3.  Built "define" indexes for some of the lib files.
    (Accessed via ENTER gg)

4.  Introduced TEACH boxdemo

5.  Removed definition of sim_scheduler, as explained below

6.  Removed procedures "smallest", "largest", replaced with "min", "max"

7.  Extended sim_agent to include the variable sim_stopping_scheduler.
    Made "do_stop" a synonum for "sim_stopping_scheduler".
    If this is made true, the scheduler stops at the end of the
    current time-slice.

8.  Removed duplicate assignment to sim_coords after sim_move_to
    and moved the call of syssleep into the ruleset "processing"
    in vehicle.agent.p
    Put redrawing/moving code into procedure move_vehicle, with
    rc_in_event_handler true locally to prevent events being
    handled during drawing.

9. In lib/tools.p, introduced two new variables:
    global vars
        braitwindow_x = "right",
        braitwindow_y = "bottom";

    These are now used by the procedures create_window
    and create_centred_window.
    They can be given different values at any time, to make the
    pictures appear elsewhere.

10. In lib/interface.p made the control panel include two more buttons
        SPEED UP
        SLOW DOWN
    Also ensured that panels and graphics window had rc_drag_only
    slot made true, so that movements of the mouse cannot affect
    drawing of objects.

11. The file brait/lib/process_event_queue.p redefines the RCLIB
    procedure rc_process_event_queue so that it doesn't handle
    events if a picture object is being drawn. This can reduce
    unwanted interference between asynchronous mouse events and
    move objects being drawn. However it can also make the
    control panel too unresponsive, so it has not been included
    by default. To experiment with it do this
        uses brait
        uses process_event_queue

12. For most of the lib/*.p files I've added a definition of the
    file name at the end as a global constant with value true, so
    that "uses" will not recompile the file. Unfortunatley this
    cannot be done with
        ball.object.p
        box.object.p
        source.object.p
        vehicle.agent.p
    These files should probably have their names changed, replacing
    the first "." with "_"


NOTE:
Duncan found some problems using the RCLIB graphical tools in
conjunction with the SimAgent toolkit and resolved them by redefining
some procedures from the RCLIB and SimAgent toolkits

This had the disadvantage that the code could become incompatible with
the toolkits if they changed.

As explained above, I have changed his solution to fit in better with
the philosophy of both RCLIB and SimAgent. The changes are described
above.

--- $poplocal/local/brait/README
--- Copyright University of Birmingham 2000. All rights reserved. ------
