# evalSurf

Evaluate gain surfaces at specific design points

## Syntax

``GV = evalSurf(GS,X)``
``GV = evalSurf(GS,X1,...,XM)``
``GV = evalSurf(___,gridflag)``

## Description

example

````GV = evalSurf(GS,X)` evaluates a gain surface at the list of points specified in the array `X`. A point is a combination of scheduling-variable values. Thus `X` is an N-by-M array, where N is the number of points at which to evaluate the gain, and M is the number of scheduling variables in `GS`.```

example

````GV = evalSurf(GS,X1,...,XM)` evaluates the gain surface over the rectangular grid generated by the vectors `X1,...,XM`. Each vector contains values for one scheduling variable of `GS`. ```

example

````GV = evalSurf(___,gridflag)` specifies the layout of `GV`. ```

## Examples

collapse all

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

collapse all

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.

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

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

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

collapse all

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

## Version History

Introduced in R2015b