The file format described here applies to both output vector and output scalar files. Their formats are consistent, only the types of entries occurring in them are different. This unified format also means that they can be read with a common routine.
Result files are line oriented. A line consists of one or more tokens, separated by whitespace. Tokens either do not contain whitespace, or whitespace is escaped using a backslash, or are quoted using double quotes. Escaping within quotes using backslashes is also permitted.
The first token of a line usually identifies the type of the entry. A notable exception is an output vector data line, which begins with a numeric identifier of the given output vector.
A line starting with # as the first non-whitespace character denotes a comment, and is to be ignored during processing.
Result files are written from simulation runs. A simulation run generates physically contiguous sets of lines into one or more result files. (That is, lines from different runs do not arbitrarily mix in the files.)
A run is identified by a unique textual runId, which appears in all result files written during that run. The runId may appear on the user interface, so it should be somewhat meaningful to the user. Nothing should be assumed about the particular format of runId, but it will be some string concatenated from the simulated network's name, the time/date, the hostname, and other pieces of data to make it unique.
A simulation run will typically write into two result files (.vec and .sca). However, when using parallel distributed simulation, the user will end up with several .vec and .sca files, because different partitions (a separate process each) will write into different files. However, all these files will contain the same runId, so it is possible to relate data that belong together.
Entry types are:
Specifies the format of the result file. It is written at the beginning of the file.
Syntax:
version versionNumber
The version described in this document is 2. Version 1 files are produced by OMNeT++ 3.3 or earlier.
Marks the beginning of a new run in the file. Entries after this line belong to this run.
Syntax:
run runId
Example:
run TokenRing1-0-20080514-18:19:44-3248
Typically there will be one run per file, but this is not mandatory. In cases when there are more than one run in a file and it is not feasible to keep the entire file in memory during analysis, the offsets of the run lines may be indexed for more efficient random access.
The run line may be immediately followed by attribute lines. Attributes may store generic data like the network name, date/time of running the simulation, configuration options that took effect for the simulation, etc.
Run attribute names used by OMNeT++ include the following:
Generic attribute names:
Attributes associated with parameter studies (iterated runs):
An example run header:
run TokenRing1-0-20080514-18:19:44-3248 attr configname TokenRing1 attr datetime 20080514-18:19:44 attr experiment TokenRing1 attr inifile omnetpp.ini attr iterationvars "" attr measurement "" attr network TokenRing attr processid 3248 attr repetition 0 attr replication #0 attr resultdir results attr runnumber 0 attr seedset 0
Contains an attribute for the preceding run, vector, scalar or statistics object. Attributes can be used for saving arbitrary extra information for objects; processors should ignore unrecognized attributes.
Syntax:
attr name value
Example:
attr network "largeNet"
Contains a module parameter value for the given run. This is needed so that module parameters may be included in the analysis (e.g. to identify the load for a “throughput vs load” plot).
It may not be practical to simply store all parameters of all modules in the result file, because there may be too many. We assume that NED files are invariant and do not store parameters defined in them. However, we store parameter assignments that come from omnetpp.ini, in their original wildcard form (i.e. not expanded) to conserve space. Parameter values entered interactively by the user are also stored.
When the original NED files are present, it should thus be possible to reconstruct all parameters for the given simulation.
Syntax:
param parameterNamePattern value
Example:
param **.gen.sendIaTime exponential(0.01) param **.gen.msgLength 10 param **.fifo.bitsPerSec 1000
Contains an output scalar value.
Syntax:
scalar moduleName scalarName value
Examples:
scalar "net.switchA.relay" "processed frames" 100
Scalar lines may be immediately followed by attribute lines. OMNeT++ uses the following attributes for scalars:
Defines an output vector.
Syntax:
vector vectorId moduleName vectorName
vector vectorId moduleName vectorName columnSpec
Where columnSpec is a string, encoding the meaning and ordering the columns of data lines. Characters of the string mean:
Common values are TV and ETV. The default value is TV.
Vector lines may be immediately followed by attribute lines. OMNeT++ uses the following attributes for vectors:
Adds a value to an output vector. This is the same as in older output vector files.
Syntax:
vectorId column1 column2 ...
Simulation times and event numbers within an output vector are required to be in increasing order.
Performance note: Data lines belonging to the same output vector may be written out in clusters (of size roughly a multiple of the disk's physical block size). Then, since an output vector file is typically not kept in memory during analysis, indexing the start offsets of these clusters allows one to read the file and seek in it more efficiently. This does not require any change or extension to the file format.
The first line of the index file stores the size and modification date of the vector file. If the attributes of a vector file differ from the information stored in the index file, then the IDE automatically rebuilds the index file.
Syntax:
file filesize modificationDate
Stores the location and statistics of blocks in the vector file.
Syntax:
vectorId offset length firstEventNo lastEventNo firstSimtime lastSimtime count min max sum sqrsum
where
Represents a statistics object.
Syntax:
statistic moduleName statisticName
Example:
statistic Aloha.server "collision multiplicity"
A statistic line may be followed by field and attribute lines, and a series of bin lines that represent histogram data.
OMNeT++ uses the following attributes:
A full example with fields, attributes and histogram bins:
statistic Aloha.server "collision multiplicity" field count 13908 field mean 6.8510209951107 field stddev 5.2385484477843 field sum 95284 field sqrsum 1034434 field min 2 field max 65 attr type int attr unit packets bin -INF 0 bin 0 0 bin 1 0 bin 2 2254 bin 3 2047 bin 4 1586 bin 5 1428 bin 6 1101 bin 7 952 bin 8 785 ... bin 52 2
Represents a field in a statistics object.
Syntax:
field fieldName value
Example:
field sum 95284
Fields:
For weighted statistics, additionally the following fields may be recorded:
Represents a bin in a histogram object.
Syntax:
bin binLowerBound value
Histogram name and module is defined on the statistic line, which is followed by several bin lines to contain data. Any non-bin line marks the end of the histogram data.
The binLowerBound column of bin lines represent the (inclusive) lower bound of the given histogram cell. Bin lines are in increasing binLowerBound order.
The value column of a bin line represents the observation count in the given cell: value k is the number of observations greater or equal to binLowerBound k, but smaller than binLowerBound k+1. Value is not necessarily an integer, because the cKSplit and cPSquare algorithms produce non-integer estimates. The first bin line is the underflow cell, and the last bin line is the overflow cell.
Example:
bin -INF 0 bin 0 4 bin 2 6 bin 4 2 bin 6 1
The database structure in SQLite result files is created with the following SQL statements. Scalar and vector files are identical in structure, they only differ in data.
CREATE TABLE run
(
runId INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
runName TEXT NOT NULL,
simtimeExp INTEGER NOT NULL
);
CREATE TABLE runattr
(
runId INTEGER NOT NULL REFERENCES run(runId) ON DELETE CASCADE,
attrName TEXT NOT NULL,
attrValue TEXT NOT NULL
);
CREATE TABLE runparam
(
runId INTEGER NOT NULL REFERENCES run(runId) ON DELETE CASCADE,
parName TEXT NOT NULL,
parValue TEXT NOT NULL
);
CREATE TABLE scalar
(
scalarId INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
runId INTEGER NOT NULL REFERENCES run(runId) ON DELETE CASCADE,
moduleName TEXT NOT NULL,
scalarName TEXT NOT NULL,
scalarValue REAL
);
CREATE TABLE scalarattr
(
scalarId INTEGER NOT NULL REFERENCES scalar(scalarId) ON DELETE CASCADE,
attrName TEXT NOT NULL,
attrValue TEXT NOT NULL
);
CREATE TABLE statistic
(
statId INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
runId INTEGER NOT NULL REFERENCES run(runId) ON DELETE CASCADE,
moduleName TEXT NOT NULL,
statName TEXT NOT NULL,
statCount INTEGER NOT NULL,
statMean REAL,
statStddev REAL,
statSum REAL,
statSqrsum REAL,
statMin REAL,
statMax REAL,
statWeights REAL,
statWeightedSum REAL,
statSqrSumWeights REAL,
statWeightedSqrSum REAL
);
CREATE TABLE histattr
(
statId INTEGER NOT NULL REFERENCES statistic(statId) ON DELETE CASCADE,
attrName TEXT NOT NULL,
attrValue TEXT NOT NULL
);
CREATE TABLE histbin
(
statId INTEGER NOT NULL REFERENCES statistic(statId) ON DELETE CASCADE,
baseValue NUMERIC NOT NULL,
cellValue INTEGER NOT NULL
);
CREATE TABLE vector
(
vectorId INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
runId INTEGER NOT NULL REFERENCES run(runId) ON DELETE CASCADE,
moduleName TEXT NOT NULL,
vectorName TEXT NOT NULL,
vectorCount INTEGER,
vectorMin REAL,
vectorMax REAL,
vectorSum REAL,
vectorSumSqr REAL,
startEventNum INTEGER,
endEventNum INTEGER,
startSimtimeRaw INTEGER,
endSimtimeRaw INTEGER
);
CREATE TABLE vectorattr
(
vectorId INTEGER NOT NULL REFERENCES vector(vectorId) ON DELETE CASCADE,
attrName TEXT NOT NULL,
attrValue TEXT NOT NULL
);
CREATE TABLE vectordata
(
vectorId INTEGER NOT NULL REFERENCES vector(vectorId) ON DELETE CASCADE,
eventNumber INTEGER NOT NULL,
simtimeRaw INTEGER NOT NULL,
value NUMERIC NOT NULL
);
Notes: