FreeSim 1.0/1.1 Instructions

NOTE: FreeSim 2.0 instructions are included in the download.

3rd Party Applications
  • JRE version 1.5 or higher, which can be obtained from http://java.sun.com, is required for running the FreeSim server application.
  • JDK version 1.5 or higher (which includes the JRE version 1.5 or higher), which can be obtained from http://java.sun.com, is required for compiling the FreeSim server application. Make sure to add the bin directory of the JDK directory to the PATH environment variable after completing the download.
  • MySQL version 4.1.12 or higher, which can be obtained from http://dev.mysql.com/downloads, is required for running the FreeSim server application.
  • A web server is required for accessing the FreeSim GUI. Any web server will work, although I recommend Apache's HTTP Server version 2.2.4, which can be obtained from http://httpd.apache.org, or Apache's Tomcat Application Server version 5.5.20, which can be obtained from http://tomcat.apache.org.
  • Adobe Flash 8 or greater, which can be obtained from http://www.adobe.com, is required for modifying the FreeSim GUI.
  • Eclipse 3.2 or greater, which can be obtained from http://www.eclipse.org, can be used quite easily to modify any of the Java components of FreeSim. The Eclipse project files for FreeSim are all included with the FreeSim source download.
  • Perl is required for running the Flash Socket Policy application, which is required for Flash version 9 and greater clients that connect using a socket to a server application (which is the case with the FreeSim Flash GUI connecting to the FreeSim server application. In Linux, I have tested the Flash Socket Policy application with v5.10.0 built for i386-linux-thread-multi (which came standard with Fedora Core 12). In Windows, I have tested the Flash Socket Policy application with ActivePerl 5.10.0 Build 1004.


Steps to Compile the FreeSim Source
  1. Download the FreeSim source zip file (freesim-src.zip) from the download page.
  2. Unzip freesim-src.zip, ensuring to keep the directory structure. For the rest of these steps, $FREESIM_HOME will be used to represent the freesim directory inside of the directory into which you unzipped the FreeSim source zip file.
  3. From the $FREESIM_HOME/freesim/ directory, run the compileFreeSim.bat file, which will create a bin directory with all of the compiled .java files.
  4. From the $FREESIM_HOME/freesim/ directory, run the jarFreeSim.bat file, which will create the freesim.jar file.
  5. Skip to step 3 of executing the FreeSim binaries to run FreeSim.


Steps to Execute the FreeSim Binaries
  1. Download the FreeSim binary zip file (freesim-bin.zip) from the download page.
  2. Unzip freesim-bin.zip, ensuring to keep the directory structure. For the rest of these steps, $FREESIM_HOME will be used to represent the freesim directory inside of the directory into which you unzipped the FreeSim binary zip file.
  3. In the $FREESIM_HOME/freesim/ directory, modify the freesimdbconfig.txt file to use a username and password that has access to the database on the computer specified by hostname.
  4. In the $FREESIM_HOME/freesim/ directory, execute the freesimdbcreate.sql file on the MySQL database specified in the freesimdbconfig.txt file from the previous step, as follows:

        mysql -u username -p < freesimdbcreate.sql

    NOTE: This step will drop and create a database named freesimdb.
  5. From the $FREESIM_HOME/freesim/ directory, run the runFreeSimFileReaders.bat file, which will populate the database with all of the data from the losangeles_nodelist.txt, losangeles_nodedistances.txt, losangeles_freewayimages.txt, losangeles_vehicleloaderfiles.txt files, since those are the files specified in the freesimconfig-<area>.txt file by default.
  6. From the $FREESIM_HOME/freesim/ directory, run the runFreeSim.bat file, which will start the FreeSim server application, listening on ports 7892 and 7893 since those are the default ports as defined in the freesimconfig-<area>.txt file.
  7. From the $FREESIM_HOME/flashsocketpolicy/ directory on the command line, run perl flashpolicyd.pl --file=flashpolicy.xml. This will run the Flash Socket Policy application on port 843, which will allow Flash version 9 and greater clients to access the FreeSim server using sockets.
  8. Copy the $FREESIM_HOME/freesim-gui/ directory to the root web application directory of your web server.
  9. Open a browser and go to http://localhost/freesim-gui/freesim.html. If your web/application server is not listening on port 80, then append the port at the end of localhost. For example, with the default Tomcat configuration, go to http://localhost:8080/freesim-gui/freesim.html.


Steps to Modify the FreeSim Source in Eclipse
  1. After installing the JDK and Eclipse, execute Eclipse.
  2. Select $FREESIM_HOME as the "Workspace".
  3. Click freesim in the Package Explorer, go to the "Project" menu, and click "Properties".
  4. Click "Java Build Path" on the left, then the "Libraries" tab on top.
  5. Select the mysql-connector-java-3.1.10-bin.jar file and click the "Edit" button.
  6. Navigate to the $FREESIM_HOME/freesim/ directory, and select the mysql-connector-java-3.1.10-bin.jar file.
  7. Select the JRE System Library [jre1.5.0_10] file if it says (unbound) next to it. Click the "Edit" button. (NOTE: If (unbound) is not displayed next to the JRE, then skip to step 9.)
  8. Select the "Workspace default JRE" and click the "Finish" button.
  9. Click the "OK" button to exit the Project Properties.
  10. The code is in the packages within the Package Explorer. Any code you modify will automatically be compiled by Eclipse.


Steps to Execute FreeSim within Eclipse
  1. Before executing FreeSim within Eclipse, make sure that you have followed the steps in the "Steps to Execute the FreeSim Binaries" section above, but runFreeSim.bat should NOT be running.
  2. Ensure that the parameters in $FREESIM_HOME/freesimconfig-<area>.txt and $FREESIM_HOME/freesimdbconfig.txt are correct for your configuration,
  3. Inside the FreeSim project in Eclipse, go to the "Run" menu and click "Open Run Dialog..."
  4. Click "Java Application" on the left, then the "New launch configuration" button at the top.
  5. Type FreeSim Server Application as the "Name" at the top.
  6. On the "Main" tab, type freesim as the "Project" and trafficsimulator.TrafficSimulator as the "Main class".
  7. On the "Arguments" tab, type freesimconfig-<area>.txt as the "Program arguments" and -Xms1024m -Xmx1024m as the "VM arguments".
  8. Click the "Run" button. If everything is configured properly, you will see a line at the bottom of the output that says "Ready for vehicle connections".
  9. Open a browser and go to http://localhost/freesim-gui/freesim.html. If your web/application server is not listening on port 80, then append the port at the end of localhost. For example, with the default Tomcat configuration, go to http://localhost:8080/freesim-gui/freesim.html.


Steps to Create Graphs in FreeSim
  1. REQUIRED: Create a node list file (i.e. $FREESIM_HOME/freesim/northwest_nodelist.txt). This file will determine where all of the nodes are placed in the FreeSim GUI. The nodes are placed between (0,0) in the top left corner to (600, 600) in the bottom right corner. The first line of the file has the following format:

    <Freeway System Long Name>,<Freeway System Short Name>

    Every subsequent line represents a node and has the following format:

    <Node Name>,<Postmile (-1 if doesn't exist)>,<Freeway Name That Contains Node>,<x location>,<y location>

  2. REQUIRED: Create a node distances file (i.e. $FREESIM_HOME/freesim/northwest_nodedistances.txt). This file will determine what nodes will have edges connecting them, and the distance between the nodes. Note that the distance between the nodes does not have to correspond to the physical locations of the nodes in the FreeSim GUI. Each line represents an edge and has the following format:

    <Source Node Name>,<Freeway Name That Contains Source Node>,<Destination Node Name>,<Freeway Name That Contains Desination Node>,<Distance>,<Optional Description of Edge>

  3. OPTIONAL: If you would like to display images in the FreeSim GUI, create an images file (i.e. $FREESIM_HOME/freesim/northwest_freewayimages.txt). This file will determine where all of the images are placed in the FreeSim GUI. The images are placed between (0,0) in the top left corner to (600, 600) in the bottom right corner. The first line of the file has the following format:

    <Freeway System Long Name>

    Every subsequent line represents an image and has the following format:

    <Location of Image>,<x location>,<y location>

  4. OPTIONAL: If you would like to have batch files for simulating multiple events simultaneously (such as multiple vehicles entering the freeway system simultaneously, determing the fastest path from one location to another at set times, etc.), create a vehicle loader list file (i.e. $FREESIM_HOME/freesim/losangeles_vehicleloaderfiles.txt). This file will list all of the files that contain batch commands. For those commands, see the section on "Creating Vehicle Loader Files". Vehicle loader files go into a directory $FREESIM_HOME/freesim/$VEHICLE_COMMAND_FILES_PREFIX/<Freeway System Long Name with Underscores>/<Vehicle Command Filename>. The value of $VEHICLE_COMMAND_FILES_PREFIX is configurable in the $FREESIM_HOME/freesim/freesimconfig-<area>.txt file as the vehiclecommandfilesprefix parameter, where that value is relative to the $FREESIM_HOME/freesim/ directory. The first line of the file has the following format:

    <Freeway System Long Name>

    Every subsequent line represents a vehicle loader file and has the following format:

    <Vehicle Loader Filename to Display in FreeSim GUI>,<Vehicle Loader Filename>

  5. Modify the following parameters in the $FREESIM_HOME/freesim/freesimconfig-<area>.txt file:
    • freewaysystem - Set this parameter to the long name of the freeway system, as set in the node list, images, and vehicle load list files.
    • freewaysystemshortname - Set this parameter to the short name of the freeway system, as set in the node list file.
    • nodelocationfilename - Set this parameter to the location of the node list file, relative to the $FREESIM_HOME/freesim/ directory.
    • edgedistancesfilename - Set this parameter to the location of the edge distances file, relative to the $FREESIM_HOME/freesim/ directory.
    • imagesforfreewaysystemfilename - Set this parameter to the location of the images file, relative to the $FREESIM_HOME/freesim/ directory.
    • vehicleloaderfilesfilename - Set this parameter to the location of the vehicle loader list file, relative to the $FREESIM_HOME/freesim/ directory.
    • Set the dbconfigfile, generateallpaths, generateallpathswithinmultiplier, multiplier, and strprefix parameters to the desired values.
  6. Run runFreeSimFileReaders.bat from the $FREESIM_HOME/freesim/ directory. This will populate the database with your graph and add it into FreeSim's GUI. Also, this may have generated all paths and all paths within a multiplier based on your settings of those parameters from the previous step.
  7. Open a browser and go to the freesim.html page. Your freeway system will appear in the "Freeway System" drop-down box in the top right corner of the GUI. Once you select it from the drop-down and click the "Load Freeway System" button, your graph will appear in the large space in the middle. The nodes will appear in the drop down boxes beneath the "Freeway System" to be used to find fastest and shortest paths. The edges can be updated in the box below that with the button "Update Speed". And the vehicle command files list will appear at the bottom in the box labeled "File". When a vehicle command file is selected and the "Load File" button is clicked, your vehicle command file will appear in the text area below that. Click the "Execute File" button to start the execution.


Steps to Create Vehicle Loader Files
  1. A vehicle loader file (i.e. $FREESIM_HOME/freesim/vehiclecommand.txt) is a batch file that allows multiple events to occur simultaneously within FreeSim. This file must be referred to by a vehicle loader list file as described in step 4 of the section on "Steps to Create Graphs in FreeSim". There is an internal timer to FreeSim that operates based on the milliseconds and timetonotifydelta parameters in the $FREESIM_HOME/freesim/freesimconfig.txt-<area> file. The milliseconds parameter tells FreeSim how often to notify vehicle listeners, and the timetonotifydelta tells FreeSim with what values it should notify the vehicle listeners. For example, if milliseconds=3000 and timetonotifydelta=10, then FreeSim will notify the vehicle listeners every 3 seconds with values 10, 20, 30, 40, ... Vehicle listeners can be created by implementing the vehicle.VehicleListener interface, and then registering this class with the vehicle.VehicleNotifier class through the registerVehicle(VehicleListener) method. The first line of the file has the following format:

    <Freeway System Long Name>

    Every subsequent line represents an event. Here are the possible events:
    • Vehicle Instantiation
      70|<Vehicle ID>|<Time to Instantiate Vehicle>|<Source Node Name>|<Source Freeway Name>|<Destination Node Name>|<Destination Freeway Name>
    • Edge Update by Vehicle
      72|<Vehicle ID>|<Time to Execute Edge Update>|<Source Node Name>|<Source Freeway Name>|<Destination Node Name>|<Destination Freeway Name>|<Updated Speed>
    • Get Updated Fastest Path for Vehicle
      73|<Vehicle ID>|<Time to Execute Fastest Path Update>
    • Get Current Location for Vehicle
      71|<Vehicle ID>|<Time to Get Current Location of Vehicle>
    • Get the Time to Traverse the Path
      76|<Vehicle ID>|<Time to Get the Time to Traverse the Path>|<Source Node Name>|<Source Freeway name>|<Next Node Name>|<Next Node Freeway Name>|...|<Destination Node Name>|<Destination Freeway Name>
    • Comment
      Any line that starts with a # is a comment and can contain anything. The entire line will be ignored by FreeSim.



Steps to Generate All-Pairs All-Paths
  1. Open $FREESIM_HOME/freesim/freesimconfig-<area>.txt.
  2. Check to ensure the following parameters are correct for your freeway system: freewaysystem, freewaysystemshortname, nodelocationfilename, and edgedistancesfilename.
  3. Set the generateallpaths parameter to true.
  4. Modify the strprefix parameter to be the directory into which you want the files containing all the paths between all the pairs of points written. NOTE: In the directory specified by the strprefix parameter, there will be a directory named based on the freewaysystem parameter. Within that directory, there will be a directory named all, which will contain a file for each pair of points that contains all of the paths between that pair. The naming convention is paths_<srcnode>-<destnode>.txt. NOTE: Make sure that you manually create the directories before executing step 5.
  5. Run runFreeSimFileReader.bat from the $FREESIM_HOME/freesim/ directory. This will populate the database with the graph then generate all paths for all pairs of nodes in that graph. NOTE: THIS WILL TAKE A VERY LONG TIME BASED ON THE SIZE OF YOUR GRAPH. It will complete, and you will see the status as the output, but it took a 2.8GHz dedicated server with 1GB RAM over 14 days to complete for the Los Angeles freeway system provided.


Steps to Generate All-Pairs All-Paths Within a Multiplier
  1. Open $FREESIM_HOME/freesim/freesimconfig-<area>.txt.
  2. Check to ensure the following parameters are correct for your freeway system: freewaysystem, freewaysystemshortname, nodelocationfilename, and edgedistancesfilename.
  3. Make sure you have already generated all paths for all points for this freeway system, as specified in the "Steps to Generate All Pairs All Paths" section.
  4. Set the generateallpaths parameter to false, the generateallpathswithinmultiplier parameter to true, and the multiplier parameter to whatever floating point multiplier you would like. If the multiplier is set to 1.5, then you will generate files that only contain paths that are within 1.5 times the length of the shortest path. This will greatly improve the running time of your algorithms, though this parameter may eliminate the fastest path based on the weights of the edges.
  5. Modify the strprefix parameter to be the directory into which you want the files containing all the paths between all the pairs of points written. NOTE: In the directory specified by the strprefix parameter, there will be a directory named based on the freewaysystem parameter. Within that directory, there will be a directory named within<multiplier>, which will contain a file for each pair of points that contains all of the paths between that pair. The naming convention is paths_<srcnode>-<destnode>.txt. NOTE: Make sure that you manually create the directories before executing step 6.
  6. Run runFreeSimFileReader.bat from the $FREESIM_HOME/freesim/ directory. This will populate the database with the graph then generate all paths for all pairs of nodes in that graph. NOTE: THIS WILL TAKE A VERY LONG TIME BASED ON THE SIZE OF YOUR GRAPH. It will complete, and you will see the status as the output, but it took a 2.8GHz dedicated server with 1GB RAM over 14 days to complete for the Los Angeles freeway system provided.
  7. FreeSim will automatically use the paths within a multiplier in its algorithms, so if you want to use all of the paths, change the multiplier to 1.0. This should only be done for small graphs since the number of paths between any two nodes in a large graph is significantly large. In the 53-node graph of the Los Angeles freeway system, there are over 1.5 million paths between some pairs of nodes.


Steps to Create Fastest Path Algorithms
  1. Create a class in the fastestpathalgorithms package that extends the abstract class fastestpathalgorithms.FastestPathAlgorithm.
  2. Override the public abstract Path getFastestPath(Node nodeSrc, Node nodeDest) and public abstract void updateEdgeWeight(Edge edge, int ispeed) methods. Note that you have access to the Graph data structure in your class since you inherited it from the FastestPathAlgorithm class.
  3. Modify the utilities.MessageTypes class to include a new public static final int variable with a unique integer for your new algorithm, similar to public static final int _APAP_PRECOMPUTED_CONSTANT_QUERY = 18;.
  4. Modify the utilities.MessageTypes class to include the new variable you created in step 3 in the _HT_ALGORITHM_NAME and _HT_SHORTENED_ALGORITHM_NAME hash tables. These hash tables map an integer value to a String value.
  5. Modify the trafficsimulator.TrafficSimulator class to include a hash table member variable that corresponds to your new algorithm, similar to private Hashtable fastestPathAPAPPCU = new Hashtable(); The reason for the hash table is so that the same algorithm can be used on multiple graphs, since FreeSim supports multiple freeway systems simultaneously. The String in the hash table represents the name of the freeway system.
  6. Modify the trafficsimulator.TrafficSimulator class to instantiate your new algorithm class in the private void simulate() method, and put the instantiated variable in the hash table you created in the previous step, similar to this.fastestPathAPAPPCU.put(freewaySystemName, new APAPPrecomputedConstantUpdate(graph));
  7. Modify the trafficsimulator.TrafficSimulator class to include an accessor member method for your new algorithm that takes a freeway system name and returns an instance of your new algorithm class that includes the graph for that freeway system, similar to:
    public APAPPrecomputedConstantUpdate getFastestPathAPAPPCU(String freewaySystemName) {
    return fastestPathAPAPPCU.get(freewaySystemName);
    }
  8. Modify the trafficsimulator.UpdateSpeedThread class to include a line in the public void run() method for calling the updateSpeedInAlgorithm method for your algorithm, similar to updateSpeedInAlgorithm(trafficSimulator.getFastestPathAPAPPCU(freewaySystemName), edge, ispeed, MessageTypes._HT_ALGORITHM_NAME.get(MessageTypes._APAP)PRECOMPUTED_CONSTANT_UPDATE)); That will force the updateEdgeWeight method in your new algorithm class to be called whenever an edge update is made.
  9. Modify the trafficsimulator.VehicleThread class to include a case in the private Path getFastestPath(String freewaySystemName, Node nodeSrc, Node nodeDest, int ialgorithmToUse) method for your new algorithm, similar to:
    case MessageTypes._APAP_PRECOMPUTED_CONSTANT_UPDATE:
    fastestPath = trafficSimulator.getFastestPathAPAPPCU(freewaySystemName);
    break;

     This method will call the getFastestPath method in your new algorithm class whenever a fastest path is requested from the FreeSim GUI using your algorithm. Note that it will print out the amoutn of time that it takes to compute the fastest path regardless of the algorithm, so that it is easier to compare actual efficiencies of fastest path algorithms.
  10. Recompile the FreeSim source then restart the FreeSim server application. If you're running it from the .bat files provided, make sure to re-jar FreeSim before running it.
  11. Open a browser and go to the freesim.html page. Select a freeway system, then select your algorithm from the "Fastest Path Algorithm" drop-down box. Select a start node from the "Start" box above the algorithm, and a destination node from the "End" box above the algorithm, then click the "Fastest Path" button. Some information about the path will appear in the "Messages" box under the algorithm, and the path will appear in red on the graph. The shortest path will always use Bellman-Ford's algorithm, regardless of the algorithm selected in the "Fastest Path Algorithm" drop-down box.