# Difference between revisions of "Using a model"

(→Available methods) |
(→plotModel) |
||

Line 28: | Line 28: | ||

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

+ | === evaluate === |
||

− | |||

<code><pre> |
<code><pre> |
||

>> values = evaluate(model, samples); |
>> values = evaluate(model, samples); |
||

Line 35: | Line 35: | ||

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 [[Data_format|simulator configuration]]. If no range (minimum and maximum) is defined, the domain is assumed to be [-1,1]. |
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 [[Data_format|simulator configuration]]. If no range (minimum and maximum) is defined, the domain is assumed to be [-1,1]. |
||

+ | === evaluateInModelspace === |
||

− | |||

<code><pre> |
<code><pre> |
||

>> values = evaluateInModelspace(model, samples); |
>> values = evaluateInModelspace(model, samples); |
||

Line 42: | Line 42: | ||

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

+ | === getSamples === |
||

− | |||

<code><pre> |
<code><pre> |
||

>> samples = getSamples(model); |
>> samples = getSamples(model); |
||

Line 49: | Line 49: | ||

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

+ | === getValues === |
||

− | |||

<code><pre> |
<code><pre> |
||

>> values = getValues(model); |
>> values = getValues(model); |
||

Line 56: | Line 56: | ||

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

+ | === getDescription === |
||

− | |||

<code><pre> |
<code><pre> |
||

>> desc = getDescription(model); |
>> desc = getDescription(model); |
||

Line 63: | Line 63: | ||

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

+ | === getExpression === |
||

− | |||

<code><pre> |
<code><pre> |
||

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

Line 70: | Line 70: | ||

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

− | |||

<code><pre> |
<code><pre> |
||

>> n = freeParams(model); |
>> n = freeParams(model); |
||

Line 77: | Line 77: | ||

Returns the number of free parameters in the model. |
Returns the number of free parameters in the model. |
||

+ | === fields === |
||

− | |||

<code><pre> |
<code><pre> |
||

>> fields(model); |
>> fields(model); |

## Revision as of 17:30, 13 June 2008

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

## Contents

## Available methods

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

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

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

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

## 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 );
```