Simscape Variable Scaling Analyzer

Resolve variable scaling issues and improve simulation speed of Simscape models

Since R2021b

Description

The Simscape Variable Scaling Analyzer app analyzes the scale of simulation states with respect to each other and to the Absolute tolerance parameter in the Simulink^® Solver pane. For instance, if you rescale a state, you can easily visualize the effect of nominal value scaling. The app provides statistical information for all model states that the simulation uses and highlights states that are potentially causing convergence issues. From the app, you can open a new model or attach the app to a currently open model. You can also access the model settings, nominal values, and the Property Inspector from the toolstrip.

The Simscape Variable Scaling Analyzer app enables you to:

Run a variable scaling analysis.
View statistical data for the model states.
Visualize the behavior of model states with respect to one another and to a given absolute tolerance.
View the most recent simulation diagnostics.
View recommendations provided by the app.

Poorly scaled units can artificially diminish or magnify the presence of a variable with respect to the other variables in the simulation. Whether the scale of the variable is disproportionately high compared to other variables or the scale is significantly close to the absolute tolerance, the likely result is that the solver is slow or fails to converge. The app can help you decide what variables are important, why the simulation may not be performing as desired, and what actions may improve the simulation performance. In general, you can globally rescale a nominal value, locally rescale a nominal unit for a block, or make changes to your underlying equations. For more information, see Select Nominal Values Using the Variable Scaling Analyzer.

The Raw Data pane contains a table that lists this data:

Index is an index number to represent the retained state.
StateName is the object name of the variable.
NominalUnits is the value-unit pair associated with the variable. Units of '1' represent dimensionless variables.
PercentTimeBelowAbsTol is the percentage of time during the simulation that the variable spends below the Absolute tolerance parameter (AbsTol) when the Autoscaling absolute tolerance parameter in the Configuration Parameters window is unchecked.
MinData is the minimum value that the simulation computes for a given variable.
MaxData is the maximum value that the simulation computes for a given variable.
MeanAbsData is the time-weighted statistical mean of the absolute value of the data for a given variable.
LogMaxAbsData is the base-10 logarithm of the maximum absolute value of the data for a given variable.
StdDevData is the time-weighted standard deviation of the data for a given variable.

Open the Simscape Variable Scaling Analyzer App

MATLAB^® command prompt: Enter simscapeVariableScalingAnalyzer to open the app with no model loaded or you can specify the model you want to analyze as an argument for the command.

Examples

expand all

Analyze the Effect of Adjusting a Nominal Value

This example shows how to use the app to change a nominal value.

To begin, enter the command:

simscapeVariableScalingAnalyzer('ssc_simple_mechanical_system')

The ssc_simple_mechanical_system model and the Simscape Variable Scaling Analyzer app open.

Run the model from the window.

Simscape Variable Scaling Analyzer window after running the simple mechanical system model from the app window.

The simulation converges with no warnings. Observe from the NominalUnits column that meters appear in some of the important states.

Select the state associated with index 5, and click the Plot State button.

Simscape variable scaling analyzer window showing the state value plot.

Observe in the Visualization pane that the state is outside of the AbsTol. The simulation considers states that are greater in magnitude than the AbsTol. You can view the expected output of the simulation by opening the Scope block called Lever C Position.

Lever C Position scope window showing normal model behavior.

Return to the Simscape Variable Scaling Analyzer window and click Nominal Values to access the nominal values for ssc_simple_mechanical_system.

To add a nominal value-unit pair, click Add nominal value-unit pair . Enter 1e3 in the Nominal value column and enter m for meters in the Unit column. Then click OK to accept the change. To learn more, see System Scaling by Nominal Values.

Run the model again from the Simscape Variable Scaling Analyzer window. Select the state associated with index 5, and click Plot State.

Simscape variable scaling analyser window after making an adjustment to an important state nominal value and running the model again. New states are highlighted, and the app displays messages about the model behavior.

Now the state is within the absolute tolerance band for the entire simulation. The highlighting in the PercentTimeBelowAbsTol column also indicates this. The simulation does not generate a warning, but you can see the effect of the change by viewing the Scope block in the model.

Lever C Position scope window showing a plot with reduced oscillation compared to the normal behavior.

Despite the absence of a warning, adjusting the nominal value compromised the model fidelity. Ideally, you should adjust the nominal values such that the states remain at O(1).

Programmatic Use

expand all