This page gives some additional information about the implementation of Models implemented in the SUMO Toolbox. Note that the information is only given for the Model class and additional options may be available in the corresponding ModelFactory.

''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]].''

Also see the [[Using a model]] and [[Add Model Type]] pages.

== Model (Abstract base class) ==

The <code>Model</code> class serves as an overall base class, it is the interface to which all models should adhere.

== RationalModel ==

A rational model tries to interpolate or approximate data by a rational function, like
<math>3 x^2 y + 5 x y + 2x + 1</math>
or by a quotient of 2 polynomial, like
<math>\dfrac{xy + 2x + 6y + 2}{xy + 1}</math>

To decide which degrees (monomials) are present in numerator and denominator, the rational model depends on three model parameters:
* Variable weights W1 ... Wd (integer values, one for each dimension)
* Variable flags F1 ... Fd (boolean values, one for each dimension)
* An indicator for the degrees of freedom, P

To determine which degrees to use, this procedure is followed:
# Determine the number of sample points N
# Use P to determine the requested degrees of freedom: freedom = N * P / 100
# Select degrees based on weighting and flags, using following rules:
#* Only variables for which Fi == false (0) are allowed in the denominator
#* Monomials with degrees (a1 ... ad) get precedence over monomials with degrees (b1 ... bd) if and only if the expression a1*W1 + ... + ad*Wd < b1*W1 + ... + bd*Wd

The calculation of these suitable degrees are delegated to the Degrees class, which uses a Java implementation (Diophantine Solver) to order the monomials using the weighted expression.

Rationale: The weighting scheme is in place because the number of model parameters had to be restricted in some way. [[http://www.sumo.intec.ugent.be/files/1999_09_IEEE_MTT.pdf|De Geest et al.]] used such a weighting scheme before to discriminate between variables. The toolbox tries to select suitable values adaptively. In this way, it can eliminate variables which have no significant impact on the output (like in the Kotanchek example).

Please note that ''larger weights'' correspond to ''less important variables''.

Two extra options are of interest:
# Selection of base function (a function handle)
# The frequencyVariable parameter (a variable name, or the keywords auto or off)

It is sometimes advantageous to use a different set of base functions. The default set is just the power function: 1, x, x^2, ... The toolbox provides two alternatives for this, the Legendre base functions, and the Chebyshev base functions. Each occurrence of x^i in the above should be read as ''the value of the i'th base function in x''.

When the frequencyVariable parameter resolves to a variable name, or when it is set to auto and there is a variable named f, freq or frequency, that variable is treated differently. First of all it is scaled to by strictly positive. To do this the standard interval [-1,1] is rescaled to [j,2*j], in order to represent a true complex frequency. Then, a standard RationalModel is built, using ''only real coefficients''. Only use this feature when [[Outputs#Complex_handling|complexHandling]] is set to 'complex', otherwise it is pointless.

== SVMModel ==

SVMModel is the SUMO class for Support Vector Machines (SVM). It is a wrapper class for three different SVM implementations: LibSVM [http://www.csie.ntu.edu.tw/~cjlin/libsvm/], SVM-Light [http://svmlight.joachims.org/] and LS-SVM [http://www.esat.kuleuven.be/sista/lssvmlab/]. You can find more information about each implementation on their websites and in the SVMModel code.

SVMModel has the following properties (note that some of these properties only apply to one specific implementation):

* backend: Chooses which SVM implementation to use. The following options are valid: libSVM, libSVM, and lssvm. By default LibSVM is used.
* kernel: Chooses the kernel of the SVM. The following options are available: rbf (radial basis functions), lin (linear), poly (polynomial), and sig (sigmoid)
* kernelParams: Lets you specify the specific kernel parameters, the options here are dependent on the backend used
* regularizationParam: Lets you specify the trade-off parameter between the margin and the training error. The regularization parameter will be 10^regularizationParam
* epsilon: Sets the epsilon parameter of support vector regression (SVR).
* stoppingTolerance: Sets the tolerance for the stopping criterion.
* nu: Set the nu parameter of nu-SVR and nu-SVC (only for LibSVM)
* type: Sets the type of LibSVM (nu-SVR, epsilon-SVR, etc...)
* crossvalidationFolds: Set the number of folds for LibSVM in cross-validation mode

== EureqaModel ==

The EureqaModel implements the interface between the SUMO Toolbox and the Eureqa Toolbox. This interface is modified code from [http://www.mathworks.com/matlabcentral/fileexchange/32225-interface-with-eureqa-featuring-symbolic-regression]. The EureqaModel implementation does not do modelling itself, instead it connects to a Eureqa server from which it retrieves the solution. The options for the EureqaModel are the following:

* fitness: Chooses the fitness function of the genetic search. The fitness functions are coded, e.g. 0 -> mean absolute error. The complete list of fitness functions can be found [http://code.google.com/p/eureqa-api/wiki/doc_fitness_types here].
* operators: A string with the operators allowed in the genetic search. The operators can be given in arbitrary order spaces not necessary. The set of possible operators is limited compared to the standalone GUI version of Eureqa. Only 'constant, +, -, *, /, ^, exp, log, sin, cos, abs, tan' are supported.
* duration: The amount of time allocated to the genetic search in second.
* debug: Displays intermediate information during the search.
* doStart: If this is true, SUMO will automatically start a Eureqa server. If additional options about the server are given (see below) SUMO will start the server with these options. Otherwise a Eureqa server has to be started manually.
* pathToServer: The path where the Eureqa server is located. By default SUMO will look in the directory of the EureqaFactory class.
* host: The name of the host of the Eureqa server, by default this is localhost.
* port: The port with which to connect to the Eureqa Server.
* forceCores: Forces the server to use a specified amount of CPU cores.
* maxCores: Set the maximum number of CPU cores the Eureqa server can use.
* scaleFactors: Models in SUMO normally work in Model space, i.e. the input space is scaled to [-1 1] for all dimensions. The scaleFactors property tells SUMO how this [-1 1] should be scaled instead. When calling a EureqaModel from the EureqaFactory, the scaleFactors will be set equal to those defined in the Simulator.xml of the problem.

EureqaModel returns a solution string which can be accessed by the method model.getFormula. The method model.getAllSolutions will give the entire pareto front of solutions as a cell of strings.

== MOVFModel ==

The MOVFModel implements the Multivariate Orthonormal Vector Fitting (MOVF) technique [http://www.sumo.intec.ugent.be/files/2008_07_IEEE_MTT.pdf]. This is a rational that fits the data in a least-square sense. This model is not included in the release version of the SUMO Toolbox due to licensing issues. Due to the implementation, the '''frequency has to be the last parameter''' of data given to the MOVFModel.

The properties for MOVFModel are the following:

* order: A vector with the order of each input parameter. If the basis used is rational, all the orders have to be even. If the basis used is polynomial, the orders for the geometrical parameters can be any positive integer, and only the order of the frequency has to be even.
* iter: Determines the number of internal optimization iterations of the MOVFModel.
* basis: Specifies the basis used to model the geometric parameters of the MOVFModel. The basis can either be ''rational'' or ''polynomial''.
* errorFunc: A string with the name of an error function used to optimize the MOVFModel internally. The valid options can be found in src/matlab/tools/errorFunctions
* scaleFactors: Scales the data from the default [-1 1] input of SUMO to the desired bounds. When calling the MOVFModel from MOVFFactory the bounds defined in the Simulator.xml of the problem will be used.

The coefficients of the MOVFModel can be accessed via model.getMOVF.coef.

Model types explained

2012-02-15T16:06:08Z

Mnguyen: /* MOVFModel */

Model types explained

2012-02-15T15:54:32Z

Mnguyen: /* EureqaModel */

Model types explained

2012-02-15T15:54:02Z

Mnguyen: /* SVMModel */

Config:ToolboxConfiguration

2012-02-10T15:40:28Z

Mnguyen: /* Changing configuration components of an experimental run */

== 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.
<source xmlns:saxon="http://icl.com/saxon" lang="xml">
<[[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]]>
</source>

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

<source xmlns:saxon="http://icl.com/saxon" lang="xml">

</source>

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

<source lang="xml">
<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>
</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 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:AdaptiveModelBuilder|AdaptiveModelBuilder]], [[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>

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

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

<source xmlns:saxon="http://icl.com/saxon" lang="xml">

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

</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">
<SampleSelector>random</SampleSelector>
</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.

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.

=== test ===

Config:ToolboxConfiguration

2012-02-10T15:39:25Z

Mnguyen: /* Changing configuration components of an experimental run */

== 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.
<source xmlns:saxon="http://icl.com/saxon" lang="xml">
<[[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]]>
</source>

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

<source xmlns:saxon="http://icl.com/saxon" lang="xml">

</source>

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

<source lang="xml">
<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>
</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 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:AdaptiveModelBuilder|AdaptiveModelBuilder]], [[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>

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

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

<source xmlns:saxon="http://icl.com/saxon" lang="xml">

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

</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">
<SampleSelector>random</SampleSelector>
</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.

The default.xml already has a number of configuration section already defined, making it easier for you to experiment with them.