# Documentation

## Controlling Block Linearization

### When You Need to Specify Linearization for Individual Blocks

Simulink® blocks with sharp discontinuities produce poor linearization results. Typically, you must specify a custom linearization for such blocks.

When your model operates in a region away from the point of discontinuity, the linearization is zero. A block with discontinuity linearizing to zero can cause the linearization of the system to be zero when this block multiplies other blocks.

For other types of blocks, you can specify the block linearization as a:

• Linear model in the form of a D-matrix

• Control System Toolbox™ model object

• Robust Control Toolbox™ uncertain state space or uncertain real object (requires Robust Control Toolbox software)

### Specify Linear System for Block Linearization Using MATLAB Expression

This example shows how to specify the linearization of any block, subsystem, or model reference without having to replace this block in your Simulink model.

1. Right-click the block in the model, and select Linear Analysis > Specify Selected Block Linearization.

The Block Linearization Specification dialog box opens.

2. In the Specify block linearization using a list, select MATLAB Expression.

3. In the text field, enter an expression that specifies the linearization.

For example, specify the linearization as an integrator with a gain of k, G(s) = k/s.

In state-space form, this transfer function corresponds to `ss(0,1,k,0)`.

Click OK.

4. Linearize the model.

### Specify D-Matrix System for Block Linearization Using Function

This example shows how to specify custom linearization for a saturation block using a function.

```sys = 'configSatBlockFcn'; open_system(sys)```

In this model, the limits of the saturation block are `-satlimit` and `satlimit`. The current value of the workspace variable `satlimit` is 10.

2. Linearize the model at the model operating point using the linear analysis points defined in the model. Doing so returns the linearization of the saturation block.

```io = getlinio(sys); linsys = linearize(sys,io)```
```linsys = d = Constant Saturation 1 Static gain. ```

At the model operating point, the input to the saturation block is 10. This value is right on the saturation boundary. At this value, the saturation block linearizes to 1.

3. Suppose that you want the block to linearize to a transitional value of 0.5 when the input falls on the saturation boundary. Write a function that defines the saturation block linearization to behave this way. Save the function to the MATLAB® path.

```function blocklin = mySaturationLinearizationFcn(BlockData) % This function customizes the linearization of a saturation block % based on the block input signal level, U: % BLOCKLIN = 0 when |U| > saturation limit % BLOCKLIN = 1 when |U| < saturation limit % BLOCKLIN = 1/2 when U = saturation limit % Get saturation limit. satlimit = BlockData.Parameters.Value; % Compute linearization based on the input signal % level to the block. if abs(BlockData.Inputs(1).Values) > satlimit blocklin = 0; elseif abs(BlockData.Inputs(1).Values) < satlimit blocklin = 1; else blocklin = 1/2; end```

This configuration function defines the saturation block linearization based on the level of the block input signal. For input values outside the saturation limits, the block linearizes to zero. Inside the limits, the block linearizes to 1. Right on the boundary values, the block linearizes to the interpolated value of 0.5. The input to the function, `BlockData`, is a structure that the software creates automatically when you configure the linearization of the Saturation block to use the function. The configuration function reads the saturation limits from that data structure.

4. In the Simulink model, right-click the Saturation block, and select Linear Analysis > Specify Selected Block Linearization.

The Block Linearization Specification dialog box opens.

5. Check Specify block linearization using one of the following. Choose Configuration Function from the list.

Configure the linearization function:

1. Enter the name you gave to your saturation function. In this example, the function name is `mySaturationLinearizationFcn`.

2. Specify the function parameters. `mySaturationLinearizationFcn` requires the saturation limit value, which the user must specify before linearization.

Enter the variable name `satlimit` in Parameter Value. Enter the corresponding descriptive name in the Parameter Name column, `SaturationLimit`.

3. Click OK.

Configuring the Block Linearization Specification dialog box updates the model to use the specified linearization function for linearizing the Saturation Block. Specifically, this configuration automatically populates the `Parameters` field of the `BlockData` structure, which is the input argument to the configuration function.

 Note:   You can add function parameters by clicking . Use to delete selected parameters.
6. Define the saturation limit, which is a parameter required by the linearization function of the Saturation block.

`satlimit = 10;`
7. Linearize the model again. Now, the linearization uses the custom linearization of the saturation block.

`linsys_cust = linearize(sys,io)`
```linsys_cust = d = Constant Saturation 0.5 Static gain. ```

At the model operating point, the input to the saturation block is 10. Therefore, the block linearizes to 0.5, the linearization value specified in the function for saturation boundary.

### Augment the Linearization of a Block

This example shows how to augment the linearization of a block with additional time delay dynamics, using a block linearization specification function.

```mdl = 'scdFcnCall'; open_system(mdl)```

This model includes a continuous time plant, `Plant`, and a discrete-time controller, `Controller`. The `D/A` block discretizes the plant output with a sampling time of 0.1 s. The ```External Scheduler``` block triggers the controller to execute with the same period, 0.1 s. However, the trigger has an offset of 0.05 s relative to the discretized plant output. For that reason, the controller does not process a change in the reference signal until 0.05 s after the change occurs. This offset introduces a time delay of 0.05 s into the model.

2. (Optional) Linearize the closed-loop model at the model operating point without specifying a linearization for the `Controller` block.

```io = getlinio(mdl); sys_nd = linearize(mdl,io); ```

The `getlinio` function returns the linearization input and output points that are already defined in the model.

3. (Optional) Check the linearization result by frequency response estimation.

```input = frest.Sinestream(sys_nd); sysest = frestimate(mdl,io,input); bode(sys_nd,'g',sysest,'r*',{input.Frequency(1),input.Frequency(end)}) legend('Linearization without delay',... 'Frequency Response Estimation','Location','SouthWest') ```

The exact linearization does not account for the time delay introduced by the controller execution offset. A discrepancy results between the linearized model and the estimated model, especially at higher frequencies.

4. Write a function to specify the linearization of the `Controller` block that includes the time delay.

The following configuration function defines a linear system that equals the default block linearization multiplied by a time delay. Save this configuration function to a location on your MATLAB path. (For this example, the function is already saved as `scdAddDelayFcn.m`.)

```function sys = scdAddDelayFcn(BlockData) sys = BlockData.BlockLinearization*thiran(0.05,0.1);```

The input to the function, `BlockData`, is a structure that the software creates automatically each time it linearizes the block. When you specify a block linearization configuration function, the software automatically passes `BlockData` to the function. The field `BlockData.BlockLinearization` contains the current linearization of the block.

This configuration function approximates the time delay as a `thiran` filter. The filter indicates a discrete-time approximation of the fractional time delay of 0.5 sampling periods. (The 0.05 s delay has a sampling time of 0.1 s).

5. Specify the configuration function `scdAddDelayFcn` as the linearization for the `Controller` block.

1. Right-click the `Controller` block, and select Linear Analysis > Specify Selected Block Linearization.

2. Select the Specify block linearization using one of the following check box. Then, select Configuration Function from the drop-down list.

3. Enter the function name `scdAddDelayFcn` in the text box. `scdAddDelayFcn` has no parameters, so leave the parameter table blank.

4. Click OK.

6. Linearize the model using the specified block linearization.

```sys_d = linearize(mdl,io); ```

The linear model `sys_d` is a linearization of the closed-loop model that accounts for the time delay.

7. (Optional) Compare the linearization that includes the delay with the estimated frequency response.

```bode(sys_d,'b',sys_nd,'g',sysest,'r*',... {input.Frequency(1),input.Frequency(end)}) legend('Linearization with delay','Linearization without delay',... 'Frequency Response Estimation','Location','SouthWest')```

The linear model obtained with the specified block linearization now accounts for the time delay. This linear model is therefore a much better match to the real frequency response of the Simulink model.

### Models with Time Delays

#### Choosing Approximate Versus Exact Time Delays

Simulink Control Design™ lets you choose whether to linearize models using exact representation or Pade approximation of continuous time delays. How you treat time delays during linearization depends on your nonlinear model.

Simulink blocks that model time delays are:

• Transport Delay block

• Variable Time Delay block

• Variable Transport Delay block

• Delay block

• Unit Delay block

By default, linearization uses Pade approximation for representing time delays in your linear model.

Use Pade approximation to represent time delays when:

• Applying more advanced control design techniques to your linear plant, such as LQR or H-infinity control design.

• Minimizing the time to compute a linear model.

Specify to linearize with exact time delays for:

• Minimizing errors that result from approximating time delays

• PID tuning or loop-shaping control design methods in Simulink Control Design

• Discrete-time models (to avoid introducing additional states to the model)

The software treats discrete-time delays as internal delays in the linearized model. Such delays do not appear as additional states in the linearized model.

#### Specifying Exact Representation of Time Delays

• In the Linear Analysis Tool:

1. In the Linear Analysis tab, click More Options.

2. n the Options for exact linearization dialog box, in the Linearization tab, check Return linear model with exact delay(s).

• At the command line:

Use `linearizeOptions` to specify the `UseExactDelayModel` option.

### Perturbation Level of Blocks Perturbed During Linearization

Blocks that do not have preprogrammed analytic Jacobians linearize using numerical perturbation.

#### Change Block Perturbation Level

This example shows how to change the perturbation level to the Magnetic Ball Plant block in the `magball``magball` model. Changing the perturbations level changes the linearization results.

The default perturbation size is 10-5(1+|x|), where x is the operating point value of the perturbed state or the input.

Open the model before changing the perturbation level.

To change the perturbation level of the states to ${10}^{-7}\left(1+|x|\right)$, where x is the state value, type:

```blockname='magball/Magnetic Ball Plant' set_param(blockname,'StatePerturbationForJacobian','1e-7') ```

To change the perturbation level of the input to ${10}^{-7}\left(1+|x|\right)$, where x is the input signal value:

1. Open the system and get the block port handles.

```sys = 'magball'; open_system(sys); blockname = 'magball/Magnetic Ball Plant'; ph = get_param(blockname,'PortHandles') ```
2. Get the handle to the inport value.

```p_in = ph.Inport(1) ```
3. Set the inport perturbation level.

`set_param(p_in,'PerturbationForJacobian','1e-7')`

#### Perturbation Levels of Integer Valued Blocks

A custom block that requires integer input ports for indexing might have linearization issues when this block:

• Does not support small perturbations in the input value

• Accepts double-precision inputs

To fix the problem, try setting the perturbation level of such a block to zero (which sets the block linearization to a gain of 1).

### Linearizing Blocks with Nondouble Precision Data Type Signals

You can linearize blocks that have nondouble precision data type signals as either inputs or outputs, and have no preprogrammed exact linearization. Without additional configuration, such blocks automatically linearize to zero. For example, logical operator blocks have Boolean outputs and linearize to 0.

Linearizing blocks that have nondouble precision data type signals requires converting all signals to double precision. This approach only works when your model can run correctly in full double precision.

When you have only a few blocks impacted by the nondouble precision data types, use a Data Type Conversion block to fix this issue.

When you have many nondouble precision signals, you can override all data types with double precision using the Fixed Point Tool.

#### Overriding Data Types Using Data Type Conversion Block

Convert individual signals to double precision before linearizing the model by inserting a Data Type Conversion block. This approach works well for model that have only a few affected blocks.

After linearizing the model, remove the Data Type Conversion block from your model.

 Note:   Overriding nondouble data types is not appropriate when the model relies on these data types, such as relying on integer data types to perform truncation from floats.

For example, consider the model configured to linearize the Square block at an operating point where the input is 1. The resulting linearized model should be 2, but the input to the Square block is Boolean. This signal of nondouble precision date type results in linearization of zero.

In this case, inserting a Data Type Conversion block converts the input signal to the Square block to double precision.

#### Overriding Data Types Using Fixed Point Tool

When you linearize a model that contains nondouble data types but still runs correctly in full double precision, you can override all data types with doubles using the Fixed Point Tool. Use this approach when you have many nondouble precision signals.

After linearizing the model, restore your original settings.

 Note:   Overriding nondouble data types is not appropriate when the model relies on these data types, such as relying on integer data types to perform truncation from floats.
1. In the Simulink model, select Analysis > Fixed Point Tool.

The Fixed Point Tool opens.

2. In the Data type override menu, select Double.

This setting uses double precision values for all signals during linearization.

3. Restore settings when linearization completes.

### Event-Based Subsystems (Externally Scheduled Subsystems)

#### Linearizing Event-Based Subsystems

Event-based subsystems (triggered subsystems) and other event-based models require special handling during linearization.

Executing a triggered subsystem depends on previous signal events, such as zero crossings. However, because linearization occurs at a specific moment in time, the trigger event never happens.

An example of an event-based subsystem is an internal combustion (IC) engine. When an engine piston approaches the top of a compression stroke, a spark causes combustion. The timing of the spark for combustion is dependent on the speed and the position of the engine crankshaft.

In the `scdspeed` model, triggered subsystems generate events when the pistons reach both the top and bottom of the compression stroke. Linearization in the presence of such triggered subsystems is not meaningful.

#### Approaches for Linearizing Event-Based Subsystems

You can obtain a meaningful linearization of triggered subsystems, while still preserving the simulation behavior, by recasting the event-based dynamics as one of the following:

• Lumped average model that approximates the event-based behavior over time.

• Periodic function call subsystem, with Normal simulation mode.

In the case of periodical function call subsystems, the subsystem linearizes to the sampling at which the subsystem is periodically executed.

In many control applications, the controller is implemented as a discrete controller, but the execution of the controller is driven by an external scheduler. You can use such linearized plant models when the controller subsystem is marked as a Periodic Function call subsystem.

If recasting event-based dynamics does not produce good linearization results, try frequency response estimation. See Estimate Frequency Response Using Linear Analysis Tool.

#### Periodic Function Call Subsystems for Modeling Event-Based Subsystems

This example shows how to use periodic function call subsystems to approximate event-based dynamics for linearization.

```sys = 'scdPeriodicFcnCall'; open_system(sys)```
2. Linearize model at the model operating point.

```io = getlinio(sys); linsys = linearize(sys,io)```

The linearization is zero because the subsystem is not a periodic function call.

```d = Desired Wat Water-Tank S 0 Static gain.```

Now, specify the Externally Scheduled Controller block as a Periodic Function Call Subsystem.

3. Double-click the Externally Scheduled Controller (Function-Call Subsystem) block.

Double-click the function block to open the Block Parameters dialog box.

4. Set Sample time type to be `periodic`.

Leave the Sample time value as 0.01, which represents the sample time of the function call.

5. Linearize the model.

```linsys2 = linearize(sys,io) a = H Integrator H 0.9956 0.002499 Integrator -0.0007774 1 b = Desired Wat H 0.003886 Integrator 0.0007774 c = H Integrator Water-Tank S 1 0 d = Desired Wat Water-Tank S 0 Sampling time: 0.01 Discrete-time model.```
6. Plot step response.

`step(linsys2)`

7. Close the model.

`bdclose(sys);`

#### Approximating Event-Based Subsystems Using Curve Fitting (Lump-Average Model)

This example shows how to use curve fitting to approximate event-based dynamics of an engine.

The `scdspeed` model linearizes to zero because ```scdspeed/Throttle & Manifold/Intake Manifold``` is an event-triggered subsystem.

You can approximate the event-based dynamics of the ```scdspeed/Throttle & Manifold/Intake Manifold``` subsystem by adding the Convert to mass charge block inside the subsystem.

The Convert to mass charge block approximates the relationship between Air Charge, Manifold Pressure, and Engine Speed as a quadratic polynomial.

If measured data for internal signals is not available, use simulation data from the original model to compute the unknown parameters p1, p2, p3, p4, and p5 using a least squares fitting technique.

When you have measured data for internal signals, you can use the Simulink Design Optimization™ software to compute the unknown parameters. See Engine Speed Model Parameter EstimationEngine Speed Model Parameter Estimation to learn more about computing model parameters, linearizing this approximated model, and designing a feedback controlled for the linear model.

The next figure compares the simulations of the original event-based model and the approximated model. Each of the pulses corresponds to a step change in the engine speed. The size of the step change is between 1500 and 5500. Thus, you can use the approximated model to accurately simulate and linearize the engine between 1500 RPM and 5500 RPM.