Difference between revisions of "Toolbox configuration"

From SUMOwiki
Jump to navigationJump to search
 
(18 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
The toolbox can be configured by means of an [http://en.wikipedia.org/wiki/XML XML] file.   
+
The toolbox can be configured by means of an [[FAQ#What is XML?|XML]] file.   
−
Examples can be found in the <code>'<SUMO-Toolbox-directory>/config'</code> directory.
+
Examples can be found in the <code>config/</code> and <code>demo/</code> subdirectories of the SUMO installation directory.
 
The default configuration file is '''<code>config/default.xml</code>'''.   
 
The default configuration file is '''<code>config/default.xml</code>'''.   
  
 
== Structure ==
 
== Structure ==
  
 +
If you do not know what a tag or XML is please see [[FAQ#What is XML?]] first.
  
 
=== Plans and Runs ===
 
=== Plans and Runs ===
Line 13: Line 14:
 
* Each <[[Config:Plan#Run|Run]]> tag can be configured separately.   
 
* Each <[[Config:Plan#Run|Run]]> tag can be configured separately.   
  
−
For example, say you want to model some problem from electronics and you have at your disposal 3 algorithms for selecting data points.  Now lets assume you want to compare the different algorithms on your problem and see which one gives you the best model with the least number of data samples.  In this case your <[[Config:Plan|Plan]]> tag would contain 3 <[[Config:Plan#Run|Run]]> tags and each <[[Config:Plan#Run|Run]]> tag would contain a different <[[SampleSelector|SampleSelector]]> tag.  For example:
+
For example, say you want to model some problem from electronics and you have at your disposal 3 algorithms for selecting data points.  Now lets assume you want to compare the different algorithms on your problem and see which one gives you the best model with the least number of data samples.  In this case your <[[Config:Plan|Plan]]> tag would contain 3 <[[Config:Plan#Run|Run]]> tags and each <[[Config:Plan#Run|Run]]> tag would contain a different <[[SequentialDesign|SequentialDesign]]> tag.  For example:
  
−
<pre><nowiki>
+
<source lang="xml">
 
<Plan>
 
<Plan>
 
   ...
 
   ...
−
   <Run name="gradient-run" repeat="1">
+
   <Run name="lola-run" repeat="1">
−
     <SampleSelector>gradient</SampleSelector>
+
     <SequentialDesign>lola</SequentialDesign>
 
   </Run>
 
   </Run>
−
   <Run name="grid-run" repeat="1">
+
   <Run name="density-run" repeat="1">
−
     <SampleSelector>grid</SampleSelector>
+
     <SequentialDesign>density</SequentialDesign>
 
   </Run>
 
   </Run>
 
   <Run name="random-run" repeat="1">
 
   <Run name="random-run" repeat="1">
−
     <SampleSelector>random</SampleSelector>
+
     <SequentialDesign>random</SequentialDesign>
 
   </Run>
 
   </Run>
 
   ...
 
   ...
 
</Plan>
 
</Plan>
 
...
 
...
−
</nowiki></pre>
+
</source>
  
 
Thus, this concept of a plan and multiple runs allows you to setup different configurations beforehand and try them all in one go.   
 
Thus, this concept of a plan and multiple runs allows you to setup different configurations beforehand and try them all in one go.   
Line 36: Line 37:
 
As you can see it is also possible to specify a '<code>repeat</code>' attribute.  Setting it to 5, for example, will ensure that that particular run is repeated 5 times.  This is usually a good idea if there is a lot of randomness in the algorithms (as is usually the case).   
 
As you can see it is also possible to specify a '<code>repeat</code>' attribute.  Setting it to 5, for example, will ensure that that particular run is repeated 5 times.  This is usually a good idea if there is a lot of randomness in the algorithms (as is usually the case).   
  
−
Remember though to set the '<code>[[Random_state|seedRandomState]]</code>' option in the [[Config:SUMO| <SUMO>]] tag to '<code>random</code>', or otherwise you will still get deterministic results:
+
Remember though to set the '<code>[[Random_state|seedRandomState]]</code>' option in the [[Config:SUMO| <SUMO>]] tag to '<code>random</code>', or otherwise you might get deterministic results:
  
−
<pre><nowiki>
+
<source lang="xml">
 
   <Option key="seedRandomState" value="random"/>
 
   <Option key="seedRandomState" value="random"/>
−
</nowiki></pre>
+
</source>
  
 
=== Declarations and Definitions ===
 
=== Declarations and Definitions ===
Line 46: Line 47:
 
Each component in the toolbox has its own configuration section.  Inside the <[[Config:Plan#Run|Run]]> tag you ''declare'' what components you would like to use. This declaration refers to the ''definition'' of each component, further down the file.  So when you see line like:
 
Each component in the toolbox has its own configuration section.  Inside the <[[Config:Plan#Run|Run]]> tag you ''declare'' what components you would like to use. This declaration refers to the ''definition'' of each component, further down the file.  So when you see line like:
  
−
<pre><nowiki>
+
<source lang="xml">
−
     <SampleSelector>gradient</SampleSelector>
+
     <SequentialDesign>lola</SequentialDesign>
−
</nowiki></pre>
+
</source>
  
−
This means we want to use the '<code>gradient</code>' sample selection algorithm, the word '<code>gradient</code>' is a unique identifier that refers to the <[[SampleSelector|SampleSelector]]> tag that has '<code>[[SampleSelector#GradientSampleSelector|gradient]]</code>' as its "id" attribute.  In this case your configuration file would have the following structure:
+
This means we want to use the '<code>lola</code>' sample selection algorithm, the word '<code>lola</code>' is a unique identifier that refers to the <[[SequentialDesign|SequentialDesign]]> tag that has '<code>[[SampleSelector#GradientSampleSelector|lola]]</code>' as its "id" attribute.  In this case your configuration file would have the following structure:
  
−
<pre><nowiki>
+
<source lang="xml">
 
<Plan>
 
<Plan>
 
   <Run>
 
   <Run>
 
     <!-- Here we declare what components to use, for example, the gradient sample selection algorithm -->
 
     <!-- Here we declare what components to use, for example, the gradient sample selection algorithm -->
−
     <SampleSelector>gradient</SampleSelector>
+
     <SequentialDesign>lola</SequentialDesign>
 
     ...
 
     ...
 
   </Run>
 
   </Run>
Line 64: Line 65:
  
 
<!-- The definition of the sample selector -->
 
<!-- The definition of the sample selector -->
−
<SampleSelector id="gradient">
+
<SequentialDesign id="lola">
 
   ...
 
   ...
 
   <!-- all the options for the gradient sample selection algorithm -->
 
   <!-- all the options for the gradient sample selection algorithm -->
−
</SampleSelector>
+
</SequentialDesign>
 
...
 
...
−
</nowiki></pre>
+
</source>
  
 
If you would like to use a different algorithm (e.g., '<code>[[SampleSelector#ErrorSampleSelector|error]]</code>' for the Error sample selector), you simply fill in a different id in the the <[[SampleSelector|SampleSelector]]> tag in the <[[Config:Plan#Run|Run]]> tag:
 
If you would like to use a different algorithm (e.g., '<code>[[SampleSelector#ErrorSampleSelector|error]]</code>' for the Error sample selector), you simply fill in a different id in the the <[[SampleSelector|SampleSelector]]> tag in the <[[Config:Plan#Run|Run]]> tag:
  
−
<pre><nowiki>
+
<source lang="xml">
−
     <SampleSelector>error</SampleSelector>
+
     <SequentialDesign>error</SequentialDesign>
−
</nowiki></pre>
+
</source>
  
 
You just have to make sure there is a matching definition lower down the file for the id you have filled in.
 
You just have to make sure there is a matching definition lower down the file for the id you have filled in.
  
−
All the other components ([[Config:AdaptiveModelBuilder|AdaptiveModelBuilder]], [[Config:SampleEvaluator|SampleEvaluator]], ...) work in exactly the same way.
+
All the other components ([[Config:ModelBuilder|ModelBuilder]], [[Config:DataSource|DataSource]], ...) work in exactly the same way.
  
−
== Configuration File ==
+
== Running a configuration ==
−
 
 
−
Also see the [[Running]] page for more information about running the toolbox.
 
−
 
 
−
=== Default configuration ===
 
−
 
 
−
The default toolbox configuration file can be found in the '<code>config/</code>' directory under the filename '<code>default.xml</code>'.  It contains all the possible options you can set.
 
−
 
 
−
We advise you to use this file as a basis for your own experiments.
 
−
 
 
−
=== Custom configuration ===
 
−
If you know what you are doing, you can merge your own custom configuration with the 'merge' option.  Options or tags that are missing in this custom file will then be filled up with the values from the default configuration.  Merging works as follows:
 
−
 
 
−
<pre><nowiki>
 
−
go('customConfig.xml',[],[],'-merge');
 
−
</nowiki></pre>
 
  
 +
See the [[Running]] page for how to run the toolbox with a different example or with a your own configuration file.
  
 
== Components ==
 
== Components ==
  
−
''We are well aware that the list below is incomplete and possibly even out of date in some cases. We try to document everything as best we can but much is limited by available time and manpower.  The most up to date documentation can always be found (if not here) in the default.xml configuration file and, of course, in the source files.''
+
''We are well aware that documentation is not always complete and possibly even out of date in some cases. We try to document everything as best we can but much is limited by available time and manpower.  We are are a university research group after all. The most up to date documentation can always be found (if not here) in the default.xml configuration file and, of course, in the source files.  If something is unclear please dont hesitate to [[Reporting problems|ask]].''
  
 
The following components can be configured separately:
 
The following components can be configured separately:
  
 
* [[Config:Plan|Plan]]
 
* [[Config:Plan|Plan]]
 +
* [[Config:Plan|Simulator tag]]
 +
* [[Config:Plan|Inputs]]
 
* [[Outputs]]
 
* [[Outputs]]
−
** [[Measures]]
+
* [[Measures]]
−
* [[Config:Plan|Inputs]]
 
−
* [[Config:Plan|Simulator tag]]
 
 
* [[Config:ContextConfig|ContextConfig]]
 
* [[Config:ContextConfig|ContextConfig]]
 
* [[Config:SUMO|SUMO]]
 
* [[Config:SUMO|SUMO]]
−
** [[Config:SUMO|Initial Designs]]
+
* [[Config:InitialDesign|Initial Designs]]
−
* [[Config:SampleEvaluator|Sample Evaluators]]
+
* [[Config:DataSource|Data Sources]]
−
* [[SampleSelector|Sample Selectors]]
+
* [[Config:SequentialDesign|Sequential designs]]
−
* [[Config:AdaptiveModelBuilder|Adaptive Model Builders]]
+
* [[Config:ModelBuilder|Model Builders]]
−
 
 
  
 
== General guidelines ==
 
== General guidelines ==
  
 
Some general guidelines on how to configure the toolbox for different situations can be found on [[General guidelines|this page]].
 
Some general guidelines on how to configure the toolbox for different situations can be found on [[General guidelines|this page]].

Latest revision as of 16:23, 27 February 2014

The toolbox can be configured by means of an XML file. Examples can be found in the config/ and demo/ subdirectories of the SUMO installation directory. The default configuration file is config/default.xml.

Structure

If you do not know what a tag or XML is please see FAQ#What is XML? first.

Plans and Runs

The general structure of the toolbox is as follows:

  • The top-level <Plan> type defines a surrogate modeling experiment, and an experiment may consist of multiple <Run> tags.
  • Each <Run> tag can be configured separately.

For example, say you want to model some problem from electronics and you have at your disposal 3 algorithms for selecting data points. Now lets assume you want to compare the different algorithms on your problem and see which one gives you the best model with the least number of data samples. In this case your <Plan> tag would contain 3 <Run> tags and each <Run> tag would contain a different <SequentialDesign> tag. For example: 

<Plan>
   ...
   <Run name="lola-run" repeat="1">
     <SequentialDesign>lola</SequentialDesign>
   </Run>
  <Run name="density-run" repeat="1">
     <SequentialDesign>density</SequentialDesign>
   </Run>
   <Run name="random-run" repeat="1">
     <SequentialDesign>random</SequentialDesign>
   </Run>
   ...
</Plan>
...

Thus, this concept of a plan and multiple runs allows you to setup different configurations beforehand and try them all in one go.

As you can see it is also possible to specify a 'repeat' attribute. Setting it to 5, for example, will ensure that that particular run is repeated 5 times. This is usually a good idea if there is a lot of randomness in the algorithms (as is usually the case).

Remember though to set the 'seedRandomState' option in the <SUMO> tag to 'random', or otherwise you might get deterministic results: 

  <Option key="seedRandomState" value="random"/>

Declarations and Definitions

Each component in the toolbox has its own configuration section. Inside the <Run> tag you declare what components you would like to use. This declaration refers to the definition of each component, further down the file. So when you see line like: 

     <SequentialDesign>lola</SequentialDesign>

This means we want to use the 'lola' sample selection algorithm, the word 'lola' is a unique identifier that refers to the <SequentialDesign> tag that has 'lola' as its "id" attribute. In this case your configuration file would have the following structure: 

<Plan>
   <Run>
     <!-- Here we declare what components to use, for example, the gradient sample selection algorithm -->
     <SequentialDesign>lola</SequentialDesign>
     ...
   </Run>
   ...
<Plan>
...

<!-- The definition of the sample selector -->
<SequentialDesign id="lola">
   ...
   <!-- all the options for the gradient sample selection algorithm -->
</SequentialDesign>
...

If you would like to use a different algorithm (e.g., 'error' for the Error sample selector), you simply fill in a different id in the the <SampleSelector> tag in the <Run> tag: 

     <SequentialDesign>error</SequentialDesign>

You just have to make sure there is a matching definition lower down the file for the id you have filled in.

All the other components (ModelBuilder, DataSource, ...) work in exactly the same way.

Running a configuration

See the Running page for how to run the toolbox with a different example or with a your own configuration file.

Components

We are well aware that documentation is not always complete and possibly even out of date in some cases. We try to document everything as best we can but much is limited by available time and manpower. We are are a university research group after all. The most up to date documentation can always be found (if not here) in the default.xml configuration file and, of course, in the source files. If something is unclear please dont hesitate to ask.

The following components can be configured separately:

General guidelines

Some general guidelines on how to configure the toolbox for different situations can be found on this page.

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