Régis Vincent

How to run ? How to configure ? How to use ? MASS Documentation
How to script ? How to talk to ?

How to use ?

To use the simulator is quite simple, the idea is to start a process listen to a port. Every agent could connect at anytime and take part to the run. The agent should respect the identification protocol. After that, an agent well registred routes all its messages through the simulator.

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

Top level files
Unix-bin
This directory contains shell script and configuration files for Unix machines. We assume that you know how to run a shell script.
lib
In order to run MASS need an configuration file. The section How to configure ? explains you how to make this file.

Let assumes that you have this file (we provide a basic one), just type make run or mass and if everything is correct you should have 3 windows poping up, the Event Queue, the Global Environment Display and the Simulator.

That's all... Now the simulator is waiting for agent to connect.

If you get an error or no windows, please add the LEVEL 5 with the FLUSH option in the simulator.cfg and rerun it in order to determine the error.

How to run ?

When an agent successfully connects to the simulator (if you get a connection error check the Agent HOWTO.) It should add an new icon in the simulator main window and in the global environment display. For example the grab 2 shows the global environment in the Warren example.

In the main window (see grab 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 and will ack to it. The simulator DOES NOT process any events because the simulator central DID NOT CHANGED ! This button is only for debugging or testing a connection with a specific agent. The kill button sends a disconnecting message to this agent, stopping all executions requested by this agent and freeying all resources used by these executions.

The simulator is controlled by the six buttons at the bottom:

The start button run the simulation. When you click on start the simulator sends a pulse to all agents connected and wait for their acknowledgements. The next step is to process all internal events and after the loop goes on with the next pulse. This loop may be stop by clicking on the pause button (which replace the start). If an agent does not ack to the pulse before the timeout (configured in the simulator.cfg file) this agent is booted off (similar as killed). That means that this agent may not participate anymore to this simulation.

When you want to control every pulse by hand, the step button made the simulator just sending one pulse and processing the event at this time.

The button step to works with the textfield near it. Simple, you specify the time when the simulator has to pause, and you step to this time. This feature is very "handy" in a demonstration for jumping from interesting part to others automaticly. We even use this step to function in the events scripting mechanism, but chutt, that's MASS 1.2 and I'm not supposed to talk about it. The about button just pops up you a window with the copyright information. This is really not useful.

The quit button sends to all agents a disconnecting message and close every connections port and sockets before exiting of the simulator. This is the normal way to exit of the simulator.

The last button (which may sometimes be hidden by the MASL logo) is the reset. It stops every executions, freeying every resources, and send an reset messages to all agents. This reset is not fully tested. See this "bug" is known as bug 37.


Grab 1: Main Window of the simulator with four agents connected to. Dann this view is very old.


Grab 2: Global Environment for the Warren example.

The simulator instiate all the sensors and all the events you have defined in the simulator.cfg, then it waits for the agents to connect to. The exact protocol of handskaking is defined here. As the opposite to the previous of MASS, now the agent has to send the objective view to the simulator, in order to simulate it. This has several advantages:

The drawback is that the agent must generate the TÆMS objective view for the simulator and send to it at handskake. After reception, the simulator shoud display a new window that is the TAEMS Global View. This view contains ojective view the task structure. The grab 3 shows this window.


Grab 3: Global Task structure from the Warren example.

After the simulator receives the task structure, the agent may after that request the simulator for one or several executions. To be able to do so, teh agent should send its request during what we call its pulsing time. What the heck is the pulsing time ? Simple in order to be sure that the simulation is determinic, we need to control the time when the event occurs. So MASS controls the time by telling the agents when they have to run: the pulsing time. When the agent has finshed to run it sends back to the simulator an end pulsing time message.

Getting back to the method execution simulation, when the simulator receives the request and compute the cost/quality/duration of the method in using its objective view of this method. So the distribution used may differ from the one used by the agent to schedule. Especially the resources load may affect widely the distribution of the method. After getting values for cost/duration/quality the execution is added in the event queue where the current quality and cost are displayed. The time left before completion is also shown. These values are not definitive, any event may modifying theses values (especially resources overload). The grab 4 shows the event queue of the Warren example at time 27.


Grab 4: Event Queue showing the execution of four methods for the Warren example.

Now your simulation is running... We did our job, let your agents do their !

How to configure ?

The simulator configuration mechanism is straigh forward, we only define one file, called simulator.cfg. Here the Warren example simulator.cfg (every line starting with a comma is comment):

; Random number generator seed, use the keyword TIME to have a random seed
; (generated from the system clock)
; to set the SEED use this : RANDOM SEED: 889210829049
; to unset it and used a time-based setting
RANDOM SEED: TIME
; Log file name and logging level, default is System.err
; The logging level is 1 for minimum and 3 maximum.
; LOGFILE: stream/filename [FLUSH] LEVEL level
; FLUSH is optional and when set means that the simulator will flush
; the log buffer at each new message. This option is useful in debugging mode
; but consumes a lot of time.
; To redeviate the log in a file called run.log with a level 2, put this:
; LOGFILE: run.log LEVEL 2
; To use the standart error, write this:
LOGFILE: System.err LEVEL 1

; Timeout to decide to boot an agent from the simulation
; in milliseconds.........
; Optional : by defaut 5 minutes (300000ms).
TIMEOUT: 30000

; The time at which the sim will stop running
; In this case, the simulation run for 100 clicks only
STOPTIME: 100

; Wait for keyword is an extension (valid since MASS 1.11) that
; force the simulator to wait for a number of agent to connect to
; before automaticly starting.
; In this case, the simulator waits for 2 agents to connect before
; starting.
WAITFOR: 2

; Resources definition
; RESOURCE: NAME minimum maximum start_value unit
RESOURCE: CPU 0 100 0 percent
RESOURCE: Network 0 10 0 M/s

; You could also define CONSUMABLE resources
; like Hot Water Tank
CONSUMABLE: Water 0 100 100 gal.

; Resource scripts file
RESOURCESCRIPT: example.script

; Server port number
; The default is 25000
PORT: 25000

; Environmental background
; This is the GIF file used as the background in the global environment
; window. You must have a background !
BACKGROUND: http://mas.cs.umass.edu/research/mass/graphics/warren/background.JPG

How to script ?

The scripting mechanism is built inside the simulator to create expected or unexpected event. The basic mechanism we provide allow you to change the resources characteristics during the run. This could be used, for instance, to simulate a leak in the water tank, by decreasing the current volume of water over a period of time. It could also be used to simulate an upgrade of the water heater tank, so that increase its capacity.

This file to use is define in the configuration file by these field:
; Resource scripts
RESOURCESCRIPT: example.script

Here what you can define in this file:
; Example resource script file
;
; Supported commands:
;
; REFRESH time
; time (int) - the clock time to refresh at
; Sets the cycle time. Every "time" pulses the resource script
; will be run again.
;
; SET start duration resource current min max
; start (int) - the start time of the event
; duration (int) - the duration of the event
; resource (str) - the name of the affected resource

; current (int) - the new current value of the resource
; min (int) - the new max value of the resource
; max (int) - the new max value of the resource
; Sets a given resource's quantitative (current, min, max) values.
; If you don't want to adjust one of these three values, enter
; NO_CHANGE instead of a numeric value.
;
; ADJUST start duration resource current min max
; - params same as for SET
; Adjusts a given resource's quantitative (current, min, max) values.
; For instace, a "current" value of -3 would mean that the resource's
; current value would be decremented by 3 during each time slice
; the event is active.

; This will simulate a leak in the Water Tank of 0.1 gallon per click
ADJUST 1 1000 HotWater -0.1 NO_CHANGE NO_CHANGE

; If you want to simulate an upgrade of the tank at time 2000
SET 2000 1 HotWater NO_CHANGE NO_CHANGE 400.0

How to talk to the simulator ?

The connection mechanism is in seven steps:
Regis Vincent
Last modified: Sat Feb 27 18:36:09