A Guide to RINGNET

Dave Singer^{∗}

singer@eleceng.ee.QueensU.CA

February 28, 1995

Abstract

This document contains a complete guide to the RINGNET Network Simulation System. The RINGNET system consists of an event driven Network Simulator, designed to simulate variable size circular networks, and a set of MAT LAB^{tm} scripts to solve the system of Differential Equations that describe the GHK Network model.

This Guide is broken into three parts, a users guide for the simulation, a programmers guide for the simulation, and a users guide for the MAT LAB^{tm} scripts.

∗Supported by a University of Queensland Vacation Scholarship

Contents

2

1 RINGNET Users Guide

RINGNET was designed to be easy to use, and simple to incorporate into batch procedures for executing multiple runs. It reads the network configuration information from a file, and writes the output to another file. The format for begining a simulation run is:

ringnet input file output file

It is useful to put ringnet in a directory that is in your command path. This way separate batches of runs can be kept in separate directories without requiring multiple copies of ringnet. It also makes it easier to update when changes are made if only one copy of the executable file exists.

1.1 RINGNET Input File

The input file is of the form:

rand stream: 2 max time: 2.0 tran time: 5.0 no samples: 40 no runs: 200 K: 10 C: 10 lambda1 0 lambda2: 200 r: 0 TLTT: 5

rand stream: This specifies which stream of random numbers to use. Each stream has a different starting seed that guarantees the streams are independent. 1 through 20 are valid arguments.

max time: This is the maximum time the simulation will run for. It is chosen in the same units as the arrival rates (ie. if the arrival rates are in arrivals per second then the maximum time is specified in seconds.)

tran time: This is the estimated transient time of the system (may be approximated by the settling time of the GHK model). It is the time before call blocking statistics are gathered.

no samples: This is the number of sample points to be gathered from each simulation run. The are spaced at \frac{max time}{no samples} intervals. no runs: This is the number of simulation runs to be performed for this set of pa-

rameters. The mean and 95% confidence intervals for the various statistics are written to the output file.

K: The number of links in the network.

C: The number of circuits per link

lambda1: The arrival rate of type one traffic. That is traffic that only requests capacity from one link. The rate is specifed in terms of the proportion of full loading of the network. That is, a value of 1 will cause a load of 100% on the network due to type one traffic. ie. lambda1 = \frac{ν_{1}}{K∗C}

lambda2: The arrival rate of type two traffic. That is traffic that requests capacity from two links. This rate is specified in the same way as type one traffic, except that the rate is effectively doubled because each call requires twice the capacity from the network. ie. lambda2 = \frac{ν_{2}}{K∗C}^{1}

r: The number of circuits reserved from each link for type two traffic only.

TLTT: The Two Link Traffic Type. The cleardown times for all models are generated from the exponential distribution with mean 1. The various traffic types are:

0: This is the Real system. Two link calls are set up on adjacent links and are cleared down at the same time.

1: This is the ICD (Independent Clear Down) model. Two link calls are set up on adjacent links but are cleared down independently.

2: This is the GHK (Gibbens-Hunt-Kelly) model. Two link calls are set up on randomly selected links and are cleared down independently.

3: Two link calls are set up on randomly selected links but are cleared down at the same time.

4: Two link calls are set up on randomly selected links, However on cleardown two arbitrarily selected links are cleared down at the same time.

5: Two link calls are set up on adjacent links, However on cleardown two arbitrarily selected links are cleared down at the same time.

1With these defintions total loading of the network = (lambda1 + 2*lambda2)*100%

1.2 RINGNET Output File

The output of the simulation is writen to the file specified by the user when the run is started. This file consists of no samples rows of 8 columns of floating point numbers. These results can be plotted by the user’s favourite graphing package. If MAT LAB^{tm} is to be used the output filename must end in .dat, eg. out.dat. The columns are:

1: The time for which the other statistics in this row are gathered.

2: X_{C}, the proportion of full links.

3: The magnitude of the 95% confidence interval for X_{C}.

4: The average number of circuits in use in each link of the network.

5: The magnitude of the 95% confidence interval for column 4.

6: The blocking probability for the network, defined as:

1 − \frac{type1 accepted+type2 accepted}{type1 offered+type2 offered}.

7: The type one call blocking probability, defined as: 1 − \frac{type1 accepted}{type1 offered}

8: The type two call blocking probability, defined as: 1 − \frac{type2 accepted}{type2 offered}

1.3 System Limits

One limitation of RINGNET is that, due to limited development time, very little error checking has been incorporated into the program. This means that if the limits of the system are exceeded it will either crash or give meaningless results with no indication of why this is happening. This may be avoided by exercising some care when setting up the network configuration file.

The things that the user should be aware of are:

Configuration File If the configuration file is not of the correct form, or does not contain the correct number of parameters, then the system could do anything from a core dump to producing impossible results. This should be one of the first things checked if there is a suspected error.

K The maximum number of links in the network is currently set to 2048. If a larger network is desired this can be changed by changing the MAX SIZE definition in sys.h and re-compiling.

C There may not be more than MAX SIZE circuits per link in the network.

r The trunk reservation should not be set higher than the number of circuits on a link. If it is the simulation will still run, but type 1 traffic will always be lost.

tran time The transient time should not be set higher than the maximum time. If it is no blocking statistics will be gathered.

no samples The maximum number of sample points is currently set to 100. If more sample points are required this can be accomplished by changing the MAX STAT definition in sys.h and re-compiling.

output file If the specified output file already exists then the new results will be appended to end of the old file, and it can be difficult to tell which run is which.

2 MAT LAB^{tm} Script Guide

There are five MAT LAB^{tm} scripts included as part of RINGNET. They are: xdot.m, ghk23.m, ghk45.m, addghk23.m, and addghk45.m.

xdot.m contains the definitions of the system of differential equations for the GHK network model. This file should not be touched by the user unless a new system of DE’s is required.

The ghkxx.m and addghkxx.m scripts solve the system of DE’s defined in xdot.m. ghk23.m and addghk23.m use the MAT LAB^{tm} ode23 function (a variable step size Runge-Kutta method using second and third order terms) to solve the system, while ghk45.m and addghk45.m use the ode45 function (the same as ode23 except fourth and fifth order terms are used.) ode45 is more accurate, but significantly slower than ode23. It was found that for most applications ode23 produced acceptable results.

When executed both ghkxx and addghkxx will prompt the user for the parameters under which to solve the system of equations. A typical run could look like this: >> ghk23

Please enter max time: 10

Please enter C: 10

Please enter lambda1: .2

Please enter lambda2: .4

The only difference between ghkxx and addghkxx is that ghkxx will clear the MAT LAB^{tm} graphics window and graph the solution of X_{C} vs time on an appropriately scaled graph, where addghkxx plots the graph overtop of whatever graph is currently in the graphics window. addghkxx is useful for plotting the theoretical curve on the same graph as the simulated curve for comparrison purposes.

3 RINGNET Programmers Guide

The RINGNET simulation program is made up of 5 modules, a header file, and a makefile. They are: initialize.c, ringnet.c, call handling.c, random.c, event list.c, sys.h, and Makefile.

The makefile, Makefile, handles all the compiling and linking required to re-build the simulation after any of the modules have ben changed. All that is required is to type make in the directory containing all files listed above.

The header file, sys.h, contains the declarations for all the constants, structures, global variables, and functions necessary for RINGNET. If any functions are added to any of the modules they should be declared in sys.h. Also, any new global variable (ie. a variable used in more than one module) should be declared in sys.h.

The various program modules will be discussed separately, on a function by function basis, in the following sections. There will then be a brief outline of what is involved in adding new traffic disciplines to the simulation.

3.1 initialize.c

initialize all() This function calls all the relevant functions, and performs all necessary actions to initialize the simulation before the first run. This includes zeroing the variables, seeding the random number generator, calling the load inputs function, and starting the event generation cycle.

re initialize() This function performs the required initialization between successive runs. If changes are made to the methods of gathering statistics it is very important to make sure the approriate inter-run initialization is added to this function.

load inputs() This function loads all the simulation configuration parameters from the user specified input file. It returns an error message, and exits the simulation if the file cannot be opened.

initialize matrix() This function initializes the network matrices.

initialize stats() This function initializes the statistics matrices.

3.2 ringnet.c

main() Contains the initialization calls, and the main event loop for the simula-

tion.

do stat() This function gathers the statistics at each sample point. It maintains a

running sum, and sum of squares for each statistic at each sample point.

save stat() This function saves the statistics to the specified output file. It is called after all the runs are finished.

3.3 call handling.c

generate arrival1() This function generates a type one arrival. generate arrival2() This function generates the various types of type two arrivals.

generate arrival event() This function generates an event for the next arrival, and inserts it in the

event list.

generate departure event() This function takes a link, a time, and the traffic type and generates a

departure event.

departure1() This function performs type one departures. departure2() This function performs type two departures.

3.4 random.c

The random.c module used algorithms taken from \underline{Numerical Recipes in C}, and is part of a standard library of simulation modules developed at Queen’s University. These functions should not need to be modified by the user.

stream() This function takes an integer between 1 and 20 as an argument and uses that seed (from the seed list) to initialize the random number generator.

sdrand() An interactive function that allows the user to set the stream at runtime (not used in this simulation).

uniform rnd() This function generates uniformly distributed random numbers on the interval (0,1).

lim uniform rnd() This function generates a uniformly distributed integer between the specified bounds.

exponential rnd() This function generates exponentially distributed random numbers with the specified mean.

geometric rnd() This function generates geometrically distributed random numbers with the specified mean.

3.5 event list.c

The event list.c module (and the associated definitions in sys.h) is part of a standard library of simulation modules developed at Queen’s University. These functions should not need to be modified by the user, and may be regarded as Black Box functions.

allocate event space() This function returns a pointer to a portion of memory allocated as an EVENTPTR (defined in sys.h) type variable.

insert event() This function takes an event and adds it to the appropraite point of the time sorted event list (the name of the event list must be evlist ).

remove event() This function removes the head event from the list, and frees the allocated memory space.

display event() This function prints the current event list to the screen. It is generally only used for testing purposes.

3.6 Array Formats

This section will explain how the various arrays used in the simulation are structured. The arrays are:

network(MAX SIZE)(2): This array holds the desription of the network in terms of the number of

calls per link. It is set up as shown, where K is the number of links. # link 1 calls

# type 1 calls on link 1

# link 2 calls # type 1 calls on link 2

⋮

# link K calls # type 1 calls on link K

markov(MAX SIZE + 1): This array holds the markovian description of the network, in terms of the proportion of links at each degree of fullness. It is set up as shown, where C is the number of circuits per link. proportion of links with 0 calls

proportion of links with 1 call

⋮

proportion of links with C calls

stats(MAX STAT)(2): This array accumulates running sums of the proportion of full links at each sample time. It is set up as shown, where X_{C} is the proportion of full links, and N is the numbe of samples. X_{C} at sample point: 1 X_{C}^{2} at sample point: 1

X_{C} at sample point: 2 X_{C}^{2} at sample point: 2

⋮

X_{C} at sample point: N X_{C}^{2} at sample point: N

stats2(MAX STAT)(2) This array accumulates running sums of average link occupancy at each sample time. It is set up as shown, where Y_{C} is the average link occupancy, and N is the numbe of samples. Y_{C} at sample point: 1 Y_{C}^{2} at sample point: 1

Y_{C} at sample point: 2 Y_{C}^{2} at sample point: 2

⋮

Y_{C} at sample point: N Y_{C}^{2} at sample point: N block prob(MAX STAT)(3): This array accumulates running sums of the various blocking probabilities

at each sample time. It is set up as shown, where b_{t} is the total blocking probability, b_{1} is the type 1 blocking probability, b_{2} is the type 2 blocking probability, and N is the number of samples. These probabilities are defined in section 1.2. b_{t} at sample point: 1 b_{1} at sample point: 1 b_{2} at sample point: 1

b_{t} at sample point: 2 b_{1} at sample point: 2 b_{2} at sample point: 2

⋮

b_{t} at sample point: N b_{1} at sample point: N b_{2} at sample point: N

3.7 How to Add Models

This network simulator was originally designed to compare different models of two link traffic. With this in mind is was intentionally set up to be easy to add new traffic models to the system.

In order to add a new model to the simulator only 3 things need to be done:

1. Add a new Two Link Traffic Type definition to the sys.h file. This will simply be the name of the model (eg. DEP DEP) and an index number.

2. Add a new case statement to the TLTT switch in the generate arrival2() function of the call handling.c module. Using the existing cases as models, this is often a case of cut-and-paste with only one or two lines needing changing.

3. Re-compile the program.

If there are any problems, or question regarding the RINGNET package I can be contacted by e-mail, and will be more than happy to help out in any way I can.

4 Acknowledgments

I would like to thank the University of Queensland Mathematics department for the Hospitality shown During my stay as a Vacation Scholar. And I would also like to thank Mark Bebbington, Phil Pollett, and Ilze Ziedins for their continual help and support while I was working on this project.