TeD - Telecommunications Description Language
The most recent version of this document is available as http://www.cc.gatech.edu/computing/pads/tedreadme.html
New!
ATM PNNI
Critical Path
Collaboration
IntelPC Port
Solaris2.7 Port
Signals
What's...?
Overview
Background
Installation
Software
Installing
Models
Developing
Compiling
Simulation
Command-line
Graphical
Misc
FAQ
Users
Copyright
Overview
What is GTW? GTW stands for Georgia Tech Time Warp, which is a highly optimized optimistic parallel simulation kernel that has been developed at Georgia Tech by the research group led by Prof. Richard Fujimoto. It incorporates many state-of-the-art optimistic parallel simulation techniques that have been developed over the past decade. The GTW kernel is written in C. GTW++ is a layer over GTW that provides an object-oriented interface to GTW in C++. Both GTW and GTW++ are included in the TeD release software.
See the GTW Programmer's manual and the GTW++ Programmer's manual .
What is TeD? TeD stands for Telecommunications Description Language. It is a language that has been developed mainly for modeling telecommunicating network elements and protocols. Technically, it is an object-oriented language in which the behavior of each object, called entity, is expressed in terms of processes that run within the scope of that object. Objects communicate with each other by exchanging events over pre-declared and pre-mapped channels. C++ code can be embedded into the executable portions of the TeD models. The TeD release software includes a TeD compiler that translates TeD models into C++ code which uses GTW for parallel simulation.
See the TeD Meta language , the TeD/C++ language manual , and TeD tutorial.
What is Jane? Jane is a simulator-independent Client/Server-based graphical interface and scripting tool for interactive parallel simulations. TeD/GTW simulations can be executed using the Jane system. The Jane software includes a server written in C, and a client written in Java.
See an overview of Jane.
Background
TeD started out of a need for a network modeling language that is amenable to parallel simulation and that can be experimented with and enhanced over time. The first draft of the language was proposed by Richard Fujimoto and Kalyan Perumalla in December 1995 at the PI meeting of the Simulation of Integrated Communications Systems (SICS) project. The first version of a TeD compiler was released by the Georgia Tech group in February 1996, and several groups started to independently develop large-scale network models incorporating complex protocols such as TCP/IP, ATM PNNI, multicast and wireless protocols. These groups included David Nicol, BJ Premore and Jason Liu at the Dartmouth College; Don Towsley, Jim Kurose, Dan Rubenstein, and Timur Friedman at the University of Massachusetts; Sandeep Bhatt, Matthew Andrews, Lisa Zhang and Kalyan Perumalla at Bellcore; Andrew Ogielski, Jignesh Panchal, Owen Kelly and others at WINLAB, Rutgers University; and, Richard Fujimoto, Ellen Zegura, Fang Hao and Kalyan Perumalla at Georgia Tech. The model development effort resulted in significant feedback that was used for improving the language along with greatly improving the efficiency of the underlying parallel simulation techniques. The simulation performance results were very promising, as documented in the special issue of the SIGMETRICS Performance Evaluation Review, March 1998. The TeD effort continued into another large-scale simulation project called the Scalable Self-organizing Simulations (S3).
Installation
Obtaining Software | Installing TeD/GTW | Installing JANE

Obtaining Software

To obtain a copy of the TeD/GTW and Jane software, send email to Kalyan Perumalla.

TeD/GTW : The TeD/GTW distribution is in the form of a single compressed tar file named tedx.y.tar.Z, where x.y is the version number, such as 2.2. When uncompressed and extracted, the distribution includes the following:

Module Description Directory Applications Directories
GTW Parallel simulator kernel GTW/SRC/ARCH-GTW PHOLD GTW/APP/*
GTW++ C++ interface to GTW GTW++/SRC PING, PHOLD, HOLDSEQ GTW++/APP/*
GTWTED C++ class library supporting TeD entities and processes TED/GTWTED/SRC N/A N/A
TeD Compiler Translates *.ted, *.the to *.C, *.h TED/COMPILER/SRC PING, MUX, BMUX, DMUX, PCS TED/APP/*
Jane Server Server for Jane clients GTW/SRC/SERVER N/A N/A
Jane Client Java-based graphical interface for executing TeD/GTW simulations JANECLIENT N/A N/A

Jane : The Jane distribution consists of a single Java class library jane-classes.jar and a simple shell script that invokes the default graphical interface of the Jane client that is included with the class library. The script is a C-shell script janeclient.csh for Unix machines, and a batch file janeclient.bat for PCs. All these files are included in the directory JANECLIENT in the TeD software.

Installing TeD/GTW

Type make in the top-level directory of TeD release (the directory that contains the sub-directories GTW, GTW++, etc.). It builds all the modules as mentioned above.

Architecture codes
The TeD/GTW software is designed so that a single copy of the source code can be simultaneously used for multiple architectures. Currently, SGI multiprocessors, Sun Sparcs and Intel i86pcs are supported. We shall use ARCH to denote the architecture code of the node on which the software is installed. Thus, henceforth, ARCH must be interpreted as SPARC if a Sun Sparc is used, SGIMP if an SGI multiprocessor is used, and so on.
Arch code Platform
SGIMP SGI 64-bit multiprocessors running Irix
SPARC Sun SPARCs running Solaris 2.5 or above
INTELSOL Intel PCs running Solaris

Installing JANE

The JANE system consists of server and client components.

Building TeD Models

Developing TeD Models: Refer to the TeD meta-language and TeD language documentation for illustrative examples of TeD models.

Compiling TeD Models: Refer to the TeD language documentation for instructions on compiling TeD models.

Executing Simulations

The simulations can be executed in the following ways:

  1. Command-Line Execution
  2. Execution using the Jane graphical interface.

Command-Line Execution

TeD executables can be run from the command-line of a shell. Refer to the TeD language manual for the details on the command-line parameters for TeD/GTW executables. GTW or TeD executables can be run at the shell command-line in batch mode or interactive mode. The interactive mode is invoked by using the -I command line argument after the endtime argument. A range of commands is available in the interactive mode.

Execution Using Jane

To execute simulations using the Jane system, do the following:

  1. Start the JANE Server.
  2. Start the JANE Client.
  3. Run your Simulation.
  4. Collaborate with Multiple Clients.

Start JANE Server

First the JANE server must be started on the machine which will be used in the simulation. Once started, the server can be left running, and need not be restarted for each client.

  1. Execute the server on the previously selected node as follows: 
    GTW/SRC/SERVER/OBJ/ARCH/tedserver |& tee /tmp/yourname.log &
    where, ARCH is the architecture code of the node, and yourname is replaced by your name (to avoid clash with other users). The output from the server will be captured in yourname.log, so that you can refer to it when necessary.
  2. The server prints out the port number on which it will accept connections from clients. This is the port number that will need to be specified to the client when connecting to the server. The server attempts to make the port number equal to (or close to) the user ID of your account on that node. If you ever forget the port number, it can be found in the first few lines of the log file into which you are capturing the server output.
  3. When you want to kill the server, use the kill command on the process ID of the server.

Start JANE Client

The JANE client can be started on any node on which JAVA is installed, and from which the server can be reached across a network.

  1. On UNIX nodes, run the JANE/CLIENT/janeclient.csh C-shell script. On Windows nodes, run the JANE\CLIENT\janeclient.bat batch file. In case you run into problems executing the scripts, you may want to briefly view the contents of the script files to understand the problem.
  2. The client displays a connection dialog. Specify the node on which the server has been started, along with its port number. Specify your name, which will be used to identify you during collaborative executions. This will connect you to the server.

Run your Simulation

  1. Spawning the Simulation.
  2. Simulation Input/Output.

Spawning the Simulation

Once the client is successfully connected to the server, you can start your simulation using the client's graphical interface.

In the Simulation-Start dialog, specify the simulation information. On-line help is available in that dialog for information on how to specify the simulation execution information.

Simulation Input/Output

Once the simulation is successfully started, the output from the simulation is displayed by the client in the tabbed text windows. Standard input can be entered by selecting the window, and entering the input and selecting the Send button. Thus, each federate can invoke input functions, such as getchar(), to receive individual user input.

Collaborate with Multiple Clients

The JANE client/server system permits multiple clients to collaborate in controlling a simulation.

  1. One client connects to the server using its original port number. Then that user enables collaboration by using the corresponding menu option in the client window. The server responds with a new collaboration port number to which other clients can now connect. This collaboration port number is different from the original port number to which the first client connected. When other clients connect to this collaboration port (instead of to the original port), then all the collaborating clients receive identical displays of the simulation activity. The clients can communicate with each other using the chat area in the client window.
    Note: There is no master-slave distinction among the collaborating clients. All the active clients have identical capabilities.
  2. If a client joins for collaboration after a simulation has been started, then that new client may not get the most accurate display of the activity. It is best to let all the clients join for collaboration before starting simulations. However, it is permissible for any client to exit from collaboration at any time, even during the execution of a simulation.
  3. Once the collaboration is enabled, and all the interested clients have joined, further joins can be disabled by closing the collaboration port via the corresponding menu option in any of the joined clients.

Frequently Asked Questions
Q1: I get a segmentation fault before/during/after the simulation. What could be the problem?
Try running the simulation under a debugger, such as dbx. For example, you can execute:
dbx -r OBJ/ARCH/runmodel npe endtime
which will run the simulation as usual, but traps the segmentation fault when it happens (assuming that the error is repeatable). You can use the debugger command where to print a stack trace at the point of failure, which could give an idea of where the problem lies.
Q2: I've completed developing my models, and am simulating them now. However, I notice that if I use 4 processors, it actually runs slower than if I use 1 processor! What should I do to get a true speedup?
The amount of speedup depends on several factors. The most important are the number of entities and the communication pattern among the entities. You may have to do a more careful assignment of entities to processors, using the SET_PREFERRED_PE() macro in dconst:init.
Q3: I get a segmentation fault even while the TeD entitites are being initialized. What could be the problem?
This can happen if the amount of preallocated size for lstate variables is less than what is required to hold all the lstate variables in the instantiated network configuration. Try increasing the value of the integer resource PreallocSize in your model.cfg configuration file. If even that doesn't help, try running the simulation under a debugger (ref. Q1).
Q4: Is there a distributed version of TeD/GTW that runs on network of workstations?
No. Currently, the version of GTW used for TeD runs only on a shared-memory multiprocessor, and hence TeD models can only be run on a shared-memory multiprocessor.
Q5: How can I change the compiler used to compile GTW? How about GTW++? TeD compiler? TeD applications?
To change the compiler used to compile GTW, change the CC variable in GTW/SRC/ARCH-GTW. To change the compiler used to build GTW++, the TeD compiler, and the TeD applications, change the GTWPPCC variable in TED/GTW++/CONF/*.defs. To change the compiler flags, change the values of the corresponding variables in the above files.
Q6: How can I interrupt a long-running simulation, without losing all the results that it had simulated so far?
GTW traps several signals and performs various functions depending upon the type of the signal. For example, it exits gracefully upon receiving a SIGTERM. You can interrupt it using the normal interrupt signal, such as SIGTERM or SIGINT -- for example, by pressing the interrupt character control-C or DEL. Or you can kill the process using the kill shell command with the process ID. GTW traps the signal and sets the endtime to the current GVT value, which in turn makes the simulation end normally.
Q7: I have a simulation that has been running for a long time. How can I know how far it has simulated?
Send your simulation process a user signal, SIGUSR1 or SIGUSR2, using kill -USR1 pid, where pid is the process ID of the simulation. GTW traps that signal and prints the current GVT value.
Q8: How can I find the best speedup achievable for my simulation model?
We have incorporated critical path analysis (CPA) into GTW. This permits any GTW application to be analyzed transparently to predict the best speedup achievable for that application. You can invoke the critical path analysis of GTW by using the -CPA flag to the TeD/GTW executable. The simulation must first be run without the -CPA flag on n processors. This will automatically create an LP.MAP file to record the LP-to-processor mapping information. You can run it with an endtime of 0, since it is run only to obtain the LP mappings to processors. Then run the simulation on 1 processor using the -CPA flag (following the endtime argument). GTW will then use Jason Lin's critical path analysis (Algorithm III) to predict the best speedup possible when n processors are used for that simulation, and print a summary of the analysis at the end of the simulation. Absolutely no modifications are required to the application to obtain its critical path information.
Q9: How does the incremental state saving facility in GTW++ work, and how is it used in TeD for lstate variables?
The transparent incremental state saving techniques implemented in GTW++ are based on the well-known method of overloading the assignment operators, i.e., by exploiting the operator overloading features of C++. This technique is straight-forward to understand and implement when the overloaded state types are not used for any reason other than for state variables. However, in TeD models, it turns out that these types are composed into complex structs and classes, which end up being used for local (stack) variables, parameters to functions, global variables, and so on. To address this problem, the incremental state saving methods in GTW++ have been adapted to take care of the non-state usage of these types. The result is that the interface has become relatively complex. Since the TeD compiler generates the code for the TeD models, TeD models are shielded from this complexity. If you need to use GTW++ to build applications, and you intend to use transparent incremental state saving, please contact Kalyan Perumalla for more information.
Q10: What is makefile.aimk and how does it work?
The makefile.aimk is used in conjunction with Makefile to compile the same copy of any source code on multiple heterogeneous architectures. The build-mechanisms of GTW and TeD software have been written using this facility. Briefly, it is nothing but a portable way of including multiple Makefile specifications into one dependency file that make can use. Common definitions are grouped into what are called configuration files (SPARC.defs, SGIMP.defs, etc.) under the CONF directory for each module. These definitions are gathered together while building any software that depends on these modules. Since there is no truly portable way of "gathering" by "including" the files, we use the -f option of make to gather multiple make definition files. All the configuration files are included using the -f flags, and then the makefile.aimk is added as the final make specification that includes all the rules for building the sotware making use of the gathered specifications.
Q11: Does TeD include any run-time checks to trap errors? How do I turn them off for better simulation performance?
The TeD compiler generates extensive runtime checks in the generated code. The GTWTED class library, and the GTW++ class library also include several runtime checks for ensuring sanity at runtime. Almost all of these checks can be turned on (or off) by setting the C preprocessor definition -DDEVELOPMENT=1 (or =0) in GTW/CONF/ARCH.defs. It is recommended that you use two different copies of the TeD installation. During installation of TeD, before you compile the TeD sources, you need to set choose whether runtime checks are turned on or off. Set the DEVELOPMENT flag to 1 for one of the copies, which is the one you should use during the development your models. Set the DEVELOPMENT flag to 0 for the other copy, which is the one you should use for efficient simulation of your models.
Q12: Is there a purely sequential version of GTW that I can use for my TeD simulations?
Yes, a pure sequential simulator with GTW application interface is included with the TeD distribution, under the top directory SEQ-GTW. However, the interface of the sequential version has not been kept up with that of the parallel versions. This may result in errors during compilation of TeD models with the pure sequential version. Note that the execution of the parallel version of GTW on a single processor is almost as efficient as a pure sequential simulator (at run-time, state saving is bypassed by GTW++ and TeD when only one processor is used).
Q13: I want to do parallel simulation of my model, but the percentage of aborted events is always too much (20%). What can I do to reduce it?
When processing an event, if an LP/entity tries to schedule an event, it tries to find a memory buffer from a pre-allocated buffer pool. If there are no more buffers, then the event that is being processed is aborted and re-tried after some time. You can try to reduce the number of aborted events by any/all of the following methods (see TED3.0/TED/APP/MUX/.tw-config for some additional information):
  1. Increase the event memory (EVENT_MEMORY in .tw-config).
  2. Specifying more accurately what percentage of events are local vs. remote (by setting LOCAL_COMMUNICATION in .tw-config).
  3. Increasing the rate at which GVT is computed (decreasing GVT_PERIOD in .tw-config).
  4. Decreasing the batch size (decreasing BATCH in .tw-config).
Q14: Where can I get more help/information?
This document is periodically updated with more information and answers over time. Check out the latest version. Or, send questions via email, or post a question to the TeD users mailing list.
Distribution List

GTW and/or TeD have been distributed to researchers at the following institutions upon their request.

Barcelona University Beijing Univ. of Aero. & Astro. Bellcore
Bell Labs, Lucent Technologies Boston Univ. Bowie State University
BT Labs Cooperating Systems Inc. Colorado State Univ.
ATRI, Curtin Univ. of Tech. Dartmouth College Georgia Tech
Gintic Inst. of Manufacturing Tech., Singapore Fondazione Ugo Bordoni, Italy Hankuk Univ. of FS, Korea
Jet Propulsion Laboratory Mitre Corp. Middle East Tech. Univ., Turkey
Newbridge Networks, Canada Rice Univ. Traveller Multimedia Networks
Trieste Univ., Italy Ultra Corp. Univ. of Alberta, Canada
Univ. of Calgary, Canada Univ. of California, Los Angeles Univ. of Cincinnati
Univ. of Kansas Univ. of Massachusetts, Amherst Univ. of Minnesota
Univ. Politecnic of Catalunya, Spain Universidade de Sao Paulo, Brazil Univ. of Texas, San Antonio
Univ. of Waikato, New Zealand WINLAB, Rutgers University
Copyright and Disclaimers
Modules Authors
GTW Fujimoto, Das, Panesar, et al
GTW++, TeD, Jane Server Perumalla
Jane Client Perumalla and Morgan
Copyright 1996-99 by Georgia Institute of Technology Atlanta, Georgia
All Rights Reserved
Permission to use, copy and modify this software and its documentation for any research purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The use or inclusion of this software or its documentation in any commercial product or distribution of this software to any other party without specific, written prior permission is prohibited.
THE SOFTWARE IS PROVIDED AS IS AND GEORGIA INSTITUTE OF TECHNOLOGY DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL GEORGIA INSTITUTE OF TECHNOLOGY OR THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Kalyan Perumalla, 20 March 1999
Last updated 18 October 1999