WOLFRAM SYSTEMMODELER TUTORIAL

Model CenterClass Browser

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 Class Browser is used to browse packages and components of libraries, and to perform operations on classes, such as renaming, saving, and more.

The Modelica Class Concept

In Modelica, classes are used to model systems. From a class it is possible to create any number of objects that are known as instances of that class. An instance of a class is also often referred to as a component. As a class is very general and does not give any information about what it defines, several kinds of specialized classes are available. The class specialization of a class specifies the constraints that apply to the class.

  • Model. The model class is by far the most commonly used kind of class for modeling purposes. The only restriction is that a model may not be used in connections.
  • Package. A package is primarily used to organize Modelica code and may only contain declarations of other classes and constants. No variable declarations are allowed within a package.
  • Function. The function concept in Modelica corresponds to mathematical functions without external side effects and may be recursive.
  • Connector. Connector classes are typically used as templates for connectors. A connector is a connection point used for communicating data between objects.
  • Record. The record class is used for specifying data without behavior.
  • Block. A block is a class for which the causality (whether the data-flow direction is input or output) of each of its variables is known.
  • Type. Classes of specialization type are used to define custom types, extending a predefined type, enumeration, array of type, or a class extending from another type.

Browsing Classes

Modelica classes and their hierarchical organization are visualized using grouped tree views in the Class Browser. Classes are grouped into packages and components, where the items of each group are sorted alphabetically. Packages are represented as branches of the tree and components as leaves. To show the contents of a package, expand it by clicking the symbol to the left of its icon (or name if the package has no icon). Double-clicking also expands packages. Inside packages, items are ordered according to the specifications of the library developer. This is usually controlled with a package.order file or through declaration order.

Clicking the symbol to the left of an expanded package will show it as collapsed again, hiding its contents.

1.gif

Browsing the Modelica Standard Library.

To view the contents of a package as a separate group within the Class Browser, right-click its name and choose View as Group. This can prove useful if you use components from more than one package when designing a model. By opening the packages of interest as separate groups, you can minimize the scrolling up and down needed in order to find the components.

2.gif

Viewing the contents of two packages in separate group views.

The icon of a package or class can be copied to the clipboard as an image by right-clicking its name and choosing Copy Icon as Image.

It is possible to view balloon help (on-screen information) for a class by moving the mouse cursor over its icon and holding it still for a short period of time. The class name and description (if available) are shown.

Finding Classes

If you know the name of the class you are looking for, or parts of its name, you can use the search feature of the Class Browser to find it. This is especially useful if you do not know the exact location of the class. Type in the text to search for in the text box at the top of the Class Browser. Pattern-matching searching is supported using one or more * characters. A * character matches zero or more characters of any kind. For example, a search for analog*resistor will find all resistor classes located in the Modelica.Electrical.Analog.Basic package but filter out all resistors in other packages, such as Modelica.Electrical.MultiPhase.Basic and Modelica.Electrical.QuasiStationary.SinglePhase.Basic.

While typing, a short list of matching results will appear in a group below the search box, in the top of the Class Browser. To get a complete list of matching results, press Enter or click the Find All button. The number of hits that the search resulted in is displayed within parentheses in the title bar of the group. If there is a single match for the entered search term, the button changes into Open, and clicking it or pressing Enter will open the class in a new class window.

3.gif

Finding transformer classes using the search feature of the Class Browser.

You can go directly to the location of a class in the Class Browser by right-clicking components in the Component Browser or the Diagram View and choosing Go to Class in Class Browser in the popup menu.

Copying Classes

Classes can be copied using drag-and-drop within the Class Browser or by using menus. The destination of the copy operation can be any other class as long as the class is not read-only. Drag the class you want and drop it on the class in which you want the copy to be created. To copy a class to the top level of the class hierarchy, drop the class on the item representing the root of the group.

Another way to copy a class is to right-click it and choose Copy. The class is copied to the clipboard and can be inserted to any number of classes by first selecting the class and then choosing Paste from the Edit menu.

A third way to create a copy of a class is to right-click it and choose Duplicate.

Once the class is dropped or a class is pasted using the menu, a confirmation dialog box will be shown. The dialog box will also let you give the copy a name different from the original. Note that copying very complex classes or packages with many local classes is a time-consuming task and may take a considerable amount of time.

4.gif

Copying the Modelica.Mechanics.Rotational.Components.BearingFriction class.

Opening and Editing Classes

To open a class, right-click its name and choose Open from the popup menu. For classes that are not packages, double-clicking its name is a more convenient way. The class will appear in a new class window unless the class has already been opened, in which case its class window will become the active class window.

The default view of the class window when opening a class depends on the specialization of the class. For example, the default view of a package is the Icon View, while the default view of a model is the Diagram View. The default view can be changed for a specific class by specifying a preferred view as a Modelica annotation within the definition of the class. For more information on how to create such an annotation, see the section on specifying a preferred view.

In case the file in which the class is saved has the read-only attribute set, the class becomes read-only as well. A read-only class is still possible to open in a class window, but the class cannot be edited. All classes in the Modelica Standard Library and the IntroductoryExamples library are read-only.

Creating Classes

New classes are created either by using the popup menus of the Class Browser or the File menu. Choose New Class from the popup menu that appears when right-clicking in an empty area of the Class Browser, or choose New Class from the File menu. This will open a dialog box in which you will be able to specify the attributes of the class.

If you want to insert the new class into an existing class, you can right-click the parent class in the Class Browser and choose New Class from the popup menu. The Insert into text box of the dialog box will then be filled in automatically for you.

5.gif

Creating a new class.

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

  • General. Specifies general information about the class, such as the specialization, name, and description.
  • Specialization. The drop-down menu provides a selection of different class specializations, which specify the constraints that are applied to the class. For more information about class restrictions, see the section on the Modelica class concept. If you select Enumeration as the class specialization, the dialog will allow you to specify enumerators and their corresponding descriptions. To add a new item to the enumeration, select an empty field in the Enumerator column and start writing. Remove items by selecting a row and clicking the button with a minus sign, and rearrange by clicking on the up and down arrow buttons.
  • Name. The name identifies the class.
  • Description (optional). The optional description input field is where the class can be described. The class description, if specified, appears along with the name of the class as a balloon help for the class in the Class Browser.
  • Insert into (optional). If specified, it states the location of the class. If you create a class using the File menu, the Insert into text box will be empty, which means that the class will be created at the top level of the class hierarchy. Creating the class using the popup menu of the Class Browser will insert the class in the class currently selected in the Class Browser (if any).
  • Extends (optional). The Extends field specifies the base classes to inherit from. Multiple base classes can be specified by using a comma to separate them. In many situations it is convenient to declare a base class with a general interface that is extended when creating more specialized classes. You will see that this is a common practice in the Modelica Standard Library, where for example almost all two pin analog electrical components inherit the Modelica.Electical.Analog.Interfaces.OnePort class. If you do not know the full path to the class you want to extend, you can use the Class Browser to search for the class and then drag it from the Class Browser and drop it on the text box. See this section for more information on how to find classes using the search functionality of the Class Browser.
  • Short Class Definition. If the Short class definition checkbox is checked, the class is defined using a short class definition. Classes with a short class definition must extend from exactly one other class.
  • Properties. Specifies the partial and encapsulated properties of the class.
  • Final. Prevents the class from being modified using redeclarations.
  • Partial. The partial property is used to indicate that a class is incomplete such that it cannot be instantiated. A partial class can only be used as a base class.
  • Encapsulated. An encapsulated class represents an independent unit of code. All dependencies outside the class must be explicitly stated using import statements.
  • Protected. A protected class is inaccessible to classes outside of that class. The protected property is only applicable to classes located within another class. By default, protected classes are not visible in the class browser.

Renaming Classes

A class can be renamed at any time by right-clicking the name of the class in the Class Browser, choosing Rename from the popup menu, and editing the name in the Class Properties dialog box. It is also possible to rename a class by selecting its icon and pressing the F2 key.

When renaming a class from the Class Properties dialog box, all references to the renamed class will be updated automatically in all currently loaded classes. For example, if you have a class Resistor that inherits the class TwoPin and you rename class TwoPin to TwoPinInterface, the Resistor class will automatically update its inheritance to class TwoPinInterface. When the renaming operation is completed, a list of all classes that were modified due to references to the renamed class is shown.

6.gif

List of modified classes after renaming a class.

Renaming a class will often change in what file the class is saved. If that is the case, a dialog will be shown warning about this:

7.gif

Warning that renaming the class will change where it is saved.

Clicking the Rename and Save button will perform the rename and immediately save the class in the new location. If the model contains references to external files, these references may need to be updated after the rename has been performed. Examples of such references include:

  • modelica:// URIs referencing the renamed class or one of its children
  • images in icon and diagram layer
  • external files with C code
  • CAD files for animation
  • data files for tables

Deleting Classes

To delete a model or any other class, select it by clicking its name and choose Edit Delete, or right-click the name of the class in the Class Browser and choose Delete from the popup menu. No files are deleted when deleting a class, but any unsaved changes will be lost. Moreover, if you have more than one class associated with the same file, for instance a package named Electrical containing a class named Resistor, deleting the Resistor class and then saving the package will remove the deleted class Resistor from the file.

When deleting a top-level class, for instance Modelica, the class is unloaded; no files are deleted or affected.

When deleting or unloading a class, all references to the class in other classes will become unresolved. As a consequence, the components of the class will no longer be graphically visible in Model Center. Classes with references to the deleted class will not be modified; however, it will be impossible to simulate them until the unresolved references have been addressed.

Editing the Properties of Classes

The properties of a class, such as its name, description, and so on, can be viewed and edited from the Class Properties dialog box. The Class Properties dialog box is reached by right-clicking the name of a class in the Class Browser and choosing Properties from the popup menu.

The dialog box is divided into four tabs:

  • General. Lets you view and edit general information about the class.
  • Attributes. Lets you add or remove class attributes, such as Final, Protected, and Partial.
  • Version. Shows version information about the library of which the class is a part.
  • Experiment. Shows experiment settings for the class.

These tabs are described in more detail below.

8.gif

The Class Properties dialog box for the HelloWorld model.

  • General: Class. Specifies general information about the class, such as name and description. Each property is described in more detail below.
  • Specialization. Specifies the constraints that are applied to the class. For more information about class specializations, see the section on the Modelica class concept. Note that the class specialization cannot be edited from the dialog box. If you need to change the specialization, it can be done in the Modelica Text View of the class. If the class specialization is enumeration, the dialog box will allow editing of enumerators and their corresponding descriptions. To add a new item to the enumeration, select an empty field in the Enumerator column and start writing. Remove items by selecting a row and clicking the button with a minus sign, and rearrange by clicking on the up and down arrow buttons.
  • Name. Identifies the class. The class can be renamed by editing its name. For information on how references are automatically updated when a class is renamed, see the section on renaming classes.
  • Description. This field contains an optional short description of the class. If present, the class description appears along with the name of the class as a balloon help for the class in the Class Browser.
  • Defined in. The Defined in field states the path to where the class is defined. The path cannot be edited from the dialog box. See the section on copying classes for information on how to copy a class from one location to another.
  • Extends. If the class extends any classes, these classes will be listed here. You may add or remove inheritance relationships by adding or removing classes to the list. If there are multiple inheritances, the classes should be separated by commas.
  • Source File. If the class has an associated source file, the full path and name of the file is shown as the bottom item in the Class section of the dialog box.
  • General: Statistics. Shows statistics about how many classes and components this class contains and how many components that are inherited.
  • Attributes: Properties. Specifies the possible attributes that can be assigned to the class.
  • Final. A class declared as final cannot be modified using redeclarations.
  • Partial. The partial property is used to indicate that a class is incomplete such that it cannot be instantiated on its own. A partial class can only be used as a base class.
  • Protected. A protected class is inaccessible to classes outside of that class. The protected property is only applicable to classes located within another class. By default, protected classes are not visible in the Class Browser.
  • Encapsulated. An encapsulated class represents an independent unit of code. All dependencies outside the class must be explicitly stated using import statements.
  • Version: Library Version. The Library Version section shows version information about the library of which the class is a part. This information, if available, is extracted from the top-level ancestor class. The following information is listed in this section:
  • Version. The version number of the library.
  • Version Date. The date of the first version build.
  • Version Build. The version build number that is used for maintenance updates. The higher the number, the more recent the update.
  • Date Modified. The date and time of the last version build of the library.
  • Revision ID. Revision identifier of the version management system used to manage the library.
  • Experiment: Solver Settings. The solver settings section specifies which solver settings, e.g. start and stop time, to use when simulating the class. Values in gray text are default values or values inherited from base classes. Such values can be overridden by specifying new values. More information on these settings can be found here. The section includes the following properties:
  • Start time [s]. Time point to start the simulation.
  • Stop time [s]. Time point to end the simulation.
  • Solver. Choose what solver to use.
  • Step size [s]. Step size the solver should take.
  • Tolerance. Local tolerance to use in each step.
  • Experiment: Output. The output section shows which output settings to use when simulating the class. Values in gray text are default values or values inherited from base classes. Such values can be overridden by specifying new values.
  • Interval length [s]. Sets the length of each interval in the simulation output.
  • Number of intervals. Sets the number of intervals to use in the simulation output.
  • All solver steps. Use all solver steps as simulation output.
  • Experiment: Options. The options section shows additional options to use when simulating the class.
  • Synchronize with real time. Slow down simulation so that simulation time and real time progress at the same pace.

Saving Classes

To save the class of the active class window, choose File Save.

When a class is saved for the first time, a dialog box is shown, letting you choose a location for the class. If the class is located within an unsaved package, you will be asked to save the complete package instead.

If you are saving a package for the first time, a dialog box is shown, letting you choose whether to save in a directory structure or a single file:

9.gif

Dialog with alternatives for saving a package.

If you choose Save in directory structure, you choose a directory where the class will be saved. In that location, a directory structure for your package will be created, placing each class in a separate file. This choice is recommended if you are developing a library or larger package, or if the package will be worked on by multiple people. Below is an illustration of what this choice results in for one example package.

10.gif

Saving a package in a directory structure.

If you choose Save in single file, the complete package and all the classes in it will be saved in a single file called NameOfTheModel.mo. This choice is recommended for small and simple packages.

Classes can also be saved using the Class Browser. Right-click the name of the class and choose Save from the popup menu.

Controlling Save Locations

Once a package or model has been saved, adding, renaming or otherwise changing classes inside it will automatically choose where each class is saved. A new class added to a parent class saved in a single file will save the new class in the same file. A new class added to a parent class saved in a directory structure will save the new class in a new file just for that class. This default behavior is enough for the vast majority of use cases.

For more advanced control of how classes are saved, a manual split or merge operation can be applied at any level in a package hierarchy. To change how a package is saved, choose File Split/Merge and Save or right-click the class in the Class Browser and choose Split/Merge and Save. This will bring up a dialog, letting you choose between saving in a directory structure or a single file, the same as when first saving a package. Choosing Save in this dialog will apply the operation recursively for all child classes and save each of them.

Similar to renaming classes, this changes the save location of classes, and references to external files may need to be updated. See more details in the section on renaming classes.

Saving Complete Definitions

At times it can be useful to save a complete definition of a class, including all classes used by it, to a single file. This has the benefit that the saved class becomes independent of other files and libraries.

To save a complete definition of the class of the active class window, choose File Save Total Model. Complete definitions of classes can also be saved using the Class Browser. Right-click the name of the class and choose Save Total Model from the popup menu.

Changing the Order of Classes

When classes in the Class Browser are sorted by declaration order, the order in a package can be changed by dragging and dropping classes. If a class is dropped in between other classes, the class is moved to the dropped position. If a class is dropped on top of another class, a copy of the class is created; see the section on copying classes.

Reloading Libraries

It is possible, at any time, to reload the libraries that have been specified to automatically load at the startup of SystemModeler (see the section on startup libraries) by a simple mouse click. This is useful if you have loaded a total model that has replaced one or more class definitions, for instance the Modelica Standard Library, and you wish to restore the original class definitions. Note that reloading is not possible for unsaved classes and the reload option in the popup menu becomes visible only when the target class has been saved.

To reload all startup libraries, choose Reload Libraries from the File menu.

To reload a specific library, right-click on the library in the Class Browser and choose Reload.

Switching Modelica Standard Library Versions

SystemModeler is shipped with both version 3.1 and version 3.2.1 of the Modelica Standard Library (MSL). The Class Browser provides a way to quickly switch MSL versions. Simply right-click on the Modelica package and, in the popup menu, choose Version and then either MSL 3.1 or MSL 3.2.1. SystemModeler will unload the currently loaded version of MSL and load the chosen version.

11.gif

Switching MSL versions.

Customizing the Class Browser

The Class Browser can be customized by editing the settings found in the Options dialog box. The Options dialog box can be reached from the Tools menu. All of the Class Browser settings except the tooltip setting are found in the Model Center Class Browser view. The setting to enable or disable tooltips is located in the Model Center General view. All settings available in the dialog box are automatically saved when closing the dialog box and restored the next time Model Center is started.

12.gif

The Class Browser view of the options dialog box.

The Class Browser section of Options dialog contains a number of choices:

  • Icon size. Specifies the size (width and height) in pixels of the icons in the Class Browser.
  • Show protected classes. Specifies whether or not protected classes should be shown in the Class Browser.
  • Show recently used item list. Specifies whether or not recently used items, and the number of recently used items, should be shown in the Class Browser.
  • Arrange items by. Specifies whether items representing Modelica classes or constants are arranged by name or by their order of declaration in the Class Browser.

Class Browser Tools

At the bottom of the Class Browser there is a small toolbar with three buttons for downloading Modelica libraries from the Wolfram Store and for quick access to various settings of the Class Browser.

The bottom of the Class Browser holds a small toolbar.

The leftmost button, labeled Download Libraries, will open a web browser and take you to the Wolfram Store. From there, you can download free libraries and buy commercial libraries that you might need in your modeling work.

Clicking the second rightmost button lets you choose the sorting order of classes in the Class Browser. Classes can either be sorted by declaration order or by their name (in ascending order). Search results and classes located under Recently Used or at the top hierarchical level are not affected by this option.

Clicking the rightmost button in the toolbar opens the Modelica Libraries section of the Options dialog box. This section allows you to configure your Modelica libraries in the product, e.g. specify which libraries to load at start-up, add or remove custom library paths, and handle library archives.

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