Main Content

getIOTransfer

Transfer function for specified I/O set using slLinearizer or slTuner interface

Description

linsys = getIOTransfer(s,in,out) returns the transfer function for the specified inputs and outputs for the model associated with the slLinearizer or slTuner interface, s.

The software enforces all the permanent openings specified for s when it calculates linsys. For information on how getIOTransfer treats in and out, see Transfer Functions. If you configured either s.Parameters, or s.OperatingPoints, or both, getIOTransfer performs multiple linearizations and returns an array of transfer functions.

example

linsys = getIOTransfer(s,in,out,temp_opening) considers additional, temporary, openings at the point specified by temp_opening. Use an opening, for example, to obtain the transfer function of the controller in series with the plant, with the feedback loop open.

example

linsys = getIOTransfer(s,ios) returns the transfer function for the inputs and outputs specified by ios for the model associated with s. Use the linio command to create ios. The software enforces the linearization I/O type of each signal specified in ios when it calculates linsys. The software also enforces all the permanent loop openings specified for s.

linsys = getIOTransfer(___,mdl_index) returns a subset of the batch linearization results. mdl_index specifies the index of the linearizations of interest, in addition to any of the input arguments in previous syntaxes.

Use this syntax for efficient linearization, when you want to obtain the transfer function for only a subset of the batch linearization results.

example

[linsys,info] = getIOTransfer(___) returns additional linearization information.

example

Examples

collapse all

Obtain the closed-loop transfer function from the reference signal, r, to the plant output, y, for the ex_scd_simple_fdbk model.

Open the ex_scd_simple_fdbk model.

mdl = 'ex_scd_simple_fdbk';
open_system(mdl);

In this model:

$$\begin{array}{l}
K(s) = {K_p} = 3\\
G(s) = \frac{1}{{s + 5}}
\end{array}$$

Create an slLinearizer interface for the model.

sllin = slLinearizer(mdl);

To obtain the closed-loop transfer function from the reference signal, r, to the plant output, y, add both points to sllin.

addPoint(sllin,{'r','y'});

Obtain the closed-loop transfer function from r to y.

sys = getIOTransfer(sllin,'r','y');
tf(sys)
ans =
 
  From input "r" to output "y":
    3
  -----
  s + 8
 
Continuous-time transfer function.

The software adds a linearization input at r, dr, and a linearization output at y.

sys is the transfer function from dr to y, which is equal to $(I+GK)^{-1}GK$.

Obtain the plant model transfer function, G, for the ex_scd_simple_fdbk model.

Open the ex_scd_simple_fdbk model.

mdl = 'ex_scd_simple_fdbk';
open_system(mdl);

In this model:

$$\begin{array}{l}
K(s) = {K_p} = 3\\
G(s) = \frac{1}{{s + 5}}.
\end{array}$$

Create an slLinearizer interface for the model.

sllin = slLinearizer(mdl);

To obtain the plant model transfer function, use u as the input point and y as the output point. To eliminate the effects of feedback, you must break the loop. You can break the loop at u, e, or y. For this example, break the loop at u. Add these points to sllin.

addPoint(sllin,{'u','y'});

Obtain the plant model transfer function.

sys = getIOTransfer(sllin,'u','y','u');
tf(sys)
ans =
 
  From input "u" to output "y":
    1
  -----
  s + 5
 
Continuous-time transfer function.

The second input argument specifies u as the input, while the fourth input argument specifies u as a temporary loop opening.

sys is the transfer function from du to y, which is equal to $G$.

Suppose you batch linearize the scdcascade model for multiple transfer functions. For most linearizations, you vary the proportional (Kp2) and integral gain (Ki2) of the C2 controller in the 10% range. For this example, calculate the open-loop response transfer function for the inner loop, from e2 to y2, for the maximum value of Kp2 and Ki2.

Open the scdcascade model.

mdl = 'scdcascade';
open_system(mdl)

Create an slLinearizer interface for the model.

sllin = slLinearizer(mdl);

Vary the proportional (Kp2) and integral gain (Ki2) of the C2 controller in the 10% range.

Kp2_range = linspace(0.9*Kp2,1.1*Kp2,3);
Ki2_range = linspace(0.9*Ki2,1.1*Ki2,5);

[Kp2_grid,Ki2_grid] = ndgrid(Kp2_range,Ki2_range);

params(1).Name = 'Kp2';
params(1).Value = Kp2_grid;

params(2).Name = 'Ki2';
params(2).Value = Ki2_grid;

sllin.Parameters = params;

To calculate the open-loop transfer function for the inner loop, use e2 and y2 as analysis points. To eliminate the effects of the outer loop, break the loop at e2. Add e2 and y2 to sllin as analysis points.

addPoint(sllin,{'e2','y2'})

Determine the index for the maximum values of Ki2 and Kp2.

mdl_index = params(1).Value == max(Kp2_range) & params(2).Value == max(Ki2_range);

Obtain the open-loop transfer function from e2 to y2.

sys = getIOTransfer(sllin,'e2','y2','e2',mdl_index);

Open Simulink® model.

mdl = 'scdcascade';
open_system(mdl)

Create a linearization option set, and set the StoreOffsets option.

opt = linearizeOptions('StoreOffsets',true);

Create slLinearizer interface.

sllin = slLinearizer(mdl,opt);

Add analysis points to calculate the closed-loop transfer function.

addPoint(sllin,{'r','y1m'});

Calculate the input/output transfer function, and obtain the corresponding linearization offsets.

[sys,info] = getIOTransfer(sllin,'r','y1m');

View offsets.

info.Offsets
ans = 

  struct with fields:

            dx: [6×1 double]
             x: [6×1 double]
             u: 1
             y: 0
    OutputName: {'y1m'}
     InputName: {'r'}
     StateName: {6×1 cell}
            Ts: 0

Input Arguments

collapse all

Interface to a Simulink model, specified as either an slLinearizer interface or an slTuner interface.

Input analysis point signal name, specified as:

  • Character vector or string — Analysis point signal name.

    To determine the signal name associated with an analysis point, type s. The software displays the contents of s in the MATLAB® command window, including the analysis point signal names, block names, and port numbers. Suppose that an analysis point does not have a signal name, but only a block name and port number. You can specify in as the block name. To use a point not in the list of analysis points for s, first add the point using addPoint.

    You can specify in as a uniquely matching portion of the full signal name or block name. Suppose that the full signal name of an analysis point is 'LoadTorque'. You can specify in as 'Torque' as long as 'Torque' is not a portion of the signal name for any other analysis point of s.

    For example, in = 'y1m'.

  • Cell array of character vectors or string array — Specifies multiple analysis point names. For example, in = {'y1m','y2m'}.

Output analysis point signal name, specified as:

  • Character vector or string — Analysis point signal name.

    To determine the signal name associated with an analysis point, type s. The software displays the contents of s in the MATLAB command window, including the analysis point signal names, block names, and port numbers. Suppose that an analysis point does not have a signal name, but only a block name and port number. You can specify out as the block name. To use a point not in the list of analysis points for s, first add the point using addPoint.

    You can specify out as a uniquely matching portion of the full signal name or block name. Suppose that the full signal name of an analysis point is 'LoadTorque'. You can specify out as 'Torque' as long as 'Torque' is not a portion of the signal name for any other analysis point of s.

    For example, out = 'y1m'.

  • Cell array of character vectors or string array — Specifies multiple analysis point names. For example, out = {'y1m','y2m'}.

Temporary opening signal name, specified as:

  • Character vector or string — Analysis point signal name.

    temp_opening must specify an analysis point that is in the list of analysis points for s. To determine the signal name associated with an analysis point, type s. The software displays the contents of s in the MATLAB command window, including the analysis point signal names, block names, and port numbers. Suppose that an analysis point does not have a signal name, but only a block name and port number. You can specify temp_opening as the block name. To use a point not in the list of analysis points for s, first add the point using addPoint.

    You can specify temp_opening as a uniquely matching portion of the full signal name or block name. Suppose that the full signal name of an analysis point is 'LoadTorque'. You can specify temp_opening as 'Torque' as long as 'Torque' is not a portion of the signal name for any other analysis point of s.

    For example, temp_opening = 'y1m'.

  • Cell array of character vectors or string array — Specifies multiple analysis point names. For example, temp_opening = {'y1m','y2m'}.

Linearization I/Os, created using linio, specified as a linearization I/O object.

ios must specify signals that are in the list of analysis points for s. To view the list of analysis points, type s. To use a point that is not in the list of analysis points for s, you must first add the point to the list using addPoint.

For example:

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

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

Index for linearizations of interest, specified as:

  • Array of logical values — Logical array index of linearizations of interest. Suppose that you vary two parameters, par1 and par2, and want to extract the linearization for the combination of par1 > 0.5 and par2 <= 5. Use:

    params = s.Parameters;
    mdl_index = params(1).Value>0.5 & params(2).Value <= 5;

    The expression params(1).Value>0.5 & params(2).Value<5 uses logical indexing and returns a logical array. This logical array is the same size as params(1).Value and params(2).Value. Each entry contains the logical evaluation of the expression for corresponding entries in params(1).Value and params(2).Value.

  • Vector of positive integers — Linear index of linearizations of interest. Suppose that you vary two parameters, par1 and par2, and want to extract the linearization for the combination of par1 > 0.5 and par2 <= 5. Use:

    params = s.Parameters;
    mdl_index = find(params(1).Value>0.5 & params(2).Value <= 5);

    The expression params(1).Value>0.5 & params(2).Value<5 returns a logical array. find returns the linear index of every true entry in the logical array

Output Arguments

collapse all

Transfer function for specified I/Os, returned as described in the following:

  • If you did not configure s.Parameters and s.OperatingPoints, the software calculates linsys using the default model parameter values. The software uses the model initial conditions as the linearization operating point. linsys is returned as a state-space model.

  • If you configured s.Parameters only, the software computes a linearization for each parameter grid point. linsys is returned as a state-space model array of the same size as the parameter grid.

  • If you configured s.OperatingPoints only, the software computes a linearization for each specified operating point. linsys is returned as a state-space model array of the same size as s.OperatingPoints.

  • If you configured s.Parameters and specified s.OperatingPoints as a single operating point, the software computes a linearization for each parameter grid point. The software uses the specified operating point as the linearization operating point. linsys is returned as a state-space model array of the same size as the parameter grid.

  • If you configured s.Parameters and specified s.OperatingPoints as multiple operating point objects, the software computes a linearization for each parameter grid point. The software requires that s.OperatingPoints is the same size as the parameter grid specified by s.Parameters. The software computes each linearization using corresponding operating points and parameter grid points. linsys is returned as a state-space model array of the same size as the parameter grid.

  • If you configured s.Parameters and specified s.OperatingPoints as multiple simulation snapshot times, the software simulates and linearizes the model for each snapshot time and parameter grid point combination. Suppose that you specify a parameter grid of size p and N snapshot times. linsys is returned as a state-space model array of size N-by-p.

For most models, linsys is returned as an ss object or an array of ss objects. However, if your model contains one of the following blocks in the linearization path defined by in and out, then linsys returns the specified type of state-space model.

Blocklinsys Type
Block with a substitution specified as a genss object or tunable model objectgenss
Block with a substitution specified as an uncertain model, such as ussuss (Robust Control Toolbox)
Sparse Second Order blockmechss
Descriptor State-Space block configured to linearize to a sparse modelsparss

Linearization information, returned as a structure with the following fields:

Linearization offsets, returned as [] if s.Options.StoreOffsets is false. Otherwise, Offsets is returned as one of the following:

  • If linsys is a single state-space model, then Offsets is a structure.

  • If linsys is an array of state-space models, then Offsets is a structure array with the same dimensions as linsys.

Each offset structure has the following fields:

FieldDescription
xState offsets used for linearization, returned as a column vector of length nx, where nx is the number of states in linsys.
yOutput offsets used for linearization, returned as a column vector of length ny, where ny is the number of outputs in linsys.
uInput offsets used for linearization, returned as a column vector of length nu, where nu is the number of inputs in linsys.
dxDerivative offsets for continuous time systems or updated state values for discrete-time systems, returned as a column vector of length nx.
StateNameState names, returned as a cell array that contains nx elements that match the names in linsys.StateName.
InputNameInput names, returned as a cell array that contains nu elements that match the names in linsys.InputName.
OutputNameOutput names, returned as a cell array that contains ny elements that match the names in linsys.OutputName.
TsSample time of the linearized system, returned as a scalar that matches the sample time in linsys.Ts. For continuous-time systems, Ts is 0.

If Offsets is a structure array, you can configure an LPV System block using the offsets. To do so, first convert them to the required format using getOffsetsForLPV. For an example, see Approximate Nonlinear Behavior Using Array of LTI Systems.

Linearization diagnostic information, returned as [] if s.Options.StoreAdvisor is false. Otherwise, Advisor is returned as one of the following:

  • If linsys is a single state-space model, Advisor is a LinearizationAdvisor object.

  • If linsys is an array of state-space models, Advisor is an array of LinearizationAdvisor objects with the same dimensions as linsys.

LinearizationAdvisor objects store linearization diagnostic information for individual linearized blocks. For an example of troubleshooting linearization results using a LinearizationAdvisor object, see Troubleshoot Linearization Results at Command Line.

More About

collapse all

Version History

Introduced in R2013b

expand all