Interfacing with the toolbox

IMPORTANT

Version 4.2 and higher:

• The toolbox works on any input domain specified in the simulator configuration file by a minimum and maximum attribute.
  • If a minimum is not given, the default value of -1 is assumed. Equivalently, the default value for the maximum range is 1.
  • Example:

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

Version 4.1:

• The toolbox only works on the input domain [-1 1]
  • You must scale the inputs of your datasets to [-1 1]
  • You must wrap or edit your simulation code so that it scales the input points generated by the toolbox to the range required by your code.

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

Also remember that:

• Complex outputs should always be returned as 2 values (real and imaginary)

So make sure your data source complies with these contracts, 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):

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 datapoint, with one column per dimension.