Interfacing with the toolbox - Revision history

Admin: /* Matlab simulator */

2010-03-06T09:55:16Z

Matlab simulator

← Older revision		Revision as of 09:55, 6 March 2010
Line 91:		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 your project directory (see [[Adding an example]]).		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]]		'''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:

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

Admin: /* IMPORTANT */

2010-03-06T09:49:56Z

IMPORTANT

← Older revision		Revision as of 09:49, 6 March 2010
Line 2:		Line 2:

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

Admin: /* IMPORTANT */

2010-03-06T09:49:30Z

IMPORTANT

← Older revision		Revision as of 09:49, 6 March 2010
Line 21:		Line 21:

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

Admin: /* Native simulator */

2010-03-06T09:43:55Z

Native simulator

← Older revision		Revision as of 09:43, 6 March 2010
Line 44:		Line 44:
	== 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 ==

Dgorissen: /* Matlab function */

2009-09-29T18:23:19Z

Matlab function

← Older revision		Revision as of 18:23, 29 September 2009
Line 84:		Line 84:
	</pre></code>		</pre></code>

	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>~~).		Then you just need to make sure the Matlab file is in your project directory (see [[Adding an example]]).

Dgorissen: /* Scattered datasets */

2009-09-29T18:22:15Z

Scattered datasets

← Older revision		Revision as of 18:22, 29 September 2009
Line 40:		Line 40:
	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 ==

Dgorissen: /* Passing data directly */

2009-09-29T18:21:20Z

Passing data directly

← Older revision		Revision as of 18:21, 29 September 2009
Line 24:		Line 24:
	== 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.

Dgorissen: /* IMPORTANT */

2009-09-29T18:20:31Z

IMPORTANT

← Older revision		Revision as of 18:20, 29 September 2009
Line 18:		Line 18:

	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.

Dgorissen at 18:19, 29 September 2009

2009-09-29T18:19:49Z

← Older revision		Revision as of 18:19, 29 September 2009
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 ==

Dgorissen: /* Matlab function */

2009-07-28T09:06:25Z

Matlab function

← Older revision		Revision as of 09:06, 28 July 2009
Line 99:		Line 99:
	</pre></code>		</pre></code>

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

	== Java simulator ==		== Java simulator ==