+-----------------------------------------------------------------------+
|                                                                       |
|                                                                       |
|   A G N  --  N E U R A L   N E T W O R K   C O N T E S T    1 9 9 6   |
|   =================================================================   |
|                                                                       |
|       Second international contest for simulated neural networks,     |
|       organised by >>AG Neuroscience e. V.<< at TH Darmstadt.         |                              |
|                                                                       |
|       - - - - - - - - - - - - - - - - - - - - - - - - - - - - -       |
|                                                                       |
|       documentation to the testing environment                        |
|                                                                       |
|       documentation:          S. Lang                                 |
|       implementation:         J. Loeber, S. Lang, W. Wichern          |
|       version:                07/14/1994, v 1.07                      |
|                                                                       |
+-----------------------------------------------------------------------+
    _    _  _    _  ____    __   ____   _____   ___   _   _  _____    _
   / \  | || \  / ||  _ \  /  \ |  _ \ |_   _| / _ \ | \ | ||_   _|  / \
   \ /  | ||  \/  || |_) )/ /\ \| |_) )  | |  | |_| ||  \| |  | |    \ /
    V   | || |\/| ||  __/ \ \/ /|    /   | |  |  _  || |\  |  | |     V
    O   |_||_|  |_||_|     \__/ |_|\_\   |_|  |_| |_||_| \_|  |_|     O

DEADLINE for REGISTRATION and for SUBMISSION of software or documentation
is being delayed to:
     September 1st, 1996
The contest will take place during the KI-96, which is from 
September 17th-19th in Dresden.

1. Overview
-----------
This documentation is dedicated to the partcipants of the neural network
contest 1996. It includes important information about:
        - the simulation
        - using the testing environment
        - using the executable program and
        - programming details about the contest
        progtrammtechnische Einzelheiten ueber die Durchfuehrung
          des Wettbewerbs

If You want to participate at the contest, first assure that You have got
all files necessary (they are listed in part 2).
If You'd like to examine the abilities of the vessel, read part 8.

2. Files
--------
You should have received the following files:
Source:
        agn.cpp
        agn_1.cpp
        autopilt.cpp
        bitmap.cpp
        boat.cpp
        dummykbd.cpp
        fp.cpp
        timer.cpp
        yournet.cpp
        yournet2.cpp
Includes:
        agn.h
        agn_type.h
        bitmap.h
        boat.h
        fp.h
        net.h
        sensor.h
        timer.h
Objects:
        agn.obj
        autopilt.obj
        bitmap.obj
        boat.obj
        dummykbd.obj
        fp.obj
        timer.obj
        yournet.obj
        yournet2.obj
        egavga.obj
        litt.obj
        trip.obj
        c0l.obj
Libraries:
        cl.lib
        emu.lib
        graphics.lib
        math.lib
Data:
        logo.bmp
        nnc96.cfg
        nnc96.ini
        nnc96.mak
        nnc96.prj
        sea<x>.bmp      (several files)
        sea<x>.ini      (several files)
Documentation:
        nnc96107.doc       (this file)
        nnc96107.dok      
        aufgabe.txt
        ausschr.txt
        termine.txt
Add-On:
        serial.zip      

3. Properties of the simulated world
------------------------------------
After starting the program a 16 color VGA screen is being loaded (called
sea<x>.bmp). The Qualities of the world represented by this image is coded
by means of the colors of its objects:
- LIGHTGREEN and
- BROWN      represent isles or a quay,
- YELLOW     marks the finish,
- LIGHTCYAN  is the color of water,
- BLACK      is used for text,
- WHITE      is reserved for "rays" (see 4.),
- CYAN       is used for displaying the wind within the instruments section
             of the image and
- 8 more colors  are reserved for the vessels of the participants.

During the race wind is blowing from a defined direction with constant
strength and a steady current flows all over the visible world.

The boats are displayed as small polygons including a sail, each in its own
color. They can move about the water freely. Isles or other vessels cannot
be passed through!

The lower portion of the screen contains eight displays, each refering to
one of the vessels. The display consists of five elements.
The upper bar shows the change of the boat`s speed, displayed in this boat`s
color.
Below this are two instruments: to the left a bar (in LIGHTCYAN), showing
the relative speed of water current - to the right a circular display for
the direction of water current (LIGHTCYAN) and the rudder`s direction
(drawn in the boat`s color), both relative to the boat`s direction.
Two similar instruments are to be seen at the bottom: to the left a
directon display for the wind (CYAN) and sail (boat`s color) relative to
the boat`s direction - to the right the wind`s relative speed (CYAN).

4. Properties of the sailing boat
---------------------------------
From within the boat it is impossible to determine the real wind or water
current, because it is moving all the time, driven by these forces. Instead,
the direction and strength of wind and water relative to the motion of the
vessel are calculated. Let VA be the vector of the real wind and VB be the
motion vector of the boat, then the vector of the relative wind AR
calculates as the difference of these two vectors:

                          /|
                         / |
                        /  |
                    -> /   |->      ->   ->   ->
                    AR/    |VA      AR = VA - VB
                     /     |
                    /      |
                  |/  ->   |
                  L_  VB  \|/
                  ---------Y
                          /
                                                              ->
The direction of the relative wind is defined as the angle of AR relative
to the bow of the boat.
The relative water current can be determined accordingly.
If one of the speeds (air or water) is 0, no direction can be determined and
the appropriate variable is set to -1.

The sail can be set to any position from -90 to +90 degrees (measured
relative to the stern of the boat). As the wind swells the sail out, its
form becomes similar to the curved profile of a planeīs wing. The force
which affects the sail is composed not only of the forward thrust but also
of the buoyance. It reaches its maximum at a position of 15 degrees relative
to AR (about 1.2 times the force of AR on a sail set at a right angle).
This force pulls at the sail at a right angle and both drives the sailing
boat forward and sidewards (though less sidewards than forward).

Like the sail the rudder can be set to any position from -90 to +90 degrees
(relative to the stern). Its effect is at an optimum, when it is set at a
right angle to the relative water current.

To give an orientation within the simulated world, the sailor may look into
several directions. This is simulated by lines radiating from the boat
which are shortly displayed on the screen. The information gained by each
of these viewing rays is the color and distance to the next obstacle within
line of sight.

Should the boat crash into an obstacle, its speed is set to zero. If they
collide with another sailing boat, both vessels are stopped and are punished
by means of a handicap: each sailing program will not be called for a number
of iterations equal to the square of their speed at the moment of collision.
You are dearly advised to look out for and avoid other combatants!

5. Programming Interface
------------------------
Parameter
  heading      (i) - direction to the finish, measured relative to the bow
  airdir       (i) - angle of the relative wind,   ---     "     ---
  airspeed     (i) - strength of the relative wind
  waterdir     (i) - angle of the relative current, relative to the bow
  waterspeed   (i) - speed of the boat over water
  sensor[12]  (i/o)- array of sensor data, as described in SENSOR.H
                     Donīt forget to supply valid direction values (from
                     0 to 360 degrees) in the variables sensor[i].dir.
                     Otherwise the values of sensor[i].dist and sensor[i].s
                     will be undefined at the next iteration.
  rudderdir    (o) - set your rudder position here (values from -90 to 90)
  saildir      (o) - set your sail position here (values from -90 to 90)
  name         (o) - copy the name of your network into this variable

Initialization
  Your program will be called once BEFORE the start of the race. At this
  call the sensor values will be undefined. This call is made to give you
  the opportunity to initialize your network and set your rudder, sail
  and sensor directions.

Sensors
  You can perceive your environment by means of sensor rays. If you supply
  valid directions in the variables sensor[i].dir, the programming
  environment will use the dist and s fields of the sensor structur to
  pass you the distance and color of the next obstacle in the user defined
  direction. You may use up to 12 sensor rays. Should you need less than
  that, you must use the sensors with the smallest indices. The programming
  environment ignores sensors with invalid directions AND ALL THE FOLLOWING
  SENSORS AS WELL! The special meanings of the color values passed to you
  in the field s can be found within the file SENSOR.H. If there is no
  obstacle to be seen in a given direction, the distance value returned
  will be negative and the sensor value s will contain "nocolor". Else
  s will be one of "finish", "isle1", "isle2" or a boat color ("boat1_s"
  ... "boat8_s").

Return ~
  Please check the validity of your returned variables:
  - sensor[i].dir    any integer from 0 to 360 (i from 0 to 11)
  - rudderdir and
  - saildir          integers from -90 to 90

6. Program Generation
---------------------
If you are using the Borland C/C++ compiler, the setup is easy, as most of
the settings are contained within the project file you have received.
Check the directory settings and assure that the project window contains
all of the source and object files delivered. You wonīt need the libraries.
Probably you will have to change the directory settings from C:\BC (which
is our setting) to the subdirectory containing your copy of the borland
compiler.

For other compilers you will have to adjust the following settings:
compiler options
  memory model: large
  code generation: DOS Standard
  language: ANSI C or C++
linker call
  <link> <all object files including newly compiled source files>
         <other options you might need on your system>
         -lgraphics.lib -lmath.lib -lemu.lib -lcl -oNNC96
Some compilers might need additional options or the order and spelling
of the options might differ from the format described. If you are having
problems of this kind please refer to the support or hot line of the
software company that made your compiler!

7. Program Usage
----------------
Syntax:
  NNC96 <sea map> <participants>
<sea map> is an image of a lake on which the regatta takes place. It has a
  resolution of 640 times 480 pixel with 16 colors and is stored in the
  windows bitmap (*.BMP) format. The included files SEA<X>.BMP serve as
  examples. If you intend to design another map you should use SEA0.BMP as
  a start. You may only use the colors LIGHTGREEN ("isle1") and BROWN
  ("isle2") for painting the isles and you may paint only within the
  LIGHTCYAN ("water") colored rectangle. Do not change the location of the
  finish!
<participants> is a list consisting of at least one and up to eight
  nonnegative numbers. Each number corresponds to one neural sailing
  program.
  The number 0 will call a keyboard controlled participant (see below!),
  the number 1 is defined for the call of "neural_net1" (your program!),
  the number 2 is defined for the call of "neural_net2" and
  any number greater than 2 results in a call to the built-in autopilot.
  You may specify a number more than once (i. e. the command "nnc96 sea1
  3 1 3" will start a regatta with your network and two sailing boats
  controlled by an autopilot).

At the beginning the program reads some parameters from the file NNC96.INI.
This contains in each line a name-value-pair (and a short remark). Possible
names and values are completly listed in the INI-file. The values of air and
water current are freely selectable. However, the air speed shouldn't grow
above 10 and you should set a current with speeds below half the air speed.
On slow computers you can speed up the race by setting the wind vector
components to high values (although the boat will become more sensitive to
the controls).

After loading the map the program will be busy with internal initialisations
for quite a long time especially on slow computers. The program will be ready
to start, when the sailing boats appear on the screen. Press any key to start
the regatta or <ESC> to exit the program. The <ESC> key is available during the
regatta at all times.

Starting the program in batch mode (enter option "batch: yes" in NNC96.INI)
causes the following changes to the execution of the program:
  - The program won't wait for a key as described above.
  - The regatta will be started anew immediately after the end of the race.
  - You can abort the current race at any time by pressing the <BS> key
    (backspace). The regatta will start anew at once.
The <ESC> key still works as described. You may use this mode for training of
your neural network or to generate training data off line. ATTENTION:
running the program in batch mode with append mode set to "yes" will fill up
your hard disk with the log file! Setting append mode to "no" will result in
a log file that only contains information about the last race and previous
information will be overwritten.

During the race the program continually writes information concerning the
participants into a log file. The name of this file is generated from the
base name "________.LOG" and the numbers of the participants: a program call
like "NNC96 SEA1 1 1 3" creates a log file with the name "113_____.LOG".

The keyboard driven sailor (select participant number 0) can be controlled
as follows:
During every iteration one key press will be evaluated, the key codes
interpreted as follows:
 's' : turn sail to the left for 20 degrees
 'e' : turn sail to the left for 5 degrees
 'd' : let go of the sail and let it turn into the wind
 'r' : turn sail to the right for 5 degrees
 'f' : turn sail to the right for 20 degrees
 'j' : turn rudder to the left for 10 degrees
 'k' : set rudder to 0 degrees
 'l' : turn rudder to the right for 10 degrees

Should you intend to use keyboard input within your program, copy the code
segments from DUMMYKBD.CPP. Do not use the keys <ESC> and <BS>. These are
questioned by the main program. Don't forget that your program will have to
run without keyboard input at the contest!

8. Quick start
--------------
To get an impression of the programming environment and the simulated world,
read paragraph 7 and start the program by entering "NNC96 SEA1 0" (to call
the keyboard controlled sailing boat) or "NNC96 SEA1 3" (to call the autopilot).

9. Changes to be expected
-------------------------
- Regatta map
  The map used for the final contest may differ considerably from the maps
  you have been given. The location of the finish may change as well. Probably
  the size of the boats and isles will decrease to increase the number of
  possible paths to the finish.
- Number of participants
  Currently up to eight sailing vessels can participate. In the final contest
  probably between four and six boats will sail at the same time. This depends
  on the number of participants and the speed of the running program.
- physical properties
  The properties of the sailing boat are derived from discrete versions of
  the equations of force for a real sailing boat. Because of these discrete
  equations and the ignoring of some minor physical effects the boats may
  react in an unnatural way under certain conditions. If this should prove a
  problem, we will do our best to eliminate these feats.
- Limitations to the change of the sail's position
  Currently you can change the sail's position from one iteration to the next
  without limitation. In later versions this will be changed. Then it will be
  impossible to turn the sail for more than 30 degrees from one iteration to
  the next.

10. Known bugs
--------------
  If you encounter some obvious bugs, please contact us.

11. Changes
-----------
1.0 to 1.02:
  - The collision control routine was fixed. The boats shouldn't run _THROUGH_
    obstacles any longer.
  - The program now clears the keyboard input buffer and reacts on all keys
    pressed during the regatta. The participants may use the keyboard as well
    (see the end of paragraph 7).
  - The resolution of timekeeping was increased considerably - times in the
    log file are correct now.
  - A batch mode was integrated into the program. Refer to paragraph 7 for
    a description. Many thanks to Andreas Kircher for the suggestion!
  - The file list in paragraph 2 was updated.
1.02 to 1.04:
  - The size of the boats may be changed by setting the new variable scale
    in the file NNC96.INI (the old value was 1.5).
  - The startup code was enhanced by usage of a new defined file format for
    the image data (*.IBM). The *.IBM file will be generated automatically
    from the *.BMP file, if it doesn't exist or is older than the *.BMP file.
  - The maximum change in the sails' position per iteration is limited to
    30 degrees.
  - The position and direction of the sailing boats can be set in an
    initialization file. The name of this file is connected to the name of an
    image file. Each line determines the X and Y coordinates of one vessel.
    The optional third parameter determines its direction.
1.04 to 1.05
 - A new parameter gust is added in NNC96.INI. It fixes the maximum alteration
   of the normal windspeed.
1.05 to 1.07
 - The global wind direction is shown in a wind rose at the lower right corner
   of the screen. To its right there is also a wind speed meter.
 - The regatta can now be subdivided into several parts. In order to do this
   you will have to add lines containing the coordinates of the intermediate
   checkpoints into the *.INI file that belongs to a map. They should be
   inserted after the definition of the boat's starting coordinates and
   an additional empty line. The last checkpoint should be located on the
   finish line. If you omit the checkpoint definition a default checkpoint will
   be set at the center of the screen's right side. You may define up to
   49 intermediate checkpoints.
   The function parameter HEADING always points to the next checkpoint.
   The return values of the sensor structure is manipulated in such a manner
   that it will actually 'see' the intermediate checkpoints and interpret it
   as FINISH. At the same time the real finish is hidden unless the boat
   is on its way to the final checkpoint.
 - Axel Fischer from Laatzen (Germany) kindly sent us a program extension.
   It is an interface for transferring data from within the program to the
   serial port. We leave the program (to be found in SERIAL.ZIP) to the
   participants of the NNC as is.


Arbeitsgemeinschaft Neuro Science e.V. (AGN)

Technische Hochschule Darmstadt
Karolinenplatz 5
D-64289 Darmstadt 

Germany

EMail-Adress: agn@rbg.informatik.th-darmstadt.de
WWW : www.th-darmstadt.de/diverses/agn/AGN-Homepage.html
Fax: ++49-6151-596453