Working with RoadRunner Plugins

Introduction

The plugin API allows users to easily access roadrunner plugins. Only three concepts need to be understood:

1. Loading a plugin
2. Setting and Getting plugin properties
3. Executing the plugin

Before using the plugin system the plugin library must be imported using the line:

import teplugins as tel

To load a plugin called "tel_add_noise" use the Python command:

p = tel.Plugin ("tel_add_noise")

The variable p now represents the plugin. Plugins expose a number of properties, these are variables that can be inspected or set. For example the add noise plugin has a property called Sigma. To set this to a particular value we would use:

p.Sigma = 0.5

Likewise, properties can be inspected:

print p.Sigma

To list all propreties in a plugin use the method listOfProperties. The following uses call together with pprint to make the output more understandable:

import pprint
pprint.pprint (p.listOfProperties())
[['NoiseType', 'Type of noise (Gaussian = 0, Psychological = 1).'],
['Sigma', 'Standard deviation of applied noise'],
['InputData', 'Data Series to apply the noise to'],
['Progress', 'Indicate progress in (0-100%)']]

To run a plugin so that it carries out its function, use the execute method:

p.execute()

The results from an execute call will either be saved to a file or more likely via properties of the plugin. As a trivial example, consider a plugin called "add" that has three properties, x, y and z. When the execute() method is called the plugin will take the values stored in x and y, add them together and store the result in z. The following script illustrates how the plugin would be used from Python:

import teplugins as tel
p = tel.Plugin ("add")
p.x = 1.2
p.y = 4.5
p.execute()
print p.z

The following script illustrates a more substantial example using the add_noise plugin

import roadrunner
import teplugins as tel

noisePlugin = tel.Plugin ("tel_add_noise")

print noisePlugin.name()
print noisePlugin.hint()
print noisePlugin.description()

print '==== List of properties ===='
print noisePlugin.listOfProperties()

modelPlugin= tel.Plugin("tel_test_model")        
test_model = modelPlugin.Model

# Create a roadrunner instance
rr = roadrunner.RoadRunner()
rr.load(test_model)

# Generate data
data = rr.simulate(0, 10, 50) 

# The plugin will need a handle to the underlying roadrunner data
d = tel.getDataSeries (data)

noisePlugin.InputData = d

# Get parameter for the 'size' of the noise
noisePlugin.Sigma = 5.e-6

noisePlugin.InputData.plot()
noisePlugin.execute()

noisePlugin.InputData.plot()
tel.show()

print "done"

DataSeries

The plugin system supports a special data type called a Data Series. This is a convenient way to represent rows and colums of data. The data type also has the ability to label columns with a text string and to associate each value in the data series with an additional value called a weight. In practice the data series will usually store experimental data and the weights will represent a measure of undertaintly, perhaps a standard deviation, of the data point. A Data Series can be created using the call:

import teplugins as tel
data = tel.DataSeries()

Data can be entered into a data series either by loading the data from a specially formated file or from a Python NumPy array. For example:

data.readDataSeries ("mydata.txt")

To read numpy arrays into a data series use the code:

import numpy as py
values = py.array([[1,2],{2,5],[3,7]])
data = tel.DataSeries.fromNumPy (values)

The number of rows and columns in a Data Series can be obtained using:

print data.rows
print data.cols

Currently individual values in a data series can be accessed using the set and get methods:

p.setElement (1, 2, 4.567)
print p.getElement (1, 2)

Data series can be plotted using the plot method:

data.plot()

The following script is an example of using the add_noise plugin. This plugin takes a data series and add a given amount of Guassian noise to all data except the data in the first column.

import teplugins as *
p = Plugin ("tel_add_noise")
p.viewManual()
pl = p.listOfProperties()
for item in pl:
    print item

p.Sigma = 0.00005
series = DataSeries.loadDataSeries ("..\\Examples\\testData.dat")
series.plot()
p.InputData = series
p.execute()
p.InputData.plot()

print "Test Finished"

Plugins

Plugin objects are instanciated using Plugin class. For example to instanciate a plugin called myplugin, we would use the code:

p = Plugin ("myplugin")

All interactions with plugins are via plugin properties. Values can be set and retrieved via plugin properties. For example, if a plugin has a property sigma, we can assign or access the value using the code:

p.sigma = 0.1
print p.sigma

Plugins have a single method that can be used to excecute the plugin's functionality:

p.execute()

Once a plugin has been executed, any output from the plugin can be retrieved via properties. Let's suppose for example there is a plugin all add, which has three properties called, x, y and result. When executed the plugin will take the values in x and y, compute the sum and assign it to result. The plugin can therefore be used as follows:

p = Plugin("add")
p.x = 3.4
p.y = 5.6
p.execute()
print p.result