18-649 Simulator Overview

Last modified May 9, 2010
What we provide:

All of the basic simulation infrastructure is provided for you. Specifically, we provide the discrete-time simulation tools, the constructs needed to communicate with other objects in the simulation, environmental actuators that will respond to your commands and standardized message definitions.

The codebase can be downloaded here

If you unpack the codebase, you will find the following files and directories:

The simulator is composed of 5 main packages.

Detailed descriptions of each package can be found in the javadoc api documentation, which can be built by running 'make' in the root of the simulator release (not the code/ directory).  The object simulator.framework.Elevator is the top-level object that provides command line interface and instantiates all other simulation objects. 

All source code is provided (except for the control modules you will be creating later in the semester).  You should not need to modify the simulation framework code in the normal course of completing your assignments.  It is primarily to help you understand how the simulated elevator works (and to help with debugging).  If you wish to modify the framework to make your life easier, you can do so, but be careful not to break anything!  Keep in mind that you will only submit your controller code, so any modifications you make to your local copy of the framework will not be present when we run tests on your project submissions.

If you come up with useful a useful modification to the framework (for example, a modification that makes testing easier), you may submit the code to TAs for eventual inclusion in the official codebase.  Decisions on whether to include your modification (or when to release the new version) will be at the sole discretion of the course staff, and you will still be responsible for making sure the code and test files submitted for each project work with the current official release.

Please see the Example section of this document for more details and an example on how everything fits together.

Running the simulator:

In order to run the simulation, first make sure that you are running an appropriate version of Java on an appropriate machine. We recommend using the ece cluster (ece000.ece.cmu.edu) or the color machines. Accounts should be created for every enrolled student by the end of the third week of class.

Please note that, per department policy,  you may not run simulations on the head machines of each cluster:  asl (games/linux cluster), vonneumann(deadmathematicians), ece000 (ece cluster) and black (color cluster)

To connect to the ece cluster, ssh to ece000.ece.cmu.edu.  You will get a list of the other machines in the cluster when you log in.  Note that some of these machines have an IP on the local cmu network (e.g. ece009.campus.ece.cmu.local), so they are not reachable from off-campus.  If you are off-campus, you must first ssh to a publicly accessibly machine (e.g. one of the color cluster machines or ece000.ece.cmu.edu through ece008.ece.cmu.edu).

To ssh from a windows machine, you should use Putty or another terminal program.  You should also run a Windows X client, as described in the Project FAQ.

For more information on accessing the clusters from on and off campus please see the ece wiki located here

For your benefit and the benefit of others, please spread the load around on various machines. You can use the 'top' command to see what other programs are running on each machine. A complete list of the machines in the cluster is shown when you first log in.

The required version of java is whatever is being run on the cluster.  You can check what version of Java is installed by typing: 

java -version
Once you have downloaded the code to your home directory, you can extract it using this command (change the filenames as appropriate):

tar -xzvf .tar.gz

NOTE: This code will be the framework used for all future projects. We recommend that you keep a copy of the code from each project before modifying it for the next project.

Compiling:

The makefile provided will compile all java files. You can execute it by running

  make

from the 'code' directory.

To execute the java compiler directly, use:

javac filename.java

You will need to recompile each file after you modify it.  Running "make" does this automatically.

Note:  you may get an error if any of the folders in your current path have spaces in the name.

Note 2:  Because we include only the .class files (not the .java source files) for the controllers in the simulator.elevatorcontrol package, if you run 'make clean' (which should be unnecessary), it will delete these class files, but fail to recreate them since the source files are missing.  You will need to restore them from the simulator tarball or another location.  This will cease to be an issue as the semester progresses and you implement your own controllers to replace the ones we have provided.

Running:

You can run the simulator from the code directory by executing:

java simulator.framework.Elevator

If you wish to run the simulator from another directory, then add the "-c /path/to/code" flag to the java command line, or set the CLASSPATH variable using:

export CLASSPATH=`pwd`

(note the backticks used around pwd). If you wish to have your CLASSPATH set every time, you can add the line above to your .bashrc file (assuming you are using the BASH shell).

Command Line Arguments:

Executing the simulator without any arguments (or with incorrect or inconsistent arguments) will list the command line parameters. We recommend that you read the entire list carefully. The simulator has many useful features.

For acceptance tests, use the '-pf' flag. This automatically instantiates all the elevator objects.

For unit tests (testing a single module), use the '-cf' flag to control which module is instantiated and the '-mf' flag to supply inputs to the message injector. For integration tess (testing a few modules), you will still use the -cf and -mf flags, but your -cf file might contain multiple objects.

Running tests will produce files with the extension .stats that contain statistics regarding the performance of your elevator, including assertions passed and failed for unit and integration tests and detailed information on passenger delivery, monitoring, and network usage for acceptance tests.

Running with the GUI enabled:

If you run the simulator with the -gui option, you must make sure that you have are running an X window manager and that you have X11 forwarding enabled in your ssh client. Also note that running the simulator on an on-campus host while trying to view the GUI from an off-campus host over SSH or X-Win 32 will be very slow. You will get more satisfactory results from the GUI if you run the simulator on a local machine.

For Linux:

For Windows:

Reference Information:

Sun's Java Tutorial

*Please submit all project-related questions to {email} -- thanks!
Back to the codebase