|TeD - Telecommunications Description Language|
|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.
|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
|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.
|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).|
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:
|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/GTWType 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.
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.
The simulations can be executed in the following ways:
Command-Line ExecutionTeD 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:
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.
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.
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.
Run your Simulation
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.
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.
|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
|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.|
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|
|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.|
20 March 1999
Last updated 18 October 1999