Main Content

slTuner

Interface for control system tuning of Simulink models

    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 as systune, looptune, getIOTransfer, and getLoopTransfer.

    You can configure the slTuner interface to linearize a model at a range of operating points and specify variations for model parameter values. You can use analysis points and permanent openings to obtain linearizations for any open-loop or closed-loop transfer function from a model. You can then analyze the stability, or time-domain or frequency-domain characteristics of the linearized models.

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

    Creation

    Description

    example

    st = slTuner(model,tunedBlocks) returns an slTuner interface for tuning the control system blocks specified by tunedBlocks in the Simulink model model and sets the Model and TunedBlocks properties. The interface adds the linear analysis points marked in the model as analysis points and also adds the linear analysis points that imply an opening as permanent openings.

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

    st = slTuner(model,tunedBlocks,param) specifies the parameters whose values you want to vary when linearizing the model and sets the Parameters property to param.

    st = slTuner(model,tunedBlocks,op) specifies the operating points for linearizing the model and sets the OperatingPoints property to op.

    st = slTuner(model,tunedBlocks,blocksub) specifies substitute linearizations of blocks and subsystems and sets the BlockSubstitutions property to blocksub. 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(model,tunedBlocks,opt) configures the linearization algorithm options and sets the Options property to opt.

    st = slTuner(model,tunedBlocks,pt,op,param,blocksub,options) creates an slTuner interface using any combination of pt, op, param, blocksub, and options in any order.

    If you do not specify pt, the interface adds the linear analysis points marked in the model as analysis points. The interface also adds linear analysis points that imply an opening as permanent openings.

    Input Arguments

    expand all

    Analysis points to add to the slTuner interface, specified as one of the following:

    • Character vector or string — 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 or string array — 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 signals that imply a loop opening as permanent openings.

    For more information, see Analysis Points and Permanent Openings.

    Properties

    expand all

    Model name, specified as a character vector or string.

    Blocks to be added to the list of tuned blocks in the slTuner interface, specified as one of the following:

    • Character vector or string — 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 or string array — Multiple block paths.

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

    Tuning options, specified as an slTunerOptions object.

    Sample time for analyzing and tuning model, specified as nonnegative scalar.

    Operating point for linearizing model, specified as:

    • OperatingPoint or OperatingReport object, created using findop with either a single operating point specification, or a single snapshot time.

    • Array of OperatingPoint or OperatingReport objects, specifying multiple operating points.

      To create an array of OperatingPoint or OperatingReport objects, you can:

    • Vector of positive scalars, specifying simulation snapshot times.

    If you configure the Parameters property, then specify OperatingPoints as one of the following:

    • Single OperatingPoint or OperatingReport object.

    • Array of OperatingPoint or OperatingReport 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 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.

    If you do not specify OperatingPoints, the slLinearizer interface uses the model initial condition.

    Parameter samples for linearizing model, specified as:

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

      • Name — Parameter name, specified as a character vector or string. 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, use the first element of vector V as a parameter.

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

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

      parameters.Name = 'A';
      parameters.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));
      parameters(1).Name = 'A';
      parameters(1).Value = A_grid;
      parameters(2).Name = 'b';
      parameters(2).Value = b_grid;

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

    If Parameters specifies tunable parameters only, then the software batch linearizes the model using a single compilation. If you also configure the OperatingPoints property 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 Parameters, and set Options.StoreOffsets to true. You can then return additional linearization information when calling linearization functions such as getIOTransfer, and extract the offsets using getOffsetsForLPV.

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

    To study the effects of varying the linearization of a block on the model dynamics, you can batch linearize your model by specifying multiple substitute linearizations for a block.

    If you substitute a linearization with a sample time that differs from that of the original block or subsystem, it is best practice to set the overall linearization sample time (Options.SampleTime) to a nondefault value.

    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 or string.

    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 the Parameters property 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 ParameterValues field.

      ParameterValues

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

    Time units for linearized models computed by getIOTransfer, getLoopTransfer, getSensitivity, and getCompSensitivity, specified as one of the following values.

    • 'nanoseconds'

    • 'microseconds'

    • 'milliseconds'

    • 'seconds'

    • 'minutes'

    • 'hours'

    • 'days'

    • 'weeks'

    • 'months'

    • 'years'

    Object Functions

    addBlockAdd block to list of tuned blocks for slTuner interface
    addOpeningAdd signal to list of openings for slLinearizer or slTuner interface
    addPointAdd signal to list of analysis points for slLinearizer or slTuner interface
    getPointsGet list of analysis points for slLinearizer or slTuner interface
    getOpeningsGet list of openings for slLinearizer or slTuner interface
    getBlockParamGet parameterization of tuned block in slTuner interface
    getBlockValueGet current value of tuned block parameterization in slTuner interface
    getTunedValueGet current value of tuned variable in slTuner interface
    getBlockRateConversionGet rate conversion settings for tuned block in slTuner interface
    setBlockParamSet parameterization of tuned block in slTuner interface
    setBlockValueSet value of tuned block parameterization in slTuner interface
    setBlockRateConversionSet rate conversion settings for tuned block in slTuner interface
    systuneTune control system parameters in Simulink using slTuner interface
    looptuneTune MIMO feedback loops in Simulink using slTuner interface
    loopviewGraphically analyze results of control system tuning using slTuner interface
    looptuneSetupConstruct tuning setup for looptune to tuning setup for systune using slTuner interface
    showTunableShow value of parameterizations of tunable blocks of slTuner interface
    getIOTransferTransfer function for specified I/O set using slLinearizer or slTuner interface
    getLoopTransferOpen-loop transfer function at specified point using slLinearizer or slTuner interface
    getSensitivitySensitivity function at specified point using slLinearizer or slTuner interface
    getCompSensitivityComplementary sensitivity function at specified point using slLinearizer or slTuner interface
    writeBlockValueUpdate block values in Simulink model
    writeLookupTableDataUpdate portion of tuned lookup table
    removePointRemove point from list of analysis points in slLinearizer or slTuner interface
    removeAllPointsRemove all points from list of analysis points in slLinearizer or slTuner interface
    removeAllOpeningsRemove all openings from list of permanent openings in slLinearizer or slTuner interface
    refreshResynchronize slLinearizer or slTuner interface with current model state

    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 that 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 a 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 y1m and reference input r|for the tracking requirement. Also, add the disturbance-rejection location |d2.

    addPoint(st,["r","y1m","d2"]);
    

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

    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)
    

    Limitations

    • Linearization is not supported for model hierarchies that contain referenced models configured to use a local solver.

    • Linearization is not supported for Simscape™ networks configured to use a local solver.

    More About

    expand all

    Alternatives

    To interactively tune Simulink models, use the Control System Tuner app.

    Version History

    Introduced in R2014a

    expand all