Difference between revisions of "Toolbox configuration"

From SUMOwiki
Jump to navigationJump to search
 
(52 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
The toolbox can be configured by means of an XML file.  Examples can be found in the 'config' directory. The default configuration file is 'config/default.xml'.   
+
The toolbox can be configured by means of an [[FAQ#What is XML?|XML]] file.   
 +
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>'''.   
  
−
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.
+
== Structure ==
−
<pre><nowiki>
 
−
go('customConfig.xml',[],[],'-merge');
 
−
</nowiki></pre>
 
  
−
See the [[Running]] page for more information about running the toolbox.
+
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 <[[Config:Plan|Plan]]> type defines a surrogate modeling experiment, and an experiment may consist of multiple <[[Config:Plan#Run|Run]]> tags. 
 +
* 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 <[[SequentialDesign|SequentialDesign]]> tag.  For example:
 +
 
 +
<source lang="xml">
 +
<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>
 +
...
 +
</source>
 +
 
 +
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 '<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 might get deterministic results:
 +
 
 +
<source lang="xml">
 +
  <Option key="seedRandomState" value="random"/>
 +
</source>
 +
 
 +
=== Declarations and Definitions ===
 +
 
 +
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:
 +
 
 +
<source lang="xml">
 +
    <SequentialDesign>lola</SequentialDesign>
 +
</source>
 +
 
 +
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:
 +
 
 +
<source lang="xml">
 +
<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>
 +
...
 +
</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:
 +
 
 +
<source lang="xml">
 +
    <SequentialDesign>error</SequentialDesign>
 +
</source>
 +
 
 +
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:ModelBuilder|ModelBuilder]], [[Config:DataSource|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 [[Reporting problems|ask]].''
  
 
The following components can be configured separately:
 
The following components can be configured separately:
  
−
* [[Plan]]
+
* [[Config:Plan|Plan]]
−
* [[Simulator]]
+
* [[Config:Plan|Simulator tag]]
−
* [[ContextConfig]]
+
* [[Config:Plan|Inputs]]
−
* [[M3]]
+
* [[Outputs]]
−
* [[Sample Evaluators]]
+
* [[Measures]]
−
* [[Sample Selectors]]
+
* [[Config:ContextConfig|ContextConfig]]
−
* [[Adaptive Model Builders]]
+
* [[Config:SUMO|SUMO]]
 +
* [[Config:InitialDesign|Initial Designs]]
 +
* [[Config:DataSource|Data Sources]]
 +
* [[Config:SequentialDesign|Sequential designs]]
 +
* [[Config:ModelBuilder|Model Builders]]
 +
 
 +
== General guidelines ==
 +
 
 +
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"