A Simulation Environment for Continuous Virtual Multi-Agent Systems
User Manual
Gunter Bruns, Peter Mossinger, Daniel Polani, Rene Spalt, Thomas Uthmann and Stefan Weber
1st version: April 23 1994 Current version: V7.0, February 4, 1999
[email protected]
Contents 1 Introduction 1.1 1.2 1.3 1.4
The Purpose of XRaptor System Requirements . . . Notes on the Manual . . . . Notes on the Release . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
2 An Overview of the XRaptor Concept
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
3 3 3 4 4
5
2.1 The Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2 User Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3 Integration of the Control Kernels . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 The Scenarios
7
3.1 The Braitenberg-Vehicle Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2 The Ant-Colony Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4 The Class Group 4.1 4.2 4.3 4.4
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . Team Methods . . . . . . . . . . . . . . . . . . . . . . . . System Methods . . . . . . . . . . . . . . . . . . . . . . . Manipulating World Parameters . . . . . . . . . . . . . . 4.4.1 Manipulation in the Braitenberg-Vehicle Scenario . 4.4.2 Manipulation in the Predator-Prey Scenario . . . . 4.4.3 Manipulation in the Ant-Colony Scenario . . . . .
5 Implementation of the Scenarios
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
5.1 The Class Hierarchy . . . . . . . . . . . . . 5.2 Abstract Classes . . . . . . . . . . . . . . . 5.2.1 The Class Coord . . . . . . . . . . 5.2.2 The Abstract Class Handler . . . . 5.2.3 The Abstract Class Brain . . . . . 5.3 Classes of the Braitenberg-Vehicle Scenario 5.4 Classes of the Ant-Colony Scenario . . . . . 5.4.1 The Type Species . . . . . . . . . . 5.4.2 The Class Ant . . . . . . . . . . . . 5.4.3 The Class Queen . . . . . . . . . . 5.4.4 The Class Ant Food . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
6.1 Code Organization . . . . . . . . . . . 6.1.1 The XRaptor Library . . . . 6.1.2 The Registration Code . . . . . 6.1.3 The Team and Agent Modules 6.2 Installing the \Core" XRaptor . . . 6.2.1 Checklist for Installation . . . . 6.2.2 Making XRaptor . . . . . . . 6.2.3 Making the XRaptor library . 6.3 Compiling User Files . . . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
6 Setting Up and Running XRaptor
. . . . . . . . . 2
. . . . . . . . .
. . . . . . . . .
9
9 9 10 11 12 12 12
12 12 14 14 16 16 17 17 17 17 20 21
21 22 23 23 24 24 24 25 26 26
6.4 Compiling a Tournament . . . . . . . . . . 6.4.1 The Team Side . . . . . . . . . . . . 6.4.2 The Tournament Supervisor Side . . 6.5 Running XRaptor . . . . . . . . . . . . . 6.5.1 XRaptor 3D Window . . . . . . . . 6.5.2 XRaptor Radar Window . . . . . . . 6.5.3 XRaptor Control Panel . . . . . . . 6.5.4 XRaptor Input and Output Window
7 Problems
7.1 Usage Problems . . . . . . . . . . . . . . . 7.2 Other Problems . . . . . . . . . . . . . . . 7.2.1 Problems in XRaptor Extension 7.2.2 Problematic Design Decisions . . .
8 Copyright
. . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
27 28 28 29 31 31 31 32
32 32 33 33 33
33
1 Introduction 1.1 The Purpose of XRaptor XRaptor is an environment for simulation of scenarios in virtual multi-agent worlds. It is written in C++ for UNIX platforms with the X Window System and Motif 1.2. XRaptor
allows studying the behavior of agents in di erent 2- or 3-dimensional continuous worlds. In the current version an agent is either a point in its world, or occupies a circular area or a spherical volume. It contains a sensor unit through which it obtains information about the outside world as well as an actor unit through which it performs actions. The agents are controlled by a userde ned control kernel. The control kernel determines an agent's action based on the sensory input. A typical control kernel is designed to maximize the agent's survival time. The user can construct an agent by implementing concrete control kernels derived from abstract classes (i.e. classes with pure virtual methods) provided by the XRaptor environment, whose pure virtual methods have to be overridden by the user.
1.2 System Requirements XRaptor has been successfully ported to Solaris 2.5.1, HPUX 10.20, Linux 2.0.34, IRIX 6.4, working with the respective native compiler as well as with gcc. The current make le has been
adapted to Solaris 2.5.1 and additional make les are planned for the near future. In the meantime adapting it to the other platforms should not prove too dicult for a user, but particularly the di ering template handling and X-library requirements of di erent platforms may still require some modi cation of the current make le. A con guration script is envisaged for the future. The XRaptor code itself should be fairly portable and we believe it should be not too hard to port it to other platforms than the mentioned. In addition to aforementioned operating systems you need X11R5 and Motif 1.2. If you do not have Motif 1.2, you may try using the free Motif replacement named Lesstif. XRaptor has been successfully compiled using Lesstif. We did experience some minor problems when running it, though, and did not perform extensive tests with Lesstif. Due to our lack of manpower we will 3
not be able to identify and x any problems arising by use of Lesstif. So, consider the Lesstif variant being a probably viable, while unsupported, alternative to using Motif 1.2.
1.3 Notes on the Manual This manual is intended to cover the user-visible aspects of XRaptor. It will consider the di erent scenarios from two perspectives: First, from a global view of the models included in XRaptor and second from a more detailed description of the C++ interfaces provided to create agent controls for each of these models. Section 2 will o er a general overview of XRaptor and the concepts of its implementation. Section 3 presents the scenarios implemented in XRaptor from the modelling perspective. Based on the concepts from Sec. 2, Sec. 4 will describe the class Group which is of fundamental importance for using XRaptor. The concrete implementation following object-oriented concepts is illustrated in Sec. 5. It provides a description of the class structure and the scenario-speci c classes. Setup and starting procedures for XRaptor will be dealt with in Sec. 6. Please note that in the current version of the manual descriptions of some of the scenarios are still missing. Only the Ant-Colony scenario is covered in detail.
1.4 Notes on the Release With this rst public release of the XRaptor simulation environment we wish to meet a frequent request at several di erent occasions where work in connection with XRaptor has been presented. With XRaptor, we intend to ll a gap between completely general and completely specialized continuous world simulators for multi-agent systems, in particular for the simulation of scenarios where tournament can take place between di erent teams. XRaptor has been developed and used for several years now. During this time it has continuously been extended and enhanced, while trying to maintain the original spirit of extendibility, and its original \look and feel". In this period the XRaptor simulation environment has been used for research as well as for education. Di erent scenarios have been implemented and the user interface has undergone a rewrite from scratch. A rst public release had been planned much earlier, but was delayed due to several facts: on the one hand the user interface had been extended to support full 3D graphics for 3D scenarios using the X Window PEX library. On the other hand the rst handbook version turned out to be inadequate for the description of the several di erent new scenarios added to XRaptor in the last years and had to be completely rewritten, and, to support internationality, translated into English. Though during the development of XRaptor we tried to keep an eye on (hopefully) fairly clean coding and a good portability, we could not avoid historical burdens completely. Therefore, even if a scenario is already implemented, switching between the scenarios currently still has to be done by manually hacking the the simulation loop. Although we are currently working on a mechanism allowing an easier and cleaner switching between scenarios, including such a mechanism in the current version would have delayed its release even further, so we decided to release XRaptor in a version with only its most popular
4
scenario active, the Ant-Colony scenario (Sec. 3.2). Although implemented, the 3D Predator-Prey scenario (which is using the PEX graphics) is not made active in this release1 . In a preliminary near future release, we will make available the Predator-Prey and another implemented scenario in addition to the Ant-Colony by a simple switch, before we will be able to o er the conceptually cleaner solution for selecting a scenario in a more distant future. We hope that you will enjoy working with XRaptor. The code should be fairly stable by now. Should you nevertheless encounter bugs, please submit them to
[email protected]. Before you submit bugs, however, be sure to have checked Sec. 7. Bugs in the user manual, patches, critique, comments, suggestions and, of course, fan mail , should also be sent to above address.
2 An Overview of the XRaptor Concept The current section gives a general overview over the XRaptor concept. It is useful to read this section if you want to use XRaptor.
2.1 The Model The simulation takes place in the unlimited, in nite 2 or 3-dimensional space | only bound by the range of double-values. All simulated agents have a position represented by a vector 2 R3 and an orientation 2 R. An agent also maintains a life-energy value that decreases during a simulation run. It can be replenished eating fruit-objects, other agents, or, depending on the scenario, also through other mechanisms. Once its life-energy value drops below a certain threshold, the agent dies. The agents' movements are typically modelled via ordinary di erential equations. These equations are solved for every agent in every step of the simulation run. For reasons of eciency Euler's method is used 2 .
2.2 User Types Fig. 1 gives an overview of the user structure of XRaptor. There are three distinct user types: dependent designer or team , independent designer, and supervisor. The design of the agents' control kernels will depend on the particular virtual world supplied by the simulation environment. Accordingly we call the designers of control kernels dependent designers. Di erent dependent designers can contend with each other by having their respective agents compete with each other in a single virtual world. A dependent designer in XRaptor thus represents a certain team, or as we will also call it, a group of users. The independent designer determines the physics and the laws of nature that apply to the agents and to all other objects of the simulated world. Having direct access to the code and the simulation parameters he maintains control of the characteristics of the virtual world of XRaptor. You will note, however, that a lot of variables exist in the constant le ConstFile that are not documented in this manual. These belong to the other scenarios and a future release will separate the constants belonging to those di erent scenarios. Do not delete or insert lines in ConstFile unless you adapt Constant.C and Constant.h accordingly and don't do that unless you know what you are doing! You may, however, edit the constants within a certain numerical range (Sec. 4.4.3, p. 12). 2 As in XRaptor the simulation of a large number of agents is more important than precision, Euler's method is preferred to the slower Runge-Kutta method. 1
5
Supervisor
Dependent Designer Dependent Designer
User Interface
Modus
World
Independent Designer
Dependent Designer
Figure 1: Overview of the User-Structure of XRaptor
The supervisor controls the progress of the simulation interactively. Besides setting up the visualization monitor, he sets up the mode of operation of XRaptor. The operation modes are described in Sec. 14.2. During the control kernel design the developing teams act both as dependent designer and supervisor. Controlling the simulation both interactively or by way of automated training procedures the teams can assess the performance of their own prototypes. When using XRaptor in a student project, the project management takes the role of the independent designer. In a tournament it also takes over the function of the supervisor from the developing teams, directing the simulation. In this mode the teams can interact with the virtual world only through their agents' sensor and actor modules.
2.3 Integration of the Control Kernels The dependent designers incorporate control kernels of their own design into the simulation environment. Therefore they need to create control classes for their agents and integrate the control kernels ("brains") into the system. Furthermore they require a simulation control class that is used for both: Setting up agent training and adaptation environments in the simulated world and for checking its agents into the simulation environment at the beginning of a tournament. Such a simulation control class is obtained as a derivation from Group (see Sec. 4) and overriding its pure virtual methods. The three virtual Group methods will be called team methods and are described in detail in Sec. 4.2. Two of these methods, training() and command(), provide control over the training process. The third, tournament(), should be called only once at the beginning of a tournament to register the team's agents. Additionally, Group supplies several system methods able to perform global actions not related to a particular agent. The system methods can be used for the training of the control kernels in command and training mode only and are not available in tournament mode (Sec. 4.3). Dependent designers develop their own control kernels deriving them from speci c Brain-classes of the agent-classes provided by XRaptor (Sec. 5.2.3), and overriding their action()-method. 6
orientation eyes
eyes
left engine
right engine
Figure 2: Structure of a Braitenberg-Agent
Analyzing the sensor input (represented by objects of a Sensor class) the agent brain can plan its actions, and carry them out setting the parameters of its actor unit (a subclass of Actor). Sensor information as represented by the class Sensor is grouped into agent-speci c subclasses of the Sensorics class (Sec. 5.1). The classes derived from Sensor and Actor model the respective characteristics of the di erent agents. The independent designer can provide di erent Brain classes for each agent model.
3 The Scenarios XRaptor generally supports two di erent scenario types, 2-dimensional and 3-dimensional ones. The Ant-Colony scenario described in Sec. 3.2 is set in a 2-dimensional virtual world. Although not documented here, additional scenarios are already modelled in the current version of XRaptor and will be treated in a future version of this manual. Among them there is a 3-dimensional predator-prey scenario and a Braitenberg vehicle scenario. The predator-prey scenario is not covered in the current version and the Braitenberg vehicle scenario is covered only as far as relevant for the ant colony scenario.
3.1 The Braitenberg-Vehicle Scenario Braitenberg vehicles (named after Vehicle 3c of Braitenberg (1984)) are driven by two engines, one to the left and one to the right of their orientation axis, respectively (Fig. 2). These engines can be adjusted by real-numbered values between ?1 and 1. When set to the value 1 the respective engine is running forward with maximum speed, whereas setting it to ?1 will make it run backward with maximum speed. If both engines are set to the same positive value, the vehicle will move straight in the direction of its orientation axis. Setting them to the identical negative value will move the vehicle backwards. If both engines are set to di erent values, the vehicle will, apart from the resulting movement, rotate around its center. The system is considered as strongly dampened, i.e. e ects of inertia are ignored in the model. The engine settings directly transform into a velocity value. Formally the movement equations
7
are given as:
x_ (t) = cx (mright (t) + mleft (t)) ^b _ (t) = c (mright (t) ? mleft (t)) Here t 2 R denotes the current time, x 2 R3 the position of the agent center, the angle between the orientation axis and the x0 -axis (2n), ^b 2 R2 the normalized vector in the direction of the orientation axis, mright (t) and mleft (t) the respective engine settings at time t, and nally cx and c constants quantifying the relation between the engine settings and the resulting translational or angular velocity. The relation between ^b and is given by
^b(t) = cos (t) sin (t)
The physical state of a Braitenberg-agent is completely determined by the position x of its center, its direction of movement as de ned by or ^b, and its current life-energy value.
3.2 The Ant-Colony Scenario The Ant-Colony scenario simulates a 2-dimensional world populated by "ant queens" and "ants", represented by the classes Queen and Ant, respectively (Sec. 5.4) 3 . Both types of agents inherit sensor and actor units from the class Braitenberg Vehicle (Sec. 3.1). In particular, the motion concept in the Ant-Colony scenario is the same as in Sec. 3.1. In contrast to Braitenberg vehicles (as modelled in XRaptor), ants contain a subclass Ant Relpos of Sensor. The class Ant Relpos provides them with a view di erent from those in other scenarios: Sensor information is not transformed or distorted, but ants receive the relevant parameters of all objects within a certain range in a 360-degree eld of vision. Additionally, Queen-agents are able to create new Antagents. Both Queen and Ant-agents can eat instances of the class Ant Food, thereby increasing their life-energy. Ant-agents can also regurgitate or \spit" such objects back, i.e. transform part of their own life-energy into an instance of the class Ant Food. But the transformation itself will consume a certain amount of energy (Tab. 3, p. 18). If two agents collide in this scenario, they will both rebound. Furthermore, both of them will lose life energy if they belong to di erent teams. In this scenario the task for a team of agents is to prevail against the others and to remain as the only surviving team. 3 These classes only represent XRaptor agents inspired by ant colonies, without the intention of an modelling
reality in an accurate fashion.
8
4 The Class Group 4.1 Overview The following table presents an overview of the simulation control called Group. The methods are subdivided into team methods (Sec. 4.2) and system methods (Sec. 4.3). It also contains a sub-object of the type Constant Spy which can be used for queries and modi cations of world parameters, i.e. simulation constants. Constant Spy will be treated in Sec. 4.4. The dependent designer derives a team-class from Group. The derived class should adhere to the following conventions: 1. The new class carries the name of the particular team. 2. A constructor method must be supplied by the derived class calling the constructor method of its parent class Group with a string containing the name of the instance of the derived class as argument (typically the class name itself if only one instance is realized). 3. Every instance of the class Group receives a unique integer as group-id, beginning with 1, by which the agents belonging to its team can be identi ed. 4. A destructor method is not explicitly required, but may be useful in some cases | e.g. to save training data or similar information to a le.
4.2 Team Methods The team methods are high-level methods where the concrete training setup can is de ned or where the check-in of agents into a tournament takes place.
9
Class Group Constructor Group(const char* name) Description to be called with the name of the team as parameter. Method void training() Description training method; to be overridden. In this method control kernel instances can be created and checked into the simulation. The agents pertaining to the control kernel can be positioned in the world and full information regarding the world can be requested. This mode allows the application of a wide range of adaptation by performing controlled experiments with known and controllable parameters and, eventually, learning processes. Method void command(const char* cmd) Description method able to process a command-string cmd; to be overridden. A string entered into the XRaptor command window (Fig. 8) is passed to command as parameter cmd and can be processed by a parser (to be supplied by the dependent designer). This way, similar to the training mode, a user-de ned command with full world information access can be executed. While the training mode is used for \batch"-like work, this method allows interaction between the user and the team class. Method void tournament() Description method called once at the beginning of a tournament; to be overridden. In this method control kernel instances should be created and checked in. In contrast to the training mode, the number of objects that can be checked in may be limited. Setting and querying all parameter values or world data is disabled. The only way agents can interact with the world in this mode is via their sensor and actor modules.
4.3 System Methods The system methods concentrate on actions which a ect the simulation in detail, like stepping, checking agents in and out, and inquiring their \alife" status. As general mode to check in the agents (method checkin, Tab. 1) we chose the convention of fat pointers , i.e. an agent brain pointer is created using new and this pointer is checked into the simulator. Saying that the pointer is fat means that it is the responsibility of the simulator to delete the object the fat pointer is pointing to if the corresponding agent is killed. In other words, after an object or agent is checked into the simulator via that pointer, the user is not allowed to call delete on that pointer anymore, because this will be always done by the simulator, even (and this is important!) on a call to checkout4 . 4
The reasons for this design decision are discussed in Sec. 7.2.2.
10
Class Group (cont.) Description methods to be called by the team methods. Method void step() Description carries out one single simulation step; disabled in tournament mode. Method void step(int t) Description carries out t simulation steps; disabled in tournament mode. Method void checkin(* handler) Description a family of methods to check in a control class. A pointer to the control class is given as parameter. The double are used to indicate that for every concrete control class derived from Handler there is a corresponding overloaded checkin method (Sec. 5). This prototype is not to be called directly, one calls the speci c method with the concrete pointer on Handler lled in for . handler is a fat pointer! Method void checkout(Handler* handler) Description removes the given Handler or Brain instance from the simulated world. The pointer given to checkout is invalid after the call, and calling alive() will return false afterwards (see below). Method bool alive(Handler* handler) Description returns true, if the instance handler is pointing to a valid agent, otherwise false. This method should be called before a Handler-object is accessed via a pointer from an overridden training or command-method. Once an agent dies, its control class is destroyed, and the pointer referencing its Handler-object becomes invalid instantaneously. Trying to access invalid pointers is one of the most common sources of errors when using XRaptor in training or command mode. Table 1: The Group system methods.
4.4 Manipulating World Parameters The following tables present the methods of the class Constant Spy, sorted according to the di erent scenarios. For a description of the scenario model see Sec. 3 and for the C++ interfaces see Sec. 5.
11
Class Group (cont.) Object Constant_Spy constant Description using the sub-object constant in the current instance of Group the constant world-parameters can be queried and modi ed.
4.4.1 Manipulation in the Braitenberg-Vehicle Scenario The documentation in this table is restricted to parameters relevant for the Ant-Colony scenario.
Class Constant Spy Description The following pairs of methods are used to query and to set the world parameters, respectively. Methods double collision_energy_rate() void set_collision_energy_rate(double er)
Description proportionality factor for energy loss per simulation step during a collision with a non-penetrable object (e.g. other vehicles). The actual energy loss depends on the actual penetration depth. Methods double braitenberg_rot_energy() void set_braitenberg_rot_energy(double e)
Description energy consumption per simulation step of a Braitenberg Vehicle object.
4.4.2 Manipulation in the Predator-Prey Scenario In the current version of XRaptor this scenario does not contain any constants open to modi cation from the simulation environment. Some parameters can be adjusted using the ConstFile (Sec. 1 and 4.4.3).
4.4.3 Manipulation in the Ant-Colony Scenario In the current version of XRaptor this scenario does not contain any constants open to modi -
cation from the simulation environment. Some parameters can be adjusted using the ConstFile (see also the footnote in Sec. 1).
5 Implementation of the Scenarios 5.1 The Class Hierarchy The class tree in Fig. 3 shows the classes of world objects provided for the Ant-Colony scenario. A later version of this manual will include a tree extended by the classes of other scenarios. There are several parallel class structures that refer to the class hierarchy as given in Fig. 3: 12
Biological
Ant Food
Agent
Ant
Queen Figure 3: Overview of the Class Hierarchy
Biological/Agent Classes : The word Biological refers to simulable localized XRaptor objects. Agents are specialized Biological objects where a Brain can be plugged in.
Handler/Brain Classes : For the dependent designer the Handler and Brain classes are
the only way to implement the agents' behavior in the simulation environment. Each class shown in the class-tree of world-objects, agents and non- agents, has ^ts own Handler class. This Handler is the dependent designer's interface to his objects. Brain is a specialized subclass of a Handler, designed as a control class for instances of Agent. It is used to process the sensory input and determine the action to be taken. Depending on the behavior of a particular agent-type, a control kernel class is derived from the respective Brain-class and the pure virtual action() method is overridden. The specialized Handler or Brain classes adhere to particular namingconventions, e.g. Ant Food Handler or Ant Brain for Ant Food-objects or Ant- agents. They are described in detail in the respective scenarios.
Sensorics Classes :
Sensorics objects are accessed via the Handler/Brain classes of which they are subobjects. For each particular type of agents there is a special Sensorics class. These classes contain species-dependent combinations of sensors each derived from the class Sensor. For the specialized Sensorics classes the naming conventions apply as well; thus they are called e.g. Ant Sensorics and they will be described in Sec. 5.3 and Sec. 5.4. Actor Classes : Similar to the Sensorics classes, the Actor objects are sub-objects of the Handler/Brain classes. The entries in the Actor classes are set to certain values to perform actions in the simulated world. As above, the specialized Actor classes adhere to the naming conventions and are called, e.g. Ant Actor. They are covered in detail in Sec. 5.3 and Sec. 5.4.
13
5.2 Abstract Classes As usual in descriptions of class hierarchies, a method or property common to several subclasses will be presented in the class of the highest hierarchy level.
5.2.1 The Class Coord Before introducing the other abstract classes it is necessary to discuss the class Coord. The 2D- as well as 3D positions of objects in the virtual world simulated by XRaptor is generally handled by Coord. All classes concerned with the position of an agent in the later sections will make use of this class.
Class Coord Description This class represents coordinates in R3 . If the simulation takes place in R2 , the second entry is set to zero (x1 = 0). This is the case e.g. in the Braitenberg-Vehicle and Ant-Colony scenarios. Constructor Coord(double r) Description sets Coord to (r; r; r) 2 R3 . Never use it in 2D-scenarios, since for those x1 has to be 0. (Fig. 4 and see also Sec. 7). Constructor Coord(double x0, double x1, double x2) Description sets Coord to (x0 ; x1 ; x2 ) 2 R3 . Constructor Coord(const Coord &c) Description the copy-constructor. Method void add mult(const Coord &c, double k) Description adds k c to the current object. Method double norm() Description returns the Euclidian length of the current Coord-object interpreted as a vector 2 R3 . Method void set(double x0, double x1, double x2) Description sets the current object to (x0 ; x1 ; x2 ). Method void print() Description prints the current object to stdout. Method void fprint(FILE *file) Description prints the current object to the already opened le file. Object double x[3] Description the actual coordinates as an array, starting with x[0] by Cconventions. Table 2: Class Coord
14
x2 x1
x0
Figure 4: The XRaptor axes and a 2D Braitenberg agent.
Class Operators
Coord void operator=(const Coord &c) void operator=(double r) void operator-=(const Coord &c) void operator*=(double dt) Coord& operator/=(double dt) Coord operator* (double dt) Coord operator/ (double dt) Coord operator+ (const Coord &c) Coord operator- (const Coord &c)
Description overloaded operators with canonical functionality. Table 2: Class Coord
15
5.2.2 The Abstract Class Handler Class Handler Description This is the base class for all other classes that provide dependent designer access to objects in the simulation environment. Method void set pos(const Coord &pos) Description sets the object to the speci ed position pos in the virtual world. This function is only available in training or command mode. Method void position(Coord *pos) Description returns the actual absolute position in pos This function is only available in training or command mode. Method void set energy(double e) Description sets the life-energy value to the speci ed amount e. The parameter e has to be larger than a given threshold for the object to stay alive. This function is only available in training or command mode. Method void user action() Description is called when the object is clicked on with the center button in the XRaptor visualization window; may be overridden by the user. This function is disabled in tournament-mode. Method int group no() Description returns the unique group (team) number of this handler's object. Method double energy() Description returns the current life-energy value.
5.2.3 The Abstract Class Brain Class Brain Description This class is derived from Handler and has some additional functionality to control an agent. Method void set dir(double angle) Description sets the orientation of the object. The angle should be given in radians with respect to the x0 -axis in the x0 x1 -plane in a 3Dscenario, or in the x0 x2 -plane in case of a 2D-scenario (Fig. 4). Method double direction() Description returns the current orientation of the agent in radians (see set dir above). 16
5.3 Classes of the Braitenberg-Vehicle Scenario The classes of the Braitenberg-Vehicle scenario are closely related to the classes of the Ant-Colony scenario and will be treated in detail in a future version of this manual.
5.4 Classes of the Ant-Colony Scenario
5.4.1 The Type Species
Type Species Description an enumeration of the names of all simulated objects of XRaptor (Further types exist that are not used in the current scenarios). Values NO SPECIES, ANT FOOD, ANT, QUEEN
5.4.2 The Class Ant The class Ant is derived from the class Braitenberg (which refers to a Braitenberg vehicle, actually). In the current manual the following tables show all elements and methods of the respective classes, including those inherited from parent classes. Agents of the class Ant are accessed via the class Ant Brain.
Class Ant Brain Constructor Ant Brain(const char *n) Method virtual void action() Description pure virtual method to be overridden. Object Ant Actor actor Description actor sub-object representing the agent's actor unit. Object Ant Sensorics sensor Description sub-object representing the particular agent's sensor unit. Class Ant Actor Constructor Ant Actor() Description initializes all Actor-variables with 0. Variables double left engine double right engine
Table 3: Class Ant Actor
17
Description used to query the current engine settings or to set them to values between ?1 and 1, representing the speed of the respective engine. Negative values signify running backward, positive ones running forward. Variable double spit Description to be set to the amount of life-energy that is converted to an Ant Food-object (Sec. 3.2). Part of the agent's energy is wasted in the process. Variable Pheromone pheromone Description can be set to integer values from 0; 1; ::; 4. These values represent a (user-de ned) state of the object and can be read out by other agents. Pheromone is compatible to int. Variable bool gobble Description setting gobble determines whether in the current step the agent will eat all objects of type Ant Food within a certain range or not. Method bool exceeds limits() Description checks whether the engine settings right engine, left engine and pheromone exceed their limits or not. Table 3: Class Ant Actor
18
Class Ant Sensorics Constructor Ant Sensorics() Object Ant Relpos relpos Description contains a list with the relative position and the type of objects in the range of the current agent's Relpos sensor (see class Ant Relpos below). Object Hunger hunger Description contains a real-numbered hunger-value between 0 and 1, where 0 signi es little and 1 extreme hunger. Hunger is compatible with double. Object Psi psi Description not de ned in the current version of XRaptor. Object Smell smell Description returns a Smell. The class Smell contains an element smell with record elements sweet, sour, bitter, and foul, all of type double and containing double values between 0 and 1. Currently not used in the Ant-Colony scenario.
19
Class Ant Relpos Description contains a list of objects near the current agent. The di erent objects can be accessed using an index i (i = 0; 1; 2; ::) and are sorted by distance to the current agent. The closest object has index 0. Method bool visible(int i) Description returns whether the object with index i is visible or not. This method should always be called before calling any of the Ant Relpos methods below (see Warnings and Sec. 7). Method int group no(int i) Description returns the unique group number for the visible object with index i. Warning: If the requested object is not visible, the requesting agent will removed by the simulator in the next simulation step! Method Pheromone pheromone(int i) Description returns a Pheromone value (compatible with int) in the range 0; 1; ::; 4 signifying the pheromone state of the object. With Ant Food-objects a value of 0 means the food has a low, and 4 a high nutritional value. This value is subject to noise. Queen- and Ant-agents can set their pheromone value themselves (see class Ant Actor above). Warning: If the requested object is not visible, the requesting agent will removed by the simulator in the next simulation step! Method Species species(int i) Description returns the type of a visible object. The type Species is described in Sec. 5.4. Warning: If the requested object is not visible, the requesting agent will removed by the simulator in the next simulation step! Operator Coord operator()(int i) Description returns the position of a visible object as a Coord-object relative to the agent. Coord's x0 -axis is parallel to the agent's orientation axis, the x1 -axis is orthogonal to x0 and increases towards the left of the orientation axis (Fig. 5). In the ant colony scenario x2 = 0 always holds. Warning: If the requested object is not visible, the requesting agent will removed by the simulator in the next simulation step!
5.4.3 The Class Queen The class Queen Brain is similar to the class Ant Brain, and Queen Sensorics is equivalent to Ant Sensorics. Only Queen Actor di ers slightly from the corresponding Ant class. We will only document the di erences between Ant Actor and Queen Actor in the table: 20
x1
object
x0
Figure 5:
Coord
agent orientation
components returned by relpos
Class Queen Actor Constructor Queen Actor() Description initializes all Actor-variables with 0. Variable Ant Brain* child Description If the queen control kernel decides to generate a new ant, the control kernel sets child to a newly generated instance of an Ant control kernel class derived from Ant Brain. The new ant will be created by XRaptor in the next simulation step.
5.4.4 The Class Ant Food Instances of the class Ant Food can only be accessed via an Ant Food Handler object in training or command mode. The class Ant Food Handler is derived from the class Handler (Sec. 5.2.2), and does not contain any additional features.
6 Setting Up and Running XRaptor Because of the di erent usage modes of XRaptor there are di erent ways how project compilations involving XRaptor will look like and those will be described in full during this section. Most probably, however, you will rst like to have a quick look at it before diving into the depths of the di erent compilation procedures. In this case, you can shortcut by just reading Sec. 6.2 to compile and Sec. 6.5 to run XRaptor. In any case we ask you to have the patience to go through the makefile checklist in Sec. 6.2.1. If you are going to use XRaptor beyond this experimental phase, you should read Sec. 6.1.
21
XRaptor Library
Executable xraptor
Registration Competitors.C
Teams and Agents
Teams and Agents
Chiefs.C/h
Masters.C/h
class Chiefs
:::
class Masters
class MyAntBrain
class ThyAntBrain
class MyQueenBrain
class ThyQueenBrain
Figure 6: General organization of XRaptor code. To obtain the executable one has to link the XRaptor library les or the complete library with a registration code (Competitors.C) and with the dependent designers' modules. For details see text.
6.1 Code Organization For performance reasons, the design decision for combining the agent implementation of di erent teams was taken against a client/server concept5 . This means that the code of all di erent agent classes that are to participate in the simulation, e.g. in a tournament, have to be linked into the executable. Figure 6 gives an overview over the XRaptor code. The code is partitioned into three sections: The XRaptor library, the registration code and the dependent designers' (the teams') modules. All three must be compiled and linked together to create an executable. 5 At the time the XRaptor was designed it was completely out of the question that the speed of a typical (not a dedicated high-performance) network would be high enough to support the simulation performance we required. Currently, however, we are considering to extend XRaptor to allow a client/server mechanism for more comfortable usage.
22
#include #include #include Competitor::Competitor() { group.app(new Chiefs("Chiefs")); group.app(new Bosses("Bosses")); group.app(new Masters("Masters")); }
Figure 7: Relevant Structure of Competitors.C
6.1.1 The XRaptor Library In the following we will refer to the XRaptor library also as \core" XRaptor. It contains all the les for the simulation and visualization that are only accessible to the independent designer (Sec. 2.2). There are no \naive" user serviceable functions in this library and we advise to thoroughly understand the simulation mechanism of XRaptor before modifying anything in the core library if you are going to ask us for bug xes afterwards ,.
6.1.2 The Registration Code The registration code contains information about the agent teams to be registered for simulation. The agent teams are represented by instances of classes derived from Group (Sec. 4). For those classes we will use the notion team or agent team and Group class interchangeably. The registration code is placed in Competitors.C which the user has to edit to register given agent teams. A typical form for a Competitors.C le registering three instances from three di erent Group classes named, say, Chiefs, Bosses and Masters (de ned by the dependent designers) is shown in Fig. 7. The supervisor of the simulation (which can be the independent designer as well as the dependent designer) has to edit the Competitors.C le, of which a sample is provided with the distribution. Essentially he has to provide the de nition for the constructor of a class Competitors de ned in the XRaptor library. In this constructor he has to create instances of the given Group classes (in Fig. 7 those are Chiefs, Bosses and Masters) with new and append pointers to those instances to the group member object of the Competitor class. Note that in the example of Fig. 7 the Group classes take a string (const char *) argument that is passed on to their parent class Group, indicating the name under which agents created by those teams will be known in the simulation. According to the di erent possibilities to use XRaptor there are di erent versions of Competitors.C.
23
6.1.3 The Team and Agent Modules and Chiefs.C as found in the src and demo directories of your XRaptor distribution is an example for the source of a team and an agent module. It comprises the team or Group class Chiefs that controls training and tournament registration, but it also includes the code for an implementation of the Ant and Queen brain classes of the Ant-Colony scenario as an example. The registration les Competitors.C in the demo, the src and the tour directories are slightly di erent. Chiefs.h
In the version in the demo directory the le Competitors.C contains the registration as would be typical for a dependent designer who uses the XRaptor library. A single Group
class is registered in this case. In the src directory Competitors.C registers three instances of the example class Chiefs. In tournament mode (see Sec. 6.5.3, p. 6.5.3 how to activate it) the populations generated by these instances ght against each other, thus providing an example for a tournament. If you have perl on your system you do not have to edit the the Competitors.C le in the tour directory. Instead, you can call the perl script compmake with the names of the teams as arguments which are to participate at the tournament. If not, or if the naming conventions di er from those we suggest, you will have to edit the Competitors.C le yourself (Secs. 6.4 and 6.4.2).
6.2 Installing the \Core" XRaptor To get a quick hands-on of XRaptor it is sucient to compile the \essential", the core XRaptor, as we will call it. All other sections deal with further compilation procedures that only become relevant when you export XRaptor for use by, e.g. students or when you set up a tournament between di erent agent teams. To compile XRaptor, cd into the main XRaptor directory XRaptor/src and edit the makefile. Then run make. We believe that you should need to really edit only a few variables to be able to compile successfully, so please take the time to go through the checklist. Should you encounter serious problems compiling XRaptor, please report it as a bug to
[email protected], even if you eventually succeed. Sending us your modi ed makefile (and, if relevant, other modi ed les) will help us a lot.
6.2.1 Checklist for Installation We begin with a checklist for the installation of the main part of XRaptor. Please note that in Tab. 4 variables named FLAGS denote a sequence of ags (that may include but need not to be restricted to path speci cations), but PATH always denotes a single path without any additional option speci cation. We denote some of the makefile variables with necessary, check or optional. Flags which you most probably should set are marked necessary. check means that we suggest these ag values, but you should check whether these are applicable or useful on your system. optional are suggestions where we do not expect a modi cation to be necessary; you may leave them as they are. The variables are listed in the same order as in the makefile. 24
CXX LD
LEX YACC INCFLAGS XRPATH
XRINCPATH XRLIBPATH BOOLDEFS
XRCXXFLAGS
XLIBS XRLDFLAGS
XRLIBS XRTARGET XRLIBNAME
check check
C++-compiler for compilation Linker compatible with compiler speci ed in CXX. Often a good idea to use the linker invoked by the same call as in CXX. check flex (strongly recommended) check bison (strongly recommended) necessary Flags specifying include paths for general system les (e.g. X-libraries) necessary exported XRaptor parent directory where all XRaptor include and library directories will lie exported to user teams. Do not leave any spaces at the end of the line de ning XRPATH! optional directory where XRaptor will export its headers to optional directory where the XRaptor library will be exported to check well, some C++-compilers do not yet know the bool type (really!). If they do, comment out setting this
ag. check
ags set during compilation of the XRaptor package. The C/C++-macro CONSTPATH is set to the default path for ConstFile and PermFile (see Sec. 1 and 4.4.3 for more details). check
ags to link the required X-libraries check with templates, some C++-compilers need to ag the include directories also to their linker. In this case, you might have to export not only the relevant .h, but also the corresponding .C les. check libraries to link beyond X optional target name for the XRaptor executable. optional As set, the XRaptor library will have to be linked using -lXRaptor by the user modules. Table 4: The main makefile ags
6.2.2 Making XRaptor Calling
make creates a le with the name speci ed XRaptor/src directory. In this directory you can xraptor (for details on invocation, see Sec. 6.5).
25
by XRTARGET (xraptor by default) in the now run the core XRaptor by invoking
With the invocation of make, certain header les relevant to users of the XRaptor library or to participants of the tournaments are exported to the locations speci ed by XRPATH, XRINCPATH and XRLIBPATH. Please note that the compilation of the core XRaptor already incorporates the implementation of an agent team represented by the group Chiefs in the le Chiefs.C and Chiefs.h (providing teams and agents like in Fig. 6). In Chiefs.h and Chiefs.C you nd a typical example for the implementation of a Group class is implemented and how agents might be realized. Also note that Competitors.C is registering three instances of Chiefs such that on switching to tournament mode you can observe three identically implemented teams competing with each other.
6.2.3 Making the XRaptor library To make the XRaptor library for use by the teams, use the makefile from Sec. 6.2.1 and call
make public.
This will create the library and place it in the directory speci ed by XRLIBPATH.
6.3 Compiling User Files We assume now the XRaptor library is already installed. To compile user-written Group and Agent classes, we suggest to use a makefile as in the XRaptor/demo directory. Chiefs.C and Chiefs.h are demonstration les identical with those in XRaptor/src and the makefile logics is similar to this in the src directory, however with slight di erences (Tab. 5). You might want to call make depend before a compilation with make whenever you change the include structure of your les. CXX LD
INCFLAGS XRPATH
XRINCPATH XRLIBPATH BOOLDEFS XRCXXFLAGS XRLDFLAGS
check check
C++-compiler for compilation Linker compatible with compiler speci ed in CXX. Often a good idea to use the linker invoked by the same call as in CXX. necessary Flags specifying include paths for general system les (e.g. X-libraries) necessary exported XRaptor parent directory where all XRaptor include and library directories are placed. Should be the same as speci ed at compilation of the XRaptor core (Tab. 4). Do not leave any spaces at the end of the line de ning XRPATH! optional directory of the XRaptor include les optional directory of the XRaptor library check well, some C++-compilers do not yet know the bool type (really!). If they do, comment out this line. check
ags set during compilation of the XRaptor package. check
ag for default XRaptor library path. add other library paths if necessary Table 5: The user makefile ags 26
XRLIBS XRTARGET PUBLIBNAME
TOURPATH
TOURINCPATH
TOURLIBPATH
PUBHEADERS
PUBOBJECTS OBJECTS
LIBOBJECTS
check libraries to link optional target name for the XRaptor executable. necessary under which name to export the current team as library for a tournament. As set, the team will be have to linked as -lChiefs by the tournament supervisor. check directory where the teams will export the include and library les to. This directory should be provided by the tournament supervisor as well as TOURINCPATH and TOURLIBPATH. optional Where the teams' include les will be placed on \publication". Should be provided by the tournament supervisor and must be writable for the users. optional Where the teams' library les will be placed on \publication". Should be provided by the tournament supervisor and must be writable for the users. necessary which headers are to be exported by the team. We strongly suggest not to export more than one header containing just the team's Group class declaration and to encapsulate the rest. necessary object les required to generate an exportable library. optional object les required to generate an executable for local use by the team only. Always needs to include the relevant Competitors.o optional usually equivalent with PUBOBJECTS. Only di erent if published code (Sec. 6.2.3) needs object les different from local one. Table 5: The user makefile ags
6.4 Compiling a Tournament To compile a tournament, two sides have to be considered. First, the on side of the teams the libraries containing their Group and agent classes have to be compiled and exported into the public directories. Second, the tournament supervisor has to specify the teams participating at the tournament in his Competitors.C le and link everything together. Though in principle each team might choose di erent names for its Group class, the exported header, the library and the name it wishes to appear in the simulation, we strongly recommend to adhere to strict conventions, since this makes life much, much easier (believe us). So we suggest choosing exactly the same name and capitalization convention for the Group class, the header, 27
the library and the tournament name | in our example Chiefs for the Group class, Chiefs.h for the header, libChiefs.a for the library and so on6 .
6.4.1 The Team Side Assuming that the team's makefile has been completely set up according to Tab. 5, a call of make public will generate the library in the speci ed tournament path.
6.4.2 The Tournament Supervisor Side The tournament supervisor must set up his make le rst (in the XRaptor/tour directory) which is structured similarly to Tab. 4 and 5. He should create the directories speci ed by TOURPATH, by TOURINCPATH and by TOURLIBPATH (see Tab. 6). This should happen before the teams call make public. Make sure the TOURINCPATH and TOURLIBPATH are writable for the teams and sticky. CXX LD
INCFLAGS XRPATH
XRINCPATH XRLIBPATH BOOLDEFS XRCXXFLAGS XLIBS XRLDFLAGS XRLIBS XRTARGET
check check
C++-compiler for compilation Linker compatible with compiler speci ed in CXX. Often a good idea to use the linker invoked by the same call as in CXX. necessary Flags specifying include paths for general system les (e.g. X-libraries) necessary directory where all XRaptor include and library directories have been placed. Should be the same as speci ed at compilation of the XRaptor core (Tab. 4) and in the teams' make les. Do not leave any spaces at the end of the line de ning XRPATH! optional directory of the XRaptor include les optional directory of the XRaptor library check well, some C++-compilers do not yet know the bool type (really!). If they do, comment out this line. check
ags set during compilation of the XRaptor package. check
ags to link the required X-libraries check
ag for default XRaptor library path. add other library paths if necessary check libraries to link optional target name for the XRaptor executable. Table 6: The tournament supervisor's makefile ags
The only exception one might make is for the name that the team is given during the simulation, i.e. the arguments given to the Group constructor. It may be useful to give di erent names to multiple instances of the same Group class. 6
28
necessary under which name to export the current team as library for a tournament. As set, the team will be have to linked as -lChiefs by the tournament supervisor. TOURPATH check directory where the teams will export the include and library les to. This directory should be created by the tournament supervisor as well as TOURINCPATH and TOURLIBPATH. TOURINCPATH optional Where the teams' include les will be placed on \publication". Should be provided by the tournament supervisor and must be writable for the users. TOURLIBPATH optional Where the teams' library les will be placed on \publication". Should be provided by the tournament supervisor and must be writable for the users. TOURINCFLAGS check the ags necessary to compile the tournament. If any include les in addition to the XRaptor and the teams' header les should be agged, this is the place to do it. TOURLIBFLAGS check The same as TOURINCFLAGS for libraries. TOURLIBS necessary ags indicating the team libraries to link for a tournament. Must include -lXRaptor in addition to the team libraries. Table 6: The tournament supervisor's makefile ags PUBLIBNAME
After the variables are set, if you have perl, calling the compmake script with the team names like perl compmake Chiefs Bosses Masters
will create a Competitors.C le which sets up a registration for the teams Chiefs, Bosses and Masters and essentially looks like in Fig. 7. If your teams do not adhere to thenaming conventions mentioned at Sec. 6.4, p. 6.4, you will have to edit your Competitors.C by hand. After the teams have made their libraries public by make public (Sec. 6.4.1), the tournament supervisor should call make depend and then make. After that, the tournament is ready to run.
6.5 Running XRaptor A simple call of xraptor at the command line (with or without the -train option) will start up a screen as shown in Fig. 8. The signi cance of the di erent windows are explained in the following sections. 29
Figure 8: XRaptor startup screen. XRaptor 3D is the main view screen, XRaptor Radar the overview screen for 3D simulations, the central XRaptor panel is used for control, the XRaptor Input window is used for command mode and XRaptor Output for XRaptor-speci c output. The scene shown is from a 3D scenario not activated in the current release. For details see text.
To be able to run XRaptor certain data les (e.g. PermFile and ConstFile, XRaptor mentions the missing les) must be available either in the current path or in CONSTPATH which is speci ed in the makefile (Tab. 4, p. 25) and compiled into the library. It is possible to open screens on multiple displays by specifying those displays in a le named DisplayFile in the directory where XRaptor is started. Each display in addition to the default one has to be speci ed in a separate line of DisplayFile. The contents of DisplayFile therefore will look like: closebydisplay:0.0 anotherdisplay:0.0 someremotedisplay.other.net:0.0
Of course, the host XRaptor is running on must be allowed to open the speci ed displays. The default display is called master display, while the displays speci ed by DisplayFile are called slave displays. With slave displays only passive manipulations of those described below can take place (e.g. as changing the viewpoint, following an object and similar actions). Active 30
manipulations of the world (like starting and stopping the simulations) can only be controlled from the master display.
6.5.1 XRaptor 3D Window The main window used to observe the simulations. The observer looks in the direction of the
x1 -axis. In 2D simulations the simulation takes place in the x0 =x2 -plane (Fig. 4 and see also the
description of the class Coord, Sec. 2, p. 14). If this window is active, it is possible to use the arrow keys to move the observer left/right (in x0 -direction) and up/down (in x2 -direction), resp. Using the +/- keys on the key pad moves the observer forward/backward (in x1 -direction). The * and / keys are used to zoom in or out by narrowing or widening the angle of the view cone (see below). By clicking on an object it can be marked and automatically followed (see Follow button, Sec. 6.5.3). To unmark, simply click the mouse button at some region in the window not too close to an agent. Clicking the right mouse button on an object causes its life energy to be displayed in the XRaptor Output window, clicking the middle mouse button on an agent causes the agent's userAction() method to be performed (if not in tournament mode). The userAction() method is void by default and can be overridden by the user (Sec. 5.2.2). When running a 2D-scenario, on startup the x0 =x2 -plane is usually too close to the observer, such that the - key will have to be used a few times to get a good picture of the world (Sec. 7).
6.5.2 XRaptor Radar Window It shows an overview over the simulation from above, i.e. it looks at the simulation in the negative direction of the x2 -axis. The objects are shown as dots in the color of their 3D-representation. The cone of the view from the XRaptor 3D window is indicated by the two diverging lines. When an object leaves the region denoted by the frame, it is displayed as a dot at the edge of the window indicating its direction; thus it is possible to detect whether there is an object somewhere outside the window range. It is possible to zoom in and out using + and - on the key pad. This window is only of quite limited usefulness for 2D-scenarios.
6.5.3 XRaptor Control Panel The central panel is used to control the simulation. It is possible to simulate a single simulation step by pressing Animate 1, ten simulation steps by Animate 10 and to perform a continuous simulation by Animate. During continuous simulation the frame rate are 10 simulation steps per frame. The Command/Tournament button switches between command and tournament mode. On startup XRaptor is in command mode. Then it is possible to enter string commands in the XRaptor Input window (see Sec. 6.5.4), which are passed to the command() method of the currently linked Group classes and can be parsed by them, possibly triggering di erent training actions. Command mode can be seen as interactive training mode. In command mode the button shows the label Tournament to indicate that pressing it will switch to tournament mode. Doing so will reset the world and trigger the tournament() methods of all linked Group classes which are essentially only checking in agents for a tournament, where aforementioned animation buttons can be used as before. 31
Likewise, the Group/Energy button can be used to display the team (Group) membership or either the life energy status of di erent agents with di erent colors. Finally, by activating the Follow button the windows will follow an object marked with the mouse (Sec. 6.5.1). Some interactive help is given by pressing the Help button. If XRaptor is started in training mode (i.e. using the -train option), pressing Animate will start running the training() method of the currently linked Group class. In training mode the frame display rate and the possibility to stop the simulation depends on the granularity of the user calls of step() in the training() method.
6.5.4 XRaptor Input and Output Window The XRaptor Input window is used to send commands to the command() method of the currently linked Group class (see also Sec. 6.5.3). It includes a command history with some useful utilities for recovering and editing past commands. The XRaptor Output window is used by XRaptor itself for di erent messages for the user. A later version of this manual will cover further options, environment and resources of XRaptor. For a quick reference, take a look at the le res.doc in the src directory, which gives a commented listing of the resources. It can be modi ed and directly read into the X resource data base.
7 Problems Of course, description of such a package like XRaptor cannot be complete without stating some problems. This section will deal with problems encountered with XRaptor. After listing some of the more commonly encountered user problems and possible remedies in Sec. 7.1, we wish state general problems which we are aware of, but cannot get rid of currently in Sec. 7.2.
7.1 Usage Problems Problem Message
Bio not found. Probably Handler not checked in
displayed in shell window.
XRaptor gives an Assertion == 0
failed:
r[1]
Possible reason This message should only appear in training mode. You try to access the handler or brain of an object or agent which is not checked in, which has been checked out, or which has died during the last call of step(). Check any pointer you are going to use in training() via alive() (Tab. 1, p. 11). Reading Sec. 4.3 again might help, too. In the 2-dimensional scenarios XRaptor checks on some occasions whether the y-component (i.e. the r[1] component) of the object position equals 0. This should always be the case, except if you positioned an object using the Coord(double r) constructor by mistake (Tab. 2, p. 14).
Table 7: Table of typical problems encountered in daily usage 32
I started XRaptor and I do not see anything.
Try pressing - to move your viewpoint back. XRaptor does not make a di erence between a 2D- and a 3D-scenario. A 2D-scenario is merely a 3D-scenario limited to the x0 =x2 -plane (see Fig. 4 and also Sec. 6.5.1). Your viewpoint may be too close to the x0 =x2 -plane initially. XRaptor complains about missing les. Set the data le path in makefile to their location and recompile or copy them to the current path (see also Sec. 6.5, p. 29). Table 7: Table of typical problems encountered in daily usage
7.2 Other Problems
7.2.1 Problems in XRaptor Extension For all those interested in adaptation of the XRaptor simulator to their own needs there is a
problem we are aware of: Due to the historical development of the package many of the comments in the code are in German. As long you are not going to hack the XRaptor kernel, this is not an issue since our demonstration example Chiefs.C and .h is kept in English. But before you are going to modify the kernel you should be aware of it. We hope to gradually shift comments to English, but do not expect this to happen anytime soon since XRaptor is just one of our projects and we use it mainly as workhorse, of which this release is just a by-product. Help translating comments to English is very welcome.
7.2.2 Problematic Design Decisions In Sec. 4.3 we pointed out that checkin is called on a fat pointer. This was a quite problematic design decision to which we saw only two alternatives: giving checkin a meager pointer, i.e. a reference, while the right to delete is maintained by the dependent designers or XRaptor making an internal copy of the agent control passed as parameter to the checkin method. The rst option was rejected because in training mode the dependent designers have the opportunity to check out agent controls and to delete them, but this is not possible during tournament mode. On the other hand we wanted to keep the interface consistent with all modes. The second option was rejected because it would have required to introduce a virtual clone method in the Brain classes which would have to be overwritten by the dependent designers to create a copy of the current object. Since XRaptor was intended for use for education in computer science courses where the students could not be assumed to be pro cient in all conventions of C++ and this was seen as a possible source for very subtle bugs, this option was also dismissed. If you see an alternative concept to solve the checking in problem that avoids aforementioned diculties, we would be glad to know about it.
8 Copyright XRaptor is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. 33
XRaptor is distributed in the hope that it will be useful, but without any warranty ; without
even the implied warranty of merchantability or tness for a particular purpose. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with XRaptor; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Contact Information: Daniel Polani Institut fur Informatik Fachbereich Mathematik/Informatik Johannes Gutenberg-Universitat D-55099 Mainz, Germany
[email protected]
The newest version of XRaptor can be found at: ftp://ftp.informatik.uni-mainz.de/pub/sources/XRaptor.tar.gz
or follow the link below http://www.informatik.uni-mainz.de/PERSONEN/Polani.html
Acknowledgements Well, XRaptor is a large project and this, of course, implicates that we are indebted to a large number of people involved in making this project go. The idea for XRaptor has a long history which we will tell another time. To make a long story short, after several university courses where we used tournament scenarios of deterministic 2-person strategy games as benchmarks for AI programs written by students, we decided that a continuous scenario instead of a discrete one might be more useful to show the advantages of neural or genetic AI approaches. In the winter of 1993/94 we started with a simple 2-dimensional Moby-Dick like pursuit-evasion scenario. Then we extended our ambition to more general simulation settings, including 3D on the one hand and tournament capabilities on the other hand. The 3D simulation setting itself was partly inspired by XAero (Keller et al. 1993) which, however, is just a simulation of the classical mechanical dynamics of bodies and did not have any active agent components. For a small while we thought about adapting the ingenious XPilots program (Stabell and Schouten 1996) to our simulation requirements and to run it also in a kind of general tournament mode, into which generic computer controls with well de ned sensor and actor interfaces could be plugged. However, this proved to be impractical and not exible enough for our purposes, so we then quickly stepped on to design the 3-dimensional simulator which you now all know and (hopefully) love as XRaptor. The rst stable version of XRaptor ran in spring 1994. Since then look and feel as well as the main design concept of XRaptor have survived, although large parts, including the graphics layer have been thoroughly reengineered. Concept and scenarios of XRaptor have been discussed e.g. in (Mossinger et al. 1995, 1997). Most of the participants of the XRaptor development process itself have been mentioned as authors of this manual. Among those not mentioned above we wish to thank Erich Kutschinski 34
for translating the manual from its original German version into English and thus to put us into the position to make XRaptor available to a wider audience. We also thank the participants of several AI courses by now that have contributed to the development of XRaptor by their motivation and feedback. Special thanks go to Peter Dauscher for creating the XRaptor logo and to Jurgen Perl for several design ideas. Much of the e ort has been sponsored by the Institute of Computer Science of the University of Mainz which has provided the infrastructure and the means to develop, write and extend XRaptor, for which we are very thankful. Also we would like to thank Emmanuel Frecon and Olof Hagsand from SICS, the Swedish Institute of Computer Science, for being allowed to base our VRML parser on their code. And last but certainly not least, we wish to thank the innumerate people who have repeatedly asked us for a release of XRaptor; those people motivated us to put that particular e ort into the project which is required to convert something that is merely a stably running software package into something worth to be called a release. We thank all of you and hope you will enjoy using XRaptor.
References Braitenberg, V., (1984). Vehicles: Experiments in Synthetic Psychology. Cambridge: MIT Press. Keller, H., Stolz, H., Ziegler, A., and Braunl, T., (1993). Virtuelle Mechanik { Simulation und Animation von Mehrkorpersystemen. Technical Report 8, Fakultat Informatik, Universitat Stuttgart. Mossinger, P., Polani, D., Spalt, R., and Uthmann, T., (1995). XRaptor { A synthetic MultiAgent Environment for Evaluation of Adaptive Control Mechanisms. In Breitenecker, F., and Husinsky, I., editors, Proc. EUROSIM '95. Elsevier. Mossinger, P., Polani, D., Spalt, R., and Uthmann, T., (1997). A virtual testbed for analysis and design of sensorimotoric aspects of agent control. Simulation Practice and Theory, 5(78):671{687. Stabell, B., and Schouten, K. R., (1996). The Story of XPilot. ACM Crossroads. http://www.acm.org/crossroads/xrds3-2/xpilot.html, January 1999
35
Index
agent team, 22
system methods, 6
checklist installation, 23 code organization, 21 compilation of core XRaptor, 23 of the XRaptor library, 25 of user les, 25 quick, 23 ConstFile, 4 control classes, 6 conventions for Group class, 8 naming, 12
team, 5, 5, 22 team methods, 6 team name convention, 26 usage problems, 31 user types, 5 version of Motif, 3 of operating system, 4 of X Window System, 3
dependent designer, 5 designer dependent, 5 independent, 5 fat pointer, 9, 10 following an object, 30 frame rate, 30 group of users, 5 Group class, 22 independent designer, 5 main XRaptor directory, 23 makefile checklist, 20 meager pointer, 32 naming conventions, 12 naming convention, 26 naming conventions, 12, 28 patience, 20 pointer fat, 9, 32 meager, 32 running 2D-scenario, 30 supervisor, 5, 22 tournament, 26{28 36
