Simscape Variable Scaling Analyzer
Resolve variable scaling issues and improve simulation speed of Simscape models
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.
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:
ssc_simple_mechanical_system model and the Simscape
Variable Scaling Analyzer app open.
Run the model from the 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.
Observe in the Visualization pane that the state is outside of
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.
Return to the Simscape Variable Scaling Analyzer window and click Nominal
Values to access the nominal values for
To add a nominal value-unit pair, click Add nominal value-unit
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.
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.
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).
simscapeVariableScalingAnalyzer opens the Simscape Variable
Scaling Analyzer app.
simscapeVariableScalingAnalyzer(modelName) opens the Simscape
Variable Scaling Analyzer app and attaches it to the model
modelName, which you specify as a character vector or string
Assumptions and Limitations
This app does not work with Simscape™ Multibody™ networks.
Introduced in R2021b