Variable Viewer

About Variable Viewer

Prior to simulating the model, you can use the Variable Viewer to check the results of the initial conditions computation for the model and to see which of the block-level variable initialization targets have been satisfied. The Variable Viewer displays the variable priority and target values, where specified, along with the actual initial values for all the variables obtained as a result of the solve.

To open the Variable Viewer, in the top menu bar of the model window, select Analysis > Simscape > Variable Viewer.

The Variable Viewer is a table, its rows listing all the blocks in the model and all the public variables under each block, and the columns providing the initialization status, priority, target and actual start values, and other information for each variable.

By default, the Variable Viewer opens in basic configuration, which has the following columns:

NameDescription
Status

Initialization status of each variable, can be one of:

  • Green circle — Displayed for variables with initialization targets satisfied, and also for all variables with no initialization priority.

  • Yellow triangle — Displayed for low-priority variables if the target is not satisfied.

  • Red square — Displayed for high-priority variables if the target is not satisfied.

  • Red cross — If initial condition solve fails, displayed for variables that could not be initialized.

  • Gray rectangle — Displayed when status is not available. This can happen, for example, if model initialization failed, or if the viewer was left open during diagram update. For more information, see Interaction with Model Updates and Simulation.

PriorityVariable initialization priority, as specified in the block dialog box or in the underlying component file. For more information, see Set Priority and Initial Target for Block Variables and Variable Priority for Model Initialization. If the variable has no initialization priority (priority.none or Unused), then this field is empty.
TargetInitial target value for a high-priority or low-priority variable. If the variable has no initialization priority, then this field is empty.
StartThe actual initial value of the variable computed by the solver.
UnitThe variable base unit, common for all the values (Target, Prestart, and Start). Simscape™ unit manager automatically converts all the values as needed. For example, if you specified the target Value in the block dialog box as 20 and the Unit as mm, the Variable Viewer displays the Target as 0.2 and Unit as m.

A downward-pointing arrow next to a column name indicates that you can filter the table rows based on their value in this column. For more information on the filtering options, see Useful Filtering Techniques.

The Variable Viewer toolbar buttons perform the following actions:

Displays the data in the Variable Viewer in tree view, with variable nodes grouped under the parent port, block, and subsystem nodes. This is the default view.
Displays the data in the Variable Viewer in flat view, to minimize the number of rows in the table. In flat view, the rows for parent nodes are not shown, and the table contains just one row per variable, with the Name column including the complete path to the variable from the model root. If the Variable Viewer is in flat view, the buttons that expand and collapse nodes are disabled.
Expands all nodes, showing all variables under each block name. This button is available only if the Variable Viewer is in tree view.
Collapses all variables under each block name. You can then expand the block nodes individually to see the variables under this block. This button is available only if the Variable Viewer is in tree view.
Recomputes the initial conditions for the model and refreshes the values displayed in the viewer. Use this button after adjusting the block parameter values, changing variable priorities and targets, or updating the block diagram. For more information, see Interaction with Model Updates and Simulation.
Clears all the column filtering options and displays all the rows in the table. For more information, see Useful Filtering Techniques.
Shows the Variable Viewer in its default, basic, configuration, with only the following columns displayed: Status, Priority, Target, Start, and Unit.
Shows the Variable Viewer in advanced configuration, with all the columns displayed. Use this view for troubleshooting your model, for example, if the model initialization failed.

Advanced Configuration

In most cases, the default Variable Viewer configuration contains sufficient data for viewing the variable targets and verifying the model initialization results. However, if the solver is unable to satisfy all the high-priority variable targets, or if the model initialization fails, the advanced Variable Viewer configuration might provide additional data that can help you troubleshoot your model.

To switch to the advanced configuration, click in the Variable Viewer toolbar.

In advanced configuration, the Variable Viewer displays the following additional columns:

NameDescription
PrestartThe value of the variable that the solver uses at the beginning of the initial conditions solve process. For variables with no initialization priority, the prestart values come from the variable declaration in the underlying component file. If the initialization process fails, these values can help you determine the reason (for example, a prestart value of 0 for a variable used as a denominator in a model equation). If a variable has an undesirable prestart value, specify a better value as a low-priority initialization target, to make the solver start iterations from a different point.
EliminatedThese variables are eliminated by the software prior to numerical integration and are not used in solving the system. Prestart values for these variables have no effect on the system solution. However, you can set the initialization priority and targets on these variables, in which case their targets will be represented in terms of the variables that are retained by the solver.
DeterminedThe values of these variables depend on the system inputs, or their values are predetermined based on the analysis of equations. Therefore, specifying initialization priority and targets for these variables has little or no impact on system solution. Also, if you specify a high-priority target for a predetermined variable, the solver most likely will not be able to satisfy this target but will spend extra time trying to find a second-stage solution.
DifferentialTime derivatives of these variables appear in equations. These variables add dynamics to the system and can produce independent states. Therefore, these variables are more likely to require high initialization priority.

You can change the default order of columns by clicking a column heading and dragging it, while holding down the mouse button, to the desired location. You can also hide columns by right-clicking their headers and selecting Hide This Column from the context menu, or clearing the check mark next to a column name. Clicking or in the Variable Viewer toolbar restores the default basic or advanced layout, respectively.

Switching Between Tree View and Flat View

You can control the number of rows in the Variable Viewer by switching between the tree view (the default) and the flat view. By default, the Variable Viewer opens in tree view, with variable nodes grouped under the parent port, block, and subsystem nodes. Therefore, the Variable Viewer table contains the rows for the parent nodes (ports, blocks, and subsystems) in addition to the rows that correspond to all the public variables. Only the rows that represent variables contain data such as targets and actual values. All rows display a status, with the status of a parent node being determined by the status of its children variables: if all the children are green, then the row for the parent node also displays a green circle in its Status column.

For example, in the Variable Viewer table below, the first row represents the Ideal Translational Motion Sensor block, the second row — port C of this block, and only the third row contains the data for the actual variable v (velocity at port C).

To switch to the flat view, click in the Variable Viewer toolbar.

In flat view, the rows for parent nodes are not shown, and the table contains just one row per variable, with the Name column including the complete path to the variable from the top-level model. For example, the first row of the Variable Viewer table in flat view represents the same variable v (velocity at port C of the Ideal Translational Motion Sensor block), and the Name column includes the names of its parents and shows the path to the variable. Flat view makes the Variable Viewer table more compact.

If the Variable Viewer is in flat view, the buttons that expand and collapse nodes are disabled.

To switch back to the tree view, click in the Variable Viewer toolbar.

Useful Filtering Techniques

A downward-pointing arrow next to a column name indicates that you can filter the table rows based on their value in this column.

To filter the rows, click the arrow, and then select or clear the check boxes in the drop-down list to indicate which rows you want to be displayed, based on their value. Selecting All clears all the filters for that column. To clear all filters for all columns, click in the Variable Viewer toolbar.

For example, filtering on the Priority column values (selecting only the check boxes for HIGH and LOW) lets you view all the targets and actual values in a compact format, which can be helpful for a large model.

You might also find the following filtering techniques useful in troubleshooting your models:

  • Filter the Differential column on TRUE, to display only the rows for differential variables. Time derivatives of these variables appear in equations. These variables add dynamics to the system and can produce independent states, therefore these variables are more likely to require high initialization priority.

  • Filter the Determined column on TRUE, to verify that these variables have no initialization priority. The values of these variables are either predetermined by the equation analysis or depend on the system inputs, and therefore specifying initialization priority and targets for these variables has little or no effect on model initialization.

Interaction with Model Updates and Simulation

The Variable Viewer computes the actual initial values of the variables by running the simulation for 0 seconds. Therefore:

  • The model must be in an executable state when you open or refresh the viewer, otherwise you get an error message.

  • If the scopes are open, they turn blank every time you open or refresh the viewer. Rerun the simulation to see the new results.

  • If you rerun the simulation while the Variable Viewer is open, the results in the viewer are automatically refreshed when the simulation starts running.

  • If you change variable priorities and targets or adjust the block parameters while the Variable Viewer is open, the results in the viewer are not updated automatically. Refresh the viewer (by clicking in the Variable Viewer toolbar) to compute the new actual values of the variables and update the status.

  • If you update block diagram (by selecting Simulation > Update Diagram in the top menu bar of the model window) while the Variable Viewer is open, the previously computed actual values become unavailable and the Status column displays gray rectangles. The overall status at the bottom of the Variable Viewer window is also not available. Refresh the viewer to compute the new actual values of the variables and update the status.

Related Examples

More About

Was this topic helpful?