Interfacing with the toolbox

For how to add an example to the toolbox see the Adding an example page.

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, for each input parameter.
  • 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="a" type="real" minimum="47.0" maximum="50.0"/>
    <Parameter name="b" 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 part and imaginary part separately).

Make sure your data source complies with these requirements. This is your responsibility.

Passing data directly

As mentioned on the Running page you pass your (input and corresponding output) data directly to the toolbox. Remember though that the dimensions of your data must still match the information in the toolbox configuration file used.

Scattered datasets

Your data source may also be a dataset containing some scattered data points. Scattered means the points do not have to be in any order, i.e., they may be distributed in any way (e.g., randomly). In this case your dataset must be stored in textual format and should contain exactly one data point per row with inputs and outputs separated by spaces.

For example, for a problem with 3 inputs and 2 outputs your text file looks like:

  -1.5743   -0.0328    0.2732   -0.6980   -0.8389
  -0.7347   -1.8929    0.2294   -0.9992   -1.5545
   0.7472    0.5474   -0.8233    0.9931    1.5339
   0.3766    0.8020   -0.0336    0.9758    1.4774
     ...       ...       ...       ...       ...
   0.8785    0.0362   -1.4864    0.8407    1.1173

So the first three columns are the input points, the last two are the outputs. Again, remember that a complex output should be stored as two columns (real and imaginary).

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 input 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 (for a problem with 3 input parameters):

>> ./someSimulationCode  0.5  0.6  0.5

The code should then produce one value per output per line.

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 <SUMO-Toolbox-installation-dir>/bin/c or the absolute path to the executable must be specified in the simulator configuration xml file.

If your xml file contains options, these will be passed to the simulator as command line arguments (both in single and batch mode). For example:

>> ./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):

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 to the simulator as an extra cell array parameter:

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',...}

Note: since Matlab is single threaded it is impossible to execute the simulator script while modeling (and vica versa). Thus the two are done sequentially which can lead to significant slowdowns if your simulator takes a long time to execute. In that case it is best to use a native executable or script. This will change in future versions when we start using the parallel/distributed computing toolbox.

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. And make sure the class file is in the Matlab Java path.

Options are passed as a java Properties object.

Gridded datasets

Gridded datasets assume that the data is spread uniformly over a grid. By making this assumption, there is no need to store the sample locations as in a scattered dataset: only the output values are stored. However, you must specify the 'gridSize' attribute in the Simulator configuration file. For example, setting 'gridSize="20,40,50"' means the toolbox will expect the gridded dataset to contain 40000 values per output (20-by-40-by-50 grid = 40000 points for one output).

Because the input values are not stored, the dataset must adhere to a strict order in which the output values are specified: the points must be specified in lexicographic order. For example, if you want to define a 3-dimensional dataset with grid size 2x3x2 on the [-1,1] domain, you must provide the outputs for the samples in the following order:

value at [-1, -1, -1]
value at [-1, -1,  1]
value at [-1,  0, -1]
value at [-1,  0,  1]
value at [-1,  1, -1]
value at [-1,  1,  1]
value at [ 1, -1, -1]
value at [ 1, -1,  1]
value at [ 1,  0, -1]
value at [ 1,  0,  1]
value at [ 1,  1, -1]
value at [ 1,  1,  1]

The advantage of gridded datasets is that they are a bit faster to work with. However, they are a bit harder to interpret and to transfer to other programs who expect a scattered format. In general we recommend to simply use the scattered format.