I. Getting OBJECTSIM
II. Using OBJECTSIM
- Software Structure
III. Extending OBJECTSIM
- The OBJECTSIM Simulation Model
- Command Line Environment
- The Sample Experiment
- Building Your Own Experiments
- The Hierarchy
- Specifying Simulation Entities
- Example of a Simulation Library Implementation
- Integrating Simulation Libraries into OBJECTSIM
OBJECTSIM V0.3 has been developed for UNIX workstations. It requires the following minimum configuration.
OBJECTSIM is distributed as a single UNIX tar file OBJDST_V0.3.tar. This file is also available as a gnu compressed version OBJDST_V0.3.tar.gz. To install the system you extract the tar file which will create the file system ./OBJECTSIM/Dist, and unpack the distribution into the resulting Dist directory. You should cd to the Dist directory and follow the customization and installation instructions contained in the README file there.
Assuming that you have downloaded the compressed source files a normal
sequence of instructions to do this is.
Once you have unpacked the sources and created all the rest of the required file system in the process you should cd to the OBJECTSIM/src directory and type make. This builds all the kernel and object libraries supplied with the standard installation and distributes them appropriately. This also builds the OSim executable and places it in the OBJECTSIM/bin directory.
Finally you need to edit your .cshrc file and update it as instructed in the README. Don't forget to add the OBJECTSIM/bin directory to your PATH variable. Please contact your local system administrator if any of the steps in the README or these instructions are unfamiliar to you or you wish to have a commonly available version of OBJECTSIM. Since OBJECTSIM is still under development we ask you to please register your copy of OBJECTSIM for tracking purposes, and so that we can assist you with future releases.
NOTE: OBJECTSIM is not a commercial product, so
support maintenance and development are entirely at the discretion of the
research team using OBJECTSIM. No warranties or product guarantees are
made or should be inferred from the distribution of this software.
After installing OBJECTSIM you should have the file system shown in figure 1 below. This section of the manual explains the function of each directory, and prepares you to compile the sample experiment that is included with the distribution.
The major directories that are created by installing OBJECTSIM contain all the sources and libraries required to create OBJECTSIM itself, and then use it to configure and execute simulations. Building the OBJECTSIM suite creates libraries which support the construction of simulations based on the objects included in the standard distributions, and also distribute the header files which define the interfaces with simulation objects, and the OBJECTSIM kernel source files.
The current distribution supports basic modelling of multistage interconnection networks (MIN's). It defines two by two unbuffered crossbar switches which can be connected to each other to form standard types of MIN. Banyan switches with various levels of buffering and multicast capability are also implemented in the base object library.
The libraries are stored in the directory OBJECTSIM/lib and the headers are all copied from the relevant source locations to OBJECTSIM/include. If you want to look at the C++ interface for any simulation or kernel class you should go to the include directory and look at the header files there.
The OBJECTSIM kernel code is separated into two logical components. Kernel code and model code. The kernel code manages the model object instances, and the model library code defines the classes in the model object libraries from which object instances are created and connected to form simulations. The installation includes the standard model libraries we have developed for network and computer architecture simulations. Models of new object classes added during your research should be implemented as new model source files using standard interfaces inherited from the basic OBJECTSIM hierarchy. Building your own simulation objects and libraries and integrating them into OBJECTSIM is described in Section III .
We expect additional libraries to become available from the OBJECTSIM
web site as people apply the methodology to their own application areas.
Since one of the major objectives of OBJECTSIM is to encourage code reuse
in the simulation community it is hoped that people using the tool will submit
their libraries to this Web site for use by the OBJECTSIM community.
OBJECTSIM consists of a simulation kernel and a generic object class from which all simulation entities are derived. This allows OBJECTSIM to provide generic support for event driven simulation of any system that can be modelled as a set of interacting entities. In essence the simulation model assumes a collection of entities, each of which is a state machine responding to external events. Typical responses to events include generating future events, changing internal state. The execution model assumes that all data items are associated with an event. However, this event model does not assume that every event has data associated with it, since meta-events, and control events are not usually associated with data exchange between simulation entities.
Simulation entities are completely generic, and have no concept of the structure of the overall system of which they are a part. They merely respond to events that are delivered to them. This approach to simulation of concurrent systems relies on the definition of an extremely powerful generic hierarchy of simulation entities. All OBJECTSIM simulation entities are derived from a single base class, which completely defines the interface between these entities, the simulation kernel, and all other entities. This derivation allows simulation architects to focus on specifying a behavioural model of the simulation entities with no concern for the entity interconnections and other issues associated with the structure of the overall system being modelled.
To arrive at this level of genericity OBJECTSIM uses the concept of virtual PORTS to specify abstract entry and exit points for an entity. These ports are used in each entitiy to accept inputs and store outputs. The implementations of generic simulation entities consume messages from input ports and generate messages on output ports. When a system architect designs a new simulation entity s(he) will derive a new object type from the base class Object, specify how many input and output ports it has, and provide an implementation for a virtual function called Execute(). The code of the Execute() function defines how the new entity will react to input messages, including forwarding messages to output port or generating new messages on output ports. Consequently, when designing a new class of simulation entities for OBJECTSIM one need only decide on the structure of that particular entity, and provide an interface through which that entity communicates with the external environment.
The overall structure of a simulation for a complex system is defined
by establishing relationships between object instances (entities/agents).
Output to input port correspondences for each simulation agent are specified
when a system model is constructed. Port correspondences are registered
with the OBJECTSIM kernel Routing manager which handles the transfer of
Events between agents. Currently the registration of port mappings and
the construction and supply of object instances to the kernel must be handled
by the user, however, a Visual Simulation design interface is planned
for release with OBJECTSIM V0.5.
OSim can be configured to run experiments by issuing commands
to a command line environment, or by specifying options at
runtime. Combinations of runtime and command line options can
also be used. This section describes the commands that can be
used at the OSim prompt.
When you run OSim as a stand alone environment a prompt
appears, and commands can be used to load experimental
configurations and execute them. The available commands can be
listed at any time by issuing the command "help" at the prompt.
The command line environment
also allows the user to configure OSim in a cluster computing
environment, adding additional hosts, and running parallel simulations
on the workstation cluster.
Current OSim commands are
Many of these commands have runtime option equivalents.
All the runtime options are listed in the
manpage and are also listed using the "-h"
runtime option to OSim.
When you run OSim as a stand alone environment a prompt appears, and commands can be used to load experimental configurations and execute them. The available commands can be listed at any time by issuing the command "help" at the prompt.
The command line environment also allows the user to configure OSim in a cluster computing environment, adding additional hosts, and running parallel simulations on the workstation cluster.
Current OSim commands are
Many of these commands have runtime option equivalents. All the runtime options are listed in the manpage and are also listed using the "-h" runtime option to OSim.
Some sample configuration files that can be used to test OSim, and familiarize oneself with the OSim runtime environment are located in OBJECTSIM/experiment. This section describes how to start OSim and run an experiment and explains the features of OBJECTSIM that you need to understand to do this. The upgrade from V0.3 to Version 0.4 makes OBJECTSIM a runtime simulation environment that can be customized to execute any simulation consisting on object instances constructed from an OBJECTSIM library.
Previous releases of OBJECTSIM used module libraries and compiled and linked the main simulation kernel to the library which provided the object definitions and a main routine (written by the experimenter) that constructed the simulation experiment's object instances and initialized the simulation kernel. From V0.4 onwards the approach is completely different. To run an experiment you invoke OBJECTSIM and load simulation configuration files using either command line options or by issuing instructions to the OBJECTSIM environment command interface.
To run the basic experiment type "OSim -f test.ocf" in the OBJECTSIM/experiment directory. This automatically starts the objectsim environment and loads the default experiment. Note, OBJECTSIM configuration files are expected to terminate with the extension .ocf and the environment checks the file extension and some internal format during loading. An experiment can be loaded at invocation using command line options to select a configuration file, or by issuing commands at the command prompt once the basic kernel has been booted.
To run the "test" experiment you type "run" or "go" at the command prompt since all the configuration and simulation objects were loaded during bootup using command line options supplied in a startup script. This test experiment consists of the most simple simulation possible. A statistical source object (generating message packets) is connected to a statistics collection object (which consumes and counts packets received). The output of the simulation is data which indicates how many packets were generated at the source, and information from the consumer object shows how many packets were recieved and the distribution of destination addresses of the packets collected.
The experiment directory contains two configuration files that are a useful guide to creating and executing your own simulations. If you are only going to use the standard objects provided with OBJECTSIM you need only consult the section which defines all the standard objects and their interfaces, and copy and modify the experiment directory script files using them as a template for creating your own simulations.
Each simulation consists of a number of simulation objects and a wiring plan that specifies how the input and output ports of each object are connected so that events can flow between the objects. The structural representation of the test experimental system is shown in figure 1.
MaxPrts 2 MaxObjs 2 StatCPU 1000 0 2 NetSink "Received Packets" 4 END RouterEntry 0 0 0 0 RouterEntry 0 1 1 0 Event 0 0 0 0 0
The first two lines in the script specify the number of objects in the system, and the maximum specified number of ports in any object that is used by the simulation. These figures are used to define the size of the routing table that describes how objects communicate with each other. These two quantities can occur in any order, but must be given as the first two lines of any configuration file.
The next section of the simulation configuration file specifies the parameters to be used to create each object in the simulation. Each line represents an object and the objects are assumed to be numbered from zero to MAX_OBJS. This numbering scheme is important since it is used to set up the routing table. Each Object of the file consists of the Object name first and then the user parameters that can be supplied to the constructor of that object. The system does limited checking against some internal information to check that the object name and number of parameters are legal. This section must be terminated with an "END" on a single line.
The next section of the file specifies the routing entries used to connect the ports of the simulation's objects together, forming a final system architecture. Each routing table entry begins with the string RouterEntry which is followed by four parameter values. Each router entry consists of two tuples (OId,Port). To wire the objects together each RouterEntry specifies an output tuple, and the input tuple which represent the two end-points of a connection.
In the test example there are two entries. The first is the self activation event flow for the StatCPU object, and you can see that the connection is between (0,0) and (0,0), meaning that events exiting object zero via output port 0 should be delivered to objects 0 input port 0 at some time in the future. The second entry is (0,1) to (1,0), meaning that events leaving object 0 on output port 1 should be delivered to object 1 input port 0. This configuration is shown as an object wire diagram in the figure below. A more complicated example is given in section ???.
When simulation objects are implemented the input and output ports for different types of operations are specified by the designer. By referring to the specifications in the library documentation one can decide how to connect the ports of objects together to realize the system design we wish to simulate.
Gathering and display of performance statistics for each object in the system can be implemented by writing code in the DumpStats() methods of the simulation objects to collect and report/store any information that is required. At present this data is summary information and it is not really possible to use this facility to dump out progressive statistics. Progressive information can be collected by instrumenting the Execute method of the object to print information to the screen, or to dump information to a file. Future versions of OBJECTSIM hope to provide integrated data visualization facilities, but such facilities are not scheduled for inclusion in releases of OBJECTSIM in the near future.
Using the standard libraries to build experiments begins by selecting the simulation objects that are required. Next create a logical communication schematic of the architecture similar to that shown for our sample experiment. This will help you to build a correct routing table. This step will be automated when we release the visual design interface integrated into OBJECTSIM V0.5.
To create an experiment, create a configuration file
and list the objects you need, and instruct the router on how they are connected
together. Once again, the test experiment code provides a useful guide
on how to do this. To load your new experiment invoke OSim using
the -f runtime option or the command line to load your file.
Type "go" at the command prompt to execute your model.
The standard library objects collect and display
predefined statistical information that was considered of interest to the
designers. If you require other statistics or need access to objects which
are not defined in the standard libraries you will need to create new simulation
model library code to implement new simulation object classes, or derive
and refine new object classes from the existing objects in order to adjust
the definitions of existing objects to fulfil your requirements.
When you do so, we suggest that rather than changing
the implementation of the standard objects, you inherit their structure
and build new object libraries to meet your needs. By using the inheritance
features of C++ in this way you can maximize the benefit of using other
people's code, without compromising the integrity of the basic OBJECTSIM
The next section is a step by step guide to extending
the OBJECTSIM hierarchy, and writing new libraries of simulation objects
that are derived directly from the three basic node classes. Please read
this section before you start to implement new OBJECTSIM classes to ensure
that your new simulation objects will be compatible with the simulation
kernel. If you decide to extend the OBJECTSIM hierarchy please consider
submitting your extensions and new class libraries to the OBJECTSIM web
site to enhance the system and assist other users.
The standard library objects collect and display predefined statistical information that was considered of interest to the designers. If you require other statistics or need access to objects which are not defined in the standard libraries you will need to create new simulation model library code to implement new simulation object classes, or derive and refine new object classes from the existing objects in order to adjust the definitions of existing objects to fulfil your requirements.
When you do so, we suggest that rather than changing the implementation of the standard objects, you inherit their structure and build new object libraries to meet your needs. By using the inheritance features of C++ in this way you can maximize the benefit of using other people's code, without compromising the integrity of the basic OBJECTSIM library hierarchy.
The next section is a step by step guide to extending the OBJECTSIM hierarchy, and writing new libraries of simulation objects that are derived directly from the three basic node classes. Please read this section before you start to implement new OBJECTSIM classes to ensure that your new simulation objects will be compatible with the simulation kernel. If you decide to extend the OBJECTSIM hierarchy please consider submitting your extensions and new class libraries to the OBJECTSIM web site to enhance the system and assist other users.
The OBJECTSIM simulation model is based on a simple and powerful hierarchy of simulation objects. This methodology proposes single high level interface for all objects (node), and derives three basic classes of object from this single entity. The fundamental entity of a simulation is a Node, a simulation node will be one of three basic types, a source, forward, or sink for events. The node types may be briefly characterized as follows:-
The Object class also specifies the interface used for all interaction between simulation model entities. Additional private and public methods can be added to classes derived from the virtual class Object, but these methods are not accessible to the Simulation Kernel and should not be used to communicate directly between derived object classes as this contravenes our "prime directive"; which is to maintain complete object genericity, and independence. This means that no object implementation should have any knowledge about the methods or data types of other objects, with the exception of Events.
The standard interface provides input and output Event lists for
each object, and a virtual function Execute, which is overridden in the
derived classes to provide the functionality of the new object class. The
Execute function of a derived class will normally use additional private
methods specific to that class to process the incoming messages and events,
and generate additional events if required. Data transfer between entities
is handled by attaching the data to an Event, and Posting it to a port.
How that data is unpacked by the receiver depends entirely upon the functional
definition of the receiving object. Obviously objects that exchange data
will have a protocol which allows them to interpret each others data, but
we leave details of this nature to the end user. To facilitate generic
data transfer OBJECTSIM events pass all data content as a void *,
thus data consistency and memory allocation for explicit data transfer
between objects is entirely an end user issue. An example of data
exchange piggy-backed with event exchange is provided in the standard network
object library objects. For example see the implementations of SlotBus,
and TwoMIN in the model directory file base.cc.
To design a new simulation entity you must inherit the basic interface of a simulation object by including the header file sim_obj.h, and deriving your new class from the basic OBJECTSIM class Object. As previously noted new simulation classes must be derived from this base class to ensure compatibility with the Kernel implementation. Of course additional attributes and methods can be added to the derived classes to implement their new functionality using the standard C++ syntax. However it should be noted that the basic functional definition of a derived class must be implemented by overloading the Execute virtual function of the base class Object. A pictorial representation of the important features of the OBJECTSIM Object showing the major interface entry and exit points and the principal attributes is given below. This is not a complete specification. The intention is to give an overview of the important aspects of the OBJECTSIM Object model in order to facilitate understanding of the fundamental techniques. A full interface specification in C++ can be found in the file OBJECTSIM/include/sim_obj.h.
// Our functional defn of
Execute and DumpStats
// We will define their implementations in our .cc impl file
virtual void Execute();
virtual void DumpStats();
A rather nasty feature of the current OBJECTSIM implementation is that
event creation and deletion are handled expicitly in the code that defines
the implementations of behaviour. That is you will create and Post
an event using code similar to the following
// Update clock, memorise it locally, and generate
setClock( evt->getTime() );
clk= (int) getClock();
// Delete event
As indicated this section is devoted to explaining the structure of a sample simulation library. The intention is to provide more information about how a simulation library should be designed and implemented in OBJECTSIM. The complete implementation of the library code is found in the files $(LOCATION)/OBJECTSIM/src/model/base.cc and base.h in your installation.
The objects in the base simulation library implement very simple
objects which provide source address streams, switches and output packet
collectors for a very simple model of a Multi-stage Interconnection Network
(MIN). In this model we have defined three object types which will be used
to implement a MIN network of any size, and then evaluate the packet loss,
throughput and average delay for that network. The generic nature
of OBJECTSIM simulation components means that we can build an arbitarily
large network by creating instances of the three primary object classes.
The object classes and their function in the simulation model are summarised
in the following table.
|StatCPU||A source object that generates data packets to a destination addess on the other side of the MIN. Destination addresses are generated using a standard statistical model based on random number generation.|
|TwoMIN||Two input crossbar switch with no buffers. Since the switch has no information about what stage of the MIN it is in it has to interrogate the packet that it is switching to discover how it should treat that packet.|
|NetSink||A statistics object that collects and disposes of the data packets as they leave the MIN. Packets can leave the MIN when they are dumped due to internal collisions or when they arrive at the destination. The implementation of a NetSink is currently just a counter of how many packets were discarded or left the network normally, and the average time those packets spent in the network.|
The MIN that is defined in the expts directory in the file
is a two stage min constructed from four switches to which are connected
input generators and output data collectors. The conceptual design for
this experiment is shown in the figure below.
However the figure above (while an accurate depiction of the system
to be modelled is not the most efficient way to construct a model of this
system from the objects we have defined, and to collect the appropriate
statistics. Since we are interested to collect a summary of the output
and discarded parket information the actual simulation model that we have
used in the experiment is the following.
This conceptual simulation model is finally implemented using an inter-object communication pattern that is almost identical to that shown above. The only difference is that self execution loops are added to the StatCPU instances to ensure a steady stream in input packets.
Having defined the simulation model as shown the final step is to implement
the functionality of each of the object classes required. The following
subsections deal with the key issues involved in designing each of the
objects in turn, and also discusses the need for a packet data structure
which can store state information so that appropriate statistics can be
collected by the model objects.
Once you have designed and implemented new simulation objects and tested them you will need to link these objects into the OBJECTSIM libraries so that you can use them in simulations. To do this you need to follow the instructions below, which specify how to add the files you have created to the set of standard source files used to build the OBJECTSIM model object libraries. You can then include the appropriate header file into an experiment main.cc file, instantiate objects, and insert them into a kernel instance in exactly the same manner as was used in the sample experiment.
To compile and install a new set of objects into the OBJECTSIM model libraries you need to implement your library and update the Makefile in the OBJECTSIM/model directory to include your new library as a compilation and distribution target. This will ensure that your library will be added to the standard OBJECTSIM model library archive automatically when you type make in the OBJECTSIM/model directory. It also ensures that if you collect the OBJECTSIM version you have installed and relocate it to another platform all your new sources will be automatically added to the standard distribution files and unpacked and distributed appropriately, simplifying the relocation process. In effect your new code will have become a standard part of the OBJECTSIM library collection.