History

How to pass parameters to your experiment and change them at run-time¶

1. Prerequisites¶

Make sure that you understand how OMF works from a user's point of view.
Make sure that you have completed and understood the basic "Hello World" tutorial.

2. Goal¶

This tutorial shows you how to define and use Experiment Properties within your experiment.

Experiment Properties allows you to:
- pass parameters to your experiment when it starts its execution, via the use of options to the omf-5.3 exec command line
- change values of these parameters dynamically, while your experiment is running

3. Scenario¶

Here we are using the same simple scenario as in the basic "Hello World" tutorial.

We will modify this example, to allow us to:
- define some of the attributes of this experiment as parameters, aka properties
- assign values to these properties
- change these values at runtime, i.e. while the experiment is running

4. The New "Hello World" Experiment Description¶

The Experiment Description (ED) describing this simple experiment is (download it here: dynamic-properties.rb):

 1 defProperty('theSender', 'omf.nicta.node1', "ID of sender node")
 2 defProperty('theReceiver', 'omf.nicta.node2', "ID of receiver node")
 3 defProperty('packetsize', 128, "Packet size (byte) from the sender node")
 4 defProperty('bitrate', 2048, "Bitrate (bit/s) from the sender node")
 5 defProperty('runtime', 40, "Time in second for the experiment is to run")
 6 defProperty('wifiType', "g", "The type of WIFI to use in this experiment")
 7 defProperty('channel', '6', "The WIFI channel to use in this experiment")
 8 defProperty('netid', "example2", "The ESSID to use in this experiment")
 9 
10 defGroup('Sender',property.theSender) do |node|
11   node.addApplication("test:app:otg2") do |app|
12     app.setProperty('udp:local_host', '192.168.0.2')
13     app.setProperty('udp:dst_host', '192.168.0.3')
14     app.setProperty('udp:dst_port', 3000)
15     app.setProperty('cbr:size', property.packetsize)
16     app.setProperty('cbr:rate', property.bitrate * 2)
17     app.measure('udp_out', :samples => 1)
18   end
19   node.net.w0.mode = "adhoc" 
20   node.net.w0.type = property.wifiType
21   node.net.w0.channel = property.channel
22   node.net.w0.essid = "foo"+property.netid
23   node.net.w0.ip = "192.168.0.2" 
24 end
25 
26 defGroup('Receiver',property.theReceiver) do |node|
27   node.addApplication("test:app:otr2") do |app|
28     app.setProperty('udp:local_host', '192.168.0.3')
29     app.setProperty('udp:local_port', 3000)
30     app.measure('udp_in', :samples => 1)
31   end
32   node.net.w0.mode = "adhoc" 
33   node.net.w0.type = property.wifiType
34   node.net.w0.channel = property.channel
35   node.net.w0.essid = "foo"+property.netid
36   node.net.w0.ip = "192.168.0.3" 
37 end
38 
39 onEvent(:ALL_UP_AND_INSTALLED) do |event|
40   info "This is my first OMF experiment" 
41   wait 10
42   allGroups.startApplications
43   info "All my Applications are started now..." 
44   wait property.runtime / 4
45   property.packetsize = 256
46   wait property.runtime / 4
47   property.packetsize = 512
48   wait property.runtime / 4
49   property.packetsize = 1024
50   wait property.runtime / 4
51   allGroups.stopApplications
52   info "All my Applications are stopped now." 
53   Experiment.done
54 end

This ED is available for download here: dynamic-properties.rb

Line 1-8: define 8 Experiment Properties, i.e. parameters to the experiment, and set their default values and descriptions
- Line 1: defines a property named theSender, which has a default value omf.nicta.node1. This parameter represents the ID of the node to use as a sender in "Hello World".
- Line 3: defines the packetsize property, which has a default integer value 128. It represents the packet size in bytes which the sender in "Hello World" will use to generates its UDP traffic.
- Line 7: we define the channel property, which as a default string value 6, i.e. the 802.11 channel to use in "Hello World"
- etc...

Line 10-24: 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. For example:
- we use the syntax: property.name to access the value of the property called name (e.g. Line 10 or 20)
- we use the same syntax to assign an Experiment Property to an application parameter (e.g. Line 15)
- we use operations with Experiment Properties as arguments
  - Line 22: the addition of a property to a string returns this string concatenated with the string representation of that property.
  - Line 16: arithmetic operations involving a properties and an integer/float are allowed (only if the property value is an integer/float).

Line 39-54: we dynamically change the value of the packetsize property during the execution of the experiment.
- Line 44: we let the experiment run for a quarter of the time with the initial "packetsize" value
- Line 45: we change the value of the "packetsize" property
- Line 46: we let the experiment run for another quarter of the time
- etc...

How does the dynamic update of a property work?
- First you assign an Experiment Property to an application parameters (line 15)
- Later, when you change the value of that property (line 45), a string line is sent to the Standard-In input of that application
- Here for example, line 45 triggers the string line "cbr:size 256" to be written to the Standard-In input of the application otg2 used by the "Sender" group
- Prerequisites for this to work:
  - Your application (otg2 in this example) needs to be able to received and interprets strings on its Standard-In input, while it is running. This should be easy to implement in your own applications.
  - This mechanism only works when you assign directly the Experiment Property as the application parameter as in Line 15!
  - If you use an operation as part of this assignment (e.g.line 16), then your application parameter will be assigned the resulting value of that operation. Thus, any change in the used Experiment Property will not result in a dynamic application parameter change
    - for example, calling property.bitrate = 1024 in the tasks declaration (line 39-54) will not result in the dynamic update of the application's bitrate parameter.

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.

Finally... Please refer to the basic "Hello World" tutorial if you do not understand the remaining lines of the above ED.

5. Running the experiment¶

5.1. How to run it¶

Please refer to the basic "Hello World" tutorial and the Getting Started page to find out how to run an experiment with OMF. Here we assume that you have the above ED saved in the file named dynamic-properties.rb.

if you want to run the experiment using the default values for all the properties (as defined in line 1-8):
```
omf-5.3 exec dynamic-properties.rb
```

if you want to pass your own initial values to some of the experiment's properties via the command line:

omf-5.3 exec dynamic_properties.rb -- --theSender omf.nicta.node36 --theReceiver omf.nicta.node37

# OR

omf-5.3 exec dynamic_properties.rb -- --runtime 80 --bitrate 1024

# ETC...

5.2. What you should see on the console:¶

You should see an output similar to the following:

 1 
 2 INFO NodeHandler: OMF Experiment Controller 5.3.642 
 3 INFO NodeHandler: Slice ID: testing_slice (default) 
 4 INFO NodeHandler: Experiment ID: testing_slice-2010-09-08t15.23.50+10.00 
 5 INFO NodeHandler: Message authentication is disabled 
 6 
 7 INFO NodeHandler: Web interface available at: http://10.0.0.200:4000 
 8 INFO Experiment: load system:exp:stdlib 
 9 INFO property.resetDelay: value = 210 (Fixnum) 
10 INFO property.resetTries: value = 1 (Fixnum) 
11 INFO Experiment: load system:exp:eventlib 
12 INFO Experiment: load dynamic_properties.rb 
13 INFO property.theSender: value = "omf.nicta.node36" (String) 
14 INFO property.theReceiver: value = "omf.nicta.node37" (String) 
15 INFO property.packetsize: value = 128 (Fixnum) 
16 INFO property.bitrate: value = 2048 (Fixnum) 
17 INFO property.runtime: value = 40 (Fixnum) 
18 INFO property.wifiType: value = "g" (String) 
19 INFO property.channel: value = "6" (String) 
20 INFO property.netid: value = "example2" (String) 
21 INFO Topology: Loading topology 'omf.nicta.node36'. 
22 INFO Topology: Loading topology 'omf.nicta.node37'. 
23 INFO stdlib: Waiting for nodes (Up/Down/Total): 1/1/2 - (still down: omf.nicta.node37) 
24 INFO omf.nicta.node36: Device 'net/w0' reported 06:0B:6B:84:3C:23 
25 INFO ALL_UP_AND_INSTALLED: Event triggered. Starting the associated tasks. 
26 INFO exp: This is my first OMF experiment 
27 INFO exp: Request from Experiment Script: Wait for 10s.... 
28 INFO omf.nicta.node37: Device 'net/w0' reported 06:0B:6B:84:3D:0F 
29 INFO omf.nicta.node36: Device 'net/w0' reported 06:0B:6B:84:3D:0F 
30 INFO exp: All my Applications are started now... 
31 INFO exp: Request from Experiment Script: Wait for 10s.... 
32 INFO property.packetsize: value = 256 (Fixnum) 
33 INFO exp: Request from Experiment Script: Wait for 10s.... 
34 INFO property.packetsize: value = 512 (Fixnum) 
35 INFO exp: Request from Experiment Script: Wait for 10s.... 
36 INFO property.packetsize: value = 1024 (Fixnum) 
37 INFO exp: Request from Experiment Script: Wait for 10s.... 
38 INFO exp: All my Applications are stopped now. 
39 INFO EXPERIMENT_DONE: Event triggered. Starting the associated tasks. 
40 INFO NodeHandler: 
41 INFO NodeHandler: Shutting down experiment, please wait... 
42 INFO NodeHandler: 
43 INFO run: Experiment testing_slice-2010-09-08t15.23.50+10.00 finished after 1:16

6. The Results¶

Please refer to the "Hello World" tutorial to find out how to access and use your result database
- you can download an example of a database produced by this experiment here: myDatabase

Following the same example as in the "Hello World" tutorial, here we extend our Experiment Description to request the plotting of a graph on the EC's webpage during the runtime of our experiment

To do that, we had the following lines to our ED (download the extended ED here: attachment dynamic-properties-graph.rb):

 1 
 2 addTab(:defaults) 
 3 addTab(:graph2) do |tab| 
 4 opts = { :postfix => %{This graph shows the Packet Size of the incoming UDP traffic (byte).}, :updateEvery => 1 } 
 5 tab.addGraph("Incoming UDP Packet Size", opts) do |g| 
 6 dataIn = Array.new 
 7 mpIn = ms('udp_in') 
 8 mpIn.project(:oml_ts_server, :pkt_length).each do |sample| 
 9 dataIn << sample.tuple 
10 end 
11 g.addLine(dataIn, :label => "Incoming UDP (byte)") 
12 end 
13 end

The Another tutorial provides a full description on How to define graphs to plot during your experiment's runtime.

Please refer to the "Hello World" tutorial to find out how to access the EC's webpage during your experiment visualisation widget runtime

While this extended experiment is running, the EC's web page should look display a front page similar to this:
- Note the dashboard showing the values of the experiment properties that we defined

If you click on the Graph tab, you should see a graph similar to this:

On this graph, we can see the packet size of the incoming UDP traffic increasing in steps every 10 sec during our 40-sec experiment.

7. What is Next?¶

Now that you know how to use Experiment Properties, you may want to read the following basic OMF tutorials. Each one of them is introducing an OMF feature, using the simple "Hello World" experiment as a base. You do not need to follow them in the order suggested below.