tsim

tsim is a simple train simulator written by Magnus Carlsson and Alois Goller and used on the Concurrent Programming course at Chalmers University of Technology. This page describes tsim v0.81-HUT (which contains some modifications for compatibility with more operating systems and to make it more suitable for use at HUT) by Jan Lönnberg used on the Concurrent Programming course at Helsinki University of Technology. tsim simulates trains running on a track that can be edited through a graphical user interface. The trains can be controlled by other programs through TCP or using the Java interface for tsim.

The simulator (tsim-0.8), Java interface (TSim) and the track used for the programming task at HUT (track) and scripts used to start them (*.sh) can be downloaded here, together with example code (trains and track-sensors).

tsim uses X11 for its GUI, so you will need the X11 libraries and include files to compile and run tsim. To compile tsim, run make in the tsim-0.8 directory. This will generate an executable called tsim (or tsim.exe on Windows Cygwin) in that directory. tsim should compile without modification on Linux and Cygwin. You must edit the C compiler flags in the Makefile to compile on Solaris, FreeBSD, Irix or Tru64 Unix. tsim can use an external sound player for sound effects; by default mpg123 is used on Unix and Sound Recorder on Windows. The supplied sound effects are public domain samples converted to MPEG Layer 3 WAVs.

Using tsim

tsim can be started in three different ways (the executable must be in the current directory if the default settings are used; the supplied script tsim.sh passes the additional settings needed to the executable and can be run instead):

• tsim <filename>
  • This starts tsim with the track contained in the specified file. HUT students should modify the supplied track.
• tsim <width> <height>
  • This starts tsim with an empty track with the specified size.
• tsim
  • This starts tsim with an empty 20×20 track.

You can also add options to the command line.

tsim is preinstalled in Niksula and HUT-CC (Unix machines only) and can be found in ~jlonnber/tsim (the startup scripts automatically choose the right binary for the machine you are using).

When you start tsim, the following windows appear:

Main tsim window containing the supplied track

tsim tools window

The main tsim window displays the track and the trains. The track consists of segments placed on a square grid. Unsurprisingly, trains travel along tracks and collide if they occupy the same track segment. Similarly, a train derails if it moves into a square that does not contain a track segment connected to the previous track segment. Switches connect a common part of the track to one of two alternative track parts. This means that a train entering a switch from the common part will continue onto either the left or right part depending on the state of the switch. A train entering from the connected left or right part will proceed onto the common part, while a train entering from the unconnected part will derail. The currently connected track part is marked by a small arrow. Stops may also be placed on the track. The train can crash into these.

A train consists of a number (at least one) of units, the first of which is a locomotive. The units are each one square long and travel along the track, occupying two squares partially or one square fully and are directly connected to each other. Thus, a train with three units occupies three or four squares.

The tools window contains tools to edit the track and control the trains. The upper row contains (from left to right) tools to place stations, track segments, sensors (shown as small T-shapes). Clicking the sensor tool and clicking a track segment places a sensor on that segment or removes the existing sensor. Sensors may not be placed on crossings, switches or stops. In the lower row, you will find:

• The train tool, used to place new trains on the track.
• The delete tool. Selecting this deletes the contents of any square you click on.
• The switch tool. Selecting this allows you to toggle switches by clicking them. This is useful for testing.
• The speed tool. Selecting this allows you to change the speed of trains.
• The co-ordinate display. You will need to use this co-ordinates to identify sensors.
• The save button. Click this to save your track (including sensors and trains).
• The quit button. Click this to quit tsim. This will also cause the Java interface to terminate, if it is connected to the simulator.

Configuring tsim

tsim is configured using X resources or command-line options. The following options are supported by tsim:

• bitmapDir
  • The directory tsim uses to find bitmaps. Change this if tsim is not run from the current directory.
  • Default: ./bitmaps
• soundDir
  • The directory tsim uses to find sounds. Change this if tsim is not run from the current directory.
  • Default: ./sounds
• timeoutInterval
  • Time for each time step in tsim (in seconds).
  • Default: 0.1
• acceleration
  • Acceleration in pixels/(second²).
  • Default: 5.0
• playCmd
  • Sound playback command. The name of the sound file to play is specified as %s.
  • Default (Windows): sndrec32 /play /close /embedding "%s"
  • Default (Unix): mpg123 "%s"
  • Set this to - to disable sound (very useful in university computer labs; default in Niksula and HUT-CC!).
• speedupFactor
  • Ratio between simulation time and wall time (a "second" in this document is always simulation time). Setting this too high (more than 20 or so, depending on the system) is likely to decrease the time trains have to react to sensors too low for reliable travel.
  • Default: 1.0
• timeout
  • Time allowed for a train to travel from one station to another in seconds. Only enforced in strict mode.
  • Default: 120.0
• strict
  • Enforce timeouts and abort simulation on fatal errors (timeouts, collisions, derailment, stop collisions).
  • Default: no
• log
  • Output all commands, responses and events to stderr.
  • Default: no
• foreground
  • Foreground colour.
  • Default: black
• background
  • Background colour.
  • Default: white

Options can be specified in two ways:

• As X resources, which are typically loaded from ~/.Xresources. They can also be set using xrdb -merge. The format used in both cases is: tsim* <option>:<value>
• As command line options, of the form -<option> for Boolean options and -<option> <value> for other options.

For example, to direct sound output through aRts (which is very useful when using KDE), run xrdb -merge and enter the following:

tsim*playCmd:artsdsp mpg123 \"%s\" &> /dev/null

or add -playCmd 'artsdsp mpg123 "%s" &> /dev/null' to the tsim command line.

tsim Java interface

The tsim Java interface allows you to control the simulator easily using Java programs. The Java interface package includes a description of the interface (in TSim/doc). The Java interface is typically used together with the supplied startup script run.sh (run-cygwin.sh in Cygwin), which starts the simulation with two trains using the control code in trains/Train.class (i.e. the current directory and the interface is in the Java class path). The variant scripts run-log.sh and run-cygwin-log.sh activate logging in both the simulator and Java interface.

Starting run.sh as shown above results in three processes running as follows:

Structure of tsim runtime configuration

This configuration is used for concurrent programming exercises. In this configuration, run.sh starts tsim and two Java virtual machines running the student's train controller code and the tsim Java interface, and connects tsim and the JVM with each other through TCP. Standard output and error (System.out and System.err) can be used for debugging.

Each virtual machine runs a single train in a single thread (the Java interface uses an additional thread for I/O). Each train is identified by an id number, which is an increasing integer starting from 1. For example, if there are two trains, their ids will be 1 and 2.

The functionality of the tsim Java interface is accessed by the student's code through the TSim.TSimInterface class. An instance of this class is passed to the Train constructor.

The TSimInterface has five primary methods through which the trains are controlled:

• public void setSpeed(int speed)
  • This method sets the speed of the train to speed. The speed is measured in pixels/second.
• public void setSwitch(int xPos, int yPos, int switchPos)
  • This method sets the state of the switch at (xPos, yPos) to switchPos. switchPos can be either TSimInterface.SWITCH_LEFT or TSimInterface.SWITCH_RIGHT.
• public void loadUnload()
  • This method unloads and loads passengers and goods. This method must be called each time the train has arrived at a station.
• public SensorEvent getSensor()
  • This method waits until a sensor event is received by the train and returns the sensor event. Sensor events are generated when the train enters (starts occupying a square at least partially) or exits a square (ceases to overlap the square at all) containing a sensor. Sensor events can be examined through the following SensorEvent methods:
    • public int getXpos()
      • This method returns the X position of the sensor.
    • public int getYpos()
      • This method returns the Y position of the sensor.
    • public int getStatus()
      • This method returns the status of the sensor: SensorEvent.ACTIVE if the train has entered the sensor's square and SensorEvent.INACTIVE if the train has left the sensor's square.
• public Semaphore getSemaphore(int s)
  • tsim provides Semaphores for interprocess communication. The nth call to this method by a process returns the nth semaphore (n starts from 0). If the process is the first to get this semaphore, it is initialised to s; otherwise, the existing semaphore is returned unchanged. The semaphore supports the following (atomic) operations:
    • public void acquire()
      • P operation: wait until value is greater than 0 and decrement by 1.
    • public void release()
      • V operation: increment value by 1.
    • public boolean tryAcquire()
      • If value is greater than 0, decrement and return true, else return false.

For further details, see TSim/doc/index.html in the tsim package.

Page last updated by Jan Lönnberg 2007-10-02.