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.

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.

Model space vs Simulator space

It is important to note the difference between Model space and Simulator space. When a data point is in model space, it means its inputs all lie in the range [-1 1]. When the point is in simulator space its inputs lie in the range specified by the Simulator configuration file.

Internally the toolbox only works in model space. The toolbox will take care of translating points from simulator space into model space and back (this happens in the SampleManager object). You will note that many methods have a XXXinModelSpace variant. This just means that the method does exactly the same, except it expects points to be in model space. You should normally not have to care about model space unless you are writing your own extensions to the toolbox. In that case see Add Model Type.

Available methods

Once the model is loaded you can invoke a number methods on it. We list the main ones below. For a full list of available methods just use the matlab 'methods' command:

 >>methods(model)

If you want to understand the structure of the model, i.e., how the model object is built up you can do two things:

1. open the class file for that model, e.g., for an ANNModel object, open the src/matlab/models/@ANNModel/ANNModel.m file
2. use the struct command to convert the model object to a structure. For example:

 >>str = struct(model)

Also, some model types provide methods to access the internal model representation. For example, if m is an object of type ANNModel, then executing m.getNetwork() will return the nested Matlab neural network object (from the Matlab Neural Network Toolbox).

guiPlotModel

The easiest way to explore a model is to use the graphical model browser. See here for more information

plotModel

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

plotModel will generate an indicative plot of the model surface. To do so, it evaluates the model on a reasonably dense 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 get the default options simply call Model.getPlotDefaults().

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

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) was specified, the domain is assumed to be [-1,1].

See also Using_a_model#Model_object_interfacing_and_optimization

evaluateDerivative

 >> values = evaluateDerivative(model, samples, [outputIndex]);

This approximates the partial derivatives of the model at each given sample. Note that the base class implementation is a very simple approximation. Models can override this function to provide more accurate derivatives (e.g., Kriging does this already). However, in its current form it is already useful.

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.

construct

 >> model = construct(model,samples);

This will build/train/fit.. the model on the given set of data points and return the updated model.

complexity

 >> n = complexity(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.

Model object interfacing and optimization

You may want to use the model as part of a larger Matlab program, or you may simply want to optimizer the model. To easily do this you can create a function handle to the model object. You can do this 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 );

Miscellaneous post-processing scripts

The SUMO Toolbox also includes some miscellaneous scripts you can use to analyze the results of your run. You can find them in ...\SUMO-Toolbox\src\scripts\matlab\ folder.