How to use ?

In order to run the simulator, you need to have the following structure:

Top level files

• COPYRIGHT - You shoudl read this file and agree with its contents before running the simulator. It basically just tells you that we don't guarantee anything.
• README - This file gives you this address and quickly explains the changes from previous versions of MASS
• scripts.cfg - is an example of the scripting configuration file for the simulator. Be careful - this is for Windows users, Unix folk should use the file in the Unix-bin directory
• sensors.cfg - is an example of sensor configuration for the simulator. Be careful this is for the Windows machine, Unix boxes should use the file in the Unix-bin directory
• simulator.cfg - is the main configuration file for MASS. Be careful this is for the Windows machine, Unix boxes should use the file in the Unix-bin directory
• mass.bat is created for running MASS under Windows.

Unix-bin

• scripts.cfg - same file as the one at the top level root.
• sensors.cfg - same file as the one at the top level root.
• mass.sh* - Shell script to run MASS under Unix.
• simulator.cfg - same file as the one at the top level root.

lib

• simulator.zip - Simulator main class file.
• ttaems.zip - Class files needed to work with TAEMS objects in Java.
• utilities.zip - Miscellaneous utilities used both in the agent and the classes in the other two libraries.
• swingall.jar - Swing distribution class file.
• motif.jar - Swing Motif specific component.
• windows.jar - Swing Windows specific component..

Lets assume that you have this file (we provide a basic one), just type make run or mass and if everything is correct you should have 4 windows appear, the Event Queue, Global Environment Display, Script control and Simulator.

That's all...the simulator will now be waiting for agents to connect.

If you get an error message, or no windows appear, please add "LEVEL 5" and "FLUSH" to the LOGFILE option in the simulator.cfg and rerun it. Hopefully this will help you determine the error.

How to run ?

In the main window (see figure 1), a line with an icon, the name, the internal simulator ID, the status (false = idle, true = running) and two buttons () that kill or pulse this agent independently of the simulation. When you pulse an agent, only this agent will receive the pulse. The simulator does not process any of the events in its queue at this time, because the simulation state as a whole has not advanced (only that one agent will think time has passed). This button is really only for debugging or testing a connection with a specific agent. The kill button sends a disconnect message to this agent, stopping all executions requested by this agent and freeing all resources used by those executions.

The simulator is controlled by the row of buttons at the bottom:

The start button runs the simulation by periodically sending a pulse to all connected agents waiting for their acknowledgments. Following each pulse, the controller will process all internal events and scripts before progressing to the next time slice. This loop may be broken by clicking on the pause button (which replaces the start while running). If an agent does not acknowledge the pulse sent to it before the timeout (configured in the simulator.cfg file) this agent is booted from the simulation (same as if it had been killed). That means that this agent has been removed from the current simulation run, and will no longer be reachable.

When you want to control every pulse by hand, the step button causes the simulator to just send one pulse to each agent, and processing the events after those pulses are acknowledged.

The button step to works with the text field near it. As one might expect, you simply specify the time when you want the simulator to stop progressing in the text box, and then hit step to to cause the simulator to run to that point in time.. This feature can be very handy during a demonstration for jumping from one interesting spot to the next automaticaly (although this behavior can also be exhibited using the scripting mechanism). The about button just pops up you a window with the copyright information. This is not particularly useful on an everyday basis.

The quit button sends to all agents a disconnecting message and closes all connection ports and sockets before halting the simulator. This is the preferred way to exit the simulator.

The last button (which may sometimes be hidden by the MASL logo) is the reset. It will stop all executing methods, freeing their resources, and send an reset messages to all agents. (Note this hasn't been fully tested. This "feature" is known as bug 37.)

Figure 1: Main Window of the simulator with four agents connected to.

Figure 2: Global Environment for the IHome example.

On startup, the simulator instantiates all the sensors and scripts you have defined in the configuration files, and then waits for incoming agent connections. The exact protocol of handshaking is defined here. Different from previous versions of MASS, the agent is now responsible for providing its objective view to the simulator, which is needed to simulate it method executions. This has several advantages:

• First, agents now carry their own grammar (and thus their behavior specification) with them.
• Second, agents could potentially have a mix of simulated methods (performed by the simulator) and methods where agents run real code (real methods).
• Third, agents can now join and leave at any time during the simulation.
• Fourth, an extension to the third point, the simulator no longer needs a priori knowledge about what agents will be in the run to work correctly.

Figure 3: Global Task structure from the IHome example.

Getting back to the method execution simulation, when the simulator receives the execution request it begins by computes the eventual cost/quality/duration of the method in using the requesting agent's objective view. Because the task structure used by the agent to select this course of action may differ from the objective view held by the simulator, the performance perceived by the agent may not meet its expectations. Resource load across the simulation in particular may widely affect the distribution of the method. After getting values for cost/duration/quality the method execution will be added in the event queue where the current quality and cost are displayed. The time left before completion is also shown. It should be noted that these values are not definitive, as any event may interact with the metehod and thus change these values as time progresses (especially if a resource is overloaded). Figure 4 shows the event queue of the IHome example at time 12.

Grab 4: Event Queue showing the execution of two methods for the IHome example.

How to configure ?

We have added a new sensing mechanism, now each agents could sense only what it allow to. You have to add this line in the simulator.cfg file
use:
SENSORS: sensors.cfg

Here the sensor file :
; Format is simple
; Separator is comma
; Sensor comma
; ClassType comma
; Free String matching
; Free list of parameter separated by colon. Like Type:Value
; Deviation parameter is defined like that:
; Error function as (prob token min max unit) token is from (= + -) and
; unit is (# for fixed percent, ! for fixed value,
; % random percent , ~ for random value )


Sensor , ResourceSensor , Resource Hotwater, Resource :HotWater, Deviation :((0.2 = 2 5 #)(0.8 + 1 5 !))

Sensor, ResourceSensor, Sensor, Deviation:(1.0 + 1 5 %)



Scripting module

Grab 5: Scripting control window. The scripting mechanism built inside the simulator is designed to allow the modification of just about everything of interest in the simulation. We have written a separate page describing the scripting definition, how it is organized, used and extended. You can read it here