Adding an example - Revision history

Dgorissen at 22:04, 2 September 2009

2009-09-02T22:04:02Z

← Older revision		Revision as of 22:04, 2 September 2009
Line 1:		Line 1:
	This page explains how to add your own data/simulation code/... to the toolbox to model it.		This page explains how to add your own data/simulation code/... to the toolbox in order to model it.

	== Project directories ==		== Project directories ==

	The SUMO Toolbox comes with a large number of example problems and datasets which you can use for testing, benchmarking, or simply to get a feel of what is possible. These problems cover a very large range of domains, from Biology to Geography and Electronics.		The SUMO Toolbox comes with a large number of example problems and datasets which you can use for testing, benchmarking, or simply to get a feel of what is possible. These problems cover a very large range of domains, from Biology to Geography and Electronics. If you simply want to play around and try different examples please refer to [[Running#Running_different_examples]].

	~~Since version 6.0 every example (and all~~ related ~~files) is self contained~~ in a project directory. ~~See~~ <code>examples/</code> ~~for a list~~ of ~~examples and associated project directories~~.		All the files related to one problem are placed together in a directory. We call this the project directory for that problem. Many examples of project directories can be found in the <code>examples/</code> subdirectory of your SUMO-Toolbox installation. If you open one of those directories you will see they contain the following things:
	If you open one of those directories you will see they contain the following things:

	# A simulator xml file with the same name as the project directory (~~mandatory~~)		# A simulator xml file with the same name as the project directory. This file is mandatory (though there are some small exceptions)
	# One or more executables: matlab script, C++ file, binary, ... (optional)		# One or more executables: matlab script, C++ file, binary, ... (optional)
	# One or more data files (optional)		# One or more data files (optional)
Line 14:		Line 13:
	# Other files, e.g., a documenting pdf (optional)		# Other files, e.g., a documenting pdf (optional)

	~~You can structure~~ the ~~directory as~~ you ~~please but make~~ sure ~~it contains at least the simulator xml and a dataset or executable~~.		Open up a couple of the example project directories and have a look inside so you are sure whats going on.

	== ~~Simulator file~~ ==		== Modeling your own problem ==

	If you want to ~~create a surrogate~~ model ~~(metamodel) for~~ your own problem you ~~will first~~ have to ~~write~~ a ~~simple [[simulator]] [[FAQ#What is XML\|XML]] file~~. ~~You can~~ use ~~one of~~ the ~~existing simulator XML files (from one of~~ the examples~~) as a guide~~. ~~The simulator xml~~ file ~~should have the same name and capitalization as the project directory (except for the~~ .xml ~~extension).~~		If you want to model your own problem, this means you have to create a new project directory and give it a name. For ease of use we suggest to create it in the examples/ subdirectory. For example, if your problem is called ''Foobar'' create the directory ''examples/Foobar''. Inside this directory you must place: a file called ''Foobar.xml'', this is the [[simulator configuration]] file. See the [[simulator configuration]] page for information how to write such a file.
	~~You can then edit~~ this file ~~to suit your particular problem (see also~~ [[~~Simulator~~ configuration]]).

	~~Then just~~ place any datasets, Matlab scripts, ... into ~~that~~ directory. ~~For requirements on~~ the ~~structure of the dataset~~ or ~~signature of~~ the ~~executable/script please see [[Interfacing with the toolbox]]~~.		Once you have this file you simply place place any datasets, Matlab scripts, ... into your project directory. If you specified the correct path in your simulator configuration file then SUMO will find them. Paths can be absolute or relative to the project directory. If no file extension is present, '.txt' is assumed.

	Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your problem (<Simulator> tag). For information on this see [[Running#Running different examples]].		Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your problem (<Simulator> tag). For information on this see [[Running#Running different examples]].

Dgorissen at 14:41, 10 June 2009

2009-06-10T14:41:57Z

← Older revision		Revision as of 14:41, 10 June 2009
Line 22:		Line 22:

	Then just place any datasets, Matlab scripts, ... into that directory. For requirements on the structure of the dataset or signature of the executable/script please see [[Interfacing with the toolbox]].		Then just place any datasets, Matlab scripts, ... into that directory. For requirements on the structure of the dataset or signature of the executable/script please see [[Interfacing with the toolbox]].

	~~For an explanation of the data format and how the toolbox interfaces with the [[simulator]], see the [[Interfacing with the toolbox]] page.~~

	Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your problem (<Simulator> tag). For information on this see [[Running#Running different examples]].		Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your problem (<Simulator> tag). For information on this see [[Running#Running different examples]].

Dgorissen at 14:39, 10 June 2009

2009-06-10T14:39:52Z

← Older revision		Revision as of 14:39, 10 June 2009
Line 3:		Line 3:
	== Project directories ==		== Project directories ==

	~~Since version 6.0 every~~ example (and ~~all related files) is self contained in a project directory. See <code>examples/</code>~~ for a ~~list~~ of ~~examples and associated project directories~~. ~~You can use one~~ of ~~them as an example for how~~ to ~~add your own~~.		The SUMO Toolbox comes with a large number of example problems and datasets which you can use for testing, benchmarking, or simply to get a feel of what is possible. These problems cover a very large range of domains, from Biology to Geography and Electronics.

	~~== Simulator~~ file ==		Since version 6.0 every example (and all related files) is self contained in a project directory. See <code>examples/</code> for a list of examples and associated project directories.
			If you open one of those directories you will see they contain the following things:

			# A simulator xml file with the same name as the project directory (mandatory)
			# One or more executables: matlab script, C++ file, binary, ... (optional)
			# One or more data files (optional)
			# Alternative simulator xml files (optional)
			# Other files, e.g., a documenting pdf (optional)

	~~If you want to create a surrogate model (metamodel) for your own problem~~ you ~~will first have to write a [[simulator]] xml file. Again, use one of~~ the ~~exsiting~~ simulator xml ~~files (from on of the examples) as~~ a ~~guide. The simulator xml file should have the same name and capitalization as the project directory (except for the .xml extension). Also see the [[Simulator configuration]] page~~.		You can structure the directory as you please but make sure it contains at least the simulator xml and a dataset or executable.

	~~You can then edit this~~ file ~~to suit your particular problem. This file should be pretty straightforward to write.~~		== Simulator file ==

	~~'''For versions < 6~~.~~0:'''~~		If you want to create a surrogate model (metamodel) for your own problem you will first have to write a simple [[simulator]] [[FAQ#What is XML\|XML]] file. You can use one of the existing simulator XML files (from one of the examples) as a guide. The simulator xml file should have the same name and capitalization as the project directory (except for the .xml extension).
	~~Datasets~~ should ~~be placed in <code>examples/data/txt</code>~~.		You can then edit this file to suit your particular problem (see also [[Simulator configuration]]).
	~~In case of doubt about which dataset~~ to ~~use, use 'ScatteredDataFile'.~~
	~~Matlab scripts should be placed in <code>src/matlab/examples</code>~~.

	~~'''For version 6.0:'''~~		Then just place any datasets, Matlab scripts, ... into that directory. For requirements on the structure of the dataset or signature of the executable/script please see [[Interfacing with the toolbox]].
	~~You can~~ just ~~copy the Datasets~~, ~~matlab~~ scripts, ~~extra files in~~ the ~~project directory you created in~~ the ~~steps above~~.

	For an explanation of the data format and how the toolbox interfaces with the [[simulator]], see the [[Interfacing with the toolbox]] page.		For an explanation of the data format and how the toolbox interfaces with the [[simulator]], see the [[Interfacing with the toolbox]] page.

	Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your problem (<Simulator> tag). Finally you just run '<code>go</code>'. In version 5.0 of the toolbox you would just use the name of the simulator configuration file, for version 6.0 you must specify the project directory name (can be an absolute path or a directory name inside the toolbox path).		Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your problem (<Simulator> tag). For information on this see [[Running#Running different examples]].

	Note that, depending on whether your simulator is a script, native executable, dataset or Matlab script you will need to set different [[Config:SampleEvaluator\| sample evaluator]] configuration options. For example, if your data comes from a dataset you will have to set the sample evaluator to [[Config:SampleEvaluator#scattered\| scattered]] or [[Config:SampleEvaluator#gridded\| gridded]], depending if you data points are scattered or on a regular grid.
	If on ~~the other hand your data comes from a native executable you would want to use the~~ [[~~Config:SampleEvaluator~~#local\| local]] sample evaluator with the simulatorType set to "external" (you can also set the type to "java" if your executable is a java class). For Matlab scripts the sample evaluator to use is [[Config:SampleEvaluator#matlab\| matlab]].

Dgorissen: /* Simulator file */

2008-07-25T12:58:37Z

Simulator file

← Older revision		Revision as of 12:58, 25 July 2008
Line 7:		Line 7:
	== Simulator file ==		== Simulator file ==

	If you want to create a surrogate model (metamodel) for your own problem you will first have to write a [[simulator]] xml file. Again, use one of the exsiting simulator xml files (from on of the examples) as a guide. The simulator xml file should have the same name and capitalization as the project directory (except for the .xml extension). ~~(also~~ see the [[Simulator configuration]] page.		If you want to create a surrogate model (metamodel) for your own problem you will first have to write a [[simulator]] xml file. Again, use one of the exsiting simulator xml files (from on of the examples) as a guide. The simulator xml file should have the same name and capitalization as the project directory (except for the .xml extension). Also see the [[Simulator configuration]] page.

	You can then edit this file to suit your particular problem. This file should be pretty straightforward to write.		You can then edit this file to suit your particular problem. This file should be pretty straightforward to write.

Dgorissen at 12:54, 25 July 2008

2008-07-25T12:54:33Z

← Older revision		Revision as of 12:54, 25 July 2008
Line 1:		Line 1:
			This page explains how to add your own data/simulation code/... to the toolbox to model it.

			== Project directories ==

			Since version 6.0 every example (and all related files) is self contained in a project directory. See <code>examples/</code> for a list of examples and associated project directories. You can use one of them as an example for how to add your own.

	== Simulator file ==		== Simulator file ==

	If you want to create a surrogate model (metamodel) for your own problem you will first have to write a [[simulator]] xml file.~~To do this simply open~~ one of the ~~existing~~ simulator xml files (~~in the <code>examples/</code> subdirectory) and create a copy~~ of ~~it in~~ the ~~same directory but under a new name.~~		If you want to create a surrogate model (metamodel) for your own problem you will first have to write a [[simulator]] xml file. Again, use one of the exsiting simulator xml files (from on of the examples) as a guide. The simulator xml file should have the same name and capitalization as the project directory (except for the .xml extension). (also see the [[Simulator configuration]] page.
	~~Note, since version 6.0 each simulator resides in its own project directory in <code>~~examples~~/</code>. To create a new simulator you can copy one of the existing project directories (e.g. Academic2D~~) ~~in the same directory but under~~ a ~~new name~~. ~~Make sure the~~ simulator ~~configuration inside the project directory has~~ the same name as the project directory ~~itself~~ (except for the .xml extension).

	You can then edit this file to suit your particular problem. This file should be pretty straightforward to write.		You can then edit this file to suit your particular problem. This file should be pretty straightforward to write.
	~~Your simulator XML file may specify different implementations:~~
	* an executable or script (<Executable> tag)
	* a Java class (<Executable> tag, platform = java)
	* a Matlab script (<Executable> tag, platform = matlab)
	* a dataset
	** scattered data (<ScatteredDataFile> tag)
	** gridded data, data lies on a regular grid (<GriddedDataFile>)

	'''For versions < 6.0:'''		'''For versions < 6.0:'''
	Datasets should be placed in <code>examples/data/txt</code>.		Datasets should be placed in <code>examples/data/txt</code>.
	In case of doubt about which dataset to use, use 'ScatteredDataFile'.		In case of doubt about which dataset to use, use 'ScatteredDataFile'.

	Matlab scripts should be placed in <code>src/matlab/examples</code>.		Matlab scripts should be placed in <code>src/matlab/examples</code>.

Line 24:		Line 21:
	For an explanation of the data format and how the toolbox interfaces with the [[simulator]], see the [[Interfacing with the toolbox]] page.		For an explanation of the data format and how the toolbox interfaces with the [[simulator]], see the [[Interfacing with the toolbox]] page.

	Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your ~~file~~ (<Simulator> tag). Finally you just run '<code>go</code>'.		Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your problem (<Simulator> tag). Finally you just run '<code>go</code>'. In version 5.0 of the toolbox you would just use the name of the simulator configuration file, for version 6.0 you must specify the project directory name (can be an absolute path or a directory name inside the toolbox path).
	In version 5.0 of the toolbox you would just use the name of the simulator configuration file, for version 6.0 you must specify the project directory.

	Note that, depending on whether your simulator is a script, native executable, dataset or Matlab script you will need to set different [[Config:SampleEvaluator\| sample evaluator]] configuration options. For example, if your data comes from a dataset you will have to set the sample evaluator to [[Config:SampleEvaluator#scattered\| scattered]] or [[Config:SampleEvaluator#gridded\| gridded]], depending if you data points are scattered or on a regular grid.		Note that, depending on whether your simulator is a script, native executable, dataset or Matlab script you will need to set different [[Config:SampleEvaluator\| sample evaluator]] configuration options. For example, if your data comes from a dataset you will have to set the sample evaluator to [[Config:SampleEvaluator#scattered\| scattered]] or [[Config:SampleEvaluator#gridded\| gridded]], depending if you data points are scattered or on a regular grid.
	If on the other hand your data comes from a native executable you would want to use the [[Config:SampleEvaluator#local\| local]] sample evaluator with the simulatorType set to "external" (you can also set the type to "java" if your executable is a java class). For Matlab scripts the sample evaluator to use is [[Config:SampleEvaluator#matlab\| matlab]].		If on the other hand your data comes from a native executable you would want to use the [[Config:SampleEvaluator#local\| local]] sample evaluator with the simulatorType set to "external" (you can also set the type to "java" if your executable is a java class). For Matlab scripts the sample evaluator to use is [[Config:SampleEvaluator#matlab\| matlab]].

Icouckuy at 14:25, 17 July 2008

2008-07-17T14:25:01Z

← Older revision		Revision as of 14:25, 17 July 2008
Line 13:		Line 13:
	** gridded data, data lies on a regular grid (<GriddedDataFile>)		** gridded data, data lies on a regular grid (<GriddedDataFile>)

	For versions < 6.0:		'''For versions < 6.0:'''
	Datasets should be placed in <code>examples/data/txt</code>.		Datasets should be placed in <code>examples/data/txt</code>.
	In case of doubt about which dataset to use, use 'ScatteredDataFile'.		In case of doubt about which dataset to use, use 'ScatteredDataFile'.
Line 19:		Line 19:
	Matlab scripts should be placed in <code>src/matlab/examples</code>.		Matlab scripts should be placed in <code>src/matlab/examples</code>.

	For version 6.0:		'''For version 6.0:'''
	You can just copy the Datasets, matlab scripts, extra files in the project directory you created in the steps above.		You can just copy the Datasets, matlab scripts, extra files in the project directory you created in the steps above.

Icouckuy at 14:24, 17 July 2008

2008-07-17T14:24:31Z

← Older revision		Revision as of 14:24, 17 July 2008
Line 1:		Line 1:
	~~If you want to create a surrogate model (metamodel) for your own problem you will first have to write a [[simulator]] xml~~ file. To do this simply open one of the existing simulator xml files (in the <code>examples/</code> subdirectory) and create a copy of it in the same directory but under a new name. You can then edit this file to suit your particular problem. This file should be pretty straightforward to write.		== Simulator file ==

			If you want to create a surrogate model (metamodel) for your own problem you will first have to write a [[simulator]] xml file.To do this simply open one of the existing simulator xml files (in the <code>examples/</code> subdirectory) and create a copy of it in the same directory but under a new name.
			Note, since version 6.0 each simulator resides in its own project directory in <code>examples/</code>. To create a new simulator you can copy one of the existing project directories (e.g. Academic2D) in the same directory but under a new name. Make sure the simulator configuration inside the project directory has the same name as the project directory itself (except for the .xml extension).

			You can then edit this file to suit your particular problem. This file should be pretty straightforward to write.
	Your simulator XML file may specify different implementations:		Your simulator XML file may specify different implementations:
	* an executable or script (<Executable> tag)		* an executable or script (<Executable> tag)
Line 9:		Line 13:
	** gridded data, data lies on a regular grid (<GriddedDataFile>)		** gridded data, data lies on a regular grid (<GriddedDataFile>)

			For versions < 6.0:
	Datasets should be placed in <code>examples/data/txt</code>.		Datasets should be placed in <code>examples/data/txt</code>.
	In case of doubt about which dataset to use, use 'ScatteredDataFile'.		In case of doubt about which dataset to use, use 'ScatteredDataFile'.

	Matlab scripts should be placed in <code>src/matlab/examples</code>.		Matlab scripts should be placed in <code>src/matlab/examples</code>.

			For version 6.0:
			You can just copy the Datasets, matlab scripts, extra files in the project directory you created in the steps above.

	For an explanation of the data format and how the toolbox interfaces with the [[simulator]], see the [[Interfacing with the toolbox]] page.		For an explanation of the data format and how the toolbox interfaces with the [[simulator]], see the [[Interfacing with the toolbox]] page.

	Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your file (<Simulator> tag). Finally you just run '<code>go</code>'.		Having written your simulator XML file and provided the datasets/executables you now just need to change <code>default.xml</code> so it uses your file (<Simulator> tag). Finally you just run '<code>go</code>'.
			In version 5.0 of the toolbox you would just use the name of the simulator configuration file, for version 6.0 you must specify the project directory.

	Note that, depending on whether your simulator is a script, native executable, dataset or Matlab script you will need to set different [[Config:SampleEvaluator\| sample evaluator]] configuration options. For example, if your data comes from a dataset you will have to set the sample evaluator to [[Config:SampleEvaluator#scattered\| scattered]] or [[Config:SampleEvaluator#gridded\| gridded]], depending if you data points are scattered or on a regular grid.		Note that, depending on whether your simulator is a script, native executable, dataset or Matlab script you will need to set different [[Config:SampleEvaluator\| sample evaluator]] configuration options. For example, if your data comes from a dataset you will have to set the sample evaluator to [[Config:SampleEvaluator#scattered\| scattered]] or [[Config:SampleEvaluator#gridded\| gridded]], depending if you data points are scattered or on a regular grid.
	If on the other hand your data comes from a native executable you would want to use the [[Config:SampleEvaluator#local\| local]] sample evaluator with the simulatorType set to "external" (you can also set the type to "java" if your executable is a java class). For Matlab scripts the sample evaluator to use is [[Config:SampleEvaluator#matlab\| matlab]].		If on the other hand your data comes from a native executable you would want to use the [[Config:SampleEvaluator#local\| local]] sample evaluator with the simulatorType set to "external" (you can also set the type to "java" if your executable is a java class). For Matlab scripts the sample evaluator to use is [[Config:SampleEvaluator#matlab\| matlab]].

Tdhaene at 16:03, 10 June 2008

2008-06-10T16:03:41Z

← Older revision		Revision as of 16:03, 10 June 2008
Line 8:		Line 8:
	** scattered data (<ScatteredDataFile> tag)		** scattered data (<ScatteredDataFile> tag)
	** gridded data, data lies on a regular grid (<GriddedDataFile>)		** gridded data, data lies on a regular grid (<GriddedDataFile>)

			Datasets should be placed in <code>examples/data/txt</code>.
	In case of doubt about which dataset to use, use 'ScatteredDataFile'.		In case of doubt about which dataset to use, use 'ScatteredDataFile'.

	~~Datasets should be placed in <code>examples/data/txt</code>.~~ Matlab scripts should be placed in <code>src/matlab/examples</code>.		Matlab scripts should be placed in <code>src/matlab/examples</code>.

	For an explanation of the data format and how the toolbox interfaces with the [[simulator]], see the [[Interfacing with the toolbox]] page.		For an explanation of the data format and how the toolbox interfaces with the [[simulator]], see the [[Interfacing with the toolbox]] page.

Tdhaene at 16:02, 10 June 2008

2008-06-10T16:02:44Z

← Older revision		Revision as of 16:02, 10 June 2008
Line 1:		Line 1:
	If you want to create a surrogate model (metamodel) for your own problem you will first have to write a [[simulator]] xml file. To do this simply open one of the existing simulator xml files (in the <code>examples/</code> ~~directory~~) and create a copy of it in the same directory but under a new name. You can then edit this file to suit your particular problem. This file should be pretty straightforward to write.		If you want to create a surrogate model (metamodel) for your own problem you will first have to write a [[simulator]] xml file. To do this simply open one of the existing simulator xml files (in the <code>examples/</code> subdirectory) and create a copy of it in the same directory but under a new name. You can then edit this file to suit your particular problem. This file should be pretty straightforward to write.

	Your simulator XML file may specify different implementations:		Your simulator XML file may specify different implementations:
Line 8:		Line 8:
	** scattered data (<ScatteredDataFile> tag)		** scattered data (<ScatteredDataFile> tag)
	** gridded data, data lies on a regular grid (<GriddedDataFile>)		** gridded data, data lies on a regular grid (<GriddedDataFile>)

	~~See the [[Simulator configuration]] page for a full list of the possibilities.~~
	In case of doubt about which dataset to use, use 'ScatteredDataFile'.		In case of doubt about which dataset to use, use 'ScatteredDataFile'.

Tdhaene at 14:11, 10 June 2008

2008-06-10T14:11:48Z

← Older revision		Revision as of 14:11, 10 June 2008
Line 19:		Line 19:

	Note that, depending on whether your simulator is a script, native executable, dataset or Matlab script you will need to set different [[Config:SampleEvaluator\| sample evaluator]] configuration options. For example, if your data comes from a dataset you will have to set the sample evaluator to [[Config:SampleEvaluator#scattered\| scattered]] or [[Config:SampleEvaluator#gridded\| gridded]], depending if you data points are scattered or on a regular grid.		Note that, depending on whether your simulator is a script, native executable, dataset or Matlab script you will need to set different [[Config:SampleEvaluator\| sample evaluator]] configuration options. For example, if your data comes from a dataset you will have to set the sample evaluator to [[Config:SampleEvaluator#scattered\| scattered]] or [[Config:SampleEvaluator#gridded\| gridded]], depending if you data points are scattered or on a regular grid.
	If on the other hand your data comes from a native executable you would want to use the [[Config:SampleEvaluator#local\| local]] sample evaluator with the ~~type~~ set to "external" (you can also set the type to "java" if your executable is a java class). For Matlab scripts the sample evaluator to use is [[Config:SampleEvaluator#matlab\| matlab]].		If on the other hand your data comes from a native executable you would want to use the [[Config:SampleEvaluator#local\| local]] sample evaluator with the simulatorType set to "external" (you can also set the type to "java" if your executable is a java class). For Matlab scripts the sample evaluator to use is [[Config:SampleEvaluator#matlab\| matlab]].