Difference between revisions of "Interfacing with the toolbox"

From SUMOwiki
Jump to navigationJump to search
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
For how to add an example to the toolbox see the [[Adding an example]] page.
+
For information how to model your own problem/data see the [[Adding an example]] page.
  
 
== IMPORTANT ==
 
== IMPORTANT ==
 +
 +
=== Input/Output Format ===
  
 
* The SUMO Toolbox works on any '''input domain''' (= design space = input parameter ranges) specified in the [[simulator configuration]] file by a '<code>minimum</code>' and '<code>maximum</code>' attribute, for each input parameter.
 
* The SUMO Toolbox works on any '''input domain''' (= design space = input parameter ranges) specified in the [[simulator configuration]] file by a '<code>minimum</code>' and '<code>maximum</code>' attribute, for each input parameter.
Line 18: Line 20:
  
 
Also remember that:
 
Also remember that:
* '''Complex output''' should always be returned as '''2 real values''' (i.e., real part and imaginary part separately).
+
* A '''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.
 
Make sure your data source complies with these requirements. This is your responsibility.
 +
 +
=== Batch Mode ===
 +
 +
By default the toolbox will call your simulation code or script with one point at a time.  However, sometimes this may not be efficient and you want to execute multiple simulations in one go.  This is referred to as '''Batch Mode'''.
 +
 +
If you want to use Batch mode you must add the ''batch'' and ''batchSize'' attributes to the <Executable> tag in your simulator file.  For example:
 +
 +
<source lang="xml">
 +
<Executable platform="matlab" batch="true" batchSize="9">/path/to/your/executable</Executable>
 +
</source>
 +
 +
This means that we want to use batch mode (batch = true) and we want to evaluate maximally 9 points per batch.
  
 
== Passing data directly ==
 
== Passing data directly ==
  
As mentioned on the [[Running]] page you pass your (input and corresponding output) data directly to the toolbox.  
+
It is possible to pass data directly to the toolbox.  For how to do this just type "help go".  
 
Remember though that the dimensions of your data must still match the information in the [[Toolbox configuration|toolbox configuration file]] used.
 
Remember though that the dimensions of your data must still match the information in the [[Toolbox configuration|toolbox configuration file]] used.
  
Line 40: Line 54:
 
     0.8785    0.0362  -1.4864    0.8407    1.1173
 
     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).
+
So the first three columns are the input points, the last two are the outputs.  The file may not contain any other comments or text. Again, remember that a complex output should be stored as two columns (real and imaginary).
  
 
== 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.  
+
If your simulator is a native binary (e.g., exe file) or shell 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.  Your code/script should NOT produce any other output.  
  
There are 2 '''input''' methods supported for native simulators: '''batch mode''' and '''command line mode'''.
+
There are two ways your code/script can be called by the SUMO-Toolbox: '''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):
 
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):
  
<code><pre>
+
<source lang="bash">
>> ./someSimulationCode 0.5  0.6  0.5
+
$ ./yourSimulationCode 0.5  0.6  0.5
</pre></code>
+
</source>
  
The code should then produce one value per output per line.
+
Your code/script should then produce one value per output per line (as discussed above).
  
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 (<code>stdin</code>). First, the size of the batch (the number of samples) is placed on <code>stdin</code>. Then, one line is written for each sample. this means that in total, <code>1 + (batchSize * inputDimension)</code> numbers are written to <code>stdin</code>. An example of the format looks like:
+
If your simulator is called with '''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 input points for a batch are instead passed to your simulation code/script through standard input (<code>stdin</code>). First, the size of the batch (the number of samples) is placed on <code>stdin</code>. Then, one line is written for each sample. this means that in total, <code>1 + (batchSize * inputDimension)</code> numbers are written to <code>stdin</code>. An example of the format looks like:
  
<code><pre>
+
<source lang="bash">
 
3
 
3
 
0.5  0.6  0.5
 
0.5  0.6  0.5
 
0.2  0.7  0.3
 
0.2  0.7  0.3
 
0.2  0.6  0.8
 
0.2  0.6  0.8
</pre></code>
+
</source>
  
The executable '<code>someSimulationCode</code>' must be in your path (easiest is just to place it in the <code><SUMO-Toolbox-installation-dir>/bin/c</code> or the absolute path to the executable must be specified in the [[simulator configuration]] xml file.
+
The executable '<code>yourSimulationCode</code>' must be in your path 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:
 
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:
<code><pre>
+
 
>> ./someSimulationCode 0.5  0.6  0.5  option1=value1  option2=value2  etc..
+
<source lang="bash">
</pre></code>
+
$ ./yourSimulationCode 0.5  0.6  0.5  option1=value1  option2=value2  etc..
 +
</source>
  
 
== Matlab simulator ==
 
== Matlab simulator ==
Line 76: Line 91:
 
=== 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):
+
If your simulator is a Matlab file and you are not using batch mode, you just have to provide the following function to your code (for the same 3D example):
  
<code><pre>
+
<source lang="matlab">
 
function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3)
 
function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3)
 
   ...
 
   ...
 
   % do the calculation
 
   % do the calculation
</pre></code>
+
</source>
  
Then you just need to make sure the Matlab file is in the toolbox path (e.g., you can place it in <code>src/matlab/examples</code>).
+
You can also pass inputs and outputs as a single matrices.  Then you just need to make sure the Matlab file is in your project directory (see [[Adding an example]]).
  
 +
Options (if present) are passed to the simulator as an extra cell array parameter:
  
Options (if present) are passed to the simulator as an extra cell array parameter:
 
  
<code><pre>
+
<source lang="matlab">
 
function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3, options)
 
function [output1 output2 output3] = mySimulationCode(input1, input2 ,input3, options)
</pre></code>
+
</source>
  
 
where '<code>options</code>' is a cell array of strings of the form:
 
where '<code>options</code>' is a cell array of strings of the form:
  
<code><pre>
+
<source lang="matlab">
 
options : {'option1','value1','option2','value2',...}
 
options : {'option1','value1','option2','value2',...}
</pre></code>
+
</source>
 +
 
 +
'''Note''': see also [[FAQ#Should_I_use_a_Matlab_script_or_a_shell_script_for_interfacing_with_my_simulation_code.3F]]
 +
 
 +
=== Batch Mode ===
  
'''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.
+
If you ARE using batch mode, then your function must look like this:
 +
 
 +
<source lang="matlab">
 +
function [result] = mySimulationCode(inputs)
 +
  ...
 +
  % do the calculation
 +
  ...
 +
  % IMPORTANT: you MUST return both inputs and output values
 +
  result = [inputs outputs];
 +
</source>
  
 
== Java simulator ==
 
== Java simulator ==

Latest revision as of 10:55, 6 March 2010

For information how to model your own problem/data see the Adding an example page.

IMPORTANT

Input/Output Format

  • 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:

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

Batch Mode

By default the toolbox will call your simulation code or script with one point at a time. However, sometimes this may not be efficient and you want to execute multiple simulations in one go. This is referred to as Batch Mode.

If you want to use Batch mode you must add the batch and batchSize attributes to the <Executable> tag in your simulator file. For example:

<Executable platform="matlab" batch="true" batchSize="9">/path/to/your/executable</Executable>

This means that we want to use batch mode (batch = true) and we want to evaluate maximally 9 points per batch.

Passing data directly

It is possible to pass data directly to the toolbox. For how to do this just type "help go". 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. The file may not contain any other comments or text. Again, remember that a complex output should be stored as two columns (real and imaginary).

Native simulator

If your simulator is a native binary (e.g., exe file) or shell 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. Your code/script should NOT produce any other output.

There are two ways your code/script can be called by the SUMO-Toolbox: 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):

$ ./yourSimulationCode  0.5  0.6  0.5

Your code/script should then produce one value per output per line (as discussed above).

If your simulator is called with 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 input points for a batch are instead passed to your simulation code/script through 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 'yourSimulationCode' must be in your path 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:

$ ./yourSimulationCode  0.5  0.6  0.5  option1=value1  option2=value2  etc..

Matlab simulator

Matlab function

If your simulator is a Matlab file and you are not using batch mode, 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

You can also pass inputs and outputs as a single matrices. Then you just need to make sure the Matlab file is in your project directory (see Adding an example).

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: see also FAQ#Should_I_use_a_Matlab_script_or_a_shell_script_for_interfacing_with_my_simulation_code.3F

Batch Mode

If you ARE using batch mode, then your function must look like this:

function [result] = mySimulationCode(inputs)
   ...
   % do the calculation
   ...
   % IMPORTANT: you MUST return both inputs and output values
   result = [inputs outputs];

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.