evalSurf

Evaluate gain surfaces at specific design points

Syntax

GV = evalSurf(GS,X)

GV = evalSurf(GS,X1,...,XM)

GV = evalSurf(___,gridflag)

Description

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.

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.

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

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

• Use evalSurf to turn tuned gain surfaces into lookup tables. Set X1,...,XM to the desired table breakpoints and use GV as table data. The table breakpoints do not need to match the design points used for tuning GS.