Select Nominal Values Using the Variable Scaling Analyzer

Simscape™ can perform nominal value analysis to help you select nominal values. Nominal values are a means to specify the expected magnitude of a model variable to improve simulation conditions. Choosing the right nominal values can improve the conditions to make convergence possible or improve speed. To learn more, see System Scaling by Nominal Values.

When to Perform Variable Scaling Analysis

Solvers may encounter speed issues due to variable scaling. For example, when a state is too small relative to the Absolute tolerance parameter in the Simulink^® Solver pane, the solver may ignore it during some or all of the simulation. The Simscape Variable Scaling Analyzer app identifies states that

• remain below the Absolute tolerance parameter for the duration of the simulation.

• trend near the Absolute tolerance but do not remain below it.

• are orders of magnitude larger than other variables.

The Solver Profiler tool also identifies some of these issues in the States Below Absolute Tolerance tab. All of these cases can lead to solver performance issues.

Tip

Your model will perform best when all of your states are approximately O(1).

Consider the simple three-phase circuit model in the figure.

Running the model with the default nominal values generates this warning:

First solve for initial conditions failed to converge. Trying again with all high priorities relaxed to low.

In this case, the solver ignores one variable with Priority set to High. This produces the result in the figure.

The Primary currents [A] subplot and the Magnetic flux [pu] subplot exhibit the expected three-phase behavior; however, the Secondary currents [A] subplot does not. The solver failed to properly initialize the secondary currents. Running the simulation within the Solver Profiler reports dense groups of solver exceptions and zero crossings but does not indicate states below the absolute tolerance. Note the Off setting for Auto scale absolute tolerance.

Opening the Simscape Variable Scaling Analyzer

To open the Simscape Variable Scaling Analyzer, enter this command in the MATLAB^® command window:

simscapeVariableScalingAnalyzer

You can optionally specify the model that you want to analyze as an argument for the command.

Otherwise, you can choose which model to attach using the app interface.

Analyzing the Model

Running the simple circuit model in the app generates the results in the figure.

The app highlights potentially problematic states and provides suggestions based on the type of issues it finds. There is a cluster of highlighted states that share the unit Wb. The solver assigns this unit a nominal value of 1. However, the LogMaxAbsData column reports that the log of the states with this unit trend around -2.4, which is in proximity to -3, the log of the Absolute tolerance parameter. You can view a visual representation of the data by selecting the highlighted states and clicking Plot State.

Note the desired three-phase behavior, where each phase has three superimposed variables. The proximity of the states to the absolute tolerance suggests improper scaling of the flux.

Selecting and Rescaling Nominal Values

You can rescale nominal values locally using the Property Inspector for a block that creates a problematic state or you can globally rescale nominal values using the Nominal values for model window.

Locally rescaling nominal values

The problematic states deal with the units Wb, which do not explicitly tie to a certain block in the model. The figure shows the Property Inspector window for the Two-Winding Transformer (Three-Phase) block. In the Nominal Values section, when you select the check box next to each variable name, you can view the default local block settings for each value it generates.

Adjusting these values does not improve the performance of this model. Consider globally rescaling nominal values if local rescaling is insufficient.

Globally rescaling nominal values

You can launch the nominal values window for the model from the Simscape Variable Scaling Analyzer app by clicking Nominal Values.

To add a nominal value-unit pair, click Add nominal value-unit pair . In this example, rescaling the nominal value to 1e-3 makes the nominal value closer to where the state values trend. To learn more, see System Scaling by Nominal Values.

Checking Results

Rerunning the model from the analyzer after specifying a new value-unit pair generates these results.

The states from before are no longer highlighted, but one new state appears to behave differently than before. This may need to be rescaled, depending on your requirements. However, the model Scope block displays properly initialized secondary currents.