README for Simone V3
Simone - Simulator for OCDMA Network Experimentation

1. Introduction
---------------

Simone, (Simulator for OCDMA Network Experimentation) is a discrete event simulator used to simulate media access control protocols on a shared medium, broadcast Local Area Network that uses an optical CDMA physical layer.
It simulates a network of several nodes connected by a passive optic coupler.
It is used for evaluating Interference Avoidance, a distributed, contention based Media Access Control (MAC) protocol for optical CDMA LANs.
This document contains instructions on how to build Simone, its limitations and how to use it.

2. Building Simone 
------------------

Download the code to a directory.
Open the Makefile for editing and change the $SRCBASE variable to reflect the path to the source.
Type "make".
An executable called "simone" should be created.


3. Running Simone
-----------------

This section explains the configurable parameters of a Simone simulation.
Typing simone at the command line results in the following output:


The parameters are described in detail below:
Usage: simone <seed> <N> <A> <w> <K> <Chip rate in c/s> <Interarrival distribution> <Packetsize distribution>  <Input traffic file> <Output traffic file> <Average packet size in bytes> <Normalized offered load> <Number of packets> <Topology> <Number of nodes> <Topology distribution>  <Average distance of node in m> <Bus coupling distance>  <Tx scheduling algorithm> <Threshold> <State estimation algorithm> <Window (bits)> <Processing delay (bits)> <Sampling> <Sampling frequency
<Topology> 0-Star/Bus 1- Modified bus
<Sampling> 0-No 1-Yes
<Transmission scheduling algorithm> 0-Aloha 1-Selfish 2-Threshold 3-Overlap section 4-Overlap size 5-Admission control 6-Distributed perfect scheduling.
<State estimation algorithm> 0-Perfect 1-On demand 2-Continuous
<Distributions> 0-Exponential 1-Uniform 2-Deterministic 3-Trimodal 4-From file




3a. Parameters
------------

Several parameters can be configured:
Physical layer: 
(a) Bandwidth (chipping rate) of the network
(b) Codeset parameters (Length N , Wavelengths A, weight w, kappa K)
(c) Codeset used

MAC layer:
(a) Transmission scheduling algorithm: (Aloha, Selfish, Threshold, Section length
(b) Threshold parameter
State estimation parameters (distances, sensing windows, mode, backoff parameters) will be supported in the next version.

Traffic model
(a) Distribution or from a file
(b) Offered load (this decides the average inter arrival time)
(c) Average packet size

Simulation parameters:
(a) Number of packets in the simulation

For more information about the meaning of the simulation parameters, 
refer to [1], [2] [3].

3b. Prerequisites
---------------

A codeset file called codes.N.A.w.K.txt must be present before running the simulation. Its format is discussed below. Sample codesets may be generated using the "codegen" tool present in the package.
If the traffic is to be read from a file then a traffic file must be present. Its format is discussed below.

3c. Trace file format
---------------------

The simulator can run using traffic files. The traffic files consist of records for each packet. 
The trace file has the following parameters:
(a) Arrival time of the packet
(b) Source, destination addresses 
(c) Packet sizes 

A sample trace file 1.trc is provided with the simulator code.
The format is 

<timestamp of packet arrival at interface card in seconds> <x coordinate of transmitter> < y coordinate> < z coordinate> <size of packet in bytes> <src address>.<src port> <dst address>.<dst port> <packet id>

<pktid> is a unique identifier (integer) for each packet

E.g.
0.0000000000000 0 0 0 1000 1.1.1.1.80 2.2.2.2.80 0

3d. Codeset file format
----------------------
A sample codeset file codes.10.10.3.3.txt is provided with the simulator code.
The naming format of the codeset file is codes.<code length>.<number of wavelengths><weight>.<kappa>.txt 
The codeset file format supports both 1D and 2D codewords.
 
The codeset file format is below:
<Number of codewords in the codeset>
<Weight of the codeset>
<Codeword1 on  Lambda1> <Codeword1 on Wavelength2>.....
<Codeword2 on  Lambda1> <Codeword2 on Wavelength2>.....
<Codeword3 on  Lambda1> <Codeword3 on Wavelength2>.....
.
. 
.
.


4. Evaluating the output
------------------------

The output trace file format is 
<timestamp of when the packet passed the coupler> <packet size in bytes>  <source addr>.<src port> <dst addr>.<dst port> <packet id> <state of packet (Received/Dropped)> 

Note that the timestamps in the output file will not be in order 
Packets are ordered in the order that they pass the coupler.
The state is 0 for received without error and 1 for received with error.

At the end of the run, the simulator provides the following results:
(a) Number of packets that were sent
(b) Number of packets that survived interference
(c) Offered load
(d) Network throughput
(e) Average number of packets on the line

5. Limitations
	- Tested on FreeBSD 4.9-RELEASE only. Other systems may need modification. 
	- The offered load printed in the output is erroneous when traffic is read from a traffic file

6. References

[1]	P. Kamath, J. D. Touch, and J. A. Bannister, ``Algorithms for Interference 
Sensing in Optical CDMA Networks,'' in IEEE International Conference on
Communications (ICC), June 2004.

[2]	P. Kamath, J. D. Touch, and J. A. Bannister, ``The Need for Media Access 
Control in Optical CDMA Networks,'' in IEEE Infocom, March 2004.

[3]	P. Kamath, J. D. Touch, and J. A. Bannister, ``Transmission scheduling in Optical CDMA Networks'', April 2005.