WOLFRAM SYSTEMMODELER TUTORIAL

Model CenterVariable Views

Introduction | Class Browser | Class Window | Graphical Views | Modelica Text View | Component Browser | Variable Views | Reliability View | Messages View | Kernel Command View | Documentation Center | Functional Mock-up Interface | Keyboard Shortcuts | Kernel Commands

The bottom area of the model editor shows one or several tabs dedicated to viewing and editing parameters, variables, and constants of the class in the active class window, as well as of its components. Parameters and constants are variables with a restricted variability in Modelica. Below, the term variable will be used for all three of them, unless it is necessary to distinguish between them. If no component is selected, the variables of the class will be shown. To show the variables of a specific component, select the component in the Icon View, the Diagram View, or the Component Browser.

The tabs shown depend on the class being shown. The grouping of variables in a class can be configured in the Show in Variable Views section of the Component Properties dialog for each variable. This dialog can be opened by clicking the name of the variable in the view at the bottom of the screen, or right-clicking on the variable in the component browser and choosing Properties. This dialog is described in more detail in this section.

Variables, parameters, and constants can be shown in separate tabs by opening the Variables view, Parameters view, or Constants view in the View menu. These tabs are hidden by default.

For models that have replaceable classes, these classes appear as parameters in the General and Parameters views.

Sorting Variables

The variables in a view can be sorted by name or declaration order. By default, they are sorted by declaration order.

To sort by name, right-click an empty area of the view and choose Arrange by Name from the popup menu.

1.gif

Sorting the variables by name.

Editing Variables

Before attempting to edit a variable, make sure that either the Icon View or Diagram View is the active view of the class window. Editing in the variable views is disabled while editing the class in the Modelica Text View. Note that editing is also disabled for read-only classes, as these cannot be edited.

Variables have several editable attributes. To give a variable an initial value, edit the value of the corresponding Initial Value box. All editable attributes of variables are explained in detail below. Note that the number of attributes available will depend on the type of the variable. For instance, a variable of type String has only the attribute value.

  • Value. Specify a value to give the variable a constant value throughout the simulation or set the value of a parameter. If the class contains alternatives for this value through choices annotations or enumerations, these choices will be shown in a drop-down box for easy selection.
  • Initial Value. The initial value of the variable, by default zero or an array of which all elements are zero.
  • Fixed. If set to false (default setting for variables), the simulation tool (solver) is free to use another initial value than the one specified, if necessary in order to solve the systems of equations. If set to true, the initial value of the variable is fixed to the value specified in the Initial Value box. Note that state variables have the fixed attribute set to true as the default setting. This does not conform to standard Modelica, but since SystemModeler allows an overdetermined system of equations as an initial condition, it is more intuitive with the fixed attribute set to true for state variables.
  • State Select. This attribute provides manual control over the selection of state variables for numerical solution of equation systems. The column is only shown in the Variables view, which can be shown by choosing View Variables. The alternatives are as follows:
  • never. The variable will never be selected as a state variable.
  • avoid. Use the variable as a state variable only if it appears differentiated.
  • default. Select the variable as a state variable if appropriate, meaning that the variable is likely to be selected as a state variable if its derivative appears in the model. This is the default setting.
  • prefer. The variable is preferably selected as a state variable over those that have the default attribute.
  • always. The variable will always be selected as a state variable.

Note that variables declared with the final or outer attribute are not shown. For more information on how to declare a variable final or outer, see this section.

Editing a Variable for Several Components at Once

On some occasions, you may find it useful to set an attribute of a variable for several components at once. This is possible as long as the components are of the same type. Select the components whose variables you wish to edit. For those variable attributes that are the same for all components, the values will be shown in the value text boxes. If the values differ, the text boxes will show "No Common Value". When typing in a new value for a variable or editing an existing value, all of the selected components will be affected. Components that inherit from the same base class can be selected and the variables from the base class edited in the same way.

Editing Using Specially Adapted Dialogs

The values of variables can also be edited using specially adapted editing dialog by clicking the edit icon next to the edit field. Clicking this icon will bring up a dialog suitable for editing values of the variable's type, such as a color selector for variables specifying a color.

A parameter input field with an edit button.

The type of edit dialog that is shown is determined by the variable's type and if the variable has any associated standard Modelica annotation requesting a specific type of editing dialog, such as the Dialog.colorSelector annotation.

Editing Arrays

For array variables, clicking the edit icon next to the edit field will open a dedicated array editor. The array editor consists of two synchronized views: a table view and an expression view. Either view can be used to edit the array. The expression view can be used to edit any array expression, but is mostly used to edit arrays constructed by non-literal expressions. The table view is an evaluated version of the expression view and is the preferred view to edit individual elements of an array.

When editing an array in one view, it may happen that the other view becomes disabled and an error message is displayed in the bottom left of the array editor dialog. This is an indication that the array is invalid, and the cause could be, for instance, an illegal expression in the expression view or a cell with an invalid value in the table view. Correcting the error will enable the other view again.

displayUnit

All physical variables in a Modelica model should be declared with a unit. The unit attribute of a variable is the unit used in all equations, and the equations are only correct for those particular units. However, it is possible to change the unit displayed to you as a user in the graphical user interface by specifying a displayUnit. As an example, say you have a model with a Modelica.Mechanics.Translational.Components.Mass component, and you wish to display its mass (variable m) in the unit "lb" rather than the default unit "kg". To do this, click the mass component, go to the variable view, find the parameter m and click the kg button. This opens up a drop-down menu with all the possible display units for that particular parameter.

3.gif

Setting the displayUnit to lb instead of kg in the variable view.

When you click lb in the menu, the value in the Value field is converted from kilograms to pounds in the graphical user interface. At the same time, unless your model is read only, a short piece of Modelica code, namely displayUnit="g", is added to the parameter m in component mass1 in the text view of the model.

4.gif

displayUnit="g" has been added to parameter m in component mass1.

Note that the top unit in the drop-down menu is also the base unit and is kept separated from the derived units with a gray divider.

When editing the value in the Value field, a different displayUnit can be chosen without automatically converting the value. Once the value and displayUnit is set, the drop-down menu is used to convert the value between different units.

Worth noting is that whenever the value of a variable is set using a drop-down menu containing predefined values, the displayUnit changes back to the base unit. The reason for this behavior is that predefined values are always specified in the base unit.

Redeclaring Replaceable Classes

An advanced configuration feature allows switching out complete classes used in a model. This makes it easier to quickly reconfigure parts of your model. Classes like these are called replaceable classes. These classes are shown as parameters in your model.

5.gif

A replaceable class shown as a parameter, with available choices shown in dropdown.

To redeclare the replaceable class, choose one of the items in the dropdown.

A replaceable class can be further modified by adding modifiers to the redeclaration. These modifiers can be added in parenthesis after the class name.

6.gif

A replaceable class redeclared with a modifier to the tire radius R.

Adding Variables

To add a variable to a model, use the Insert menu, or right-click an empty area of the variable views to bring up a popup menu from which you can choose to add a variable, parameter, or constant. The dialog box that appears is the common dialog box for adding variables of any kind of variability.

7.gif

Adding a continuous variable of the SI unit type Current to a resistor model.

The dialog box is divided into two views:

  • General. In this view you specify the variability, type, dimensions, name, value, and description of the variable.
  • Attributes. This view lets you specify various attributes of the variable.

To add the variable, click the Add button. The variable will appear in the Component Browser. If the Variables view is visible, the variable will appear there as well. The dialog box will remain open to let you add more variables. To close it, click the Close button.

The sections of the dialog box are described in more detail below.

  • General: Variability. Specifies the variability of the variable, with respect to simulation time.
  • Unspecified (default). For variables of type Real, the variability (continuous or discrete) will be determined by the context in which it is used. The variability will be discrete for variables of type Boolean, Integer, String, and enumeration.
  • Discrete. Discrete variables are piecewise constant with respect to simulation time and may only be changed by events during simulation.
  • Constant. Constants can never change once defined.
  • Parameter. Parameters may change before simulation, but remain constant during simulation.
  • General: Type. Specifies the type of the variable. Note that the SI unit and non-SI unit types are only available if the Modelica Standard Library is loaded.
  • Built-in. Modelica built-in types.
  • SI unit. SI unit types defined in the Modelica Standard Library.
  • Non-SI unit. Non-SI unit types defined in the Modelica Standard Library.
  • Other. Custom type. If you do not know the full path of the type, you can search for it using the Class Browser and then drag the type from the Class Browser and drop it in the text box. See this section for information on how to use the Class Browser to find types and other classes.
  • General: Array. Specifies the dimensions of the variable. Leave this section unchecked for scalars.
  • Dimensions. The number of dimensions.
  • Sizes. The dimension sizes. If the number of dimensions exceeds four, a single text box is shown where the dimension sizes are separated using a comma.
  • General: General. Specifies the name, value, and description of the variable.
  • Name. The name of the variable.
  • Value/Initial Value (optional). The value for variables with the variability set to Parameter or Constant and the initial value for continuous and discrete variables.
  • Fixed. If checked, the initial value is fixed; otherwise the initial value is used as a guess value. Only applicable for continuous and discrete variables.
  • Description (optional). A short description of the variable.
  • General: Show in Variable Views. Specifies whether the variable should be visible in the variable views (parameters are always visible).
  • View. The name of the view in which to show the variable. This is the name of the tab in the bottom area of Model Center.
  • Group. The name of the group under which the variable should be listed. This is the grouping inside tabs.
  • Attributes: Properties. Specifies the properties of the variable.
  • Final. Prevents modifications of the variable.
  • Protected. Access to the variable is restricted to the class in which it is declared and to classes inheriting that class. Clear this checkbox to make the variable accessible from all classes.
  • Replaceable. Allows modifications of the variable in form of redeclarations.
  • Flow. Applies only to variables declared in connector classes. The flow property specifies whether the sum of the quantity should sum to zero when connected. Select this checkbox for variables specifying a flow quantity such as current, fluid, force, etc. Clear this checkbox for variables specifying potential (non-flow) quantities, such as voltage, pressure, position, etc.
  • Stream. Applies only to variables declared in connector classes. A stream variable describes a quantity that is carried by a flow variable. The value of the stream variable is the specific property inside the component close to the boundary, assuming that matter flows out of the component into the connection point.
  • Attributes: Causality. Specifies the causality of the variable. The causality of a variable does not have to be explicitly specified unless the variable is an input or output to a block or function.
  • None (default). No explicitly specified causality.
  • Input. The variable is an input to a class.
  • Output. The variable is an output to a class.
  • Attributes: Dynamic Reference. Specifies the dynamic reference property of the variable.
  • Inner. Enable access to the variable in nested scopes.
  • Outer. Make the variable reference an inner variable with the same name in an enclosing scope.

Removing Variables

To remove variables of a class, locate the component that represents the variable in the component browser and remove it. For information on how to remove components, see this section.

Introduction | Class Browser | Class Window | Graphical Views | Modelica Text View | Component Browser | Variable Views | Reliability View | Messages View | Kernel Command View | Documentation Center | Functional Mock-up Interface | Keyboard Shortcuts | Kernel Commands