# Simulation Center—Equation Browser

Introduction | Options | Experiment Browser | Plot Windows | 3D Animation | **Tools** | Importing and Exporting | Keyboard Shortcuts | Input Variable Data Files | File Formats | Communication with Simulation

## How to Get to the Equation Browser

There are several ways to get to the Equation Browser:

- To open the Equation Browser and go to the block that solves a particular variable, right-click the variable in the Plot view of the Experiment Browser and select Show in Equation Browser.

- To open the EquationBrowser and go to the block that generated a particular message in the Simulation Log, click the link at the end of the message.

Error message in the Simulation Log with link to the corresponding block in the Equation Browser.

## Overview

The Equation Browser consists of the three tabs, each corresponding to its part of the simulation problem:

- Integration—the part of the dynamic problem that needs to be solved by integration in order to advance the time.

- Output—the part of the dynamic problem that can be calculated from the variables solved in the integration part.

Each tab is divided into two parts, the *block browser* on the left and the *block view* showing the currently selected block on the right.

The Equation Browser is divided into two parts, the block browser on the left and the block view to the right.

### Equation Blocks and Equation Systems

An appearance of a variable in an equation is called an *incidence*. In order to identify the block structure shown at the bottom part of the block browser, only basic incidence information is needed (see Incidence Information). This information is collected for all equations and variables, resulting in the bipartite global *incidence graph*. Then, a (variable-equation) matching is used to turn the bipartite graph into an equation dependency graph, whose strong components are what is called the *equation blocks*. Sorting the strong components topologically reveals the lower triangular structure seen in the block browser.

Each equation block is associated with the variables matched to the equations in the block. The *block incidence graph* is the bipartite incidence graph of the equations and variables in a block. The Incidence Graph is found in the upper part of the block view, where rows correspond to equations and columns correspond to variables.

To solve the equations of a block, the equations and variables are organized into one or more *equation systems*. Each equation or variable may be part of one or more equation systems. For most blocks, however, there is no overlap between equation systems, and incidence information relating to the equation system is visualized in the block view's incidence graph.

## Classification

Classification in the Equation Browser is found at several levels, and each level is considered in turn in this section, starting with variables and ending at the block level.

### Variable Classification

In the Equation Browser, one is only concerned with variables that have values, meaning that external object variables will not be considered. Each remaining scalar variable then belongs to one of three categories, according to its *value domain* and *time variability*, with each category having its own symbol:

A *discrete-time* variable can only change value at events, and a *discrete-valued* variable can only take on values from a discrete set. A *continuous-time* variable can change value continuously between events (which is why it cannot be discrete valued) and is allowed to have discontinuous changes at events. The possible combinations correspond directly to Modelica scalar types and variability restrictions:

### Incidence Information

Depending on the application, information of different levels of detail may be associated with an incidence.

#### Basic Incidence Information

The *basic incidence information* used to identify the block structure consists of a classification as either:

*independent*—variable appears in equation, but not in such a way that the equation can be used to solve for the variable.

Basic incidence information for the discrete part of a mixed-value block. Dependent incidences are marked with a filled symbol (always a circle in the case of a discrete-valued variable), while independent incidences are marked with an empty circle.

In the Incidence Graph, an independent incidence is shown as an empty circle, whereas a dependent incidence is shown as a filled symbol (not necessarily a circle). Since this information is only a function of the equation and variable of the incidence, the basic incidence information can always be displayed directly for the incidence graph of a block.

Incidences of discrete-valued variables never get further classification, whereas incidences of continuous-valued variables may be further classified depending on the type of system they appear in.

#### Enriched Incidence Information

When more detailed incidence classification is needed for a continuous-valued variable, this happens in the context of a system of equations. The partial derivative of the equation's residual with respect to the variable is classified as one of the following, in increasing order of dominance:

Symbols used to represent enriched incidence information in the Incidence Graph.

This is called the *enriched incidence information*. In the Incidence Graph, the information is shown using the color and shape (used for linear system incidence variability) of the filled incidence symbols, as explained in the incidence graph's legend. As long as the equation systems do not have overlapping incidences, the enriched incidence information can be shown directly in the incidence graph of a block; otherwise, the equation system context needs to be specified (currently not supported by the Equation Browser).

### Equation System Classification

An equation system is classified according to the value domain of the variables it solves for:

For an equation system that is solved using the enriched incidence information, the system is also classified according to the most dominant incidence:

The size of an equation system is measured in the number of variables it solves for. When tearing is applied, the torn system size is defined by not counting the variables solved in the triangular inner system of the tearing partitioning.

### Block Classification and Homotopy Structure

Finally, the value domain, time variability and equation system class are propagated from the equation systems of a block to the block as a whole.

The size of a block is again measured in the number of variables solved in the block. When filtering blocks by size, it is also convenient to define the torn size of a block. The torn block size is derived from the torn system sizes of the equation systems contained in the block, but the exact relation depends on how the equation systems are used to solve the block.

Above the block structure shown in the block browser, blocks in the initialization problem may also be linked by homotopy initialization. This structure is currently not visible in the Equation Browser.

## Block Browser

The block browser shows the equation blocks that belong to the selected part of the simulation problem (Initialization/Integration/Output), sorted in the order that they will be solved. The blocks are laid out on the diagonal, and the dependency links between blocks are illustrated with a dot on the left side of the diagonal. If the block at position (i,i) depends on the block at (j,j), there will be a dependency link dot at (i,j). Click the dependency link dot to jump between the dependent block and dependee block. The tooltip for the dependency link will show the variables that are solved by the dependee block and used in the dependent block.

To get more information on a block, select the block by clicking it, and information about that block will be presented in the block view to the right. When a block is selected, all its incoming and outgoing dependency links are highlighted.

The Equation Blocks view with the blocks laid out diagonally and dependency links shown on the left side of the diagonal.

### Color Scheme

There is a user-selectable color scheme for each classification axis that can be used to quickly identify objects of a specific class. The selected color scheme is applied throughout the Equation Browser on blocks in the block browser, on systems in Block Summary and on incidences in the Incidence Graph.

### Filtering

It is possible to filter blocks by the three classification axes: system class, value domain and time variability. When a filter item is unselected, it shows in parentheses how many blocks there are of that class within the subset selected by the other filter axes. This means that in addition to finding specific blocks, the Block Filter alone can also be used to get global model statistics like:

It is also possible to filter by block size. If Use torn size is checked, the block size after tearing will be used for filtering. The size buttons have a tooltip that shows how many blocks there are of that size. Sizes that are present in the subset of blocks currently selected by the filter are shown in bold.

Block Filter illustrating that there are three linear systems with mixed-value domain.

Filtered blocks are represented by a small gray block in the Equation Blocks view. To expand a filtered block and undo the effect of filtering on one group of filtered blocks, right-click the block and choose Expand Block. To collapse expanded blocks, right-click anywhere in the Equation Blocks view and choose Collapse Expanded Blocks.

## Block View

When a block is selected in the block browser, it is presented in more detail in the block view on the right side of the Equation Browser.

The block view, with an active selection of an incidence and its corresponding equation and variable.

### Block Summary

The Block Summary shows the classification of the selected block along the three different classification axes, as well as the block size before and after tearing. At the bottom, there is a list of systems in the block, and for each system there is a link. Click the link for system-specific actions like going to the generated code for the system. If Calculate Condition Estimates is enabled, it is also possible to plot the condition estimate for the system if the current block is in the Integration or Output tab. If it is in the Initialization tab, the condition estimate before and after initialization is available as a tooltip on the system link.

Click on the systems link in the Block Summary for system-specific actions like plotting the condition estimate for the system, or go to the generated code for the system.

### Incidence Graph

The Incidence Graph shows the incidence graph for the currently selected block, with rows corresponding to the equations listed in Equations in Block, and columns corresponding to variables listed in Variables Solved in Block. When an equation is selected in Equations in Block, the corresponding row is also selected in the Incidence Graph, and when a variable is selected in Variables Solved in Block, the corresponding column is also selected.

When the block contains overlapping equation systems, it only shows basic incidence information. Otherwise, it both shows any enriched incidence information, as well as a possible partitioning into sub-blocks. Partitioning indicated by gray lines corresponds to equation system tearing.

### Equations in Block

The equations of the currently selected block are listed in Equations in Block. Variables belonging to the selected block are marked in **bold**. Clicking a variable shown in blue gives a menu with links to related places in the Equation Browser. There is also a contextual menu for the equation, containing links for all variables in the equation.

### Variables Solved in Block

The variables solved in the selected block are listed in Variables Solved in Block. A variable that is not available in the simulation result is shown with a disabled look. A variable can be missing due to the current output settings, or because it is an internal help variable that is not stored.

The Initialized To column shows how a variable's start value is used and the actual value after initialization (if simulation result is available for the variable). The start value can be used in three possible ways:

— initialized exactly from start value.

—solved in a block that is solved iteratively;start value is used as initial guess.

—calculated directly from other variables;start value does not have any impact on initialization.

#### Plotting

When the model has been simulated, all variables that are available in the simulation result will have a checkbox next to them. Click the checkbox to plot the variable in the currently active plot. For information on how to create new plot windows or subplots, see the section on Plot Windows.

If there is more than one experiment with a similar variable structure, it is possible to enable automatic plotting from other selected experiments where the variable exists. To set up plotting from other experiments, click the experiment name in the Plot from label and select the experiments to plot from.