# evalSurf

Evaluate gain surfaces at specific design points

## Description

## Examples

### Evaluate 1-D Gain Surface at Specified Values

Create a gain surface with one scheduling variable and evaluate the gain at a list of scheduling-variable values.

When you create a gain surface using `tunableSurface`

, you specify design points at which the gain coefficients are tuned. These points are the typically the scheduling-variable values at which you have sampled or linearized the plant. However, you might want to implement the gain surface as a lookup table with breakpoints that are different from the specified design points. In this example, you create a gain surface with a set of design points and then evaluate the surface using a different set of scheduling variable values.

Create a scalar gain that varies as a quadratic function of one scheduling variable, *t*. Suppose that you have linearized your plant every five seconds from *t* = 0 to *t* = 40.

t = 0:5:40; domain = struct('t',t); shapefcn = @(x) [x,x^2]; GS = tunableSurface('GS',1,domain,shapefcn);

Typically, you would tune the coefficients as part of a control system. For this example, instead of tuning, manually set the coefficients to non-zero values.

GS = setData(GS,[12.1,4.2,2]);

Evaluate the gain surface at a different set of time values.

```
tvals = [0,4,11,18,25,32,39,42]; % eight values
GV = evalSurf(GS,tvals)
```

`GV = `*8×1*
9.9000
10.0200
10.6150
11.7000
13.2750
15.3400
17.8950
19.1400

`GV`

is an 8-by-1 array. You can use `tvals`

and `GV`

to implement the variable gain as a lookup table.

### Evaluate Gain Surface on Grid of Values

Evaluate a gain surface with two scheduling variables over a grid of values of those variables.

When you create a gain surface using `tunableSurface`

, you specify design points at which the gain coefficients are tuned. These points are the typically the scheduling-variable values at which you have sampled or linearized the plant. However, you might want to implement the gain surface as a lookup table with breakpoints that are different from the specified design points. In this example, you create a gain surface with a set of design points and then evaluate the surface using a different set of scheduling-variable values.

Create a scalar-valued gain surface that is a bilinear function of two independent variables, $$\alpha $$ and *V*.

[alpha,V] = ndgrid(0:1.5:15,300:30:600); domain = struct('alpha',alpha,'V',V); shapefcn = @(x,y) [x,y,x*y]; GS = tunableSurface('GS',1,domain,shapefcn);

Typically, you would tune the coefficients as part of a control system. For this example, instead of tuning, manually set the coefficients to non-zero values.

GS = setData(GS,[100,28,40,10]);

Evaluate the gain at selected values of $$\alpha $$ and *V*.

alpha_vec = [7:1:13]; % N1 = 7 points V_vec = [400:25:625]; % N2 = 10 points GV = evalSurf(GS,alpha_vec,V_vec);

The breakpoints at which you evaluate the gain surface need not fall within the range specified by `domain`

. However, if you attempt to evaluate the gain too far outside the range used for tuning, the software issues a warning.

The breakpoints also need not be regularly spaced. `evalSurf`

evaluates the gain surface over the grid formed by `ndgrid(alpha_vec,V_vec)`

. Examine the dimensions of the resulting array.

size(GV)

`ans = `*1×2*
7 10

By default, the grid dimensions `N1-by-N2`

are first in the array, followed by the gain dimensions. `GS`

is scalar-valued gain, so the dimensions of `GV`

are [7,10,1,1], or equivalently [7,10].

The value in each location of `GV`

is the gain evaluated at the corresponding `(alpha_vec,V_vec)`

pair in the grid. For example, `GV(2,3)`

is the gain evaluated at `(alpha_vec(2),V_vec(3))`

or `(8,450)`

.

### Evaluate Array-Valued Gain Surface

Evaluate an array-valued gain surface with two scheduling variables over a grid of values of those variables.

Create a vector-valued gain that has two scheduling variables.

[alpha,V] = ndgrid(0:1.5:15,300:30:600); domain = struct('alpha',alpha,'V',V); shapefcn = @(x,y) [x,y,x*y]; GS = tunableSurface('GS',ones(2,2),domain,shapefcn);

Setting the initial constant coefficient to `ones(2,2)`

causes `tunableSurface`

to generate a 2-by-2 gain matrix. Each entry in that matrix is an independently tunable gain surface that is a bilinear function of two scheduling variables. In other words, the gain surface is given by:

$$GS={K}_{0}+{K}_{1}\alpha +{K}_{2}V+{K}_{3}\alpha V,$$

where each of the coefficients $${K}_{0},\dots ,{K}_{3}$$ is itself a 2-by-2 matrix.

Typically, you would tune the coefficients of those gain surfaces as part of a control system. For this example, instead of tuning, manually set the coefficients to non-zero values.

K0 = 10*rand(2); K1 = 10*rand(2); K2 = 10*rand(2); K3 = 10*rand(2);

The `tunableSurface`

object stores array-valued coefficients by concatenating them into a 2-by-8 array (see the `tunableSurface`

reference page). Therefore, concatenate these values of $${K}_{0},\dots ,{K}_{3}$$ to change the coefficients of `GS`

.

GS = setData(GS,[K0 K1 K2 K3]);

Now evaluate the gain surface at selected values of the scheduling variables.

alpha_vec = [7:1:13]; % N1 = 7 points V_vec = [400:25:625]; % N2 = 10 points GV = evalSurf(GS,alpha_vec,V_vec,'gridlast');

The `'gridlast'`

orders the array `GV`

such that the dimensions of the grid of gain values, 7-by-10, are last. The dimensions of the gain array itself, 2-by-2, are first.

size(GV)

`ans = `*1×4*
2 2 7 10

## Input Arguments

`GS`

— Gain surface

`tunableSurface`

object

Gain surface to evaluate, specified as a `tunableSurface`

object. `GS`

can
have any number of scheduling variables, and can be scalar-valued
or array-valued.

`X`

— Points

array

Points at which to evaluate the gain surface, specified as an
array. A point is a combination of scheduling-variable values. `X`

has
dimensions *N*-by-*M*, where *M* is
the number of scheduling variables in `GS`

and *N* is
the number of points at which to evaluate `GS`

.
Thus, `X`

is a list of scheduling-variable-value
combinations at which to evaluate the gain. For example, suppose `GS`

has
two scheduling variables, `a`

and `b`

,
and you want to evaluate `GS`

at 10 (`a`

,`b`

)
pairs. In that case, `X`

is a 10-by-2 array that
lists the (`a`

,`b`

). The points
in `X`

need not match the design points in `GS.SamplingGrid`

.

`X1,...,XM`

— Scheduling-variable values

arrays

Scheduling-variable values at which to evaluate the gain surface,
specified as *M* arrays, where *M* is
the number of scheduling variables in `GS`

. For
example, if `GS`

has two scheduling variables, `a`

and `b`

,
then `X1`

and `X2`

are vectors of `a`

and `b`

values,
respectively. The gain surface is evaluated over the grid `ndgrid(X1,X2)`

.
The values in that grid need not match the design points in `GS.SamplingGrid`

.

`gridflag`

— Layout of output array

`'gridfirst'`

(default) | `'gridlast'`

Layout of output array, specified as either `'gridfirst'`

or `'gridlast'`

.

`'gridfirst'`

—`GV`

is of size`[N1,...,NM,Ny,Nu]`

with the grid dimensions first and the gain dimensions last. This layout is the natural format for a scalar gain, where`Ny = Nu = 1`

.`'gridlast'`

—`GV`

is of size`[Ny,Nu,N1,...,NM]`

with the gain dimensions first. This format is more readable for matrix-valued gains.

## Output Arguments

`GV`

— Gain values

array

Gain values, returned as an array. `GV`

contains
the gain evaluated at the points (scheduling-variable values) specified
by `X`

or `X1,...,XM`

. The size
of `GV`

depends on the number of scheduling variables
in `GS`

, the I/O dimensions of the gain defined
by `GS`

, and the value of `gridflag`

.

If you compute the gain at a list of `N`

points
specified in an array `X`

, then the size of `GV`

is `[N,Ny,Nu]`

.
Here, `[Ny,Nu]`

are the I/O dimensions of the gain.
For example, suppose `GS`

is a scalar gain surface
with two scheduling variables, `a`

and `b`

,
and `X`

is a 10-by-2 array containing 10 `(a,b)`

pairs.
Then `GV`

is a column vector of ten values.

If you compute the gain over a grid specified by vectors `X1,...,XM`

,
then the dimensions of `GV`

depend on the value
of `gridflag`

.

`gridflag = 'gridfirst'`

(default) — The size of`GV`

is`[N1,...,NM,Ny,Nu]`

. Each`Ni`

is the length of`Xi`

, the number of values of the i-th scheduling variable. For example, suppose`GS`

is a scalar gain surface with two scheduling variables,`a`

and`b`

, and`X1`

and`X2`

are vectors of 4`a`

values and 5`b`

values, respectively. Then, the size of`GV`

is [4,5,1,1] or equivalently, [4,5]. Or, if`GS`

is a three-output, two-input vector-valued gain, then the size of`GV`

is [4,5,3,2].`gridflag = 'gridlast'`

— The size of`GV`

is`[Ny,Nu,N1,...,NM]`

. For example, suppose`GS`

is a scalar gain surface with two scheduling variables,`a`

and`b`

, and`X1`

and`X2`

are vectors of 4`a`

values and 5`b`

values, respectively. Then, the size of`GV`

is [1,1,4,5]. Or, if`GS`

is a three-output, two-input vector-valued gain, then the size of`GV`

is [3,2,4,5].

## Tips

## Version History

**Introduced in R2015b**

## See Also

`tunableSurface`

| `viewSurf`

| `getData`

| `setData`

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)