Specify Parameter Samples for Batch Linearization

Block parameters configure a Simulink^® model in several ways. For example, you can use block parameters to specify various coefficients or controller sample times. You can also use a discrete parameter, like the control input to a Multiport Switch block, to control the data path within a model. Varying the value of a parameter helps you understand its impact on the model behavior.

When using any of the Simulink Control Design™ linearization tools (or tuning with slTuner or Control System Tuner) you can specify a set of block parameter values at which to linearize the model. The full set of values is called a parameter grid or parameter samples. The tools batch-linearize the model, computing a linearization for each value in the parameter grid. You can vary multiple parameters, thus extending the parameter grid dimension. When using the command-line linearization tools, including the linearize command and the slLinearizer and slTuner interfaces, you specify the parameter samples using a structure with fields Name and Value. In the Model Linearizer and Control System Tuner apps, you specify parameter samples interactively using the graphical interface.

Which Parameters Can Be Sampled?

You can vary any model parameter whose value is given by a variable in the model workspace, the MATLAB^® workspace, or a data dictionary. In cases where the varying parameters are all tunable, the linearization tools require only one model compilation to compute transfer functions for varying parameter values. This efficiency is especially advantageous for models that are expensive to compile repeatedly.

For more information, see Batch Linearization Efficiency When You Vary Parameter Values.

Multi-Dimension Parameter Grids

When you vary more than one parameter at a time, you generate parameter grids of higher dimension. For example, varying two parameters yields a parameter matrix, and varying three parameters yields a 3-D parameter grid. Consider the following parameter grid:

Here, you vary the values of three parameters, a, b, and c. The samples form a 3-by-4-by-5 grid. When batch linearizing your model, the ss model array, sys, is the batch result. Similarly, when batch trimming your model, you get an array of operating point objects.

Vary Parameters at the Command Line

To vary the value of a single parameter for batch linearization with linearize, slLinearizer, or slTuner, specify the parameter grid as a structure having two fields. The Name field contains the name of the workspace variable that specifies the parameter. The Value field contains a vector of values for that parameter to take during linearization.

For example, the Watertank model has three parameters defined as MATLAB workspace variables, a, b, and A. The following commands specify a parameter grid for the single parameter for A.

param.Name = 'A';
param.Value = Avals;

Here, Avals is an array specifying the sample values for A.

The following table lists some common ways of specifying parameter samples.

Parameter Sample-Space Type	How to Specify the Parameter Samples
Evenly spaced values across a given range	`param.Value = [Amin:1:Amax]`
Linearly spaced values across a given range	`param.Value = linspace(Amin,Amax,N)`
Logarithmically spaced values across a given range	`param.Value = logspace(Amin,Amax,N)`
Random values	`param.Value = rand(1,N)`
Custom vector	`param.Value = [value1,value2,...,valueN]`

If the variable used by the model is not a scalar variable, specify the parameter name as an expression that resolves to a numeric scalar value. For example, suppose that Kpid is a vector of PID gains. The first entry in that vector, Kpid, is used as a gain value in a block in your model. Use the following commands to vary that gain using the values given in a vector Kpvals:

param.Name = 'Kpid(1)';
param.Value = Kpvals;

After you create the structure param:

Pass it to linearize as the param input argument.
Set it as the Parameters property of an slLinearizer or slTuner interface.

To vary the value of multiple parameters for batch linearization with linearize, slLinearizer, or slTuner, specify parameter samples as a structure array. The structure has an entry for each parameter whose value you vary. Each element of the structure array has a Name and Value field.

You can specify the Value field for a parameter to be an array of any dimension. However, the size of the Value field must match for all parameters. Corresponding array entries for all the parameters, also referred to as a parameter grid point, must map to a desired parameter combination. When the software linearizes the model, it computes a linearization — an ss model — for each grid point. The software populates the SamplingGrid property of each linearized model with information about the parameter grid point that the model corresponds to.

Specify Full Grid

Suppose that your model has two parameters whose values you want to vary, a and b:

$\begin{array}{l} a = {a 1, a 2} \\ b = {b 1, b 2} \end{array}$

You want to linearize the model for every combination of a and b, also referred to as a full grid:

${\begin{matrix} (a_{1}, b_{1}), & (a_{1}, b_{2}) \\ (a_{2}, b_{1}), & (a_{2}, b_{2}) \end{matrix}}$

Create a rectangular parameter grid using ndgrid.

a1 = 1;
a2 = 2;
a = [a1 a2];

b1 = 3;
b2 = 4;
b = [b1 b2];

[A,B] = ndgrid(a,b)

Create the structure array, params, that specifies the parameter grid.

params(1).Name = 'a';
params(1).Value = A;

params(2).Name = 'b';
params(2).Value = B;

In general, to specify a full grid for N parameters, use ndgrid to obtain N grid arrays.

[P1,...,PN] = ndgrid(p1,...,pN);

Here, p₁,...,p_N are the parameter sample vectors.

Create a 1 x N structure array.

params(1).Name = 'p1';
params(1).Value = P1;
...
params(N).Name = 'pN';
params(N).Value = PN;

Specify Subset of Full Grid

If your model is complex or you vary the value of many parameters, linearizing the model for the full grid can become expensive. In this case, you can specify a subset of the full grid using a table-like approach. Using the example in Specify Full Grid, suppose you want to linearize the model for the following combinations of a and b:

${(a_{1}, b_{1}), (a_{1}, b_{2})}$

Create the structure array, params, that specifies this parameter grid.

A = [a1 a1];
params(1).Name = 'a';
params(1).Value = A;

B = [b1 b2];
params(2).Name = 'b';
params(2).Value = B;

Vary Parameters in Graphical Tools

To select parameters to vary for batch linearization, in the Parameter Variations drop-down list, click Select parameters to vary. In Model Linearizer, the Parameter Variations drop-down list is on the Linear Analysis tab. In Control System Tuner, the Parameter Variations drop-down list is on the Control System tab.

On the Parameter Variations tab, click Manage Parameters. In the Select model variables dialog box, select the variables you want to vary. The table lists all variables in the MATLAB workspace and the model workspace that are used in the model, whether tunable or not.

If your model contains many variables, filter the list by typing in the Filter by variable name field. The Used By column lists all blocks in the model that use the variable. To highlight blocks in the model that use a variable, click the corresponding block name.

The variables that you select for variation must have a numeric scalar value that uses the data type double. If the value of a variable does not meet these conditions, use these techniques:

To vary a single element of a matrix or array variable, in the Add new parameter by indexing/expression with existing one field, enter an expression that resolves to a numeric scalar value and press Enter key. For example, if A is a vector, enter A(3) to specify the third entry in A. If A is a structure and the scalar parameter you want to vary is the Value field of that structure, enter A.Value. The indexed variable appears in the variable list.
To use a variable of a numeric data type other than double, convert the variable to a Simulink.Parameter object, which separates a parameter value from its data type. Set the Value property to a default double number, and use the DataType property to control the data type.
To use the value of a Simulink.Parameter object, specify the Value property. Enter the expression myParamObj.Value.
To use a field of a structure, enter myStruct.PID.P1. If you store the structure in a Simulink.Parameter object, enter myStruct.Value.PID.P1.
To use one cell of a cell array, enter myCells{3}.

After you select variables, click OK. The selected variables appear in the Parameter Variations table with initial sample values based on the current values of the parameters.

When varying a single parameter, each row of the table corresponds to a single parameter value for which to linearize the model.

When varying multiple parameters:

Each column in the table corresponds to one selected variable.
Each row in the table represents one full set of parameter values for which to linearize the model.

Use the table to specify parameter values manually or generate values automatically. When you linearize the model, the software computes as many linear models as there are rows in the table.

After you specify the parameter values, when you return to the Linear Analysis tab and linearize the model, Model Linearizer linearizes the model at all parameter values listed in the Parameter Variations table. For example, the following figure shows

Note

In Control System Tuner, when you finish specifying your parameter variations, you must apply the changes before continuing with tuning. To do so, on the Parameter Variations tab, click Apply. Control System Tuner applies the specified parameter variations, relinearizes your model, and updates all existing plots.

Manually Specify Parameter Values

To specify parameter values manually, add rows to the table by clicking Insert Row and selecting either Insert Row Above or Insert Row Below.

Then, edit the values in the table as needed. For example, the following table specifies four parameter-value pairs for (Ki2,Kp2) = (3.5,1), (3.5,2), (5,1), and (5,2).

Automatically Generate Parameter Values

To generate values automatically, on the Parameter Variations tab, click Generate Values.

In the Generate Parameter Values dialog box, select one of the following gridding methods:

All Combinations — Generate all possible combinations of the values specified in the Starting Values table.
Min-Max Combinations — Generate parameter samples using only the minimum and maximum values of each vector specified in the Starting Values table.
Pair-Wise Combinations — Generate parameter samples using only pair-wise combinations of the values in the vectors specified in the Starting Values table. This method is available only when all vectors in the table have the same dimensions.

In the Generate Parameter Values dialog box, in the Starting Values table, specify the base values for parameter grid generation. In the Values column, enter an expression for the base values you want for each variable. The following table lists some common ways of specifying parameter samples.

Parameter Sample-Space Type	How to Specify the Parameter Samples
Evenly spaced values across a given range	`[Amin:1:Amax]`
Linearly spaced values across a given range	`linspace(Amin,Amax,N)`
Logarithmically spaced values across a given range	`logspace(Amin,Amax,N)`
Random values	`rand(1,N)`
Custom vector	`[value1,value2,...,valueN]`

For example, the following figure shows the settings for generating parameter-value pairs for all possible combinations of Kp1 = [0.1,0.15,0.2,0.25,0.3] and Kp2 = [0.03,0.04,0.05].

To replace the values in the Parameter Variations table with the generated values, select Overwrite previous values. To append the generated values to the existing values, select Append to previous values.

Click OK.