History

OMF Main Page » OMF User Guide » BasicTutorials-5-2 »

This page and its sub-pages presents some information related to the previous OMF 5.2 release

Please visit the pages linked from the Main User Guide page for the documentation on the latest OMF version

How to pass parameters to your Experiment Description, and change them at run-time

1. Prerequisites

2. Goal

  • This tutorial shows you how to define and use Experiment Properties within your Experiment Description.
  • Experiment Properties allows you to:
    • assign values to these Properties, when starting your experiment execution, via the use of parameters on the "omf exec" command line
    • change values of these Properties, while your experiment is running

3. Scenario

  • We will modify this example, to allow us to:
    • parameterise some of the attributes of this experiment
    • assign values to these attributes
    • change these values at run-time (i.e. while the experiment is running)

4. The New "Hello World" Experiment Description

 1 defProperty('thesender', 1, "ID of sender node")
 2 defProperty('thereceiver', 2, "ID of receiver node")
 3 defProperty('packetsize', 256, "Packet size (byte) from the sender node")
 4 defProperty('bitrate', 2048, "Bitrate (bit/s) from the sender node")
 5 defProperty('runtime', 20, "Time in second for the experiment is to run")
 6 defProperty('netid', "helloworld", "The ESSID to use in this experiment")
 7 
 8 defGroup('Sender', [1,property.thesender]) {|node|
 9   node.addApplication("test:app:otg2") {|app|
10     app.setProperty('udp:local_host', "192.168.0"+property.thesender)
11     app.setProperty('udp:dst_host', "192.168.0."+property.thereceiver)
12     app.setProperty('udp:dst_port', 3000)
13     app.setProperty('cbr:rate', property.bitrate * 2)
14     app.setProperty('cbr:size', property.packetsize)
15     app.measure('udp_out', :samples => 3)
16   }
17   node.net.w0.mode = "adhoc" 
18   node.net.w0.type = 'g'
19   node.net.w0.channel = "6" 
20   node.net.w0.essid = property.netid
21   node.net.w0.ip = "192.168.0"+property.thesender
22 }
23 
24 defGroup('Receiver', [1,property.thereceiver]) {|node|
25   node.addApplication("test:app:otr2") {|app|
26     app.setProperty('udp:local_host', "192.168.0"+property.thereceiver)
27     app.setProperty('udp:local_port', 3000)
28     app.measure('udp_in', :samples => 3)
29   }
30   node.net.w0.mode = "adhoc" 
31   node.net.w0.type = 'g'
32   node.net.w0.channel = "6" 
33   node.net.w0.essid = property.netid
34   node.net.w0.ip = "192.168.0"+property.thereceiver
35 }
36 
37 whenAllInstalled() {|node|
38   wait 10
39   allGroups.startApplications
40   wait property.runtime / 2
41   property.packetsize = 512
42   wait property.runtime / 2
43   allGroups.stopApplications
44   Experiment.done
45 }
  • Line 1-6: we define the 6 Experiment Properties (i.e. parameters to the experiment), and assign default values and descriptions to them
    • More precisely:
      • Line 1: we define a property named "sender", which has a default integer value 1. This parameter represents the ID of the node to use as a sender in "Hello World".
      • Line 4: we define the "bitrate" property, which has a default integer value 2048. It represents the bitrate in bits/s which the sender will use to send traffic.
      • Line 6: we define the "netid" property, which as a default string value "helloworld".
      • etc...
  • Line 8-22: we use these Experiment Properties in our definition and configuration of the "Sender" group. These lines show you multiple examples on how to use Experiment Properties.
    • More precisely:
      • we use the syntax: property.name to access the value of the property called name (e.g. Line 8, or 20)
      • we use the same syntax to assign an Experiment Property to an application parameter (e.g. Line 14)
      • we use operations with Experiment Properties has arguments
        • Line 10: the addition of a property to a string returns this string concatenated with a string representation of that property.
        • Line 13: arithmetic operations involving a properties and an integer/float value are allowed, provided the property value is an integer or a float.
  • Line 24-35: same as above, with the "Receiver" group
  • Line 40-42: we dynamically change the value of some properties during the execution of the experiment.
    • More precisely:
      • Line 40: we let the experiment run for half of the time with the initial "packetsize" value.
      • Line 41: we change the value of the "packetsize" properties.
      • Line 42: we let the experiment run for the other half of the time with the new "packetsize" value.
  • How does it work?
    • when you assign an Experiment Property to an application parameters (e.g. Line 14), if later on you change the value of that property, a resulting string line is sent to the Standard-In input of that application.
    • for example: Line 41 will trigger the string line "cbr:size 512" to be written to the Standard-In input of the application otg2 used by the "Sender" group.
    • Note 1: Of course, the application (otg2 in this example) needs to be able to received and interprets strings on its Standard-In input, while it is running. This is trivial to implement in your own applications.
    • Note 2: This mechanism only works when you assign directly the Experiment Property as the application parameter as in Line 14! If you use an operation as part of this assignment, as it is the case in Line 13, then your application parameter will be assigned the resulting value of that operation. Thus you any change in the used Experiment Property will not result in a dynamic application parameter change. In the above example, calling "property.bitrate = 1024" between Lines 37-45 will not trigger a string to the written to the application's Standard-In input.
  • Important
    • There are a few reserved names that are used by the EC or Ruby, and which cannot be used to name Experiment Properties
    • A list of these names can be found on the reserved names and keywords list.

5. Running the experiment

5.1. How to run it

Please refer to the Basic "Hello World" tutorial and example and the Getting Started page if you do not know how to run an experiment with OMF.

Assuming you have the above Experiment Description saved in the file named "myExp.rb", the different command line alternatives to run this experiments are:

  • if you want to run the experiment with all the default values of Experiment Properties as defined in Line 1-6:
omf exec myExp.rb
  • if you want to run the experiment with the Experiment Properties value given on the command line:
omf exec myExp.rb -- --thesender 3 --packetsize 1024 --bitrate 1024

## or

omf exec myExp.rb -- --runtime 120 --thesender 4 --thereceiver 10 --netid anothernetwork 

## etc...

4.2. What you should see on the console:

  • Assuming you ran the above Experiment Description with the following command line:
omf exec tutorial1.rb -- --thesender 2 --thereceiver 3 --runtime 40
  • You should see an output similar to the following on the command line:
 1  INFO NodeHandler: init OMF Experiment Controller 5.2.302
 2  INFO NodeHandler: init Experiment ID: npc_2009_11_17_16_55_47
 3  INFO NodeHandler: Web interface available at: http://10.0.0.200:4000
 4  INFO Experiment: load system:exp:stdlib
 5  INFO property.resetDelay: value = 210 (Fixnum)
 6  INFO property.resetTries: value = 1 (Fixnum)
 7  INFO Experiment: load tutorial1.rb
 8  INFO property.thesender: value = 2 (Fixnum)
 9  INFO property.thereceiver: value = 3 (Fixnum)
10  INFO property.packetsize: value = 256 (Fixnum)
11  INFO property.bitrate: value = 2048 (Fixnum)
12  INFO property.runtime: value = 40 (Fixnum)
13  INFO property.netid: value = "helloworld" (String)
14  INFO whenAll: *: 'apps/app/status/@value' fires
15  INFO exp: Request from Experiment Script: Wait for 10s....
16  INFO n_1_3: Device 'net/w0' reported 06:0B:6B:84:3C:1B
17  INFO n_1_2: Device 'net/w0' reported 06:0B:6B:84:3C:1B
18  INFO exp: Request from Experiment Script: Wait for 20s....
19  INFO property.packetsize: value = 512 (Fixnum)
20  INFO exp: Request from Experiment Script: Wait for 20s....
21  INFO Experiment: DONE!
22  INFO run: Experiment npc_2009_11_17_16_55_47 finished after 1:11

6. The Results

Here is an an example of what you could do with the measurement from this experiment:

  • First, you should retrieve a dump of your measurement database from the experiment you just ran. Please refer to the detailed steps in the Basic "Hello World" tutorial and example if you do not know how to access your experiment result.
  • Assuming you have your measurement database in the file "myDatabase", you can run a query to get the timestamp and size of the UDP packets received on the "Receiver" side:
## Assuming you have sqlite3 installed
## Load "myDatabase" into sqlite3, run a query to get the field we are interested in, and save the result in a text file

sqlite3 -separator " " -init myDatabase db1 "select oml_ts_server,pkt_length from otr2_udp_in;" | sed '1d' >mySelection.txt

## You now have a file "mySelection.txt" which contains timestamps and packet sizes
  • Use Gnuplot to plot a graph of received packet size versus received time:
## Assuming you have gnuplot installed

gnuplot
gnuplot> set term postscript
gnuplot> set output "property_graph.eps" 
gnuplot> set xlabel "Time since experiment start (sec)" 
gnuplot> set ylabel "Received Packet Size (Bytes)" 
gnuplot> set xrange [0:41]
gnuplot> set yrange [0:600]
gnuplot> plot 'mySelection.txt' using 1:2 notitle with points
gnuplot> quit
  • You should then get a graph similar to this:

Please refer to the OML Documentation pages to learn more about the different standard tables and fields in any OML generated measurement database

7. What is Next?

Now that you have learnt how to use Experiment Properties, you can:

- either go back to refer to the Basic "Hello World" tutorial and example

- or continue reading the following basic OMF tutorials. Each one of them is introducing a new basic OMF feature, incrementally building on the simple "Hello World" example. You do not need to follow them in the order suggested below.

And finally, a "Conference Room" scenario which combines all of the above features:

This page and its sub-pages presents some information related to the previous OMF 5.2 release

Please visit the pages linked from the Main User Guide page for the documentation on the latest OMF version

property_graph.png (27.2 kB) Thierry Rakotoarivelo, 11/18/2009 11:48 am