<< , >> , Title , Contents , Index

4. PROGRAMMER DOCUMENTATION


It is intended for this section to help programmers understand BOTSsim code.

4.1 DATA FLOW DIAGRAMS

4.1.1 Context Diagram


Figure 8--Context Diagram

4.1.2 Explanation

1. The program launches the GUI

2. If the user presses TED or new template, TED is launched.

3. If the user presses run, the environment duplicates the world, and starts the run. This button also launches the brain, which sends a ready message when the socket is open.

4. If the user presses pause or stop, that message is passed onto the environment.

5. If the user presses Save run, this message is sent on to TED to save the template, and the environment to save the run info. The GUI saves the Rule Sets of all the robots.

6. During a run, the environment makes passes the sensor information to the brain, which responds with an action.

7. At the end of a generation, the environment passes the fitness levels of all the robots to the brain. The brain analyses these fitness levels, and returns a Robot Environment position

4.1.3 GUI Data Flow Diagram


Figure 9--GUI Component Data Flow Diagram

4.1.4 TED Data Flow Diagram


Figure 10--Template Editor Data Flow Diagram

4.1.5 Environment Data Flow Diagram


Figure 11--Environment Component Data Flow Diagram

4.1.6 Brain Data Flow Diagram


Figure 12--Brain Component Data Flow Diagram

4.1.7 GUI Module Descriptions

The following is a description of the modules in the data flow diagrams for the GUI.

4.1.7.1 User/GUI

This is actually a collection of Event Handlers. It handles all of the input from the User and performs actions based upon that input. The User/GUI also controls the overall application.

4.1.7.2 Open Run

Controls the opening of all files associated with a single Run.

4.1.7.3 Open Template

Opens a saved Environment Template from a file.

4.1.7.4 Edit Run Information

Lets the user modify the information which is relevant to this particular run. Both the Environment and Genetic Programming Variables are used in this module.

4.1.7.5 Save Run

Controls the saving of all files associated with a single Run.

4.1.7.6 Display

This module contains all of the routines associated with displaying Environments, Histograms and Bots. This module should actually be broken up further but due to time constraints it is not.

4.1.8 TED Module Descriptions

The following is a description of the modules in the data flow diagrams for the TED.

4.1.8.1 Main

Controls the creation of an Environment Template.

4.1.8.2 Open Template

Handles the opening & loading of an existing Environment Template.

4.1.8.3 Save Template

Handles the saving of the current Environment Template.

4.1.9 Environment Module Descriptions

The following is a description of the modules in the data flow diagrams for the Environment.

4.1.9.1 Initialise Run

Receives Run Information, specifically Environment Variables. This module is responsible for starting a Run. This includes the creation of an Evaluation (multiple Environments) and creation of the Bot population as well as setting the initial fitness values for the Bots.

4.1.9.2 Manage Worlds

This module's purpose is to manage the many Environments within the simulation. Modification of fitness values as well as animation of the simulation occur in this module.

4.1.9.3 Robot Sensor Evaluation

The basic algorithm for this module is as follows:-

For each robot in world get sensor values send to brain and retrieve actions process actions and move robot end

4.1.9.4 Main Generation Loop

The basic algorithm for this module is as follows:-

Loop Wait for timestep trigger For each world do RobotSensorEvaluation until set time has elapsed

4.1.10 DFD Data Flows

Display Info This tells Display World what the user wants to be displayed, which is either Statistics or a world, or both. The user can look at several worlds at once, as well as the overall statistics.
Run Information This is a combination of a Template, Rule Set, GP Variables, and Environment Info.
Template This is what the environment views the world as. It is made up of a series of Bins, Distribution Areas, Walls and Bots.
Rule Set The set of rules that governs the bot's actions from given inputs.
Genetic Programming Variables Maximum depth for new individuals
Maximum depth for individuals after crossover
Maximum depth for new subtrees in mutants
Fitness proportionate reproduction fraction
Crossover at any point fraction
Crossover at function point fraction
Number of factories
Random number seed
Method of selection
Method of generation
Environment Variables Bot Turn Speed
Bot Move Speed
Generation Length: How many Time Steps per generation
Start Fitness
Block Pickup Gain
Right Drop Gain
Wrong Drop Loss
Robot Current Environment No. This determines what robot belong to what environment. ie robots 1 -5 in environment 1.
Fitness Levels The set of fitness levels for all robots.
Environment The multiple instances of the Template.
State The position of the blocks and robots in a given world, as well as the overall statistics.
Sensor This is the set of sensor inputs
Action This is the action the robot will perform.

4.1.11 DFD Triggers (Events)

Pause/Unpause/Abort Run Tells the Main Generation Loop to either pause, continue, or abort the current generation
Open Run Activates the Load Run module
Open Template Activates the Load Template module
Edit Run Information Activates the Edit Run Information module
Save Run Activates the Save Run module
Create/Modify Template Activates the TED module
Get Rule Set Gets the Rule Set from the Brain
Get State Gets the current state of the environment from the main generation loop
Time Step This activates the Robot Sensor Evaluation module, and is used at regular intervals

4.2 DATA DICTIONARY FOR IMPORTANT OBJECTS AND VARIABLES

This explains the purpose of the most "important" objects and variables within the GUI and Environment components. These variables are often referred to in multiple modules, and in some cases multiple source files.

4.2.1 AboutBox

This variable provides access to the About BOTSsim Dialogue Box.

4.2.2 BotDialogBox

This variable provides access to the Bot Properties Dialogue Box.

4.2.3 BotForm

This variable provides access to the Bot Window.

4.2.4 AboutColin

This variable provides access to the About Colin Dialogue Box.

4.2.5 AboutDavid

This variable provides access to the About David Dialogue Box.

4.2.6 AboutMark

This variable provides access to the About Mark Dialogue Box.

4.2.7 AboutMichael

This variable provides access to the About Michael Dialogue Box.

4.2.8 AboutMik

This variable provides access to the About Mik Dialogue Box.

4.2.9 AboutStephen

This variable provides access to the About Stephen Dialogue Box.

4.2.10 CommsDebug

This variable provides access to the Communications Debug Dialogue Box.

4.2.11 BotsPerWorld

This variable stores the number of Bots per Environment (World). This variable saves us from having to call the CountBots function on multiple occasions. This is an important variable because CountBots is an important function that gets called on many occasions within the Evaluation object. By having a variable to store this information we save a lot of processing resources during the execution of a Run.

4.2.12 Worlds

This variable stores the number of Environments (Worlds) in a Run. This is an important variable because the number of Environments in a Run would be otherwise unavailable. This variable is used in mostly the same places as the BotsPerWorld variable. It's high usage gives it it's importance.

4.2.13 HitsHistogram

This variable provides access to the Histogram Window.

4.2.14 HitsArray

This variable provides storage for the Histogram itself. The Histogram is an array of dynamic length, hence it is important that we have an easy way to access variables within it. The array construct provides us with this easy way to access the Histogram and display it on the screen.

4.2.15 MainForm

This variable provides access to the BOTSsim Dialogue, also referred to as the Main Dialogue.

4.2.16 TimeStepCounter

This variable is used to keep track of the progress over a single Generation of the Run.

4.2.17 GenerationCounter

This variable is used to keep track of the progress of the Run.

4.2.18 MainEval

This provides access to the Main Evaluation object (this is in fact the only Evaluation object). The Evaluation is perhaps one of the core variables within BOTSsim. Without it we would not be able to perform a Run with multiple Environments, construct the Histograms, or perform any of the other functions that are central to the overall functionality of BOTSsim.

4.2.19 CBEP

This provides access to the CBEP object. The CBEP object provides communications with the Brain for both the GUI and Environment components. This is an extremely important variable as it encompasses all of the high level communications in the Complex Environment Brain Protocol.

4.2.20 RunInfoDlg

This variable provides access to the Run Information Dialogue, which allows you to configure both the Genetic Programming Variables and the Environment Variables.

4.2.21 EnvironmentVars

This variable is a structure that provides access to the variables that affect the way the Environment works. The structure contains the following fields:-

* BotTurnSpeed

* BotMoveSpeed

* StartFitness

* BlockPickupGain

* RightDropGain

* WrongDropLoss

* GenerationLength

4.2.22 GPVars

This variable is a structure that provides access to the variables that affect the way the Genetic Programming algorithms and other constructs work. The structure contains the following fields:-

* MaxDepthForNewIndividuals

* MaxDepthForIndividualsAfterCrossover

* MaxDepthForNewSubtreesInMutants

* FitnessProportionateReproductionFraction

* CrossoverAtAnyPointFraction

* CrossoverAtFunctionPointFraction

* NumberOfFactories

* PopulationSize

* RandomNumberSeed

* MethodOfSelection

* MethodOfGeneration

4.2.23 ShowBotByID

This variable provides access to the Show Bot By ID Dialogue Box.

4.2.24 TEDForm

This variable provides access to the TED Window and it's associated functionality.

4.2.25 Zoom

This variable stores the Camera Zoom Factor within the TED Window. This variable's importance lies in the fact that the user will often wish to change the Zoom Factor while editing a Template.

4.2.26 ViewAnEnvironmentDlg

This variable provides access to the View An Environment Dialogue Box.

4.2.27 VisibleEnvironments

This variable provides access to all of the multiple View Environment Windows. This is an array construct that is used for dynamic creation & destruction of View Environment Windows.

4.2.28 WorldParams

This variable provides access to the Template Dimensions Dialogue Box.

4.3 MODULE (PROCEDURE AND FUNCTION) INFORMATION

This section explains the purpose of BOTSsim's modules, ie: Delphi procedures and functions.

4.3.1 About Box Modules

4.3.1.1 Image1Click

Displays the About Mark Dialogue.

4.3.1.2 Image2Click

Displays the About Mik Dialogue.

4.3.1.3 Image3Click

Displays the About Stephen Dialogue.

4.3.1.4 Image4Click

Displays the About Michael Dialogue.

4.3.1.5 Image5Click

Displays the About David Dialogue.

4.3.1.6 Image6Click

Displays the About Colin Dialogue.

4.3.1.7 CancelBtnClick

Closes the About BOTSsim Dialogue.

4.3.1.8 FormKeyDown

Close if the Escape (ASCII 27) key is pressed.

4.3.2 Bot Dialogue Box Modules

4.3.2.1 OKBtnClick

Sets the Bot Box variables.

4.3.2.2 ColorSBClick

Changes the colour of the bot.

4.3.3 Bot Form Modules

4.3.3.1 UpdateTimerTimer

Updates the bot display.

4.3.3.2 FormCreate

This is when the form is first created.

4.3.3.3 FormPaint

Now draw the thing.

4.3.3.4 FormShow

This is when the form is first shown. Also gets called by FormActivate when the ID of the bot being shown changes.

4.3.3.5 FormDestroy

Destroys the World in which the default bot lives in.

4.3.3.6 CloseButtonClick

Closes the bot form.

4.3.3.7 ShowRulesetButtonClick

Displays the Rule set of the current bot in the memo pad.

4.3.3.8 FormResize

This is the event that is called when bot form is resized.

4.3.3.9 FormClose

This disables the timer when the form is closed.

4.3.3.10 ShowEnvironmentButtonClick

This displays the window the environment the current bot is in.

4.3.3.11 FormActivate

If the bot has changed, show the new bot.

4.3.3.12 UpdateBotDisplay

Shows the bot and its sensors.

4.3.4 CBEP Modules

4.3.4.1 Create

Creates an instance of the TCBEP Object.

4.3.4.2 Destroy

Destroys an instance of the TCBEP Object.

4.3.4.3 GetRuleSet

Gets the Rule Sets from the Brain.

4.3.4.4 SetRuleSet

Sets the Rule set of a bot.

4.3.4.5 RobotWorld

Puts the bots in their worlds.

4.3.4.6 SetGPVars

Sets the GP Variables in the Brain.

4.3.4.7 SensorToAction

Sends sensors to the Brain and receives corresponding actions.

4.3.4.8 SetFitnesses

Sends bot fitness values to the Brain.

4.3.4.9 InitialiseRuleSets

Initialises bot Rule Sets.

4.3.4.10 Mirror

Implements mirroring (see section 3.3 on page 13 of this document.)

4.3.4.11 Error

Informs the user of an Invalid CBEP Message & Exits BOTSsim.

4.3.5 FastEval Modules

4.3.5.1 CreateTree

Creates the rule set trees.

4.3.5.2 DestroyTree

Destroys the rule set trees.

4.3.5.3 IfClause

Processes the String if it begins with I

4.3.5.4 Action

Processes the String if it doesn't begin with I

4.3.5.5 WallSensor

Determine which wall sensor the string is referring to.

4.3.5.6 WhichB

Determine which block sensor the string is referring to.

4.3.5.7 WhichG

Determine which Go action the string is referring to.

4.3.5.8 WhichT

Determine which turn action the string is referring to.

4.3.5.9 BinSensor

Determine which bin sensor the string is referring to.

4.3.5.10 BlockSensor

Determine which block sensor the string is referring to.

4.3.5.11 BotSensor

Determine which bot sensor the string is referring to.

4.3.5.12 SensorMapping

Maps the sensor to an action.

4.3.5.13 GetAction

Maps the sensor to an action.

4.3.5.14 InitialiseRuleSets

Creates blank trees.

4.3.5.15 DestroyRuleSets

Destroys the current tree.

4.3.5.16 DestroyAllRuleSets

Destroys all trees.

4.3.5.17 ShowRuleSet

Displays the rule set of the bot.

4.3.5.18 TokenToString

Converts a token to a string.

4.3.6 Fitness Modules

4.3.6.1 CalculateFitness

Calculates the refined fitness from the raw fitness. The different fitness functions tried are described in section 3.2 on page 11 of this report.

4.3.7 Hits Modules

4.3.7.1 FormShow

Recalculates & Shows The Updated Hits Histogram.

4.3.7.2 ResetHistogramClick

Handles The Single Click On The Update Histogram Button.

4.3.7.3 CancelBtnClick

Closes The Hits Histogram Window.

4.3.7.4 ResetHitsHistogram

Recalculates The Hits Histogram.

4.3.8 MainForm Modules

4.3.8.1 FileSaveRunClick

Saves The Current Run's TED, RIF & SEX Files.

4.3.8.2 FileNewRunClick

Creates A New Run with TED, RIF & SEX Files.

4.3.8.3 FileOpenRunClick

Opens An Existing Run with TED, RIF & SEX Files.

4.3.8.4 FileExitClick

4.3.8.5 Exits the application.

4.3.8.6 FileOpenTemplateClick

Opens an existing Template via the TED Form.

4.3.8.7 EditTemplateClick

Switches control to the TED Window.

4.3.8.8 EditRunInfoClick

Switches control to the Run Information Dialogue.

4.3.8.9 RunStartRunClick

Starts a Run. Clone Worlds, Run Brain, Init Brain, Assign Bots, Evaluate.

4.3.8.10 RunPauseRunClick

Pauses / Unpauses a Run.

4.3.8.11 RunResetRunClick

Resets The Run.

4.3.8.12 ViewHitsHistogramClick

Opens & switches control to the Hits Histogram Window.

4.3.8.13 ViewCommunicationsClick

Shows The Communications Debug Dialogue.

4.3.8.14 ShowEnvironment

Shows the appropriate Environment Display Window.

4.3.8.15 ShowBot

Shows the appropriate Bot Display Window.

4.3.8.16 BotMenuClick

This gets called every time the "Show Bot" menu is displayed.

4.3.8.17 BotShowAnotherBotClick

Shows the Show Bot By ID Dialogue.

4.3.8.18 HelpTopicsClick

This procedure gives the user help on BOTSsim when they press Help à Help Topics

4.3.8.19 HelpAboutClick

Displays the Help About Box.

4.3.8.20 FormCreate

Changes to the appropriate directory for BOTSsim. Assigns BOTSsim an appropriate BOTSsim Help File. Disallows the ability to start a Run.

4.3.8.21 FormClose

Close The Brain Component As Well.

4.3.8.22 AnimationTimerTimer

Animates the Environments.

4.3.8.23 EndOfGeneration

Sends the Bots' Fitness Levels to the Brain...

4.3.8.24 AllowRun

Enables the Run Feature.

4.3.8.25 DisallowRun

Disables the Run Feature.

4.3.8.26 AllowStartRun

Enables the Start Run Feature.

4.3.8.27 DisallowStartRun

Disables the Start Run Feature.

4.3.8.28 UpdateRunDisplay

Updates the RUN Display on the Status Bar.

4.3.8.29 UpdateTemplateDisplay

Updates the TED Display on the Status Bar.

4.3.8.30 UpdateRunInfoDisplay

Updates the TED Display on the Status Bar.

4.3.9 Run Information Modules

4.3.9.1 FormCreate

Initialises all of the Run Information Variables so that they

start within their specified ranges before the the initial

Display of the Run Information Dialogue.

4.3.9.2 FormShow

Displays all of the desired Run Information values.

4.3.9.3 OpenBtnClick

Open The Desired Run Information File.

4.3.9.4 SaveBtnClick

Verify any changes made, save validated changes.

4.3.9.5 CloseBtnClick

Cancel any changes made & close the dialogue.

4.3.9.6 HelpBtnClick

Raises the Help Window.

4.3.9.7 SetModifiedFlag

Sets the modified flag to TRUE.

4.3.9.8 ClearModifiedFlag

Sets the modified flag to FALSE.

4.3.9.9 SetEnvironmentVars

Copies the Run Information Dialogue's Environment Variables over

the Environment Variables used by the actual Environment Component.

4.3.9.10 RetrieveRunInformation

Retrieves the Run Information Variables.

4.3.9.11 ValidateRunInformation

Validates the Run Information Variables.

4.3.9.12 SetPopulationSize

Sets the PopulationSize to the appropriate value.

4.3.10 Runs Modules

4.3.10.1 SaveRun

Saves the Run file.

4.3.10.2 SaveRuleSets

Saves the rule sets.

4.3.10.3 OpenRuleSets

Loads the rule sets.

4.3.11 Show Bot Modules

4.3.11.1 OKBtnClick

Sets the bot window to be the bot selected.

4.3.11.2 CancelBtnClick

Cancels the change bot number.

4.3.11.3 FormShow

Gets the bot number.

4.3.12 TED Modules

4.3.12.1 SaveTemplate

Saves a template.

4.3.12.2 OpenTemplate

Opens a template.

4.3.12.3 FormPaint

The Paint Event Gets Handled As A Draw Event.

4.3.12.4 CloseTEDClick

This procedure closes the form when the uses presses File à Close

4.3.12.5 HelpTopicsClick

This procedure gives the user help on TED when they press Help à Help Topics. NOTE--TED's Help Context ID is 400 in the Help File.

4.3.12.6 CreateBotClick

This procedure turns create mode on, and sets the create mode to be a robot.

4.3.12.7 CreateDAClick

This procedure turns create mode on, and sets the create mode to be a distribution area.

4.3.12.8 TemplateMouseDown

This is the event handler for mouse down.

4.3.12.9 FormCreate

Creates The TED Form.

4.3.12.10 CreateNewBot

This procedure checks that there are less than 20 bots, and if there are creates a new bot with centre at X,Y. if there are 20 bots already, it gives an error message.

4.3.12.11 CreateNewBin

This procedure checks that there are less than 20 distribution areas, and if there are creates a new bot with centre at X,Y. if there are 20 distribution areas already, it gives an error message.

4.3.12.12 CreateNewBlock

This procedure checks that there are less than 20 bins, and if there are creates a new bot with centre at X,Y. if there are 20 bins already, it gives an error message.

4.3.12.13 CreateNewWall

Creates a new wall.

4.3.12.14 Draw

This procedure redraws the world

4.3.12.15 PointDistance

This procedure returns the distance from StartX,Y to EndX,Y

4.3.12.16 TemplateMouseUp

The mouse up event handler.

4.3.12.17 CreateWallClick

This procedure turns create mode on, and sets the create mode to be a wall.

4.3.12.18 CreateBinClick

This procedure turns create mode on, and sets the create mode to be a bin.

4.3.12.19 TemplateMouseMove

The mouse move event handler.

4.3.12.20 EditDestroyClick

Destroys the current object.

4.3.12.21 EditChangePropertiesClick

This procedure allows you to change the properties of the currently selected Object--colour basically.

4.3.12.22 TemplateSaveClick

Saves The Current Template File.

4.3.12.23 TemplateSaveAsClick

Saves The Current Template File With The Given Name.

4.3.12.24 TemplateOpenClick

Opens a template.

4.3.12.25 TemplateNewClick

Creates a new template.

4.3.12.26 CreateNewTemplate

This procedure resizes the template information.

4.3.12.27 FormKeyPress

Converts Keystrokes To Events.

4.3.12.28 AboutClick

Shows The About Box.

4.3.12.29 ZoomInClick

Increases the Camer Zoom for the Template.

4.3.12.30 ZoomOutClick

Decreases the Camer Zoom for the Template.

4.3.12.31 UpdateZoomLevel

Updates Display Of The Zoom Level.

4.3.12.32 CreateBoundaryWalls

This procedure creates the 4 boundary walls

4.3.12.33 FormClose

Checks Whether The Template Needs Saving Or Not.

4.3.12.34 FormResize

Resizes the Scrool Box with the For.

4.3.12.35 TemplatePaint

Redraws The Template.

4.3.12.36 IsTemplateValid

Returns whether the current Template is valid enough for Running.

4.3.12.37 UpdateTemplateScroller

Updates The Height, Width & Ranges On The Scroller.

4.3.13 ViewAnEnvironment Modules

4.3.13.1 OKBtnClick

Creates a new Environment Window if any more are allowed.

4.3.13.2 CancelBtnClick

Closes the Dialogue.

4.3.13.3 FormShow

Updates the Prompt Caption when the Dialogue is displayed.

4.3.14 ViewEnvironment Module

4.3.14.1 FormCreate

Create The Bitmap For Double Buffering.

4.3.14.2 FormClose

Disables The Update Display Timer and Frees This Environment Window.

4.3.14.3 FormShow

Sets Values For The Environment Display.

4.3.14.4 FormResize

Sets Values For The Environment Display.

4.3.14.5 FormPaint

A Repaint Message Causes A Redraw Of The Displayed Environment.

4.3.14.6 FormMouseMove

Changes The Camera Zoom And Updates The Display.

4.3.14.7 FormMouseDown

Shows The Clicked On Bot Or Enables Zooming Changes.

4.3.14.8 FormMouseUp

Disables Zooming Changes.

4.3.14.9 UpdateDisplayTimer

Update The Environment Display.

4.3.14.10 UpdateEnvironmentScroller

Updates The Height, Width & Ranges On The Scroller.

4.3.15 World Module

4.3.15.1 OKBtnClick

Gets the height and the width from the user, and passes them back to TED.

4.4 BRAIN COMPONENT INFORMATION

This section contains programmer information about the Brain Component. It is in a form that genetic programmers should be comfortable with.

4.4.1 Component Description

Purpose: The Brain provides a genetic prograing and program evaluation service to the GUI and Environment components, respectively. It not only optimises the control algorithms of individual simulated robots in the population but executes these control algorithms as well.

Coupling: Coupling is achieved via sockets, counicating using the CBEP protocol.

4.4.2 Files

4.4.2.1 bots-problem-function.lsp

4.4.2.1.1 Purpose

Defines the BOTS optimisation problem in a way that the gp-kernel can operate on.

4.4.2.1.2 Person Responsible

Mark Greenaway

4.4.2.1.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.1.4 Contained Modules

define-terminal-set-for-BOTS

define-function-set-for-BOTS

if-HasBlock-implementation

if-BlockCollide-implementation

if-WallForward-implementation

if-WallBackward-implementation

if-WallLeft-implementation

if-WallRight-implementation

if-BotForward-implementation

if-BotBackward-implementation

if-BotLeft-implementation

if-BotRight-implementation

if-BlockForward-implementation

if-BlockBackward-implementation

if-BlockLeft-implementation

if-BlockRight-implementation

if-BinForward-implementation

if-BinBackward-implementation

if-BinLeft-implementation

if-BinRight-implementation

if-BlockCollide

if-WallForward

if-WallBackward

if-WallLeft

if-WallRight

if-BotForward

if-BotBackward

if-BotLeft

if-BotRight

if-BlockForward

if-BlockBackward

if-BlockLeft

if-BlockRight

if-BinForward

if-BinBackward

if-BinLeft

if-BinRight

define-fitness-cases-for-BOTS

evaluate-standardized-fitness-for-BOTS

define-parameters-for-BOTS

termination-criteria-for-bots

4.4.2.2 brain-var.lsp

4.4.2.2.1 Purpose

Define Brain module variables which need to be shared among other modules.

4.4.2.2.2 Person Responsible

David Formosa

4.4.2.2.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.2.4 Contained Modules

*population-size*

*number-of-factories*

*maximum-generations*

*bot-factory-groupings*

4.4.2.3 brain.lsp

4.4.2.3.1 Purpose

Run genetic prograing system as a whole. Create a CBEP socket, and then run the genetic prograing system contained in gp-kernel.lsp

4.4.2.3.2 Person Responsible

Mark Greenaway

4.4.2.3.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.3.4 Contained Modules

brain

place-robots-in-environments

4.4.2.4 fast-eval.lsp

4.4.2.4.1 Purpose

Streamlined function to evaluate simple LISP-like expressions. Used to speed evaluation of the control programs of individual Bots.

4.4.2.4.2 Person Responsible

John Koza, some additional modification by David Formosa

4.4.2.4.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.4.4 Contained Modules

fast-eval-fun

fast-eval

install-pseudo-macro

4.4.2.5 gp-kernel-var.lsp

4.4.2.5.1 Purpose

Share gp-kernel variables among other modules.

4.4.2.5.2 Person Responsible

David Formosa

4.4.2.5.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.5.4 Contained Modules

*number-of-fitness-cases* ^M

*max-depth-for-new-individuals* ^M

*max-depth-for-individuals-after-crossover* ^M

*fitness-proportionate-reproduction-fraction* ^M

*crossover-at-any-point-fraction* ^M

*crossover-at-function-point-fraction* ^M

*max-depth-for-new-subtrees-in-mutants* ^M

*method-of-selection* ^M

*method-of-generation*

*seed*

*best-of-run-individual*

*generation-of-best-of-run-individual*

*sensor-reading*

*terminate-brain*

4.4.2.6 gp-kernel.lsp

4.4.2.6.1 Purpose

Provide basic genetic programming facilities, to be used in optimisation.

4.4.2.6.2 Person Responsible

John Koza, with minor modifications by David Formosa and Mark Greenaway

4.4.2.6.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.6.4 Modified Modules

run-genetic-prograing-system

evaluate-fitness-of-population

4.4.2.7 link.lsp

4.4.2.7.1 Purpose

Setup and close CBEP socket connections.

4.4.2.7.2 Person Responsible

David Formosa

4.4.2.7.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.7.4 Contained Modules

*CBEP-stream*

open-cbep

close-cbep

4.4.2.8 parser.lsp

4.4.2.8.1 Purpose

Parse CBEP protocol messages received and perform the appropriate action as defined in semantics.lsp

4.4.2.8.2 Person Responsible

David Formosa

4.4.2.8.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.8.4 Contained Modules

domessage

parser

test-modules

4.4.2.9 semantics.lsp

4.4.2.9.1 Purpose

Perform appropriate actions for CBEP protocol messages, such as setting fitness values etc.

4.4.2.9.2 Person Responsible

Mark Greenaway, with mirroring support added by David Formosa

4.4.2.9.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.9.4 Contained Modules

makecall

sensorcall

fitnesslevelcall

getrulesetcall

setruleset

test-if-valid-variable

SetGPVariablescall

errorcall

closecall

mirrorcall

make-new-tree

4.4.2.10 sendmessage.lsp

4.4.2.10.1 Purpose

Send CBEP protocol messages to the GUI/Environment.

4.4.2.10.2 Person Responsible

David Formosa

4.4.2.10.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.10.4 Contained Modules

send-action

send-RobotEnvironment-message

4.4.2.11 sensor.lsp

4.4.2.11.1 Purpose

Define sensor structure used to pass sensor values around the Brain component.

4.4.2.11.2 Person Responsible

Mark Greenaway

4.4.2.11.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.4.2.11.4 Contained Modules

sensor

4.4.3 Functions and variables

4.4.3.1 bots-problem-function.lsp

4.4.3.1.1 define-terminal-set-for-BOTS()
Description: "Define terminal set for BOTS. "
4.4.3.1.2 define-function-set-for-BOTS()
Description: "Define function set for BOTS. "

4.4.3.1.3 if-HasBlock-implementation (if-clause else-clause)
4.4.3.1.4 if-BlockCollide-implementation (if-clause else-clause)
4.4.3.1.5 if-WallForward-implementation (if-clause else-clause)
4.4.3.1.6 if-WallBackward-implementation (if-clause else-clause)
4.4.3.1.7 if-WallLeft-implementation (if-clause else-clause)
4.4.3.1.8 if-WallRight-implementation (if-clause else-clause)
4.4.3.1.9 if-BotForward-implementation (if-clause else-clause)
4.4.3.1.10 if-BotBackward-implementation (if-clause else-clause)
4.4.3.1.11 if-BotLeft-implementation (if-clause else-clause)
4.4.3.1.12 if-BotRight-implementation (if-clause else-clause)
4.4.3.1.13 if-BlockForward-implementation (if-clause else-clause)
4.4.3.1.14 if-BlockBackward-implementation (if-clause else-clause)
4.4.3.1.15 if-BlockLeft-implementation (if-clause else-clause)
4.4.3.1.16 if-BlockRight-implementation (if-clause else-clause)
4.4.3.1.17 if-WallBackward-implementation (if-clause else-clause)
4.4.3.1.18 if-WallLeft-implementation (if-clause else-clause)
4.4.3.1.19 if-WallRight-implementation (if-clause else-clause)
4.4.3.1.20 if-BotForward-implementation (if-clause else-clause)
4.4.3.1.21 if-BotBackward-implementation (if-clause else-clause)
4.4.3.1.22 if-BotLeft-implementation (if-clause else-clause)
4.4.3.1.23 if-BotRight-implementation (if-clause else-clause)
4.4.3.1.24 if-BlockForward-implementation (if-clause else-clause)
4.4.3.1.25 if-BlockBackward-implementation (if-clause else-clause)
4.4.3.1.26 if-BlockLeft-implementation (if-clause else-clause)
4.4.3.1.27 if-BlockRight-implementation (if-clause else-clause)
4.4.3.1.28 if-BinForward-implementation (if-clause else-clause)
4.4.3.1.29 if-BinBackward-implementation (if-clause else-clause)
4.4.3.1.30 if-BinLeft-implementation (if-clause else-clause)
4.4.3.1.31 if-BinRight-implementation (if-clause else-clause)
4.4.3.1.32 if-BlockCollide (if-clause else-clause)
4.4.3.1.33 if-WallForward (if-clause else-clause)
4.4.3.1.34 if-WallBackward (if-clause else-clause)
4.4.3.1.35 if-WallLeft (if-clause else-clause)
4.4.3.1.36 if-WallRight (if-clause else-clause)
4.4.3.1.37 if-BotForward (if-clause else-clause)
4.4.3.1.38 if-BotBackward (if-clause else-clause)
4.4.3.1.39 if-BotLeft (if-clause else-clause)
4.4.3.1.40 if-BinBackward-implementation (if-clause else-clause)
4.4.3.1.41 if-BinLeft-implementation (if-clause else-clause)
4.4.3.1.42 if-BinRight-implementation (if-clause else-clause)
4.4.3.1.43 if-BlockCollide (if-clause else-clause)
4.4.3.1.44 if-WallForward (if-clause else-clause)
4.4.3.1.45 if-WallBackward (if-clause else-clause)
4.4.3.1.46 if-WallLeft (if-clause else-clause)
4.4.3.1.47 if-WallRight (if-clause else-clause)
4.4.3.1.48 if-BotForward (if-clause else-clause)
4.4.3.1.49 if-BotBackward (if-clause else-clause)
4.4.3.1.50 if-BotLeft (if-clause else-clause)
4.4.3.1.51 if-BotRight (if-clause else-clause)
4.4.3.1.52 if-BlockForward (if-clause else-clause)
4.4.3.1.53 if-BlockBackward (if-clause else-clause)
4.4.3.1.54 if-BlockLeft (if-clause else-clause)
4.4.3.1.55 if-BlockRight (if-clause else-clause)
4.4.3.1.56 if-BinForward (if-clause else-clause)
4.4.3.1.57 if-BinBackward (if-clause else-clause)
4.4.3.1.58 if-BinLeft (if-clause else-clause)
4.4.3.1.59 if-BinRight (if-clause else-clause)
4.4.3.1.60 define-fitness-cases-for-BOTS()
Description: "Define fitness cases for BOTS. "

4.4.3.1.61 evaluate-standardized-fitness-for-BOTS(program fitness-cases)
Description: "Evaluate standardized fitness for BOTS individuals. "

4.4.3.1.62 define-parameters-for-BOTS()
4.4.3.1.63 termination-criteria-for-bots(current-generation

4.4.3.1.64 BOTS ()
Description: "Define problem function for the BOTS system. "

4.4.3.2 brain-var.lsp

4.4.3.2.1 *population-size* :unbound
Description: "The size of the population used in the current run. ")
Type: Integer

4.4.3.2.2 *number-of-factories* :unbound
Description: "The number of factories to be used in evaluation of sub-groups of the population. ")
Type: Integer
4.4.3.2.3 *maximum-generations* 0
Description: "The maximum number of generations that the GP kernel system should continue a run for. ")
Type: Integer
4.4.3.2.4 *bot-factory-groupings* :unbound
Description: "The way bots are grouped to be put into separate factories for evaluation. probably would..."
Type: Array [1..*number-of-factories*] of lists of bot numbers belonging in that factory

4.4.3.3 brain.lsp

4.4.3.3.1 brain()
Description: "Main function which runs the Brain component of the BOTS system, using the GP kernel to provide optimisation services for the GUI component."
4.4.3.3.2 place-robots-in-environments(number-of-individuals number-of-factories)M
Description: "Return a list detailing which robots should go into which factories for evaluation purposes. This information is constant for a run."

4.4.3.4 fast-eval.lsp

Macro: fast-eval-fun ()
Description: "A code body that does fast evaluation of a functional expression. This is a streamlined verson of the fast-eval it strips out the support for functions outher then thouse haveing 2 arguments.
4.4.3.4.1 fast-eval (expr)
Description: "A fast evaluator that can be used with the Genetic Prograing Paradigm for the Allegro LISP system."

4.4.3.4.2 install-pseudo-macro (name implementation)
Description: "Install a pseudo-macro called Name, which is implemented by the function Implementation."

4.4.3.5 gp-kernel-var.lsp

4.4.3.5.1 *sensor-reading* M
Description: "The sensor reading for the bot currently being evaluated "M
Type: A sensor structure. See below.

4.4.3.5.2 *terminate-brain*M
Description: "Boolean variable dictating whether we should halt brain execution or not. "
Type: A boolean variable.

4.4.3.6 gp-kernel.lsp

run-genetic-prograing-system

4.4.3.6.1 evaluate-fitness-of-population (population fitness-cases
Description: "Loops over the individuals in the population evaluating and recording the fitness and hits."

4.4.3.7 link.lsp

4.4.3.7.1 *CBEP-stream* nil
Description: "This is the stream for CBEP coinactions. "
Type: A LISP stream.

4.4.3.7.2 open-CBEP (&optional (port *CBEP-server*))
Description: "Opens up a CBEP connection. Blocks untill the clinet connects "

4.4.3.7.3 close-CBEP ()
Description: "Close the CBEP connection. "

4.4.3.8 parser.lsp

4.4.3.8.1 domessage ()
Description: "Read in and procesess messages, exiting if the flow of exiction should continue. "
4.4.3.8.2 parser (message)
Description: "Parse a message from the protocol "
4.4.3.8.3 test-modules ()
Description: "This is a simple test module that tests wether the cepb protocol is working.

4.4.3.9 semantics.lsp

Macro: makecall (funname docstring)

Description: "This is stub module generator. It creates stub functions so I don't have to do it."
4.4.3.9.1 sensorcall (message)
Description: "Load sensor values into the sensor struct and then call the mapping function"
4.4.3.9.2 fitnesslevelcall (message)
Description: "Load fitness levels into the Brain and continue with the flow of execution. "
4.4.3.9.3 getrulesetcall(bot-number)
Description: "Get the rule set for a bot."

This function MUST return a rule set message (as defined in BottsS04) and the argument to this is a bot number.

4.4.3.9.4 setruleset(message)
Description: "Set a rule set for a bot"
4.4.3.9.5 test-if-valid-variable (element)
Description: "Returns true if the variable name contained in (first element) is valid for us the SetGPVariables message. See the BotsS04 standard for further details."
4.4.3.9.6 SetGPVariablescall (message)
Description: "Set the gp variables and continue with the flow of execution. "
Using macro: makecall ResetBrain()
Description: "Cause orderly shutdown and restart of the Brain. If this is ever implemented I'll be very surprised. "
4.4.3.9.7 errorcall(message)
Description: "Gets called when the parser dosen't parse. "
4.4.3.9.8 closecall(message)
Description: "Close the connection and cause a semi-orderly shutdown of the brain "
4.4.3.9.9 mirrorcall(message)
Description: Perform the process known as mirroring to half of the population, and remove the other half of the population. See section 3.3 on page 13 of this document for more information about mirroring.

4.4.3.9.10 make-new-tree
Description: Take a current individual rule set and return a mirrored individual corresponding to that rule set, with certain functions and terminals swapped as described in the section on mirroring. See section 3.3 on page 13 of this document for more information about mirroring.

4.4.3.10 sendmessage.lsp

4.4.3.10.1 send-action (action)
Description: "Pseudo send. Perpears a action message from a message. "
4.4.3.10.2 send-RobotEnvironment-message (bot-factory-groupings)
Description: "True send. Sends a RobotEnviroment-Message. "

4.4.3.11 sensor.lsp

Nothing relevant

4.4.4 Data Structure Descriptions

sensor

Description: A structure to hold the various true or false values corresponding to various sensor readings.

Elements:

Boolean values. The meaning of each is described in the standard BotsS01.

HasBlock

BlockCollide

WallForward

WallBackward

WallLeft

WallRight

BotForward

BotBackward

BotLeft

BotRight

BlockForward

BlockBackward

BlockLeft

BlockRight

BinForward

BinBackward

BinLeft

BinRight

4.5 ENVIRONMENT COMPONENT INFORMATION

This section contains programmer information about the Environment Component. It is in a form that object-orientated programmers should be comfortable with. Note that some of the information contained in this section is duplicated in other parts of this document in a more traditional form.

4.5.1 Introduction

4.5.1.1 Synopsis

This section is a brainstorm on how the environment component might be structured, as well as how the components might interacts. It is intended mainly to inspire, encourage and indeed offend people. J

4.5.1.2 Functions provided by the environment

For the display of the world, we will need some coupling that isn't too tight, but at the same time doesn't restrict flexibility. The most complicated thing I can think of is to allow dragging of objects to reposition them within the world. This would require knowledge of the object's appearance by the user interface.

Now for general display of the entire world, there could be a camera object in the world which is manipulated by the user. A function would be called to pass what is seen by this camera to the GUI component, possibly as a bitmap, possibly as a series of vectors or lines. This would enable the GUI to display the world without really having to know anything about what's in it.

For dragging of objects, this is what we could do: the GUI could receive a description of the object as seen by the camera, and use that description for dragging and creating. A procedure to get this description would have to be called every time an object is created or moved, since the object as seen by the user depends on the position (i.e. distance) of the camera.

OR, the GUI could have direct access to all the data that is necessary to draw the world and draw each individual object, in any camera position. This would give the entire job of display to the GUI, but will mean rather tight coupling.

4.5.1.3 Creation of generations by the Genetic Algorithm

In the very simplest terms, the way the artificial intelligence is supposed to `train' the Bots is by `evaluating' a large population of Bots, and picking out the most useful ones. This means the brain component will have to be able to manipulate the Bots, and possibly the environment(s), so as to `train' the large number of Bots necessary. This in turn will mean certain control might have to be given to the brain component This is not much of an issue as yet, but it might result in discrepancies with abstraction and coupling. I'll shut up about it for now...

4.5.1.4 Design of Bots

We want to allow the Bots be as configurable as possible, to give the project the flexibility should we decide to exploit it. It might be useful to be able to add things like control of the Bots' maneuverability and speed, or the positions (or indeed types) of their sensors.

To do this the appropriate information will need to be controlled by the user, and coordinated by the environment. The brain component might want to be able to query the capabilities of its Bot, if the corresponding team decides to pursue implementation of the ability to totally reconfigure sensors at runtime.

4.5.1.5 Saving and Restoring of worlds

This is what could happen: The save and restore commands are in the GUI component. The save procedure save any necessary global settings, and then calls a save procedure in the world component to save the state of the world. The world saves its global settings, and then in turn calls save routines for each object to save their states. The Bot's save routine will call an appropriate routine in the brain component to save necessary state information there. And so the program will traverse a tree of `savable' objects, getting each objects to save its state information as it goes, until eventually everything has been saved. This is what I did with SFXy, and it worked very well.

4.5.2 Environment Module (Environment.pas)

4.5.2.1 Non-Object Types

4.5.2.1.1 TBotAction
type TBotAction=(goForward,goBackward,turnLeft,turnRight,getBlock,dropBlock,NoOp);
4.5.2.1.2 TThingClass
type TThingClass=classofTSimThing;

4.5.2.1.3 TRoundThingClass
type TThingClass=classofTRoundThing;

4.5.2.1.4 TThingArray, PThingArray
type TThingArray=array[0..10000]ofTSimThing; type PThingArray=^TThingArray;

This type is used internally by the environment component for the storage of SimThings.

Note that it does NOT simply allocate an array of 10000 SimThings when it is created! Despite the specification of an array size, the type can be, and is, used to allocate a smaller (or larger) array.

4.5.2.2 Constants

4.5.2.2.1 SENSORCOUNT

Set to the number of sensors that Bots have.

4.5.2.2.2 HoldingBlock, CollideBlock, WallForward, WallBackward, WallLeft, WallRight, BotForward, BotBackward, BotLeft, BotRight, BlockForward, BlockBackward, BlockLeft, BlockRight, BinForward, BinBackward, BinLeft, BinRight

These constants are for indexes into the sensor array of the T B o t object. They can be used to find the values of any sensor of any Bot after a call to T W o r l d . A n i m a t e.

4.5.2.3 Global Variables and Properties

4.5.2.3.1 SelColor

Determines the color of the dotted line that encloses the currently selected Thing.

4.5.2.3.2 NewBlockColor

Block that appear from Distribution Areas get their colour from this variable.

4.5.2.3.3 BotTurnSpeed

v a r B o t T u r n S p e e d : e x t e n d e d ;

Specifies how fast Bots can turn, in radians per frame.

4.5.2.3.4 BotMoveSpeed

v a r B o t M o v e S p e e d : e x t e n d e d ;

Specifies how fast Bots can move, in millimetres per frame.

4.5.2.3.5 FitnessOnMove

v a r F i t n e s s O n M o v e : e x t e n d e d ;

Determines the amount of fitness that gets added to a Bot's fitness level for each frame it moves or turns.

4.5.2.3.6 FitnessOnPickUp

v a r F i t n e s s O n P i c k U p : e x t e n d e d ;

Determines the amount of fitness that gets added to a Bot's fitness level when it picks up a Block.

4.5.2.3.7 FitnessOnFloorDrop

v a r F i t n e s s O n F l o o r D r o p : e x t e n d e d ;

Determines the amount of fitness that gets added to a Bot's fitness level when it drops a Block outside a Bin.

4.5.2.3.8 FitnessOnBinDrop

v a r F i t n e s s O n B i n D r o p : e x t e n d e d ;

Determines the amount of fitness that gets added to a Bot's fitness level when it drops a Block in the correct Bin.

4.5.2.3.9 FitnessOnBadDrop

v a r F i t n e s s O n B a d D r o p : e x t e n d e d ;

Determines the amount of fitness that gets added to a Bot's fitness level when it drops a Block in the wrong Bin.

This variable serves no purpose at present. It will be useful when the Bots are to drop Blocks into Bins of the same colour.

4.5.2.3.10 StartFitness

v a r S t a r t F i t n e s s : e x t e n d e d ;

Determines the fitness level that gets assigned to every Bot in the World when the simulation starts (i.e. when the I n i t S i m u l a t i o n method is called).

4.5.2.3.11 DeathFitness

v a r D e a t h F i t n e s s : e x t e n d e d ;

Determines the fitness level that will cause a Bot to die should its fitness fall below this level. This variable is only useful if the M o r t a l B o t s variable (below) is set to T r u e.

Note that a Bot will not actually be destroyed by a d e s t r o y method call when it reaches this point. It will only cease to be a part of the simulation. This is so that if an application is analyzing this Bot during the simulation (displaying statistics to the user, for example), an exception will not result when the Bot dies.

4.5.2.3.12 MortalBots

v a r D e a t h F i t n e s s : e x t e n d e d ;

Determines whether Bots can die.

4.5.2.3.13 BotSize

v a r B o t S i z e : e x t e n d e d ;

Specifies the radius (half of the width) of a Bot. Initially set to 75 millimetres.

4.5.2.3.14 BlockSize

v a r B l o c k S i z e : e x t e n d e d ;

Specifies the radius (half of the width) of a Block. Initially set to 50 millimetres.

4.5.2.3.15 DistAreaSize

v a r D i s t A r e a S i z e : e x t e n d e d ;

Specifies the radius (half of the width) of a Distribution Area. Initially set to 60 millimetres.

4.5.2.3.16 BinSize

v a r B i n S i z e : e x t e n d e d ;

Specifies the radius (half of the width) of a Bin. Initially set to 70 millimetres.

4.5.2.3.17 TimeStepsPerGeneration

v a r T i m e S t e p s P e r G e n e r a t i o n : i n t e g e r ;

Determines how many frames of simulation complete an evaluation. (This should be in e v a l u t a t i o n . p a s)

4.5.2.4 Object Hierarchy

4.5.2.4.1 TWorld

Tworld

4.5.2.4.1.1 Properties
4.5.2.4.1.1.1 DisplayBotIds

p r o p e r t y D i s p l a y B o t I d s : b o o l e a n ;

This flag is false on creation of a T W o r l d object. If set to true, each Bot in the World will be displayed with its Id property near it, in decimal, to aid in visual identification.

4.5.2.4.1.1.2 CameraX, CameraY

p r o p e r t y C a m e r a X : e x t e n d e d ;

p r o p e r t y C a m e r a Y : e x t e n d e d ;

D e t e r m i n e s w h i c h p a r t o f t h e W o r l d g e t s d i s p l a y e d b y a D r a w m e t h o d . T h e c o o r d i n a t e s r e f e r e n c e d b y t h e s e p r o p e r t i e s w i l l b e m a p p e d t o t h e s c r e e n c o o r d i n a t e s r e f e r e n c e d b y W i n d o w C e n t e r X a n d W i n d o w C e n t e r Y , d e s c r i b e d b e l o w .

4.5.2.4.1.1.3 CameraZoom

p r o p e r t y C a m e r a Z o o m : e x t e n d e d ;

Determines how big everything is, as it is seen by the results of a D r a w method. If C a m e r a Z o o m i s 1 , o n e m i l l i m e t r e m a p s t o o n e p i x e l o n t h e s c r e e n .

4.5.2.4.1.1.4 WindowCenterX, WindowCenterY

p r o p e r t y W i n d o w C e n t e r X : i n t e g e r ;

p r o p e r t y W i n d o w C e n t e r Y : i n t e g e r ;

These values define the point on the Canvas where the camera is directed, for the purpose of drawing. They can be left at the creation-defaults of (0, 0), but zooming will then be centered on the top-left corner of the Canvas, and that will look funky. The application should keep these coordinates at the center of the Canvas, by intercepting resize events.

4.5.2.4.1.1.5 id

p r o p e r t y i d : i n t e g e r ;

This property is provided solely for outside use. An application may use this property to give each World a unique number for tracking or identification purposes.

4.5.2.4.1.2 Methods
4.5.2.4.1.2.1 Create

c o n s t r u c t o r C r e a t e ;

C r e a t e s a n e w e m p t y W o r l d . ( S e e G e n e s i s 1 : 1 )

4.5.2.4.1.2.2 Save

p r o c e d u r e S a v e ( v a r f : t e x t ) ;

Saves the entire World and the positions and properties of all of its SimThings to file f, in a text format interpretable by most unix fetishists.

4.5.2.4.1.2.3 Restore

p r o c e d u r e R e s t o r e ( v a r f : t e x t ) ;

Loads a World's state from a file, saved by the S a v e method described above.

4.5.2.4.1.2.4 Draw

p r o c e d u r e D r a w ( v a r C a n v a s : T C a n v a s ) ;

Draws the World and all its objects onto C a n v a s. Note that the canvas is not initially cleaned--this must be done by the application.

4.5.2.4.1.2.5 MouseToThing

f u n c t i o n M o u s e T o T h i n g ( x , y : i n t e g e r ) : T S i m T h i n g ;

Determines the SimThing that is selected by a mouse click at the screen coordinates passed to the function. Returns N I L if no object was clicked.

4.5.2.4.1.2.6 ScreenToReal

p r o c e d u r e R e a l T o S c r e e n ( x , y : i n t e g e r ; v a r n e w x , n e w y : e x t e n d e d ) ;

Converts the screen coordinates at (x, y) to the World's real coordinates, according to the current camera orientation determined by C a m e r a X, C a m e r a Y and C a m e r a Z o o m.

4.5.2.4.1.2.7 RealToScreen

p r o c e d u r e R e a l T o S c r e e n ( x , y : e x t e n d e d ; v a r n e w x , n e w y : i n t e g e r ) ;

Converts the real coordinates (x, y) within the World to screen coordinates, according to the current camera orientation determined by C a m e r a X, C a m e r a Y and C a m e r a Z o o m.

4.5.2.4.1.2.8 InitSimulation

p r o c e d u r e I n i t S i m u l a t i o n ;

Initializes the World and the SimThings contained within it, so that it is ready for a simulation.

4.5.2.4.1.2.9 Animate

p r o c e d u r e A n i m a t e ;

Processes one time frame of the simulation. Each Bot in the World is subsequently processed--its sensor information is calculated, then that information is sent to the Brain component for processing into an action, then the action is processed.

This procedure should be called periodically to affect the simulation proper. The speed of the simulation can be consequently controlled by the application.

This method must NOT be called before the I n i t S i m u l a t i o n method is called.

4.5.2.4.1.2.10 CountBots

f u n c t i o n C o u n t B o t s : i n t e g e r ;

Returns the number of Bots in the World. This function's primary use is to determine the size of the array that must be passed to the G e t B o t s method, described below.

4.5.2.4.1.2.11 GetBots

p r o c e d u r e G e t B o t s ( v a r B o t A r r a y : a r r a y o f T B o t ) ;

Places the object references of all of the Bots in the World into the array B o t A r r a y.

4.5.2.4.1.2.12 CountBins

f u n c t i o n C o u n t B i n s : i n t e g e r ;

Returns the number of Bins in the World.

4.5.2.4.1.2.13 CountDistAreas

f u n c t i o n C o u n t D i s t A r e a s : i n t e g e r ;

Returns the number of Distribution Areas in the World.

4.5.2.4.1.2.14 Clone

f u n c t i o n C l o n e : T W o r l d ;

Creates a copy of the World and all of its SimThings. Both Worlds are then independent copies of each other.

4.5.2.4.1.2.15 ClosestThing

f u n c t i o n C l o s e s t T h i n g ( B o t : T B o t ; T h i n g T y p e : T R o u n d T h i n g C l a s s ) : E x t e n d e d ;

Find the distance from B o t to the closest Thing of type T h i n g T y p e, in World units.

4.5.2.4.1.2.16 CalculateFitness

p r o c e d u r e C a l c u l a t e F i t n e s s ( v a r B o t : T B o t ) ;

Calculates B o t's fitness and stores it in its Fitness property.

4.5.2.4.2 TSimThing

TSimThing

This is the abstract class for the Bots, Walls, Blocks, Distribution Areas and Bins contained in a World. T S i m T h i n g objects should not be created, only subtypes of T S i m T h i n g should be created.

4.5.2.4.2.1 Properties
4.5.2.4.2.1.1 Color

p r o p e r t y C o l o r : i n t e g e r ;

The colour that the SimThing is when it is drawn. For now this serves no other purpose, but later it may be used to allow sorting of different colored Blocks into their corresponding Bins.

4.5.2.4.2.1.2 Owner

p r o p e r t y O w n e r : T W o r l d ;

Read-only. Stores the Owning world of this SimThing.

4.5.2.4.2.1.3 Selected

p r o p e r t y S e l e c t e d : B o o l e a n ;

If this value is set to T r u e when the D r a w method (or the D r a w method of this SimThing's owning world) is called, the SimThing will be drawn with a dashed border around it. This is so that a design program can give the user a distinction between a `current' SimThing and a non-`current' one.

4.5.2.4.2.2 Methods
4.5.2.4.2.2.1 Create

c o n s t r u c t o r C r e a t e ( W o r l d : T W o r l d ) ;

Creates the Thing in W o r l d. The initial position of the Thing is determined by the properties of the particular object being created.

4.5.2.4.2.2.2 Save

p r o c e d u r e S a v e ( v a r f : f i l e ) ;

Saves the state of the Thing, including its position within the World (but not what World it is in) to file f.

4.5.2.4.2.2.3 Restore

p r o c e d u r e R e s t o r e ( v a r f : f i l e ) ;

Restores the position and state of the Thing from file f.

4.5.2.4.2.2.4 Draw

p r o c e d u r e D r a w ( v a r C a n v a s : T C a n v a s ) ;

Draws the Thing in its position within the World onto C a n v a s.

This routine should only be called when the Thing is created. Otherwise, the World's Draw method should be called.

4.5.2.4.2.2.5 Clicked

f u n c t i o n C l i c k e d ( x , y : i n t e g e r ) : b o o l e a n ;

Determines if the SimThing has been clicked. x and y are screen coordinates.

Although this method is public, there should be no need for an application to use it. The T W o r l d . M o u s e T o T h i n g method can be used instead in most cases.

4.5.2.4.2.2.6 BotCollide

f u n c t i o n B o t C o l l i d e ( B o t : T B o t ) : b o o l e a n ;

Determines if B o t is intersecting this thing in its current position. This method should not be called outside e n v i r o n m e n t . p a s.

4.5.2.4.2.2.7 Detect

Detect(x,y,min,max,radius:extended):boolean;

determines if thus thing is intersecting the sensor perimeter created by x, y, m i n, m a x and r a d i u s. This method should not be called outside e n v i r o n m e n t . p a s.

4.5.2.4.2.2.8 Clone

f u n c t i o n C l o n e ( S o u r c e : T S i m T h i n g ) : b o o l e a n ;

Makes this Thing a 'copy' of S o u r c e, provided this Thing and S o u r c e are of the same class. Returns t r u e if successful.

4.5.2.4.3 TRoundThing

TSimThing

*TRoundThing

T R o u n d T h i n g is another abstract class, for Things with whose position can be determined by a single x/y coordinate pair and (optionally) a direction.

T R o u n d T h i n g objects should not be created.

4.5.2.4.3.1 Properties
4.5.2.4.3.1.1 X,Y

p r o p e r t y X : e x t e n d e d ;

p r o p e r t y Y : e x t e n d e d ;

Defines the coordinates of the center of the SimThing.

4.5.2.4.3.1.2 Direction

p r o p e r t y D i r e c t i o n : e x t e n d e d ;

Defines the orientation of the SimThing.

At present, this property is only used by the T B o t object. Other objects act and look the same regardless of the value of this property.

4.5.2.4.3.1.3 Carried

Determines if this Thing is currently being carried. Do NOT modify this property.

4.5.2.4.3.2 Methods

No uninherited methods for this object.

4.5.2.4.4 TWall

TSimThing

*TWall

This object is used to create boundaries that the Bots cannot move through.

4.5.2.4.4.1 Properties
4.5.2.4.4.1.1 StartX, StartY, EndX, EndY

p r o p e r t y S t a r t X : e x t e n d e d ;

p r o p e r t y S t a r t Y : e x t e n d e d ;

p r o p e r t y E n d X : e x t e n d e d ;

p r o p e r t y E n d Y : e x t e n d e d ;

Determines the positions of both ends of the Wall.

4.5.2.4.4.2 Methods

No uninherited methods for this object.

4.5.2.4.5 TBot

TSimThing

*TRoundThing*TBot

4.5.2.4.5.1 Properties
4.5.2.4.5.1.1 Sensor

S e n s o r : a r r a y [ 0 . . S E N S O R C O U N T ] o f b o o l e a n ;

Contains the values of the Bot's sensors after a call to it's owning World's A n i m a t e method. This array should not be modified.

4.5.2.4.5.1.2 id

p r o p e r t y i d : i n t e g e r ;

This is the number that gets passed to the Brain component to identify the Bot whose sensor information is to be processed into an action. The i d property of all of the Bots in a World MUST be set to the appropriate values before any call to the World's A n i m a t e method.

4.5.2.4.5.1.3 Carrying

p r o p e r t y C a r r y i n g : T B l o c k ;

Read-only. Determines which Block the Bot is carrying at any particular instant, if any. If the Bot is not carrying a Block, C a r r y i n g is set to N I L, otherwise it references the Block object that is being carried.

4.5.2.4.5.1.4 Hits

p r o p e r t y H i t s : i n t e g e r ;

Read-only. Specifies the number of blocks that this Bot has successfully dropped in the correct Bin. Set to 0 by a call to the World's I n i t S i m u l a t i o n method.

4.5.2.4.5.1.5 Drops

p r o p e r t y D r o p s : i n t e g e r ;

Read-only. Specifies the number of Blocks that this Bot has dropped, whether inside or outside a

Bin. Set to 0 by a call to the World's I n i t S i m u l a t i o n method.

4.5.2.4.5.1.6 Rank

p r o p e r t y R a n k : i n t e g e r ;

This variable is not affected by any method calls. It can be used by the application to rank Bots over several Worlds.

4.5.2.4.5.1.7 Pickups

p r o p e r t y P i c k u p s : i n t e g e r ;

Read-only. Specifies the number of blocks that this Bot has picked up. Set to 0 by a call to the World's I n i t i S i m u l a t i o n method.

4.5.2.4.5.1.8 Fitness

p r o p e r t y F i t n e s s : e x t e n d e d ;

Read-only. Specifies the current fitness of this Bot. This value changes as the Bot performs certain actions. The way this value changes is determines by the FitnessOnMove and similar global variables, described in a previous section.

4.5.2.4.5.2 Methods

No uninherited methods for this object.

4.5.2.4.6 TBin

TSimThing

*TRoundThing*TBin

This object is used to create Bins that the Bots can drop Blocks into.

4.5.2.4.6.1 Properties

No uninherited properties for this object.

4.5.2.4.6.2 Methods

No uninherited methods for this object.

4.5.2.4.7 TBlock

TSimThing

*TRoundThing*TBlock

4.5.2.4.7.1 Properties
4.5.2.4.7.1.1 FromDistArea

p r o p e r t y F r o m D i s t A r e a : T D i s t A r e a ;

Specifies which Distribution Area this Block appeared from. This property is used to determine when to make other Blocks apear. Do NOT modify it.

4.5.2.4.7.1.2 DroppedBy

p r o p e r t y D r o p p e d B y : T B o t ;

Specifies which Bot dropped this Block, if any. This is used to prevent a Bot from colliding with a Block it has just dropped, until it moves away from it. Do NOT modify this property.

4.5.2.4.7.2 Methods

No uninherited methods for this object.

4.5.2.4.8 TDistArea

TSimThing

*TRoundThing*TDistArea

4.5.2.4.8.1 Properties

No uninherited properties for this object.

4.5.2.4.8.2 Methods

No uninherited methods for this object.

4.5.2.5 Procedures and Functions

4.5.2.5.1 InvalidTemplateFile

p r o c e d u r e I n v a l i d T e m p l a t e F i l e ;

Brings up a dialog box stating that the template file is invalid or corrupt. (should be in some other file)

4.5.2.5.2 SkipToken

f u n c t i o n S k i p T o k e n ( v a r f : T e x t ; T o k e n : S t r i n g ) : B o o l e a n ;

Reads from f character by character until it finds an '=' or goes further than the length of T o k e n. Returns true if the token read matched T o k e n. (should be in some other file)

4.5.2.5.3 ClassToString

function ClassToString(TempClass: TThingClass): String;

Converts T e m p C l a s s into a string representation.

4.5.2.5.4 StringToClass

function StringToClass(Buffer: String): TThingClass;

Converts the string representation B u f f e r into a class of T S i m T h i n g.

4.5.3 Geometry Module (Geometry.pas)

4.5.3.1 Non-Object Types

None.

4.5.3.2 Constants

None.

4.5.3.3 Global Variables and Properties

None.

4.5.3.4 Object Hierarchy

None.

4.5.3.5 Procedures and Functions

4.5.3.5.1 WhichSide

f u n c t i o n W h i c h S i d e ( x , y , x 1 , y 1 , x 2 , y 2 : i n t e g e r ) : b o o l e a n ;

Determines on which side of the line ( x 1, y 1)--( x 2, y 2) is the point ( x, y). Which way is which is determined by the relative positions of the endpoints of the line. Generally, if a point is on the left of the line as you travel from ( x 1, y 1) to ( x 2, y 2), then the result returned will be f a l s e.

4.5.3.5.2 IsInside

f u n c t i o n I s I n s i d e ( x , y , x 1 , y 1 , x 2 , y 2 , x 3 , y 3 , x 4 , y 4 : i n t e g e r ) : b o o l e a n ;

Returns t r u e if the point ( x, y) is inside the 4-sided polygon described by the points ( x 1, y 1), ( x 2, y 2), ( x 3, y 3) and ( x 4, y 4).

This routine is used by the Clicked methods of the various SimThing objects to determine if the user has clicked a line.

4.5.3.5.3 IsCloseEnough

f u n c t i o n I s C l o s e E n o u g h ( x 1 , y 1 , x 2 , y 2 , r a d i u s : e x t e n d e d ) : b o o l e a n ;

Returns t r u e if the two points ( x 1, y 1) and ( x 2, y 2) are closer than r a d i u s.

4.5.3.5.4 LineCircleCollide

f u n c t i o n L i n e C i r c l e C o l l i d e ( x , y , r a d i u s , x 1 , y 1 , x 2 , y 2 : e x t e n d e d ) : b o o l e a n ;

Returns t r u e if the Line ( x 1, y 1)--( x 2, y 2) crosses the circle centre ( x, y) radius r a d i u s.

4.5.3.5.5 ToAngle

f u n c t i o n T o A n g l e ( x , y : e x t e n d e d ) : e x t e n d e d ;

Converts the polar screen coordinates ( x, y) into an angle, navigational style (North is 0 radians, East is [pi]/2 radians etc.).

4.5.3.5.6 AngleRange

f u n c t i o n A n g l e R a n g e ( a n g l e , m i n , m a x : e x t e n d e d ) : b o o l e a n ;

Determines if a n g l e is between m i n and m a x. The function is warranted because the task is a little more complex than two comparisons, since min could be greater than m a x (specifying a range that passes over 0 radians).

4.5.3.5.7 LineCollide

f u n c t i o n L i n e C o l l i d e ( x 1 1 , y 1 1 , x 1 2 , y 1 2 , x 2 1 , y 2 1 , x 2 2 , y 2 2 : e x t e n d e d ) : b o o l e a n ;

Returns t r u e if the lines ( x 1 1, y 1 1)--( x 1 2, y 1 2) and ( x 2 1, y 2 1)--( x 2 2, y 2 2) intersect.

4.5.3.5.8 SecCircleCollide

f u n c t i o n S e c C i r c l e C o l l i d e ( x , y , r a d i u s , s e c x , s e c y , s e c m i n , s e c m a x , s e c r a d : e x t e n d e d ) : b o o l e a n ;

Returns t r u e if the circle center ( x, y) radius r a d i u s, and the sector center ( s e c x, s e c y) radius s e c r a d with start and end angles s e c m i n and s e c m a x respectively, intersect.

4.5.3.5.9 SecLineCollide

f u n c t i o n S e c L i n e C o l l i d e ( x 1 , y 1 , x 2 , y 2 , s e c x , s e c y , s e c m i n , s e c m a x , s e c r a d : e x t e n d e d ) : b o o l e a n ;

Returns t r u e if the line ( x 1, y 1)--( x 2, y 2), and the sector center ( s e c x, s e c y) radius s e c r a d with start and end angles s e c m i n and s e c m a x respectively, intersect.

4.5.3.5.10 SecBoxCollide

f u n c t i o n S e c B o x C o l l i d e ( x 1 , y 1 , x 2 , y 2 , s e c x , s e c y , s e c m i n , s e c m a x , s e c r a d : e x t e n d e d ) : b o o l e a n ;

Returns t r u e if the box with boundaries x 1, y 1, x 2 and y 2, and the sector center ( s e c x, s e c y) radius s e c r a d with start and end angles s e c m i n and s e c m a x respectively, intersect.

4.5.3.5.11 CircleBoxCollide

f u n c t i o n C i r c l e B o x C o l l i d e ( x , y , r a d i u s , x 1 , y 1 , x 2 , y 2 : e x t e n d e d ) : b o o l e a n ;

Returns t r u e if the box with boundaries x 1, y 1, x 2 and y 2, and the circle center ( x, y) radius r a d i u s, intersect.

4.5.3.5.12 BoxBoxCollide

function BoxBoxcollide(x11,y11,x12,y12,x21,y21,x22,y22:extended):boolean;

Returns t r u e if the box with boundaries x 1 1, y 1 1, x 1 2 and y 1 2, and the box with boundaries x 2 1, y 2 1, x 2 2 and y 2 2, intersect.

4.5.4 Communications Module (Comms.pas)

4.5.4.1 Non-Object Types

None.

4.5.4.2 Constants

None.

4.5.4.3 Global Variables and Properties

None.

4.5.4.4 Object Hierarchy

None.

4.5.4.5 Procedures and Functions

4.5.4.5.1 Hookup

f u n c t i o n H o o k u p ( h o s t , p o r t : s t r i n g ) : b o o l e a n ;

connects to the specified host on the specified port, via TCP/IP.

At present, h o s t cannot be an IP address (dotted quad) but p o r t may be a number.

4.5.4.5.2 GetMessage

f u n c t i o n G e t M e s s a g e : P C h a r ;

Retrieves a single message from the other end of the connection.

As far as this routine is concerned, a message is lisp-style, i.e. it is enclosed in brackets (), and may contain nested sets of brackets. Anything before the first opening bracket is ignored.

the message returned is an allocated string. Its memory MUST be deallocated after use.

4.5.4.5.3 SendMessage

p r o c e d u r e S e n d M e s s a g e ( m e s s a g e : P C h a r ) ;

Sends an arbitrary string to the other end of the connection.

4.5.4.5.4 UnHook

p r o c e d u r e U n h o o k ;

Disconnects from the socket connected to by a call to H o o k U p.

4.5.5 Evaluation Module (Evaluation.pas)

4.5.5.1 Non-Object Types

4.5.5.1.1 TWorldArray, PWorldArray

type TThingArray=array[0..10000] of TSimThing;

type PThingArray=^TThingArray;

This type is used internally by the unit for the storage of Worlds.

4.5.5.2 Constants

4.5.5.2.1 MaxBots

Set to the maximum number of Bots in an Evaluation. The product of the number of Worlds and the number of Bots in each World cannot exceed this number.

4.5.5.3 Global Variables and Properties

4.5.5.3.1 BotsPerWorld

Specifies the number of Bots in each World in an evaluation object. This shouldn't be here, is should be a property of T E v a l u a t i o n, but some choad meister made is a global variable. Michael is not to blame.

4.5.5.3.2 Worlds

Sepcifies the number of Worlds in an Evaluation. This should be a property of T E v a l u a t i o n also.

4.5.5.4 Object Hierarchy

4.5.5.4.1 TEvaluation

TEvaluation

This class encapsulates all of the Worlds in a signel Evaluation. It creates all of the Worlds from a template World and prepares them for the simulation.

4.5.5.4.1.1 Properties
4.5.5.4.1.1.1 Worlds

property TEvaluation.Worlds:integer;

Read-only. Contains the number of Worlds in this evaluation, as sepcified by the Create call (see below).

4.5.5.4.1.1.2 World

property TEvaluation.World:TWorldArray;

Read-only. This is the array of Worlds created by the Create call. DO NOT destroy them or otherwise tamper with them as anything of this sort will disrupt the function of the Evaluation.

4.5.5.4.1.2 Methods
4.5.5.4.1.2.1 Create

constructor TEvaluation.Create(Template:TWorld;NewWorlds:integer);

Creates NewWorlds worlds from the template world Template, then calls the InitSimulation method of each one.

4.5.5.4.1.2.2 AssignIds

procedure TEvaluation.AssignIds(var id:array of integer);

Assigns the Id property of each Bot in each World in the Evaluation from each value in the array. The array is assumed to be in order of Bot then World.

4.5.5.4.1.2.3 CreateFitnessLevelString

function TEvaluation.CreateFitnessLevelString: string;

Creates the message specifying the fitness levels of all of the Bots in the Evaluation, in the format required by the Common Brain-Environment Protocol (CBEP).

4.5.5.4.1.2.4 CreateHitsHistogram

procedure TEvaluation.CreateHitsHistogram(var HitsArray: array of integer; var MaxHeight: Integer);

Creates a histogram of number-of-Bots vs. Hits. The array must have the same number of elements as Worlds*BotsPerWorld.

4.5.5.4.1.2.5 CreateBotRankings

procedure TEvaluation.CreateBotRankings(var BotRankedID:array of integer);

Assigns the array with the Id's of all of the Bots in the Evaluation, in order of their final fitness levels. The array must have the same number of elements as Worlds*BotsPerWorld.

4.5.5.4.1.2.6 Animate

procedure TEvaluation.Animate;

Calls the Animate methods of all of the Worlds in the Evaluation, once each.

4.5.5.4.1.2.7 GetBot
f u n c t i o n G e t B o t ( B u f f M y K n o b : I n t e g e r ) : T B o t ;

Returns the Bot whose Id is B u f f M y K n o b.

4.5.5.5 Procedures and Functions

None.

4.6 BOTSSIM SOURCE FILES

4.6.1 AboutFrm.pas / AboutBox.dfm

4.6.1.1 Components

GUI

4.6.1.2 Purpose

This is the About BOTSsim form. It displays some basic Technical Information about the BOTSsim Application as well as displaying a Bitmap of all of the Group Members. Links are available from the Group Members Bitmap to individual About Boxes for each Group Member.

4.6.1.3 Persons responsible

* Stephen & Colin

4.6.1.4 Required Software

Borland Delphi Version 2.0

4.6.1.5 Contained Modules

4.6.2 BotBox.pas / BotDialogBox.dfm

4.6.2.1 Components

GUI

4.6.2.2 Purpose

This is the Bot Properties Dialogue Box. It allows you to change the properties of a Bot. The properties that can be changed include the Bot's initial direction and the Bot's colour.

4.6.2.3 Persons responsible

* Stephen & Colin

4.6.2.4 Required Software

Borland Delphi Version 2.0

4.6.2.5 Contained Modules

* p r o c e d u r e O K B t n C l i c k

* p r o c e d u r e C o l o r S B C l i c k

4.6.3 BotFrm.pas/BotForm.dfm

4.6.3.1 Components

GUI

4.6.3.2 Purpose

This is the Bot form. It displays the properties of a selected Bot in real time. The properties displayed include the Environment Number, Hits, Pickups, Drops, Raw Fitness, and the Rule Set.

4.6.3.3 Person responsible

* Mik

4.6.3.4 Required Software

Delphi

4.6.3.5 Contained Modules

* p r o c e d u r e U p d a t e T i m e r T i m e r

* p r o c e d u r e F o r m C r e a t e

* p r o c e d u r e F o r m P a i n t

* p r o c e d u r e F o r m S h o w

* p r o c e d u r e F o r m D e s t r o y

* p r o c e d u r e C l o s e B u t t o n C l i c k

* p r o c e d u r e S h o w R u l e s e t B u t t o n C l i c k

* p r o c e d u r e F o r m R e s i z e

* p r o c e d u r e F o r m C l o s e

* p r o c e d u r e S h o w E n v i r o n m e n t B u t t o n C l i c k

* p r o c e d u r e F o r m A c t i v a t e

* p r o c e d u r e U p d a t e B o t D i s p l a y

4.6.4 bots-problem-function.lsp

4.6.4.1 Purpose

Defines the BOTS optimisation problem in a way that the gp-kernel can operate on.

4.6.4.2 Person Responsible

Mark Greenaway

4.6.4.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.4.4 Contained Modules

* d e f i n e--t e r m i n a l--s e t--f o r--B O T S

* d e f i n e--f u n c t i o n--s e t--f o r--B O T S

* i f--H a s B l o c k--i m p l e m e n t a t i o n

* i f--B l o c k C o l l i d e--i m p l e m e n t a t i o n

* i f--W a l l F o r w a r d--i m p l e m e n t a t i o n

* i f--W a l l B a c k w a r d--i m p l e m e n t a t i o n

* i f--W a l l L e f t--i m p l e m e n t a t i o n

* i f--W a l l R i g h t--i m p l e m e n t a t i o n

* i f--B o t F o r w a r d--i m p l e m e n t a t i o n

* i f--B o t B a c k w a r d--i m p l e m e n t a t i o n

* i f--B o t L e f t--i m p l e m e n t a t i o n

* i f--B o t R i g h t--i m p l e m e n t a t i o n

* i f--B l o c k F o r w a r d--i m p l e m e n t a t i o n

* i f--B l o c k B a c k w a r d--i m p l e m e n t a t i o n

* i f--B l o c k L e f t--i m p l e m e n t a t i o n

* i f--B l o c k R i g h t--i m p l e m e n t a t i o n

* i f--B i n F o r w a r d--i m p l e m e n t a t i o n

* i f--B i n B a c k w a r d--i m p l e m e n t a t i o n

* i f--B i n L e f t--i m p l e m e n t a t i o n

* i f--B i n R i g h t--i m p l e m e n t a t i o n

* i f--B l o c k C o l l i d e

* i f--W a l l F o r w a r d

* i f--W a l l B a c k w a r d

* i f--W a l l L e f t

* i f--W a l l R i g h t

* i f--B o t F o r w a r d

* i f--B o t B a c k w a r d

* i f--B o t L e f t

* i f--B o t R i g h t

* i f--B l o c k F o r w a r d

* i f--B l o c k B a c k w a r d

* i f--B l o c k L e f t

* i f--B l o c k R i g h t

* i f--B i n F o r w a r d

* i f--B i n B a c k w a r d

* i f--B i n L e f t

* i f--B i n R i g h t

* d e f i n e--f i t n e s s--c a s e s--f o r--B O T S

* e v a l u a t e--s t a n d a r d i z e d--f i t n e s s--f o r--B O T S

* d e f i n e--p a r a m e t e r s--f o r--B O T S

* t e r m i n a t i o n--c r i t e r i a--f o r--b o t s

4.6.5 brain.lsp

4.6.5.1 Purpose

Run genetic programming system as a whole. Create a CBEP socket, and then run the genetic programming system contained in gp-kernel.lsp

4.6.5.2 Person Responsible

Mark Greenaway

4.6.5.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.5.4 Contained Modules

* b r a i n

* p l a c e--r o b o t s--i n--e n v i r o n m e n t s

4.6.6 brain-var.lsp

4.6.6.1 Purpose

Define Brain module variables which need to be shared among other modules.

4.6.6.2 Person Responsible

David Formosa

4.6.6.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.6.4 Contained Modules

* * p o p u l a t i o n--s i z e *

* * n u m b e r--o f--f a c t o r i e s *

* * m a x i m u m--g e n e r a t i o n s *

* * b o t--f a c t o r y--g r o u p i n g s *

4.6.7 CBEP.pas

4.6.7.1 Components

GUI

4.6.7.2 Purpose

This is the CBEP unit. It contains the code that implements the Complex Brain Environment Protocol (CBEP) on the GUI / Environment side. It also contains code to create & destroy the CBEP object.

4.6.7.3 Persons responsible

4.6.7.4 Required Software

Borland Delphi Version 2.0

4.6.7.5 Contained Modules

4.6.8 ColinAbout.pas / AboutColin.dfm

4.6.8.1 Components

GUI

4.6.8.2 Purpose

This is the About Colin form. It is completely inherited from the About Mark form. Information is available under About Mark form specification--section MarkAbout.pas / AboutMark.dfm.

4.6.8.3 Persons responsible

4.6.8.4 Required Software

Borland Delphi Version 2.0

4.6.9 Comms.pas

4.6.9.1 Components

Environment, GUI

4.6.9.2 Purpose

Contains routines to connect to the Brain via TCP/IP, and send and receive messages.

4.6.9.3 Persons responsible

Michael Slade

4.6.9.4 Required Software

Borland Delphi 2.0

4.6.9.5 Contained Modules

* f u n c t i o n H o o k u p

* f u n c t i o n G e t P r o t o c o l M e s s a g e

* p r o c e d u r e S e n d P r o t o c o l M e s s a g e

* p r o c e d u r e U n h o o k

4.6.10 CommsDebugDlg.pas / CommsDebug.dfm

4.6.10.1 Components

Environment, GUI

4.6.10.2 Purpose

Contains code that stores & displays incoming & outgoing CBEP messages for the purpose of debugging.

4.6.10.3 Persons responsible

Stephen Beacom

4.6.10.4 Required Software

Borland Delphi 2.0

4.6.10.5 Contained Modules

* p r o c e d u r e F o r m C r e a t e

* p r o c e d u r e A d d I n c o m i n g M e s s a g e

* p r o c e d u r e A d d O u t g o i n g M e s s a g e

4.6.11 DavidAbout.pas / AboutDavid.dfm

4.6.11.1 Components

GUI

4.6.11.2 Purpose

This is the About David form. It is completely inherited from the About Mark form. Information is available under About Mark form specification--section MarkAbout.pas / AboutMark.dfm.

4.6.11.3 Persons responsible

4.6.11.4 Required Software

Borland Delphi Version 2.0

4.6.12 Environment.pas

4.6.12.1 Components

Environment

4.6.12.2 Purpose

This is the heart and bulk of the environment component. It contains an object hierarchy with objects types for a simulated world and the things, called SimThings, contained in that world. It stores position, orientation, and other information about the SimThings in a World, and performs all of the simulation processes, except for the actual brain functions.

4.6.12.3 Persons responsible

Michael Slade

4.6.12.4 Required Software

Borland Delphi 2.0

4.6.12.5 Contained Modules

* TWorld

* TSimThing

* TWall

* TRoundThing

* TBot

* TBlock

* TBin

* TDistarea

4.6.13 Evaluation.pas

4.6.13.1 Components

Environment

4.6.13.2 Purpose

The Evaluation unit encapsulates objects that allow restricted access to the multiple instances of the Template Environment within the Run.

4.6.13.3 Persons responsible

Michael Slade

4.6.13.4 Required Software

Borland Delphi 2.0

4.6.13.5 Contained Modules

* c o n s t r u c t o r C r e a t e

* d e s t r u c t o r D e s t r o y

* p r o c e d u r e A s s i g n I d s

* f u n c t i o n C r e a t e F i t n e s s L e v e l S t r i n g

* p r o c e d u r e C r e a t e H i t s H i s t o g r a m

* p r o c e d u r e C r e a t e B o t R a n k i n g s

* f u n c t i o n G e t B o t

* p r o c e d u r e A n i m a t e

4.6.14 fast-eval.lsp

4.6.14.1 Purpose

Streamlined function to evaluate simple LISP-like expressions. Used to speed evaluation of the control programs of individual Bots.

4.6.14.2 Person Responsible

John Koza, some additional modification by David Formosa

4.6.14.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.14.4 Contained Modules

* f a s t--e v a l--f u n

* f a s t--e v a l

* i n s t a l l--p s e u d o--m a c r o

4.6.15 FastEval.pas

4.6.15.1 Purpose

Streamlined function to evaluate simple LISP-like expressions. Used to speed up evaluation of the control programs of individual Bots.

4.6.15.2 Person Responsible

Colin Lowther

4.6.15.3 Required Software

Borland Delphi 2.0

4.6.15.4 Contained Modules

* f u n c t i o n C r e a t e T r e e

* p r o c e d u r e D e s t r o y T r e e

* f u n c t i o n I f C l a u s e

* f u n c t i o n A c t i o n

* f u n c t i o n W a l l S e n s o r

* f u n c t i o n W h i c h B

* f u n c t i o n W h i c h G

* f u n c t i o n W h i c h T

* f u n c t i o n B i n S e n s o r

* f u n c t i o n B l o c k S e n s o r

* f u n c t i o n B o t S e n s o r

* f u n c t i o n S e n s o r M a p p i n g

* f u n c t i o n G e t A c t i o n

* p r o c e d u r e I n i t i a l i s e R u l e S e t s

* p r o c e d u r e D e s t r o y R u l e S e t s

* p r o c e d u r e D e s t r o y A l l R u l e S e t s

* p r o c e d u r e S h o w R u l e S e t

* f u n c t i o n T o k e n T o S t r i n g

4.6.16 Fitness.pas

4.6.16.1 Purpose

Converts Raw Fitness into Refined Fitness for the purpose of sending it to the Brain.

4.6.16.2 Person Responsible

Colin Lowther

4.6.16.3 Required Software

Borland Delphi 2.0

4.6.16.4 Contained Modules

* procedure CalculateFitness

4.6.17 Geometry.pas

4.6.17.1 Components

Environment

4.6.17.2 Purpose

This pascal unit contains procedures that perform the analytic geometry needed by Environment.pas for the simulation. Among these are line-circle intersection, line-sector intersection, and so on.

4.6.17.3 Persons responsible

Michael Slade

4.6.17.4 Required Software

Borland Delphi 2.0

4.6.17.5 Contained Modules

* WhichSide

* IsInside

* IsCloseEnough

* LineCircleCollide

* ToAngle

* AngleRange

* LineCollide

* SecCircleCollide

* SecLineCollide

* SecBoxCollide

* CircleBoxCollide

* BoxBoxcollide

4.6.18 gp-kernel.lsp

4.6.18.1 Purpose

Provide basic genetic prograing facilities, to be used in optimisation.

4.6.18.2 Person Responsible

John Koza, with minor modifications by David Formosa and Mark Greenaway

4.6.18.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.18.4 Modified Modules

* r u n--g e n e t i c--p r o g r a i n g--s y s t e m

* e v a l u a t e--f i t n e s s--o f--p o p u l a t i o n

4.6.19 gp-kernel-var.lsp

4.6.19.1 Purpose

Share gp-kernel variables among other modules.

4.6.19.2 Person Responsible

David Formosa

4.6.19.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.19.4 Contained Modules

* * n u m b e r--o f--f i t n e s s--c a s e s *

* * m a x--d e p t h--f o r--n e w--i n d i v i d u a l s *

* * m a x--d e p t h--f o r--i n d i v i d u a l s--a f t e r--c r o s s o v e r *

* * f i t n e s s--p r o p o r t i o n a t e--r e p r o d u c t i o n--f r a c t i o n *

* * c r o s s o v e r--a t--a n y--p o i n t--f r a c t i o n *

* * c r o s s o v e r--a t--f u n c t i o n--p o i n t--f r a c t i o n *

* * m a x--d e p t h--f o r--n e w--s u b t r e e s--i n--m u t a n t s *

* * m e t h o d--o f--s e l e c t i o n *

* * m e t h o d--o f--g e n e r a t i o n *

* * s e e d *

* * b e s t--o f--r u n--i n d i v i d u a l *

* * g e n e r a t i o n--o f--b e s t--o f--r u n--i n d i v i d u a l *

* * s e n s o r--r e a d i n g *

* * t e r m i n a t e--b r a i n *

4.6.20 Hits.pas / HitsHistogram.dfm

4.6.20.1 Purpose

This unit contains code for operating the Histogram Window. The Histogram is a Bar Chart that displays the number of Hits achieved by each Bot. As an after-thought we decided to add the ability for the Hits Histogram to display Hits, Pickups or Drops for all the Bots. On the 17th of September the Histogram was changed so that it would display percentages of the Bot Population instead of the actual number of Bots. This was done to increase the accuracy & scaling factor.

4.6.20.2 Persons Responsible

Colin Lowther & Stephen Beacom

4.6.20.3 Required Software

Borland Delphi Version 2.0

4.6.20.4 Contained Modules

* p r o c e d u r e F o r m S h o w

* p r o c e d u r e R e s e t H i s t o g r a m C l i c k

* p r o c e d u r e C a n c e l B t n C l i c k

* p r o c e d u r e R e s e t H i t s H i s t o g r a m

4.6.21 link.lsp

4.6.21.1 Purpose

Setup and close CBEP socket connections.

4.6.21.2 Person Responsible

David Formosa

4.6.21.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.21.4 Contained Modules

*CBEP-stream*

open-cbep

close-cbep

4.6.22 MainFrm.pas/MainForm.dfm

4.6.22.1 Components

GUI

4.6.22.2 Purpose

This is the main form, also known as the BOTSsim form. It is the first window that the user sees when the program starts, and is responsible for coordinating all of the components. Through this window, runs are loaded, launched and saved. Users can also get online instructions, open other windows, launch TED, and quit from this window.

4.6.22.3 Persons responsible

* Stephen Beacom, Colin Lowther, Mik Scheper

4.6.22.4 Required Software

Borland Delphi Version 2.0

4.6.22.5 Contained Modules

* p r o c e d u r e F i l e S a v e R u n C l i c k

* p r o c e d u r e F i l e N e w R u n C l i c k

* p r o c e d u r e F i l e O p e n R u n C l i c k

* p r o c e d u r e F i l e E x i t C l i c k

* p r o c e d u r e F i l e O p e n T e m p l a t e C l i c k

* p r o c e d u r e E d i t T e m p l a t e C l i c k

* p r o c e d u r e E d i t R u n I n f o C l i c k

* p r o c e d u r e R u n S t a r t R u n C l i c k

* p r o c e d u r e R u n P a u s e R u n C l i c k

* p r o c e d u r e R u n R e s e t R u n C l i c k

* p r o c e d u r e V i e w H i t s H i s t o g r a m C l i c k

* p r o c e d u r e V i e w C o m m u n i c a t i o n s C l i c k

* p r o c e d u r e S h o w E n v i r o n m e n t

* p r o c e d u r e S h o w B o t

* p r o c e d u r e B o t M e n u C l i c k

* p r o c e d u r e B o t S h o w A n o t h e r B o t C l i c k

* p r o c e d u r e H e l p T o p i c s C l i c k

* p r o c e d u r e H e l p A b o u t C l i c k

* p r o c e d u r e F o r m C r e a t e

* p r o c e d u r e F o r m C l o s e

* p r o c e d u r e A n i m a t i o n T i m e r T i m e r

* p r o c e d u r e E n d O f G e n e r a t i o n

* p r o c e d u r e A l l o w R u n

* p r o c e d u r e D i s a l l o w R u n

* p r o c e d u r e A l l o w S t a r t R u n

* p r o c e d u r e D i s a l l o w S t a r t R u n

* procedure UpdateRunDisplay

* procedure UpdateTemplateDisplay

* procedure UpdateRunInfoDisplay

4.6.23 MarkAbout.pas / AboutMark.dfm

4.6.23.1 Components

GUI

4.6.23.2 Purpose

This is the About Mark form. It displays some basic Technical Information about Mark as well as displaying mugshot style bitmaps of Mark. Also contained are Notable Comments made by Mark, as well as what Project sections Mark is responsible for. Also visible here is Mark's alias ( a.k.a. N/A ).

4.6.23.3 Persons responsible

4.6.23.4 Required Software

Borland Delphi Version 2.0

4.6.23.5 Contained Modules

4.6.24 MichaelAbout.pas / AboutMichael.dfm

4.6.24.1 Components

GUI

4.6.24.2 Purpose

This is the About Michael form. It is completely inherited from the About Mark form. Information is available under About Mark form specification--section MarkAbout.pas / AboutMark.dfm.

4.6.24.3 Persons responsible

4.6.24.4 Required Software

Borland Delphi Version 2.0

4.6.25 MikAbout.pas / AboutMik.dfm

4.6.25.1 Components

GUI

4.6.25.2 Purpose

This is the About Mik form. It is completely inherited from the About Mark form. Information is available under About Mark form specification--section MarkAbout.pas / AboutMark.dfm.

4.6.25.3 Persons responsible

4.6.25.4 Required Software

Borland Delphi Version 2.0

4.6.26 parser.lsp

4.6.26.1 Purpose

Parse CBEP protocol messages received and perform the appropriate action as defined in semantics.lsp

4.6.26.2 Person Responsible

David Formosa

4.6.26.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.26.4 Contained Modules

domessage

parser

test-modules

4.6.27 RunInformation.pas / RunInformation.dfm

4.6.27.1 Components

GUI

4.6.27.2 Purpose

This unit contains code for operating the Run Information Dialogue. This unit has code for Opening and saving the dialogue's variables, as well as code for sending the Environment Variables to the Environment Component and code for sending the GP Variables to the Brain Component via the IPC method of Sockets using our BOTSsim project's proprietary socket protocol CBEP.

4.6.27.3 Persons responsible

4.6.27.4 Required Software

Borland Delphi Version 2.0

4.6.27.5 Contained Modules

4.6.28 Runs.pas

4.6.28.1 Components

GUI

4.6.28.2 Purpose

This unit contains for Loading & Saving Runs.

4.6.28.3 Persons responsible

4.6.28.4 Required Software

Borland Delphi Version 2.0

4.6.28.5 Contained Modules

4.6.29 semantics.lsp

4.6.29.1 Purpose

Perform appropriate actions for CBEP protocol messages, such as setting fitness values etc.

4.6.29.2 Person Responsible

Mark Greenaway

4.6.29.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.29.4 Contained Modules

makecall

sensorcall

set-slot-and-eat

fitnesslevelcall

getrulesetcall

setruleset

test-if-valid-variable

SetGPVariablescall

errorcall

closecall

4.6.30 sendmessage.lsp

4.6.30.1 Purpose

Send CBEP protocol messages to the GUI/Environment.

4.6.30.2 Person Responsible

David Formosa

4.6.30.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.30.4 Contained Modules

* s e n d--a c t i o n

* s e n d--R o b o t E n v i r o n m e n t--m e s s a g e

4.6.31 sensor.lsp

4.6.31.1 Purpose

Define sensor structure used to pass sensor values around the Brain component.

4.6.31.2 Person Responsible

Mark Greenaway

4.6.31.3 Required Software

Allegro Common LISP for Windows 3.0.2

4.6.31.4 Contained Modules

* s e n s o r

4.6.32 ShowBot.pas / ShowBotByID.dfm

4.6.32.1 Components

GUI

4.6.32.2 Purpose

To allow the user to choose by Bot ID the Bot whose details to show in the Bot Window.

4.6.32.3 Persons responsible

4.6.32.4 Required Software

Borland Delphi Version 2.0

4.6.32.5 Contained Modules

* p r o c e d u r e O K B t n C l i c k

* p r o c e d u r e C a n c e l B t n C l i c k

* p r o c e d u r e F o r m S h o w

4.6.33 StephenAbout.pas / AboutStephen.dfm

4.6.33.1 Components

GUI

4.6.33.2 Purpose

This is the About Stephen form. It is completely inherited from the About Mark form. Information is available under About Mark form specification--section MarkAbout.pas / AboutMark.dfm.

4.6.33.3 Persons responsible

4.6.33.4 Required Software

Borland Delphi Version 2.0

4.6.34 TED.pas / TEDForm.dfm

4.6.34.1 Components

GUI

4.6.34.2 Purpose

This unit contains the code for the TED Form. Contained within is code for creating, opening, saving and editing Template Environments. That's about it really.

4.6.34.3 Persons responsible

4.6.34.4 Required Software

Borland Delphi Version 2.0

4.6.34.5 Contained Modules

* p r o c e d u r e S a v e T e m p l a t e

* p r o c e d u r e O p e n T e m p l a t e

* p r o c e d u r e F o r m P a i n t

* p r o c e d u r e C l o s e T E D C l i c k

* p r o c e d u r e H e l p T o p i c s C l i c k

* p r o c e d u r e C r e a t e B o t C l i c k

* p r o c e d u r e C r e a t e D A C l i c k

* p r o c e d u r e T e m p l a t e M o u s e D o w n

* p r o c e d u r e F o r m C r e a t e

* p r o c e d u r e C r e a t e N e w B o t

* p r o c e d u r e C r e a t e N e w B i n

* p r o c e d u r e C r e a t e N e w B l o c k

* p r o c e d u r e C r e a t e N e w W a l l

* p r o c e d u r e D r a w

* f u n c t i o n P o i n t D i s t a n c e

* p r o c e d u r e T e m p l a t e M o u s e U p

* p r o c e d u r e C r e a t e W a l l C l i c k

* p r o c e d u r e C r e a t e B i n C l i c k

* p r o c e d u r e T e m p l a t e M o u s e M o v e

* p r o c e d u r e E d i t D e s t r o y C l i c k

* p r o c e d u r e E d i t C h a n g e P r o p e r t i e s C l i c k

* p r o c e d u r e T e m p l a t e S a v e C l i c k

* p r o c e d u r e T e m p l a t e S a v e A s C l i c k

* p r o c e d u r e T e m p l a t e O p e n C l i c k

* p r o c e d u r e T e m p l a t e N e w C l i c k

* p r o c e d u r e C r e a t e N e w T e m p l a t e

* p r o c e d u r e F o r m K e y P r e s s

* p r o c e d u r e A b o u t C l i c k

* p r o c e d u r e Z o o m I n C l i c k

* p r o c e d u r e Z o o m O u t C l i c k

* p r o c e d u r e U p d a t e Z o o m L e v e l

* p r o c e d u r e C r e a t e B o u n d a r y W a l l s

* p r o c e d u r e F o r m C l o s e

* p r o c e d u r e F o r m R e s i z e

* p r o c e d u r e T e m p l a t e P a i n t

* f u n c t i o n I s T e m p l a t e V a l i d

* p r o c e d u r e U p d a t e T e m p l a t e S c r o l l e r

4.6.35 ViewAnEnvironment.pas / ViewAnEnvironmentDlg.dfm

4.6.35.1 Components

GUI

4.6.35.2 Purpose

Allows the user to an Environment based upon it's Environment Number.

4.6.35.3 Person responsible

4.6.35.4 Required Software

Borland Delphi Version 2.0

4.6.35.5 Contained Modules

* procedure OKBtnClick

* procedure CancelBtnClick

* procedure FormShow

4.6.36 ViewEnvironment.pas / ViewEnvironmentWin.dfm

4.6.36.1 Components

GUI

4.6.36.2 Purpose

This unit contains code that displays any Environment.

4.6.36.3 Person responsible

4.6.36.4 Required Software

Borland Delphi Version 2.0

4.6.36.5 Contained Modules

* procedure FormCreate

* procedure FormClose

* procedure FormShow

* procedure FormResize

* procedure FormPaint

* procedure FormMouseMove

* procedure FormMouseDown

* procedure FormMouseUp

* procedure UpdateDisplayTimer

* procedure UpdateEnvironmentScroller

4.6.37 WorldSize.pas / WorldParams.dfm

4.6.37.1 Components

GUI

4.6.37.2 Purpose

This unit contains the code for the Template Dimensions Dialogue. Code contained within this unit implements the functionality for creating a Template Environment of user defined dimensions.

4.6.37.3 Person responsible

4.6.37.4 Required Software

Borland Delphi Version 2.0

4.6.37.5 Contained Modules

* procedure OKBtnClick

4.7 BOTSSIM STANDARDS

BOTSsim standards are a reference for all group members to refer to. Originally there were seven separate standards, but only four are shown here. The others are either obsolete, or their contents are contained within other parts of this document.

4.7.1 BOTSS1: Bot Sensors

4.7.1.1 Introduction

This BotsS provides information about the sensors possessed by the Bots. The sensors exist to communicate data about the simulated world into the robot's "Brain".

4.7.1.2 Robot Model

This standard regards the robot a vector. From the robot there are 4 directions Forward, Backward, Left and right

4.7.1.2.1.1 Forward

Forward is the direction that the vector points.

4.7.1.2.1.2 Backward

Backward is 180° from forward.

4.7.1.2.1.3 Right

Right is 90° clockwise from forward.

4.7.1.2.1.4 Left

Left is 270° clockwise from forward.

4.7.1.3 Contact sensors

4.7.1.3.1 HasBlock?

This sensor MUST return True if the bot is holding a block otherwise it MUST return a False.

4.7.1.3.2 BlockCollide

This sensor MUST return True if the bot is close enough to pick up a block otherwise it MUST return False.

4.7.1.3.3 BinCollide

This sensor MUST return True if the bot is close enough to drop a block in a bin otherwise it MUST return False.

4.7.1.4 Short range sensors

4.7.1.4.1 Wall sensors

There are 4 wall sensors, Forward, Backward, right and left. The 4 sensors possess a common range (Rw) and an individual scope (Swf Swb Swr Swl). The sensors MUST cover all directions without blind spots i.e. Swf + Swb + Swr + Swl = 360

4.7.1.4.1.1 Forward wall sensor

The Forward wall sensor MUST return True if there is a wall within the sector with a radius of Rw and an angel of Swf otherwise it MUST return False. This sector SHOULD face forward.

4.7.1.4.1.2 Right wall sensor

The Forward wall sensor MUST return True if there is a wall within the sector with a radius of Rw and an angel of Swr otherwise it MUST return False. This sector SHOULD face right.

4.7.1.4.1.3 Backward wall sensor

The Backward wall sensor MUST return True if there is a wall within the sector with a radius of Rw and an angel of Swb otherwise it MUST return False. This sector SHOULD face backward.

4.7.1.4.1.4 Left wall sensor

The Left wall sensor MUST return True if there is a wall within the sector with a radius of Rw and an angel of Swl otherwise it MUST return False. This sector SHOULD faceleft.

4.7.1.4.2 Bot sensors

There are 4 bot sensors, Forward, Backward, right and left. The 4 sensors possess a common range (Rb) and an individual scope (Sbf Sbb Sbr Sbl). The sensors cover all directions without blind spots i.e. Sbf + Sbb + Sbr + Sbl = 360

4.7.1.4.2.1 Forward bot sensor

The Forward bot sensor MUST return True if there is a bot within the sector with a radius of Rb and an angel of Sbf otherwise it MUST return False. This sector SHOULD face forward.

4.7.1.4.2.2 Right bot sensor

The Right bot sensor MUST return True if there is a bot within the sector with a radius of Rb and an angel of Sbr otherwise it MUST return False. This sector SHOULD face right.

4.7.1.4.2.3 Backward bot sensor

The Backward bot sensor MUST return True if there is a bot within the sector with a radius of Rb and an angel of Sbb otherwise it MUST return False. This sector SHOULD face backward.

4.7.1.4.2.4 Left bot sensor

The Left bot sensor MUST return True if there is a bot within the sector with a radius of Rb and an angel of Sbl otherwise it MUST return False. This sector SHOULD face left.

4.7.1.5 Long Range sensors

4.7.1.5.1 Block sensors

There are 4 block sensors, Forward, Backward, right and left. The 4 sensors have an individual scope (Slf Slb Slr Sll). The sensors MUST cover all directions without blind spots i.e. Slf + Slb + Slr + Sll = 360

4.7.1.5.1.1 Forward bot sensor

The Forward block sensor MUST return True if there is a block within the sector with an infinite radius and an angel of Slf otherwise it MUST return False. This sector SHOULD face forward.

4.7.1.5.1.2 Right bot sensor

The right block sensor MUST return True if there is a block within the sector with an infinite radius and an angel of Slr otherwise it MUST return False. This sector SHOULD face right.

4.7.1.5.1.3 Backward bot sensor

The Backward block sensor MUST return True if there is a block within the sector with an infinite radius and an angel of Slf otherwise it MUST return False. This sector SHOULD face forward.

4.7.1.5.1.4 Left bot sensor

The left block sensor MUST return True if there is a block within the sector with an infinite radius and an angel of Slf otherwise it MUST return False. This sector SHOULD face forward.

4.7.1.5.2 Bin sensors

There are 4 bin sensors, Forward, Backward, right and left. The 4 sensors have an individual scope (Sif Sib Sir Sil). The sensors MUST cover all directions without blind spots i.e. Sif + Sib + Sir + Sil = 360

4.7.1.5.2.1 Forward bot sensor

The Forward bin sensor MUST return True if there is a bin within the sector with an infinite radius and an angel of Sif otherwise it MUST return False. This sector SHOULD face forward.

4.7.1.5.2.2 Right bot sensor

The right bin sensor MUST return True if there is a bin within the sector with an infinite radius and an angel of Sir otherwise it MUST return False. This sector SHOULD face right.

4.7.1.5.2.3 Backward bot sensor

The Backward bin sensor MUST return True if there is a bin within the sector with an infinite radius and an angel of Sif otherwise it MUST return False. This sector SHOULD face forward.

4.7.1.5.2.4 Left bot sensor

The left bin sensor MUST return True if there is a bin within the sector with an infinite radius and an angel of Sif otherwise it MUST return False. This sector SHOULD face forward.

4.7.2 BOTSS4: CBEP--Complex BrainEnvironment Protocol

4.7.2.1 Introduction

This BotsS provides information about communication between the Brain and GUI/Environment modules. This is based on the Context diagram in report two. This protocol is built on top of TCP however I believe it is possible to mount it on any stream based protocol.

This document is split into two sections, The Brain à Environment messages, and the Environment à Brain messages.

The protocol MUST be case insensitive.

4.7.2.2 Brain GUI/Environment messages

There are a number of brain à Environment messages they all take the basic form of

<Message> ::= "(" <MessageName> <space> {<Argument>}")"

The messages are Action, RobotEnvironment, Rule set, FitnessOrder, Ready and Error.

These messages go from the brain to the GUI.

4.7.2.2.1 Action

The action message represents an action resulting from a sensor mapping request.

The action message MUST be returned as a result of a Sensor message (defined in 3.1). It has the form of

<Message> ::= "(" "Action" <space> <Argument>")"

Where Argument is one of "goForward" "goBackward" "turnLeft" "turnRight" "getBlock" "dropBlock" as defined in BotsS05.

4.7.2.2.2 RobotEnvironment

The robotEnvironment message represents the grouping of bots into enviroments.

The robotEnvironment message MUST be returned as a result of a FitnessLevel message (defined in 3.2) or SetGPVariables (defined in 3.5). It has the form of

<Message> ::= "(" "RobotWorld" { <space> "(" <botno> {<space> <botno>} ")" } ")"

The meaning is to put each bot botno into enviroment enviromentno.

e.g.

(RobotWorld (4 1 2 8)(7 6 5 3))

means place robots 1,2,4 and 8 into world 0, and robots 3,5,6,7 into world 1.

4.7.2.2.3 Rule set

The rule set message represents one bots brain, returned after the request for one.

The get rule message MUST be returned as a result of a GetRuleSet message (defined in 3.3). It has the form of

<Message> ::= "(" "Rule set" <space> <Lisp-S-Expression> ")"

4.7.2.2.4 Ready

The ready message MUST be returned as a result of a successful connection.

<Message> ::= "(Ready)"

4.7.2.2.5 Error

This message MAY be returned when an error occurs. The error takes the form of

<Message> ::= "(Error)"

4.7.2.2.6 OK

This message MAY be returned when the input is acceptable.

<Message> ::= "(ok)"

4.7.2.3 GUI/Environment Brain messages

There are a number of Environment à Brain messages they all take the basic form of

<Message> ::= "(" <MessageName> <space> {<Argument>}")"

The messages are Sensor, FitnessLevel, GetRuleSet, SetRuleSet, SetGPVariables, Mirror, reset and GetFitnessOrder.

4.7.2.3.1 Sensor

The sensor message represents the values of the sensors at some point

The sensor message MUST occur some time after the SetGPVerable message has been sent

<Message> ::= "(" "Sensor" <space> <botno> <space> <Bincollide> <space> <HasBlock> <space> <BlockCollide> <space> <WallForward> <space> <WallBackward> <space> <WallLeft> <space> <WallRight> <space> <BotForward> <space> <BotBackward> <space> <BotLeft> <space> <BotRight> <space> <BlockForward> <space> <BlockBackward> <space> <BlockLeft> <space> <BlockRight> <space> <BinForward> <space> <BinBackward><space> <BinLeft><space> <BinRight> ")"

Where <HasBlock> etc. is "T" or "Nil"

4.7.2.3.2 FitnessLevel

The FitnessLevel represents the value of each robots fitness.

The FitnessLevel message MUST occur some time after the SetGPVariable message has been sent.

<Message> ::= "(" "FitnessLevel" {<space><value>} ")"

Where each <value> is the value of that robots raw fitness of the n'th robot.

4.7.2.3.3 GetRuleSet

The GetRuleSet represents a request for a rule set.

The GetRuleSet message MUST occur some time after the SetGPVerable message has been sent.

<Message> ::= "(" "GetRuleSet" <space> <botno> ")"

4.7.2.3.4 SetRuleSet

The SetRuleSet represents an attempt to set the rule set for a robot.

The SetRuleSet MUST occur some time after the SetGPVerable message has been sent.

<Message> ::= "(" "SetRuleSet" <space> <botno> <space> <Lisp-S-Expresstion>")"

The <Lisp-S-Expresstion> SHOULD be valid lisp, the Brain MAY return an error if it is not.

4.7.2.3.5 SetGPVariables

The SetGPVariables represents an attempt to set the variables for the system.

The SetGPVariables message MUST be sent only once during a run.

The SetGPVariables message MUST occur as a response to the Ready message.

<Message> ::= "(" "SetGPVariables" <space> "(" { "(" <Varname> <space> <Varvalue>")" } ")"

4.7.2.3.6 Reset

SHOULD reset the brain.

<Message> ::= "(reset)"

4.7.2.3.7 Close

The close message MUST cause the connection and the brain component to undergo an orderly shutdown.

<Message> ::= "(close)"

4.7.2.3.8 Mirror

The Mirror message SHOULD cause the Brain to implement rule set mirroring. The stability of the brain after this message is send is not guaranteed.

4.7.3 BOTSS5: Bot Actions

4.7.3.1 Introduction

This BotsS defines standards for actions. There are three types of actions movement, block, and noop.

The robot model from BotsS01 is used in this document.

4.7.3.2 Movement Actions

Movement actions cause the robot to change its vector.

4.7.3.2.1 goForward

This action means that a robot moves forward by a user defined distance.

4.7.3.2.2 goBackward

This action means that a robot moves backward by a user defined distance.

4.7.3.2.3 turnLeft

This action means that a robot turns to the left by a user defined distance.

4.7.3.2.4 turnRight

This action means that a robot turns to the right by a user defined distance.

4.7.3.3 Block Actions

Block action cause the robot to change the robots ownership of a block.

4.7.3.3.1 getBlock

This action means that a robot picks up a block if available.

4.7.3.3.2 dropBlock

This action means that a robot drops a block if it has one.

4.7.3.4 Noop

This action means that the robot dose not do anything for this time period (pronounced No Op or noop)

4.7.4 BOTSS6: File Formats

4.7.4.1 Introduction

This BOTS Standard provides information about the File Formats used for Loading and Saving Runs. The information saved includes Template Environments, Run Information and Bot Rule Sets. BOTSsim provides facilities for Loading and Saving Template Environments and Run Information separately or as part of a Run. This document contains sections that explain the File Formats used for Loading and Saving Runs, Template Environments, Run Information and Bot Rule Sets.

4.7.4.2 RUN Files--Runs

The RUN File is just a blank file that we create for the purposes of directory searching. The RUN File contains the File Name of the Run, this is the same File Name that is used for saving the TED, RIF and SEX files for the same Run.

4.7.4.3 TED Files--Template Environments

The TED File contains the data for all of the objects that appear in that Template Environment. Note that <ObjectClass> can at the moment be any of Wall, Bot, Bin or DA.

4.7.4.3.1 The Title

The first line contains the title and type of the file. The title used for Template Environments is "Template Environment". If the correct title is not scanned by the file interpreter then the file is deemed to be an invalid Template Environment file.

<Title> ::= "Template Environment"

4.7.4.3.2 Total Things

The second line contains the number of objects in the Template Environment.

<TotalThings> ::= "TotalThings=" <Total Things>

4.7.4.3.3 Wall Data

Each Wall in the Template Environment contains 6 lines that identify the it's properties.

<Line 1> ::= "ObjectClass=" <ObjectClass>

<Line 2> ::= "StartX=" <Start X Coordinate>

<Line 3> ::= "StartY=" <Start Y Coordinate>

<Line 4> ::= "EndX=" <End X Coordinate>

<Line 5> ::= "EndY=" <End Y Coordinate>

<Line 6> ::= "Colour=" <Colour>

4.7.4.3.4 Round Thing Data

Each Round Thing in the Template Environment contains 5 lines that identify the it's properties. Round Things within the Template Environment are Bots, Bins and Distribution Areas.

<Line 1> ::= "ObjectClass=" <ObjectClass>

<Line 2> ::= "X=" <X Coordinate>

<Line 3> ::= "Y=" <Y Coordinate>

<Line 4> ::= "Direction=" <Starting Direction>

<Line 5> ::= "Colour=" <Colour>

4.7.4.4 RIF Files--Run Information

The RIF File contains the data for all of the Run Information variables applicable to a Run.

4.7.4.4.1 The Title

The first line contains the title and type of the file. The title used for Run Information Files is "RunInformationVariables". If the correct title is not scanned by the file interpreter then the file is deemed to be an invalid Run Information file.

<Title> ::= "RunInformationVariables"

4.7.4.4.2 Variable Data

Each subsequent line contains data that identifies the Variable Name, and Variable Value.

<Run Information Variable> ::= <VariableName> "=" <VariableValue>

4.7.4.5 SEx Files--Bot Rule Sets (S-Expression Files)

The SEx File contains the data for all of the Rule Sets used by Bots in that Run.

4.7.4.5.1 Number Of Rule Sets

The first line contains the Number Of Rule Sets stored in that file.

<Number Of Rule Sets> ::= "NumberOfRuleSets=" <Number Of Rule Sets Value>

4.7.4.5.2 Rule Set Data

The rest of the file are rule sets. Each rule set is on a separate line and the number of rule sets MUST be equal or greater than the number in the first line of the file.

4.7.4.6 LOG Files

Log exist to record a log of events that occur in the systems history.

4.7.4.6.1 Unified.log

The Unified Log (So called because it unified a number of previously separate logs.) records the rule sets and fitness over the generations. In general enteries in this log MUST take the form.

<Unified Log Line> ::= "(" <Entry Type> <Space> {<Argument>} ")"

The Entry type SHOULD be one of "Header", "Rule set", "FitnessLevel", "BestBot", "Generation". This field is case insensertive.

4.7.4.6.1.1 Header

The Unified log MAY contain a Header. If present it SHOULD be the first line in the log. The header MAY contain data to aid analysis.

<Header> ::= "(Header" <SPACE> {"(" <Header-Attribute-Type> <Header-Attribute-Value> ")" } ")"

At the time of writing there where no standard header-type values.

4.7.4.6.1.2 Rule set

This Entry has the same format as the Rule set message from the Cbep standard. See that for details

4.7.4.6.1.3 FitnessLevel

This Entry has the same format as the FitnessLevel message from the Cbep standard. See that for details

4.7.4.6.1.4 BestBot

This Entry records the best Bot within a generation. There MUST not be more then one BestBot entry within the scope of a generation.

<BestBot> ::= "(BestBot" <SPACE> {"(" <BestBot-Attribute-Type> <BestBot-Attribute-Value> ")" } ")"

The Attribute Types currently are Fitness, Pickups, Drops, Hits, and Rule set. Unknown Attributes SHOULD be silently ignored.

4.7.4.6.1.4.1 Fitness

The value of this attribute is a real number representing the fitness of the best bot.

4.7.4.6.1.4.2 Pickups

The value of this attribute is a integer number representing the number of the times the bot has picked up a block.

4.7.4.6.1.4.3 Drops

The value of this attribute is a integer number representing the number of the times the bot has dropped a block.

4.7.4.6.1.4.4 Hits

The value of this attribute is a integer number representing the number of the times the bot has picked up and dropped a block in the correct place.

4.7.4.6.1.4.5 Rule set

This Entry has the same format as the FitnessLevel message from the Cbep standard. See that for details.

4.7.4.6.1.5 Generation

This

4.7.4.6.2 Comms.log

The Comms log contains data for debugging of the Brain/Environment. communications link.

All entries in this log take the form

BBBB >> CBEP message

For messages to the brain

EEEE << CBEP message

For messages to the enviroment


<< , >> , Title , Contents , Index