BlockDiagnostic

Diagnostic information for individual block linearization

Description

When you linearize a Simulink^® model, you can create a LinearizationAdvisor object that contains BlockDiagnostic objects. Each BlockDiagnostic object contains diagnostic information regarding the linearization of the corresponding Simulink block. You can troubleshoot the block linearization by examining the BlockDiagnostic object properties.

Creation

To access block diagnostic information in a LinearizationAdvisor object, use the getBlockInfo function. Using this function, you can obtain either a single BlockDiagnostic object or multiple BlockDiagnostic objects. For example, see:

• Obtain Diagnostics for Potentially Problematic Blocks

• Obtain Diagnostics Using Block Names

Properties

IsOnPath — Flag indicating whether the block is on the linearization path

'Yes' | 'No'

Flag indicating whether the block is on the linearization path, specified as one of the following:

• 'Yes' — Block is on linearization path

• 'No' — Block is not on linearization path

The linearization path connects the linearization inputs to the linearization outputs. To view the linearization path in the Simulink model, use the highlight function.

ContributesToLinearization — Flag indicating whether the block numerically influences the model linearization

'Yes' | 'No'

Flag indicating whether the block numerically influences the model linearization, specified as one of the following:

• 'Yes' — Block contributes to the linearization result

• 'No' — Block does not contribute to the linearization result

If a block is not on the linearization path; that is, if IsOnPath is 'No', then ContributesToLinearization is 'No'.

DiagnosticMessages — Diagnostic messages

cell array of character vectors

Diagnostic message regarding the block linearization, specified as a cell array of character vectors. These messages indicate possible issues that can affect the block linearization.

If HasDiagnostics is 'No', then DiagnosticMessages is an empty cell array.

BlockPath — Block path

character vector

Block path in Simulink model, specified as a character vector.

HasDiagnostics — Flag indicating whether the block has diagnostic messages

'Yes' | 'No'

Flag indicating whether the block has diagnostic messages regarding its linearization, specified as one of the following:

• 'Yes' — Block has diagnostic messages

• 'No' — Block does not have diagnostic messages

If HasDiagnostics is 'Yes', then DiagnosticMessages is a cell array of character vectors that contains the messages.

Linearization — Block linearization

state-space model

Block linearization, specified as a state-space model.

LinearizationMethod — Linearization method

'Exact' | 'Perturbation' | 'Block Substituted' | 'Simscape Network' | 'Not Supported'

Linearization method, specified as one of the following:

• 'Exact' — Block linearized using its defined exact linearization

• 'Perturbation' — Block linearized using numerical perturbation

• 'Block Substituted' — Block linearized using a specified custom linearization

• 'Simscape Network' — Simscape™ network linearized using the exact linearization defined in the Simscape engine. A LinearizationAdvisor object does not provide diagnostic information on a component-level basis for Simscape networks. Instead, it groups diagnostic information together for multiple Simscape components connected to a single Solver Configuration block.

• 'Not Supported' — Block in its current configuration does not support linearization. For example, a Discrete Transfer Fcn block with an external reset does not support linearization.

  In this case, the block Linearization is zero. For more troubleshooting information, check the DiagnosticMessages property.

OperatingPoint — Operating point

BlockOperatingPoint object

Operating point at which the block is linearized, specified as a BlockOperatingPoint object.

Usage

You can troubleshoot the linearization of a Simulink model by examining the diagnostics for individual block linearizations. To do so, examine the properties of BlockDiagnostic objects returned from getBlockInfo. For more information, see Troubleshoot Linearization Results at Command Line.

Examples

Obtain Diagnostics for Potentially Problematic Blocks

Load Simulink model.

mdl = 'scdpendulum';
load_system(mdl)

Linearize the model and obtain LinearizationAdvisor object.

io = getlinio(mdl);
opt = linearizeOptions('StoreAdvisor',true);
[linsys,~,info] = linearize(mdl,io,opt);
advisor = info.Advisor;

Find blocks that are potentially problematic for linearization.

blocks = advise(advisor);

Obtain diagnostics for these blocks.

diags = getBlockInfo(blocks)

diags = 
Linearization Diagnostics for the Blocks:

Block Info:
-----------
Index   BlockPath                                           Is On Path   Contributes To Linearization   Linearization Method   
1.      scdpendulum/pendulum/Saturation                     Yes          No                             Exact                  
2.      scdpendulum/angle_wrap/Trigonometric Function1      Yes          No                             Perturbation           
3.      scdpendulum/pendulum/Trigonometric Function         Yes          No                             Perturbation           

Obtain Diagnostics Using Block Names

Load Simulink model.

mdl = 'scdpendulum';
load_system(mdl)

Linearize the model and obtain LinearizationAdvisor object.

io = getlinio(mdl);
opt = linearizeOptions('StoreAdvisor',true);
[linsys,~,info] = linearize(mdl,io,opt);
advisor = info.Advisor;

Obtain diagnostic information for the saturation block.

satDiag = getBlockInfo(advisor,'scdpendulum/pendulum/Saturation')

satDiag = 
Linearization Diagnostics for scdpendulum/pendulum/Saturation with properties:

                      IsOnPath: 'Yes'
    ContributesToLinearization: 'No'
           LinearizationMethod: 'Exact'
                 Linearization: [1×1 ss]
                OperatingPoint: [1×1 linearize.advisor.BlockOperatingPoint]

You can also obtain diagnostic information for multiple blocks at once. Obtain diagnostics for the sin blocks in the model.

sinBlocks = {'scdpendulum/pendulum/Trigonometric Function';
             'scdpendulum/angle_wrap/Trigonometric Function1'};
         
sinDiag = getBlockInfo(advisor,sinBlocks)

sinDiag = 
Linearization Diagnostics for the Blocks:

Block Info:
-----------
Index   BlockPath                                           Is On Path   Contributes To Linearization   Linearization Method   
1.      scdpendulum/angle_wrap/Trigonometric Function1      Yes          No                             Perturbation           
2.      scdpendulum/pendulum/Trigonometric Function         Yes          No                             Perturbation           

Version History

Introduced in R2017b

R2018a: Simscape states and inputs now combined into single block diagnostic per Solver Configuration block

When troubleshooting linearization issues using the Linearization Advisor, diagnostic information for Simscape states and inputs is now combined into a single block diagnostic object. Previously, states and inputs were returned in separate diagnostic objects.

Update Code

To view diagnostic information for Simscape networks at the command line, you first query the Linearization Advisor object, advisor, for blocks of type 'simscape'.

qSS = linqueryIsBlockType('simscape');
advSS = find(advisor,qSS);

In R2017b, to view state or input information for the Simscape network, you searched the block paths of the diagnostics in advSS for the text EVAL_KEY/STATE or EVAL_KEY/INPUT, respectively. For example, to find diagnostics with state information, you used:

paths = getBlockPaths(advisor);
index = contains(paths,'EVAL_KEY/STATE');
diag = getBlockInfo(advSS,index);

You then viewed the state or input information in the associated operating point object.

diag(i).OperatingPoint

Starting in R2018a, you access both the state and input information directly from the operating point of the Simscape block diagnostic object without searching the block paths.

advSS.BlockDiagnostics(i).OperatingPoint