Difference between revisions of "Config:ToolboxConfiguration"

From SUMOwiki
Jump to navigationJump to search
 
(19 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
<source xmlns:saxon="http://icl.com/saxon" lang="xml">
 
<source xmlns:saxon="http://icl.com/saxon" lang="xml">
 
<[[Config:ToolboxConfiguration|ToolboxConfiguration]] version="7.0">
 
<[[Config:ToolboxConfiguration|ToolboxConfiguration]] version="7.0">
<[[Config:Plan|Plan]]/>
+
<[[Config:Plan|Plan]]/>
<[[Config:ContextConfig|ContextConfig]]/>
+
<[[Config:ContextConfig|ContextConfig]]/>
<[[Config:Logging|Logging]]/>
+
<[[Config:Logging|Logging]]/>
<[[Config:LevelPlot|LevelPlot]]/>
+
<[[Config:LevelPlot|LevelPlot]]/>
<[[Config:SUMO|SUMO]]/>
+
<[[Config:SUMO|SUMO]]/>
<[[Config:SampleEvaluator|SampleEvaluator]]/>
+
<[[Config:DataSource|DataSource]]/>
<[[Config:SampleSelector|SampleSelector]]/>
+
<[[Config:SequentialDesign|SequentialDesign]]/>
<[[Config:AdaptiveModelBuilder|AdaptiveModelBuilder]]/>
+
<[[Config:ModelBuilder|ModelBuilder]]/>
<[[Config:BasisFunction|BasisFunction]]/>
+
<[[Config:BasisFunction|BasisFunction]]/>
<[[Config:InitialDesign|InitialDesign]]/>
+
<[[Config:InitialDesign|InitialDesign]]/>
<[[Config:Optimizer|Optimizer]]/>
+
<[[Config:Optimizer|Optimizer]]/>
 
</[[Config:ToolboxConfiguration|ToolboxConfiguration]]>
 
</[[Config:ToolboxConfiguration|ToolboxConfiguration]]>
 
</source>
 
</source>
 
  
 
== Interpreting the configuration file ==  
 
== Interpreting the configuration file ==  
Line 60: Line 59:
 
</source>
 
</source>
  
The configuration file uses XML to group information about the Toolbox into logical units. Here is an example configuration of a [[Config:SampleSelector#delaunay|SampleSelector called delaunay]]. It has three attributes ''id'', ''type'' and ''combineOutputs''.  
+
The configuration file uses XML to group information about the Toolbox into logical units. Here is an example configuration of a [[Config:SampleSelector#delaunay|SampleSelector]] called delaunay. It has three attributes ''id'', ''type'' and ''combineOutputs''. The SUMO Toolbox uses the ''id'' to refer to this configuration section in other places in the configuration file. The ''type'' refers tells the toolbox what class of sample selector it has to look for in the <code>src</code> folder, in this case the class ''PipeLinSampleSelector'' which you can find under <code>src/matlab/sampleselector/@PipeLineSampleSelector</code>. The ''combineOutputs'' tells the SUMO how the SampleSelector has to deal with multiple outputs.
  
 +
If you look at the implementation of the PipeLineSampleSelector you will see that it requires a ''CandidateGenerator'', ''CandidateRanker'' and a ''MergeCriterion'' all of which are specified here within the ''SampleSelector'' tag.
 +
 +
Other components (such as [[Config:ModelBuilder|ModelBuilder]], [[Config:InitialDesign|initial design]], etc...) require different information. To find what options and configurations you need/can give to a component check out their wiki page or their implementation in the Toolbox.
  
 
<source lang=xml>
 
<source lang=xml>
  
<SampleSelector id="delaunay" type="PipelineSampleSelector" combineOutputs="false">
+
<SequentialDesign id="delaunay" type="PipelineSampleSelector" combineOutputs="false">
 
 
 
<CandidateGenerator type="DelaunayCandidateGenerator"/>
 
<CandidateGenerator type="DelaunayCandidateGenerator"/>
Line 76: Line 78:
 
         <MergeCriterion type="WeightedAverage" weights="[1 1]"/>
 
         <MergeCriterion type="WeightedAverage" weights="[1 1]"/>
 
          
 
          
</SampleSelector>
+
</SequentialDesign>
 
</source>
 
</source>
  
=== test ===
+
=== Changing configuration components of an experimental run ===
 +
The SUMO Toolbox was written with flexibility in mind, making it easy to experiment with different combinations of algorithms. Here is a snippet from a configuration XML. The snippet show the <Plan> tag which determines how the experimental runs are configured and two different pre-defined <SampleSelector> tags, ''random'' and ''delaunay''.
  
 
<source xmlns:saxon="http://icl.com/saxon" lang="xml">
 
<source xmlns:saxon="http://icl.com/saxon" lang="xml">
Line 93: Line 96:
 
                 <Run name="" repeat="1">
 
                 <Run name="" repeat="1">
 
<InitialDesign>lhdWithCornerPoints</InitialDesign>
 
<InitialDesign>lhdWithCornerPoints</InitialDesign>
<SampleSelector>random</SampleSelector>
+
<DataSource>random</DataSource>
 
<SampleEvaluator>matlab</SampleEvaluator>
 
<SampleEvaluator>matlab</SampleEvaluator>
<AdaptiveModelBuilder>kriging</AdaptiveModelBuilder>
+
<SequentialDesign>kriging</SequentialDesign>
 
<Measure type="CrossValidation" target="0.01" errorFcn="rootRelativeSquareError" use="on" />
 
<Measure type="CrossValidation" target="0.01" errorFcn="rootRelativeSquareError" use="on" />
 
<Outputs>
 
<Outputs>
Line 127: Line 130:
  
 
</source>
 
</source>
 +
 +
All the tags within the <Plan> tag, except for Measure, Inputs and Outputs, refer to a configuration section defined further in the configuration xml. These tags determine what algorithm will be used for the experimental run. For example in this case the tag:
 +
 +
<source lang="xml">
 +
<SequentialDesign>random</SequentialDesign>
 +
</source>
 +
 +
refers to the SampleSelector tag with an ''id=random''. So even though both the ''random'' SampleSelector and ''delaunay'' SampleSelector are defined, it is the random SampleSelector which will be used in the experimental run. To use the ''delaunay'' SampleSelector simply replace ''random'' by ''delaunay'' in the <Plan>.
 +
 +
The default.xml already has a number of configuration section already defined, making it easier for you to experiment with them. All you have to do is use the appropriate ''id'' in the right tags.
 +
 +
=== Modifying/Creating your own configuration section ===
 +
 +
In some cases the default configuration sections might no suit your needs. For example if you require a lhdWithCornerPoints [[Config:InitialDesign|initial design]] with 40 instead of the default 20 points. In this case you can either create a new configuration section like so:
 +
 +
<source lang="xml">
 +
<InitialDesign id="lhdWithCornerPoints40" type="CombinedDesign">
 +
<InitialDesign type="LatinHypercubeDesign">
 +
<!-- how many points to generate -->
 +
<Option key="points" value="40"/>
 +
</InitialDesign>
 +
 +
<InitialDesign type="FactorialDesign">
 +
<Option key="levels" value="2" />
 +
</InitialDesign>
 +
</InitialDesign>
 +
</source>
 +
 +
and refer to it in the plan using the ''id'' lhdWithCornerPoints40 or you can simply edit the default lhdWithCornerPoints :). When making your own configuration section, make sure you specify all necessary tags and options and you're set to go!

Latest revision as of 16:26, 27 February 2014

Toolbox configuration file

This is the default SUMO toolbox configuration, this is what gets used when you run 'go' without any arguments You can edit this file directly or make a copy and run that. See the wiki for detailed information.

<[[Config:ToolboxConfiguration|ToolboxConfiguration]] version="7.0">
	<[[Config:Plan|Plan]]/>
	<[[Config:ContextConfig|ContextConfig]]/>
	<[[Config:Logging|Logging]]/>
	<[[Config:LevelPlot|LevelPlot]]/>
	<[[Config:SUMO|SUMO]]/>
	<[[Config:DataSource|DataSource]]/>
	<[[Config:SequentialDesign|SequentialDesign]]/>
	<[[Config:ModelBuilder|ModelBuilder]]/>
	<[[Config:BasisFunction|BasisFunction]]/>
	<[[Config:InitialDesign|InitialDesign]]/>
	<[[Config:Optimizer|Optimizer]]/>
</[[Config:ToolboxConfiguration|ToolboxConfiguration]]>

Interpreting the configuration file

When first looking at the default.xml you are presented with a lot of information and it can be a bit difficult to understand what is going, especially if you are not familiar with XML. However there is method in the madness, and this section will help you to break down the components that make up the configuration file.

Comments

Comments in the XML are displayed like so:

	<!-- This is an example comment. -->

The default.xml contains a lot of comments with information about the different sections or example usage.

Tags

XML groups information that logically belong to with each other within so called tags. Here is an example of a recipe tag. This is a recipe to make pancakes, which is grouped in a logical way; all the ingredients items are grouped within the ingredients tag. The items themselves in turn group information about the type of ingredient and the required amount. Tags can also have attributes, here the recipe tag has an attribute called category with the value desert.

  <recipe category="dessert">
  <title>Pancakes</title>
  <author>sumo@intec.ugent.be</author>
  <date>Wed, 14 Jun 95</date>
  <description>
    Good old fashioned pancakes.
  </description>
  <ingredients>
    <item>
        <amount>3</amount>
        <type>eggs</type>
    </item>
    
    <item>
         <amount>0.5 tablespoon</amount>
         <type>salt</type>
    </item>
     ...
  </ingredients>
  <preparation>
    ...
  </preparation>
 </recipe>

The configuration file uses XML to group information about the Toolbox into logical units. Here is an example configuration of a SampleSelector called delaunay. It has three attributes id, type and combineOutputs. The SUMO Toolbox uses the id to refer to this configuration section in other places in the configuration file. The type refers tells the toolbox what class of sample selector it has to look for in the src folder, in this case the class PipeLinSampleSelector which you can find under src/matlab/sampleselector/@PipeLineSampleSelector. The combineOutputs tells the SUMO how the SampleSelector has to deal with multiple outputs.

If you look at the implementation of the PipeLineSampleSelector you will see that it requires a CandidateGenerator, CandidateRanker and a MergeCriterion all of which are specified here within the SampleSelector tag.

Other components (such as ModelBuilder, initial design, etc...) require different information. To find what options and configurations you need/can give to a component check out their wiki page or their implementation in the Toolbox.

	<SequentialDesign id="delaunay" type="PipelineSampleSelector" combineOutputs="false">
		
		<CandidateGenerator type="DelaunayCandidateGenerator"/>
		
        	<CandidateRanker type="modelDifference">
        		<Option key="criterion_parameter" value="2"/>
       		</CandidateRanker>
        	<CandidateRanker type="delaunayVolume"/>
        
        	<MergeCriterion type="WeightedAverage" weights="[1 1]"/>
        
</SequentialDesign>

Changing configuration components of an experimental run

The SUMO Toolbox was written with flexibility in mind, making it easy to experiment with different combinations of algorithms. Here is a snippet from a configuration XML. The snippet show the <Plan> tag which determines how the experimental runs are configured and two different pre-defined <SampleSelector> tags, random and delaunay.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<ToolboxConfiguration version="7.0">

	<Plan>
                <ContextConfig>default</ContextConfig>
		<SUMO>default</SUMO>
		<LevelPlot>default</LevelPlot>
		<Simulator>Math/Academic/Academic2DTwice.xml</Simulator>
                <Run name="" repeat="1">
			<InitialDesign>lhdWithCornerPoints</InitialDesign>
			<DataSource>random</DataSource>
			<SampleEvaluator>matlab</SampleEvaluator>
			<SequentialDesign>kriging</SequentialDesign>
			<Measure type="CrossValidation" target="0.01" errorFcn="rootRelativeSquareError" use="on" />
			<Outputs>
				<Output name="out">
				</Output>
				<Output name="outinverse">
				</Output>
			</Outputs>
		</Run>
	</Plan>

 	...

	<SampleSelector id="random" type="RandomSampleSelector" combineOutputs="false"/>

	<SampleSelector id="delaunay" type="PipelineSampleSelector" combineOutputs="false">
		
		<CandidateGenerator type="DelaunayCandidateGenerator"/>
		
        	<CandidateRanker type="modelDifference">
        		<Option key="criterion_parameter" value="2"/>
       		</CandidateRanker>
        	<CandidateRanker type="delaunayVolume"/>
        
        	<MergeCriterion type="WeightedAverage" weights="[1 1]"/>
        
	</SampleSelector>


</ToolboxConfiguration>

All the tags within the <Plan> tag, except for Measure, Inputs and Outputs, refer to a configuration section defined further in the configuration xml. These tags determine what algorithm will be used for the experimental run. For example in this case the tag:

	<SequentialDesign>random</SequentialDesign>

refers to the SampleSelector tag with an id=random. So even though both the random SampleSelector and delaunay SampleSelector are defined, it is the random SampleSelector which will be used in the experimental run. To use the delaunay SampleSelector simply replace random by delaunay in the <Plan>.

The default.xml already has a number of configuration section already defined, making it easier for you to experiment with them. All you have to do is use the appropriate id in the right tags.

Modifying/Creating your own configuration section

In some cases the default configuration sections might no suit your needs. For example if you require a lhdWithCornerPoints initial design with 40 instead of the default 20 points. In this case you can either create a new configuration section like so:

	<InitialDesign id="lhdWithCornerPoints40" type="CombinedDesign">
		<InitialDesign type="LatinHypercubeDesign">
			<!-- how many points to generate -->
			<Option key="points" value="40"/>
		</InitialDesign>

		<InitialDesign type="FactorialDesign">
			<Option key="levels" value="2" />
		</InitialDesign>
	</InitialDesign>

and refer to it in the plan using the id lhdWithCornerPoints40 or you can simply edit the default lhdWithCornerPoints :). When making your own configuration section, make sure you specify all necessary tags and options and you're set to go!