Difference between revisions of "Adding an example"

From SUMOwiki
Jump to navigationJump to search
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
== Simulator file ==
+
This page explains how to add your own data/simulation code/... to the toolbox in order to model it.
  
−
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.
+
== Project directories ==
−
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.
+
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]].
−
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:'''
+
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:
−
Datasets should be placed in <code>examples/data/txt</code>.  
 
−
In case of doubt about which dataset to use, use 'ScatteredDataFile'.
 
  
−
Matlab scripts should be placed in <code>src/matlab/examples</code>.
+
# 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 data files (optional)
 +
# Alternative simulator xml files (optional)
 +
# Other files, e.g., a documenting pdf (optional)
  
−
'''For version 6.0:'''
+
Open up a couple of the example project directories and have a look inside so you are sure whats going on.
−
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.
+
== Modeling your own problem ==
  
−
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>'.
+
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.
−
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.
+
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.
−
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]].
+
 
 +
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]].

Latest revision as of 00:04, 3 September 2009

This page explains how to add your own data/simulation code/... to the toolbox in order to model it.

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. If you simply want to play around and try different examples please refer to Running#Running_different_examples.

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 examples/ subdirectory of your SUMO-Toolbox installation. If you open one of those directories you will see they contain the following things:

  1. A simulator xml file with the same name as the project directory. This file is mandatory (though there are some small exceptions)
  2. One or more executables: matlab script, C++ file, binary, ... (optional)
  3. One or more data files (optional)
  4. Alternative simulator xml files (optional)
  5. Other files, e.g., a documenting pdf (optional)

Open up a couple of the example project directories and have a look inside so you are sure whats going on.

Modeling your own problem

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.

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 default.xml so it uses your problem (<Simulator> tag). For information on this see Running#Running different examples.

Retrieved from "http://sumowiki.intec.ugent.be/index.php?title=Adding_an_example&oldid=4844"