Interfacing with the toolbox

IMPORTANT

• The SUMO Toolbox works on any input domain (= design space = input parameter ranges) specified in the simulator configuration file by a 'minimum' and 'maximum' attribute.
  • If a 'minimum' is not specified, the default value of '-1' is assumed.
  • If a 'maximum' is not specified, the default value of '+1' is assumed.
  • Example:

	<InputParameters>
		<Parameter name="x" type="real" minimum="47.0" maximum="50.0"/>
		<Parameter name="y" type="real" minimum="-20.0"/>
	</InputParameters>

• Be aware that all input values that are not in the specified input domain are trimmed, and thus not used in the modeling process.

Also remember that:

• Complex output should always be returned as 2 real values (i.e., real and imaginary part separately).

So make sure your data source complies with these requirements, that is your responsibility.

Passing data directly

As mentioned on the Running page you can call the toolbox as follows:

     	"go('MyConfigFile.xml',xValues, yValues, [options])"

This allows you to pass your data directly to the toolbox. Remember though that the dimensions of your data must still match the information in MyConfigFile.xml.

Native Simulator

If your simulator is a native code or script it is expected to produce one output value per line. So every output should be on a new line, with complex outputs using two lines. There are 2 inputs methods supported for native simulators: batch mode and command line mode.

In command line mode (the default option), the inputs are given to the simulator as command line arguments. A call to a simulator in command line mode looks like:

>> ./someSimulationCode 0.5 0.6 0.5

In batch mode, multiple samples can be evaluated in batches. The simulation code is called with no command line arguments (except for optional options, see below). The inputs for a batch are instead given to the simulator on standard input (stdin). First, the size of the batch (the number of samples) is placed on stdin. Then, one line is written for each sample. this means that in total, 1 + (batchSize * inputDimension) numbers are written to stdin. An example of the format looks like:

3
0.5 0.6 0.5
0.2 0.7 0.3
0.2 0.6 0.8

The executable someSimulationCode must be in your path (easiest is just to place it in the M3-Toolbox/bin/c directory) or the absolute path to the executable must be specified in the Simulator xml file.

Options (if present) are passed the simulator as follows (only from version 4.2 and later):

>> ./someSimulationCode 0.5 0.6 0.5 option1=value1 option2=value2 etc..

Matlab Simulator

Matlab function

If your simulator is a Matlab file you just have to provide the following function to your code (for the same 3D example):

<code

function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3)
   ...
   % do the calculation

Then you just need to make sure the Matlab file is in the toolbox path (e.g., you can place it in src/matlab/examples).

Options (if present) are passed the simulator as an extra cell array parameter (only from version 4.2 and later):

function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3, options)

Where options is a cell array of strings of the form

options : {'option1','value1','option2','value2',...}

Matlab class

Your simulator can also be a Matlab object of a particular class. Provide your class with the following function:

function [output1 output2 output3] = evaluate(input1, input2 ,input3)
   ...
   % do the calculation

Options work in the same way as the pure Matlab simulator.

Java Simulator

You can also implement your simulator as a Java class. All you need to do is write a class that implements the Simulator interface. Options are passed as a java Properties object.

Scattered datasets

Each row should contain exactly one data point, with one column per dimension.