Difference between revisions of "Interfacing with the toolbox"

From SUMOwiki
Jump to navigationJump to search
Line 24: Line 24:
  
 
So make sure your data source complies with these contracts, that is your responsibility.
 
So make sure your data source complies with these contracts, that is your responsibility.
 +
  
 
== Passing data directly ==
 
== Passing data directly ==
 +
 
As mentioned on the [[Running]] page you can call the toolbox as follows:
 
As mentioned on the [[Running]] page you can call the toolbox as follows:
  
Line 33: Line 35:
  
 
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''.
 
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 ==
 
== 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.
 
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:
 
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:
  
<code>
+
<code><pre>
<pre>
 
 
>> ./someSimulationCode 0.5 0.6 0.5
 
>> ./someSimulationCode 0.5 0.6 0.5
</pre>
+
</pre></code>
</code>
 
  
 
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:
 
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:
Line 59: Line 61:
 
Options (if present) are passed the simulator as follows (only from version 4.2 and later):  
 
Options (if present) are passed the simulator as follows (only from version 4.2 and later):  
  
<code>
+
<code><pre>
<pre>
 
 
>> ./someSimulationCode 0.5 0.6 0.5 option1=value1 option2=value2 etc..
 
>> ./someSimulationCode 0.5 0.6 0.5 option1=value1 option2=value2 etc..
</pre>
+
</pre></code>
</code>
+
 
  
 
== Matlab Simulator ==
 
== Matlab Simulator ==
 +
 
=== Matlab function ===
 
=== 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>
+
If your simulator is a Matlab file you just have to provide the following function to your code (for the same 3D example):
<pre>
+
 
 +
<code<pre>
 
function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3)
 
function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3)
 
   ...
 
   ...
 
   % do the calculation
 
   % do the calculation
</pre>
+
</pre></code>
</code>
 
  
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).
+
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):  
 
Options (if present) are passed the simulator as an extra cell array parameter (only from version 4.2 and later):  
  
<code>
+
<code><pre>
<pre>
 
 
function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3, options)
 
function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3, options)
</pre>
+
</pre></code>
</code>
 
  
 
Where options is a cell array of strings of the form
 
Where options is a cell array of strings of the form
  
<code>
+
<code><pre>
<pre>
 
 
options : {'option1','value1','option2','value2',...}
 
options : {'option1','value1','option2','value2',...}
</pre>
+
</pre></code>
</code>
 
  
 
=== Matlab class ===
 
=== Matlab class ===
 +
 
Your simulator can also be a Matlab object of a particular class.  Provide your class with the following function:
 
Your simulator can also be a Matlab object of a particular class.  Provide your class with the following function:
  
<code>
+
<code><pre>
<pre>
 
 
function [output1 output2 output3] = evaluate(input1, input2 ,input3)
 
function [output1 output2 output3] = evaluate(input1, input2 ,input3)
 
   ...
 
   ...
 
   % do the calculation
 
   % do the calculation
</pre>
+
</pre></code>
</code>
 
  
 
Options work in the same way as the pure Matlab simulator.
 
Options work in the same way as the pure Matlab simulator.
  
 
== Java Simulator ==
 
== Java Simulator ==
 +
 
You can also implement your simulator as a [http://en.wikipedia.org/wiki/Java_%28programming_language%29 Java] class.  All you need to do is write a class that implements the ''Simulator'' interface.  Options are passed as a java Properties object.
 
You can also implement your simulator as a [http://en.wikipedia.org/wiki/Java_%28programming_language%29 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 ==
 
== Scattered datasets ==
Each row should contain exactly one datapoint, with one column per dimension.
+
 
 +
Each row should contain exactly one data point, with one column per dimension.
  
 
== Gridded datasets ==
 
== Gridded datasets ==

Revision as of 17:08, 10 June 2008

IMPORTANT

Version 4.2 and higher:

  • The toolbox works on any input domain (= design space) 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):

<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.

Gridded datasets