Using a model

This page explains what you can do with a SUMO generated model.

Loading a model from disk

As the SUMO Toolbox builds models, each current best model is stored as a Matlab mat file in the output directory (e.g.: output/Academic_2D_Twice_rep01_run00_2008.05.20_10-27-18/models_out/model_0002.mat).

In order to load this model from disk and actually use it, do the following:

• Start Matlab, make sure the SUMO Toolbox is in your path and navigate to the directory where the model file is stored
• Load the model from disk as follows:
  • >> modelFile = load('model_0002.mat');
  • >> model = modelFile.model;

Now the model is available as the variable 'model' in the Matlab workspace. See the Using a model page.

Model portability

How do you exchange and/or export SUMO models.

The other person has the SUMO Toolbox installed

The model 'mat' files can be shared with other people. In order for somebody else to use your saved model the following conditions need to be satisfied:

• The person has the SUMO Toolbox in his Matlab path
• The person should be using a similar Matlab version (including toolboxes) as was used to create the model file (preferably equal)
• The person should be using a similar SUMO Toolbox version as was used to create the model file (preferably equal)

We do not guarantee portability if the the above versions differ.

The other person does NOT have the SUMO Toolbox installed

In this case you can use the getExpression and exportToMFile (available from v6.0) methods. See below.

Available methods

Once the model is loaded you can invoke a number methods on it. For the most complete, up to date list see the list of functions in the @Model and @XModel subdirectories.

guiPlotModel

The easiest way to explore a model is to use the graphical model browser (available from v6.0). See here for more information

plotModel

 >>[figureHandle options] = plotModel(model,[outputNumber],[options])

plotModel will generate an indicative plot of the model surface. To do so, it evaluates the model on a reasonably large grid of points.

plotModel optional parameters:

• outputNumber: optional parameter, an integer specifying which output to plot
• options: optional parameter, a struct containing a number of options you can set. To see the list of available options, simply call plotModel with 2 output arguments and only one input argument.

To determine which kind of plot is generated, one makes a distinction based on the dimension of the input space:

• One dimensional models are always plotted in a simple XY line chart. Samples are shown as dots.
• Two dimensional models are plotted as a Matlab *mesh* plot, i.e. a colored surface. The colors are just an indication of height and don't have any further meaning. The samples are plotted as dots, and should (hopefully) approach the surface.
• Three dimensional problems are plotted used a custom built Slice Plot.
• Four dimensional problems are plotted using 3 Slice Plots. The leftmost plot fixes the variable of the fourth variable at -1, the middle plot at 0 and the rightmost plot at 1 (thus reducing the function to a three dimensional function, making a slice plot possible
• Five dimensional problems are plotted using 9 Slice Plots. The fourth and fifth variables are fixed at values of -1, 0 and 1. Indicators below the plots show where the variables were fixed.
• Higher dimensional problems: All variables after the fifth are fixed at 0, and plotting proceeds as if the model was five dimensional.

The toolbox handles COMPLEX OUTPUTS as their modulus (= absolute value = magnitude) for plotting purposes. These plots are just visual aids for monitoring the modeling process. Phase data can be extracted from the model files.

plotModelErrors

Available since v6.0. Normally you would want to use this function through model browser gui instead.

Shows the errors of your model on the training data and (optionally) validation data.

 >> [fighandle options] = plotModelErrors(model, [output index], [validation data], [options]);

If passed the format of the validation data should match the model signature exactly (one column for every input and output, with 2 columns for complex data). Options are obtained in the same way as with plotModel.

evaluate

 >> values = evaluate(model, samples);

This evaluates the model on the given samples. The samples should be provided in simulator space. Simulator space is defined by the range in the simulator configuration. If no range (minimum and maximum) is defined, the domain is assumed to be [-1,1].

evaluateInModelspace

 >> values = evaluateInModelspace(model, samples);

This evaluates the model on the given samples. The samples should lie in the [-1,1] range (model space).

getSamples

 >> samples = getSamples(model);

Returns the samples that were used to fit the model. The samples are returned in simulator space.

getValues

 >> values = getValues(model);

Returns the values that correspond to the samples from getSamples().

getDescription

 >> desc = getDescription(model);

Returns a string with a user friendly description of the model.

getExpression

 >> desc = getExpression(model,[outputNumber]);

Returns the symbolic mathematical expression of this model (e.g., 3*x1^2 - 2*x2 +5). Note that not all model types implement this (yet).

freeParams

 >> n = freeParams(model);

Returns the number of free parameters in the model. By default this returns the number of datapoints the model was built with but this is overridden by some model types. For example, an ANN model returns the number of weights in the network while a rational model returns the number of coefficients.

fields

 >> fields(model);

Returns all fields the object has.

Other methods differ per model type. Inspect the corresponding model directory and constructor to see what methods and options are available.

Model Optimization

To optimize the model, Matlab requires a function handle to the objective function (= the model object). You can construct a function handle from the model object as follows (example for the 3D case):

  handle = @(x,y,z) evaluate( model, [x,y,z] );

Afterwards, you can pass that handle to your optimization procedure, or use it through feval:

  fmincon( handle, ... );
  feval( handle, 0, 1, -1 );