source: proiecte/ptvs/docs/Readme.txt @ 31

Setting the environment
=======================

To build and run the application you will need at least JDK 1.5 and apache ant.

The simulator GUI makes use of the OpenGl library

Windows installation instructions:

Copy "jogl.dll" and "jogl_cg.dll" into the "\bin" directory for the Java SDK 
or JRE installed on your machine (i.e. C:\[jre_location]\bin\jogl.dll).

Copy "jogl.jar" into the "\lib\ext" directory for the Java SDK or JRE installed 
on your machine (i.e. C:\[jre_location]\lib\ext\jogl.jar


Configuring the simulator
=========================

After you launch the simulator (see below), you will see 4 lists.

The TIGER files are "rt1" and "rt2" files. The first list only shows the "rt1" files, which should be
placed under the "maps/rt" directory. From the RT files, we build, as you know, a "Map" object, which
we then serialize in a ".map" file. Map files are kept under the "maps/map" directory. We chose
to keep them in a binary, serialized form, in order to avoid computing them every time. The ".map" files
can be seen in the second list. In order to recompute a map from the "rt" files, you can use the 
"Create compiled map" button, which will take the selected "rt1" file and its coresponding "rt2" file, 
compute the map, and save
it in the "maps/map" directory. During the map computation phase, the program will look for an
".rtx.txt" file under the "maps/rt" directory, with the same name as the ".rt1" file. This ".rtx.txt" file
contains some additional information about the map, like number of lanes for some roads, or "one-way" 
information about some roads. The format of the ".rtx.txt" file is text, and, in order to use it, 
road id's must be known (id's as they result from the constructed map, not as they are given in the TIGER files). 
There is no way of knowing these
id's before you actually construct the map. Anyway, if there is no ".rtx.txt" file, there is no problem,
no extra information will be added. The number of lanes will be set randomly. Also randomly (but with some
rules in mind), traffic control systems will be set (priority/yield signs, traffic lights)

Having the maps, the next part is to configure traffic scenarios. In order to do this, there are
".smf" files, which contain basic, empty scenarios for a given map. They just specify entry points, exit points and
routes between the entries and the exits of a map.
A full scenario will also add customized flows of vehicles between the entries and the exits, and using
the routes specified in the ".smf" empty scenario.

The empty scenarios are constructed by using the ".map" objects, and information in the route files,
found under "/maps/routefiles". These specify, in a text format, entries, exits and routes. The road
id's and point id's which must be used in the route files are again those which result from the compiled map.
In order to create the empty scenarios, use the "Create empty scenarios" button.

In order to create full scenarios (that is, to add flows of vehicles to the empty scenarios), use the
"Scenario designer". This one will take an empty scenario as an input and let you configure the flows
of vehicles through a GUI. The result will be a full scenario (".fsc"). These ones can be seen in
the last list of the "MapLoader" GUI. In order to actually simulate a full scenario, use the
"Simulate scenario" button. Furthermore, the flows specified in a full scenario can be configured to
vary during the simulation. This can be done through the "variations" files, under "maps/variations".

By the way, all these text files we have used (rtx, route files, variations) obey the same basic rules:
white spaces and letters are ignored, the only information which will be parsed are the numbers. The
letters are only used as "comments".

When a simulation is started, you will be able to configure several parameters, through a GUI. Among these,
there are 3 radio buttons specifying how vehicles should choose their routes. Routes can be predefined (as
they result from the scenario designer), or they can alter dynamically, as vehicles constantly try to find
the best route to their destination (This was Raluca's graduation project, you can find more details in
her graduation thesis).

For the injection of queries, we have not developped a GUI. Currently, the only supported query is the
one asking for vehicles' speeds. In order to inject such a query on a node, you can use the 
vitp.predefinedqueries.PredefinedQueries class, which has a static member called "queries". In this
collection queries can be placed, along with the time moment when they must be injected, and with the
node on which they must be injected. This node can either be specified by its id (use the QueryById
class), or by its location (use the QueryByLocation class).

Quick launch:
============

        - ant in the base directory

        - select a scenario (4th list) and click Simulate Scenario
                        - Apaca.fsc or Ciurel.fsc - isolated intersections that show how adaptive traffic lights work
                        - also see Turnpike and Manhattan scenarios

        - configure the simulation parameters (or leave them as default)

                        - you can test either with fixed or adaptive traffic lights (especially on the first two scenarios)
                        - For the moment leave routing type as default (as we had some problems integrating Raluca's dynamic 
                        routing) but we will fix that in a few days
                        - dissemination model: 
                                        - Neighbor Discovery - cars send only local info
                                        - Complete Forwarding - cars forward as many cars as they can for the current road
                                        - Probabilistic Forwarding (DEFAULT) - optimization of the previous with only a few cars 
                                                                                        that send the full database and the others either send
                                                                                        local info or don't send anything if they are stopped  
                                        (details in my (Victor) thesis)

        


During the simulation:
======================

        - Control the simulation with Run (starts the simulation), Pause, Step (second by second)

        - On the panel on right it is displayed:
                        - simulation time 
                        - real time of simulation 
                        - number of events (Send, Receive, GPS, Cleanup)
                        - number of cars on the map

        - On the bottom-right side of the screen:
                        - Control delay (delay caused by traffic lights)
                        - fuel consumed and gas emissions

        - To Select a car - click it until you see it changing its color to light blue (challenging because of problems of transforming 
                        3D coordinates, so be perseverent - try when the simulation is paused)

                - its neighbors received through TrafficView are marked on the map with a pink circle

                - you can switch to DRIVER MODE (button) or "near view" for the selected car, just like in TrafficView

                - on the panel on right are displayed:
                                - current speed
                                - Current phase and phase time remaining for the next traffic light as it is published by 
                                the traffic light
                                - Speed recommendation for optimum delay and fuel consumed (with problems, working on it)

        - To select a traffic light click in the middle of the intersection untill it is displayed on the panel 
        "Selection: Traffic Light"
                
                - The approaching cars received through TrafficView either from cars or other taffic lights are displayed 
                with pink circles

                - on the panel on right:
                                - current signal plan
                                - demands and volumes computed for all approaches

        - GUI OFF and COM OFF disable the GUI updates (of vehicles) and communication betwwen nodes

        - Trace Car button - colors the selected car differently from the other even after another car is selected

        - Show Route - marks the route of the selected car with a red line

        - Switch view buton
                - Acceleration view - colors the cars depending on their acceleration (green, yellow, red)
                - "Dissemination Model" View - colors differently the cars that send only local info (white), 
                                                full cars database (blue) or do not send anything (light blue)
                                                (see the Probabilistic Forwarding Model in my thesis (Victor) )