+-----------------------------------------------------------------------+ | | | | | 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 | | ================================================================= | | | | Zweiter internationaler Wettbewerb fuer simulierte | | neuronale Netzwerke, veranstaltet von der AG Neuroscience | | e. V. an der TH Darmstadt. | | | | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | | | Dokumentation zur Entwicklungsumgebung | | | | Dokumentation: S. Lang | | Programmierung: J. Loeber, S. Lang, W. Wichern | | Stand: 14.7.1994, Version 1.07 | | | +-----------------------------------------------------------------------+ _ _ _ _ __ _ _ _______ _ __ _ / \ \\ // | | /__\ | | | | |__ __| | | /__\ / \ \ / \\ /\ // | | // | |_| | | | | | // _ \ / V \\//\\// | | \\__ | _ | | | | | \\__/| V O \/ \/ |_| \__/ |_| |_| |_| |_| \__/| O ANMELDE- und ABGABESCHLUSS fuer den Wettbewerb: Der Termin wird verschoben auf den 01. 09. 1996 Dieser Termin ist verbindlich fuer alle Teilnehmer. Die Endausscheidung wird stattfinden w„hrend der KI-96, die vom 17.-19. 09. 1996 in Dresden stattfindet. 1. Uebersicht ------------- Diese Dokumentation wurde fuer die Teilnehmer am NNC '96 geschrieben und enthaelt wichtige Informationen ueber: - die Simulation - die Nutzung der Entwicklungsumgebung - die Benutzung des ausfuehrbaren Programms und - programmtechnische Einzelheiten ueber die Durchfuehrung des Wettbewerbs Wenn Sie am Wettbewerb teilnehmen moechten, pruefen Sie zunaechst die Vollstaendigkeit der mitgelieferten Dateien (siehe Abschnitt 2!). Wenn Sie sich vom Verhalten des Bootes ein Bild verschaffen wollen, lesen Sie Abschnitt 8. 2. Dateien ---------- Sie sollten die folgenden Dateien erhalten haben: Quellcode-Dateien: agn.cpp agn_1.cpp autopilt.cpp bitmap.cpp boat.cpp dummykbd.cpp fp.cpp timer.cpp yournet.cpp yournet2.cpp Include-Dateien: agn.h agn_type.h bitmap.h boat.h fp.h net.h sensor.h timer.h Objekt-Dateien: 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 Bibliotheken: cl.lib emu.lib graphics.lib math.lib Daten-Dateien: logo.bmp nnc96.cfg nnc96.ini nnc96.mak nnc96.prj sea.bmp (mehrere Dateien) sea.ini (mehrere Dateien) Dokumentation: nnc96107.dok (diese Datei) nnc96107.doc aufgabe.txt Aufgabenstellung ausschr.txt Ausschreibung termine.txt die neuen Termine Add-On: serial.zip 3. Eigenschaften der simulierten Welt ------------------------------------- Nach dem Start des Programms wird die Regattastrecke in Form eines 16-Farb- VGA-Bildes (sea.bmp) geladen. Die Beschaffenheit der Welt ist durch die Farben der Objekte in diesem Bild codiert: - LIGHTGREEN und - BROWN sind fuer Inseln oder Uferbegrenzungen reserviert - YELLOW ist die Farbe der Ziellinie - LIGHTCYAN ist Wasser - BLACK ist die Textfarbe - WHITE ist die Farbe fuer "Sehstrahlen" (siehe Abschnitt 4) - CYAN wird fuer die Anzeige des relativen Windes verwendet und - 8 weitere Farben sind fuer die teilnehmenden Boote reserviert Waehrend des Rennens blaest ueberall ein gleichmaessiger Wind und das Wasser stroemt mit gleichmaessiger Geschwindigkeit in eine konstante Richtung. Die Boote werden als kleines Polygon mit Segel dargestellt, jedes in seiner eigenen Farbe. Sie koennen sich ueberall auf dem Wasser frei bewegen. Inseln oder andere Boote koennen nicht durchfahren werden! Fuer jedes der maximal acht Boote existiert eine Anzeige am unteren Bild- schirmrand. Diese enthaelt oben eine Anzeige fuer die Geschwindigkeitsaenderung, in der Farbe des korrespondierenden Bootes dargestellt. Darunter sind zwei Anzeigen: links die Geschwindigkeit des Bootes ueber Wasser, also die relative Wassergeschwindigkeit (in LIGHTCYAN dargestellt) - rechts daneben eine Richtungsanzeige fuer die relative Wasserstroemung (in LIGHTCYAN) und die augenblickliche Ruderstellung relativ zum Boot (in Bootsfarbe). Ganz unten sind zwei aehnliche Anzeigen angeordnet: links die Richtungs- anzeige fuer den relativen Wind (CYAN), bzw. die Segelstellung (Bootsfarbe) und rechts die Staerke des relativen Windes (CYAN). 4. Eigenschaften des Segelbootes -------------------------------- Auf dem Boot kann niemals der tatsaechliche Wind oder die absolute Wasser- stroemung festgestellt werden, da es sich immer - angetrieben von diesen Kraeften - bewegt. Stattdessen wird Richtung und Staerke des Windes und des Wassers relativ zur Ausrichtung und Bewegung des Bootes ermittelt. Ist zum Beispiel VA der Geschwindigkeitsvektor des absoluten Windes und VB der Geschwindigkeitsvektor des Bootes, dann berechnet sich der Vektor des relativen Windes AR als Differenz dieser Vektoren: -> -> -> AR = VA - VB Die relative Windrichtung ist der Winkel von AR relativ zum Bug des Bootes. Entsprechend ist die relative Wasserstroemung zu ermitteln. Das Segel kann zwischen -90 und +90 Grad eingestellt werden (relativ zum Heck des Bootes). Da es sich im Wind blaeht wirkt nicht nur der Winddruck auf den Vortrieb des Bootes, sondern auch Auftriebskraefte wie bei einem Flugzeugfluegel. Die Gesamtkraft, die auf das Segel wirkt, ist bei einer Segelstellung von etwa 15 Grad relativ zu AR am groessten (etwa 1.2 mal groesser als bei Segelstellung senkrecht zu AR. Diese Kraft wirkt senkrecht zum Segel. Die Komponente dieser Kraft in Bootslaengsrichtung sorgt fuer den Vortrieb, die Komponente senkrecht zur Bootsrichtung verursacht eine Abdrift des Bootes, die allerdings durch den groesseren Stroemungswiderstand vermindert wird. Das Ruder kann ebenfalls zwischen -90 und 90 Grad gestellt werden. Die Ruderwirkung ist am Groessten, wenn es senkrecht zur relativen Wasser- stroemung steht. Zur Orientierung in dieser simulierten Welt kann der Segler vom Boot aus in verschiedene Richtungen blicken. Dies wird durch Sehstrahlen simuliert, die kurz im Bild eingeblendet werden. Als Information liefert jeder Sehstrahl die Farbe und Entfernung des naechsten Hindernisses. Sollte das Boot gegen ein Hindernis stossen, wird sofort gestoppt. Ist das Hindernis ein anderes Boot, erhalten zusaetzlich beide Boote ein Handicap: die Boote werden fuer eine Anzahl von Iterationen nicht aufgerufen, wobei diese Anzahl dem Quadrat der Eigengeschwindigkeit entspricht. Man sollte also stets Ausschau nach anderen Booten halten! 5. Programmierschnittstelle --------------------------- Parameter heading (i) - Richtung des Ziels in Grad, relativ zum Bug des Bootes airdir (i) - Richtung des relativen Windes --- " --- airspeed (i) - Staerke des relativen Windes waterdir (i) - Richtung des relativen Windes, relativ zum Bug des Bootes waterspeed (i) - Geschwindigkeit des Bootes ueber Wasser sensor[12] (i/o)- Feld mit Sensordaten, wie in SENSOR.H beschrieben Denken Sie daran, fuer alle benoetigten Sehstrahlen eine Richtung im Feld snesor[i].dir im Bereich 0 bis 360 Grad anzugeben. Sonst sind beim naechsten Aufruf die Werte von sensor[i].dist und sensor[i].s nicht definiert. rudderdir (o) - stellen Sie hier Ihr Ruder ein (-90 bis 90) saildir (o) - stellen Sie hier Ihr Segel ein (-90 bis 90) name (o) - kopieren Sie den Namen ihres Netzes in dieses Feld! Ist eine der uebergebenen Geschwindigkeiten (airspeed oder waterspeed) gleich Null, so kann dafuer keine Richtung ermittelt werden und der Wert der entsprechenden Richtungsvariablen ist -1. Initialisierung Ihr Programm wird VOR Start der Regatta einmal aufgerufen. Bei diesem Aufruf erhalten Sie noch keine gueltigen Sensorinformationen. Benutzen Sie diesen Aufruf, um Ihr Programm zu initialisieren und vor allem Ihre Sensor-, Ruder- und Segelstellungen zu definieren. Sensoren Sie koennen Ihre Umwelt durch Sehstrahlen wahrnehmen. Wenn Sie in den Feldern sensor[i].dir eine Richtung definieren, erhalten Sie bei der naechsten Iteration von der Entwicklungsumgebung in den Feldern sensor[i].dist und sensor[i].s den Abstand und die Farbe des naechst- gelegenen Hindernisses in dieser Richtung. Ihnen stehen maximal 12 Sehstrahlen zur Verfuegung. Sollten Sie weniger benoetigen, benutzen Sie die Sensoren mit den kleinsten Indices (0 bis N). Die Entwicklungsumgebung ignoriert Sensoren mit ungueltigen Richtungsangaben UND ALLE FOLGENDEN SENSOREN! Die Bedeutung der von der Entwicklungsumgebung geliefertenSensor- werte koennen Sie der Datei SENSOR.H entnehmen. Wenn kein Hindernis zu sehen ist, wird eine negative Distanz und der Sensorwert "nocolor" zurueckgegeben. Andernfalls treten nur die Farben "finish", "isle_1", "isle_2" oder eine Bootsfarbe ("boat1_s" ... "boat8_s") auf. Rueckgabewerte Achten Sie darauf, dass die von Ihnen zurueckgegebenen Parameter im gueltigen Wertebereich liegen: - sensor[i].dir im Bereich 0 bis 360 (i zwischen 0 und 11) - rudderdir und - saildir im Bereich -90 bis 90 6. Programmerzeugung -------------------- Wenn Sie den C/C++-Compiler von Borland verwenden, eruebrigen sich die Einstellungen, da diese in der mitgelieferten Projekt-Datei enthalten sind. Vergewissern Sie sich, dass die Pfade stimmen und im Projektfenster alle mitgelieferten Objekt und Source-Dateien enthalten sind. Die mitgelieferten LIB-Dateien benoetigen Sie nicht. Der von uns verwendete Pfad fuer den Borland-Compiler ist C:\BC . Diesen muessen Sie ggf. anpassen. Bei andern Compilern machen Sie folgende Einstellungen: Compileroptionen Speichermodell: large Codegenerierung: DOS Standard Sprache: ANSI C oder C++ Linkeraufruf -lgraphics.lib -lmath.lib -lemu.lib -lcl -oNNC96 Einige Compiler benoetigen vielleicht andere oder zusaetzliche Optionen. Bei Problemen wenden Sie sich bitte an die Hersteller ihres Compilers oder andere Fachleute - wir koennen nicht alle Compiler kennen!!! 7. Benutzung des Programms -------------------------- Syntax: NNC96 Die ist ein Bild des Regattastrecke im Format 640*480 Pixel, 16 Farben, gespeichert im Windows-BMP-Format. Einige Beispielkarten werden mitgeliefert (sea.bmp). Wenn Sie selbst eine Karte entwerfen wollen, benutzen Sie "sea0.bmp" als Vorlage. Zeichnen Sie nur mit LIGHTGREEN oder BROWN (den moeglichen Inselfarben) im LIGHTCYAN (Wasser) ausgefuellten Bereich! Veraendern Sie nicht die Lage der Ziellinie! ist eine Liste von maximal acht (minimal ein) nichtnegative ganze Zahlen. Jede Zahl entspricht einem (neuronalen) Segelkapitaen. Mit 0 koennen Sie die Tastatursteuerung als Teilnehmer anmelden, mit 1 rufen Sie "neural_net1", also ihr eigenes Programm, mit 2 rufen Sie "neural_net2" und jede andere Zahl erzeugt einen Autopilot. Durch mehrfache Angabe einer Zahl koennen Sie mehrere Boote mit identischer Steuerung starten. Das Programm liest zu Beginn einige Parameter aus der Datei NNC96.INI. Diese enthaelt in jeder Zeile ein Namens-Werte-Paar (sowie einen kurzen Kommentar). Moegliche Namen und Werte sind vollstaendig in der mitgelieferten INI-Datei aufgefuehrt. Die Werte fuer die Vektoren der Wind- und Wasserstroemung koennen im Prinzip beliebig gewaehlt werden. Sie sollten allerdings den Betrag der Windgeschwindigkeit nicht ueber 10 setzen und die Wassergeschwin- digkeit hoechstens halb so gross waehlen. Wenn Sie nur ueber einen langsamen Rechner verfuegen, koennen Sie dies ueber die Windgeschwindigkeit ein wenig ausgleichen (allerdings reagiert dann die Steuerung empfindlicher). Nach dem laden der Seekarte fuehrt das Programm noch interne Initialisierungen aus, die auf manchen Rechnern etwas lange dauern. Das Programm ist startbereit, wenn die Boote auf dem Bildschirm erscheinen. Druecken Sie auf eine Taste, um die Regatta zu starten, oder ESC zum Abbruch. Auch waehrend der Regatta koennen Sie mit ESC abbrechen. Wenn Sie das Programm im Batchmodus (Option "batch: yes" in NNC96.INI) starten, bewirkt dies folgende Aenderungen im Programmablauf: - Das Programm wartet nicht mehr auf Tastendruecke, wie oben beschrieben. - Das Rennen wird nach Beendigung sofort neu gestartet. - Sie koennen das laufende Rennen durch druecken der Taste (Backspace) abbrechen und neu starten. Die Taste bewirkt wie bisher den Programmabbruch. Sie koennen diesen Modus benutzen, um ihr neuronales Netz zu trainieren, oder Trainingsdaten zu generieren. ACHTUNG: Wenn Sie das Programm unbeaufsichtigt im Batchmodus betreiben und "append: yes" gesetzt haben, wird ihre Festplatte von der Log-Datei vollgeschrieben! Im Modus "append: no" enthaelt die Log-Datei immer nur die Informationen zum letzten Rennen. Waehrend des Rennens schreibt das Programm staendig Informationen zu den Teilnehmern in eine Log-Datei. Der Name dieser Datei wird generiert aus dem Basisnamen "________.LOG" und den Nummern der Teilnehmer; ein mit "NNC96 SEA1 1 1 3" gestartetes Programm erzeugt die Log-Datei "113_____.LOG". Der Tastaturskipper (Teilnehmer Nummer 0) wird wie folgt bedient: In jeder Iteration wird ein Tastendruck ausgewertet; dabei bedeutet: 's' : Segel um 20 Grad nach links drehen 'e' : Segel um 5 Grad nach links drehen 'd' : Segel flattern lassen, d. h. in Windrichtung stellen 'r' : Segel um 5 Grad nach rechts drehen 'f' : Segel um 20 Grad nach rechts drehen 'j' : Ruder um 10 Grad nach links drehen 'k' : Ruder auf 0 Grad stellen 'l' : Ruder um 10 Grad nach rechts drehen Wenn Sie zu Trainingszwecken eine Tastaturabfrage in "neural_net()" integrieren wollen, verwenden Sie dieselben Codesegmente wie in DUMMYKBD.CPP. Die Tasten und sollten Sie nicht benutzen, da sie vom Hauptprogramm abgefragt werden. Denken Sie daran, dass ihr Programm waehrend der Endausscheidung ohne Tastatur auskommen muss! 8. Schnellstart --------------- Wenn Sie sich einen Eindruck von der Entwicklungsumgebung und den simulierten Umweltbedingungen verschaffen wollen, lesen Sie Abschnitt 7 und starten Sie das Programm mit "nnc96 sea1 0" (fuer die Tastatursteuerung) oder "nnc96 sea1 3" (fuer den autopilot) (Sie koennen statt sea1 auch eine andere Seekarte auswaehlen). 9. Zukuenftige Aenderungen -------------------------- - Regattastrecke Das Aussehen der Seekarte fuer die Endausscheidung ist noch voellig offen. Das Ziel muss sich nicht unbedingt rechts befinden. Wahrscheinlich wird es kleinere Boote und Inseln geben, sodass es mehr moegliche Durchfahrten gibt. - Anzahl der Teilnehmer Zur Zeit koennen bis zu acht Segler teilnehmen. Bei der Endausscheidung werden voraussichtlich vier bis sechs Boote gleichzeitig gegeneinander fahren. Dies haengt von der Anzahl der Wettbewerbsteilnehmer und der Ausfuehrungsgeschwindigkeit des Programms (und der neuronalen Netze) ab. - physikalische Eigenschaften Die Eigenschaften des Segelbootes beruhen auf einer Diskretisierung der Kraeftegleichungen fuer ein echtes Segelboot. Aufgrund dieser Diskre- tisierung und der Vernachlaessigung zusaetzlicher geringfuegiger Effekte kann es unter bestimmten Bedingungen zu unnatuerlichem Verhalten des Bootes kommen. Soweit dies fuer faire Wettbewerbsbedingungen notwendig erscheint, sollen diese Effekte noch eliminiert werden. - Begrenzung der Segelstellungsaenderung Zur Zeit laesst sich das Segel von einer Iteration zur naechsten in eine beliebige andere Stellung bringen. Dies wird in kommenden Versionen (spaetestens bei der Endausscheidung) geaendert, sodass das Segel bei jeder Iteration nur um einen maximalen Drehwinkel von z. B. 30 Grad gedreht werden kann. 10. Bekannte Fehler ------------------- Falls Ihnen offensichtliche Fehler auffallen, benachrichtigen Sie uns bitte ueber die bekannten Adressen. 11. Aenderungen --------------- 1.0 auf 1.02: - Die Kollisionskontrolle wurde korrigiert. Die Boote sollten jetzt nicht mehr in Hindernisse _HINEIN_fahren. - Die Tastaturabfrage wurde verbessert: das Programm reagiert auf alle eingegebenen Tasten (sofern diese verwendet werden) und die Teilnehmer koennen auch eine Tastaturabfrage in ihr Programm integrieren. (siehe Ende des 7. Abschnitts) - Die Genauigkeit der Zeitmessung wurde erheblich verbessert - die Zeiten in der Log-Datei sind jetzt korrekt. - In das Programm wurde ein Batchmodus integriert. Er ist im Abschnitt 7 beschrieben. Vielen Dank an Andreas Kircher fuer diese Anregung! - Die Dateiliste in Abschnitt 2 wurde aktualisiert. 1.02 auf 1.04 - Die Boote sind ueber die Variable scale in der Datei NNC96.INI frei skalierbar (Bisherige Groesse 1.5). - Die Initialisierungsphase wurde beschleunigt. Dies wurde ermoeglicht durch ein eigenes Dateiformat fuer die Bilddatei (*.IBM). Diese Datei wird automatisch aus der *.BMP-Datei generiert, wenn sie noch nicht existiert oder aelter ist. - Die maximale Aenderung der Segelstellung pro Iterationsschritt ist auf 30 Grad beschraenkt. - Die Position und Ausrichtung der Boote kann ueber eine Datei festgelegt werden. Diese ist jeweils mit der Bilddatei gleichen Namens verknuepft. Jede Zeile bestimmt die X- und Y-Koordinaten eines Bootes. Die dritte Koordinate (Ausrichtung des Bootes) ist optional. 1.04 auf 1.05 - In der Datei NNC96.INI gibt es den neuen Parameter gust. Er gibt an, wie stark Boeen von der sonst konstanten Windgeschwindigkeit abweichen duerfen. 1.05 auf 1.07 - Auf vielfachen Wunsch eines einzelnen Herren gibt es jetzt endlich eine Windrose fr die globale Windrichtung mit zusaetzlicher Windgeschwindig- keitsanzeige. - Die Regatta kann nun in mehrere Teilstrecken zerlegt werden. Dazu muss in der zur Seekarte gehoerigen .INI-Datei nach der Definition der Bootsstartpositionen und einer Leerzeile die Liste der Koordinaten fuer die Zwischenziele angegeben werden. Die Koordinaten des letzten Zielpunktes sollten auf der eingezeichneten Ziellinie liegen. Wenn keine Zielkoordinaten angegeben werden, wird die Mitte der rechten Seite des Bildschirms als Ziel angenommen. maximal 49 Zwischenziele duerfen definiert werden. Der an YOURNET.CPP uebergebene Parameter HEADING zeigt immer die Richtung zum naechsten Zielpunkt. Sehstrahlen, die in geringem Abstand das naechste Zwischenziel passieren, liefern den Abstand zu diesem Punkt und die Farbe FINISH zurueck. Andererseits sind alle anderen Zielpunkte fuer die Sehstrahlen unsichtbar und die im Bild sichtbare Ziellinie wird als ISLE_1 interpretiert, bis der letzte Zielpunkt angesteuert wird. - Axel Fischer aus Laatzen hat uns freundlicherweise eine Programmerweiterung zugeschickt. Es handelt sich um eine Schnittstelle zur Ausgabe von Daten aus dem Programm auf den seriellen Port. Wir ueberlassen den Teilnehmern des NNC die uns zugesandten Programme (zu finden in SERIAL.ZIP) zur freien Verwendung. Arbeitsgemeinschaft Neuro Science e.V. (AGN) Technische Hochschule Darmstadt Karolinenplatz 5 D-64289 Darmstadt EMail : agn@rbg.informatik.th-darmstadt.de WWW : www.th-darmstadt.de/diverses/agn/AGN-Homepage.html FAX: ++49-6151-596453