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 model window, on the Debug tab, click Simscape > Variable Viewer.
If you open a model, and then open the Variable Viewer before simulating the model, then the viewer does not contain any data. The Refresh button displays a warning symbol (), and a message at the top of the viewer window tells you to click the Refresh button to populate the viewer with data.
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, unless you specified another configuration as a preferred one. (For information on specifying a preferred configuration, see Saving Viewer Configuration.) In basic configuration, the Variable Viewer has the following columns:
Initialization status of each variable, can be one of:
|Priority||Variable 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
|Target||Initial target value for a high-priority or low-priority variable. If the variable has no initialization priority, then this field is empty.|
|Start||The actual initial value of the variable computed by the solver.|
|Unit||The 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 Beginning Value in the block dialog box as
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. If the data in the Variable Viewer is out of sync with the model, he Refresh button displays a warning symbol (), and the timestamp at the bottom of the viewer window turns red. 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.|
|Saves the current Variable Viewer configuration. For more information, see Saving Viewer 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:
|Prestart||The value of the variable that the solver uses at the beginning of the initial conditions solve process. For variables with no override of initialization priority and targets, 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 (or no-priority) initialization target, to make the solver start iterations from a different point.|
|Eliminated||These 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.|
|Determined||The 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.|
|Differential||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.|
|Representation||If frequency-and-time simulation mode is turned on, indicates how the solver marks the variables: Frequency ("fast") or Time ("slow"). For more information, see Frequency and Time Simulation Mode. In regular simulation, all variables are marked Time.|
|Nominal||Nominal value of the variable. For more information, see System Scaling by Nominal Values.|
|Nominal unit||Physical unit associated with the nominal value of the variable. For more information, see System Scaling by Nominal Values.|
|Nominal source||Source of the nominal value and unit: Block, Model, Derived, or Fixed. For more information, see Possible Sources of Nominal Values and Their Evaluation Order.|
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
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.
Component Array Representation in Variable Viewer
When your model contains blocks with underlying arrays of components, Variable Viewer includes variables that belong to array members.
For example, in the Variable Viewer table below, the Simscape
Component block contains an underlying array of resistors. In tree view (the
default), the Variable Viewer table contains the nodes
p, corresponding to the ports of the Simscape
Component block itself, each with its variable
v. Then the
Variable Viewer table contains the tree nodes for each of the array members, numbered
resistor(2), and so on. Each of these
numbered nodes, in turn, contains rows that correspond to the nodes and variables of the
underlying resistor component. Only the rows that represent variables contain data such as
targets and actual values.
If the component array size is
1xN, the members are numbered
comp(N). If the array size is
NxM, the members are numbered
Flat view makes the Variable Viewer table more compact. This is how the same array of resistors looks in the flat view. 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 variables that belong to the members of the component array, the path to the variable contains the numbered component name.
For example, the third row of the Variable Viewer table in flat view represents the same
i (the current through the first resistor) as the seventh row in the
tree view, and the Name column includes the array member name
resistor(1) in the path to the variable.
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
LOW) lets you
view all the targets and actual values in a compact format, which can be helpful for a large
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.
Saving Viewer Configuration
The Save Viewer Configuration button ( ) in the Variable Viewer toolbar lets you save the following configuration preferences:
Variable Viewer view type (tree or flat)
Ordering of columns
Filters applied for all columns (both visible and hidden)
Sorting on a specific column
If you save viewer configuration, then the next time you open Variable Viewer, for this or another model, it will open with the same configuration. This behavior is consistent with saving other MATLAB® preferences.
Link to Block Diagram
The Variable Viewer tool provides direct linking to the block diagram. This link lets you highlight the appropriate block, or easily go from a variable listed in the Variable Viewer to the Variables tab in the corresponding block dialog box, to modify the variable priorities and targets.
When you right-click in the Name column of any row in the Variable Viewer table, a context menu opens with the following options:
Go to block — Highlights the corresponding block in the block diagram, opening the appropriate subsystem if needed. If the row represents a variable, highlights the parent block for this variable.
Open block dialog — Opens the corresponding block dialog box (for a variable, opens the parent block dialog box). In the block dialog box, click the Variables tab to view or modify the variable priorities and targets. If the selected row represents a subsystem, this option is not available.
Interaction with Model Updates and Simulation
Opening the Variable Viewer does not trigger an automatic update. For complex models, computing initial values for all the variables can last several minutes, and unnecessary updates could lead to loss of productivity. You have to update the data explicitly by clicking the Refresh button ().
When you open the Variable Viewer, it gets populated with the data from the last simulation. The status at the bottom of the viewer window displays the timestamp of its last update. If you have modified the model since the viewer has last been updated, the Refresh button displays a warning symbol (), and the timestamp at the bottom of the viewer window turns red to indicate that the data in the viewer might not reflect the latest model changes.
If you open a model, and then open the Variable Viewer before simulating the model, then the viewer does not contain any data. The Refresh button displays a warning symbol (yellow triangle), and a message at the top of the viewer window tells you to click the Refresh button to populate the viewer with data.
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 refresh the viewer, otherwise you get an error message.
If the scopes are open, they turn blank every time you 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, 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 Modeling > Update Model in 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.