Using a model

This page explains what you can do with a model once you have loaded it into the Matlab workspace.

Available methods

Once the model is loaded you can invoke a number methods on it.

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

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 small crosses.
• 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 small crosses, and should (hopefuly) 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.

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

>> values = evaluateInModelspace(model, samples);

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

>> samples = getSamples(model);

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

>> values = getValues(model);

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

>> desc = getDescription(model);

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

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

>> n = freeParams(model);

Returns the number of free parameters in the model.

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

Optimization

As a further tip, say you want to optimize the model. In this case 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 );