Documentation

slTuner

Interface for control system tuning of Simulink models

Syntax

  • st = slTuner(mdl,tuned_blocks)
  • st = slTuner(mdl,tuned_blocks,pt)
  • st = slTuner(mdl,tuned_blocks,param)
  • st = slTuner(mdl,tuned_blocks,op)
  • st = slTuner(mdl,tuned_blocks,blocksub)
  • st = slTuner(mdl,tuned_blocks,options)
  • st = slTuner(mdl,tuned_blocks,pt,op,param,blocksub,options)

Description

st = slTuner(mdl,tuned_blocks) creates an slTuner interface, st, for tuning the control system blocks of the Simulink® model, mdl. The interface adds the linear analysis points marked in the model as analysis points of st. The interface also adds the linear analysis points that imply an opening as permanent openings. When the interface performs linearization, for example, to tune the blocks, it uses the model initial condition as the operating point.

st = slTuner(mdl,tuned_blocks,pt) adds the specified point to the list of analysis points for st, ignoring linear analysis points marked in the model.

st = slTuner(mdl,tuned_blocks,param) specifies the parameters whose values you want to vary when tuning the model blocks.

st = slTuner(mdl,tuned_blocks,op) specifies the operating points for tuning the model blocks.

st = slTuner(mdl,tuned_blocks,blocksub) specifies substitute linearizations of blocks and subsystems. Use this syntax, for example, to specify a custom linearization for a block. You can also use this syntax for blocks that do not linearize successfully, such as blocks with discontinuities or triggered subsystems.

st = slTuner(mdl,tuned_blocks,options) configures the linearization algorithm options.

st = slTuner(mdl,tuned_blocks,pt,op,param,blocksub,options) uses any combination of the input arguments pt, op, param, blocksub, and options to create st. For example, you can use:

  • st = slTuner(mdl,tuned_blocks,pt,param)

  • st = slTuner(mdl,tuned_blocks,op,param).

Object Description

slTuner provides an interface between a Simulink model and the tuning commands systune and looptune. slTuner allows you to:

  • Specify the control architecture.

  • Designate and parameterize blocks to be tuned.

  • Tune the control system.

  • Validate design by computing (linearized) open-loop and closed-loop responses.

  • Write tuned values back to the model.

Because tuning commands such as systune operate on linear models, the slTuner interface automatically computes and stores a linearization of your Simulink model. This linearization is automatically updated when you change any properties of the slTuner interface. The update occurs when you call commands that query the linearization stored in the interface. Such commands include systune, looptune, getIOTransfer, and getLoopTransfer. For more information about linearization, see What Is Linearization?

Examples

collapse all

Create and configure an slTuner interface for a Simulink® model that specifies which blocks to tune with systune or looptune.

Open the Simulink model.

mdl = 'scdcascade';
open_system(mdl);

The control system consists of two feedback loops, an inner loop with PI controller C2, and an outer loop with PI controller C1. Suppose you want to tune this model to meet the following control objectives:

  • Track setpoint changes to r at the system output y1m with zero steady-state error and specified rise time.

  • Reject the disturbance represented by d2.

The systune command can jointly tune the controller blocks to meet these design requirements, which you specify using TuningGoal objects. The slTuner interface sets up this tuning task.

Create an slTuner interface for the model.

st = slTuner(mdl,{'C1','C2'});

This command initializes the slTuner interface and designates the two PI controller blocks as tunable. Each tunable block is automatically parameterized according to its type and initialized with its value in the Simulink model. A linearization of the remaining, nontunable portion of the model is computed and stored in the slTuner interface.

To configure the slTuner interface, designate as analysis points any signal locations of relevance to your design requirements. Add the output and reference input for the tracking requirement. Also, add the disturbance-rejection location.

addPoint(st,{'r','y1m','d2'});

These locations in your model are now available for referencing in TuningGoal objects that capture your design goals.

Display a summary of the slTuner interface configuration in the command window.

st
 
slTuner tuning interface for "scdcascade":

2 Tuned blocks: (Read-only TunedBlocks property) 
--------------------------
Block 1: scdcascade/C1
Block 2: scdcascade/C2
 
3 Analysis points: 
--------------------------
Point 1: Signal "r", located at port 1 of scdcascade/setpoint
Point 2: Signal "y1m", located at port 1 of scdcascade/Sum
Point 3: Port 1 of scdcascade/d2
 
No permanent openings. Use the addOpening command to add new permanent openings.
Properties with dot notation get/set access:
      Parameters         : [] 
      OperatingPoints    : [] (model initial condition will be used.)
      BlockSubstitutions : []
      Options            : [1x1 linearize.SlTunerOptions]
      Ts                 : 0

The display lists the designated tunable blocks, analysis points, and other information about the interface. In the command window, click on any highlighted signal to see its location in the Simulink model. Note that specifying the block name 'd2' in the addPoint command is equivalent to designating that block's single output signal as the analysis point.

You can now capture your design goals with TuningGoal objects and use systune or looptune to tune the control system to meet those design goals.

In addition to specifying design goals, you can use analysis points for extracting system responses. For example, extract and plot the step response between the reference signal 'r' and the output 'y1m'.

T = getIOTransfer(st,'r','y1m');
stepplot(T)

Input Arguments

collapse all

Simulink model name, specified as a character vector.

Example: 'scdcascade'

Blocks to be added to the list of tuned blocks of st, specified as:

  • Character vector— Block path. You can specify the full block path or a partial path. The partial path must match the end of the full block path and unambiguously identify the block to add. For example, you can refer to a block by its name, provided the block name appears only once in the Simulink model.

    For example, blk = 'scdcascade/C1'.

  • Cell array of character vectors — Multiple block paths.

    For example, blk = {'scdcascade/C1','scdcascade/C2'}.

Analysis point to be added to the list of analysis points for st, specified as:

  • Character vector— Analysis point identifier that can be any of the following:

    • Signal name, for example pt = 'torque'

    • Block path for a block with a single output port, for example pt = 'Motor/PID'

    • Block path and port originating the signal, for example pt = 'Engine Model/1'

  • Cell array of character vectors— Specifies multiple analysis point identifiers. For example:

    pt = {'torque','Motor/PID','Engine Model/1'}
  • Vector of linearization I/O objects — Create pt using linio. For example:

    pt(1) = linio('scdcascade/setpoint',1,'input');
    pt(2) = linio('scdcascade/Sum',1,'output');

    Here, pt(1) specifies an input, and pt(2) specifies an output.

    The interface adds all the points specified by pt and ignores their I/O types. The interface also adds all 'loopbreak' type signals as permanent openings.

Parameter samples for linearizing mdl, specified as:

  • Structure — Vary the value of a single parameter by specifying param as a structure with the following fields:

    • Name — Parameter name, specified as a character vector. You can specify any model parameter that is a variable in the model workspace, the MATLAB® workspace, or a data dictionary. 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, to use the first element of vector V as a parameter, use:

      param.Name = 'V(1)';
    • Value — Parameter sample values, specified as a double array.

    For example, vary the value of parameter A in the 10% range:

    param.Name = 'A';
    param.Value = linspace(0.9*A,1.1*A,3);
  • Structure array — Vary the value of multiple parameters. For example, vary the values of parameters A and b in the 10% range:

    [A_grid,b_grid] = ndgrid(linspace(0.9*A,1.1*A,3),...
                             linspace(0.9*b,1.1*b,3));
    params(1).Name = 'A';
    params(1).Value = A_grid;
    params(2).Name = 'b';
    params(2).Value = b_grid;

For more in information, see Specify Parameter Samples for Batch Linearization.

If param specifies tunable parameters only, then the software batch linearizes the model using a single compilation. If you also configure st.OperatingPoints with operating point objects only, the software uses single model compilation.

For an example showing how batch linearization with parameter sampling works, see Vary Parameter Values and Obtain Multiple Transfer Functions. That example uses slLinearizer, but the process is the same for slTuner.

To compute the offsets required by the LPV System block, specify param, and set st.Options.StoreOffsets to true. You can then return additional linearization information when calling linearization functions such as getIOTransfer, and extract the offsets using getOffsetsForLPV.

Operating point for linearizing mdl, specified as:

If you configure st.Parameters, then specify op as one of the following:

  • Single operating point.

  • Array of operating point objects whose size matches that of the parameter grid specified by the Parameters property. When you batch linearize mdl, the software uses only one model compilation. To obtain the operating points that correspond to the parameter value combinations, batch trim your model using param before linearization. For an example that uses the To obtain the operating points that correspond to the parameter value combinations, batch trim your model using param before linearization. For an example that uses the linearize command, see Batch Linearize Model at Multiple Operating Points Derived from Parameter Variations.

  • Multiple snapshot times. When you batch linearize mdl, the software simulates the model for each snapshot time and parameter grid point combination. This operation can be computationally expensive.

Substitute linearizations for blocks and model subsystems, specified as a structure or an n-by-1 structure array, where n is the number of blocks for which you want to specify a linearization. Use blocksub to specify a custom linearization for a block or subsystem. For example, you can specify linearizations for blocks that do not have analytic linearizations, such as blocks with discontinuities or triggered subsystems.

You can batch linearize your model by specifying multiple substitute linearizations for a block. Use this functionality, for example, to study the effects of varying the linearization of a Saturation block on the model dynamics.

Each substitute linearization structure has the following fields:

Block path of the block for which you want to specify the linearization, specified as a character vector.

Substitute linearization for the block, specified as one of the following:

  • Double — Specify the linearization of a SISO block as a gain.

  • Array of doubles — Specify the linearization of a MIMO block as an nu-by-ny array of gain values, where nu is the number of inputs and ny is the number of outputs.

  • LTI model, uncertain state-space model, or uncertain real object — The I/O configuration of the specified model must match the configuration of the block specified by Name. Using an uncertain model requires Robust Control Toolbox™ software.

  • Array of LTI models, uncertain state-space models, or uncertain real objects — Batch linearize the model using multiple block substitutions. The I/O configuration of each model in the array must match the configuration of the block for which you are specifying a custom linearization. If you:

    • Vary model parameters using param and specify Value as a model array, the dimensions of Value must match the parameter grid size.

    • Define block substitutions for multiple blocks, and specify Value as an array of LTI models for more than one block, the dimensions of the arrays must match.

  • Structure with the following fields:

    FieldDescription
    Specification

    Block linearization, specified as a character vector that contains one of the following

    The specified expression or function must return one of the following:

    • Linear model in the form of a D-matrix

    • Control System Toolbox™ LTI model object

    • Uncertain state-space model or uncertain real object (requires Robust Control Toolbox software)

    The I/O configuration of the returned model must match the configuration of the block specified by Name.

    Type

    Specification type, specified as one of the following:

    • 'Expression'

    • 'Function'

    ParameterNames

    Linearization function parameter names, specified as a cell array of character vectors. Specify ParameterNames only when Type = 'Function' and your block linearization function requires input parameters. These parameters only impact the linearization of the specified block.

    You must also specify the corresponding blocksub.Value.ParameterValues field.

    ParameterValues

    Linearization function parameter values, specified as a vector of doubles. The order of parameter values must correspond to the order of parameter names in blocksub.Value.ParameterNames. Specify ParameterValues only when Type = 'Function' and your block linearization function requires input parameters.

slTuner options, specified as an slTunerOptions option set.

Example: options = slTunerOptions('IgnoreDiscreteStates','on')

Properties

slTuner object properties include:

TunedBlocks

Blocks to be tuned in mdl, specified as a cell array of character vectors.

When you create an slTuner interface, the TunedBlocks property is automatically populated with the blocks you specify in the tuned_blocks input argument. To specify additional tunable blocks in an existing slTuner interface, use addBlock.

Ts

Sampling time for analyzing and tuning mdl, specified as nonnegative scalar.

Set this property using dot notation (st.Ts = Ts).

Default: 0 (implies continuous-time)

Parameters

Parameter samples for linearizing mdl, specified as a structure or a structure array.

Set this property using the param input argument or dot notation (st.Parameters = param). param must be one of the following:

If param specifies tunable parameters only, then the software batch linearizes the model using a single compilation. If you also configure st.OperatingPoints with operating point objects only, the software uses single model compilation.

OperatingPoints

Operating points for linearizing mdl, specified as an operating point object, array of operating point objects, or array of positive scalars.

Set this property using the op input argument or dot notation (st.OperatingPoints = op). op must be one of the following:

If you configure st.Parameters, then specify op as one of the following:

  • Single operating point.

  • Array of operating point objects whose size matches that of the parameter grid specified by the Parameters property. When you batch linearize mdl, the software uses only one model compilation. To obtain the operating points that correspond to the parameter value combinations, batch trim your model using param before linearization. For an example that uses the To obtain the operating points that correspond to the parameter value combinations, batch trim your model using param before linearization. For an example that uses the linearize command, see Batch Linearize Model at Multiple Operating Points Derived from Parameter Variations.

  • Multiple snapshot times. When you batch linearize mdl, the software simulates the model for each snapshot time and parameter grid point combination. This operation can be computationally expensive.

BlockSubstitutions

Substitute linearizations for blocks and model subsystems, specified as a structure or structure array.

Use this property to specify a custom linearization for a block or subsystem. You also can use this syntax for blocks that do not have analytic linearizations, such as blocks with discontinuities or triggered subsystems.

Set this property using the blocksub input argument or dot notation (st.BlockSubstitutions = blocksubs). For information about the required structure, see blocksub.

Options

Linearization algorithm options, specified as an option set created using slTunerOptions.

Set this property using the opt input argument or dot notation (st.Options = opt).

Model

Name of the Simulink model to be linearized, specified as a character vector by the input argument mdl.

TimeUnit

Unit of the time variable. This property specifies the time units for linearized models returned by getIOTransfer, getLoopTransfer, getSensitivity, and getCompSensitivity. Use any of the following values:

  • 'nanoseconds'

  • 'microseconds'

  • 'milliseconds'

  • 'seconds'

  • 'minutes'

  • 'hours'

  • 'days'

  • 'weeks'

  • 'months'

  • 'years'

Default: 'seconds'

More About

collapse all

Analysis Points

Analysis points, used by the slLinearizer and slTuner interfaces, identify locations within a model that are relevant for linear analysis and control system tuning. You use analysis points as inputs to the linearization commands, such as getIOTransfer, getLoopTransfer, getSensitivity, and getCompSensitivity. As inputs to the linearization commands, analysis points can specify any open-loop or closed-loop transfer function in a model. You can also use analysis points to specify design requirements when tuning control systems using commands such as systune.

Location refers to a specific block output port within a model or to a bus element in such an output port. For convenience, you can use the name of the signal that originates from this port to refer to an analysis point.

You can add analysis points to an slLinearizer or slTuner interface, s, when you create the interface. For example:

s = slLinearizer('scdcascade',{'u1','y1'});

Alternatively, you can use the addPoint command.

To view all the analysis points of s, type s at the command prompt to display the interface contents. For each analysis point of s, the display includes the block name and port number and the name of the signal that originates at this point. You can also programmatically obtain a list of all the analysis points using getPoints.

For more information about how you can use analysis points, see Marking Signals of Interest for Control System Analysis and Design.

Permanent Openings

Permanent openings, used by the slLinearizer and slTuner interfaces, identify locations within a model where the software breaks the signal flow. The software enforces these openings for linearization and tuning. Use permanent openings to isolate a specific model component. Suppose that you have a large-scale model capturing aircraft dynamics and you want to perform linear analysis on the airframe only. You can use permanent openings to exclude all other components of the model. Another example is when you have cascaded loops within your model and you want to analyze a specific loop.

Location refers to a specific block output port within a model. For convenience, you can use the name of the signal that originates from this port to refer to an opening.

You can add permanent openings to an slLinearizer or slTuner interface, s, when you create the interface or by using the addOpening command. To remove a location from the list of permanent openings, use the removeOpening command.

To view all the openings of s, type s at the command prompt to display the interface contents. For each permanent opening of s, the display includes the block name and port number and the name of the signal that originates at this location. You can also programmatically obtain a list of all the permanent loop openings using getOpenings.

Custom Linearization Function

You can specify a substitute linearization for a block or subsystem in your Simulink model using a custom function on the MATLAB path.

Your custom linearization function, must have one input argument, BlockData, which is a structure that the software creates and passes to the function. BlockData has the following fields:

FieldDescription
BlockNameName of the block for which you are specifying a custom linearization.
ParametersBlock parameter values, specified as a structure array with Name and Value fields. Parameters contains the names and values of the parameters you specify in the blocksub.Value.ParameterNames and blocksub.Value.ParameterValues fields.
InputsInput signals to the block for which you are defining a linearization, specified as a structure array with one structure for each block input. Each structure in Inputs has the following fields:
FieldDescription
BlockNameFull block path of the block whose output connects to the corresponding block input.
PortIndexOutput port of the block specified by BlockName that connects to the corresponding block input.
ValuesValue of the signal specified by BlockName and PortIndex. If this signal is a vector signal, then Values is a vector with the same dimension.

nyNumber of output channels of the block linearization.
nuNumber of input channels of the block linearization.
BlockLinearizationCurrent default linearization of the block, specified as a state-space model. You can specify a block linearization that depends on the default linearization using BlockLinearization.

Your custom function must return a model with nu inputs and ny outputs. This model must be one of the following:

  • Linear model in the form of a D-matrix

  • Control System Toolbox LTI model object

  • Uncertain state-space model or uncertain real object (requires Robust Control Toolbox software)

For example, the following function multiplies the current default block linearization by a delay of Td = 0.5 seconds. The delay is represented by a Thiran filter with sample time Ts = 0.1. The delay and sample time are parameters stored in BlockData.

function sys = myCustomFunction(BlockData)
    Td = BlockData.Parameters(1).Value;
    Ts = BlockData.Parameters(2).Value;
    sys = currentSys*Thiran(Td,Ts);
end 

Save this function to a location on the MATLAB path.

To use this function as a custom linearization for a block or subsystem, specify the blocksub.Value.Specification and blocksub.Value.Type fields.

blocksub.Value.Specification = 'myCustomFunction';
blocksub.Value.Specification = 'Function';

To set the delay and sample time parameter values, specify the blocksub.Value.ParameterNames and blocksub.Value.ParameterValues fields.

blocksub.Value.ParameterNames = {'Td','Ts'};
blocksub.Value.ParameterValues = [0.5 0.1];

Algorithms

slTuner linearizes your Simulink model using the algorithms described in Exact Linearization Algorithm.

Introduced in R2014a

Was this topic helpful?