Running Simulations
9.2 Cmdenv: the command-line interface
The command line user interface is a small, portable and fast user interface that compiles and runs on all platforms. Cmdenv is designed primarily for batch execution.
Cmdenv simply executes some or all simulation runs that are described in the configuration file. If one run stops with an error message, subsequent ones will still be executed. The runs to be executed can be passed via command-line argument or in the ini file.
9.2.1 Example run
When run the Fifo example under Cmdenv, you should see something like this:
$ ./fifo -u Cmdenv -c Fifo1
OMNeT++ Discrete Event Simulation (C) 1992-2008 Andras Varga, OpenSim Ltd.
Version: 4.0, edition: Academic Public License -- NOT FOR COMMERCIAL USE See the license for distribution terms and warranty disclaimer
Setting up Cmdenv...
Loading NED files from .: 5
Preparing for running configuration Fifo1, run #0...
Scenario: $repetition=0
Assigned runID=Fifo1-0-20090104-12:23:25-5792 Setting up network ’FifoNet’...
Initializing...
Initializing module FifoNet, stage 0 Initializing module FifoNet.gen, stage 0 Initializing module FifoNet.fifo, stage 0 Initializing module FifoNet.sink, stage 0 Running simulation...
** Event #1 T=0 Elapsed: 0.000s (0m 00s) 0% completed Speed: ev/sec=0 simsec/sec=0 ev/simsec=0 Messages: created: 2 present: 2 in FES: 1
** Event #232448 T=11719.051014922336 Elapsed: 2.003s (0m 02s) 3% completed Speed: ev/sec=116050 simsec/sec=5850.75 ev/simsec=19.8351
Messages: created: 58114 present: 3 in FES: 2 ...
** Event #7206882 T=360000.52066583684 Elapsed: 78.282s (1m 18s) 100% completed Speed: ev/sec=118860 simsec/sec=5911.9 ev/simsec=20.1053
Messages: created: 1801723 present: 3 in FES: 2
<!> Simulation time limit reached -- simulation stopped.
Calling finish() at end of Run #0...
End.
As Cmdenv runs the simulation, periodically it prints the sequence number of the current event, the simulation time, the elapsed (real) time, and the performance of the simulation (how many events are processed per second; the first two values are 0 because there wasn’t enough data for it to calculate yet). At the end of the simulation, the finish() methods
OMNeT++ Manual – Running Simulations
of the simple modules are run, and the output from them are displayed. On my machine this run took 34 seconds. This Cmdenv output can be customized via omnetpp.ini entries.
The output file results/Fifo1-0.vec contains vector data recorded during simulation (here, queueing times), and it can be processed using the IDE or other tools.
9.2.2 Command-line switches
The command line environment allows you to specify more than one run by using the -r 2,4,6..8format. See 9.4 for more information about running simulation batches.
9.2.3 Cmdenv ini file options
cmdenv-runs-to-execute specifies which simulation runs should be executed. It accepts a comma-separated list of run numbers or run number ranges, e.g. 1,3..4,7..9. If the value is missing, Cmdenv executes all runs that have ini file sections; if no runs are specified in the ini file, Cmdenv does one run. The -r command line option overrides this ini file setting.
Cmdenv can be executed in two modes, selected by the cmdenv-express-mode ini file option:
• Normal (non-express) mode is for debugging: detailed information will be written to the standard output (event banners, module output, etc).
• Express mode can be used for long simulation runs: only periodical status update is displayed about the progress of the simulation.
cmdenv-performance-displayaffects express mode only: it controls whether to print perfor-mance information. Turning it on results in a 3-line entry printed on each update, containing ev/sec, simsec/sec, ev/simsec, number of messages created/still present/currently sched-uled in FES.
For a full list of options, see the ones beginning with cmdenv in Appendix G.
9.2.4 Interpreting Cmdenv output
When the simulation is running in “express” mode with detailed performance display enabled, Cmdenv periodically outputs a three-line status info about the progress of the simulation. The output looks like this:
...
** Event #250000 T=123.74354 ( 2m 3s) Elapsed: 0m 12s
Speed: ev/sec=19731.6 simsec/sec=9.80713 ev/simsec=2011.97 Messages: created: 55532 present: 6553 in FES: 8
** Event #300000 T=148.55496 ( 2m 28s) Elapsed: 0m 15s
Speed: ev/sec=19584.8 simsec/sec=9.64698 ev/simsec=2030.15 Messages: created: 66605 present: 7815 in FES: 7
...
The first line of the status display (beginning with **) contains:
• how many events have been processed so far
• the current simulation time (T), and
• the elapsed time (wall clock time) since the beginning of the simulation run.
The second line displays info about simulation performance:
• ev/sec indicates performance: how many events are processed in one real-time second.
On one hand it depends on your hardware (faster CPUs process more events per second), and on the other hand it depends on the complexity (amount of calculations) associated with processing one event. For example, protocol simulations tend to require more pro-cessing per event than e.g. queueing networks, thus the latter produce higher ev/sec values. In any case, this value is independent of the size (number of modules) in your model.
• simsec/sec shows relative speed of the simulation, that is, how fast the simulation is progressing compared to real time, how many simulated seconds can be done in one real second. This value virtually depends on everything: on the hardware, on the size of the simulation model, on the complexity of events, and the average simulation time between events as well.
• ev/simsec is the event density: how many events are there per simulated second. Event density only depends on the simulation model, regardless of the hardware used to simu-late it: in a cell-level ATM simulation you’ll have very hight values (109), while in a bank teller simulation this value is probably well under 1. It also depends on the size of your model: if you double the number of modules in your model, you can expect the event density double, too.
The third line displays the number of messages, and it is important because it may indicate the ‘health’ of your simulation.
• Created: total number of message objects created since the beginning of the simulation run. This does not mean that this many message object actually exist, because some (many) of them may have been deleted since then. It also does not mean that you created all those messages – the simulation kernel also creates messages for its own use (e.g. to implement wait() in an activity() simple module).
• Present: the number of message objects currently present in the simulation model, that is, the number of messages created (see above) minus the number of messages already deleted. This number includes the messages in the FES.
• In FES: the number of messages currently scheduled in the Future Event Set.
The second value, the number of messages present is more useful than perhaps one would initially think. It can be an indicator of the ‘health’ of the simulation: if it is growing steadily, then either you have a memory leak and losing messages (which indicates a programming error), or the network you simulate is overloaded and queues are steadily filling up (which might indicate wrong input parameters).
Of course, if the number of messages does not increase, it does not mean that you do not have a memory leak (other memory leaks are also possible). Nevertheless the value is still useful, because by far the most common way of leaking memory in a simulation is by not deleting messages.
OMNeT++ Manual – Running Simulations