Config:ToolboxConfiguration

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:SampleEvaluator|SampleEvaluator]]/>
	<[[Config:SampleSelector|SampleSelector]]/>
	<[[Config:AdaptiveModelBuilder|AdaptiveModelBuilder]]/>
	<[[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 AdaptiveModelBuilder, 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.

	<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>

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>
			<SampleSelector>random</SampleSelector>
			<SampleEvaluator>matlab</SampleEvaluator>
			<AdaptiveModelBuilder>kriging</AdaptiveModelBuilder>
			<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:

	<SampleSelector>random</SampleSelector>

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!